# Service Dependency Matrix

本文件说明 `.service-matrix/dependencies.yaml` 的维护口径。它是多服务、多仓库、IDL / API 契约或外部系统集成项目的可选 truth source；单体、小型前端或一次性脚本可以标记为 `not_applicable`。

## 适用条件

满足任一条件时，应启用服务依赖矩阵：

- 一个需求会修改或影响多个服务、包、仓库、worker、前端应用或脚本入口。
- 涉及 OpenAPI、protobuf、GraphQL schema、数据库 schema、消息事件、文件格式或第三方 API 契约。
- 需要确认上游调用方、下游依赖方、灰度、回滚、兼容性或分支一致性。
- 过去出现过“AI 只改了局部代码但漏掉调用链 / 契约 / 下游影响”的返工。

## 维护原则

- 矩阵只记录稳定拓扑和契约事实，不记录一次性任务过程。
- 不把矩阵写成项目百科；每条依赖必须能回答“谁依赖谁、通过什么契约、变更时检查什么”。
- 如果依赖需要人工确认，写 `status: needs-confirmation`，不得让实现任务继续猜。
- 如果某个项目不需要矩阵，在 `docs/architecture/constraints.md` 中写明 `service_matrix: not_applicable`。

## 最小字段

| 字段 | 说明 |
| --- | --- |
| `service_id` | 稳定服务、应用、包、worker 或集成名 |
| `repo_path` | 当前项目内路径或外部仓库标识 |
| `entrypoints` | HTTP route、CLI command、worker、UI route、package export 等公开入口 |
| `contracts` | OpenAPI、protobuf、GraphQL、typed API、schema、event、file format 或 `none` |
| `upstream` | 调用本服务 / 包 / 入口的上游 |
| `downstream` | 本服务 / 包 / 入口调用的下游 |
| `change_gates` | 变更前必须通过的契约、分支、兼容性、灰度或回归检查 |
| `owner` | 维护 owner 或确认人 |
| `status` | `active` / `draft` / `needs-confirmation` / `deprecated` / `not_applicable` |

## Driver 使用方式

- `ANALYSIS` 阶段识别本轮需求是否需要服务矩阵；需要时补齐 `.service-matrix/dependencies.yaml`。
- `PLAN` 阶段把受影响服务、契约和 change gates 映射到每个 `feature_impl` 的 `context_files`、`architecture_constraints`、`qa_contract` 和 `test_command`。
- `feature_impl` 阶段不得新增未声明的跨服务影响；发现矩阵缺失或不可信时输出 `BLOCKED`。
- `release` 阶段必须验证跨服务主链路、契约/API、失败态和回写证据。

## Review 口径

Stage 1 先检查矩阵是否足以支撑实现计划：

- 受影响服务是否都已列出。
- 上下游、契约、分支或版本约束是否明确。
- 是否有未确认依赖被实现任务当成已确认事实。
- 验证命令是否覆盖矩阵中的 change gates。

Stage 2 再检查代码是否真的遵守矩阵：

- 公开入口、契约、实现、测试和证据是否一致。
- 是否漏改下游调用、mock、生成代码、schema 或配置。
- 失败、回滚、兼容性和灰度路径是否有证据。
