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

# 蚕病智能防控平台规格说明书

**版本：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. 当前状态追踪矩阵

> 需求级追踪矩阵见 `docs/acceptance/requirements-traceability.md`；发布前必须执行 `docs/acceptance/core-e2e-cases.md` 和 `docs/acceptance/release-checklist.md`。

| 能力 | 当前状态 | 阻断项 | 目标阶段 |
|---|---|---|---|
| 环境/设备/告警 | 部分可用 | 数据质量、对象权限、校准 | B/C |
| 视频 | 部分可用 | 公开流、密码返回 | A |
| 拍照巡检 | Mock/部分可用 | 真实模型、风险语义、离线 | A/C/D |
| 风险评分 | 部分可用但存在错误 | healthy 置信度语义、缺失数据 | A |
| LAMP | 手工流程可用 | 质控、样本链、AI 判读 | C/E |
| qPCR | 手工录入且判读待修 | 对照/无效态/阈值版本 | A/C |
| SERS | 文件录入骨架 | 设备、算法、方法验证 | C/E |
| 高光谱 | 接口预留 | 数据、算法、方法验证 | E |
| 专家会诊 | 表单流程部分可用 | SLA、版本、可靠通知 | C |
| 统一检测任务/样本/发病事件 | 部分可用 | 未端到端联调、真实模型 | C |
| 生物安全（种源/消毒/二维码） | 部分可用 | 真实二维码/现场扫码联调 | C |
| 小程序离线巡检 | 部分可用 | 离线→重启→联网截图取证 | C |
| 会诊治理/知识审核/效果评估 | 部分可用 | 专家与试点联调 | C |
| 可观测性/容量/恢复 | 基线可用 | 真实负载、恢复演练、告警通道 | B/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 章的蚕病知识可继续作为领域参考底稿，但在进入知识库、检测判读规则或验收标准前，必须补充文献/规范来源、发布日期、访问日期、适用范围、证据等级和领域专家确认。设备价格、单次成本、研究状态和推广事件属于时效性信息，不作为长期固定验收事实。