docs: 建立规格追踪、端到端验收与发布门禁

README.md

@@ -609,6 +609,7 @@ MODEL_MODE=mock .venv\Scripts\python -m uvicorn app.main:app --host 0.0.0.0 --po
 - 部署规则（备份/回滚/冒烟）见根目录 `AGENTS.md`「部署到开发服务器」；SSH/SFTP 工具为 `scripts/devssh.py`（`PAN_SSH_PASS` 环境变量传密码）
 - 服务清单：Go 后端 :3000、Web :5174、ai-service :8000、recorder-go :9090、PostgreSQL :5432、IoTDB :18081、VerneMQ :1883、Ceph RGW :7480、WVP :18080、ZLM :8081
 - 可观测性：HTTP 请求统一 `X-Request-ID`；日志脱敏；`GET /api/v1/ops/metrics` 提供依赖指标；SLO/负载/备份恢复演练文档见 `docs/operations/`
+- 验收门禁：需求追踪、核心端到端用例和发布清单见 `docs/acceptance/`
 
 ## 13. Git 注意事项
 

docs/acceptance/core-e2e-cases.md

@@ -0,0 +1,62 @@
+# 核心端到端验收用例
+
+执行环境：开发服务器或隔离试点环境。每条用例记录：日期、执行人、环境、结果、失败原因、证据截图/日志。
+
+## E2E-01 healthy 图片不触发检测
+
+1. 使用真实或 mock healthy 图片上传巡检。
+2. 期望 `abnormalProbability=0`，风险不因 healthy 高置信度升高。
+3. 期望不创建待确认检测任务。
+
+## E2E-02 sick/橙色风险只创建一个待确认任务
+
+1. 上传产生橙色风险的非 mock 巡检。
+2. 等待 Outbox worker。
+3. 查询 `/detection-tasks?sourceType=inspection`，同巡检只出现一个任务。
+
+## E2E-03 AI 失败可重试且不产生虚假风险
+
+1. 停止 AI 服务后上传巡检。
+2. 期望 `aiStatus=failed`、无风险分。
+3. 恢复 AI 后重试，期望成功且使用同一幂等键不重复记录。
+
+## E2E-04 qPCR 无效不确诊
+
+1. 按当前规则录入无有效对照或无效结果。
+2. 期望 `result=invalid`，不创建 `DiseaseEvent`。
+
+## E2E-05 有效阳性创建发病事件并自动溯源
+
+1. LAMP 或统一检测任务录入 `positive`。
+2. 期望创建 `DiseaseEvent`。
+3. 期望自动创建关联 `TraceRecord`，状态为 `pending`。
+
+## E2E-06 无权用户访问受保护资源返回 403
+
+1. 使用无权限用户访问视频、设备控制、WebSocket 设备订阅。
+2. 期望业务接口 403，WebSocket 返回拒绝事件。
+
+## E2E-07 离线巡检重启后仅同步一次
+
+1. 断网拍照入队。
+2. 重启小程序。
+3. 联网后触发同步。
+4. 期望服务端仅一条记录，离线队列转为 `synced`。
+
+## E2E-08 通知失败重试且状态可查
+
+1. 制造微信/通道失败事件。
+2. 等待重试或最终失败。
+3. 期望 `notifications` 状态、尝试次数、错误可查询。
+
+## E2E-09 服务重启后任务/通知/吊销状态保持
+
+1. 创建 pending 事件、Outbox、token 吊销。
+2. 重启 Go 服务。
+3. 期望任务和通知继续处理，吊销仍生效。
+
+## E2E-10 备份恢复后核心记录与对象引用一致
+
+1. 按 `docs/operations/backup-restore-drill.md` 恢复。
+2. 核对巡检、检测、会诊、溯源、图片/光谱/录像引用。
+3. 记录 RPO/RTO 和失败项。

docs/acceptance/release-checklist.md

@@ -0,0 +1,31 @@
+# 发布门禁清单
+
+## 发布前
+
+- [ ] 确认发布基线 commit 和回滚点。
+- [ ] 执行 `powershell -ExecutionPolicy Bypass -File scripts/verify.ps1`，exit 0。
+- [ ] 执行 `git diff --check`，exit 0。
+- [ ] 涉及 schema 时完成 `pg_dump` 备份并记录恢复命令。
+- [ ] 检查磁盘、端口、服务进程和依赖健康。
+- [ ] 核对需求追踪矩阵：本次涉及的需求 ID 有实现、测试和限制说明。
+
+## 发布中
+
+- [ ] 保留旧二进制和旧 `dist`。
+- [ ] 上传新构建产物。
+- [ ] 执行数据库迁移。
+- [ ] 重启服务。
+- [ ] 健康检查和核心接口冒烟。
+
+## 发布后
+
+- [ ] 记录部署 commit、迁移版本、备份路径、冒烟结果。
+- [ ] 更新 `变更记录.md` 和 `开发交接记录.md`。
+- [ ] 执行核心端到端用例中受影响的 E2E。
+- [ ] 如失败，按回滚预案恢复并记录原因。
+
+## 回滚
+
+- 代码：恢复旧二进制/旧 dist 或 `git checkout <pre-commit>`。
+- 数据库：`pg_restore` 恢复备份。
+- 回滚后重新健康检查并记录结论。

