PIM Service Quick Start Guide

Installation (5 minutes)

1. Navigate to project directory

cd /opt/claude-workspace/L1-SERVICE/pirotehnika/pim

2. Create virtual environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Set up environment variables

Create .env file with your database credentials:

DATABASE_HOST=91.218.142.168
DATABASE_PORT=5432
DATABASE_USER=noco
DATABASE_PASSWORD=your_password
DATABASE_NAME=nocodb_data
DATABASE_SCHEMA=pt7k98pv0fwi1el

5. Run the service

python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Verify Installation

Once the service is running, check:

# Health check
curl http://localhost:8000/health

# API documentation
open http://localhost:8000/api/v1/docs

Quick API Tests

Get a product

curl -X GET "http://localhost:8000/api/v1/products/НФ-00001234"

List products

curl -X GET "http://localhost:8000/api/v1/products/?limit=10"

Calculate price

curl -X POST "http://localhost:8000/api/v1/pricing/calculate" \
  -H "Content-Type: application/json" \
  -d '{
    "article": "НФ-00001234",
    "markup_percent": 30
  }'

Run all tests

bash CURL_TESTS.sh

Available Documentation

• README.md - Project overview and features
• API_DOCUMENTATION.md - Complete API reference
• USAGE_EXAMPLES.md - Code examples and integration patterns
• DEPLOYMENT.md - Production deployment guide
• IMPLEMENTATION_SUMMARY.md - Technical implementation details
• CURL_TESTS.sh - Executable test suite

Access Points

Local Development

• API Base URL: http://localhost:8000/api/v1
• Swagger UI Docs: http://localhost:8000/api/v1/docs
• ReDoc Documentation: http://localhost:8000/api/v1/redoc
• Health Check: http://localhost:8000/health

Project Structure

pim/
├── api/              # FastAPI endpoints
│   ├── products.py   # Product endpoints
│   └── pricing.py    # Pricing endpoints
├── core/             # Business logic
│   ├── products.py   # Product service
│   └── pricing.py    # Pricing service
├── models/           # Database ORM models
│   ├── product.py    # Product models
│   └── pricing.py    # Pricing models
├── schemas/          # Pydantic validation
│   ├── product.py    # Product schemas
│   └── pricing.py    # Pricing schemas
├── tests/            # Test cases
│   └── test_api.py   # API tests
├── config.py         # Configuration
├── database.py       # Database setup
└── main.py           # FastAPI app

Key API Endpoints

Products

• GET /products/{article} - Get product
• GET /products/ - List products
• POST /products/search - Search
• GET /products/brand/{brand} - By brand
• GET /products/category/{category} - By category

Pricing

• POST /pricing/calculate - Calculate price
• POST /pricing/calculate-bulk - Bulk calculate
• GET /pricing/rules - List cost rules
• POST /pricing/rules - Create rule
• PUT /pricing/rules/{brand} - Update rule
• DELETE /pricing/rules/{brand} - Delete rule

Common Tasks

Search for products

curl -X POST "http://localhost:8000/api/v1/products/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "фейерверк", "limit": 10}'

Get products by brand

curl "http://localhost:8000/api/v1/products/?brand=JF-Pyro&limit=20"

Create a cost rule

curl -X POST "http://localhost:8000/api/v1/pricing/rules" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "MyBrand",
    "discount_percent": 30,
    "description": "My brand discount"
  }'

Calculate prices for multiple products

curl -X POST "http://localhost:8000/api/v1/pricing/calculate-bulk" \
  -H "Content-Type: application/json" \
  -d '{
    "articles": ["НФ-00001234", "НФ-00001235", "НФ-00001236"],
    "markup_percent": 30
  }'

Troubleshooting

Service won't start

1. Check Python version: python --version (should be 3.10+)
2. Check virtual environment is activated
3. Verify dependencies: pip list
4. Check port 8000 is available

Database connection error

1. Verify DATABASE_HOST and DATABASE_PORT in .env
2. Test connection: psql -h HOST -U USER -d DATABASE
3. Check credentials are correct

API returns 404

1. Check you're using the correct article number
2. Verify product exists in database
3. Check the API base URL includes /api/v1

Next Steps

1. Read Documentation: Start with README.md
2. Explore API: Open http://localhost:8000/api/v1/docs
3. Run Tests: Execute bash CURL_TESTS.sh
4. Understand Pricing: See pricing calculation examples in USAGE_EXAMPLES.md
5. Deploy: Follow DEPLOYMENT.md for production setup

Support

For detailed documentation:
- API Reference: API_DOCUMENTATION.md
- Usage Guide: USAGE_EXAMPLES.md
- Deployment: DEPLOYMENT.md
- Implementation: IMPLEMENTATION_SUMMARY.md

Environment Variables

# Database Connection
DATABASE_HOST=91.218.142.168
DATABASE_PORT=5432
DATABASE_USER=noco
DATABASE_PASSWORD=password
DATABASE_NAME=nocodb_data
DATABASE_SCHEMA=pt7k98pv0fwi1el

# API Configuration
API_V1_PREFIX=/api/v1
API_TITLE=PIM Service API
API_VERSION=1.0.0
LOG_LEVEL=INFO

Files Summary

Performance Tips

1. Use pagination when listing large datasets
2. Search on indexed fields (article, brand, category)
3. Cache cost rules (they change infrequently)
4. Use bulk endpoints for multiple operations
5. Monitor query performance with echo=True in config

Security Notes

• Always use HTTPS in production
• Store credentials in .env (never in code)
• Implement authentication before production deployment
• Add rate limiting for public APIs
• Validate all user inputs

Enjoy using PIM Service!