5c6a2e78cf
Register all active platform services and base features in core DB so admin can manage them, add delivery/hospitality/sports-center backend phases, update apps catalog and production deploy tooling. Co-authored-by: Cursor <cursoragent@cursor.com>
134 lines
4.7 KiB
Markdown
134 lines
4.7 KiB
Markdown
# Phase 10.0 — Delivery Platform Foundation
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Status | Complete |
|
|
| Module | delivery |
|
|
| Version | 0.10.0.0 |
|
|
| Database | `delivery_db` |
|
|
| API Port | 8007 |
|
|
| ADR | ADR-001, ADR-003, ADR-006, ADR-015 |
|
|
| Commercial Product | Torbat Driver |
|
|
|
|
## Goal
|
|
|
|
Establish the **Delivery & Fleet Platform** as a completely independent enterprise microservice foundation (commercial product: **Torbat Driver**).
|
|
|
|
Reusable by Hospitality, Marketplace, Store, Pharmacy, Clinic, Sports Center, and future services via **API + Events only** — no shared databases, no business logic duplication.
|
|
|
|
This phase implements foundation shells and discovery surfaces only. It does **not** implement driver workflows, dispatch, routing engines, tracking, or settlement engines.
|
|
|
|
## Scope Delivered
|
|
|
|
### In Scope
|
|
|
|
- Service scaffold under `backend/services/delivery` (API → Service → Repository → Model)
|
|
- Foundation aggregates: DeliveryOrganization, DeliveryHub, DeliveryRole, DeliveryPermission, ExternalProviderConfig, RoutingEngineRegistration, DeliveryConfiguration, DeliverySetting, DeliveryAuditLog
|
|
- Health `/health`, Capability `/capabilities`, Metrics `/metrics`
|
|
- Permissions `delivery.*` trees (foundation + planned leaves)
|
|
- Publish-only events `delivery.*` (organization/hub/provider/routing/config/setting)
|
|
- Platform provider contracts (Accounting, CRM, Loyalty, Communication, Notification, Storage, AI, Identity, RoutingEngine, Fleet)
|
|
- Tenant isolation via `X-Tenant-ID`
|
|
- Alembic `0001_initial` + compose wiring (port 8007)
|
|
- Tests: architecture, API/tenant, permissions, migration, dependency, security, docs
|
|
|
|
### Out of Scope
|
|
|
|
- Driver management (10.1)
|
|
- Fleet / vehicle types (10.2)
|
|
- Availability / shifts / zones (10.3)
|
|
- Pricing / capability bundles (10.4)
|
|
- Dispatch engine (10.5)
|
|
- Routing / optimization execution (10.6)
|
|
- Tracking / POD (10.7)
|
|
- Settlement posting (10.8)
|
|
- Merchant connector / app UI (10.9)
|
|
- Analytics / AI (10.10)
|
|
|
|
## Service Boundaries
|
|
|
|
| Delivery owns | Delivery does not own |
|
|
| --- | --- |
|
|
| Aggregates above | Accounting / Posting Engine |
|
|
| Delivery HTTP APIs under `/api/v1/*` | CRM sales entities |
|
|
| `delivery.*` permissions | Loyalty ledger / points |
|
|
| Publish-only delivery events | Communication / SMS providers / message delivery timeline |
|
|
| External provider & routing-engine **registrations** | Vertical order aggregates |
|
|
| Tenant delivery configuration | Identity / Storage blobs / AI inference |
|
|
|
|
## Published Events (Phase 10.0)
|
|
|
|
| Event | Aggregate |
|
|
| --- | --- |
|
|
| `delivery.organization.created` / `updated` | organization |
|
|
| `delivery.hub.created` / `updated` | hub |
|
|
| `delivery.external_provider.registered` / `updated` | external_provider_config |
|
|
| `delivery.routing_engine.registered` / `updated` | routing_engine_registration |
|
|
| `delivery.configuration.created` / `updated` | configuration |
|
|
| `delivery.setting.upserted` | setting |
|
|
|
|
## API Contracts
|
|
|
|
| Resource | Prefix |
|
|
| --- | --- |
|
|
| Organizations | `/api/v1/organizations` |
|
|
| Hubs | `/api/v1/hubs` |
|
|
| External providers | `/api/v1/external-providers` |
|
|
| Routing engines | `/api/v1/routing-engines` |
|
|
| Configurations | `/api/v1/configurations` |
|
|
| Settings | `/api/v1/settings` |
|
|
| Audit | `/api/v1/audit` |
|
|
| Health / Capabilities / Metrics | `/health`, `/capabilities`, `/metrics` |
|
|
|
|
## Permissions
|
|
|
|
`delivery.*` trees covering organizations, hubs, external providers, routing engines, configurations, settings, audit, plus planned leaves for drivers/fleet/dispatch/routing/tracking/settlement.
|
|
|
|
## Architecture Decisions
|
|
|
|
1. Database-per-service (`delivery_db`) — ADR-001 / ADR-015
|
|
2. Row-level `tenant_id` — ADR-003
|
|
3. Event publish contracts via `EventEnvelope` — ADR-006
|
|
4. Vertical-agnostic logistics platform — no hardcoded Hospitality/Marketplace rules
|
|
5. External routing/fleet providers behind Protocols — vendor logic outside business services
|
|
6. Soft delete + actor audit + delivery audit log
|
|
7. Optimistic locking on organizations, providers, routing engines, configurations
|
|
|
|
## Folder Structure
|
|
|
|
```
|
|
backend/services/delivery/
|
|
app/
|
|
api/v1/
|
|
core/
|
|
middlewares/
|
|
models/
|
|
repositories/
|
|
services/
|
|
validators/
|
|
schemas/
|
|
events/
|
|
permissions/
|
|
providers/
|
|
policies/
|
|
specifications/
|
|
commands/
|
|
queries/
|
|
tests/
|
|
alembic/versions/0001_initial.py
|
|
scripts/ensure_db.py
|
|
README.md
|
|
```
|
|
|
|
## Tests Executed
|
|
|
|
Architecture · API foundation flow · tenant isolation · permissions · migration · dependency · security · docs
|
|
|
|
## Related Documents
|
|
|
|
- [Phase Handover 10.0](phase-handover/phase-10-0.md)
|
|
- [Delivery Roadmap](delivery-roadmap.md)
|
|
- [ADR-015](architecture/adr/ADR-015.md)
|
|
- [Module Registry](module-registry.md#delivery)
|
|
- [Progress](progress.md)
|