docs/acceptance/requirements-traceability.md

@@ -0,0 +1,86 @@
+# 需求追踪矩阵
+
+追踪列：需求 ID、实现、自动测试、手工用例、环境、证据、状态、限制、负责人。
+
+状态约定：
+
+- `已实现`：代码和单元/构建证据存在，但未在目标环境完成最终验收。
+- `部分可用`：主链路可用，仍有明确限制。
+- `延后`：按决策暂不实施。
+- `未完成`：未实现或实现不足。
+
+## Wave 1：安全与正确性
+
+| 需求 ID | 实现 | 自动测试 | 手工用例 | 环境 | 证据 | 状态 | 限制 | 负责人 |
+|---|---|---|---|---|---|---|---|---|
+| IAM-001 | `handler/auth.go`、`middleware/token_blacklist.go` | `middleware/state_test.go` | 登录/刷新/登出/跨实例吊销 | 开发/生产 | `go test ./...` | 部分可用 | Redis 不可用时保守失败 | 后端 |
+| IAM-002 | `middleware/permission.go`、`permission_seed.go` | 无专项测试 | 角色访问矩阵 | 开发 | 路由权限检查 | 部分可用 | 缺少对象级 ACL | 后端 |
+| IAM-003 | 未完成 | 无 | 无 | 无 | 无 | 未完成 | 需组织/区域/房间 ACL | 后端 |
+| IAM-004 | 延后 Task 3 | 无 | 无 | 无 | 决策记录 | 延后 | 默认凭据和强制改密待最后阶段 | 后端+运维 |
+| AI-INS-002 | `service/risk.go`、`ai-service` | `risk_test.go`、AI pytest | healthy/sick 图片 | 本地 | verify.ps1 | 部分可用 | 真实模型未验收 | AI+后端 |
+| AI-INS-003 | `inspection.go`、`is_mock` | `inspection_test.go` | Mock 标识与统计排除 | 本地 | verify.ps1 | 部分可用 | 历史 mock 需人工审阅 | 后端 |
+| AI-INS-004 | `RiskAssessment` | `risk_test.go` | 风险解释展示 | 本地 | verify.ps1 | 部分可用 | 权重待试点校准 | 后端 |
+| AI-INS-005 | `offlineQueue.ts` | `offlineQueue.test.ts` | 离线→重启→联网 | 微信开发者工具 | miniapp test | 部分可用 | 未做截图取证 | 小程序 |
+| RISK-001 | `RiskLevel` | `risk_test.go` | 边界用例 | 本地 | go test | 已实现 | 无 | 后端 |
+| RISK-002 | `RiskInput` 指针 | `risk_test.go` | 缺失组件展示 | 本地 | go test | 已实现 | 无 | 后端 |
+| RISK-003 | `risk_assessment` | `risk_test.go` | 巡检详情 | 本地 | go test | 已实现 | 无 | 后端 |
+| RISK-004 | `risk-v2-2026.08.14` | 无 | 试点校准 | 待试点 | 无 | 部分可用 | 权重非科学结论 | 后端+专家 |
+| RISK-005 | 未完成 | 无 | 无 | 无 | 无 | 未完成 | 人工纠正等级 | 后端 |
+
+## Wave 2：工程可靠性
+
+| 需求 ID | 实现 | 自动测试 | 手工用例 | 环境 | 证据 | 状态 | 限制 | 负责人 |
+|---|---|---|---|---|---|---|---|---|
+| DET-001 | `detection_task.go` | `detection_task_test.go` | 任务中心 | 本地 | verify.ps1 | 部分可用 | 未端到端联调 | 后端 |
+| DET-002 | `sample.go` | `detection_task_test.go` | 样本流转 | 本地 | go test | 部分可用 | 单样本/任务 | 后端 |
+| DET-003 | `molecular.go` | `molecular_test.go` | 结果枚举 | 本地 | go test | 部分可用 | qPCR 四态延后 | 后端 |
+| DET-004 | 延后 Task 7 | 无 | 无 | 无 | 决策记录 | 延后 | 专家确认 | 后端+专家 |
+| DET-005 | `lamp.go` | `lamp_test_test.go` | LAMP 5 步 | 本地 | go test | 部分可用 | 对照/照片质控待完善 | 后端 |
+| DET-006 | `cross_validate.go` | `cross_validate_test.go` | 交叉验证 | 本地 | go test | 部分可用 | 真实数据待联调 | 后端 |
+| DET-007 | `detection_recommend.go` | `detection_recommend_test.go` | 推荐接口 | 本地 | go test | 部分可用 | 未绑定组织可用设备 | 后端 |
+| DET-008 | `consumable.go` | `consumable_test.go` | 耗材预警 | 本地 | go test | 部分可用 | 无批次/领用 | 后端 |
+| DET-009 | 未完成 | 无 | 无 | 无 | 无 | 未完成 | 设备回传协议 | 后端 |
+| DET-010 | 未完成 | 无 | 无 | 无 | 无 | 未完成 | LAMP 图像判读 | AI |
+| DET-011 | `spectrum_entries` | 无专项测试 | 光谱上传 | 本地 | 构建 | 部分可用 | 方法学验证未做 | AI |
+| MSG-001 | `outbox.go`、`notification.go` | `outbox_test.go` | 通知重试 | 本地 | verify.ps1 | 部分可用 | 未真实联调 | 后端 |
+| MSG-002 | `wechat.go`、outbox | `wechat_test.go` | 微信订阅 | 本地 | pytest/go test | 部分可用 | 缺真实凭证 | 后端 |
+
+## Wave 3：业务闭环
+
+| 需求 ID | 实现 | 自动测试 | 手工用例 | 环境 | 证据 | 状态 | 限制 | 负责人 |
+|---|---|---|---|---|---|---|---|---|
+| FARM-001 | `tray_batch.go` | `knowledge_seed_test.go` 等 | 蚕房/批次 CRUD | 本地 | go test | 已实现 | 无 | 后端 |
+| FARM-002 | `identity_links.go` | `biosecurity_test.go` | 二维码签发/解析 | 本地 | go test | 部分可用 | 未打印扫码 | 后端+小程序 |
+| FARM-003 | `rearing_records` | 无专项测试 | 饲养记录 | 本地 | go test | 部分可用 | 缺死亡/淘汰字段 | 后端 |
+| FARM-004 | `disinfection_records` | `biosecurity_test.go` | 消毒计划/执行 | 本地 | verify.ps1 | 部分可用 | 未现场联调 | 后端+小程序 |
+| FARM-005 | `seed_sources` | `biosecurity_test.go` | 种源链 | 本地 | go test | 部分可用 | 供应商凭证待接入 | 后端 |
+| FARM-006 | 未完成 | 无 | 无 | 无 | 无 | 未完成 | 产量/损失/成本 | 后端 |
+| ENV-001 | `telemetry.go`、`mqtt.go` | 无专项测试 | 遥测查询 | 开发 | 构建 | 已实现 | 数据质量标识不足 | 后端 |
+| ENV-002 | `threshold.go`、`alarm.go` | 无专项测试 | 阈值告警 | 开发 | 构建 | 已实现 | 无对象级授权 | 后端 |
+| ENV-003 | `rule_engine.go` | `rule_engine_test.go` | 过期数据 | 本地 | go test | 部分可用 | 未接入生产遥测 | 后端 |
+| ENV-004 | `rule_engine.go`、`weather_risk.go` | `rule_engine_test.go` | 连续时窗 | 本地 | go test | 部分可用 | 密度/通风等输入待接入 | 后端 |
+| ENV-005 | `rule_engine.go` | `rule_engine_test.go` | 规则解释 | 本地 | go test | 部分可用 | 结果持久化未全链路 | 后端 |
+| ENV-006 | 未完成 | 无 | 无 | 无 | 无 | 未完成 | 设备校准/维护 | 后端 |
+| ENV-007 | 未完成 | 无 | 无 | 无 | 无 | 未完成 | 安全控制建议 | 后端 |
+| EXP-001 | `consultation.go` | `consultation_test.go` | 病例快照 | 本地 | go test | 已实现 | 环境/天气摘要待增强 | 后端 |
+| EXP-002 | `consultation.go` | `consultation_test.go` | 会诊状态机 | 本地 | go test | 已实现 | 无 | 后端 |
+| EXP-003 | `ConsultationSLAState` | `consultation_test.go` | SLA 超时 | 本地 | go test | 部分可用 | 无升级通知 | 后端 |
+| EXP-004 | `consultation_opinion_versions` | `consultation_test.go` | 意见版本 | 本地 | go test | 已实现 | 无 | 后端 |
+| EXP-005 | `health_profile.go` effect | `health_profile_test.go` | 效果报告 | 本地 | go test | 部分可用 | 损失/成本缺失 | 后端 |
+| KB-001 | `knowledge.go` | `knowledge_governance_test.go` | 审核发布 | 本地 | go test | 部分可用 | 审核权限基于角色 | 后端+Web |
+| KB-002 | `knowledge.go` source 字段 | 无专项测试 | 来源展示 | 本地 | 构建 | 部分可用 | 专家签名待接入 | 后端 |
+| KB-003 | 未完成 | 无 | 无 | 无 | 无 | 未完成 | 案例沉淀 | 后端 |
+| TRACE-001 | `disease_events` | `disease_event_test.go` | 发病事件 | 本地 | go test | 部分可用 | 未端到端 | 后端 |
+| TRACE-002 | `trace.go` auto | 无专项测试 | 自动溯源 | 本地 | go test | 部分可用 | 空间/样本链不足 | 后端 |
+| TRACE-003 | `trace.go` checklist | 无专项测试 | 二级排查 | 本地 | go test | 部分可用 | 无版本化清单 | 后端 |
+| TRACE-004 | `trace.go` lab note | 无专项测试 | 三级溯源 | 本地 | go test | 部分可用 | 结构化实验室数据未做 | 后端 |
+| TRACE-005 | `trace.go` | `trace_test.go` | 来源结论 | 本地 | go test | 部分可用 | 专家确认流程未做 | 后端 |
+| TRACE-006 | `region_stat.go` | `region_stat_test.go` | 区域统计 | 本地 | go test | 部分可用 | 小样本脱敏未做 | 后端 |
+| TRACE-007 | `seed_sources` + 复发字段 | `biosecurity_test.go` | 复发关联 | 本地 | go test | 部分可用 | 人工确认未做 | 后端 |
+| VIDEO-001 | `video_auth.go` | `video_auth_test.go` | 播放授权 | 本地 | go test | 部分可用 | 对象级授权待后续 | 后端 |
+| VIDEO-002 | DTO 脱敏 | `video_dto.go` | 密钥不返回 | 本地 | go test | 部分可用 | 历史配置审计 | 后端 |
+| VIDEO-003 | 未完成 | 无 | 无 | 无 | 无 | 未完成 | 录制状态持久化 | 后端 |
+| VIDEO-004 | `stream_tasks.py` | AI pytest | 受限拉流 | 本地 | pytest | 部分可用 | 摄像头真实视角待接入 | AI |
+| ANA-001 | `health_profile.go` | `health_profile_test.go` | 健康画像 | 本地 | go test | 部分可用 | 公式未回测 | 后端 |
+| ANA-002 | `health_profile.go` effect | `health_profile_test.go` | 效果评估 | 本地 | go test | 部分可用 | 损失/成本缺失 | 后端 |
+| ANA-003 | `region_stat.go` | `region_stat_test.go` | 区域图 | 本地 | go test | 部分可用 | 地图/脱敏未做 | 后端 |

