TorbatYar/docs/delivery-phase-10-1.md

# Phase 10.1 — Driver Management

| Field | Value |
| --- | --- |
| Identifier | `delivery-10.1` |
| Status | Complete |
| Module | delivery |
| Service | `delivery-service` |
| Version | `0.10.1.0` |
| Database | `delivery_db` |
| API Port | 8007 |
| Depends On | Phase 10.0 |
| ADR(s) | ADR-001, ADR-003, ADR-006, ADR-015 |
| Commercial Product | Torbat Driver |
| Manifest | [phase-manifest.yaml](ai-framework/phase-manifest.yaml) |

## Enterprise Phase Discovery Summary

| Item | Detail |
| --- | --- |
| Capabilities required | Driver profiles, credential/document refs, status lifecycle, list UX (filter/sort/search/page), audit, outbox events, permissions |
| Gaps closed | Driver aggregate + lifecycle policy + credentials/documents + transactional outbox + permission leaves |
| Exclusions | Fleet/vehicles (10.2), availability/shifts/zones (10.3), dispatch (10.5), routing execution (10.6), tracking/POD (10.7) |
| CRUD-only rejected | Yes — lifecycle machine, credentials, documents, outbox, specs, policies required |

## Goal

Deliver production-ready **Driver Management** for the Delivery & Fleet Platform (Torbat Driver): profiles, credential and document references, status lifecycle with append-only history, tenant-isolated APIs, audit, and outbox events — without fleet, dispatch, routing, or tracking engines.

## Scope Delivered

### In Scope

- Aggregates: `Driver`, `DriverCredential`, `DriverDocument`, `DriverLifecycleEvent`, `OutboxEvent`
- Lifecycle: activate, suspend, resume, deactivate, block, unblock, archive
- Soft delete + optimistic locking on drivers
- List: pagination, filtering (status/org/hub), sorting, searching
- Commands / queries / policies / specifications / validators
- Permissions `delivery.drivers.*` leaves + catalog discovery API
- Publish-only events `delivery.driver.*` via transactional outbox
- Health / capabilities / metrics updated (`phase: 10.1`, `drivers: true`)
- Alembic `0002_phase_101_drivers`
- Tests: unit, API/integration, tenant, architecture, migration, permissions, performance indexes, docs

### Out of Scope

- Fleet / vehicle types / vehicles (10.2)
- Availability / shifts / working zones (10.3)
- Pricing / capability bundles (10.4)
- Dispatch engine (10.5)
- Routing / optimization execution (10.6)
- Tracking / POD (10.7)
- Settlement (10.8)
- Merchant connector / app UI (10.9)
- Analytics / AI (10.10)

## Service Boundaries

| Delivery owns | Delivery does not own |
| --- | --- |
| Driver profiles and lifecycle in `delivery_db` | Identity user administration |
| Credential/document **metadata** + Storage file refs | File blobs (Storage) |
| External user / CRM contact refs | CRM contact master |
| Driver permissions `delivery.drivers.*` | Communication message delivery |
| Outbox `delivery.driver.*` events | Accounting journals |

## Domain Model

### Driver statuses

`pending` → `active` ↔ `suspended` → `inactive` → `archived` (terminal); `block` → `blocked` → `unblock` → `inactive`.

| Action | Allowed from | To | Reason required |
| --- | --- | --- | --- |
| activate | pending, inactive, suspended | active | No |
| suspend | active | suspended | Yes |
| resume | suspended | active | No |
| deactivate | active, suspended | inactive | Yes |
| block | pending, active, suspended, inactive | blocked | Yes |
| unblock | blocked | inactive | No |
| archive | inactive, blocked | archived | Yes |

### Aggregates

| Entity | Soft delete | Optimistic lock | Tenant |
| --- | --- | --- | --- |
| Driver | Yes | Yes | Yes |
| DriverCredential | Yes | No | Yes |
| DriverDocument | Yes | No | Yes |
| DriverLifecycleEvent | No (append-only) | No | Yes |
| OutboxEvent | N/A | N/A | Yes |

## APIs

