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>
100 lines
6.2 KiB
Markdown
100 lines
6.2 KiB
Markdown
# Mandatory Phase Artifacts
|
|
|
|
Every implementation phase **automatically** includes the artifacts below unless the phase is explicitly **documentation-only** or an item is marked **N/A** with written justification tied to the phase boundary.
|
|
|
|
This list is normative. Agents must not wait for the phase prompt to restate it. ([ADR-018](../architecture/adr/ADR-018.md))
|
|
|
|
## Artifact Matrix
|
|
|
|
| # | Artifact | Required when | Primary standard |
|
|
| --- | --- | --- | --- |
|
|
| 0 | Enterprise Phase Discovery | Always (before Implementation) | [enterprise-phase-discovery.md](enterprise-phase-discovery.md) |
|
|
| 1 | Business Analysis | Always (implementation phases) | [phase-template.md](phase-template.md) · [definition-of-done.md](definition-of-done.md) |
|
|
| 2 | Architecture Validation | Always | [development-loop.md](development-loop.md) · ADRs · [module-boundaries.md](../architecture/module-boundaries.md) |
|
|
| 3 | Domain Modeling | New/changed domain surface | Phase doc Domain Model section |
|
|
| 4 | Aggregate Design | New/changed aggregates | [entity-template.md](entity-template.md) · DDD aggregate rules |
|
|
| 5 | Entity Design | New/changed tables/models | [entity-template.md](entity-template.md) |
|
|
| 6 | DTO Design | Any API surface | [api-template.md](api-template.md) |
|
|
| 7 | Repository Design | Persistence for aggregates | [repository-template.md](repository-template.md) |
|
|
| 8 | Service Design | Business logic | [service-layer-template.md](service-layer-template.md) |
|
|
| 9 | Specification Pattern | Reusable predicates / query specs | `app/specifications/` · service-layer template |
|
|
| 10 | Policy Layer | Authz, entitlement, domain policies | `app/policies/` · authorization architecture |
|
|
| 11 | Commands | State-changing use cases | `app/commands/` or explicit service command methods |
|
|
| 12 | Queries | Read use cases | `app/queries/` or explicit query services |
|
|
| 13 | REST APIs | Externalizable capabilities | [api-template.md](api-template.md) |
|
|
| 14 | Capability APIs | Platform/discoverable services | `/capabilities` |
|
|
| 15 | Health APIs | Every runnable service | `/health` |
|
|
| 16 | Metrics | Runnable services with ops surface | `/metrics` or justified N/A |
|
|
| 17 | Permission APIs / tree | Privileged operations | `{service}.*` · permission registration |
|
|
| 18 | OpenAPI Documentation | Any new/changed HTTP routes | FastAPI OpenAPI / exported schema |
|
|
| 19 | Validation Layer | Any input or domain rule | Pydantic + `app/validators/` |
|
|
| 20 | Pagination | Collection list endpoints | Shared page meta |
|
|
| 21 | Filtering | List endpoints with attributes | Query params + repository filters |
|
|
| 22 | Sorting | List endpoints | Stable sort keys documented |
|
|
| 23 | Searching | List endpoints with text find | Search params + indexed fields where needed |
|
|
| 24 | Soft Delete | Master/business records | [entity-template.md](entity-template.md) |
|
|
| 25 | Optimistic Locking | Concurrent update risk | Version/row version column |
|
|
| 26 | Audit Trail | State-changing business actions | Audit tables / audit service |
|
|
| 27 | Outbox Events | Cross-service-relevant changes | [event-template.md](event-template.md) · [ADR-006](../architecture/adr/ADR-006.md) |
|
|
| 28 | Tenant Isolation | All business data | [ADR-003](../architecture/adr/ADR-003.md) |
|
|
| 29 | Migration | Schema changes | Alembic in owning service only |
|
|
| 30 | Seed Data | Bootstrap/reference data required | Idempotent seeds documented |
|
|
| 31 | Background Jobs | Async/scheduled work in scope | Celery/worker pattern of the service |
|
|
| 32 | Configuration | Always for runtime services | Env / settings — no secrets in code |
|
|
| 33 | Feature Flags | Gated capabilities in scope | Entitlement / toggle pattern |
|
|
| 34 | Provider Interfaces | External systems | `app/providers/` protocols · [provider-registry.md](../provider-registry.md) |
|
|
| 35 | Dependency Injection | Always | Explicit FastAPI/deps or constructor injection |
|
|
| 36 | Unit Tests | Always when logic exists | [testing-template.md](testing-template.md) |
|
|
| 37 | Integration Tests | Always when APIs/flows exist | [testing-template.md](testing-template.md) |
|
|
| 38 | Architecture Tests | Service/module code phases | Boundary / layering tests |
|
|
| 39 | Security Tests | Privileged or tenant APIs | Authn/authz negatives |
|
|
| 40 | Performance Validation | Hot paths or lists | Indexes, N+1 guard, timing N/A justified |
|
|
| 41 | Documentation | Always | [documentation-template.md](documentation-template.md) |
|
|
| 42 | Self Audit | Always | [development-loop.md](development-loop.md) |
|
|
| 43 | Service Snapshot | Service-scoped phases on Complete | [service-snapshot-policy.md](service-snapshot-policy.md) · Project Index `snapshot_file` |
|
|
| 44 | Project Index Update | Service registration or phase Complete | [project-index.yaml](project-index.yaml) |
|
|
|
|
## Package Layout Expectation
|
|
|
|
For implementation phases inside a service, prefer (create when missing for in-scope work):
|
|
|
|
```
|
|
app/
|
|
api/v1/
|
|
commands/
|
|
queries/
|
|
policies/
|
|
specifications/
|
|
validators/
|
|
providers/
|
|
services/
|
|
repositories/
|
|
models/
|
|
schemas/
|
|
events/
|
|
permissions/
|
|
tests/
|
|
```
|
|
|
|
Existing services that use equivalent patterns (command methods on services, inline specs) may keep their style **if** responsibilities are equally covered and documented. New services should follow the layout above.
|
|
|
|
## N/A Rules
|
|
|
|
An artifact may be N/A only when:
|
|
|
|
1. The phase is documentation-only / registration-only, **or**
|
|
2. The artifact cannot apply inside the phase boundary (e.g. no list endpoints → Searching N/A), **and**
|
|
3. The phase doc or handover records the justification.
|
|
|
|
N/A is **never** allowed for Tenant Isolation, Documentation, Self Audit, Architecture Validation, Service Snapshot (when service-scoped), Project Index update (when service-scoped), or Definition of Done overall on implementation phases that touch business data.
|
|
|
|
## Related Documents
|
|
|
|
- [Project Index](project-index.yaml)
|
|
- [Service Snapshot Policy](service-snapshot-policy.md)
|
|
- [Enterprise Phase Discovery](enterprise-phase-discovery.md)
|
|
- [Definition of Done](definition-of-done.md)
|
|
- [Enterprise Completeness](enterprise-completeness.md)
|
|
- [Service Template](service-template.md)
|
|
- [Module Template](module-template.md)
|