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>
165 lines
6.2 KiB
Markdown
165 lines
6.2 KiB
Markdown
# Phase Handover — 10.1 Driver Management
|
|
|
|
## Metadata
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Phase ID | `delivery-10.1` |
|
|
| Title | Driver Management |
|
|
| Status | Complete |
|
|
| Service(s) | `delivery` |
|
|
| Version | 0.10.1.0 |
|
|
| Date | 2026-07-25 |
|
|
| ADR(s) | [ADR-015](../architecture/adr/ADR-015.md), ADR-001, ADR-003, ADR-006 |
|
|
|
|
## Enterprise Phase Discovery Summary
|
|
|
|
| Item | Detail |
|
|
| --- | --- |
|
|
| Discovery Record location | [delivery-phase-10-1.md](../delivery-phase-10-1.md#enterprise-phase-discovery-summary) |
|
|
| Gaps promoted & closed | Driver aggregate, lifecycle, credentials/documents, outbox, list UX, permission leaves |
|
|
| Exclusions (future / other service) | Fleet 10.2; availability 10.3; dispatch 10.5; Identity/CRM/Storage ownership |
|
|
| CRUD-only rejected | Yes |
|
|
|
|
## Business Analysis Summary
|
|
|
|
| Item | Detail |
|
|
| --- | --- |
|
|
| Capabilities delivered | Driver profiles; status lifecycle; credential & document refs; audit; outbox events; permission catalog |
|
|
| Explicit non-goals honored | No fleet, dispatch, routing execution, tracking, settlement |
|
|
|
|
## Reusable Components
|
|
|
|
| Component | Location | Reuse notes |
|
|
| --- | --- | --- |
|
|
| DriverLifecyclePolicy | `app/policies/drivers.py` | Later availability/dispatch readiness checks |
|
|
| DriverListSpec | `app/specifications/drivers.py` | Pattern for fleet/vehicle lists |
|
|
| TransactionalEventPublisher | `app/events/publisher.py` | Prefer for all new Delivery mutations |
|
|
| DriverCommands / DriverQueries | `app/commands|queries/drivers.py` | CQ thin wrappers |
|
|
| TenantBaseRepository | `app/repositories/base.py` | Continued |
|
|
|
|
## Public APIs
|
|
|
|
| Method | Path | Auth / Permission | Notes |
|
|
| --- | --- | --- | --- |
|
|
| GET | `/health` | Public | Liveness |
|
|
| GET | `/capabilities` | Public | `phase: 10.1`, `drivers: true` |
|
|
| GET | `/metrics` | Public | Driver metric keys |
|
|
| * | `/api/v1/drivers` | JWT + `delivery.drivers.*` | CRUD + lifecycle + credentials/documents |
|
|
| GET | `/api/v1/permissions/catalog` | JWT + `delivery.view` | Static permission discovery |
|
|
| * | Foundation routes from 10.0 | Unchanged | Backward compatible |
|
|
|
|
## Events
|
|
|
|
| Event type | Domain / Integration | Payload summary | Version |
|
|
| --- | --- | --- | --- |
|
|
| `delivery.driver.created` | Delivery | code, status, organization_id | 0.10.1.0 |
|
|
| `delivery.driver.updated` | Delivery | code | 0.10.1.0 |
|
|
| `delivery.driver.status_changed` | Delivery | action, from/to status | 0.10.1.0 |
|
|
| `delivery.driver.activated` / `suspended` / `resumed` / `deactivated` / `blocked` / `unblocked` / `archived` | Delivery | code, status | 0.10.1.0 |
|
|
| `delivery.driver.deleted` | Delivery | code | 0.10.1.0 |
|
|
| `delivery.driver.credential_added` | Delivery | driver_id, kind | 0.10.1.0 |
|
|
| `delivery.driver.document_attached` | Delivery | driver_id, kind | 0.10.1.0 |
|
|
|
|
## Permissions
|
|
|
|
| Permission | Routes / actions |
|
|
| --- | --- |
|
|
| `delivery.drivers.view` | GET list/detail |
|
|
| `delivery.drivers.create` | POST create |
|
|
| `delivery.drivers.update` | PATCH profile |
|
|
| `delivery.drivers.delete` | POST soft delete |
|
|
| `delivery.drivers.activate\|suspend\|resume\|deactivate\|block\|unblock\|archive` | Lifecycle POSTs |
|
|
| `delivery.drivers.lifecycle.view` | GET lifecycle history |
|
|
| `delivery.drivers.credentials.*` | Credential POST/GET |
|
|
| `delivery.drivers.documents.*` | Document POST/GET |
|
|
| `delivery.drivers.manage` | Wildcard manage leaf |
|
|
|
|
## Extension Points
|
|
|
|
| Extension point | How to extend | Forbidden uses |
|
|
| --- | --- | --- |
|
|
| Driver.capability_tags | Later pricing/bundles (10.4) | Encoding vertical order rules |
|
|
| external_user_ref / CRM ref | Identity/CRM link only | Owning users/contacts in Delivery |
|
|
| Storage file refs | Attachments via Storage | Storing blobs in delivery_db |
|
|
| Outbox drain | Worker/publisher later | Sync cross-DB writes |
|
|
|
|
## Known Limitations
|
|
|
|
- No availability/shift/zone readiness (10.3)
|
|
- No vehicle assignment (10.2)
|
|
- Outbox drain worker not yet implemented (rows persisted; mirror in tests)
|
|
- Metrics remain discovery-oriented (no live Prometheus scrape counters)
|
|
- Driver App UI remains frontend (API only)
|
|
|
|
## Migration Notes
|
|
|
|
| Item | Detail |
|
|
| --- | --- |
|
|
| Alembic revision(s) | `0002_phase_101_drivers` |
|
|
| Upgrade steps | `alembic upgrade head` |
|
|
| Downgrade support | Drops additive driver/outbox tables |
|
|
| Data backfill / seeds | None |
|
|
| Breaking changes | None |
|
|
|
|
## Dependencies
|
|
|
|
| Dependency | Type | Required for |
|
|
| --- | --- | --- |
|
|
| Phase 10.0 foundation | Service | Org/hub validation |
|
|
| shared-lib | Library | JWT, events, exceptions |
|
|
| ADR-015 / ADR-006 | Docs | Boundaries / outbox |
|
|
| Postgres `delivery_db` | Infra | Persistence |
|
|
|
|
## Boundary Compliance
|
|
|
|
- [x] No foreign service ownership implemented
|
|
- [x] No business logic duplication
|
|
- [x] No cross-DB access
|
|
- [x] Integrations only via API / Events / Providers
|
|
- [x] No future-phase functionality pulled forward
|
|
|
|
## Enterprise Completeness Sign-Off
|
|
|
|
- [x] Business completeness
|
|
- [x] Architectural completeness
|
|
- [x] API completeness
|
|
- [x] Permission completeness
|
|
- [x] Capability completeness
|
|
- [x] Event completeness
|
|
- [x] Migration completeness
|
|
- [x] Repository completeness
|
|
- [x] Validation completeness
|
|
- [x] Security completeness
|
|
- [x] Performance completeness
|
|
- [x] Documentation completeness
|
|
- [x] Test completeness
|
|
- [x] Operational readiness
|
|
- [x] Developer experience
|
|
- [x] Self audit
|
|
|
|
## Next Phase Entry
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Recommended next phase | `delivery-10.2` Fleet & Vehicle Types |
|
|
| Blockers for next phase | None |
|
|
| Entry checklist | Read this handover + [delivery-phase-10-1.md](../delivery-phase-10-1.md) + ADR-015; implement fleets/vehicle types/vehicles only — no dispatch yet |
|
|
|
|
## Completion Sign-Off
|
|
|
|
- [x] Quality gates passed
|
|
- [x] Tests green
|
|
- [x] Documentation updated
|
|
- [x] Progress / next-steps / registries updated
|
|
- [x] No unfinished claimed deliverables
|
|
- [x] Self audit completed
|
|
|
|
## Related Documents
|
|
|
|
- [Delivery Phase 10.1](../delivery-phase-10-1.md)
|
|
- [Delivery Roadmap](../delivery-roadmap.md)
|
|
- [ADR-015](../architecture/adr/ADR-015.md)
|
|
- [Phase Manifest](../ai-framework/phase-manifest.yaml)
|
|
- [Service Manifest](../ai-framework/service-manifest.yaml)
|