aios/docs/aios-v2/05-TRACEABILITY-MATRIX.md

AIOS V2 需求—架构—代码—测试—部署追踪矩阵

• 文档版本：V2R1C0-candidate
• 目的：确保每项用户需求都能追踪到架构设计、代码实现、自动测试、部署资产和验收命令

1. 追踪规则

每条需求至少具备：

1. 需求编号；
2. 架构章节；
3. 实现路径；
4. 测试路径；
5. 部署/运维资产；
6. 验收状态。

状态定义：

• Implemented：代码已进入 Candidate 分支；
• Test-defined：测试代码已进入 Candidate 分支；
• Test-verified：精确 commit 的测试已运行并保存证据；
• Pre-production verified：预发布部署、健康检查和回滚演练已通过；
• Production released：Owner 批准并完成 merge/tag/deploy。

2. 核心追踪矩阵

需求	设计依据	代码实现	测试	部署/运维	当前状态
UR-001 AIOS 唯一控制面	02-TARGET-ARCHITECTURE.md §3.2/§3.3；ADR-001	aios_v2/control_plane.py、aios_v2/orchestrator.py、aios_v2/app.py	tests/aios_v2_candidate/test_candidate_flow.py	deploy/aios-v2/systemd/aios-v2.service	Implemented / Test-defined
UR-002 复用现有能力	02-TARGET-ARCHITECTURE.md §2；03-MIGRATION-AND-DELIVERY.md §2	aios_openclaw/、aios_hermes/	OpenClaw/Hermes flow tests	Candidate branch + adapter boundaries	Implemented / Test-defined
UR-003 OpenClaw/Hermes 解耦	02-TARGET-ARCHITECTURE.md §3.4/§3.5；ADR-002	aios_openclaw/adapter.py、aios_hermes/adapter.py	runtime boundary tests in candidate flow suite	systemd/Docker runtime configuration	Implemented / Test-defined
UR-004 全面 Web 化	02-TARGET-ARCHITECTURE.md §3.1/§8	aios_v2/console.py、aios_v2/gateway.py、aios_v2/app.py	API/console smoke test pending	Docker/systemd + reverse proxy requirement	Implemented / Test pending
UR-005 多租户隔离	02-TARGET-ARCHITECTURE.md §4；ADR-004	control_plane.py、orchestrator.py、aios_openclaw/*、aios_hermes/*、execution_tracking.py	test_cross_tenant_task_read_is_denied	tenant-scoped state/evidence directories	Implemented / Test-defined
UR-006 权威任务生命周期	04-MODULE-CONTRACTS.md §4	control_plane.py	OpenClaw/Hermes full-flow tests	persisted state + audit	Implemented / Test-defined
UR-007 策略与审批	04-MODULE-CONTRACTS.md §5	control_plane.py、gateway.py	role/policy negative tests需补充	reverse proxy identity + audit	Implemented / Partial test
UR-008 幂等与并发安全	02-TARGET-ARCHITECTURE.md §7	control_plane.py、aios_openclaw/adapter.py、aios_hermes/adapter.py、worker.py	flow + restart tests；并发专项测试需补充	GitOps detached guard + SQLite WAL	Implemented / Partial test
UR-009 执行证据	04-MODULE-CONTRACTS.md §9	execution_tracking.py	test_execution_tracking_persists_claim_heartbeat_and_result	/var/lib/aios-v2/executions	Implemented / Test-defined
UR-010 GitOps 唯一变更流程	03-MIGRATION-AND-DELIVERY.md §4/§5；ADR-003	GitOps Runtime、gitops_status.py	healthcheck 的 detached/clean 检查	deploy/aios-v2/healthcheck/check.sh	Implemented / Runtime verified partially
UR-011 持久化与恢复	02-TARGET-ARCHITECTURE.md §3.6	persistence.py	test_durable_service_recovers_state_after_restart	state dir + backup/rollback	Implemented / Test-defined
UR-012 审计与合规	04-MODULE-CONTRACTS.md §6	control_plane.py、aios_openclaw/callback.py、app.py	flow test + audit assertions需补充	Console audit view	Implemented / Partial test
UR-013 密钥安全	02-TARGET-ARCHITECTURE.md §6；ADR-006	FileSigningMaterialResolver、credential refs、Secret Gate	permission/secret-scan test需补充	env template + external protected file	Implemented / Partial test
UR-014 部署与回滚	03-MIGRATION-AND-DELIVERY.md §7	deployment scripts/assets	acceptance runner + healthcheck	deploy/aios-v2/	Implemented / Pre-prod pending
UR-015 文档与代码同步	03-MIGRATION-AND-DELIVERY.md §9；ADR-005	tools/aios_v2_docs_code_check.py	checker self-test / acceptance runner	CI/Gitea Actions 可调用	Implemented after checker commit

3. API 追踪

API	需求	实现	测试状态
GET /api/v2/health	UR-004, UR-014	gateway.py	healthcheck 定义完成
POST /api/v2/tenants	UR-001, UR-005	gateway.py / control_plane.py	需增加 HTTP 集成测试
POST /api/v2/agents	UR-001, UR-005	gateway.py / control_plane.py	Domain flow 已覆盖
POST /api/v2/tasks	UR-006, UR-008	gateway.py / control_plane.py	Domain flow 已覆盖
POST /api/v2/tasks/{id}/approve	UR-006, UR-007	gateway.py	Domain flow 已覆盖
POST /api/v2/tasks/{id}/dispatch	UR-001, UR-003	app.py / orchestrator.py	OpenClaw/Hermes flow 已覆盖
GET /api/v2/runtime	UR-004, UR-009	app.py	HTTP smoke test待执行
GET /api/v2/executions	UR-009	app.py / execution_tracking.py	Evidence persistence test已定义
GET /api/v2/gitops	UR-010	app.py / gitops_status.py	Runtime/healthcheck验证待执行
POST /api/v2/hermes/results/reconcile	UR-003, UR-006	app.py / orchestrator.py	Hermes flow已覆盖 Domain 路径

4. 运行时契约追踪

契约	设计	代码	测试
OpenClawCommand	04-MODULE-CONTRACTS.md §7.1	aios_openclaw/contract.py	OpenClaw full-flow；签名负向测试需补充
OpenClawResult	§7.2	aios_openclaw/contract.py	OpenClaw full-flow
RuntimeHealth	§7.3	aios_openclaw/contract.py、health.py	health policy测试需补充
HermesJob	§8.1	aios_hermes/contract.py	Hermes full-flow
HermesResult	§8.2	aios_hermes/contract.py	Hermes full-flow
HermesHealth	§8.3	aios_hermes/contract.py、adapter.py	healthcheck/worker test待执行
ExecutionEvidence	§9	execution_tracking.py	evidence persistence test
GitOpsStatus	§10	gitops_status.py	healthcheck detached/clean检查

5. 部署追踪

能力	文件	验收命令
systemd	deploy/aios-v2/systemd/aios-v2.service	systemctl status aios-v2
环境模板	deploy/aios-v2/env/aios-v2.env.example	systemd-analyze verify + 文件权限检查
Docker	deploy/aios-v2/docker/Dockerfile	docker build
Compose	deploy/aios-v2/docker/compose.yaml	docker compose config / up
健康检查	deploy/aios-v2/healthcheck/check.sh	直接执行
回滚	deploy/aios-v2/rollback/rollback.sh	预发布回滚演练
全量验收	deploy/aios-v2/acceptance/run-all.sh	直接执行

6. 文档覆盖追踪

文档	覆盖内容	代码/变更触发条件
README.md	事实源索引、状态语言、实现地图	新模块/目录/版本
01-USER-REQUIREMENTS.md	用户需求、NFR、验收场景	用户行为、功能范围、验收变化
02-TARGET-ARCHITECTURE.md	分层、边界、数据流、安全、租户	架构边界、数据流、运行时变化
03-MIGRATION-AND-DELIVERY.md	迁移、GitOps、Gate、回滚	发布流程、迁移阶段、门禁变化
04-MODULE-CONTRACTS.md	字段、API、状态机、错误语义	Contract/API/模型变化
05-TRACEABILITY-MATRIX.md	需求到代码测试部署映射	代码、测试、部署路径变化
adr/*	关键不可逆或跨模块决策	新架构决策或旧决策替换

7. 当前未完成验证项

以下项目代码或测试定义已存在，但尚不能标记为 Test-verified 或 Pre-production verified：

1. 精确 Candidate commit 的测试执行结果；
2. HTTP API 与 Web Console 冒烟测试；
3. 真实 OpenClaw Runtime 签名、取消、超时和健康联调；
4. Hermes 长任务心跳、Worker 崩溃和 Lease 恢复演练；
5. 多实例 SQLite/并发容量边界；
6. systemd、Docker、Compose、restart 和 rollback 演练；
7. local/Gitea Candidate OID 一致证明；
8. 生产身份代理、防伪 Header、CSRF/CORS/Rate Limit 验证；
9. 文档—代码同步检查器在 CI/Acceptance 中执行通过。

8. 更新要求

任何代码、API、部署或测试路径变化，必须同步更新本矩阵。验收脚本会检查本文档引用的关键路径存在，并检查架构/功能代码变化是否同时包含 docs/aios-v2/ 变化。