后续工作计划.md

@@ -1,6 +1,6 @@
 # 后续工作计划
 
-> **完成状态（2026-08-14 更新）**：#5-#24、#27 已完成，Task 0/1/2/4/5/6/8/9/10/11/12/13 整改代码完成（详见 `开发交接记录.md`）；#1-4 因物理机问题挂起；#23/#26 骨架完成；Task 3/7 延后到最后处理；微信/天气真实数据待凭证。
+> **完成状态（2026-08-14 更新）**：#5-#24、#27 已完成，Task 0/1/2/4/5/6/8/9/10/11/12/13/14 整改代码/验收文档完成（详见 `开发交接记录.md`）；#1-4 因物理机问题挂起；#23/#26 骨架完成；Task 3/7 延后到最后处理；微信/天气真实数据待凭证。
 
 ## 整改实施计划 Wave 0-4（2026-08-13 启动）
 
@@ -22,7 +22,7 @@
 | Wave 3 | 业务闭环 | Task 11 实现小程序离线巡检与可靠同步 | 部分可用 | 待开发服务器迁移部署与开发者工具离线/重启联调 |
 | Wave 3 | 业务闭环 | Task 12 完善环境规则、会诊治理、知识审核与效果评估 | 部分可用 | 待开发服务器迁移部署与专家/试点联调 |
 | Wave 4 | 验收与发布 | Task 13 建立可观测性、容量与恢复验证 | 部分可用 | 待真实环境负载/备份恢复演练与告警通道联调 |
