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

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 | 部分可用 | 地图/脱敏未做 | 后端 |