| Method | Path | Permission |
| --- | --- | --- |
| POST | `/api/v1/drivers` | `delivery.drivers.create` |
| GET | `/api/v1/drivers` | `delivery.drivers.view` |
| GET | `/api/v1/drivers/{id}` | `delivery.drivers.view` |
| PATCH | `/api/v1/drivers/{id}` | `delivery.drivers.update` |
| POST | `/api/v1/drivers/{id}/activate` | `delivery.drivers.activate` |
| POST | `/api/v1/drivers/{id}/suspend` | `delivery.drivers.suspend` |
| POST | `/api/v1/drivers/{id}/resume` | `delivery.drivers.resume` |
| POST | `/api/v1/drivers/{id}/deactivate` | `delivery.drivers.deactivate` |
| POST | `/api/v1/drivers/{id}/block` | `delivery.drivers.block` |
| POST | `/api/v1/drivers/{id}/unblock` | `delivery.drivers.unblock` |
| POST | `/api/v1/drivers/{id}/archive` | `delivery.drivers.archive` |
| GET | `/api/v1/drivers/{id}/lifecycle` | `delivery.drivers.lifecycle.view` |
| POST/GET | `/api/v1/drivers/{id}/credentials` | credentials.manage / view |
| POST/GET | `/api/v1/drivers/{id}/documents` | documents.manage / view |
| POST | `/api/v1/drivers/{id}/delete` | `delivery.drivers.delete` |
| GET | `/api/v1/permissions/catalog` | `delivery.view` |
| GET | `/health`, `/capabilities`, `/metrics` | Public |

List query params: `page`, `page_size`, `status`, `organization_id`, `hub_id`, `q`, `sort_by`, `sort_dir`.

## Events

| Event | Aggregate |
| --- | --- |
| `delivery.driver.created` | driver |
| `delivery.driver.updated` | driver |
| `delivery.driver.activated` / `suspended` / `resumed` / `deactivated` / `blocked` / `unblocked` / `archived` | driver |
| `delivery.driver.status_changed` | driver |
| `delivery.driver.deleted` | driver |
| `delivery.driver.credential_added` | driver_credential |
| `delivery.driver.document_attached` | driver_document |

Persisted via transactional outbox (`outbox_events`) per ADR-006; mirrored in-memory under test.

## Permissions

`delivery.drivers.view|create|update|delete|activate|suspend|resume|deactivate|block|unblock|archive|lifecycle.view|credentials.view|credentials.manage|documents.view|documents.manage|manage`

## Migration

| Item | Detail |
| --- | --- |
| Alembic | `0002_phase_101_drivers` (down_revision `0001_initial`) |
| Breaking | None — additive tables |
| Backfill | None |

## Architecture Decisions

1. Driver status machine owned by Delivery validators/policies — not Identity
2. Credential/document binaries remain Storage refs only
3. Transactional outbox introduced for driver mutations (backward-compatible with foundation in-memory publisher)
4. No fleet/vehicle/dispatch tables in this phase
5. Soft delete + optimistic lock on Driver; append-only lifecycle history

## Folder Additions

```
app/models/drivers.py
app/models/outbox.py
app/validators/drivers.py
app/policies/drivers.py
app/specifications/drivers.py
app/repositories/drivers.py
app/services/drivers.py
app/schemas/drivers.py
app/commands/drivers.py
app/queries/drivers.py
app/api/v1/drivers.py
app/api/v1/permissions.py
alembic/versions/0002_phase_101_drivers.py
```

## Tests

- Unit: lifecycle transition matrix
- Integration: lifecycle flow, credentials/documents, filter/sort/search, optimistic lock, soft delete, tenant isolation
- Architecture / migration / permissions / performance indexes / docs / security (auth required)

## Definition of Done

All Enterprise Quality Gates for Phase 10.1 satisfied. See [phase-handover/phase-10-1.md](phase-handover/phase-10-1.md).

## Related Documents

- [Delivery Roadmap](delivery-roadmap.md)
- [Phase 10.0](delivery-phase-10-0.md)
- [Handover 10.1](phase-handover/phase-10-1.md)
- [ADR-015](architecture/adr/ADR-015.md)