# Architecture Constraints Packet

本文件在需求分析结束、进入计划或编码前完成。它把“系统应该是什么形态”转成可执行约束，供 `task.json`、Stage 1 Review 和验证命令使用。

默认路径是 `docs/architecture/constraints.md`。项目可以在 `task.json.runtime.handoff.truth_sources.architecture` 中改用其他路径，但后续任务、prompt 和 review 必须读取同一组 truth source。

## 1. System Shape

- `delivery_shape`: `web_app` / `backend_service` / `monolith` / `frontend_app` / `cli` / `library` / `automation` / `data_pipeline` / `domain_prototype` / `other:<name>`
- `runtime_model`: `http_service` / `worker` / `scheduled_job` / `static_site` / `embedded_library` / `command` / `not_applicable`
- `deployment_unit`: `container` / `single_process` / `serverless` / `package` / `static_assets` / `not_applicable`
- `production_entrypoints`: 列出当前项目真实启动入口、公开命令、页面入口、worker entry、package export、Dockerfile 或 `not_applicable`。

## 2. Public Interface Boundary

- `public_interfaces`: `HTTP` / `gRPC` / `GraphQL` / `MQ` / `CLI` / `UI route` / `package API` / `file format` / `none`
- `contract_source`: `OpenAPI` / `protobuf` / `GraphQL schema` / `existing API` / `typed API` / `docs` / `not_applicable`
- `interface_trace_rule`: 每个公开入口应能追踪到实现、测试和证据路径；没有公开入口时写明 `not_applicable`。

## 2.1 Service And Contract Topology

多服务、多仓库、契约或外部系统项目必须声明服务拓扑；不适用时写明 `service_matrix: not_applicable`。

- `service_matrix`: `.service-matrix/dependencies.yaml` / `not_applicable` / `project_defined:<path>`
- `affected_services`: 本轮需求会修改或影响的服务、应用、包、worker、前端入口或外部系统。
- `upstream_downstream_rule`: 说明上游调用方和下游依赖方如何确认；不能只依赖代码搜索。
- `contract_branch_rule`: IDL、OpenAPI、schema、generated code 或外部契约是否需要同分支、同版本或兼容性证明。
- `change_gate_rule`: 对应 contract diff、consumer test、integration test、mock 更新、灰度或回滚检查。

## 3. Data Boundary

- `persistence_boundary`: `MySQL` / `PostgreSQL` / `SQLite` / `Redis` / `object_storage` / `filesystem` / `browser_storage` / `external API` / `none`
- `schema_or_migration_required`: `yes` / `no` / `not_applicable`
- `historical_data_strategy`: 旧数据如何兼容、回填、默认值和发布窗口；不适用写 `not_applicable`
- `migration_rollback_strategy`: migration 如何回滚、降级或 feature flag 切换；不适用写 `not_applicable`
- `repository_policy`: 说明声明交付路径使用的真实数据边界；测试替身、fixture、mock adapter 或 local-only adapter 只能用于声明允许的范围。
- `consistency_requirements`: 事务、锁、幂等键、唯一约束、审计保留、缓存失效、离线同步或 `not_applicable`。

## 4. Async And Worker Boundary

- `async_required`: `yes` / `no`
- `scheduling_model`: `DB polling` / `MQ consumer` / `cron` / `event bus` / `browser event` / `manual command` / `none`
- `concurrency_control`: `DB row lock` / `optimistic CAS` / `distributed lock` / `single process` / `browser single-thread` / `none`
- `time_source`: `database time` / `server time` / `event time` / `browser time` / `not_applicable`

## 4.1 Backend Layering And Error Boundary

如果项目包含后端服务、BFF、worker API 或命令式写路径，至少补齐：

- `controller_policy`: Controller / Handler 只负责请求解析、权限入口、调用 service、响应映射；不堆业务规则。
- `service_policy`: Service 负责业务逻辑、事务编排、幂等和副作用协调；不得直接依赖 `req/res/ctx/request/response`。
- `repository_policy_detail`: Repository / DAO 负责数据库访问、查询组合和持久化边界；不返回页面展示字段。
- `dto_policy`: DTO / Request / Response / Entity 的边界和禁止混用规则。
- `error_handling_policy`: 全局异常处理、错误码模型、用户可见错误、日志保留策略。
- `transaction_boundary`: 哪些写路径必须事务化，哪些步骤不得跨外部调用长持锁。
- `idempotency_policy`: 哪些入口必须幂等，幂等键放在哪里，重复请求返回什么。

## 5. Test Double Policy

- `test_double_allowed_scope`: `unit_tests_only` / `contract_tests` / `local_demo` / `domain_prototype` / `not_allowed` / `project_defined:<rule>`
- `mock_as_acceptance_evidence`: `no` by default；如果允许，必须写明原因、适用依赖、过期条件和替代真实验证计划。
- `minimum_integration_evidence`: 列出当前项目最低真实验证组合，例如 UI + API、API + DB、CLI + filesystem、package API + consumer test、worker + queue，或 `not_applicable`。

## 6. Forbidden Implementations

按项目填充，不要只写抽象原则。示例只作为选项，不代表所有项目都适用：

- 不允许只实现领域 service 而没有任务声明的公开入口。
- 不允许公开契约有 operation 但代码没有对应实现或验证。
- 不允许用测试替身、mock、fixture、local-only adapter 冒充声明交付路径。
- 不允许把 `domain_prototype` 标记为可交付功能完成。
- 不允许只运行 `git diff --check` 就声明 `feature_impl` 完成。

## 7. Architecture Fitness Checks

每个项目至少定义一个可运行或可审查的架构适配检查，并把命令或检查项同步到 `task.json` 的 `test_command`。

```powershell
<replace-with-project-fitness-check>
```

若暂时没有脚本，必须在 `docs/testing/verify-matrix.md` 写明等价检查项。可选检查包括：

- 声明的生产入口存在，且能被启动、导入、访问或执行。
- 公开接口与实现、测试和证据路径可追踪。
- 声明交付路径未引用禁止的测试替身。
- 需要持久化、worker、浏览器、文件或第三方服务时，存在对应的真实验证证据。
- 不适用的边界已明确标记为 `not_applicable`，而不是留空。

## 8. Definition Of Done

- `architecture_constraints` 已从本文件或等价 truth source 复制到每个相关 `feature_impl` 任务。
- 多服务、多仓库或契约任务已把服务矩阵、受影响服务和 change gates 复制到相关 `feature_impl` 的 `context_files`、`architecture_constraints`、`qa_contract` 和 `test_command`。
- `forbidden_implementations` 已覆盖当前项目最容易跑偏的替代实现。
- `test_command` 包含项目适配检查、affected tests、必要契约/集成/端到端验证和 `git diff --check`。
- Stage 1 Review 对声明的架构形态给出 PASS。
- 完成声明能说明声明交付路径、测试替身和不适用边界。
