fix: resolve all remaining legacy import issues
- Update models/database/__init__.py to import from module locations - Update models/schema/__init__.py to remove deleted modules - Update models/__init__.py to import Inventory from module - Remove duplicate AdminNotification from models/database/admin.py - Fix monitoring module to import AdminNotification from messaging - Update stats schema imports in admin/vendor API - Update notification schema imports - Add order_item_exception.py schema to orders module - Fix app/api/v1/__init__.py to use storefront instead of shop - Add cms_admin_pages import to main.py - Fix password_reset_token imports - Fix AdminNotification test imports Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,161 @@
|
||||
# Session Note: Module Config & Migrations Infrastructure
|
||||
|
||||
**Date:** 2026-01-28
|
||||
**Focus:** Self-contained module configuration and migrations auto-discovery
|
||||
|
||||
## Summary
|
||||
|
||||
Completed the infrastructure for fully self-contained modules with config and migrations auto-discovery. All modules now have placeholder files ready for the final migration phase.
|
||||
|
||||
## What Was Done
|
||||
|
||||
### 1. Module Config Auto-Discovery
|
||||
|
||||
Created `app/modules/config.py` that auto-discovers module configurations:
|
||||
|
||||
```python
|
||||
from app.modules.config import get_module_config
|
||||
|
||||
marketplace_config = get_module_config("marketplace")
|
||||
```
|
||||
|
||||
Each module now has a `config.py` placeholder:
|
||||
|
||||
```python
|
||||
# app/modules/marketplace/config.py
|
||||
class MarketplaceConfig(BaseSettings):
|
||||
model_config = {"env_prefix": "MARKETPLACE_"}
|
||||
|
||||
config = MarketplaceConfig()
|
||||
```
|
||||
|
||||
### 2. Module Migrations Directories
|
||||
|
||||
Created `migrations/versions/` directories for all 11 self-contained modules:
|
||||
- analytics, billing, cms, customers, dev_tools
|
||||
- inventory, marketplace, messaging, monitoring, orders, payments
|
||||
|
||||
Each with required `__init__.py` files for Alembic discovery.
|
||||
|
||||
### 3. New Architecture Rules
|
||||
|
||||
Added rules MOD-013 to MOD-015:
|
||||
|
||||
| Rule | Description |
|
||||
|------|-------------|
|
||||
| MOD-013 | config.py should export `config` or `config_class` |
|
||||
| MOD-014 | Migrations must follow naming convention `{module}_{seq}_{desc}.py` |
|
||||
| MOD-015 | Migrations directory must have `__init__.py` files |
|
||||
|
||||
### 4. Module Migration Commits
|
||||
|
||||
Committed all pending module migration work:
|
||||
|
||||
| Commit | Description |
|
||||
|--------|-------------|
|
||||
| `2466dfd` | feat: add module config and migrations auto-discovery infrastructure |
|
||||
| `bd2c99a` | feat: complete analytics module self-containment |
|
||||
| `f79e67d` | feat: complete billing module self-containment |
|
||||
| `b74d134` | feat: complete marketplace module self-containment |
|
||||
| `705d336` | feat: add self-contained structure to remaining modules |
|
||||
| `d987274` | feat: complete dev_tools module self-containment |
|
||||
| `37cf74c` | refactor: update registry and main.py for module auto-discovery |
|
||||
| `3ffa337` | refactor: convert legacy models/schemas to re-exports |
|
||||
| `bf871dc` | refactor: convert legacy services/tasks to re-exports |
|
||||
| `fbcf079` | chore: update API routers, validation, and docs |
|
||||
|
||||
### 5. Documentation Updates
|
||||
|
||||
- `docs/architecture/module-system.md` - Added Module Configuration and Module Migrations sections
|
||||
- `docs/development/creating-modules.md` - Added config.py pattern, updated migrations docs
|
||||
|
||||
## Current Module Status
|
||||
|
||||
| Module | definition.py | config.py | migrations/ | routes/api/ | routes/pages/ | locales/ | Status |
|
||||
|--------|--------------|-----------|-------------|-------------|---------------|----------|--------|
|
||||
| analytics | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | **Complete** |
|
||||
| billing | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | Needs pages |
|
||||
| cms | ✅ | ✅ | ✅ | ✅ | ✅ | - | **Complete** |
|
||||
| customers | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | - | Needs routes |
|
||||
| dev_tools | ✅ | ✅ | ✅ | ✅ | - | - | **Complete** |
|
||||
| inventory | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | - | Needs routes |
|
||||
| marketplace | ✅ | ✅ | ✅ | ✅ | ⚠️ | ✅ | Needs pages |
|
||||
| messaging | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | - | Needs routes |
|
||||
| monitoring | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | - | Needs routes |
|
||||
| orders | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | - | Needs routes |
|
||||
| payments | ✅ | ✅ | ✅ | ⚠️ | ⚠️ | - | Needs routes |
|
||||
| core | ✅ | - | - | - | - | - | Minimal |
|
||||
| tenancy | ✅ | - | - | - | - | - | Minimal |
|
||||
|
||||
## Decisions Made
|
||||
|
||||
1. **Config is environment-based**: Each module uses Pydantic Settings with `{MODULE}_` prefix
|
||||
2. **Migrations stay central for now**: Existing migrations remain in `alembic/versions/`, module directories are for future changes
|
||||
3. **Migration reorganization deferred**: Will move existing migrations to modules before production
|
||||
4. **Legacy files become re-exports**: Original files in `models/database/`, `models/schema/`, `app/services/` re-export from modules
|
||||
|
||||
## Tomorrow's Tasks
|
||||
|
||||
### Phase 1: Module Alignment Audit
|
||||
|
||||
Run architecture validator and fix all modules to comply with rules:
|
||||
|
||||
```bash
|
||||
python scripts/validate_architecture.py
|
||||
```
|
||||
|
||||
Check each module for:
|
||||
- [ ] MOD-001: Required directories exist
|
||||
- [ ] MOD-002: Services contain actual code (not re-exports)
|
||||
- [ ] MOD-003: Schemas contain actual code (not re-exports)
|
||||
- [ ] MOD-004: Routes import from module, not legacy
|
||||
- [ ] MOD-005: Templates and static exist for UI modules
|
||||
- [ ] MOD-008: exceptions.py exists
|
||||
- [ ] MOD-010: Routes export `router` variable
|
||||
- [ ] MOD-011: Tasks have `__init__.py`
|
||||
|
||||
### Phase 2: Complete Module Routes Migration
|
||||
|
||||
Move remaining routes to self-contained structure:
|
||||
|
||||
1. **customers** - Move routes from `app/api/v1/*/customers.py`
|
||||
2. **inventory** - Move routes from `app/api/v1/*/inventory.py`
|
||||
3. **messaging** - Move routes from `app/api/v1/*/messages.py`
|
||||
4. **monitoring** - Move routes from `app/api/v1/admin/monitoring.py`
|
||||
5. **orders** - Move routes from `app/api/v1/*/orders.py`
|
||||
6. **payments** - Move routes from `app/api/v1/*/payments.py`
|
||||
|
||||
### Phase 3: Migration Reorganization (Pre-Production)
|
||||
|
||||
Move existing migrations to module-specific directories:
|
||||
|
||||
1. Identify which tables belong to which module
|
||||
2. Create baseline migrations in module directories
|
||||
3. Test migration chain works correctly
|
||||
4. Remove/reorganize central migrations
|
||||
|
||||
### Phase 4: Validation & Testing
|
||||
|
||||
1. Run full architecture validation
|
||||
2. Test all routes are accessible
|
||||
3. Test module enable/disable functionality
|
||||
4. Verify Alembic discovers all migrations
|
||||
|
||||
## Files Changed
|
||||
|
||||
### New Files
|
||||
- `app/modules/config.py` - Config auto-discovery
|
||||
- `app/modules/*/config.py` - Module config placeholders (11 files)
|
||||
- `app/modules/*/migrations/__init__.py` - Migration package markers (11 modules)
|
||||
- `app/modules/*/migrations/versions/__init__.py` - Version package markers (11 modules)
|
||||
- `.architecture-rules/module.yaml` - Module validation rules
|
||||
|
||||
### Modified Files
|
||||
- `docs/architecture/module-system.md` - Added config/migrations sections
|
||||
- `docs/development/creating-modules.md` - Added config pattern, updated migrations
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Module System Architecture](../architecture/module-system.md)
|
||||
- [Creating Modules Guide](../development/creating-modules.md)
|
||||
- [Module Migration Plan](module-migration-plan.md)
|
||||
229
docs/proposals/temp-loyalty
Normal file
229
docs/proposals/temp-loyalty
Normal file
@@ -0,0 +1,229 @@
|
||||
│ Loyalty Platform & Module Implementation Plan │
|
||||
│ │
|
||||
│ Overview │
|
||||
│ │
|
||||
│ Create a Loyalty Module for Wizamart that provides stamp-based and points-based loyalty programs with Google Wallet and Apple Wallet integration. │
|
||||
│ │
|
||||
│ Entity Mapping │
|
||||
│ ┌────────────────────┬────────────────────┬──────────────────────────────────────────────────────────┐ │
|
||||
│ │ Loyalty Concept │ Wizamart Entity │ Notes │ │
|
||||
│ ├────────────────────┼────────────────────┼──────────────────────────────────────────────────────────┤ │
|
||||
│ │ Merchant │ Company │ Existing - legal business entity │ │
|
||||
│ ├────────────────────┼────────────────────┼──────────────────────────────────────────────────────────┤ │
|
||||
│ │ Store │ Vendor │ Existing - brand/location │ │
|
||||
│ ├────────────────────┼────────────────────┼──────────────────────────────────────────────────────────┤ │
|
||||
│ │ Customer │ Customer │ Existing - has vendor_id, total_spent, marketing_consent │ │
|
||||
│ ├────────────────────┼────────────────────┼──────────────────────────────────────────────────────────┤ │
|
||||
│ │ Pass Object │ LoyaltyCard │ NEW - links customer to vendor's program │ │
|
||||
│ ├────────────────────┼────────────────────┼──────────────────────────────────────────────────────────┤ │
|
||||
│ │ Stamp/Points Event │ LoyaltyTransaction │ NEW - records all operations │ │
|
||||
│ ├────────────────────┼────────────────────┼──────────────────────────────────────────────────────────┤ │
|
||||
│ │ Staff PIN │ StaffPin │ NEW - fraud prevention │ │
|
||||
│ └────────────────────┴────────────────────┴──────────────────────────────────────────────────────────┘ │
|
||||
│ Database Models │
|
||||
│ │
|
||||
│ Core Models (5 tables) │
|
||||
│ │
|
||||
│ 1. loyalty_programs - Vendor's program configuration │
|
||||
│ - vendor_id (unique FK) │
|
||||
│ - loyalty_type: stamps | points | hybrid │
|
||||
│ - Stamps config: stamps_target, stamps_reward_description │
|
||||
│ - Points config: points_per_euro, points_rewards (JSON) │
|
||||
│ - Anti-fraud: cooldown_minutes, max_daily_stamps, require_staff_pin │
|
||||
│ - Branding: card_name, card_color, logo_url │
|
||||
│ - Wallet IDs: google_issuer_id, apple_pass_type_id │
|
||||
│ 2. loyalty_cards - Customer's card (PassObject) │
|
||||
│ - customer_id, program_id, vendor_id │
|
||||
│ - card_number (unique), qr_code_data │
|
||||
│ - Stamps: stamp_count, total_stamps_earned, stamps_redeemed │
|
||||
│ - Points: points_balance, total_points_earned, points_redeemed │
|
||||
│ - Wallet: google_object_id, apple_serial_number, apple_auth_token │
|
||||
│ - Timestamps: last_stamp_at, last_points_at │
|
||||
│ 3. loyalty_transactions - All loyalty events │
|
||||
│ - card_id, vendor_id, staff_pin_id │
|
||||
│ - transaction_type: stamp_earned | stamp_redeemed | points_earned | points_redeemed │
|
||||
│ - stamps_delta, points_delta, purchase_amount_cents │
|
||||
│ - Metadata: ip_address, user_agent, notes │
|
||||
│ 4. staff_pins - Fraud prevention │
|
||||
│ - program_id, vendor_id │
|
||||
│ - name, pin_hash (bcrypt) │
|
||||
│ - failed_attempts, locked_until │
|
||||
│ 5. apple_device_registrations - Apple Wallet push │
|
||||
│ - card_id, device_library_identifier, push_token │
|
||||
│ │
|
||||
│ Module Structure │
|
||||
│ │
|
||||
│ app/modules/loyalty/ │
|
||||
│ ├── __init__.py │
|
||||
│ ├── definition.py # ModuleDefinition (requires: customers) │
|
||||
│ ├── config.py # LOYALTY_ env vars │
|
||||
│ ├── exceptions.py │
|
||||
│ ├── models/ │
|
||||
│ │ ├── loyalty_program.py │
|
||||
│ │ ├── loyalty_card.py │
|
||||
│ │ ├── loyalty_transaction.py │
|
||||
│ │ ├── staff_pin.py │
|
||||
│ │ └── apple_device.py │
|
||||
│ ├── schemas/ │
|
||||
│ │ ├── program.py │
|
||||
│ │ ├── card.py │
|
||||
│ │ ├── stamp.py │
|
||||
│ │ ├── points.py │
|
||||
│ │ └── pin.py │
|
||||
│ ├── services/ │
|
||||
│ │ ├── program_service.py # Program CRUD │
|
||||
│ │ ├── card_service.py # Card enrollment, lookup │
|
||||
│ │ ├── stamp_service.py # Stamp logic + anti-fraud │
|
||||
│ │ ├── points_service.py # Points logic │
|
||||
│ │ ├── pin_service.py # PIN validation │
|
||||
│ │ ├── wallet_service.py # Unified wallet abstraction │
|
||||
│ │ ├── google_wallet_service.py │
|
||||
│ │ └── apple_wallet_service.py │
|
||||
│ ├── routes/ │
|
||||
│ │ ├── api/ │
|
||||
│ │ │ ├── admin.py # Platform admin │
|
||||
│ │ │ ├── vendor.py # Vendor dashboard │
|
||||
│ │ │ └── public.py # Enrollment, Apple web service │
|
||||
│ │ └── pages/ │
|
||||
│ ├── tasks/ │
|
||||
│ │ ├── point_expiration.py │
|
||||
│ │ └── wallet_sync.py │
|
||||
│ ├── migrations/versions/ │
|
||||
│ ├── locales/ │
|
||||
│ └── templates/ │
|
||||
│ │
|
||||
│ Key API Endpoints │
|
||||
│ │
|
||||
│ Public (Customer) │
|
||||
│ │
|
||||
│ - POST /api/v1/loyalty/enroll/{vendor_code} - Enroll in program │
|
||||
│ - GET /api/v1/loyalty/passes/apple/{serial}.pkpass - Download Apple pass │
|
||||
│ - Apple Web Service endpoints for device registration/updates │
|
||||
│ │
|
||||
│ Vendor (Staff) │
|
||||
│ │
|
||||
│ - POST /api/v1/vendor/loyalty/stamp - Add stamp (requires PIN) │
|
||||
│ - POST /api/v1/vendor/loyalty/points - Add points from purchase │
|
||||
│ - POST /api/v1/vendor/loyalty/*/redeem - Redeem for reward │
|
||||
│ - GET /api/v1/vendor/loyalty/cards - List customer cards │
|
||||
│ - GET /api/v1/vendor/loyalty/pins - Manage staff PINs │
|
||||
│ - GET /api/v1/vendor/loyalty/stats - Dashboard analytics │
|
||||
│ │
|
||||
│ Admin │
|
||||
│ │
|
||||
│ - GET /api/v1/admin/loyalty/programs - List all programs │
|
||||
│ - GET /api/v1/admin/loyalty/stats - Platform-wide stats │
|
||||
│ │
|
||||
│ Anti-Fraud System │
|
||||
│ │
|
||||
│ 1. Staff PIN - Required for all stamp/points operations │
|
||||
│ 2. Cooldown - Configurable minutes between stamps (default: 15) │
|
||||
│ 3. Daily Limit - Max stamps per card per day (default: 5) │
|
||||
│ 4. PIN Lockout - Lock after 5 failed attempts for 30 minutes │
|
||||
│ 5. Audit Trail - All transactions logged with IP/user agent │
|
||||
│ │
|
||||
│ Wallet Integration │
|
||||
│ │
|
||||
│ Google Wallet │
|
||||
│ │
|
||||
│ - Create LoyaltyClass when program created │
|
||||
│ - Create LoyaltyObject when customer enrolls │
|
||||
│ - PATCH object on stamp/points change │
|
||||
│ - Generate JWT-based "Add to Wallet" URL │
|
||||
│ │
|
||||
│ Apple Wallet │
|
||||
│ │
|
||||
│ - Generate .pkpass file (pass.json + images + signature) │
|
||||
│ - Implement Apple Web Service for device registration │
|
||||
│ - Send push notification on updates → device fetches new pass │
|
||||
│ │
|
||||
│ Implementation Phases │
|
||||
│ │
|
||||
│ Phase 1: MVP (Target) │
|
||||
│ │
|
||||
│ 1. Core Infrastructure │
|
||||
│ - Module structure, definition, exceptions │
|
||||
│ - Database models and migrations │
|
||||
│ - Program service (CRUD) │
|
||||
│ - Card service (enrollment, lookup) │
|
||||
│ 2. Stamp Loyalty │
|
||||
│ - Staff PIN service with lockout │
|
||||
│ - Stamp service with anti-fraud │
|
||||
│ - Transaction logging │
|
||||
│ - Vendor API routes │
|
||||
│ 3. Points Loyalty │
|
||||
│ - Points service │
|
||||
│ - Purchase-to-points calculation │
|
||||
│ - Redemption flow │
|
||||
│ 4. Wallet Integration │
|
||||
│ - Google Wallet service │
|
||||
│ - Apple .pkpass generation │
|
||||
│ - Apple Web Service endpoints │
|
||||
│ 5. Dashboard │
|
||||
│ - Vendor stats endpoint │
|
||||
│ - Transaction history │
|
||||
│ - QR code generation │
|
||||
│ │
|
||||
│ Phase 2: Future Enhancements │
|
||||
│ │
|
||||
│ - Rewards catalog with configurable tiers │
|
||||
│ - Customer tiers (Bronze/Silver/Gold) │
|
||||
│ - Referral program │
|
||||
│ - Gamification (spin wheel, scratch cards) │
|
||||
│ - POS integration │
|
||||
│ │
|
||||
│ Files to Create │
|
||||
│ │
|
||||
│ app/modules/loyalty/ │
|
||||
│ ├── __init__.py │
|
||||
│ ├── definition.py │
|
||||
│ ├── config.py │
|
||||
│ ├── exceptions.py │
|
||||
│ ├── models/__init__.py │
|
||||
│ ├── models/loyalty_program.py │
|
||||
│ ├── models/loyalty_card.py │
|
||||
│ ├── models/loyalty_transaction.py │
|
||||
│ ├── models/staff_pin.py │
|
||||
│ ├── models/apple_device.py │
|
||||
│ ├── schemas/__init__.py │
|
||||
│ ├── schemas/program.py │
|
||||
│ ├── schemas/card.py │
|
||||
│ ├── schemas/stamp.py │
|
||||
│ ├── schemas/points.py │
|
||||
│ ├── schemas/pin.py │
|
||||
│ ├── services/__init__.py │
|
||||
│ ├── services/program_service.py │
|
||||
│ ├── services/card_service.py │
|
||||
│ ├── services/stamp_service.py │
|
||||
│ ├── services/points_service.py │
|
||||
│ ├── services/pin_service.py │
|
||||
│ ├── services/wallet_service.py │
|
||||
│ ├── services/google_wallet_service.py │
|
||||
│ ├── services/apple_wallet_service.py │
|
||||
│ ├── routes/__init__.py │
|
||||
│ ├── routes/api/__init__.py │
|
||||
│ ├── routes/api/admin.py │
|
||||
│ ├── routes/api/vendor.py │
|
||||
│ ├── routes/api/public.py │
|
||||
│ ├── routes/pages/__init__.py │
|
||||
│ ├── tasks/__init__.py │
|
||||
│ ├── tasks/point_expiration.py │
|
||||
│ ├── migrations/__init__.py │
|
||||
│ ├── migrations/versions/__init__.py │
|
||||
│ └── locales/{en,fr,de,lu}.json │
|
||||
│ │
|
||||
│ Reference Patterns │
|
||||
│ │
|
||||
│ - Module definition: app/modules/billing/definition.py │
|
||||
│ - Models: app/modules/billing/models/subscription.py │
|
||||
│ - Services: app/modules/billing/services/subscription_service.py │
|
||||
│ - Customer integration: models/database/customer.py │
|
||||
│ │
|
||||
│ Verification │
|
||||
│ │
|
||||
│ 1. Run architecture validator: python scripts/validate_architecture.py │
|
||||
│ 2. Run migrations: alembic upgrade head │
|
||||
│ 3. Test enrollment flow via API │
|
||||
│ 4. Test stamp/points operations with PIN │
|
||||
│ 5. Verify wallet pass generation │
|
||||
│ 6. Check anti-fraud (cooldown, limits, lockout)
|
||||
Reference in New Issue
Block a user