Init
This commit is contained in:
Bastian Masanek
147
tasks/09-erp-integration.md
Normal file
147
tasks/09-erp-integration.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Phase 9: ERP Integration (NAV Product Sync)
|
||||
|
||||
**Status:** ⏳ Todo
|
||||
**Progress:** 0/10 tasks (0%)
|
||||
**Started:** -
|
||||
**Completed:** -
|
||||
**Assigned to:** -
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Implement NAV ERP product sync API endpoint: receive product data pushed from NAV ERP, validate, and upsert into local database.
|
||||
|
||||
**Goal:** NAV ERP can push products to our API, keeping product catalog up-to-date.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- ✅ Phase 2: Database (products table needed)
|
||||
- ⚠️ **Required:** API key for NAV ERP authentication
|
||||
|
||||
---
|
||||
|
||||
## Tasks
|
||||
|
||||
### Schema & Validation
|
||||
|
||||
- [ ] Create NAV ERP product schema (Zod)
|
||||
- File: `server/utils/schemas/navProduct.ts`
|
||||
- Fields: navProductId, name, description, price, stockQuantity, category, active
|
||||
- Validation rules: required fields, price > 0, stock >= 0
|
||||
- Export: `navProductSchema`, `NavProductData` type
|
||||
|
||||
### API Endpoint
|
||||
|
||||
- [ ] Create /api/erp/products.post.ts endpoint
|
||||
- Body: { products: NavProductData[] } (array of products)
|
||||
- Validate API key from header: `Authorization: Bearer <API_KEY>`
|
||||
- Validate product data with Zod
|
||||
- Upsert products in DB (insert if new, update if exists)
|
||||
- Return: { success: true, upserted: count, errors: [] }
|
||||
|
||||
### Authentication
|
||||
|
||||
- [ ] Implement API key authentication
|
||||
- Middleware: `server/middleware/erpAuth.ts`
|
||||
- Check Authorization header
|
||||
- Validate API key against NAV_ERP_API_KEY env var
|
||||
- Return 401 if invalid/missing
|
||||
- Only apply to /api/erp/\* routes
|
||||
|
||||
### Business Logic
|
||||
|
||||
- [ ] Implement product validation
|
||||
- Validate required fields
|
||||
- Validate data types and formats
|
||||
- Validate price is positive
|
||||
- Validate stock quantity is non-negative
|
||||
- Return detailed errors for invalid products
|
||||
|
||||
- [ ] Implement product upsert logic
|
||||
- Check if product exists by navProductId (unique key)
|
||||
- If exists: Update name, description, price, stock, category, active, updated_at
|
||||
- If not exists: Insert new product with all fields
|
||||
- Use Drizzle's `.onConflictDoUpdate()` or manual check
|
||||
- Return count of upserted products
|
||||
|
||||
### Error Handling
|
||||
|
||||
- [ ] Add error handling & logging
|
||||
- Log all incoming requests (timestamp, product count)
|
||||
- Log validation errors with details
|
||||
- Log DB errors
|
||||
- Return structured errors to NAV ERP
|
||||
- Example: `{ success: false, errors: [{ product: '...', message: '...' }] }`
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Test product sync (mock data)
|
||||
- Create sample NAV product data (JSON)
|
||||
- POST to /api/erp/products with valid API key
|
||||
- Verify products are created in DB
|
||||
- POST again with updated data
|
||||
- Verify products are updated in DB
|
||||
- Test with invalid data → verify validation errors
|
||||
|
||||
- [ ] Test API key auth
|
||||
- Test without Authorization header → expect 401
|
||||
- Test with invalid API key → expect 401
|
||||
- Test with valid API key → expect 200
|
||||
|
||||
- [ ] Add rate limiting
|
||||
- Limit NAV ERP endpoint to prevent abuse
|
||||
- Example: 100 requests / hour per API key
|
||||
- Use `server/middleware/rate-limit.ts` (extend from Phase 3)
|
||||
- Return 429 if limit exceeded
|
||||
|
||||
- [ ] Document ERP integration
|
||||
- Document API endpoint spec (request/response format)
|
||||
- Document authentication method (API key in header)
|
||||
- Document product data schema
|
||||
- Document error codes and messages
|
||||
- Document rate limits
|
||||
- Create example curl commands for NAV team
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] NAV product schema is defined with Zod
|
||||
- [x] /api/erp/products endpoint is implemented
|
||||
- [x] API key authentication works correctly
|
||||
- [x] Product validation works (Zod schema)
|
||||
- [x] Product upsert logic works (insert new, update existing)
|
||||
- [x] Error handling returns structured errors
|
||||
- [x] Logging captures all requests and errors
|
||||
- [x] Can sync products successfully with mock data
|
||||
- [x] API key auth prevents unauthorized access
|
||||
- [x] Rate limiting protects endpoint from abuse
|
||||
- [x] ERP integration is documented for NAV team
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Push Model:** NAV ERP pushes to us (we don't pull)
|
||||
- **Batch Sync:** NAV can send multiple products in one request
|
||||
- **Idempotent:** Repeated syncs with same data should be safe (upsert)
|
||||
- **API Key Storage:** Store NAV_ERP_API_KEY in .env (dev/prod)
|
||||
- **NAV Contact:** Coordinate with NAV team for API key and sync schedule
|
||||
|
||||
---
|
||||
|
||||
## Blockers
|
||||
|
||||
- ⚠️ **API Key:** Need to generate/agree on API key with NAV team
|
||||
- ⚠️ **NAV Schema:** Need exact product schema from NAV team (may differ from assumption)
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [docs/PRD.md: F-011](../docs/PRD.md#f-011-nav-erp-push-endpunkt)
|
||||
- [docs/ARCHITECTURE.md: NAV ERP Integration](../docs/ARCHITECTURE.md#33-nav-erp-product-sync)
|
||||
- [CLAUDE.md: Important Constraints](../CLAUDE.md#important-constraints)
|
||||
Reference in New Issue
Block a user