-| Wave 4 | 验收与发布 | Task 14 建立规格追踪、端到端验收与发布门禁 | 未开始 | 无 |
+| Wave 4 | 验收与发布 | Task 14 建立规格追踪、端到端验收与发布门禁 | 部分可用 | 待目标环境执行 E2E、真实发布与恢复演练 |
 
 ## 技术选型决策（2026-08-11 确定）
 

开发交接记录.md

@@ -1147,3 +1147,31 @@ MVP 沿用 IoTDB（现状）；TDengine 作为生产规模化候选（先基准
 - 本任务前分支提交为 `126c215`；回滚可还原 Task 13 提交；
 - requestId/日志脱敏可安全保留；若指标采集开销过高，可降低采样频率；
 - 运维文档和部署指南可直接保留，不删除已记录的恢复演练要求。
+
+## 2026-08-14 整改 Task 14：建立规格追踪、端到端验收与发布门禁
+
+### 做了什么
+
+- 新增 `docs/acceptance/requirements-traceability.md`：Wave 1～3 需求 ID 到实现、测试、手工用例、环境、证据、状态、限制和负责人的追踪表；
+- 新增 `docs/acceptance/core-e2e-cases.md`：覆盖 healthy 不触发、橙色仅一个任务、AI 失败重试、无效不确诊、阳性发病事件、越权 403、离线同步、通知重试、重启保持、备份恢复共 10 条核心用例；
+- 新增 `docs/acceptance/release-checklist.md`：发布前、发布中、发布后和回滚门禁；
+- `蚕病智能防控平台规格说明书_V2.2.md` 第 12 章增加验收文档入口和近期整改能力行；
+- `scripts/verify.ps1` 已在 Task 11 起纳入小程序单测，作为当前可复现质量门禁。
+
+### 设计思路与决策依据
+
+- 追踪矩阵不允许只写模块名，每行必须能回溯到实现、测试、环境、证据、限制和负责人；
+- E2E 用例先固定核心业务闭环，目标环境执行后再更新结果，不把“已编写”当“已验证”；
+- 发布门禁要求先备份、再部署、后回滚验证，和 AGENTS.md 的服务器发布规则保持一致。
+
+### 验证结果
+
+- `scripts/verify.ps1` exit 0：Go test/vet/build、Web test/lint/build、小程序 test/typecheck/build、APP typecheck/lint、AI pytest 15/15 均通过；
+- `git diff --check` 通过；
+- 未在目标环境执行 E2E-01～10，未完成真实发布和备份恢复演练。
+
+### 回滚点
+
+- 本任务前分支提交为 `1e6a5db`；回滚可还原 Task 14 提交；
+- 本次仅新增/修改验收文档和规格书状态说明，无代码、数据库或生成产物变更；
+- 如需回滚，删除 `docs/acceptance/` 并恢复规格书第 12 章及计划/交接文档即可。

