From 1b8cab19df9ec27e3b3bb695c9d919ad994fb36c Mon Sep 17 00:00:00 2001 From: weijuesen Date: Thu, 13 Aug 2026 22:03:03 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E6=95=B4=E6=94=B9=E5=9F=BA=E7=BA=BF=EF=BC=88=E8=A7=84=E6=A0=BC?= =?UTF-8?q?=E4=B9=A6=20V2.2=E3=80=81=E7=8E=B0=E7=8A=B6=E5=88=86=E6=9E=90?= =?UTF-8?q?=E3=80=81=E5=AE=9E=E6=96=BD=E8=AE=A1=E5=88=92=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 开发交接记录.md | 82 +++ 蚕病智能防控平台规格说明书_V2.2.md | 593 +++++++++++++++++++ 项目整改实施计划_V1.0.md | 914 +++++++++++++++++++++++++++++ 项目现状与规格说明书优化分析.md | 404 +++++++++++++ 4 files changed, 1993 insertions(+) create mode 100644 蚕病智能防控平台规格说明书_V2.2.md create mode 100644 项目整改实施计划_V1.0.md create mode 100644 项目现状与规格说明书优化分析.md diff --git a/开发交接记录.md b/开发交接记录.md index 357dfd7..6f61351 100644 --- a/开发交接记录.md +++ b/开发交接记录.md @@ -661,3 +661,85 @@ MVP 沿用 IoTDB（现状）；TDengine 作为生产规模化候选（先基准 - 环境监测 + LAMP：#12 天气接入、#14 LAMP 检测管理、#15 交叉验证、#16 耗材管理、#17 技术员后台； - 专家诊断 + 溯源：#18 专家会诊、#19 qPCR/SERS/高光谱、#21 疫病溯源、#22 区域热力图、#23 摄像头流巡检； - 数据分析与运维：#24 健康画像、#25 时序存储决策、#26 GPU 监控、#27 测试基建。 + +--- + +## 2026-08-13 项目现状与规格说明书优化分析 + +### 做了什么 + +- 对照 `.cc-connect/attachments/蚕病智能防控平台规格说明书.md` V2.1，抽查 Go 后端、Web、小程序、APP、ai-service、测试和运维文档； +- 新增 `项目现状与规格说明书优化分析.md`，包含执行摘要、功能现状矩阵、规格书 V2.2 修订建议、P0/P1/P2 问题清单、分阶段优化路线图和新增功能建议； +- 识别到风险评分语义、公开视频流/密钥返回、默认凭据、迁移容错、qPCR 空 Ct 判读和小程序类型错误等高优先级问题；本次只分析和记录，未修改业务代码或部署环境。 + +### 设计思路与决策依据 + +- 采用“规格—实现—路线图”综合评审结构，把已实现、骨架/mock、手工录入、接口预留和真实联调分开，避免用单一完成勾选误导验收； +- 先以代码和本地命令为事实依据，再给出建议；codebase-memory 图谱接口在当前会话不可用，已在报告中披露并回退到目标源码核查； +- 优先级以数据/隐私暴露、业务错误传播范围、生产恢复难度和核心闭环阻断程度确定，新增功能排在安全与正确性基线之后。 + +### 验证结果 + +- `server-go`: `go test ./...`、`go vet ./...` 通过； +- `web`: `npm test` 3/3 通过，`npm run lint` 通过但有 5 个 warning； +- `ai-service`: 本机缺 fastapi/Pillow，pytest 收集失败； +- `app`: 本机目录缺 tsc/eslint 可执行依赖，类型与 lint 未运行成功； +- `miniapp`: `npx tsc --noEmit` 发现 dashboard 两处 TS1382； +- 未连接开发服务器或外部依赖，未做生产联调、渗透、负载、恢复或真实模型验收。 + +### 回滚点 + +- 本交付仅新增 `项目现状与规格说明书优化分析.md` 并追加本节；回滚时删除新增文档并移除本节即可，无数据库、配置、构建产物或服务器变更。 + +--- + +## 2026-08-13 规格说明书 V2.2 与整改实施计划 + +### 做了什么 + +- 新增 `蚕病智能防控平台规格说明书_V2.2.md`：对齐当前 Go + Python 混合架构，增加能力七态、稳定需求 ID、业务异常流程、数据/API/AI/安全/非功能规范、阶段退出条件和开放决策； +- 新增 `项目整改实施计划_V1.0.md`：把阶段 A～C 拆为 15 个可独立评审任务，列出负责人、涉及文件、接口、TDD 步骤、验证命令、依赖顺序和回滚方法； +- 近期整改聚焦安全、业务正确性、迁移/CI/可靠消息、检测与发病主链、消毒/种源、离线同步和运维验收；真实多病种模型、摄像头群体 AI、SERS/高光谱等研究项明确延后。 + +### 设计思路与决策依据 + +- 规格书区分“目标能力、当前状态、验收证据”，不再以存在页面/接口等同于功能完成； +- 风险评分、检测判读、视频/密钥安全和 schema 一致性列为 Wave 1，业务扩展必须在 P0 关闭后进入； +- 对未获确认的迁移工具、CI 平台、云服务、数据保留期、APP 范围和 qPCR 专业规则只设置决策门，不擅自选型； +- 整改任务按 TDD、小步迁移、功能开关、幂等、可观测和可回滚设计，便于多同事分工执行。 + +### 验证结果 + +- 两份文档已执行标题结构、需求 ID、任务编号、占位符、路径引用和 Markdown diff 检查； +- 本次仅创建文档并追加交接记录，没有修改业务代码、依赖、数据库、生成产物或服务器； +- 文档中的命令属于后续整改验收步骤，本次未宣称相应功能已经修复或测试通过。 + +### 回滚点 + +- 删除 `蚕病智能防控平台规格说明书_V2.2.md`、`项目整改实施计划_V1.0.md` 并移除本节即可；原 V2.1 附件、业务代码、数据库和部署环境均未改动。 + +--- + +## 2026-08-13 codebase-memory 索引生成 + +### 做了什么 + +- 使用本机已安装的 codebase-memory-mcp v0.10.2（`C:\Users\Administrator\AppData\Local\Programs\codebase-memory-mcp\codebase-memory-mcp.exe`）对仓库 `D:\silk-master-84e4ddc` 执行 `index_repository`，生成知识图谱索引：3409 节点、10351 边，状态 ready； +- 当前 Codex `config.toml` 原先缺少 `codebase-memory-mcp` 的 MCP 服务配置，已补上 `[mcp_servers.codebase-memory-mcp]` 条目并验证 `codex mcp list` 显示 enabled；原配置备份为 `C:\Users\Administrator\.codex\config.toml.cbm-bak-20260813-213259`。 + +### 设计思路与决策依据 + +- 索引存放在 codebase-memory-mcp 本地缓存（`C:\Users\Administrator\.cache\codebase-memory-mcp`），仓库内 `.codegraph` 仅为忽略规则占位，不提交业务产物； +- 通过官方 CLI 直接索引，不依赖当前会话是否已加载 MCP 工具，便于后续用 `search_graph`/`trace_path` 等图谱接口查询。 + +### 验证结果 + +- `list_projects`：项目 `D-silk-master-84e4ddc` 已登记（branch `dev_wjs`，3409 节点、10351 边）； +- `index_status`：status ready；24 个文件存在局部解析缺口（多为 SCSS/少量 TSX 行），84 个文件按设计排除（gitignore/构建产物/二进制资源），非索引失败； +- `search_graph`：按 `.*Handler.*` 查询返回 5 条结果，图谱查询可用； +- `codex mcp list`：`codebase-memory-mcp` 与 `node_repl` 均 enabled。 + +### 回滚点 + +- 删除索引：`codebase-memory-mcp cli delete_project '{"project":"D-silk-master-84e4ddc"}'`； +- 恢复 Codex 配置：用备份 `config.toml.cbm-bak-20260813-213259` 覆盖 `config.toml` 即可；本次未改业务代码、数据库或服务器。 diff --git a/蚕病智能防控平台规格说明书_V2.2.md b/蚕病智能防控平台规格说明书_V2.2.md new file mode 100644 index 0000000..b8baa4e --- /dev/null +++ b/蚕病智能防控平台规格说明书_V2.2.md @@ -0,0 +1,593 @@ +# 蚕病智能防控平台规格说明书 + +**版本：V2.2** +**日期：2026年8月13日** +**状态：整改与试点验收基线** +**适用项目：智慧蚕房环境监测与智能调控系统** + +--- + +## 0. 文档控制 + +### 0.1 编写目的 + +本规格说明书定义平台当前架构、目标能力、需求边界、数据与接口约束、AI 治理、安全要求和分阶段验收标准，作为产品设计、研发、测试、部署、试点和项目评审的共同基线。 + +本版重点解决 V2.1 中“目标设想、当前实现、接口骨架和已验收能力混写”的问题。任何功能只有满足本文件定义的验收证据后，才能标记为“已验证”。 + +### 0.2 依据文件 + +- `.cc-connect/attachments/蚕病智能防控平台规格说明书.md`（V2.1） +- `项目现状与规格说明书优化分析.md` +- `README.md` +- `后续工作计划.md` +- `开发交接记录.md` +- `物联网设备接口和数据格式.md` +- `部署指南(物理机).md` + +### 0.3 能力状态定义 + +| 状态 | 定义 | 可否计入阶段验收 | +|---|---|---| +| 未开始 | 尚无设计或实现 | 否 | +| 方案确定 | 需求、接口和验收已确定，尚未实现 | 否 | +| 骨架 | 路由、页面或服务形态存在，但不能完成真实业务闭环 | 否 | +| Mock | 使用固定结果或模拟依赖完成联调 | 否 | +| 手工录入 | 可记录数据，但未实现设备/算法自动处理 | 部分 | +| 部分可用 | 主流程可运行，异常、可靠性或外部联调尚不完整 | 部分 | +| 可验收 | 功能、权限、异常流程、测试和文档均具备 | 是 | +| 已验证 | 在目标环境按验收用例执行并保留证据 | 是 | + +### 0.4 需求优先级 + +- **P0：** 安全、业务正确性、数据可靠性或核心闭环的发布阻断项。 +- **P1：** 稳定试点必须具备的能力。 +- **P2：** 规模化运营或体验增强能力。 +- **P3：** 研究验证和长期创新能力。 + +### 0.5 修订记录 + +| 版本 | 日期 | 主要变化 | +|---|---|---| +| V1.0 | 2026-08-09 | 定义 MobileNetV3 蚕病分类方案 | +| V2.0 | 2026-08-10 | 扩展为 AI、分子检测、专家会诊三层协同体系 | +| V2.1 | 2026-08-11 | 增加三级疫病溯源和病种知识附录 | +| V2.2 | 2026-08-13 | 对齐 Go + Python 混合架构；增加能力状态、需求 ID、AI/数据/安全治理、异常流程、验收矩阵和整改基线 | + +## 1. 产品范围 + +### 1.1 产品定位 + +平台不是自动确诊工具，而是覆盖以下链路的辅助防控系统： + +```text +环境与日常管理 + ↓ +AI 高频风险筛查 + ↓ +检测任务与样本流转 + ↓ +LAMP/qPCR/SERS 等结果确认 + ↓ +专家会诊与处置方案 + ↓ +发病事件、溯源与效果评估 +``` + +平台输出的 AI 结果、风险评分和自动规则均属于辅助决策。确诊、检疫和重大处置必须由具有相应职责的人员确认。 + +### 1.2 产品目标 + +1. 提高蚕房异常发现的频率和记录完整性。 +2. 将巡检、检测、会诊、处置和溯源串成可追踪业务闭环。 +3. 降低基层检测流程的操作与管理门槛。 +4. 建立可用于专家复盘、区域分析和模型改进的可信数据底座。 +5. 在弱网、设备故障和外部服务不可用时保持数据可恢复。 + +### 1.3 非目标 + +1. 不把 AI 视觉结果表述为病原学确诊。 +2. 不在缺少方法学验证时宣称 SERS 或高光谱具备蚕病临床/现场诊断能力。 +3. 不在当前阶段自动执行隔离、消毒、通风或温湿度控制等高影响动作。 +4. 不以二分类模型指标替代多病种分类验收。 +5. 不在未获得合法授权时将业务图片、视频、光谱或个人信息用于模型训练或对外共享。 + +### 1.4 用户角色 + +| 角色 | 主要终端 | 核心职责 | +|---|---|---| +| 养蚕农户 | 微信小程序 | 日常巡检、查看环境与预警、执行采样/处置指引 | +| 蚕桑站技术员 | Web + 小程序 | 检测任务、样本流转、结果录入、现场排查、耗材管理 | +| 蚕病专家 | Web 优先 | 会诊、诊断意见、防控方案、三级溯源复核 | +| 组织管理员 | Web | 用户、角色、蚕房、设备、数据权限和运营管理 | +| 管理部门 | Web 数据视图 | 脱敏区域统计和资源配置 | +| 系统运维 | 运维工具 | 配置、发布、监控、备份、恢复和安全响应 | + +## 2. 当前架构与目标架构 + +### 2.1 已确定技术基线 + +| 层级 | 当前技术 | 目标说明 | +|---|---|---| +| Web 后台 | Vite + React + TypeScript + Ant Design | 保持现有技术栈 | +| 农户端 | Taro 4 + React + TypeScript 微信小程序 | 核心现场终端；补离线同步 | +| 移动 APP | React Native 0.74 | 当前以环境监控为主；蚕病能力是否继续同步需单独产品决策 | +| 主业务后端 | Go 1.23 + Gin + GORM | 承载认证、业务、规则、设备和数据接口 | +| AI 服务 | Python 3.11 + FastAPI + ONNX Runtime | 独立部署于 GPU 云主机；只承载模型推理与模型相关指标 | +| 业务数据 | PostgreSQL | 必须采用版本化 schema 管理 | +| 时序数据 | IoTDB，PostgreSQL 降级 | MVP 沿用；TDengine 仅为规模化候选 | +| 缓存与状态 | Valkey/Redis | 用于跨实例状态、限流、吊销和可靠任务辅助 | +| 对象存储 | 当前 Ceph S3；生产目标 OSS/COS | 通过 S3 兼容接口隔离实现差异 | +| 视频平台 | WVP-PRO + ZLMediaKit + recorder-go | 视频访问必须受授权或短时签名保护 | +| 消息 | WebSocket + 微信订阅消息 | 业务通知必须持久化、可重试、可审计 | + +### 2.2 逻辑架构 + +```text +Web / 微信小程序 / APP + │ HTTPS / WSS + ▼ +Go API（认证、RBAC、对象级授权、业务编排） + ├─ PostgreSQL（业务、审计、任务、事件） + ├─ IoTDB（遥测，PG 降级） + ├─ Redis（跨实例状态、幂等、限流、任务） + ├─ S3 兼容存储（图片、光谱、录像） + ├─ MQTT（设备遥测与控制） + ├─ WVP/ZLM/recorder-go（视频） + └─ AI Service（图片/视频帧推理） + │ + └─ 微信、天气等外部服务 +``` + +### 2.3 服务边界 + +- Go 后端负责用户身份、权限、对象归属、业务状态机、任务编排、审计和外部服务协调。 +- AI 服务不得自行决定用户数据范围，不直接接受客户端提供的任意内部流地址。 +- 客户端不得持有数据库、S3、WVP、ZLM、AI 服务或设备的长期管理密钥。 +- 外部服务失败不得造成业务记录静默丢失；需保存失败状态并允许重试。 + +### 2.4 部署边界 + +- 开发：本地或开发服务器，可显式启用 mock，但界面和数据必须标记 mock。 +- 生产：业务云主机 + GPU 云主机 + 云对象存储；服务间通过同 VPC 私网通信。 +- 生产必须使用 HTTPS/WSS、非默认密钥、独立数据库账户和最小网络开放范围。 + +## 3. 核心业务流程 + +### 3.1 日常巡检流程 + +1. 农户选择蚕房、蚕匾和批次，或扫描二维码定位对象。 +2. 客户端校验图片和本地任务 ID；弱网时进入待同步队列。 +3. 服务端保存原图、创建巡检记录并调用 AI 服务。 +4. AI 返回类别、异常概率、模型版本和推理状态。 +5. 风险引擎结合环境、龄期、整齐度、数据新鲜度和缺失项生成分数、等级与解释。 +6. 橙色风险生成待确认检测任务；红色风险同时生成会诊建议。 +7. 用户查看结果、缺失项和建议动作，不能看到“AI 已确诊”类表述。 + +异常要求： + +- 图片无效：不上传对象存储，不创建成功记录。 +- 对象存储成功但 AI 失败：保留 `ai_status=failed`，支持重试，不生成虚假风险。 +- 重复请求：同一用户和业务幂等键返回同一结果。 +- 离线同步冲突：以业务任务 ID 判重，向用户展示已同步/冲突/失败状态。 + +### 3.2 检测任务流程 + +```text +巡检触发 / 定期抽检 / 人工创建 + ↓ +DetectionTask（病种、对象、优先级、推荐方式） + ↓ +Sample（采样、交接、运输、接收） + ↓ +检测执行与质控（对照、试剂、设备、操作员） + ↓ +DetectionResult（positive/negative/invalid/indeterminate） + ↓ +交叉验证 → 发病事件 / 复检 / 专家会诊 +``` + +### 3.3 专家会诊流程 + +1. 系统生成病例快照，包含批次、巡检、检测、环境、天气、处置和溯源摘要。 +2. 管理员或规则按病种、区域和专家能力分派。 +3. 专家受理、补充询问、提交意见和防控方案。 +4. 技术员确认执行方案并记录措施。 +5. 到期复查，形成效果评估后归档。 + +### 3.4 发病与溯源流程 + +1. 经有效检测或专家确认后创建 `DiseaseEvent`。 +2. 自动汇总发病前 72 小时环境、同批/同房/同区域历史和种源/人员/工具流转信息。 +3. 技术员完成对应病种排查清单。 +4. 专家或实验室补充分型、环境样本和结论。 +5. 保存来源判断、置信度、证据、定向处置和复发复查。 + +## 4. 功能需求 + +### 4.1 身份、权限与组织 + +| ID | 优先级 | 需求 | 验收要点 | +|---|---|---|---| +| IAM-001 | P0 | 账号登录、刷新、登出和改密 | 访问/刷新令牌类型隔离；登出跨实例生效 | +| IAM-002 | P0 | RBAC 权限 | 后端所有业务路由执行权限校验，前端隐藏不等于授权 | +| IAM-003 | P0 | 对象级数据授权 | 用户只能访问获授权组织、区域、蚕房、设备、视频和业务记录 | +| IAM-004 | P0 | 安全初始化 | 生产缺少密钥或管理员初始化信息时拒绝启动；首次登录强制改密 | +| IAM-005 | P1 | 多组织模型 | 支持组织—养殖场—区域—用户归属与跨组织隔离 | +| IAM-006 | P1 | 审计 | 登录、权限、播放、导出、检测判读、会诊和处置均记录操作者与时间 | + +### 4.2 蚕房、蚕匾、批次与生物安全 + +| ID | 优先级 | 需求 | 验收要点 | +|---|---|---|---| +| FARM-001 | P0 | 蚕房、蚕匾、批次 CRUD | 关联完整、删除受引用保护、支持分页查询 | +| FARM-002 | P1 | 二维码身份 | 扫码唯一定位蚕匾/批次/样本，二维码不可猜测敏感信息 | +| FARM-003 | P1 | 饲养记录 | 记录龄期、桑叶来源、密度、死亡/淘汰和备注 | +| FARM-004 | P1 | 消毒记录 | 计划、执行、药剂、浓度、人员、照片和复核可追踪 | +| FARM-005 | P1 | 蚕种来源与检疫链 | 供应商、批号、检疫凭证、入场时间和跨批次关系可追踪 | +| FARM-006 | P2 | 产量与损失 | 记录死亡率、蚕茧产量、损失和防控成本 | + +### 4.3 环境监测、设备和预警 + +| ID | 优先级 | 需求 | 验收要点 | +|---|---|---|---| +| ENV-001 | P0 | 遥测采集与查询 | 包含设备、指标、单位、时间、来源和质量标识 | +| ENV-002 | P0 | 阈值告警 | 支持防抖、恢复、确认和告警审计 | +| ENV-003 | P1 | 数据新鲜度 | 超过指标允许时延的数据标记 stale，不参与实时风险或明确降级 | +| ENV-004 | P1 | 病害环境规则 | 支持连续时窗、龄期、密度、通风、天气、种源和消毒条件 | +| ENV-005 | P1 | 规则版本与解释 | 每次命中保存规则版本、输入快照、命中条件和缺失项 | +| ENV-006 | P1 | 设备资产与校准 | 记录传感器校准、故障、维护和固件信息 | +| ENV-007 | P2 | 安全控制建议 | 只生成建议；自动控制需独立审批、安全边界和人工确认 | + +### 4.4 AI 视觉巡检 + +| ID | 优先级 | 需求 | 验收要点 | +|---|---|---|---| +| AI-INS-001 | P0 | 图片巡检 | 图片校验、存储、推理、评分、记录和失败重试完整 | +| AI-INS-002 | P0 | 异常概率语义 | 只用 `abnormalProbability` 计算 AI 风险；healthy 高置信度不得升高风险 | +| AI-INS-003 | P0 | Mock 隔离 | Mock 结果带 `isMock=true`，不得进入生产统计、告警或训练集 | +| AI-INS-004 | P0 | 可解释风险 | 返回模型、规则、环境、龄期、整齐度、缺失项的贡献与版本 | +| AI-INS-005 | P1 | 离线巡检 | 弱网可排队、重试、判重并显示同步状态 | +| AI-INS-006 | P1 | 自动检测任务 | 橙色创建待确认检测任务；重复评分不得重复建单 | +| AI-INS-007 | P2 | 群体整齐度 | 全景图输出分布和异常度；无模型时不得以 0 冒充正常 | +| AI-INS-008 | P2 | 历史对比 | 同一蚕匾/批次按时间展示图片与风险趋势 | +| AI-INS-009 | P3 | 个体追踪 | 仅在固定视角和标识可行性验证后进入开发 | + +### 4.5 风险评分 + +风险输出结构至少包含： + +```json +{ + "score": 62.5, + "level": "orange", + "confidence": "medium", + "modelVersion": "silk-yolo-2026.08.1", + "ruleVersion": "risk-v2", + "components": { + "aiAbnormalProbability": 0.78, + "environment": 0.60, + "stage": 0.40, + "uniformity": null + }, + "missing": ["uniformity"], + "actions": ["confirm_detection_task"] +} +``` + +| ID | 优先级 | 需求 | 验收要点 | +|---|---|---|---| +| RISK-001 | P0 | 分数边界 | 绿 `[0,30]`、黄 `(30,60]`、橙 `(60,80]`、红 `(80,100]` | +| RISK-002 | P0 | 缺失语义 | 未采集数据用 null/unknown，不以 0 表示正常 | +| RISK-003 | P0 | 输入快照 | 保存分数输入、时间、数据来源、模型和规则版本 | +| RISK-004 | P1 | 数据校准 | 阈值基于试点数据评估并记录版本，不把主观权重当作科学结论 | +| RISK-005 | P1 | 人工复核 | 允许技术员纠正等级和原因，原始自动结果不可覆盖 | + +### 4.6 检测任务、样本与分子检测 + +| ID | 优先级 | 需求 | 验收要点 | +|---|---|---|---| +| DET-001 | P0 | 统一检测任务 | LAMP/qPCR/SERS/高光谱共用任务、样本、状态和结果框架 | +| DET-002 | P0 | 样本链路 | 采样、交接、运输、接收和检测全程有人员与时间 | +| DET-003 | P0 | 结果枚举 | 支持 positive/negative/invalid/indeterminate | +| DET-004 | P0 | qPCR 质控 | 无 Ct 或对照/内参失败不得判阴性；阈值绑定方案版本 | +| DET-005 | P1 | LAMP 流程质控 | 五步流程、温度、时长、试剂批次、阳/阴性对照和照片完整 | +| DET-006 | P1 | 交叉验证 | 一致、冲突、持续高风险等路径可追踪并生成下一动作 | +| DET-007 | P1 | 检测方式推荐 | 仅推荐当前组织真实可用且方法状态允许的方式 | +| DET-008 | P1 | 耗材管理 | 库存、批号、有效期、领用、报废、预警和采购建议 | +| DET-009 | P2 | 设备回传 | 设备身份、签名、重放防护、数据 schema 和失败重试明确 | +| DET-010 | P3 | LAMP 图像判读 | 完成独立数据集与方法验证前只作为辅助记录 | +| DET-011 | P3 | SERS/高光谱分析 | 区分上传、算法完成和方法学验证，不得合并为“已接入” | + +### 4.7 专家会诊与知识库 + +| ID | 优先级 | 需求 | 验收要点 | +|---|---|---|---| +| EXP-001 | P1 | 病例快照 | 包含批次、巡检、检测、环境、天气、处置和溯源摘要 | +| EXP-002 | P1 | 会诊状态机 | 待分派、已分派、已受理、待补充、已出方案、已归档转换受控 | +| EXP-003 | P1 | SLA | 记录分派、受理、响应、超时升级和完成时间 | +| EXP-004 | P1 | 专家意见版本 | 修改意见保留版本、签名、原因和时间 | +| EXP-005 | P2 | 复诊与效果 | 处置后复查并关联原病例 | +| KB-001 | P1 | 内容审核 | 草稿、审核、发布、撤回状态与审计完整 | +| KB-002 | P1 | 证据来源 | 文章、规则和病种事实记录来源、日期、适用范围和专家确认 | +| KB-003 | P2 | 案例沉淀 | 已脱敏会诊病例经审核后转为案例，不自动公开原始数据 | + +### 4.8 发病事件与疫病溯源 + +| ID | 优先级 | 需求 | 验收要点 | +|---|---|---|---| +| TRACE-001 | P1 | 发病事件 | 独立记录确诊病种、时间、范围、损失、处置和证据 | +| TRACE-002 | P1 | 一级自动溯源 | 5 分钟内生成环境、历史、空间和传播初报，明确数据缺失 | +| TRACE-003 | P1 | 二级排查 | 按病种加载版本化清单，保存答案、附件和现场说明 | +| TRACE-004 | P1 | 三级溯源 | 专家、分子分型、环境样本和实验室结果结构化关联 | +| TRACE-005 | P1 | 来源结论 | internal/external/mixed/unknown，包含置信度、证据和复核人 | +| TRACE-006 | P2 | 区域分析 | 按授权区域、时间、病种和批次统计；小样本自动脱敏 | +| TRACE-007 | P2 | 复发关联 | 识别同房、同种源、同工具或跨年复发，并允许人工确认 | + +### 4.9 视频、通知和运营分析 + +| ID | 优先级 | 需求 | 验收要点 | +|---|---|---|---| +| VIDEO-001 | P0 | 视频访问授权 | 直播/录像需要 JWT + 对象授权或短时签名令牌 | +| VIDEO-002 | P0 | 密钥保护 | 摄像头、SIP、WVP、ZLM 密钥不出现在业务 API 和日志 | +| VIDEO-003 | P1 | 录像可靠性 | 重启可恢复活跃状态；开始/停止/归档幂等 | +| VIDEO-004 | P2 | 摄像头 AI 任务 | 以 cameraId/taskId 调度；客户端不能提交任意流 URL | +| MSG-001 | P0 | 通知持久化 | 通知有状态、重试、失败原因和业务关联，服务重启不丢失 | +| MSG-002 | P1 | 订阅授权 | 微信订阅按用户授权和模板状态发送，不静默假成功 | +| ANA-001 | P1 | 健康画像 | 分数公式、数据窗口、缺失项和版本可解释、可回测 | +| ANA-002 | P1 | 防控效果 | 对比处置前后风险、阳性率、复发、损失与成本 | +| ANA-003 | P2 | 区域与年度统计 | 支持地图/图表、时间筛选、脱敏和导出审计 | + +## 5. 数据架构与治理 + +### 5.1 核心实体 + +```text +Organization +└─ Farm + └─ Room + ├─ Device / Sensor / Camera / Telemetry / Alarm + └─ Tray + └─ Batch + ├─ RearingRecord / DisinfectionRecord / SeedSource + ├─ InspectionRecord + ├─ DetectionTask ─ Sample ─ DetectionResult + └─ DiseaseEvent + ├─ Consultation + ├─ ControlMeasure / FollowUp + └─ TraceRecord +``` + +### 5.2 数据通用字段 + +所有重要业务实体应包含：ID、组织/数据范围、创建人、创建时间、更新时间、状态、版本号；涉及结论的数据增加规则/模型/方案版本和人工复核信息。 + +### 5.3 数据质量 + +- 遥测：单位、设备时间、接收时间、质量、是否迟到/重复。 +- 图片/光谱：哈希、格式、大小、来源、采集对象、授权用途。 +- 检测：试剂、设备、操作员、对照、内参、重复孔和原始数据。 +- 统计：不得把 mock、删除、无效和未完成记录混入有效统计。 + +### 5.4 数据保留与隐私 + +- 生产上线前由项目负责人确认个人信息、图片、视频、检测、审计和模型数据的保留期限。 +- 删除业务数据时，按引用关系执行限制、匿名化或延迟删除，禁止直接造成溯源链断裂。 +- 导出、共享和训练用途必须记录申请人、范围、目的和审批结果。 + +### 5.5 Schema 管理 + +- 开发可生成迁移，但生产不得依赖 GORM AutoMigrate 自动变更结构。 +- 每次 schema 变更必须有向前迁移、回滚策略、备份点和版本记录。 +- 服务启动时校验 schema 版本，不匹配则拒绝提供写服务。 +- 具体迁移工具属于尚未确认的技术选型，实施前需由项目负责人确认。 + +## 6. API 与事件契约 + +### 6.1 通用 API 规则 + +- 基础路径：`/api/v1`；新增破坏性变更使用新版本或兼容期。 +- 时间：RFC3339，服务端统一保存带时区时间。 +- 分页：`page`、`pageSize` 或 cursor 只能选定一种规范并在 OpenAPI 中统一。 +- 错误：包含稳定错误码、可读消息、requestId 和可选字段错误。 +- 幂等：巡检上传、检测建单、通知和设备回调必须支持幂等键。 +- 并发：可编辑结论使用版本号或更新时间防止静默覆盖。 + +### 6.2 服务间调用 + +- Go → AI：VPC 内认证；30 秒以内的图片推理超时；流任务异步执行。 +- recorder-go → Go：非默认内部凭据、请求签名或等效认证、重放防护。 +- 外部 API：统一超时、有限重试、熔断、失败记录和补偿任务。 + +### 6.3 事件最小结构 + +```json +{ + "eventId": "uuid", + "eventType": "inspection.risk.changed", + "occurredAt": "2026-08-13T10:00:00+08:00", + "aggregateType": "inspection", + "aggregateId": "uuid", + "organizationId": "uuid", + "schemaVersion": 1, + "payload": {} +} +``` + +消费者按 `eventId` 幂等；失败事件保留重试次数和最终失败状态。 + +## 7. AI 模型与数据规范 + +### 7.1 阶段划分 + +| 阶段 | 标签 | 用途 | 进入下一阶段条件 | +|---|---|---|---| +| 基线 | healthy/sick | 验证异常筛查可行性 | 数据集无泄漏、真实测试集指标达标 | +| 多病种 | healthy + 已验证病种 + unknown | 病种辅助分类 | 每类样本、确诊依据和混淆风险满足评审 | +| 群体 | 个体框、尺寸/整齐度 | 全景筛查 | 固定采集规范和稳定标注具备 | + +### 7.2 数据集切分 + +- 按养殖场、批次、原始图片或拍摄日期分组，防止同源样本跨集合。 +- 增强副本只能跟随原图进入同一集合。 +- 测试集冻结后不可用于训练和阈值调优。 +- 每个样本记录病种确认依据；仅凭肉眼怀疑的样本不能作为病原确诊标签。 + +### 7.3 指标 + +- 报告每类 precision、recall、F1、支持样本数、混淆矩阵和 PR-AUC。 +- 筛查模型以患病召回率、漏诊率和校准误差为主要指标，不只报告 overall accuracy。 +- 端到端报告图片失败率、推理 p95、模型加载失败、空检测和 unknown 比例。 +- 阈值由冻结验证集选择，再在冻结测试集一次性评估。 + +### 7.4 模型发布 + +每个模型版本必须有模型卡，记录：标签集、数据版本、代码版本、指标、限制、输入规范、ONNX 校验、阈值、发布日期、灰度范围和回滚版本。 + +### 7.5 人工监督 + +- UI 显示“AI 辅助筛查”及不确定性。 +- 用户可以提交纠正，但纠正需进入待复核标注队列。 +- 模型变化不得回写覆盖历史原始输出；重新推理生成新版本结果。 + +## 8. 安全与隐私要求 + +| ID | 要求 | +|---|---| +| SEC-001 | 生产关键密钥必须显式注入，不允许可用默认值 | +| SEC-002 | 已进入 Git 历史的凭据按泄露处理并轮换 | +| SEC-003 | 所有视频、对象和业务记录执行对象级授权 | +| SEC-004 | 密码、密钥、token、设备认证信息不进入 JSON、URL 查询、普通日志或客户端包 | +| SEC-005 | WebSocket 校验 Origin、令牌类型和订阅对象权限 | +| SEC-006 | 上传文件校验类型、大小、内容，隔离处理未知格式 | +| SEC-007 | AI 流任务禁止任意 URL，防止 SSRF 和内网探测 | +| SEC-008 | 登录、刷新、内部接口和高成本接口设置跨实例限流 | +| SEC-009 | 审计日志防止普通用户修改，保留期由上线评审确定 | +| SEC-010 | 安全事件有密钥轮换、禁用账号、撤销 token 和证据保留流程 | + +## 9. 非功能性需求 + +### 9.1 性能 + +| 指标 | 目标 | 验证条件 | +|---|---|---| +| 常规 API p95 | <500ms | 不含 AI、上传和视频；按目标数据量压测 | +| 常规查询 p95 | <200ms | 明确数据量、过滤条件和索引 | +| 图片上传 | <10 秒 | 4G 弱网、压缩后不超过 500KB | +| AI 图片推理 p95 | <2 秒为目标 | 指定 T4、输入尺寸、并发和模型版本 | +| 在线用户 | 常态 500、峰值 1000 | 使用真实请求比例和连接时长模型 | +| 自动溯源初报 | <5 分钟 | 从有效 DiseaseEvent 创建开始计时 | + +### 9.2 可用性与灾备 + +- 月度服务可用性目标 99.5%，需定义排除的计划维护窗口。 +- PostgreSQL 生产目标：RPO 不超过 24 小时、RTO 不超过 4 小时；上线前根据业务价值复审。 +- 每日备份、异地或独立故障域副本、季度恢复演练；只有恢复成功才算备份有效。 +- IoTDB、对象存储、Redis、视频和 AI 服务分别定义降级行为。 + +### 9.3 可观测性 + +- 全链路 requestId/eventId。 +- 结构化日志禁止包含密钥和完整 token。 +- 指标覆盖 API、数据库、Redis、MQTT、IoTDB、S3、视频、AI、微信、天气和业务任务。 +- 告警覆盖错误率、延迟、积压、存储容量、备份失败、模型失败和通知失败。 + +### 9.4 兼容性与弱网 + +- 记录并验证微信基础库最低版本、Android/iOS 最低版本和主流浏览器矩阵。 +- 小程序核心巡检在断网后可保存，恢复网络后可见同步进度和失败原因。 +- 重复点击、网络切换、超时重试不得产生重复检测任务或重复通知。 + +## 10. 测试与质量门禁 + +### 10.1 每次提交 + +- Go：`go test ./...`、`go vet ./...`、`go build ./...` +- Web：`npm test`、`npm run lint`、`npm run build` +- 小程序：`npx tsc --noEmit`、`npm run build:weapp` +- APP：`npm run tsc`、`npm run lint` +- AI：在 Python 3.11 虚拟环境执行 `python -m pytest` + +### 10.2 发布前测试 + +- 权限与对象级越权测试。 +- 核心业务端到端：巡检—检测—会诊—发病—溯源—复查。 +- 弱网、重复请求、依赖超时、服务重启和幂等测试。 +- 数据库迁移与回滚、备份恢复演练。 +- 负载、容量、密钥扫描、依赖漏洞扫描和文件上传安全测试。 + +### 10.3 验收证据 + +每个需求 ID 至少关联：实现文件/接口、自动测试、环境、执行时间、结果、已知限制和发布/回滚记录。 + +## 11. 分阶段实施与退出条件 + +### 11.1 阶段 A：安全与正确性整改 + +范围：RISK-001～003、AI-INS-002/003、IAM-003/004、VIDEO-001/002、DET-004、Schema 启动校验和当前构建错误。 + +退出条件： + +- healthy 高置信度不产生异常风险。 +- 视频流无授权不可访问，摄像头/SIP 密钥不从 API 返回。 +- 生产缺关键密钥拒绝启动，历史密钥完成轮换。 +- qPCR 无有效对照不能判阴性。 +- 五端约定的本地检查可复现执行。 + +### 11.2 阶段 B：工程化基线 + +范围：版本化迁移、CI、可靠通知/任务、跨实例状态、可观测性和 OpenAPI。 + +退出条件：新环境部署、升级、回滚和恢复演练通过；依赖失败可观测；通知和任务重启不丢失。 + +### 11.3 阶段 C：可用 MVP 闭环 + +范围：二维码、消毒、种源、样本、DiseaseEvent、自动检测任务、离线巡检、会诊 SLA 和效果评估。 + +退出条件：真实用户能在试点环境完成全链路；业务 ID、样本和证据不中断；异常流程有明确状态。 + +### 11.4 阶段 D：真实模型与规模化试点 + +范围：数据集修复、二分类基线、多病种决策、模型治理、容量与云灾备。 + +退出条件：模型卡、数据卡、冻结测试集和试点指标通过评审；生产容量、安全和恢复证据完整。 + +### 11.5 阶段 E：研究能力 + +范围：摄像头群体巡检、LAMP 图像判读、SERS/高光谱、传播模型和数字孪生建议。 + +退出条件：每项单独立项、方法学验证和伦理/数据授权完成，不影响已验收主链路。 + +## 12. 当前状态追踪矩阵 + +| 能力 | 当前状态 | 阻断项 | 目标阶段 | +|---|---|---|---| +| 环境/设备/告警 | 部分可用 | 数据质量、对象权限、校准 | B/C | +| 视频 | 部分可用 | 公开流、密码返回 | A | +| 拍照巡检 | Mock/部分可用 | 真实模型、风险语义、离线 | A/C/D | +| 风险评分 | 部分可用但存在错误 | healthy 置信度语义、缺失数据 | A | +| LAMP | 手工流程可用 | 质控、样本链、AI 判读 | C/E | +| qPCR | 手工录入且判读待修 | 对照/无效态/阈值版本 | A/C | +| SERS | 文件录入骨架 | 设备、算法、方法验证 | C/E | +| 高光谱 | 接口预留 | 数据、算法、方法验证 | E | +| 专家会诊 | 表单流程部分可用 | SLA、版本、可靠通知 | C | +| 疫病溯源 | v1 规则部分可用 | DiseaseEvent、种源/样本/空间链 | C | +| 微信/天气 | 骨架 | 真实凭证和目标环境联调 | C | +| 摄像头 AI | 骨架 | 安全任务调度、视角数据、模型 | E | +| 测试/CI/迁移/可观测性 | 基础不足 | 多端测试、CI、版本迁移、统一监控 | B | + +## 13. 开放决策 + +以下事项必须由项目负责人确认后再实施，不在本规格书中擅自选型： + +1. Go 数据库迁移工具及迁移文件管理约定。 +2. CI 承载平台与制品保存位置。 +3. 生产云厂商、对象存储产品、域名和证书方案。 +4. APP 是否继续同步全部蚕病功能，还是收敛为环境监控端。 +5. 数据、图片、视频、光谱、审计和训练集的正式保留期限。 +6. qPCR 各病种/试剂盒的对照和 Ct 判读方案。 +7. 真实模型二分类进入多病种训练的指标门槛。 + +## 14. 领域知识与引用要求 + +V2.1 第 11 章的蚕病知识可继续作为领域参考底稿，但在进入知识库、检测判读规则或验收标准前，必须补充文献/规范来源、发布日期、访问日期、适用范围、证据等级和领域专家确认。设备价格、单次成本、研究状态和推广事件属于时效性信息，不作为长期固定验收事实。 diff --git a/项目整改实施计划_V1.0.md b/项目整改实施计划_V1.0.md new file mode 100644 index 0000000..8f8fa24 --- /dev/null +++ b/项目整改实施计划_V1.0.md @@ -0,0 +1,914 @@ +# 蚕病智能防控平台整改实施计划 + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 依据《蚕病智能防控平台规格说明书 V2.2》，先消除安全与业务正确性风险，再建立可迁移、可测试、可观测、可恢复的试点闭环。 + +**Architecture:** 保持现有 Go/Gin 主业务后端、Python/FastAPI AI 微服务、React Web、Taro 小程序、React Native APP 和 IoTDB/PostgreSQL/S3/WVP 基础。整改采用“小步迁移 + TDD + 功能开关 + 可回滚发布”，不在本计划中替换既有主技术栈。 + +**Tech Stack:** Go 1.23、Gin、GORM、PostgreSQL、IoTDB、Valkey/Redis、MQTT、FastAPI、ONNX Runtime、React、Taro 4、React Native 0.74、Vitest、pytest。 + +## Global Constraints + +- 不得手改 `miniapp/dist/`、`web/dist/`、APK、Linux 二进制等生成产物。 +- 不得覆盖无关的用户修改；每个任务只提交本任务文件。 +- 新功能先写失败测试，再做最小实现，再运行模块和全量检查。 +- 生产密钥只通过环境变量/密钥管理注入，不写入提交文件。 +- 所有 schema 修改先备份、再迁移；生产不允许 GORM AutoMigrate 自动改表。 +- 每项交付必须追加 `开发交接记录.md`，记录设计依据、验证证据和回滚点。 +- 涉及发布时严格执行 `AGENTS.md` 的开发服务器部署前置、备份和回滚要求。 +- 任务 0 的开放技术选型未确认前，不得擅自引入迁移工具、CI 平台或新外部服务。 + +--- + +## 1. 执行原则与分工 + +### 1.1 优先级 + +| 波次 | 目标 | 任务 | 预计串行工期 | +|---|---|---|---| +| Wave 0 | 决策与基线 | 0～1 | 2～3 人日 | +| Wave 1 | P0 安全与正确性 | 2～7 | 10～15 人日 | +| Wave 2 | 工程可靠性 | 8～9 | 6～10 人日 | +| Wave 3 | 业务闭环 | 10～12 | 20～33 人日 | +| Wave 4 | 验收与发布 | 13～14 | 7～11 人日 | + +工期只用于排期，不是验收标准。多人并行时，任务 2 是涉及数据库实体任务的前置；任务 3～7 可在接口边界明确后分支并行，但合并前必须统一回归。 + +### 1.2 建议责任域 + +- 后端负责人：任务 2～10、13。 +- AI 负责人：任务 6 中 AI 响应与模型元数据、任务 14 AI 验收。 +- Web/小程序负责人：任务 1、11、12 的端侧部分。 +- 运维负责人：任务 3、8、9、13 的配置、监控、备份和发布。 +- 测试负责人：维护需求 ID—用例—结果矩阵，不以开发自测替代验收。 +- 领域专家：确认 qPCR 规则、风险动作、病种清单和知识来源。 + +### 1.3 每个任务的完成定义 + +1. 需求 ID 与验收用例明确。 +2. 失败测试已观察到预期失败原因。 +3. 实现和迁移完成，模块测试通过。 +4. 相关模块全量检查通过或准确记录环境阻断。 +5. 文档、配置示例和交接记录更新。 +6. 回滚步骤经过静态复核；涉及部署时完成实际冒烟。 + +--- + +### Task 0: 固化开放决策与整改基线 + +**Requirements:** V2.2 第 13 章 +**Owner:** 项目负责人 + 后端/运维/领域负责人 +**Estimated effort:** 0.5～1 人日 + +**Files:** +- Create: `docs/decisions/2026-08-13-remediation-decisions.md` +- Modify: `后续工作计划.md` +- Modify: `开发交接记录.md` + +**Interfaces:** +- Consumes: `蚕病智能防控平台规格说明书_V2.2.md` 的开放决策。 +- Produces: 迁移工具、CI 平台、保留期限、qPCR 规则负责人、APP 范围和模型门槛的书面决定。 + +- [ ] **Step 1: 召开 60 分钟决策会并逐项记录负责人、选项、理由和生效日期** + +文档必须使用如下固定表头： + +```markdown +| Decision ID | 结论 | 备选方案 | 选择理由 | 影响 | 负责人 | 复审条件 | +|---|---|---|---|---|---|---| +``` + +- [ ] **Step 2: 明确七项决定** + +必须覆盖：数据库迁移工具、CI 承载平台、制品位置、数据保留期限、qPCR 方案确认流程、APP 产品范围、二分类转多病种指标门槛。不得写“以后再定”；暂不实施时写“保持现状 + 明确复审触发条件”。 + +- [ ] **Step 3: 将 Wave 1～4 写入 `后续工作计划.md`，使用七态能力状态而不是单一勾选** + +- [ ] **Step 4: 评审并提交** + +```powershell +rg -n "Decision ID|迁移|CI|保留|qPCR|APP|二分类" docs/decisions/2026-08-13-remediation-decisions.md +git diff --check +``` + +Expected: 七项主题均可检索，`git diff --check` exit 0。 + +**Rollback:** 删除决策文档并恢复计划/交接记录；尚未执行的决定不产生运行时影响。 + +--- + +### Task 1: 恢复可复现的多端质量基线 + +**Requirements:** V2.2 第 10 章 +**Owner:** 各端负责人 +**Estimated effort:** 1～2 人日 + +**Files:** +- Modify: `miniapp/src/pages/dashboard/index.tsx` +- Modify: `miniapp/package.json` +- Modify: `app/package.json` +- Modify: `ai-service/README.md` +- Create: `scripts/verify.ps1` +- Modify: CI 配置文件（路径由 Task 0 确认的平台决定） +- Modify: `开发交接记录.md` + +**Interfaces:** +- Produces: 单命令验证入口 `powershell -ExecutionPolicy Bypass -File scripts/verify.ps1`。 + +- [ ] **Step 1: 修复小程序 JSX 类型错误** + +将裸文本箭头改为明确字符节点： + +```tsx +详情 {'>'} +全部 {'>'} +``` + +- [ ] **Step 2: 为小程序增加只读类型检查脚本，为 APP 确认本地 devDependencies 安装可用** + +```json +{ + "scripts": { + "typecheck": "tsc --noEmit" + } +} +``` + +- [ ] **Step 3: 创建验证脚本** + +`scripts/verify.ps1` 必须按模块执行并在任一失败时返回非 0： + +```powershell +$ErrorActionPreference = 'Stop' +Push-Location server-go; go test ./...; go vet ./...; go build ./...; Pop-Location +Push-Location web; npm test; npm run lint; npm run build; Pop-Location +Push-Location miniapp; npm run typecheck; npm run build:weapp; Pop-Location +Push-Location app; npm run tsc; npm run lint; Pop-Location +Push-Location ai-service; python -m pytest; Pop-Location +``` + +- [ ] **Step 4: 在干净依赖环境运行并保存结果** + +Expected: 五个模块全部 exit 0；Web lint warning 单独建单，不允许隐藏 exit code。 + +- [ ] **Step 5: 接入 Task 0 确认的 CI，禁止失败检查合并** + +**Rollback:** 恢复两处 JSX 与脚本变更；CI 门禁可关闭但不得删除失败证据。 + +--- + +### Task 2: 引入版本化数据库迁移与 Schema 启动门禁 + +**Requirements:** V2.2 5.5、阶段 B +**Owner:** 后端负责人 + DBA/运维 +**Estimated effort:** 2～3 人日 + +**Files:** +- Create: `server-go/migrations/000001_baseline.up.sql` +- Create: `server-go/migrations/000001_baseline.down.sql` +- Create: `server-go/internal/database/migrate.go` +- Create: `server-go/internal/database/migrate_test.go` +- Modify: `server-go/internal/database/db.go` +- Modify: `server-go/cmd/server/main.go` +- Modify: `README.md` +- Modify: `部署指南(物理机).md` + +**Interfaces:** +- Produces: `database.CheckSchemaVersion(db *gorm.DB, expected string) error`。 +- Constraint: 迁移执行器使用 Task 0 批准的工具；SQL 迁移文件作为唯一 schema 事实来源。 + +- [ ] **Step 1: 写失败测试，证明 schema 版本缺失/落后时返回错误** + +```go +func TestCheckSchemaVersionRejectsMismatch(t *testing.T) { + err := CheckSchemaVersion(fakeDBWithVersion("1"), "2") + if err == nil { t.Fatal("expected schema mismatch") } +} +``` + +- [ ] **Step 2: 生成当前 schema 基线 SQL，并人工核对所有表、索引和约束** + +不得使用 `AutoMigrate` 输出作为未经审核的生产脚本；基线需在空库执行后与当前模型对照。 + +- [ ] **Step 3: 实现启动检查并移除生产自动迁移** + +```go +func CheckSchemaVersion(db *gorm.DB, expected string) error +``` + +开发环境自动迁移只能由显式 `ALLOW_DEV_AUTOMIGRATE=true` 开启；生产配置忽略该开关并拒绝 AutoMigrate。 + +- [ ] **Step 4: 验证空库建库、旧库升级和 down 回滚** + +```powershell +go test ./internal/database -run TestCheckSchemaVersion -v +go test ./... +go vet ./... +go build ./... +``` + +Expected: 版本匹配通过，不匹配时服务启动失败且日志不包含 DSN 密码。 + +**Rollback:** 恢复旧二进制和迁移前数据库备份；不得只回滚代码而保留不兼容 schema。 + +--- + +### Task 3: 移除默认密钥与默认管理员密码 + +**Requirements:** IAM-004、SEC-001、SEC-002 +**Owner:** 后端 + 运维 + 各客户端负责人 +**Estimated effort:** 1～2 人日 + +**Files:** +- Modify: `server-go/internal/config/config.go` +- Create: `server-go/internal/config/config_test.go` +- Modify: `server-go/internal/handler/auth.go` +- Modify: `miniapp/src/pages/login/index.tsx` +- Modify: `app/src/screens/LoginScreen.tsx` +- Create: `server-go/.env.example` +- Modify: `app/.env.example` +- Modify: `README.md` + +**Interfaces:** +- Produces: `config.ValidateForEnvironment(cfg *Config, environment string) error`。 + +- [ ] **Step 1: 写表驱动测试，验证 production 缺 JWT/S3/ZLM/Internal API/管理员初始化配置时失败** + +```go +func TestValidateForEnvironmentRejectsProductionDefaults(t *testing.T) { + cfg := &Config{JWTSecret: "silk-secret-please-change-me"} + if err := ValidateForEnvironment(cfg, "production"); err == nil { + t.Fatal("expected insecure config rejection") + } +} +``` + +- [ ] **Step 2: 删除敏感字段的可用默认值，保留非敏感本地地址默认值** + +生产环境必须显式设置 `APP_ENV=production`；关键字段为空、长度不足或等于历史默认值均拒绝启动。 + +- [ ] **Step 3: 删除小程序和 APP 密码预填** + +```tsx +const [password, setPassword] = useState(''); +``` + +- [ ] **Step 4: 生成轮换清单并由运维在目标环境执行** + +轮换范围至少包括 PostgreSQL、Redis、MQTT、JWT、S3、WVP、ZLM、Internal API 和默认管理员。 + +- [ ] **Step 5: 验证** + +```powershell +go test ./internal/config ./internal/handler -v +rg -n "silk@123|Silk-App-Secret|silk-internal-2026|su6Tied" server-go miniapp/src app/src +``` + +Expected: 测试通过；源码搜索不再出现可用历史密钥。文档可提及已废弃值，但不得作为配置示例。 + +**Rollback:** 代码可恢复，但已轮换密钥不得回退为历史值；使用新生成密钥更新旧版本运行环境。 + +--- + +### Task 4: 收口视频访问与摄像头密钥输出 + +**Requirements:** IAM-003、VIDEO-001、VIDEO-002、SEC-003、SEC-004 +**Owner:** 视频后端负责人 +**Estimated effort:** 2～3 人日 + +**Files:** +- Modify: `server-go/internal/model/models.go` +- Create: `server-go/internal/handler/video_dto.go` +- Create: `server-go/internal/handler/video_auth.go` +- Create: `server-go/internal/handler/video_auth_test.go` +- Modify: `server-go/internal/handler/video_camera.go` +- Modify: `server-go/internal/handler/video_clip.go` +- Modify: `server-go/internal/handler/video_stream.go` +- Modify: `server-go/internal/middleware/auth.go` +- Modify: `web/src/dal/video.ts` + +**Interfaces:** +- Produces: `IssueVideoToken(userID, resourceType, resourceID string, ttl time.Duration) (string, error)`。 +- Produces: `ValidateVideoToken(token, resourceType, resourceID string) error`。 +- Token TTL: 5 分钟；绑定资源类型、ID、用户、用途和过期时间。 + +- [ ] **Step 1: 写安全回归测试** + +```go +func TestCameraResponseNeverContainsSecrets(t *testing.T) +func TestVideoStreamRejectsMissingOrWrongResourceToken(t *testing.T) +func TestVideoTokenExpires(t *testing.T) +``` + +- [ ] **Step 2: 将模型密钥字段标记为不序列化，并使用公开 DTO** + +```go +PasswordEnc *string `json:"-"` +GbAuthPassword *string `json:"-"` +``` + +`CameraPublic` 只包含播放和管理界面需要的非敏感字段；WVP 配置响应删除 `sipPassword`。 + +- [ ] **Step 3: 播放地址改为短时令牌** + +`/video/clips/:id/play` 和 `/video/cameras/:id/play` 先执行 JWT、权限和对象范围校验，再返回带短时 token 的 URL。stream/proxy 路由即使位于 auth 白名单，也必须验证该 token。 + +- [ ] **Step 4: 验证直接枚举 ID、跨用户 token、过期 token 和资源错配均为 401/403** + +```powershell +go test ./internal/handler -run "Video|CameraResponse" -v +go test ./... +``` + +**Rollback:** 可临时回滚到“JWT header 直接保护 stream”模式；禁止回滚为公开流或返回密钥。 + +--- + +### Task 5: 修复 WebSocket 越权与 AI 流 SSRF + +**Requirements:** IAM-003、SEC-005、SEC-007、VIDEO-004 +**Owner:** 后端 + AI 负责人 +**Estimated effort:** 2～3 人日 + +**Files:** +- Modify: `server-go/internal/ws/gateway.go` +- Create: `server-go/internal/ws/gateway_test.go` +- Modify: `server-go/cmd/server/main.go` +- Modify: `server-go/internal/config/config.go` +- Modify: `ai-service/app/main.py` +- Create: `ai-service/app/stream_tasks.py` +- Modify: `ai-service/tests/test_api.py` + +**Interfaces:** +- WebSocket: `NewHub(jwtSecret string, authorizer DeviceAuthorizer, allowedOrigins []string)`。 +- AI 流接口：`POST /internal/stream-tasks` 接受 `taskId` 和已解析的内部流引用，不接受公网客户端任意 URL。 + +- [ ] **Step 1: 写失败测试，覆盖非法 Origin、refresh token、无权 deviceKey 和全局广播泄露** + +- [ ] **Step 2: 增加设备授权接口并在 subscribe 时校验** + +```go +type DeviceAuthorizer interface { + CanReadDevice(userID, deviceKey string) (bool, error) +} +``` + +删除普通连接的无范围 `telemetry.all` 广播；管理视图使用单独权限和组织范围订阅。 + +- [ ] **Step 3: 禁止长期 JWT 出现在 query，改用一次性 WebSocket ticket** + +ticket 有效期 60 秒、仅使用一次；日志中不记录 ticket 值。 + +- [ ] **Step 4: 将 AI 流读取移到受限 worker** + +只允许 Go 后端以内部认证创建任务；限制并发、帧数、分辨率、超时和允许的内部地址范围。FastAPI 路由不得在事件循环中直接执行长时间 `VideoCapture.read()`。 + +- [ ] **Step 5: 验证** + +```powershell +go test ./internal/ws -v +Push-Location ai-service; python -m pytest tests/test_api.py -v; Pop-Location +``` + +**Rollback:** 关闭流 AI 功能开关；WebSocket 保留来源和对象授权，不得回滚为 `CheckOrigin=true`。 + +--- + +### Task 6: 修复 AI 风险语义并隔离 Mock 数据 + +**Requirements:** AI-INS-002～004、RISK-001～003 +**Owner:** AI + Go 后端负责人 +**Estimated effort:** 2～3 人日 + +**Files:** +- Modify: `ai-service/app/main.py` +- Modify: `ai-service/app/config.py` +- Modify: `ai-service/tests/test_api.py` +- Modify: `server-go/internal/service/ai_client.go` +- Modify: `server-go/internal/service/risk.go` +- Modify: `server-go/internal/service/risk_test.go` +- Modify: `server-go/internal/handler/inspection.go` +- Modify: `server-go/internal/handler/inspection_test.go` +- Create: `server-go/migrations/000007_inspection_idempotency.up.sql` +- Create: `server-go/migrations/000007_inspection_idempotency.down.sql` +- Modify: `server-go/internal/model/inspection.go` +- Create: `server-go/migrations/000002_risk_assessment.up.sql` +- Create: `server-go/migrations/000002_risk_assessment.down.sql` + +**Interfaces:** +- AI response adds `modelVersion`, `isMock`, `abnormalProbability`。 +- Go produces `RiskAssessment` with score、level、confidence、components、missing、modelVersion、ruleVersion。 + +- [ ] **Step 1: 写关键失败测试** + +```go +func TestHealthyHighConfidenceDoesNotIncreaseRisk(t *testing.T) { + got := AbnormalProbability([]AIDetection{{ClassName: "healthy", Confidence: .95}}) + if got != 0 { t.Fatalf("got %v", got) } +} + +func TestSickHighConfidenceIncreasesRisk(t *testing.T) { + got := AbnormalProbability([]AIDetection{{ClassName: "sick", Confidence: .9}}) + if got != .9 { t.Fatalf("got %v", got) } +} +``` + +- [ ] **Step 2: 扩展 AI 响应并明确异常类别集合** + +二分类 `sick` 和多病种中除 `healthy` 外的已配置异常类别贡献风险；空检测返回 unknown，不自动当健康。 + +- [ ] **Step 3: 用可空组件计算风险** + +```go +type RiskInput struct { + AI, Env, Stage, Uniformity *float64 +} +type RiskAssessment struct { + Score float64; Level, Confidence, RuleVersion string + Components map[string]*float64; Missing []string +} +``` + +缺失组件不填 0；V2 规则将可用权重归一化，并把 confidence 降为 low/medium。具体权重先沿用 0.5/0.2/0.15/0.15，标记为待试点校准规则而非科学事实。 + +- [ ] **Step 4: 持久化输入快照、模型/规则版本和 mock 标识** + +Mock 记录可保存供联调，但查询统计默认排除；生产环境收到 `isMock=true` 时记录失败并告警。 + +- [ ] **Step 5: 评估历史数据** + +生成只读 SQL 报告统计历史 `healthy` 高置信度记录及其风险等级；未经人工确认不得批量重算或覆盖。 + +- [ ] **Step 6: 验证** + +```powershell +go test ./internal/service -run "Risk|Abnormal" -v +go test ./internal/handler -run Inspection -v +Push-Location ai-service; python -m pytest -v; Pop-Location +``` + +**Rollback:** 功能开关回退到只展示 AI 原始结果、不计算综合风险；不得恢复错误的最大置信度算法。 + +--- + +### Task 7: 修订 qPCR 判读与检测质控 + +**Requirements:** DET-003～005 +**Owner:** 后端负责人 + 领域专家 +**Estimated effort:** 1～2 人日 + +**Files:** +- Modify: `server-go/internal/model/molecular.go` +- Modify: `server-go/internal/model/molecular_test.go` +- Modify: `server-go/internal/model/lamp.go` +- Modify: `server-go/internal/handler/lamp.go` +- Modify: `web/src/dal/lamp.ts` +- Modify: `web/src/pages/LampTests.tsx` +- Create: `server-go/migrations/000003_detection_qc.up.sql` +- Create: `server-go/migrations/000003_detection_qc.down.sql` + +**Interfaces:** +- Produces: `JudgeQPCR(input QPCRJudgeInput) QPCRJudgeResult`。 + +```go +type QPCRJudgeInput struct { + TargetCt *float64 + InternalControlCt *float64 + PositiveControlValid bool + NegativeControlValid bool + ProtocolVersion string + Threshold float64 +} +``` + +- [ ] **Step 1: 由领域专家签字确认首个 protocolVersion 与阈值适用范围** + +未确认前功能只能保存原始数据，不能自动输出阴性/阳性。 + +- [ ] **Step 2: 写表驱动测试** + +覆盖：阳性、阴性、缺 Ct、内参失败、阳性对照失败、阴性对照污染、临界值和未知 protocol。 + +- [ ] **Step 3: 实现四态结果** + +```text +positive / negative / invalid / indeterminate +``` + +无 Ct 仅在对照和内参有效且方案明确允许时判 negative；其他情况为 invalid/indeterminate。 + +- [ ] **Step 4: UI 强制填写质控字段并展示判读依据，不允许把 invalid 显示为阴性** + +- [ ] **Step 5: 验证** + +```powershell +go test ./internal/model -run QPCR -v +go test ./internal/handler -run QPCR -v +Push-Location web; npm test; npm run lint; npm run build; Pop-Location +``` + +**Rollback:** 回退为“只录入、不自动判读”，保留原始 Ct 和质控数据。 + +--- + +### Task 8: 建立可靠通知、吊销与跨实例状态 + +**Requirements:** IAM-001、MSG-001、MSG-002 +**Owner:** 后端 + 运维 +**Estimated effort:** 3～5 人日 + +**Files:** +- Create: `server-go/internal/model/notification.go` +- Create: `server-go/internal/service/outbox.go` +- Create: `server-go/internal/service/outbox_test.go` +- Modify: `server-go/internal/handler/notification.go` +- Modify: `server-go/internal/middleware/token_blacklist.go` +- Modify: `server-go/internal/middleware/ratelimit.go` +- Create: `server-go/migrations/000004_notifications_outbox.up.sql` +- Create: `server-go/migrations/000004_notifications_outbox.down.sql` +- Modify: `server-go/cmd/server/main.go` + +**Interfaces:** +- Produces: `Outbox.PublishTx(tx *gorm.DB, event Event) error`。 +- Notification states: `pending/sending/sent/retry/failed/cancelled`。 + +- [ ] **Step 1: 写测试证明服务重启后 pending 事件仍可处理，重复 eventId 不重复发送** + +- [ ] **Step 2: 业务事务内写 outbox，worker 领取、发送、退避重试并记录最终失败** + +- [ ] **Step 3: 将 token 吊销和登录限流迁移到 Redis** + +Redis 不可用时：生产登录/刷新采取保守失败；已认证的只读请求按安全评审决定降级，不得静默切回单机内存。 + +- [ ] **Step 4: 微信发送保存模板、用户授权、响应码和重试结果** + +- [ ] **Step 5: 验证并进行进程重启测试** + +```powershell +go test ./internal/service ./internal/middleware ./internal/handler -run "Outbox|Notification|Revok|Rate" -v +go test ./... +``` + +**Rollback:** 暂停 worker 保留 outbox 数据；恢复旧读接口时不得删除未发送事件。 + +--- + +### Task 9: 建立统一检测任务、样本链与发病事件 + +**Requirements:** DET-001/002/006、TRACE-001 +**Owner:** 后端 + Web + 小程序负责人 +**Estimated effort:** 5～8 人日 + +**Files:** +- Create: `server-go/internal/model/detection_task.go` +- Create: `server-go/internal/model/sample.go` +- Create: `server-go/internal/model/disease_event.go` +- Create: `server-go/internal/handler/detection_task.go` +- Create: `server-go/internal/handler/detection_task_test.go` +- Modify: `server-go/internal/handler/inspection.go` +- Modify: `server-go/internal/handler/trace.go` +- Create: `server-go/migrations/000005_detection_disease_events.up.sql` +- Create: `server-go/migrations/000005_detection_disease_events.down.sql` +- Create: `web/src/dal/detectionTask.ts` +- Create: `web/src/pages/DetectionTasks.tsx` +- Modify: `web/src/router.tsx` + +**Interfaces:** +- DetectionTask states: `draft/pending/assigned/sampling/testing/review/completed/cancelled`。 +- Sample states: `created/collected/handed_over/received/testing/consumed/disposed`。 +- DiseaseEvent states: `suspected/confirmed/controlled/closed/reopened`。 + +- [ ] **Step 1: 写状态机和幂等失败测试** + +```go +func TestDetectionTaskRejectsInvalidTransition(t *testing.T) +func TestOrangeInspectionCreatesOnlyOnePendingTask(t *testing.T) +func TestDiseaseEventRequiresEvidenceToConfirm(t *testing.T) +``` + +- [ ] **Step 2: 实现实体、外键、唯一业务键和状态转换服务** + +- [ ] **Step 3: 橙色巡检通过 outbox 创建“待确认”任务，不能直接指派或视为已检测** + +- [ ] **Step 4: 检测有效阳性或专家确认后创建 DiseaseEvent，TraceRecord 改为关联 DiseaseEvent** + +- [ ] **Step 5: Web 提供任务列表、分派、采样交接、检测和复核视图** + +- [ ] **Step 6: 验证完整 API 流程和重复请求** + +```powershell +go test ./internal/model ./internal/service ./internal/handler -run "DetectionTask|Sample|DiseaseEvent" -v +Push-Location web; npm test; npm run lint; npm run build; Pop-Location +``` + +**Rollback:** 关闭自动建单开关，保留新表数据；旧 LAMP 记录继续只读，禁止删除已建立关联。 + +--- + +### Task 10: 补齐消毒、种源与二维码身份链 + +**Requirements:** FARM-002、FARM-004、FARM-005、TRACE-007 +**Owner:** 后端 + Web + 小程序负责人 +**Estimated effort:** 4～6 人日 + +**Files:** +- Create: `server-go/internal/model/biosecurity.go` +- Create: `server-go/internal/handler/biosecurity.go` +- Create: `server-go/internal/handler/biosecurity_test.go` +- Create: `server-go/migrations/000006_biosecurity.up.sql` +- Create: `server-go/migrations/000006_biosecurity.down.sql` +- Create: `web/src/dal/biosecurity.ts` +- Create: `web/src/pages/Biosecurity.tsx` +- Create: `miniapp/src/api/biosecurity.ts` +- Create: `miniapp/src/pages/biosecurity/index.tsx` +- Modify: `miniapp/src/app.config.ts` + +**Interfaces:** +- QR payload only contains opaque `entityType`、`publicId`、校验版本，不包含密码、内部自增 ID 或个人信息。 + +- [ ] **Step 1: 写测试覆盖二维码篡改、跨组织访问、种源链循环和消毒记录必填项** + +- [ ] **Step 2: 实现 SeedSource、DisinfectionRecord、二维码解析与对象授权** + +- [ ] **Step 3: Web 提供来源/凭证/消毒计划与执行；小程序提供扫码和现场执行** + +- [ ] **Step 4: 溯源初报消费种源和消毒数据，缺失时明确显示“证据不足”** + +- [ ] **Step 5: 验证** + +```powershell +go test ./internal/handler ./internal/service -run "Biosecurity|SeedSource|Disinfection|QRCode" -v +Push-Location web; npm run build; Pop-Location +Push-Location miniapp; npm run typecheck; npm run build:weapp; Pop-Location +``` + +**Rollback:** 隐藏页面入口并停止新增写入，保留已产生的种源/消毒/二维码映射。 + +--- + +### Task 11: 实现小程序离线巡检与可靠同步 + +**Requirements:** AI-INS-005、9.4 弱网要求 +**Owner:** 小程序 + Go 后端负责人 +**Estimated effort:** 4～6 人日 + +**Files:** +- Create: `miniapp/src/services/offlineQueue.ts` +- Create: `miniapp/src/services/offlineQueue.test.ts` +- Modify: `miniapp/src/pages/inspection/index.tsx` +- Modify: `miniapp/src/api/inspections.ts` +- Modify: `miniapp/src/store/useStore.ts` +- Modify: `server-go/internal/handler/inspection.go` +- Modify: `server-go/internal/handler/inspection_test.go` + +**Interfaces:** +- Queue item states: `pending/uploading/synced/conflict/failed`。 +- Idempotency key: 客户端生成 UUID，创建后永不变化，重试复用。 + +- [ ] **Step 1: 写队列单测** + +覆盖断网入队、重启恢复、重复点击、指数退避、成功删除本地图片引用、永久失败和冲突展示。 + +- [ ] **Step 2: 实现本地持久队列，限制容量并显示剩余空间** + +- [ ] **Step 3: 网络恢复后串行上传，401 先刷新令牌，5xx/超时重试，4xx 进入人工处理** + +- [ ] **Step 4: 服务端幂等键增加用户作用域，避免不同用户键碰撞** + +唯一约束改为 `(user_id, idempotency_key)`，使用 `000007_inspection_idempotency` 迁移；先扫描并处理既有冲突，迁移不得静默删除记录。 + +- [ ] **Step 5: 在开发者工具模拟离线—重启—联网流程并保存截图/日志证据** + +```powershell +Push-Location miniapp; npm run typecheck; npm run build:weapp; Pop-Location +go test ./internal/handler -run Inspection -v +``` + +**Rollback:** 关闭离线入口，只允许在线提交；服务端幂等改动保留，避免重复数据回归。 + +--- + +### Task 12: 完善环境规则、会诊治理、知识审核与效果评估 + +**Requirements:** ENV-003～005、EXP-002～005、KB-001/002、ANA-001/002 +**Owner:** 后端 + Web + 领域专家 + 测试负责人 +**Estimated effort:** 5～8 人日 + +**Files:** +- Create: `server-go/internal/model/governance.go` +- Create: `server-go/internal/service/rule_engine.go` +- Create: `server-go/internal/service/rule_engine_test.go` +- Modify: `server-go/internal/service/weather_risk.go` +- Modify: `server-go/internal/model/consultation.go` +- Modify: `server-go/internal/handler/consultation.go` +- Modify: `server-go/internal/handler/consultation_test.go` +- Modify: `server-go/internal/model/knowledge.go` +- Modify: `server-go/internal/handler/knowledge.go` +- Modify: `server-go/internal/service/health_profile.go` +- Modify: `server-go/internal/service/health_profile_test.go` +- Create: `server-go/migrations/000008_governance_effectiveness.up.sql` +- Create: `server-go/migrations/000008_governance_effectiveness.down.sql` +- Modify: `web/src/pages/Consultations.tsx` +- Modify: `web/src/pages/Knowledge.tsx` +- Modify: `web/src/pages/Traces.tsx` + +**Interfaces:** +- Produces: `EvaluateRules(ctx RuleContext, rules []RuleVersion) []RuleResult`。 +- Consultation states: `unassigned/assigned/accepted/needs_info/resolved/archived`。 +- Knowledge states: `draft/review/published/withdrawn`。 +- Produces: `EvaluateControlEffect(eventID string, window EffectWindow) EffectReport`。 + +- [ ] **Step 1: 写规则时窗与缺失数据测试** + +```go +func TestRuleRequiresThreeContinuousDaysOfHumidity(t *testing.T) +func TestStaleTelemetryIsReportedMissing(t *testing.T) +func TestRuleResultKeepsInputAndVersion(t *testing.T) +``` + +规则输出必须保存版本、输入时间窗、命中项、缺失项和计算时间；单个最新值不得冒充连续时窗。 + +- [ ] **Step 2: 实现规则版本和数据新鲜度** + +`RuleContext` 至少包含批次阶段、时间窗遥测、天气、密度、通风、种源和消毒证据。缺失输入降低结论可信度，不填 0。 + +- [ ] **Step 3: 写并实现会诊状态机、SLA 和意见版本测试** + +```go +func TestConsultationRejectsArchiveBeforeResolution(t *testing.T) +func TestConsultationOpinionCreatesNewVersion(t *testing.T) +func TestConsultationSLAMarksOverdue(t *testing.T) +``` + +每次意见修改保留作者、时间、旧版本和原因；超时只产生升级事件，不自动伪造专家结论。 + +- [ ] **Step 4: 增加知识审核与来源字段** + +未发布内容只对有审核权限用户可见；撤回后不在农户端出现，但历史病例引用保留版本快照。 + +- [ ] **Step 5: 实现防控效果评估** + +`EffectReport` 对比处置前后指定窗口的有效巡检风险、有效检测阳性率、复发、死亡/损失和成本；所有缺失维度单独列出，不把缺失当改善。 + +- [ ] **Step 6: Web 完成会诊 SLA、知识审核和效果报告入口** + +- [ ] **Step 7: 验证** + +```powershell +go test ./internal/model ./internal/service ./internal/handler -run "Rule|Consultation|Knowledge|Health|Effect" -v +Push-Location web; npm test; npm run lint; npm run build; Pop-Location +``` + +**Rollback:** 关闭新版规则、SLA 和效果报告入口，保留版本与审核数据；不得覆盖或删除旧专家意见。 + +--- + +### Task 13: 建立可观测性、容量与恢复验证 + +**Requirements:** V2.2 9.1～9.3、10.2 +**Owner:** 运维 + 后端 + 测试负责人 +**Estimated effort:** 4～6 人日 + +**Files:** +- Modify: `server-go/internal/middleware/logger.go` +- Create: `server-go/internal/middleware/request_id.go` +- Modify: `server-go/internal/service/ai_client.go` +- Modify: `ai-service/app/main.py` +- Create: `docs/operations/slo-and-alerts.md` +- Create: `docs/operations/load-test-scenarios.md` +- Create: `docs/operations/backup-restore-drill.md` +- Modify: `部署指南(物理机).md` + +**Interfaces:** +- 每个 HTTP 请求生成/透传 `X-Request-ID`；事件使用 `eventId`；日志字段命名统一。 + +- [ ] **Step 1: 写中间件测试，验证 requestId 响应头、透传和日志脱敏** + +- [ ] **Step 2: 增加依赖指标** + +至少覆盖 PostgreSQL、Redis、MQTT、IoTDB、S3、AI、WVP、微信、天气的请求数、失败数、p95 和积压/容量。 + +- [ ] **Step 3: 定义并执行三类负载场景** + +```text +A. 500 在线用户：80% 查询、10% 遥测趋势、5% 上传、5% 管理操作 +B. 1000 WebSocket 连接：按授权设备订阅，持续 30 分钟 +C. AI 峰值：指定 T4、模型版本、输入尺寸和并发，记录 p50/p95/失败率 +``` + +- [ ] **Step 4: 执行备份恢复演练** + +恢复到隔离数据库/对象存储命名空间；记录备份时间、恢复时间、数据点核对、RPO/RTO 和失败项。 + +- [ ] **Step 5: 建立告警阈值和负责人表，进行一次模拟故障验证通知链** + +**Rollback:** 指标与 requestId 可保持；高开销采样可降低频率，不得删除备份恢复记录。 + +--- + +### Task 14: 建立规格追踪、端到端验收与发布门禁 + +**Requirements:** V2.2 第 10～12 章 +**Owner:** 测试负责人 + 项目负责人 +**Estimated effort:** 3～5 人日 + +**Files:** +- Create: `docs/acceptance/requirements-traceability.md` +- Create: `docs/acceptance/core-e2e-cases.md` +- Create: `docs/acceptance/release-checklist.md` +- Modify: `蚕病智能防控平台规格说明书_V2.2.md` +- Modify: `后续工作计划.md` +- Modify: `开发交接记录.md` + +**Interfaces:** +- Traceability columns: Requirement ID、实现、自动测试、手工用例、环境、证据、状态、限制、负责人。 + +- [ ] **Step 1: 为 Wave 1～3 的每个需求 ID 建立追踪行，不允许只写模块名** + +- [ ] **Step 2: 编写核心端到端用例** + +至少覆盖： + +```text +1. healthy 图片 → 低风险/不触发检测 +2. sick 图片 → 橙色 → 仅一个待确认任务 +3. AI 失败 → 可重试且无虚假风险 +4. qPCR 对照失败 → invalid → 不确诊 +5. 有效阳性 → DiseaseEvent → 自动溯源初报 +6. 无权用户访问视频/设备/WebSocket → 403 +7. 离线巡检 → 重启 → 联网 → 仅同步一次 +8. 通知发送失败 → 重试 → 最终状态可查 +9. 服务重启 → 任务/通知/吊销状态保持 +10. 备份恢复 → 核心记录与对象引用核对通过 +``` + +- [ ] **Step 3: 在目标环境执行全量质量门禁和端到端用例** + +```powershell +powershell -ExecutionPolicy Bypass -File scripts/verify.ps1 +git diff --check +``` + +- [ ] **Step 4: 按 AGENTS.md 完成开发服务器备份、部署、健康检查、冒烟和回滚点记录** + +- [ ] **Step 5: 更新能力状态** + +只有附有测试/环境/日期证据的功能才能从“部分可用”改为“可验收/已验证”。 + +**Rollback:** 使用发布前 tag/commit、数据库 dump、旧二进制和旧 dist；回滚后重新执行健康检查并记录原因。 + +--- + +## 2. 不纳入本轮整改的事项 + +以下能力保留在 V2.2 阶段 D/E，不得为了展示进度插入 Wave 1～3： + +- 7 类病种真实模型训练与发布。 +- 固定摄像头群体巡检和个体追踪。 +- LAMP 图像自动判读。 +- SERS/高光谱自动分析和方法学结论。 +- 区域传播预测模型和数字孪生自动控制。 +- 未经确认的 APP 全量蚕病功能同步。 + +## 3. 合并与发布顺序 + +```text +Task 0 决策 + ↓ +Task 1 质量基线 ── Task 2 迁移基线 + ↓ ↓ +Task 3 配置安全 Task 6/7 数据语义 +Task 4 视频安全 Task 8 可靠事件 +Task 5 WS/AI 安全 ↓ + └──────────────→ Task 9 检测/发病主链 + ↓ + Task 10 生物安全链 + Task 11 离线同步 + ↓ + Task 12 规则/治理/效果 + ↓ + Task 13 运维验证 + ↓ + Task 14 总体验收 +``` + +Task 3～5 可以分别评审，但必须在 Wave 1 集成分支统一执行安全回归。Task 6～12 每个 schema 变更必须基于 Task 2 的迁移机制顺序编号，禁止多人自行创建冲突编号。 + +## 4. 计划自检清单 + +- [ ] V2.2 的 P0 问题均映射到 Task 2～7。 +- [ ] 业务可靠性和治理问题映射到 Task 8～13。 +- [ ] 每个任务有负责人、文件、接口、测试、验证和回滚。 +- [ ] 未擅自确定迁移工具、CI 平台、云服务和 qPCR 医学/检疫规则。 +- [ ] 不包含手改生成产物或在服务器直接修源码的步骤。 +- [ ] 每项部署均要求备份、健康检查、冒烟和回滚记录。 +- [ ] 研究能力与近期整改明确分离。 + +## 5. 交付节奏建议 + +- 每个 Task 一个独立分支/PR；分支前缀使用 `codex/` 或团队既有规范。 +- Task 3～7 每完成一项立即做针对性安全/业务回归，不等待大版本集中验证。 +- 每周更新追踪矩阵和风险清单；只汇报有证据的状态变化。 +- Wave 1 完成后再开始 Wave 3 业务扩展；P0 未关闭时不部署新增研究功能。 +- 每次评审先看测试失败/通过证据，再看代码；每次发布先看回滚点，再执行覆盖操作。 diff --git a/项目现状与规格说明书优化分析.md b/项目现状与规格说明书优化分析.md new file mode 100644 index 0000000..9478707 --- /dev/null +++ b/项目现状与规格说明书优化分析.md @@ -0,0 +1,404 @@ +# 智慧蚕房项目现状与《蚕病智能防控平台规格说明书》优化分析 + +> 分析日期：2026-08-13 +> 分析对象：当前仓库、`.cc-connect/attachments/蚕病智能防控平台规格说明书.md`（V2.1）、`README.md`、`后续工作计划.md`、`开发交接记录.md` 及各端核心源码 +> 结论属性：基于当前代码与本地验证结果的阶段性评审，不等同于生产安全审计、算法效果验收或领域专家医学/检疫结论 + +## 1. 执行摘要 + +### 1.1 总体结论 + +项目已经从单纯的环境监控系统扩展为覆盖环境监测、设备控制、视频、AI 拍照巡检、分子检测、专家会诊、知识库、疫病溯源和区域统计的多端平台，功能广度较高，Go 后端的模块化和 RBAC 基础也已形成。 + +但当前仍应定义为“功能演示与试点验证阶段”，不宜直接按规格书 V2.1 宣称核心目标全部完成或进入生产验收，主要原因如下： + +1. **规格书已落后于实现架构。** 规格书写的是 Vue3 + Python/FastAPI 主后端 + TDengine + MinIO + MobileNet/SSD + 端侧推理；仓库实际是 React + Go/Gin 主后端 + Python AI 微服务 + IoTDB + Ceph/规划中的云对象存储 + YOLOv8 ONNX + 云端推理。 +2. **“完成”状态混入了骨架、mock、手工录入和接口预留。** 例如真实 AI 模型尚未接入，摄像头巡检只有抽帧接口骨架，高光谱只有类型预留，微信和天气依赖真实凭证，SERS/qPCR 主要是录入与文件上传，不是设备闭环。 +3. **存在必须先处理的安全与业务正确性问题。** 包括仓库内可用的默认密钥/口令、公开的视频流接口、摄像头口令随 API 返回、WebSocket 越权面，以及风险分把“健康类别的高置信度”误当作“高患病概率”。 +4. **工程质量与目标态不匹配。** 数据库依赖 AutoMigrate 且忽略迁移错误；通知、令牌黑名单和部分运行状态保存在单机内存；缺少 CI、端到端/负载/安全测试和可观测性闭环。 +5. **规格书的验收标准不足以约束研发。** 缺少需求编号、实现状态、接口 schema、异常流程、数据质量、算法数据集切分规则、模型版本治理、RTO/RPO、审计与隐私边界。 + +### 1.2 建议的总体策略 + +建议按以下顺序推进，而不是继续横向增加功能： + +1. **先止血：** 修复安全暴露、风险评分语义、qPCR 判读边界和小程序类型错误。 +2. **再校准：** 发布规格书 V2.2，把“目标态、当前态、验收态”分开，建立需求—代码—测试追踪矩阵。 +3. **补闭环：** 完成自动检测任务、离线同步、消毒与种源链、可靠消息、模型/数据治理。 +4. **后扩展：** 再投入固定摄像头巡检、LAMP 图像判读、区域流行病学、数字孪生和多模态早期预警。 + +## 2. 分析范围、方法与限制 + +### 2.1 已检查的主要证据 + +- 规格与规划：规格说明书 V2.1、`后续工作计划.md`、`README.md`、`开发交接记录.md`、部署与故障排查文档。 +- 后端：路由注册、认证与权限、配置、数据库模型与迁移、巡检、风险评分、分子检测、溯源、视频、WebSocket、通知和 AI 客户端。 +- 前端：Web、微信小程序、React Native APP 的页面/API 结构、依赖、脚本与测试配置。 +- AI 服务：FastAPI 接口、mock/ONNX 检测器、流抽帧骨架、指标接口和测试。 +- 本地验证：Go 测试与 vet、Web 测试与 lint、AI pytest、APP 脚本、小程序 TypeScript 检查。 + +### 2.2 证据限制 + +- 项目要求优先使用 codebase-memory 知识图谱，但本会话未提供 `search_graph`、`trace_path`、`check_index_coverage` 等接口，因此本次按项目约定退回到目标源码读取和精确文本检索。 +- 未连接开发服务器、数据库、IoTDB、MQTT、WVP/ZLM、Ceph、微信、天气服务或真实 GPU 模型，不能把本地静态检查当成联调或生产验收。 +- 未执行依赖漏洞数据库扫描、渗透测试、负载测试、恢复演练和算法数据集审计。 + +## 3. 当前项目能力画像 + +| 模块 | 当前状态 | 已具备能力 | 关键缺口 | +|---|---|---|---| +| 环境监测与设备控制 | 可用基础较完整 | MQTT、IoTDB/PG 降级、阈值告警、设备控制、WebSocket | 数据新鲜度与质量标识不足；设备级授权不足；缺少校准/维护计划 | +| 视频监控 | 基础可用 | GB28181/WVP/ZLM、直播、录像、告警片段 | 视频流公开；摄像头密钥返回；运行状态部分内存化；代理超时与并发治理不足 | +| AI 拍照巡检 | **骨架/联调态** | 图片上传、AI HTTP 接口、记录、风险分级、幂等 | 默认 mock；真实模型未验收；非端侧推理；风险概率语义错误；无整齐度数据；无离线队列 | +| 蚕匾/批次/饲养 | 部分可用 | Tray/Batch/RearingRecord CRUD | 缺消毒记录、蚕种来源链、死亡/淘汰/产量、样本链路和二维码身份 | +| 天气与阶段风险 | 骨架可用 | 天气接口、定时规则、阶段提示 | 真实凭证缺失；连续 3 天等时窗规则未完整实现；规则版本不可追踪 | +| LAMP/qPCR/SERS/高光谱 | 流程录入态 | LAMP 任务与步骤、结果照片、Ct 判读、光谱上传、推荐规则 | LAMP AI 判读未做；设备自动回传未做；qPCR 对照/无效态不足；高光谱仅预留 | +| 专家会诊 | 表单流程可用 | 病例快照、状态流转、方案归档 | 无实时协作、SLA/排班、消息可靠性、专家签名与版本留痕 | +| 疫病溯源 | v1 规则态 | 环境回溯、同房间历史、排查清单、区域/月度统计 | 缺独立发病事件模型、空间传播、样本/种源链、三级实验室结构化数据 | +| 知识库 | 基础可用 | 病种、文章、阶段提示、图片上传 | 内容证据等级、审核发布、版本、专家经验沉淀和素材质量不足 | +| 数据分析 | 初版可用 | 健康画像、月度统计、区域柱/饼图 | 健康分未经验证；缺处置效果、损失/成本、地图、队列趋势和数据导出 | +| 多端体验 | 不一致 | Web 功能最全，小程序覆盖核心现场流程，APP 覆盖环境监控 | APP 未同步蚕病功能；小程序离线能力未实现；测试覆盖严重不均衡 | + +## 4. 规格说明书 V2.1 需要优化的地方 + +### 4.1 先解决“目标架构与实际架构冲突” + +规格书第 5、6 章与当前仓库有多处直接冲突： + +| 主题 | 规格书 V2.1 | 当前项目/已作决策 | V2.2 建议 | +|---|---|---|---| +| Web 技术 | Vue3 + Element Plus | React + Ant Design | 改为 React 现状；若保留 Vue 只作为已否决方案写入 ADR | +| 主后端 | Python + FastAPI | Go/Gin/GORM 主业务 + FastAPI AI 微服务 | 明确混合架构及服务边界 | +| 时序库 | TDengine | MVP 沿用 IoTDB，PG 降级；TDengine 是候选 | 写明当前决定、切换触发条件和迁移策略 | +| 对象存储 | MinIO 本地 | 当前 Ceph S3；生产规划 OSS/COS | 区分开发现状和生产目标态 | +| AI 模型 | SSD-MobileNet + MobileNetV3 | YOLOv8s 二分类路线，ONNX 服务端推理 | 以当前训练路线为基线，旧路线进入备选/历史决策 | +| 推理位置 | 小程序端侧优先 | 当前图片上传到 Go，再调用 AI 服务 | 端侧推理改为后续能力，补模型兼容与更新机制后再验收 | +| 消息队列 | Redis + Celery | Go 定时协程/异步 goroutine，通知部分内存存储 | 写清当前无可靠任务队列，不应宣称已有 | + +建议新增“架构决策记录”附录，至少记录：混合后端、IoTDB 延续、云对象存储、云 GPU、YOLO 路线、端侧推理延期。每项包含决策日期、备选方案、理由、影响和复审条件。 + +### 4.2 给每条需求增加可追踪标识 + +当前功能表只有名称和 P0/P1/P2，无法稳定映射代码、接口和测试。建议使用如下结构： + +| 字段 | 示例 | +|---|---| +| 需求 ID | `AI-INS-001` | +| 用户故事/目的 | 农户上传巡检图后获得可解释的风险结果 | +| 前置条件 | 已登录、有 `inspection:create`、房间存在 | +| 正常流程 | 上传—存储—推理—评分—落库—通知 | +| 异常流程 | 图片无效、存储失败、AI 超时、重复请求、离线待同步 | +| 输入/输出 | 字段、类型、枚举、单位、范围、样例 | +| 权限与数据范围 | 角色权限 + 组织/区域/房间范围 | +| 验收标准 | 可自动测试的 Given/When/Then | +| 当前状态 | 未开始/骨架/mock/手工录入/部分可用/可验收/已验证 | +| 证据 | API、页面、测试、监控、发布记录 | + +`后续工作计划.md` 中不应再用一个勾选框同时表达“骨架完成”和“功能完成”。建议采用上述七态模型，并增加“真实依赖是否已联调”字段。 + +### 4.3 重写 AI 验收标准 + +“准确率 ≥80%”不足以约束蚕病筛查系统，尤其在健康样本远多于患病样本时会产生虚高结果。V2.2 至少应规定： + +- 按养殖场、批次、拍摄日期或原始图分组切分 train/validation/test，增强副本不得跨集合。 +- 同时报告每类 precision、recall、F1、混淆矩阵、PR-AUC、漏诊率和置信度校准；核心筛查以患病召回率和漏诊率优先。 +- 测试集版本、数据来源、设备型号、光照、龄期、季节、病种确诊依据必须可追溯。 +- 明确“healthy/sick 二分类基线”和“7 类病种模型”是两个验收阶段，不能用二分类结果替代病种分类完成度。 +- 明确模型版本、阈值、标签集、训练代码版本、ONNX 校验结果、回滚版本和灰度范围。 +- 对 mock、研究原型和生产模型的 UI 标识做强制要求，禁止 mock 结果被误当成诊断数据。 + +### 4.4 修订风险评分定义 + +规格书把“AI 识别置信度”直接写入公式，但没有定义它是健康置信度、异常概率、最大病种概率还是校准后的风险概率。当前实现因此出现实际逻辑错误：`healthy=0.95` 也会贡献 47.5 分。 + +建议 V2.2 改为： + +```text +AI 异常风险 = P(sick) 或所有异常病种校准概率之和 +综合风险 = f(AI 异常风险, 环境规则, 龄期, 群体整齐度, 数据新鲜度, 缺失标记) +``` + +并补充以下规则： + +- 健康类别高置信度必须降低风险，而不是提升风险。 +- 数据缺失不能简单当作 0；应返回 `unknown`/低可信度并显示缺失原因。 +- 环境数据必须带采集时间，过期数据不能参与实时评分。 +- 每次评分保存输入快照、规则版本、模型版本和解释项，便于复盘与审计。 +- 风险阈值应通过试点数据校准；规格书使用闭合区间，消除 30～31 等边界歧义。 +- 风险评分只触发“建议动作”，涉及隔离、消毒或设备自动控制时必须配置人工确认和安全上限。 + +### 4.5 修订分子检测规格 + +当前 qPCR 实现把“没有 Ct 值”判为阴性，规格书也没有定义阳性对照、阴性对照、内参、重复孔和无效实验。建议： + +- 结果枚举至少包含 `positive`、`negative`、`invalid`、`indeterminate`。 +- 只有对照有效且目标未扩增时才能判阴性；缺失 Ct、内参失败、曲线异常应判无效或待复核。 +- Ct 阈值应绑定试剂盒/靶标/仪器/实验方案版本，不能使用全局固定 35 作为通用事实。 +- LAMP 增加空白对照、阳性对照、反应温度/时长、试剂批次和操作员记录。 +- SERS/高光谱必须区分“文件上传成功”“算法分析完成”“方法学验证通过”三个阶段。 +- 增加样本编号、采样对象、采样位置、采样时间、运输条件、接收人和流转记录，形成样本链路。 + +### 4.6 完善数据模型与数据治理 + +规格书第 5.1 章包含 `DiseaseRecord`，当前模型没有独立的发病事件实体，TraceRecord 直接关联房间、LAMP 和会诊，导致“确诊事件—处置—损失—复发—溯源”难以形成稳定主线。 + +建议核心链路调整为： + +```text +组织/养殖场 → 蚕房 → 蚕匾 → 饲养批次 + ├─ 日常记录/消毒记录/投入品记录 + ├─ 巡检事件 → 检测任务 → 样本 → 检测结果 + └─ 发病事件 → 处置措施 → 会诊 → 溯源 → 效果评估 +``` + +同时补充： + +- 数据所有者、组织/区域数据隔离、保留期限、删除/匿名化规则。 +- 图片、视频、光谱、模型训练数据的授权用途和导出控制。 +- 数据字典：单位、枚举、空值语义、时间时区、来源和质量标识。 +- 规则、知识文章、专家结论和模型输出的版本与审核状态。 +- 训练数据从业务数据进入标注集的审批、脱敏、质检和撤回流程。 + +### 4.7 扩展接口设计 + +第 8 章目前只有协议级概述，不能直接用于联调。建议单独维护 OpenAPI 文档，并在规格书中定义： + +- 统一响应与错误码、分页、排序、过滤、幂等、并发更新版本号。 +- 请求/响应 schema、枚举、单位、最大文件大小和示例。 +- 鉴权方式、权限码、组织/房间数据范围和审计事件。 +- 外部设备的签名、重放保护、时间戳、设备身份、重试与死信策略。 +- AI、天气、微信、WVP、对象存储等依赖的超时、熔断、降级和补偿行为。 +- API 版本兼容、废弃策略和客户端最低版本。 + +### 4.8 扩展非功能性需求 + +V2.1 只有少量性能、可用性和安全条目。建议增加： + +| 类别 | 必须补充的内容 | +|---|---| +| 可用性 | SLI/SLO、依赖降级、维护窗口、故障演练、单点清单 | +| 灾备 | RPO、RTO、备份保留、异地副本、季度恢复演练和恢复验收 | +| 性能 | 明确数据量、并发模型、p95/p99、冷/热缓存、视频与图片带宽 | +| 安全 | 密钥管理、强制改密、最小权限、对象级授权、文件扫描、审计保留 | +| 隐私 | 个人信息清单、处理目的、最小收集、脱敏、导出/删除流程 | +| 可观测性 | 请求 ID、结构化日志、指标、追踪、业务告警、模型与数据漂移 | +| 兼容性 | 微信基础库、Android/iOS、浏览器、弱网和低端设备矩阵 | +| 可维护性 | 版本化数据库迁移、CI 质量门禁、依赖升级、配置校验和回滚 | +| AI 治理 | 模型卡、数据卡、版本、阈值、灰度、回滚、人工复核和申诉机制 | + +### 4.9 给技术与产业数据增加来源等级 + +规格书包含准确率、设备价格、单次成本、研究年份、传播周期和推广事件等具体陈述，但没有参考文献或采集日期。建议每条事实标注：来源链接/文献、发布日期、访问日期、证据等级、适用范围和是否经领域专家确认。价格与产业状态应设有效期，避免长期成为“固定事实”。 + +## 5. 当前项目问题清单 + +### 5.1 P0：发布前必须处理 + +#### P0-1 风险评分把健康置信度当患病概率 + +- 证据：`server-go/internal/handler/inspection.go` 取所有 detection 的最大 `confidence`；`server-go/internal/service/risk.go` 将其作为 AI 风险直接加权。 +- 影响：mock 默认返回 `healthy=0.95`，仅 AI 项即为 47.5 分，产生黄色预警；真实二分类模型同样可能把“非常健康”算成高风险。健康画像、微信推送、统计和溯源触发都会被污染。 +- 方案：AI 响应增加类别概率或明确的 `abnormalProbability`；风险层只消费异常概率；增加 healthy 高置信度、sick 高置信度、多框混合、无检测和模型失败测试；修复前隔离 mock 数据或增加 `isMock` 标识。 + +#### P0-2 仓库内存在可直接使用的默认密钥与口令 + +- 证据：`server-go/internal/config/config.go` 内含数据库、Redis、MQTT、S3、ZLM、内部 API、JWT 和管理员默认值；小程序和 APP 登录页预填默认管理员密码。 +- 影响：环境变量漏配时系统会以已知凭据启动；历史凭据可能已进入部署环境；客户端预填进一步放大弱口令风险。 +- 方案：敏感配置改为生产环境必填并在启动时校验；默认只允许显式的本地开发 profile；轮换所有已提交过的密钥；管理员首次启动一次性初始化并强制改密；客户端不预填密码。 + +#### P0-3 视频流绕过 JWT，摄像头与 SIP 密码可被 API 返回 + +- 证据：`server-go/internal/middleware/auth.go` 放行录像流和直播流；`server-go/internal/handler/video_stream.go` 明确注册为公开接口；`Camera.PasswordEnc`、`Camera.GbAuthPassword` 有 JSON 字段，列表/详情直接返回模型；WVP 配置接口返回 `sipPassword`。 +- 影响：知道或枚举 ID 即可能观看录像/直播；拥有普通 `video:read` 的用户可获得摄像头/SIP 凭据，造成隐私、设备接管和横向移动风险。 +- 方案：恢复 JWT 与对象级授权，或使用短时签名 URL/一次性播放令牌；所有密钥字段 `json:"-"` 并使用专门 DTO；WVP 配置接口只返回硬件配置所需的非敏感信息；审计所有播放和凭据操作。 + +#### P0-4 数据库迁移失败不阻断启动 + +- 证据：`server-go/internal/database/db.go` 使用 `AutoMigrate`，错误被记录为“可忽略”后继续启动。 +- 影响：代码与 schema 不一致时服务仍对外提供 API，可能在运行期丢字段、写入失败或产生半迁移状态。 +- 方案：引入可回滚、可审计的版本化迁移；生产禁止自动迁移；启动前检查 schema 版本，不一致则失败；备份与迁移验收进入发布门禁。具体迁移工具需在实施前确认。 + +#### P0-5 小程序当前 TypeScript 检查失败 + +- 证据：`miniapp/src/pages/dashboard/index.tsx:288` 和 `:350` 的 JSX 文本包含未转义 `>`，`npx tsc --noEmit` 返回 TS1382。 +- 影响：类型质量门禁无法通过，不同编译器/升级版本下可能阻断构建。 +- 方案：使用 `{'>'}`、`>` 或统一箭头图标；把 `tsc --noEmit` 加入小程序 CI。 + +#### P0-6 qPCR “无 Ct 即阴性”存在错误判读风险 + +- 证据：`server-go/internal/model/molecular.go` 在 Ct 数组为空时直接返回 negative。 +- 影响：缺数据、实验失败、内参失败或未录入都可能被误记为阴性，影响交叉验证和防控决策。 +- 方案：增加对照与内参字段以及 invalid/indeterminate 状态；判读规则按试剂/靶标版本配置并由领域专家审核。 + +### 5.2 P1：进入稳定试点前处理 + +#### P1-1 WebSocket 缺少来源和对象级授权 + +- `CheckOrigin` 始终返回 true；JWT 可经 query 传输，可能进入代理日志；任意已登录用户可订阅任意 `deviceKey`，并收到全局 `telemetry.all` 和设备状态。 +- 建议限制 Origin，优先使用安全握手/短时票据，按用户可访问的组织/房间/设备校验订阅，并停止无范围的全局广播。 + +#### P1-2 ai-service 的流接口存在 SSRF 和阻塞风险 + +- `/stream-detect` 接受任意 URL，服务端直接 `VideoCapture`；异步路由中执行同步视频 I/O；无来源白名单、私网地址限制、帧尺寸/时长/并发限制和服务认证。 +- 建议禁止客户端直接传任意 URL，改传 `cameraId/taskId`，由 Go 后端解析授权后的内部流；用任务队列和 worker 执行，设置超时、并发、帧率和资源配额；AI 服务只允许 VPC 内认证调用。 + +#### P1-3 消息、吊销和任务状态不持久 + +- 通知列表、JWT 吊销、登录限流和活跃录制包含单机内存状态；重启或多实例会丢失/不一致。 +- 建议把需要跨实例一致性的状态迁移到 Redis/数据库；通知采用 outbox + 重试 + 状态机；业务写入和事件产生保持可追踪。 + +#### P1-4 规格动作没有自动形成闭环 + +- 规格书要求橙灯自动生成分子检测任务、红灯触发专家会诊；当前巡检代码主要做评分、记录和微信推送，没有自动创建 LAMP/DetectionTask 或 Consultation。 +- 建议新增统一 `DetectionTask`，把“推荐方式”和“实际执行方式”分开；事件处理必须幂等；自动触发后允许技术员确认、改派和取消，并记录原因。 + +#### P1-5 环境风险规则被过度简化 + +- 当前只读取最新温湿度，未完整实现连续 3 天高湿、温度突变窗口、通风、桑叶潮湿、蚕头密度、消毒和种源条件；缺失数据被当成 0 风险。 +- 建议建立带时间窗和版本的规则引擎，输入包含来源、时间和质量；规则输出保存命中条件和缺失项。 + +#### P1-6 缺少正式的发病事件、消毒与种源链 + +- 当前 TraceRecord 不是完整 DiseaseEvent；批次虽有来源字段，但没有供应商/蚕种批号/检疫证/跨批次链路，也没有消毒计划、执行、药剂、浓度和复核。 +- 建议优先补齐这些基础数据，否则微粒子病追溯、内源/外源判断和防控效果评估缺少可信输入。 + +#### P1-7 多端功能与测试不均衡 + +- Web 有 1 个测试文件、3 个测试；APP 和小程序未发现测试文件；APP 当前本机缺少 TypeScript/ESLint 可执行依赖，无法验证；AI 本机缺 FastAPI/Pillow，pytest 无法收集。 +- 建议先覆盖风险评分、权限、上传、离线同步、检测判读和核心用户流程；建立统一依赖安装与 CI，输出可复现的测试报告。 + +#### P1-8 缺少生产级可观测性和容量证据 + +- AI `/metrics` 是自定义 JSON，不是统一指标系统；未发现请求追踪、错误聚合、SLO 看板、告警规则或容量测试证据。 +- 建议建立 API、数据库、MQTT、IoTDB、对象存储、视频、AI、微信/天气依赖和业务闭环指标；进行 500/1000 用户目标下的负载模型验证。 + +### 5.3 P2：中期优化 + +- 拆分过长的 handler/page，减少业务规则散落在 HTTP 层和大页面中。 +- 查询统一分页与总数，修复无上限 telemetry limit、N+1/全表辅助查询和批量导出能力。 +- 将健康画像从人工扣分公式升级为可解释、可回测、可版本化的指标体系。 +- 建立知识内容审核、发布、撤回、引用来源和专家签名。 +- 统一 APP、小程序、Web 的接口类型与枚举，降低多端漂移。 +- 清理仓库中的编译二进制、压缩包等大文件，制定制品仓库和 Git LFS 策略。 + +## 6. 优化方案与实施路线图 + +### 阶段 A：0～2 周，安全与正确性基线 + +| 交付物 | 验收结果 | +|---|---| +| 风险评分语义修复 | healthy 高置信度不升风险；异常概率、模型版本、mock 标识可追踪；回归测试通过 | +| 密钥与管理员治理 | 生产缺关键配置时拒绝启动；历史凭据完成轮换；客户端无默认密码 | +| 视频与摄像头安全 | 未授权用户无法访问流；API 不返回任何摄像头/SIP 密钥；播放行为有审计 | +| qPCR 判读修订 | 支持无效/不确定；对照失败不能判阴性；规则有版本 | +| 构建恢复 | Go test/vet、Web test/lint、小程序 typecheck、APP typecheck/lint、AI pytest 均可复现 | + +### 阶段 B：2～6 周，工程化与规格校准 + +| 交付物 | 验收结果 | +|---|---| +| 规格书 V2.2 | 架构与仓库一致；需求有 ID、状态、验收和证据；无“骨架=完成” | +| 版本化数据库迁移 | 新环境可从 0 部署；升级/回滚演练通过；schema 不一致拒绝启动 | +| CI 质量门禁 | 多模块静态检查、单测、构建、密钥扫描和制品输出自动执行 | +| 可靠事件机制 | 巡检—检测任务—通知幂等；失败可重试；状态可查询；重启不丢失 | +| 可观测性基线 | 请求 ID、结构化日志、核心指标、错误告警和依赖健康可统一查看 | + +### 阶段 C：1～3 个月，补齐可用 MVP 闭环 + +- 自动检测任务和专家升级规则。 +- 小程序离线巡检、断点上传、冲突处理和同步状态可视化。 +- 消毒记录、种源链、样本链和发病事件。 +- LAMP 对照与流程质控、qPCR 结构化结果、SERS 数据标准。 +- 区域/房间/设备级数据权限和专家 SLA。 +- 处置措施、复查结果和防控效果评估。 + +### 阶段 D：3～6 个月，真实模型与规模化试点 + +- 修复数据集泄漏，完成二分类基线，再决定是否进入 7 类模型。 +- 建立数据卡、模型卡、标注复核、灰度、漂移监测和回滚。 +- 在真实农户、设备、网络和季节条件下试点；以漏诊、误报、任务完成率、响应时间和损失改善评估价值。 +- 完成云环境的备份恢复、容量、弱网、故障注入和安全测试。 + +### 阶段 E：6 个月以后，研究型能力 + +- 固定摄像头巡检任务编排和群体整齐度模型。 +- LAMP 显色图像辅助判读。 +- SERS/高光谱方法学验证与数据集建设。 +- 区域传播模型、聚集性异常检测和跨年复发分析。 +- 在人工确认、安全约束和回滚机制下探索环境控制数字孪生。 + +## 7. 建议新增的功能 + +### 7.1 高价值、应优先增加 + +| 功能 | 价值 | 复杂度 | 建议阶段 | +|---|---|---|---| +| 蚕匾/批次/样本二维码 | 串联巡检、采样、检测、处置和溯源，减少手工选错对象 | 中 | 阶段 C | +| 消毒与生物安全管理 | 为内源复发判断提供核心数据，可形成计划、执行和复核闭环 | 中 | 阶段 C | +| 蚕种来源与检疫链 | 支撑微粒子病和跨批次追溯 | 中高 | 阶段 C | +| 检测任务中心 | 统一 LAMP/qPCR/SERS/高光谱的派单、SLA、样本和结果 | 中 | 阶段 C | +| 防控措施效果评估 | 对比处置前后风险、阳性率、损失和复发，回答“措施是否有效” | 中 | 阶段 C/D | +| 离线工作台 | 弱网下完成拍照、记录、采样和任务，联网后可靠同步 | 高 | 阶段 C | +| 数据/模型质量工作台 | 标注、复核、难例、漂移、版本和回滚 | 高 | 阶段 D | + +### 7.2 规模化运营能力 + +- **多组织/合作社/区域管理：** 组织、养殖场、人员、数据范围和跨区域脱敏统计。 +- **专家排班与会诊 SLA：** 自动分派、超时升级、意见模板、签名、复诊和工作量统计。 +- **设备资产与校准：** 传感器校准、摄像头维护、试剂设备保养、固件与故障工单。 +- **库存批次追溯：** 试剂批号、供应商、入库、领用、报废、温控和召回。 +- **经营损失与成本分析：** 死亡率、淘汰量、蚕茧产量、用药/消毒/检测成本和投资回报。 +- **数据导出与监管报表：** 按权限脱敏导出，生成区域疫情、检疫、消毒和处置报表。 +- **适老化/乡村 UX：** 大字号、语音播报、图片化操作、方言/普通话提示和一步式上报。 + +### 7.3 创新与研究功能 + +- **主动学习：** 自动挑选低置信度、模型分歧和专家纠正样本进入标注队列。 +- **多模态异常检测：** 图像、环境、活动度、声音、摄食和历史共同判断群体异常。 +- **传播网络与聚集性预警：** 结合种源、人员/工具流转和空间关系识别可能传播链。 +- **数字孪生与安全控制建议：** 模拟通风、温湿度和密度调整的影响，只输出受约束建议，关键动作由人确认。 +- **分子分型/实验室接口：** 将三级溯源从自由文本升级为结构化分型、环境采样和实验室报告。 +- **跨季节风险基线：** 建立不同地区、品种、龄期和季节的正常范围，降低统一阈值误报。 + +## 8. 建议的规格书 V2.2 目录 + +1. 文档控制、范围、术语与参考资料 +2. 产品目标、非目标、用户角色与业务边界 +3. 当前态、目标态和部署拓扑 +4. 核心业务流程与异常/补偿流程 +5. 带 ID 的功能需求 +6. 数据模型、数据字典、数据治理与保留策略 +7. API、事件、设备和外部系统契约 +8. AI 数据、训练、评估、推理和模型治理 +9. 权限、隐私、安全与审计 +10. 性能、可用性、灾备、可观测性和兼容性 +11. 分阶段范围、依赖、退出条件与验收矩阵 +12. 风险清单、假设、开放决策和 ADR 索引 +13. 蚕病领域知识附录与证据来源 +14. 需求—实现—测试—发布追踪矩阵 + +建议把 1000 行以上的现有规格书拆为“产品/系统规格主文档 + 蚕病知识附录 + API 文档 + 数据字典 + AI 模型与数据规范 + 验收矩阵”，减少科学资料、产品需求和具体技术实现互相覆盖。 + +## 9. 验证结果 + +| 检查 | 结果 | 说明 | +|---|---|---| +| `server-go: go test ./...` | 通过 | handler/model/service 测试通过，其余多个包无测试文件 | +| `server-go: go vet ./...` | 通过 | 与 go test 同一命令链执行完成 | +| `web: npm test` | 通过 | 1 个测试文件，3 个测试通过 | +| `web: npm run lint` | 通过但有 5 个 warning | 包含 hooks 依赖、缺 key 和 fast-refresh 警告 | +| `ai-service: python -m pytest -q` | 未执行成功 | 当前 Python 环境缺 `fastapi`、`Pillow`，测试收集失败 | +| `app: npm run tsc / npm run lint` | 未执行成功 | 当前目录缺可执行 `tsc`、`eslint`，说明依赖环境不完整 | +| `miniapp: npx tsc --noEmit` | 失败 | dashboard 两处 TS1382 | +| Git 工作区 | 分析前后均无意外生成物修改 | 本文档与交接记录除外 | + +## 10. 最终建议 + +本项目下一阶段最有价值的工作不是继续扩充菜单，而是把“可信、可追踪、可恢复”补齐。建议把以下四项作为下一迭代唯一 P0： + +1. 修复风险评分和 qPCR 判读，隔离不可信历史数据。 +2. 收口视频、密钥、WebSocket 和 AI 服务的安全边界。 +3. 发布与真实架构一致的规格书 V2.2 和追踪矩阵。 +4. 建立版本化迁移、CI、可靠任务/通知和基础可观测性。 + +完成这些之后，再以“二维码样本链 + 消毒/种源链 + 自动检测任务 + 离线工作台”为首个业务增强包，能够显著提高现有功能之间的闭环程度，并为后续真实 AI 模型、区域流行病学和科研合作提供可信数据底座。