refactor: migrate templates and static files to self-contained modules
Templates Migration: - Migrate admin templates to modules (tenancy, billing, monitoring, marketplace, etc.) - Migrate vendor templates to modules (tenancy, billing, orders, messaging, etc.) - Migrate storefront templates to modules (catalog, customers, orders, cart, checkout, cms) - Migrate public templates to modules (billing, marketplace, cms) - Keep shared templates in app/templates/ (base.html, errors/, partials/, macros/) - Migrate letzshop partials to marketplace module Static Files Migration: - Migrate admin JS to modules: tenancy (23 files), core (5 files), monitoring (1 file) - Migrate vendor JS to modules: tenancy (4 files), core (2 files) - Migrate shared JS: vendor-selector.js to core, media-picker.js to cms - Migrate storefront JS: storefront-layout.js to core - Keep framework JS in static/ (api-client, utils, money, icons, log-config, lib/) - Update all template references to use module_static paths Naming Consistency: - Rename static/platform/ to static/public/ - Rename app/templates/platform/ to app/templates/public/ - Update all extends and static references Documentation: - Update module-system.md with shared templates documentation - Update frontend-structure.md with new module JS organization Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -50,8 +50,8 @@ app/
|
||||
**Purpose:** Public-facing platform pages (marketing, info pages)
|
||||
|
||||
**Location:**
|
||||
- Templates: `app/templates/platform/`
|
||||
- Static: `static/platform/`
|
||||
- Templates: `app/templates/public/`
|
||||
- Static: `static/public/`
|
||||
|
||||
**Pages:**
|
||||
- Homepage (multiple layouts: default, minimal, modern)
|
||||
@@ -163,7 +163,7 @@ app/
|
||||
|
||||
Each frontend has its own static directory for frontend-specific assets. Use the appropriate directory based on which frontend the asset belongs to.
|
||||
|
||||
### Platform Static Assets (`static/platform/`)
|
||||
### Platform Static Assets (`static/public/`)
|
||||
|
||||
**JavaScript Files:**
|
||||
```html
|
||||
@@ -270,7 +270,7 @@ Each frontend has its own static directory for frontend-specific assets. Use the
|
||||
Icon system (used by all 4 frontends) → static/shared/js/icons.js
|
||||
Admin dashboard chart → static/admin/js/charts.js
|
||||
Vendor product form → static/vendor/js/product-form.js
|
||||
Platform hero image → static/platform/img/hero.jpg
|
||||
Platform hero image → static/public/img/hero.jpg
|
||||
Storefront product carousel → static/storefront/js/carousel.js
|
||||
```
|
||||
|
||||
@@ -338,31 +338,18 @@ app.mount("/static/modules/orders", StaticFiles(directory="app/modules/orders/st
|
||||
| **marketplace** | marketplace*.js, letzshop*.js | letzshop.js, marketplace.js, onboarding.js | - |
|
||||
| **monitoring** | monitoring.js, background-tasks.js, imports.js, logs.js | - | - |
|
||||
| **dev_tools** | testing-*.js, code-quality-*.js, icons-page.js, components.js | - | - |
|
||||
| **cms** | content-pages.js, content-page-edit.js | content-pages.js, content-page-edit.js, media.js | - |
|
||||
| **cms** | content-pages.js, content-page-edit.js | content-pages.js, content-page-edit.js, media.js | media-picker.js |
|
||||
| **analytics** | - | analytics.js | - |
|
||||
| **tenancy** | companies*.js, vendors*.js, platforms*.js, admin-users*.js, users*.js | login.js, team.js, profile.js, settings.js | - |
|
||||
| **core** | dashboard.js, settings.js, my-menu-config.js, login.js, init-alpine.js | dashboard.js, init-alpine.js | vendor-selector.js |
|
||||
|
||||
### Platform Static Files (Not in Modules)
|
||||
|
||||
These files remain in `static/` because they're platform-level, not module-specific:
|
||||
Only framework-level files remain in `static/`:
|
||||
|
||||
**Admin Core (`static/admin/js/`):**
|
||||
- `init-alpine.js` - Admin layout initialization
|
||||
- `dashboard.js` - Main admin dashboard
|
||||
- `login.js` - Admin authentication
|
||||
- `platforms.js`, `platform-*.js` - Platform management (6 files)
|
||||
- `vendors.js`, `vendor-*.js` - Vendor management at platform level (6 files)
|
||||
- `companies.js`, `company-*.js` - Company management (3 files)
|
||||
- `admin-users.js`, `admin-user-*.js` - Admin user management (3 files)
|
||||
- `users.js`, `user-*.js` - Platform user management (4 files)
|
||||
- `settings.js` - Platform settings
|
||||
|
||||
**Vendor Core (`static/vendor/js/`):**
|
||||
- `init-alpine.js` - Vendor layout initialization
|
||||
- `dashboard.js` - Vendor main dashboard
|
||||
- `login.js` - Vendor authentication
|
||||
- `profile.js` - Vendor account settings
|
||||
- `settings.js` - Vendor configuration
|
||||
- `team.js` - Team member management
|
||||
**Admin Framework (`static/admin/js/`):**
|
||||
- `module-config.js` - Module system configuration UI
|
||||
- `module-info.js` - Module information display
|
||||
|
||||
**Shared Utilities (`static/shared/js/`):**
|
||||
- `api-client.js` - Core HTTP client with auth
|
||||
@@ -370,8 +357,7 @@ These files remain in `static/` because they're platform-level, not module-speci
|
||||
- `money.js` - Money/currency handling
|
||||
- `icons.js` - Heroicons SVG definitions
|
||||
- `log-config.js` - Centralized logging
|
||||
- `vendor-selector.js` - Vendor autocomplete component
|
||||
- `media-picker.js` - Media picker component
|
||||
- `lib/` - Third-party libraries (Alpine.js, Chart.js, etc.)
|
||||
|
||||
### User Type Distinction
|
||||
|
||||
@@ -379,13 +365,13 @@ The codebase distinguishes between three types of users:
|
||||
|
||||
| Type | Management JS | Location | Description |
|
||||
|------|---------------|----------|-------------|
|
||||
| **Admin Users** | admin-users.js | `static/admin/js/` | Platform administrators (super admins, platform admins) |
|
||||
| **Platform Users** | users.js | `static/admin/js/` | Vendor/company users who log into the platform |
|
||||
| **Admin Users** | admin-users.js | `app/modules/tenancy/static/admin/js/` | Platform administrators (super admins, platform admins) |
|
||||
| **Platform Users** | users.js | `app/modules/tenancy/static/admin/js/` | Vendor/company users who log into the platform |
|
||||
| **Shop Customers** | customers.js | `app/modules/customers/static/` | End customers who buy from vendors |
|
||||
|
||||
This distinction is important:
|
||||
- `admin-users.js` and `users.js` manage **internal platform users** → Stay in `static/admin/js/`
|
||||
- `customers.js` manages **storefront customers** → Lives in the customers module
|
||||
All user management JS is now in self-contained modules:
|
||||
- `admin-users.js` and `users.js` are in the **tenancy** module (manages platform users)
|
||||
- `customers.js` is in the **customers** module (manages storefront customers)
|
||||
|
||||
---
|
||||
|
||||
@@ -466,7 +452,7 @@ All frontends communicate with backend via APIs:
|
||||
- `/api/v1/admin/*` - Admin APIs
|
||||
- `/api/v1/vendor/*` - Vendor APIs
|
||||
- `/api/v1/storefront/*` - Storefront APIs
|
||||
- `/api/v1/platform/*` - Platform APIs
|
||||
- `/api/v1/public/*` - Platform APIs
|
||||
|
||||
**Benefits:**
|
||||
- Clear backend contracts
|
||||
|
||||
@@ -509,11 +509,11 @@ Routes define API and page endpoints. They are auto-discovered from module direc
|
||||
|
||||
| Type | Location | Discovery | Router Name |
|
||||
|------|----------|-----------|-------------|
|
||||
| Vendor API | `routes/api/vendor.py` | `app/modules/routes.py` | `vendor_router` |
|
||||
| Admin API | `routes/api/admin.py` | `app/modules/routes.py` | `admin_router` |
|
||||
| Shop API | `routes/api/shop.py` | `app/modules/routes.py` | `shop_router` |
|
||||
| Vendor Pages | `routes/pages/vendor.py` | `app/modules/routes.py` | `vendor_router` |
|
||||
| Vendor API | `routes/api/vendor.py` | `app/modules/routes.py` | `vendor_router` |
|
||||
| Storefront API | `routes/api/storefront.py` | `app/modules/routes.py` | `router` |
|
||||
| Admin Pages | `routes/pages/admin.py` | `app/modules/routes.py` | `admin_router` |
|
||||
| Vendor Pages | `routes/pages/vendor.py` | `app/modules/routes.py` | `vendor_router` |
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
@@ -521,9 +521,10 @@ app/modules/{module}/routes/
|
||||
├── __init__.py
|
||||
├── api/
|
||||
│ ├── __init__.py
|
||||
│ ├── vendor.py # Must export vendor_router
|
||||
│ ├── admin.py # Must export admin_router
|
||||
│ └── vendor_{feature}.py # Sub-routers aggregated in vendor.py
|
||||
│ ├── vendor.py # Must export vendor_router
|
||||
│ ├── storefront.py # Must export router (public storefront)
|
||||
│ └── admin_{feature}.py # Sub-routers aggregated in admin.py
|
||||
└── pages/
|
||||
├── __init__.py
|
||||
└── vendor.py # Must export vendor_router
|
||||
@@ -754,22 +755,30 @@ class OrderAlreadyFulfilledError(OrderException):
|
||||
|
||||
### Templates
|
||||
|
||||
Jinja2 templates are auto-discovered from module `templates/` directories.
|
||||
Jinja2 templates are auto-discovered from module `templates/` directories. The template loader searches `app/templates/` first (for shared templates), then each module's `templates/` directory.
|
||||
|
||||
| Location | URL Pattern | Discovery |
|
||||
|----------|-------------|-----------|
|
||||
| `templates/{module}/vendor/*.html` | `/vendor/{vendor}/...` | Jinja2 loader |
|
||||
| `templates/{module}/admin/*.html` | `/admin/...` | Jinja2 loader |
|
||||
| `templates/{module}/storefront/*.html` | `/storefront/...` | Jinja2 loader |
|
||||
| `templates/{module}/public/*.html` | `/...` (platform pages) | Jinja2 loader |
|
||||
|
||||
**Structure:**
|
||||
**Module Template Structure:**
|
||||
```
|
||||
app/modules/{module}/templates/
|
||||
└── {module}/
|
||||
├── admin/
|
||||
│ ├── list.html
|
||||
│ └── partials/ # Module-specific partials
|
||||
│ └── my-partial.html
|
||||
├── vendor/
|
||||
│ ├── index.html
|
||||
│ └── detail.html
|
||||
└── admin/
|
||||
└── list.html
|
||||
├── storefront/ # Customer-facing shop pages
|
||||
│ └── products.html
|
||||
└── public/ # Platform marketing pages
|
||||
└── pricing.html
|
||||
```
|
||||
|
||||
**Template Reference:**
|
||||
@@ -782,6 +791,27 @@ return templates.TemplateResponse(
|
||||
)
|
||||
```
|
||||
|
||||
**Shared Templates (in `app/templates/`):**
|
||||
|
||||
Some templates remain in `app/templates/` because they are used across all modules:
|
||||
|
||||
| Directory | Contents | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| `admin/base.html` | Admin layout | Parent template all admin pages extend |
|
||||
| `vendor/base.html` | Vendor layout | Parent template all vendor pages extend |
|
||||
| `storefront/base.html` | Shop layout | Parent template all storefront pages extend |
|
||||
| `platform/base.html` | Public layout | Parent template all public pages extend |
|
||||
| `admin/errors/` | Error pages | HTTP error templates (404, 500, etc.) |
|
||||
| `vendor/errors/` | Error pages | HTTP error templates for vendor |
|
||||
| `storefront/errors/` | Error pages | HTTP error templates for storefront |
|
||||
| `admin/partials/` | Shared partials | Header, sidebar used across admin |
|
||||
| `vendor/partials/` | Shared partials | Header, sidebar used across vendor |
|
||||
| `shared/macros/` | Jinja2 macros | Reusable UI components (buttons, forms, tables) |
|
||||
| `shared/includes/` | Includes | Common HTML snippets |
|
||||
| `invoices/` | PDF templates | Invoice PDF generation |
|
||||
|
||||
These shared templates provide the "framework" that module templates build upon. Module templates extend base layouts and import shared macros.
|
||||
|
||||
---
|
||||
|
||||
### Static Files
|
||||
|
||||
@@ -207,7 +207,7 @@ COPY . .
|
||||
RUN tailwindcss -i ./static/admin/css/tailwind.css -o ./static/admin/css/tailwind.output.css --minify \
|
||||
&& tailwindcss -i ./static/vendor/css/tailwind.css -o ./static/vendor/css/tailwind.output.css --minify \
|
||||
&& tailwindcss -i ./static/shop/css/tailwind.css -o ./static/shop/css/tailwind.output.css --minify \
|
||||
&& tailwindcss -i ./static/platform/css/tailwind.css -o ./static/platform/css/tailwind.output.css --minify
|
||||
&& tailwindcss -i ./static/public/css/tailwind.css -o ./static/public/css/tailwind.output.css --minify
|
||||
|
||||
# Create non-root user
|
||||
RUN useradd -m -u 1000 wizamart && chown -R wizamart:wizamart /app
|
||||
|
||||
@@ -78,56 +78,99 @@ The Wizamart platform has been migrating from a monolithic structure with code i
|
||||
- Created `app/modules/billing/routes/api/vendor_addons.py`
|
||||
- Deleted legacy billing routes from `app/api/v1/vendor/`
|
||||
|
||||
### Phase 6: Remaining Vendor Routes (2026-01-31)
|
||||
### Phase 6: Vendor Routes Migration (2026-01-31)
|
||||
|
||||
#### Current Changes - Migrate analytics, usage, onboarding
|
||||
- **Deleted**: `app/api/v1/vendor/analytics.py` (duplicate - analytics module already auto-discovered)
|
||||
- **Created**: `app/modules/billing/routes/api/vendor_usage.py` (usage limits/upgrades)
|
||||
- **Created**: `app/modules/marketplace/routes/api/vendor_onboarding.py` (onboarding wizard)
|
||||
- **Deleted**: `app/api/v1/vendor/usage.py` (migrated to billing)
|
||||
- **Deleted**: `app/api/v1/vendor/onboarding.py` (migrated to marketplace)
|
||||
- Migrated remaining vendor routes to respective modules
|
||||
|
||||
### Phase 7: Admin Routes Migration (2026-01-31)
|
||||
|
||||
Major admin route migration to modules.
|
||||
|
||||
### Phase 8: Storefront Routes Auto-Discovery (2026-01-31)
|
||||
|
||||
- Updated `app/modules/routes.py` to discover `storefront.py` files
|
||||
- Added `get_storefront_api_routes()` function
|
||||
- Updated `app/api/v1/storefront/__init__.py` to use auto-discovery
|
||||
- 37 storefront routes now auto-discovered from 7 modules:
|
||||
- cart, catalog, checkout, cms, customers, messaging, orders
|
||||
|
||||
**Admin routes migrated to modules:**
|
||||
|
||||
**Tenancy Module** (auth, users, companies, platforms, vendors):
|
||||
- `admin_auth.py`, `admin_users.py`, `admin_admin_users.py`
|
||||
- `admin_companies.py`, `admin_platforms.py`, `admin_vendors.py`
|
||||
- `admin_vendor_domains.py`
|
||||
|
||||
**Core Module** (dashboard, settings):
|
||||
- `admin_dashboard.py`, `admin_settings.py`
|
||||
|
||||
**Messaging Module** (messages, notifications, email templates):
|
||||
- `admin_messages.py`, `admin_notifications.py`, `admin_email_templates.py`
|
||||
|
||||
**Monitoring Module** (logs, tasks, tests, code quality, audit, platform health):
|
||||
- `admin_logs.py`, `admin_tasks.py`, `admin_tests.py`
|
||||
- `admin_code_quality.py`, `admin_audit.py`, `admin_platform_health.py`
|
||||
|
||||
**CMS Module** (content pages, images, media, vendor themes):
|
||||
- `admin_content_pages.py`, `admin_images.py`
|
||||
- `admin_media.py`, `admin_vendor_themes.py`
|
||||
|
||||
**Billing Module** (subscriptions, invoices, payments, features):
|
||||
- `admin_subscriptions.py`, `admin_invoices.py`, `admin_features.py`
|
||||
|
||||
**Inventory Module** (stock management):
|
||||
- `admin.py` (inventory admin routes)
|
||||
|
||||
**Orders Module** (order management, exceptions):
|
||||
- `admin_orders.py`, `admin_order_item_exceptions.py`
|
||||
|
||||
**Marketplace Module** (letzshop integration):
|
||||
- `admin_letzshop.py`, `admin_marketplace.py`
|
||||
|
||||
## Current State
|
||||
|
||||
### Migrated to Modules (Auto-Discovered)
|
||||
### ✅ Fully Migrated to Modules (Auto-Discovered)
|
||||
|
||||
| Module | Routes | Services | Models | Schemas | Tasks |
|
||||
|--------|--------|----------|--------|---------|-------|
|
||||
| analytics | API | Stats | Report | Stats | - |
|
||||
| billing | API | Billing, Subscription | Tier, Subscription, Invoice | Billing | Subscription |
|
||||
| catalog | API | Product | Product, Category | Product | - |
|
||||
| cart | API | Cart | Cart, CartItem | Cart | Cleanup |
|
||||
| checkout | API | Checkout | - | Checkout | - |
|
||||
| cms | API, Pages | ContentPage | ContentPage, Section | CMS | - |
|
||||
| customers | API | Customer | Customer | Customer | - |
|
||||
| inventory | API | Inventory | Stock, Location | Inventory | - |
|
||||
| marketplace | API | Import, Export, Sync | ImportJob | Marketplace | Import, Export |
|
||||
| messaging | API | Message | Message | Message | - |
|
||||
| orders | API | Order | Order, OrderItem | Order | - |
|
||||
| payments | API | Payment, Stripe | Payment | Payment | - |
|
||||
| Module | Admin Routes | Vendor Routes | Services | Models | Schemas | Tasks |
|
||||
|--------|--------------|---------------|----------|--------|---------|-------|
|
||||
| analytics | - | ✅ API | Stats | Report | Stats | - |
|
||||
| billing | ✅ subscriptions, invoices, features | ✅ checkout, addons, usage | Billing, Subscription | Tier, Subscription, Invoice | Billing | Subscription |
|
||||
| catalog | ✅ products | ✅ products | Product | Product, Category | Product | - |
|
||||
| cart | - | ✅ API | Cart | Cart, CartItem | Cart | Cleanup |
|
||||
| checkout | - | ✅ API | Checkout | - | Checkout | - |
|
||||
| cms | ✅ content-pages, images, media, vendor-themes | ✅ content-pages, media | ContentPage | ContentPage, Section | CMS | - |
|
||||
| core | ✅ dashboard, settings | ✅ dashboard, settings | - | - | - | - |
|
||||
| customers | - | ✅ API | Customer | Customer | Customer | - |
|
||||
| inventory | ✅ stock | ✅ stock | Inventory | Stock, Location | Inventory | - |
|
||||
| marketplace | ✅ letzshop, marketplace | ✅ onboarding, letzshop | Import, Export, Sync | ImportJob | Marketplace | Import, Export |
|
||||
| messaging | ✅ messages, notifications, email-templates | ✅ messages, notifications, email | Message | Message | Message | - |
|
||||
| monitoring | ✅ logs, tasks, tests, code-quality, audit, platform-health | - | - | TestRun, CodeQuality | - | - |
|
||||
| orders | ✅ orders, exceptions | ✅ orders | Order | Order, OrderItem | Order | - |
|
||||
| payments | - | ✅ API | Payment, Stripe | Payment | Payment | - |
|
||||
| tenancy | ✅ auth, users, admin-users, companies, platforms, vendors | ✅ auth, profile, team, info | - | - | - | - |
|
||||
|
||||
### 🔒 Legacy Routes (Super Admin Only - Intentionally Kept)
|
||||
|
||||
These files remain in `app/api/v1/admin/` as they are super-admin framework configuration:
|
||||
|
||||
| File | Purpose | Why Legacy |
|
||||
|------|---------|------------|
|
||||
| `menu_config.py` | Navigation configuration | Framework-level config |
|
||||
| `module_config.py` | Module settings | Framework-level config |
|
||||
| `modules.py` | Module management | Framework-level config |
|
||||
|
||||
**Note:** These are intentionally kept in legacy location as they configure the module system itself.
|
||||
|
||||
### Still in Legacy Locations (Need Migration)
|
||||
|
||||
#### Vendor Routes (`app/api/v1/vendor/`)
|
||||
- `auth.py` - Authentication (belongs in core/tenancy)
|
||||
- `dashboard.py` - Dashboard (belongs in core)
|
||||
- `email_settings.py` - Email settings (belongs in messaging)
|
||||
- `email_templates.py` - Email templates (belongs in messaging)
|
||||
- `info.py` - Vendor info (belongs in tenancy)
|
||||
- `media.py` - Media library (belongs in cms)
|
||||
- `messages.py` - Messages (belongs in messaging)
|
||||
- `notifications.py` - Notifications (belongs in messaging)
|
||||
- `profile.py` - Profile (belongs in core/tenancy)
|
||||
- `settings.py` - Settings (belongs in core)
|
||||
- `team.py` - Team management (belongs in tenancy)
|
||||
|
||||
#### Admin Routes (`app/api/v1/admin/`)
|
||||
- Most files still in legacy location
|
||||
- Target: Move to respective modules or tenancy module
|
||||
|
||||
#### Services (`app/services/`)
|
||||
- 61 files still in legacy location
|
||||
- Many are re-exports from modules
|
||||
- Many files still in legacy location
|
||||
- Some are re-exports from modules
|
||||
- Target: Move actual code to modules, delete re-exports
|
||||
|
||||
#### Tasks (`app/tasks/`)
|
||||
@@ -146,10 +189,50 @@ The following rules enforce the module-first architecture:
|
||||
| MOD-018 | ERROR | Tasks must be in modules, not `app/tasks/` |
|
||||
| MOD-019 | WARNING | Schemas should be in modules, not `models/schema/` |
|
||||
|
||||
## Route Auto-Discovery Pattern
|
||||
|
||||
### Admin Routes Structure
|
||||
|
||||
Each module aggregates its admin routes in `routes/api/admin.py`:
|
||||
|
||||
```python
|
||||
# app/modules/{module}/routes/api/admin.py
|
||||
from fastapi import APIRouter, Depends
|
||||
from app.api.deps import require_module_access
|
||||
|
||||
from .admin_feature1 import admin_feature1_router
|
||||
from .admin_feature2 import admin_feature2_router
|
||||
|
||||
admin_router = APIRouter(
|
||||
dependencies=[Depends(require_module_access("{module}"))],
|
||||
)
|
||||
|
||||
admin_router.include_router(admin_feature1_router, tags=["admin-feature1"])
|
||||
admin_router.include_router(admin_feature2_router, tags=["admin-feature2"])
|
||||
```
|
||||
|
||||
### Vendor Routes Structure
|
||||
|
||||
Similar pattern for vendor routes in `routes/api/vendor.py`:
|
||||
|
||||
```python
|
||||
# app/modules/{module}/routes/api/vendor.py
|
||||
from fastapi import APIRouter, Depends
|
||||
from app.api.deps import require_module_access
|
||||
|
||||
from .vendor_feature1 import vendor_feature1_router
|
||||
|
||||
vendor_router = APIRouter(
|
||||
dependencies=[Depends(require_module_access("{module}"))],
|
||||
)
|
||||
|
||||
vendor_router.include_router(vendor_feature1_router, tags=["vendor-feature1"])
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Migrate remaining vendor routes** to appropriate modules
|
||||
2. **Migrate admin routes** to modules
|
||||
1. ✅ ~~Migrate remaining vendor routes~~ - COMPLETE
|
||||
2. ✅ ~~Migrate admin routes~~ - COMPLETE (except super-admin framework config)
|
||||
3. **Move services** from `app/services/` to module `services/`
|
||||
4. **Move tasks** from `app/tasks/` to module `tasks/`
|
||||
5. **Clean up re-exports** once all code is in modules
|
||||
@@ -168,3 +251,17 @@ Check for legacy location violations:
|
||||
python scripts/validate_architecture.py -d app/api/v1/vendor
|
||||
python scripts/validate_architecture.py -d app/services
|
||||
```
|
||||
|
||||
Verify route count:
|
||||
|
||||
```bash
|
||||
python -c "
|
||||
from main import app
|
||||
routes = [r for r in app.routes if hasattr(r, 'path')]
|
||||
print(f'Total routes: {len(routes)}')
|
||||
admin = [r for r in routes if '/admin/' in r.path]
|
||||
vendor = [r for r in routes if '/vendor/' in r.path]
|
||||
print(f'Admin routes: {len(admin)}')
|
||||
print(f'Vendor routes: {len(vendor)}')
|
||||
"
|
||||
```
|
||||
|
||||
@@ -22,7 +22,7 @@ Tailwind Standalone CLI (single binary, no npm)
|
||||
├── static/admin/css/tailwind.css → tailwind.output.css (Admin)
|
||||
├── static/vendor/css/tailwind.css → tailwind.output.css (Vendor)
|
||||
├── static/shop/css/tailwind.css → tailwind.output.css (Shop)
|
||||
└── static/platform/css/tailwind.css → tailwind.output.css (Platform)
|
||||
└── static/public/css/tailwind.css → tailwind.output.css (Platform)
|
||||
```
|
||||
|
||||
### Key Files
|
||||
|
||||
@@ -53,7 +53,7 @@ Based on `docs/marketing/pricing.md`:
|
||||
|
||||
### 1. Marketing Homepage (`/`)
|
||||
|
||||
**Template:** `app/templates/platform/homepage-wizamart.html`
|
||||
**Template:** `app/templates/public/homepage-wizamart.html`
|
||||
|
||||
**Sections:**
|
||||
|
||||
@@ -84,7 +84,7 @@ Based on `docs/marketing/pricing.md`:
|
||||
|
||||
### 2. Pricing Page (`/pricing`)
|
||||
|
||||
**Template:** `app/templates/platform/pricing.html`
|
||||
**Template:** `app/templates/public/pricing.html`
|
||||
|
||||
Standalone page with:
|
||||
- Large tier cards
|
||||
@@ -94,7 +94,7 @@ Standalone page with:
|
||||
|
||||
### 3. Find Your Shop (`/find-shop`)
|
||||
|
||||
**Template:** `app/templates/platform/find-shop.html`
|
||||
**Template:** `app/templates/public/find-shop.html`
|
||||
|
||||
- URL input with examples
|
||||
- Real-time Letzshop vendor lookup
|
||||
@@ -103,7 +103,7 @@ Standalone page with:
|
||||
|
||||
### 4. Signup Wizard (`/signup`)
|
||||
|
||||
**Template:** `app/templates/platform/signup.html`
|
||||
**Template:** `app/templates/public/signup.html`
|
||||
|
||||
**4-Step Flow:**
|
||||
|
||||
@@ -121,7 +121,7 @@ Standalone page with:
|
||||
|
||||
### 5. Signup Success (`/signup/success`)
|
||||
|
||||
**Template:** `app/templates/platform/signup-success.html`
|
||||
**Template:** `app/templates/public/signup-success.html`
|
||||
|
||||
- Success confirmation
|
||||
- Next steps checklist
|
||||
@@ -132,24 +132,24 @@ Standalone page with:
|
||||
|
||||
## API Endpoints
|
||||
|
||||
All endpoints under `/api/v1/platform/`:
|
||||
All endpoints under `/api/v1/public/`:
|
||||
|
||||
### Pricing Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/platform/tiers
|
||||
GET /api/v1/public/tiers
|
||||
Returns all public subscription tiers
|
||||
Response: TierResponse[]
|
||||
|
||||
GET /api/v1/platform/tiers/{tier_code}
|
||||
GET /api/v1/public/tiers/{tier_code}
|
||||
Returns specific tier by code
|
||||
Response: TierResponse
|
||||
|
||||
GET /api/v1/platform/addons
|
||||
GET /api/v1/public/addons
|
||||
Returns all active add-on products
|
||||
Response: AddOnResponse[]
|
||||
|
||||
GET /api/v1/platform/pricing
|
||||
GET /api/v1/public/pricing
|
||||
Returns complete pricing info (tiers + addons + trial_days)
|
||||
Response: PricingResponse
|
||||
```
|
||||
@@ -157,17 +157,17 @@ GET /api/v1/platform/pricing
|
||||
### Letzshop Vendor Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/platform/letzshop-vendors
|
||||
GET /api/v1/public/letzshop-vendors
|
||||
Query params: ?search=&category=&city=&page=1&limit=20
|
||||
Returns paginated vendor list (placeholder for future)
|
||||
Response: LetzshopVendorListResponse
|
||||
|
||||
POST /api/v1/platform/letzshop-vendors/lookup
|
||||
POST /api/v1/public/letzshop-vendors/lookup
|
||||
Body: { "url": "letzshop.lu/vendors/my-shop" }
|
||||
Returns vendor info from URL lookup
|
||||
Response: LetzshopLookupResponse
|
||||
|
||||
GET /api/v1/platform/letzshop-vendors/{slug}
|
||||
GET /api/v1/public/letzshop-vendors/{slug}
|
||||
Returns vendor info by slug
|
||||
Response: LetzshopVendorInfo
|
||||
```
|
||||
@@ -175,17 +175,17 @@ GET /api/v1/platform/letzshop-vendors/{slug}
|
||||
### Signup Endpoints
|
||||
|
||||
```
|
||||
POST /api/v1/platform/signup/start
|
||||
POST /api/v1/public/signup/start
|
||||
Body: { "tier_code": "professional", "is_annual": false }
|
||||
Creates signup session
|
||||
Response: { "session_id": "...", "tier_code": "...", "is_annual": false }
|
||||
|
||||
POST /api/v1/platform/signup/claim-vendor
|
||||
POST /api/v1/public/signup/claim-vendor
|
||||
Body: { "session_id": "...", "letzshop_slug": "my-shop" }
|
||||
Claims Letzshop vendor for session
|
||||
Response: { "session_id": "...", "letzshop_slug": "...", "vendor_name": "..." }
|
||||
|
||||
POST /api/v1/platform/signup/create-account
|
||||
POST /api/v1/public/signup/create-account
|
||||
Body: {
|
||||
"session_id": "...",
|
||||
"email": "user@example.com",
|
||||
@@ -197,17 +197,17 @@ POST /api/v1/platform/signup/create-account
|
||||
Creates User, Company, Vendor, Stripe Customer
|
||||
Response: { "session_id": "...", "user_id": 1, "vendor_id": 1, "stripe_customer_id": "cus_..." }
|
||||
|
||||
POST /api/v1/platform/signup/setup-payment
|
||||
POST /api/v1/public/signup/setup-payment
|
||||
Body: { "session_id": "..." }
|
||||
Creates Stripe SetupIntent
|
||||
Response: { "session_id": "...", "client_secret": "seti_...", "stripe_customer_id": "cus_..." }
|
||||
|
||||
POST /api/v1/platform/signup/complete
|
||||
POST /api/v1/public/signup/complete
|
||||
Body: { "session_id": "...", "setup_intent_id": "seti_..." }
|
||||
Completes signup, attaches payment method
|
||||
Response: { "success": true, "vendor_code": "...", "vendor_id": 1, "redirect_url": "...", "trial_ends_at": "..." }
|
||||
|
||||
GET /api/v1/platform/signup/session/{session_id}
|
||||
GET /api/v1/public/signup/session/{session_id}
|
||||
Returns session status for resuming signup
|
||||
Response: { "session_id": "...", "step": "...", ... }
|
||||
```
|
||||
@@ -430,7 +430,7 @@ STRIPE_TRIAL_DAYS=30
|
||||
|
||||
### Automated Tests
|
||||
|
||||
Test files located in `tests/integration/api/v1/platform/`:
|
||||
Test files located in `tests/integration/api/v1/public/`:
|
||||
|
||||
| File | Tests | Description |
|
||||
|------|-------|-------------|
|
||||
@@ -440,7 +440,7 @@ Test files located in `tests/integration/api/v1/platform/`:
|
||||
|
||||
**Run tests:**
|
||||
```bash
|
||||
pytest tests/integration/api/v1/platform/ -v
|
||||
pytest tests/integration/api/v1/public/ -v
|
||||
```
|
||||
|
||||
**Test categories:**
|
||||
@@ -479,15 +479,15 @@ pytest tests/integration/api/v1/platform/ -v
|
||||
|
||||
```bash
|
||||
# Get pricing
|
||||
curl http://localhost:8000/api/v1/platform/pricing
|
||||
curl http://localhost:8000/api/v1/public/pricing
|
||||
|
||||
# Lookup vendor
|
||||
curl -X POST http://localhost:8000/api/v1/platform/letzshop-vendors/lookup \
|
||||
curl -X POST http://localhost:8000/api/v1/public/letzshop-vendors/lookup \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"url": "letzshop.lu/vendors/test-shop"}'
|
||||
|
||||
# Start signup
|
||||
curl -X POST http://localhost:8000/api/v1/platform/signup/start \
|
||||
curl -X POST http://localhost:8000/api/v1/public/signup/start \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"tier_code": "professional", "is_annual": false}'
|
||||
```
|
||||
|
||||
129
docs/proposals/PLAN_documentation-consolidation.md
Normal file
129
docs/proposals/PLAN_documentation-consolidation.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# Documentation Consolidation Plan
|
||||
|
||||
## Overview
|
||||
|
||||
Many working documents (session notes, migration plans, proposals) now represent **implemented features**. This plan consolidates them into proper platform documentation.
|
||||
|
||||
## Document Categories
|
||||
|
||||
### 1. Implemented → Merge into Architecture/Feature Docs
|
||||
|
||||
These documents describe features that are now implemented and should be merged into proper documentation.
|
||||
|
||||
| Working Document | Target Location | Action |
|
||||
|------------------|-----------------|--------|
|
||||
| `proposals/SESSION_NOTE_2026-01-25_modular-platform-architecture.md` | `architecture/module-system.md` | Merge relevant content, archive original |
|
||||
| `proposals/SESSION_NOTE_2026-01-26_self-contained-modules.md` | `architecture/module-system.md` | Merge relevant content, archive original |
|
||||
| `proposals/SESSION_NOTE_2026-01-27_module-reclassification.md` | `architecture/module-system.md` | Merge relevant content, archive original |
|
||||
| `proposals/SESSION_NOTE_2026-01-28_module-config-migrations.md` | `architecture/module-system.md` | Merge relevant content, archive original |
|
||||
| `proposals/SESSION_NOTE_2026-01-30_self-contained-module-routes.md` | `architecture/module-system.md` | Merge relevant content, archive original |
|
||||
| `proposals/SESSION_NOTE_2026-01-31_tenancy-module-consolidation.md` | `architecture/tenancy-module-migration.md` | Merge, archive original |
|
||||
| `proposals/multi-platform-cms-architecture.md` | `features/content-management-system.md` | Merge as "How CMS Works" section |
|
||||
| `proposals/multi-platform-cms-architecture-implementation-plan.md` | Archive | Implementation complete |
|
||||
| `proposals/section-based-homepage-plan.md` | `features/platform-homepage.md` | Merge as technical details |
|
||||
| `proposals/module-migration-plan.md` | Archive | Migration complete |
|
||||
| `migration/language-i18n-implementation.md` | `architecture/language-i18n.md` | Merge (may already exist) |
|
||||
| `migration/multi-marketplace-product-architecture.md` | `architecture/marketplace-integration.md` | Merge product sync details |
|
||||
| `migration/vendor-operations-expansion.md` | `architecture/company-vendor-management.md` | Merge operations info |
|
||||
| `migration/vendor-contact-inheritance.md` | `architecture/company-vendor-management.md` | Merge contact inheritance |
|
||||
| `migration/product-migration-database-changes.md` | Archive | Migration complete |
|
||||
| `migration/makefile-refactoring-complete.md` | Archive | Refactoring complete |
|
||||
| `migration/tailwind-migration-plan.md` | Archive or `development/tailwind-css.md` | Verify if complete |
|
||||
|
||||
### 2. Keep as Development Guides
|
||||
|
||||
These should remain as development reference but may need cleanup.
|
||||
|
||||
| Document | Location | Action |
|
||||
|----------|----------|--------|
|
||||
| `migration/database-migrations.md` | Keep | Update if needed |
|
||||
| `migration/module-autodiscovery-migration.md` | Keep | Already updated, serves as history |
|
||||
| `migration/svc-006-migration-plan.md` | `development/coding-standards.md` | Merge db.commit pattern |
|
||||
|
||||
### 3. Future/Unimplemented → Keep in Proposals
|
||||
|
||||
| Document | Status | Action |
|
||||
|----------|--------|--------|
|
||||
| `proposals/loyalty-program-analysis.md` | Future feature | Keep as proposal |
|
||||
| `proposals/loyalty-phase2-interfaces-plan.md` | Future feature | Keep as proposal |
|
||||
| `proposals/PLAN_storefront-module-restructure.md` | Evaluate status | Keep or archive |
|
||||
| `proposals/humble-orbiting-otter.md` | Claude plan file | Archive |
|
||||
|
||||
## Target Documentation Structure
|
||||
|
||||
After consolidation, the docs should have:
|
||||
|
||||
```
|
||||
docs/
|
||||
├── architecture/
|
||||
│ ├── module-system.md ← Comprehensive module docs (merged SESSION_NOTEs)
|
||||
│ ├── multi-tenant.md ← Platform/Company/Vendor architecture
|
||||
│ ├── language-i18n.md ← i18n implementation
|
||||
│ ├── marketplace-integration.md ← Letzshop sync, product architecture
|
||||
│ ├── company-vendor-management.md ← Vendor operations, contact inheritance
|
||||
│ └── ...
|
||||
├── features/
|
||||
│ ├── content-management-system.md ← CMS with multi-platform details
|
||||
│ ├── platform-homepage.md ← Section-based homepage
|
||||
│ ├── subscription-billing.md ← Billing features
|
||||
│ └── ...
|
||||
├── development/
|
||||
│ ├── creating-modules.md ← How to create new modules
|
||||
│ ├── coding-standards.md ← db.commit pattern, etc.
|
||||
│ ├── database-migrations.md ← Migration guide
|
||||
│ └── migration/ ← Historical migration docs (reference)
|
||||
│ └── module-autodiscovery-migration.md
|
||||
├── proposals/ ← Future features only
|
||||
│ ├── loyalty-program-analysis.md
|
||||
│ └── loyalty-phase2-interfaces-plan.md
|
||||
└── archive/ ← Completed plans (optional)
|
||||
├── SESSION_NOTE_*.md
|
||||
└── *-implementation-plan.md
|
||||
```
|
||||
|
||||
## Consolidation Steps
|
||||
|
||||
### Phase 1: Module System Documentation
|
||||
1. Review all SESSION_NOTE files for module system
|
||||
2. Extract key decisions and final architecture
|
||||
3. Update `architecture/module-system.md` with:
|
||||
- Clear module classification (core/optional/internal)
|
||||
- Route auto-discovery pattern
|
||||
- Entity locations (routes, services, models, etc.)
|
||||
4. Archive SESSION_NOTE files
|
||||
|
||||
### Phase 2: CMS & Homepage Documentation
|
||||
1. Merge CMS architecture into `features/content-management-system.md`
|
||||
2. Merge homepage sections into `features/platform-homepage.md`
|
||||
3. Archive implementation plans
|
||||
|
||||
### Phase 3: Vendor & Marketplace Documentation
|
||||
1. Update `architecture/company-vendor-management.md` with:
|
||||
- Contact inheritance
|
||||
- Vendor operations
|
||||
2. Update `architecture/marketplace-integration.md` with:
|
||||
- Multi-marketplace product architecture
|
||||
- Sync patterns
|
||||
|
||||
### Phase 4: Development Guides
|
||||
1. Create/update `development/coding-standards.md` with db.commit pattern
|
||||
2. Verify Tailwind migration status, archive if complete
|
||||
3. Clean up migration folder
|
||||
|
||||
### Phase 5: Archive
|
||||
1. Create `docs/archive/` folder (or just delete completed plans)
|
||||
2. Move completed implementation plans
|
||||
3. Move SESSION_NOTE files
|
||||
|
||||
## Priority Order
|
||||
|
||||
1. **High**: Module system (most referenced, core architecture)
|
||||
2. **High**: CMS/Homepage (user-facing features)
|
||||
3. **Medium**: Vendor/Marketplace (operational)
|
||||
4. **Low**: Archive cleanup
|
||||
|
||||
## Notes
|
||||
|
||||
- Keep `migration/module-autodiscovery-migration.md` as historical reference
|
||||
- SESSION_NOTEs contain valuable context but are verbose for reference docs
|
||||
- Focus on "what is" not "what was planned" in final docs
|
||||
@@ -1,229 +0,0 @@
|
||||
│ 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