蚕病智能防控平台规格说明书_V2.2.md

@@ -560,6 +560,8 @@ Organization
 
 ## 12. 当前状态追踪矩阵
 
+> 需求级追踪矩阵见 `docs/acceptance/requirements-traceability.md`；发布前必须执行 `docs/acceptance/core-e2e-cases.md` 和 `docs/acceptance/release-checklist.md`。
+
 | 能力 | 当前状态 | 阻断项 | 目标阶段 |
 |---|---|---|---|
 | 环境/设备/告警 | 部分可用 | 数据质量、对象权限、校准 | B/C |
@@ -571,6 +573,11 @@ Organization
 | SERS | 文件录入骨架 | 设备、算法、方法验证 | C/E |
 | 高光谱 | 接口预留 | 数据、算法、方法验证 | E |
 | 专家会诊 | 表单流程部分可用 | SLA、版本、可靠通知 | C |
+| 统一检测任务/样本/发病事件 | 部分可用 | 未端到端联调、真实模型 | C |
+| 生物安全（种源/消毒/二维码） | 部分可用 | 真实二维码/现场扫码联调 | C |
+| 小程序离线巡检 | 部分可用 | 离线→重启→联网截图取证 | C |
+| 会诊治理/知识审核/效果评估 | 部分可用 | 专家与试点联调 | C |
+| 可观测性/容量/恢复 | 基线可用 | 真实负载、恢复演练、告警通道 | B/C |
 | 疫病溯源 | v1 规则部分可用 | DiseaseEvent、种源/样本/空间链 | C |
 | 微信/天气 | 骨架 | 真实凭证和目标环境联调 | C |
 | 摄像头 AI | 骨架 | 安全任务调度、视角数据、模型 | E |