需求分析_观澜_2.68.0.md 129 KB
需求分析 · 观澜 v2 风电场智能分析系统 · 版本 2.68.0
1 文档说明
本文用途（2026-09-22 用户说明）：本文供开发团队后续迭代观澜时使用，目标是让系统对不同风电场、不同机型尽可能适用与通用。本文以观澜当前实现为基础编写（口径取自现有代码、配置与产物），但它不是对当前实现的描述，也不是改造现有系统的要求：凡本文列出而当前实现尚未覆盖的条目，只作为后续迭代的候选需求，不得据此改动现有系统的行为与产物。
1.1 目的
本文是「观澜 v2（风电场智能分析系统）」的需求分析文档，回答四个问题：这套系统究竟要满足谁的什么需要；这些需要从哪来、经过哪些版本变成现在的样子；每一条需要对应什么功能、什么输入、什么输出、拿什么判据验收；以及哪些事本版明确不做。本文与同批交付的《系统设计说明_观澜_2.68.0.docx》《数据要求说明_观澜_2.68.0.docx》配套：本文讲「要什么、凭什么算做到了」，设计说明讲「怎么做的」，数据要求说明讲「要哪些数据、什么形态、什么单位」。
本文的写作口径是只写能取证的事实：每个数字、每条结论都能指到仓库里的某个文件、某次实跑输出或某条版本记录；查不到、取不到的一律写明「未取证」或「未到位」，不做推测性补全。因此文中会出现少量「未取证」的说明句，那是刻意留下的诚实边界，不是遗漏。
1.2 读者与用法
本文面向四类读者：场站侧的运行、点检、管理人员用它核对「系统答应做的事是否都做到了」；研发与交付人员用它做需求变更的基线（改需求先改本文的 FR 编号与验收判据）；验收与审计人员用第 9 章的门清单与退出码语义逐条核对；新加入项目的工程师用第 2、3 章在半小时内建立全局认识。
需要提醒的是：本文不是操作手册。放数据、重算、安装、卸载的具体命令在《重算操作手册》《输入数据放置指导》《README_先读我.MD》里，本文只在功能需求条目里给出判据与依据文件的位置。
1.3 版本对应关系
系统版本号只有一个真源：仓库内的 src/version.py 的 VERSION 一行。本版 VERSION = 2.68.0，版本记录（HISTORY）共 114 条，人读的版本表由 scripts/version_log.py 从 HISTORY 生成到 docs/版本记录.md，并由 version_log.py --check 与 guanlan.py check 双重校验「记录表与代码一致」。
表 1-1 版本与文档的对应关系
| 项 | 值 | 取证方式 |
|---|---|---|
| 系统版本 | 2.68.0 | src/version.py 的 VERSION；guanlan.py check 实跑报「版本管理: 观澜 v2（风电场智能分析系统） v2.68.0」 |
| 交付包名 | app_guanlang_v2.68.0.zip | src/version.py 的 package_name()；同一条 check 输出 |
| 本文版本 | 2.68.0（与系统版本同号） | 本文标题与 src/version.py 的 VERSION |
| 版本史条目数 | 13 条（最新一条即本次文档交付） | src/version.py 的 HISTORY；docs/版本记录.md |
| 版本号规则 | v大版本号.中版本号.小版本号；大改方案或架构、中改非核心功能、小为消缺 | src/version.py 的 BUMP_RULE 与 LEVEL_MEANING；docs/系统设计说明.md §15 |
| 版本级别机器判据 | level_of(旧, 新) 返回 major 或 minor 或 patch 或 same | src/version.py 的 level_of() |
| 本次变化级别 | 小（patch，源码模块化重构推进 P1：公共层九个平台件实体迁移，旧路径留兼容转发壳；系统功能与运行为未变） | HISTORY 中 2.59.0 条目的 level 字段 |
本版相对 2.10.0 的实质变化是交付文档对外化：三份交付文档（需求分析、系统设计说明、数据要求说明）全文不体现具体风电场（去标识化），并新增多风电场适用性一章；系统功能未变，属交付物修订。依据用户令原文：「修改三份文档，内容参考样本风电场，但不体现样本风电场，且具有不同风电场适用性」（引用时把样本场名按去标识化口径写成「样本风电场」）。
1.4 编写依据与取证口径
本文的取证方式分四种，文中出现数字时都能归到其中一种：读源（读代码、配置、登记表）、读文档（读仓库内已交付的设计与操作文档）、实跑（跑只读的自检与只读的审计脚本）、实测计数（对 data 与 outputs 目录做文件级计数与求和）。为避免把「文档里写过」当成「现在就是这样」，凡与现状有关的数字，本文优先采用实跑与实测计数，并在文中标注日期。本文出现的全部实测数字（件数、体量、行数、日期覆盖、耗时、退出码等）都出自样本场实测（2026-09-22）：保留它们是为了说明判据与量级，换场后必须按新场重新标定与重跑，不能直接当作新场的预期值——第 11 章的多风电场适用性要求正是围绕「结构不变、参数与数据随场变」写的。
表 1-2 取证方式与本版关键数字（样本场实测（2026-09-22））
| 取证方式 | 本版用到的实跑或实测 | 关键数字 |
|---|---|---|
| 只读自检 | guanlan.py check（2026-09-22 本机） | 结论「全绿，可 serve」，退出码 0，无 FAIL 项，41 条判定行 |
| 只读审计 | scripts/pages_audit.py --check（2026-09-22） | 检查 21 项，不一致 0，已知缺口 19，退出码 0 |
| 只读计划 | scripts/rebuild_all.py --dry-run（2026-09-22） | 默认 26 步；加 --skip-scada 为 23 步 |
| 实测计数 | data/raw/<场站> 与 outputs/<场> 递归计数（2026-09-22） | 输入 26,504 件 / 224.67 GB；产物 3,549 件 / 7,157.5 MB |
| 读源 | src/version.py、configs/portal_pages.yaml、configs/serve.json、guanlan.py、scripts/rebuild_all.py | 13 条版本史；25 条顶层页面条目（含 7 条子页共 32 条）；6 个服务端口 |
| 读文档 | docs/系统设计说明.md（56 个标题）、docs/说明书_观澜…v0.2.md、docs/输入数据放置指导_v0.1.md、docs/数据目录结构与落位约定_v0.2.md、docs/重算操作手册_v0.1.md、docs/页面输出体检_v0.1.md、README_先读我.MD | 逐章依据见附录 A |
1.5 术语与描述口径约定
本版全文遵守三条写作口径，它们是用户令落成的硬要求，也是机器清扫过的（依据 docs/系统设计说明.md §17.1）：第一，描述里含「窗」且确实指时间窗口的，一律写全「时间窗」——预设时间窗、判级时间窗、证据时间窗、随所选时间窗、时间窗内；而领域词里的天气窗、作业窗、预览窗、观测窗保持原样，不误改。第二，影响的是风电机组时统一写「影响机组」或「影响机组数」，不使用以「台」计数的旧写法；数据字段名里的旧写法暂留以兼容数据契约，显示层统一。第三，用英文简写时必须写成「中文（英文简写）」，例如平均无故障间隔（MTBF）、平均停机间隔（MTBO）、单次停机时长（MDT）；英文映射的键同步改，否则英文页会回落中文。
表 1-3 三条描述口径与落地位置
| 口径 | 要求 | 落地与证据 |
|---|---|---|
| 时间窗 | 含「窗」且指时间窗口者写全「时间窗」 | docs/系统设计说明.md §17.1；v2 页面顶栏控件与图注均写「随所选时间窗」 |
| 影响机组 | 影响风电机组时写「影响机组」 | 表头与说明含报告构建器；数据字段名暂保留 |
| 英文简写 | 中文（英文简写） | 平均无故障间隔（MTBF）、平均停机间隔（MTBO）、单次停机时长（MDT）；i18n_en 键同步 |
另外，本文出现的台号（如 WTG01 至 WTG38 一类写法）是样本场内部编号，保留编号形态只是为了与产物、台账和依据逐条对得上；换场时按实际台号替换，编号本身不构成接口约定。
术语的完整解释见附录 B。
2 系统概述
2.1 本系统是什么
本系统（观澜 v2，风电场智能分析系统）是一套纯离线的海上风电场智能分析单包系统，对象是样本风电场（下称「本场」）的 38 台 4.0 MW 级海上机组；机型代号与主机制造商（OEM）名称从略，业主单位名称从略。它把现场给来的运行数据、状态监测、报警、工单、油样落到每台机组的正确部件上，给出带证据、带边界、带责任人的检修结论；判断在代码里，本机模型只负责问答、解释与引用，不发明结论。软件不含任何联网功能，也不需要现场系统配合改造：原始件从 data/raw 读入，产物落在 outputs 下，页面只读产物，产物由数据算出来。
一页话术（给第一次接触的人的三十秒版本）：这套系统不控制风机、不下发指令、不改现场任何系统。它做的是「把现场已有的数据读进来，算出一份能说清依据的体检报告，然后用一个门户和三个服务把它讲清楚」。放数据之前，页面会如实显示「无产物」并告诉你缺哪一件、怎么补；放了数据之后，一条命令重算，页面立刻有数。所有结论都能往回指到源件与算法，指不到的地方它会写「不可判」或「缺件」，而不是编一个数字。
2.2 部署形态与运行边界
交付形态是离线单包（EDITION = offline-single-package）：一个安装目录里同时是程序、配置、交付件与数据入口。安装目录不要带空格与中文。程序侧有 6 个常驻服务，全部由安装目录下的启动器或系统服务托管；组件的内部接口只监听本机回环地址，只有门户网关按配置可对外监听。
表 2-1 常驻服务与端口（依据 configs/serve.json 与 guanlan.py 内置默认，两者口径一致）
| 服务 | 默认端口 | 监听地址 | 作用 |
|---|---|---|---|
| 门户网关 | 28084 | host 与 public_host（出厂 public_host 为 0.0.0.0） | 门户单文件页、路由与改写、运维控制台、/healthz、/api/version |
| 分析工作台 | 18033 | host（127.0.0.1） | 十个标签的分析工作台与全部 /api 取数 |
| 振动诊断 | 18020 | host（127.0.0.1） | CMS 振动报告页、逐台页、工作台页、谱图 |
| 仿真与回放 | 18791 | host（127.0.0.1） | 整机联调仿真台静态资产 |
| 仿真四系统合页 | 18792 | host（127.0.0.1） | 从冻结资料包读取的四系统合页 |
| 三维拆装工作台 | 64292 | host（127.0.0.1） | 三维资产页 |
| 本机模型（可选） | 11434 | 本机 | 本地大模型推理服务，只影响问答与本地初筛 |
对外只有一个入口 28084。这不是省事，而是边界：页面没有鉴权，把组件直接暴露出去等于把全场的运行数据摊开。要对外访问时的正确做法是限来源（防火墙白名单或反向代理加认证），或把 public_host 改回空串只用本机加隧道。
2.3 系统能力清单
表 2-2 系统能力清单（能力域、给谁用、载体、验收锚点，样本场实测（2026-09-22））
| 能力域 | 能力 | 主要载体 | 验收锚点或判据 |
|---|---|---|---|
| 判级 | 38 台乘九系统判级矩阵，四轴随时间窗重算 | 工作台系统矩阵、逐台页、问题页 | 判级报警机组数随所选时间窗变化；样本不足如实写不可判 |
| 部件问题 | 部件可靠性表、问题下钻、完整依据 | 工作台 component 与 vibration 标签 | 平均无故障间隔（MTBF）、平均停机间隔（MTBO）、单次停机时长（MDT）随所选时间窗变化；依据展开永不为空 |
| 发电性能 | 七镜头曲线、七张月度时序图、控制参数一致性 | 工作台 energy 与 generation 标签 | 图注写「随所选时间窗」；样本量随时间窗变化；控制参数按所选时间窗重算 |
| 振动 | 振动窗索引、谱库、CMS 报告、逐台页、在升与换件闭环、三层基线 | CMS 服务、工作台 vibration 标签 | 振动窗 w0316 索引 2,066,686 行；谱 420,742 条；缺件时如实空表并写边界 |
| 台账 | 报警、工单、油样三门台账与停机事件 | 工作台 fault 标签、数据层维护页 | 报警 39,211 行、工单 5,876 行、油样 404 行 |
| 本体与问答 | 对象库、检索索引、决策链、趋势证据、问答与校闸 | 工作台 assistant 与 decision 标签 | 本体审计 0 问题；两档模型都拦则不出文并给原因 |
| 报告 | CMS 标准模版报告、事实契约与派生、门户结论段 | 报告页、门户、qc 派生件 | 契约改一条 claim 则四个消费端全变 |
| 运维 | 一条命令重算、控制台按钮、清产物、数据扫描与看门狗 | 门户数据重算页、运维控制台 | 默认 26 步计划；并发动作返回 409；扫描退出码 0 与 4 与 5 |
| 门户与检索 | 单文件门户、页面归口与陈旧检测、知识检索 | 门户、页面归口登记表 | 归口审计退出码 0；页面陈旧报 7 |
| 数据接入 | 落位、体检、增量三清单、场站辨识 | 命令行脚本与维护页 | 结构合规；冲突拦下；场站辨识四条规则 |
| 交付与运维 | 打包、开箱验证、服务化、版本检查、卸载 | install、pack、uninstall 入口与服务注册器 | 入口引用闭合 48 条；卸载入口 2 个；版本记录与代码一致 |
3 需求来源与演进
3.1 需求来源的三条线
需求从三条线汇拢。第一条是现场运行的需要：值班要一眼看清全场哪几台机组有问题，点检要顺着问题找到部件与证据，管理要一份能对外的结论。第二条是交付与运维的需要：机器上没有网络、现场不会敲命令、数据每月增量、程序要能装能卸能升级。第三条是用户令：每一次人工测试或现场事故之后，用户用一句话把要求定下来（例如「所有的计算均要形成观澜的源代码」「对 data/raw 下文件的增减做到监听」「增加自定义时间段」），研发把它落成代码、机器守卫与文档。
三条线里，用户令是最硬的驱动力：它带来的是可核验的验收判据，而不是一段描述。本版 13 条版本记录里，绝大多数条目的形态都是「检查到的问题 → 根因 → 解决 → 验证」，其中「验证」一栏写的就是实跑的退出码与逐值对拍结果。
3.2 需求演进时间轴
表 3-1 版本史与用户令要点（依据 src/version.py 的 HISTORY，共 114 条）
| 版本 | 日期 | 用户令要点 | 变化级别 |
|---|---|---|---|
| 2.68.0 | 2026-10-03 | overview 结构对齐 | 中（minor） |
| 2.67.0 | 2026-10-03 | Fault 页图表改用 v2.9.2 的 SVG 渲染器+ 结构判据透明化 | 中（minor） |
| 2.66.1 | 2026-10-03 | 修可移植性门禁红项 | 小（patch） |
| 2.66.0 | 2026-10-03 | 门户在 Vue 中严格实现+ 静态附加件放置助手 | 中（minor） |
| 2.65.0 | 2026-10-03 | 图表改为复用 v2.9.2 的 SVG 渲染器 | 中（minor） |
| 2.64.0 | 2026-10-03 | 结构级对拍：工具落地 + 逐页签差距实测 | 中（minor） |
| 2.63.1 | 2026-10-03 | 恢复呈现对拍基线：10 个页签实测与重构前一致 | 小（patch） |
| 2.63.0 | 2026-10-03 | 前端与 v2.9.2 一致：Vue 采用旧页样式表 + 提供 v2.9.2 原样经典页 | 中（minor） |
| 2.62.1 | 2026-10-03 | 「门户栏目」收敛为在线服务两项；「架构与资料」内嵌四节整页展开 | 小（patch） |
| 2.62.0 | 2026-10-03 | 门户四节原样内嵌进工作台+ 修 Workbench 模板分支未命中 | 中（minor） |
| 2.61.0 | 2026-10-03 | 工作台补「门户栏目」页签；记档一次失败的网关路由尝试 | 中（minor） |
| 2.60.1 | 2026-10-03 | 两个 Java 进程纳入 serve 托管 | 小（patch） |
| 2.60.0 | 2026-10-03 | 门户「交付文档」「数据重算」迁入工作台页签+ 后端接口 | 中（minor） |
| 2.59.0 | 2026-10-01 | 产品机就绪收尾：重算链安全清理 + 逐件台账再生 + 暂存件移出产物仓 | 中（minor） |
| 2.58.0 | 2026-10-01 | 旧产物件清理+ 台账误删的自我修复 | 中（minor） |
| 2.57.2 | 2026-10-01 | 修回被删残的重算链并留待办提示 | 小（patch） |
| 2.57.1 | 2026-10-01 | 系统设计说明补“三栈重写的删除批次与能力承接”一节 | 小（patch） |
| 2.57.0 | 2026-10-01 | 单文件烘焙页随旧页退役 ⇒ 旧页渲染批已全部删除 | 中（minor） |
| 2.56.1 | 2026-10-01 | lang.py 退役+ 补 en.ts ⇒ 项目检查全绿 | 小（patch） |
| 2.56.0 | 2026-10-01 | 删除旧 Python 业务后端；产物生成端取数改指算法服务 | 中（minor） |
| 2.55.0 | 2026-10-01 | 入口改为 Vue 工作台 · 门户退役 | 中（minor） |
| 2.54.1 | 2026-10-01 | 删除旧页 design/terms+ 摘除 api 转发 ⇒ 全门禁保持通过 | 小（patch） |
| 2.54.0 | 2026-10-01 | 删被替掉的旧页前端资源+ 台账与门禁随退役对齐 ⇒ 全门禁通过 | 中（minor） |
| 2.53.2 | 2026-10-01 | detail 依赖台账按退役后的现场重写 ⇒ 全门禁恢复绿 | 小（patch） |
| 2.53.1 | 2026-10-01 | 产物登记按“不随包”入册 + 审计先看 known_gap ⇒ 开箱验证全绿 | 小（patch） |
| 2.53.0 | 2026-10-01 | 网关精确路径别名+ 契约面收敛 ⇒ 复核 40/40 全绿 | 中（minor） |
| 2.52.1 | 2026-10-01 | 修 config_audit 逮到的“手拼 configs 路径”⇒ 全门禁恢复 | 小（patch） |
| 2.52.0 | 2026-10-01 | HTTP 契约复核基址随架构更新⇒ 36/42；6 条页级不一致已列明 | 中（minor） |
| 2.51.1 | 2026-10-01 | 开箱核验页面清单随架构更新⇒ 页面 5/5 | 小（patch） |
| 2.51.0 | 2026-10-01 | 交付形态补齐：四模块可单独打包 + 根 run.bat/run.sh + install/uninstall 支持按模块 | 中（minor） |
| 2.50.0 | 2026-10-01 | 停用 Python 业务后端：运行期验证不再需要它 | 中（minor） |
| 2.49.0 | 2026-10-01 | 门户制品化：Java 网关文件优先伺服 release/portal.html | 中（minor） |
| 2.48.0 | 2026-09-30 | 补 /api/rpt_compose 探针⇒ 前端对拍恢复 10/10 | 中（minor） |
| 2.47.1 | 2026-09-30 | 修门户回归+ 登记 gateway_java 端口 ⇒ 门禁恢复全绿 | 小（patch） |
| 2.47.0 | 2026-09-30 | 入口切到 Java 网关；Python 网关退到 28086 继续供 /ops；旧页 /detail/v2 仍可达 | 中（minor） |
| 2.46.0 | 2026-09-30 | Java 网关补齐入口——为删 Python 源码铺路 | 中（minor） |
| 2.45.0 | 2026-09-30 | 灰度切换：同源 /api/* 直通 Java | 中（minor） |
| 2.44.0 | 2026-09-30 | 问答管线真跑成功；裁判把 ask_status 状态字段整组登记忽略 | 中（minor） |
| 2.43.0 | 2026-09-30 | 问答管线端到端接通；仅因本机模型服务未启动而报错 | 中（minor） |
| 2.42.1 | 2026-09-30 | 问答管线搬进算法服务；Java 侧接线暂撤回以保树可编译 | 小（patch） |
| 2.42.0 | 2026-09-30 | POST /api/ask 校验语义对齐 + 裁判加 POST 能力 ⇒ Java 范围 17/17 全部一致 | 中（minor） |
| 2.41.0 | 2026-09-30 | rpt_export 收口+ 裁判加解包文本比对 ⇒ 计分板 16/17 | 中（minor） |
| 2.40.1 | 2026-09-30 | rpt_export 组装侧就绪；HTTP 与 Java 侧下一轮接通 | 小（patch） |
| 2.40.0 | 2026-09-30 | vibcms 与 reload 迁移 + 裁判对有状态端点加固 ⇒ 计分板 15/17 | 中（minor） |
| 2.39.0 | 2026-09-30 | ask_models 与 ask_status 用 Java 实现并逐值一致 ⇒ 计分板 13/17 | 中（minor） |
| 2.38.0 | 2026-09-30 | curves 迁移 + 裁判学会等落定 ⇒ 计分板 11/17 | 中（minor） |
| 2.37.0 | 2026-09-30 | /api/fleet 逐值一致 ⇒ 计分板 10/17；裁判加预热消除冷启假差异 | 中（minor） |
| 2.36.2 | 2026-09-30 | fleet 链路打通但差异收敛到单字段，未计一致 | 小（patch） |
| 2.36.1 | 2026-09-30 | fleet 搬运完成但未计一致：自检仅剩 kpi.关注台 一处差异 | 小（patch） |
| 2.36.0 | 2026-09-30 | /api/channels 一致⇒ 计分板 9/17 | 中（minor） |
| 2.35.0 | 2026-09-30 | /api/maint_std 逐值一致 ⇒ 计分板 8/17 | 中（minor） |
| 2.34.0 | 2026-09-30 | /api/maint_framework 逐值一致 ⇒ 计分板 7/17 | 中（minor） |
| 2.33.0 | 2026-09-30 | /api/ont_chain 逐值一致 ⇒ 计分板 6/17 | 中（minor） |
| 2.32.0 | 2026-09-30 | 本体两端点逐值一致 ⇒ 计分板 5/17；算法服务通用参数透传 | 中（minor） |
| 2.31.0 | 2026-09-30 | /api/maint_survey 逐值一致：定下数据类端点迁移范式 + Java 复刻对外脱敏 | 中（minor） |
| 2.30.1 | 2026-09-30 | Java 迁移范围澄清：契约 42 条中属 Java 后端的是 17 条，算法 13 条本就是目标栈 | 小（patch） |
| 2.30.0 | 2026-09-30 | Java 第二批端点 /api/dq_findings 逐值一致 | 中（minor） |
| 2.29.1 | 2026-09-30 | Java 迁移裁判修正：未实现只按 HTTP 状态判；澄清 /api/facts/claim 不在 42 条契约内 | 小（patch） |
| 2.29.0 | 2026-09-30 | Java 后端迁移开工：逐条比对裁判 + 同一源站灰度路由 + 首批端点 /api/facts 已一致 | 中（minor） |
| 2.28.1 | 2026-09-29 | 灰度切换第一步就绪：Vue 产物经网关可作并列入口 | 小（patch） |
| 2.28.0 | 2026-09-29 | report 页签迁移完成 ⇒ 10/10 页签全部通过严格整页签对拍 | 中（minor） |
| 2.27.0 | 2026-09-29 | assistant 与 system 两个页签迁移完成 ⇒ 已迁页签 9/10 | 中（minor） |
| 2.26.0 | 2026-09-29 | decision 页签迁移完成⇒ 已迁页签 7/10 | 中（minor） |
| 2.25.0 | 2026-09-29 | generation 页签迁移完成⇒ 已迁页签 6/10 | 中（minor） |
| 2.24.2 | 2026-09-29 | generation 继续推进：补曲线图组 HTML 图例、候选机整串渲染；对拍仍受 /api/curves 建设态影响 | 小（patch） |
| 2.24.1 | 2026-09-29 | generation 页签迁移进行中 | 小（patch） |
| 2.24.0 | 2026-09-29 | vibration 页签迁移完成⇒ 已迁页签 5/10 | 中（minor） |
| 2.23.3 | 2026-09-29 | vibration 的 events 子视图迁移完成 | 小（patch） |
| 2.23.2 | 2026-09-29 | vibration 的 units 子视图迁移完成 | 小（patch） |
| 2.23.1 | 2026-09-29 | vibration 的 loop 子视图迁移完成 | 小（patch） |
| 2.23.0 | 2026-09-29 | vibration 的 matrix 子视图迁移完成，对拍 561 条文本一致 | 中（minor） |
| 2.22.1 | 2026-09-29 | 对拍门支持子视图；vibration 侦察结论入档 | 小（patch） |
| 2.22.0 | 2026-09-29 | fault 页签迁移完成；对拍门加“显式例外”并记下后端一处口径文案不一致 | 中（minor） |
| 2.21.2 | 2026-09-29 | fault 对拍推进：Pareto 图内 HTML 摘要逐字复现，图数据改用原值 | 小（patch） |
| 2.21.1 | 2026-09-29 | fault 页签迁移进行中+ 对拍门两处口径修正 | 小（patch） |
| 2.21.0 | 2026-09-29 | 三页签通过严格整页签对拍· ECharts 图表数据级一致 | 中（minor） |
| 2.20.0 | 2026-09-29 | ECharts 引入 + Java 网关/OAuth2/Security 落地；呈现对拍门升级为“严格整页签” | 中（minor） |
| 2.19.0 | 2026-09-29 | Vue 迁移第一个页签+ 呈现对拍门：jsdom 跑旧页面 vs Vue SSR，锚点逐项一致 | 中（minor） |
| 2.18.0 | 2026-09-29 | 后端 Java 化：Spring Boot 2.7.18 + springfox Swagger 离线可编可跑，与算法服 | 中（minor） |
| 2.17.0 | 2026-09-29 | 前端 Vue 化：Vue3+Vite+TS 工程落 release/web、经网关 /web 同源伺服、契约冒烟两侧一致 | 中（minor） |
| 2.16.0 | 2026-09-29 | 冻契约：现有 HTTP 面固化成契约正本 + 在线复核门 | 中（minor） |
| 2.15.2 | 2026-09-29 | 算法服务随 serve 默认起 | 小（patch） |
| 2.15.1 | 2026-09-29 | 算法服务消缺：日志纳入统一格式+ 端点登记表按实测收口 + 模块入口可起服务 | 小（patch） |
| 2.15.0 | 2026-09-29 | 算法服务化：算法层包成 FastAPI 服务，离线依赖随包 | 中（minor） |
| 2.14.0 | 2026-09-29 | 分别打包：前端 / 后端 / 算法 / 数据接入与管理 各自成包 | 中（minor） |
| 2.13.0 | 2026-09-28 | P9 源码目录结构变更：实现包上提模块根 + 每模块 common/configs/data/README/入口脚本 + | 中（minor） |
| 2.12.1 | 2026-09-28 | 源码梳理与死代码清理：删 cms_availability+ 清本地残留 15.4 MB | 小（patch） |
| 2.12.0 | 2026-09-28 | 模块化重构收官 P7：质量门与打包安装迁移——七个模块齐备 | 中（minor） |
| 2.11.9 | 2026-09-28 | 模块化重构 P6：本体与知识层实体迁移 | 小（patch） |
| 2.11.8 | 2026-09-28 | 消缺：guanlan.py stop 在 pids.json 读不动/删不掉时抛异常中断 | 小（patch） |
| 2.11.7 | 2026-09-28 | 模块化重构 P5：前端层实体迁移 | 小（patch） |
| 2.11.6 | 2026-09-28 | 消缺：服务 restart 的等待判据把 STOP_PENDING 当成已停 | 小（patch） |
| 2.11.5 | 2026-09-28 | 消缺：Windows 服务 restart 是无效命令 | 小（patch） |
| 2.11.4 | 2026-09-28 | 模块化重构 P4：后端层实体迁移 | 小（patch） |
| 2.11.3 | 2026-09-22 | 模块化重构 P3：算法层实体迁移 | 小（patch） |
| 2.11.2 | 2026-09-22 | 模块化重构 P2：数据接入管理实体迁移 | 小（patch） |
| 2.11.1 | 2026-09-22 | 模块化重构 P1：公共层九个平台件实体迁移 | 小（patch） |
| 2.11.0 | 2026-09-22 | 源码模块化重构 P0：七个模块目录 + 接口层 + 模块边界门 | 中（minor） |
| 2.10.4 | 2026-09-22 | 数据要求说明补测点：安全链与数字输入、执行器与热管理、计数账、CMS 采集参数、测点与位号字典（系统功能未变） | 小（patch） |
| 2.10.3 | 2026-09-22 | 交付件定名：《设计说明》定名为《系统设计说明》，与另外两份的交付命名对齐（文档内容未变） | 小（patch） |
| 2.10.2 | 2026-09-22 | 数据要求说明改为纯数据需求规格：去样本场现状与实现细节、测点按业务含义列表、新增 SCADA 秒级数据要求（系统功能未变） | 小（patch） |
| 2.10.1 | 2026-09-22 | 交付文档对外版：全文去样本场标识，并新增多风电场适用性一章（系统功能未变） | 小（patch） |
| 2.10.0 | 2026-09-22 | 整理需求、设计、数据接入各写一份 Word 文档，并源代码化其生成器 | 中（minor） |
| 2.9.2 | 2026-09-22 | 升级后验收补缺：重算链增 ⑧d 版本记录一致性门，版本与文档漂移有了自动拦截点 | 小（patch） |
| 2.9.1 | 2026-09-22 | 人工测试 7 项消缺：描述口径、依据空白、问题页空、门户链接 404、闭环文案、本机模型升档档位 | 小（patch） |
| 2.9.0 | 2026-09-21 | 时间窗真正生效：部件问题与发电性能随所选时间窗重算，新增自定义起止日期时间窗 | 中（minor） |
| 2.8.2 | 2026-09-21 | 扫描器的变化判据被两类非摄入件常年占住：新増上游归档口径与忽略模式 | 小（patch） |
| 2.8.1 | 2026-09-20 | 台账等价验收在全新机器上必然非零：改为容忍并写明「没做验收」 | 小（patch） |
| 2.8.0 | 2026-09-20 | 输入数据自动扫描识别：逐族指纹发现新增与变化，指明该跑哪几步并纳入重算 | 中（minor） |
| 2.7.0 | 2026-09-19 | 远程部署消缺：振动窗发布被占用不再打断重算链；门户可对外监听；控制台打印不炸 | 中（minor） |
| 2.6.0 | 2026-09-19 | 所有的计算均要形成观澜的源代码：融合面、总览页、事实契约、发布层、变桨面、振动基线与在升全部自算 | 中（minor） |
| 2.5.0 | 2026-09-17 | 卸载闭环、版本管理与打包命名规则、版本记录 | 中（minor） |
| 0.4.0 | 2026-09-17 | 打包默认不含输入数据与产物与日志与临时文件；无窗口启动；统一配置与日志；页面归口；服务化 | 旧编号（legacy） |
| 0.2.0 | 2026-09-01 | 含产物的旧交付基线，历史上用作「包内无生成端」那批产物的补救源 | 旧编号（legacy） |
需求的演进如图 1-1 所示。该图依据 src/version.py 的 HISTORY 绘制，覆盖上表 114 条记录（即两级旧编号 0.4.0 与 0.2.0，以及从 2.5.0 起按规则递增的112个版本）。按级别统计，这112个版本里「中」级变化64条（2.68.0、2.67.0、2.66.0、2.65.0、2.64.0、2.63.0、2.62.0、2.61.0、2.60.0、2.59.0、2.58.0、2.57.0、2.56.0、2.55.0、2.54.0、2.53.0、2.52.0、2.51.0、2.50.0、2.49.0、2.48.0、2.47.0、2.46.0、2.45.0、2.44.0、2.43.0、2.42.0、2.41.0、2.40.0、2.39.0、2.38.0、2.37.0、2.36.0、2.35.0、2.34.0、2.33.0、2.32.0、2.31.0、2.30.0、2.29.0、2.28.0、2.27.0、2.26.0、2.25.0、2.24.0、2.23.0、2.22.0、2.21.0、2.20.0、2.19.0、2.18.0、2.17.0、2.16.0、2.15.0、2.14.0、2.13.0、2.12.0、2.11.0、2.10.0、2.9.0、2.8.0、2.7.0、2.6.0、2.5.0），「小」级变化48条（2.66.1、2.63.1、2.62.1、2.60.1、2.57.2、2.57.1、2.56.1、2.54.1、2.53.2、2.53.1、2.52.1、2.51.1、2.47.1、2.42.1、2.40.1、2.36.2、2.36.1、2.30.1、2.29.1、2.28.1、2.24.2、2.24.1、2.23.3、2.23.2、2.23.1、2.22.1、2.21.2、2.21.1、2.15.2、2.15.1、2.12.1、2.11.9、2.11.8、2.11.7、2.11.6、2.11.5、2.11.4、2.11.3、2.11.2、2.11.1、2.10.4、2.10.3、2.10.2、2.10.1、2.9.2、2.9.1、2.8.2、2.8.1），没有大版本升级。这个分布清楚地显示出这条线的性质——功能面在 2.5.0 到 2.7.0 之间快速铺开，之后转入以消缺与口径统一为主的密集收敛期。
从时间轴能看出三个事实。第一，2.5.0 到 2.7.0 三天内出了三个中版本，全部是「装上、卸掉、打包、对外监听」这类交付能力，说明这一阶段的需求主线从「算得对」转向「交付得出去」。第二，2.7.0 之后密集出现小版本消缺，且每一条都带实跑验证，说明需求进入了「现场怎么用就怎么改」的收敛期。第三，2.10.0 是规格化的标志：需求不再只由代码与脚本承载，而是被写成可评审的文档，且文档本身也源代码化，可机器重生成。2.10.1 在这条线上再走一步：文档去样本场标识并补上多风电场适用性一章，使同一份文档能被别的风电场直接拿去用。2.10.2 把《数据要求说明》改成纯数据需求规格：不写样本场的接入现状、不写英文测点名与文件名与落盘位置，测点一律用业务含义名称按类列表（含单位与必须性），并补上 SCADA 秒级数据的要求。2.10.3 把《设计说明》定名为《系统设计说明》，与另外两份交付文档的命名对齐（文档内容未变）。2.10.4 按测点遗漏体检补齐《数据要求说明》：新增安全链与数字输入、执行器与热管理两域，扩充计数账与 CMS 采集参数，并加上"测点与位号字典"这项收资要求。2.11.0 起按用户令做源码模块化重构（七个模块目录 + 接口层 + 模块边界门），2.11.1 把公共层九个平台件实体迁入模块目录、旧路径留兼容转发壳——两步都是源码组织层变化，行为零变化。
3.3 需求如何被人工程序化
用户令通常是一句话，落到系统里要经过「变成判据、变成机器守卫、变成可复核证据」三步。第一步最关键：把一句中文要求翻译成一个可判定的条件。例如「时间窗变化时部件问题要跟着变」，翻译成「给定时间窗 w，判级矩阵的返回必须随 w 而变，且月度件按月取整、日粒度件按日精确」，这样才有办法验。第二步是把它做成每次都会跑的守卫，而不是靠人记得。第三步是留下可复核的证据（日志、退出码、逐值对拍结果、sha256）。
表 3-2 用户令到程序化落点的对照（节选，按版本递进，样本场实测（2026-09-22））
| 用户令（原话要点） | 程序化落点 | 可核验证据 |
|---|---|---|
| 部件问题与发电性能应随下拉框值变化，并增加自定义时间段 | months_of(win) 与 win_range 与 in_win；taxonomy.system_matrix(span=)；reliability.overview(span=)；/api/curves?win= | 变桨报警 15 与 13 与 10、偏航 15 与 11 与 5、齿轮箱 7 与 4 与 4 分别对应 2026年与 2025H2 与 2026-07 |
| 对 data/raw 含嵌套子目录下文件的增减做到监听 | scripts/raw_scan.py 逐族指纹（件数、体积、最新落盘、清单摘要、子目录清单）；重算链 ①b 步；rebuild_all --auto | 实测 --check 由 rc=4 转 rc=0（与上次快照一致）；空目录新建也能发现 |
| 所有的计算均要形成观澜的源代码 | 逐族补生成端：变桨面、在升闭环、三层基线、融合面 handoff、总览页、由台账生成 claim | 反向呼应审计成立 3,548 件、不成立 0 件、未归类 0 件 |
| 运行期一律不从交付包补齐 | 第 ⑤ 步由「补齐随包件」改为「反向呼应审计」，只报账不搬运 | rebuild_all --dry-run 计划中 ⑤ 步命令为 products_reverse_audit.py --check |
| 清除产物不留备份 | products_state.py --off --yes 改真删除；--on 与门户恢复按钮移除 | 控制台按钮语义与 409 前置校验；docs/系统设计说明.md §7 |
| 装成服务并在安装时检查版本 | win_service.py 以 ctypes 直连 SCM；service_main.py 与 systemd 单元；install-info.json 记录版本并比对 | check 实跑报「卸载入口在位 2 个」「版本管理 v2.68.0」 |
| 观澜改为监听所有 IP | serve.json 增 public_host 且出厂为 0.0.0.0，仅门户网关用它，组件仍绑本机 | check 实跑显示 6 个端口全部运行中；README 第二节写明无鉴权风险与回退口径 |
| 描述口径：时间窗、影响机组、中文（英文简写） | 界面文案与报告构建器统一改写；i18n_en 键同步 | docs/系统设计说明.md §17.1 与 §17.2；语言包 845 条前后端成对 |
| 整理需求与设计与数据接入各写一份 Word 文档 | docs/src 下 markdown 源件；渲染器输出带域目录的 docx；插图生成器生成 14 张图，数字全部从真件取 | HISTORY 2.10.0 条目；本版三份文档 |
4 用户与场景
4.1 角色
系统没有账号体系，角色划分是使用场景的划分，不是权限的划分。这一点必须在需求层面写清：当前版本没有页面鉴权，谁打开浏览器谁就能看到全场的运行数据；对外可达时的风险控制靠网络层（防火墙白名单、反向代理加认证、只绑内网地址）而不是靠系统内部。角色表的价值在于把「谁要什么」变成可核对的功能覆盖清单。
表 4-1 角色与核心诉求
| 角色 | 典型身份 | 核心诉求 | 主要页面与入口 | 对应功能需求 |
|---|---|---|---|---|
| 值班运行 | 场站值班员、集控值班员 | 一眼看清全场状态；报警是否集中；有没有正在恶化的机组 | 门户总览、系统状态、工作台 overview 与 energy、振动与 CMS | FR-01 至 FR-05、FR-09 至 FR-12 |
| 点检与检修 | 点检员、检修工程师、专业工程师 | 从现象定位到部件；要证据、要边界、要处置建议；看换件后是否回落 | 工作台 component 与 vibration 与 decision、问题页、CMS 逐台页 | FR-03 至 FR-05、FR-13 至 FR-17、FR-22 至 FR-25 |
| 场站管理 | 场长、技术负责人、生产管理 | 结论能否对外；停机损失与可靠性账；治理进展 | 门户经验发现与交付文档、汇报纸与报告导出、治理清单交付件 | FR-03、FR-09 至 FR-12、FR-26 至 FR-28 |
| 研发与交付 | 观澜维护方、交付工程师、审计人员 | 数据怎么接、重算是否成功、安装升级卸载是否干净、口径是否一致 | 运维控制台、数据重算页、命令行入口、版本记录与设计说明 | FR-29 至 FR-52、NFR 全部 |
4.2 场景到任务到页面
场景不必多，八个够覆盖日常。每个场景都要能回答「谁、在什么时刻、要完成什么、打开哪一页、看到什么算成功」。这一步是需求分析里最有用的动作：它把抽象的「系统要好用」变成「点开这页三秒内能看出哪几台报警」。角色、场景与页面的关系如图 2-1 所示。
表 4-2 场景到任务到页面
| 场景 | 任务 | 页面或入口 | 成功的样子 |
|---|---|---|---|
| 交班巡检 | 看全场状态与报警集中度 | 门户总览、系统状态、数据重算页 | 一屏内看清哪几台报警、服务是否在跑 |
| 例行点检 | 逐台看判级与四轴 | 工作台系统矩阵、逐台页 | 点台号即出该台各系统判级与依据 |
| 异常追因 | 从报警下钻到部件与证据 | 问题页、部件问题页 | 依据展开有部件、链路进度、卡点、证据源 |
| 振动专题 | 看振动判级、谱图、在升与换件闭环 | CMS 服务、工作台 vibration | 六层判读清楚，未闭环时明写「没有成对记录」 |
| 时间窗对比 | 换一个时间窗看判级与性能是否变化 | v2 顶栏时间窗与两个日期输入框 | 图注写「随所选时间窗」；样本量随之变化 |
| 月度汇报 | 出结论与报告 | 汇报纸、CMS 标准模版报告、门户结论段 | 结论带证据级、审级与处置措施 |
| 数据接入 | 放新数据、体检、重算 | 命令行落位与体检脚本、运维控制台 | 冲突被拦下；重算结束出每步 OK 与耗时 |
| 交付与升级 | 打包、开箱验证、装服务、卸载 | pack 与 install 与 uninstall 入口、服务注册器 | 版本检查提示正确；卸载后数据一件不少 |
4.3 角色与可用性边界
与角色相关的一条硬需求是「没有产物也要能打开页面」。现场第一次装完、或者在控制台上点了「清除产物」之后，页面必须仍然可访问，并明确说出缺哪一件、怎么补，而不是白屏或掐断连接。这条需求来自两次现场事故：振动服务在无产物时曾因空表拼接抛异常带走进程，工作台在缺件时曾直接返回 500 让人分不清「没放数据」还是「程序坏了」。现在的口径是：缺件时返回结构化缺件页与 err=no_source，页面写清缺件与补齐办法。相关功能需求见 FR-33 与 NFR-06。
5 功能需求
5.1 功能需求编号与总览
功能需求按十二个域组织，编号从 FR-01 到 FR-52，共 52 条。编号是稳定的：新增需求往后排号，不重排已有编号；需求作废时保留编号并标注作废，不改用它。每条需求都给出五项：需求描述、输入、输出、验收判据、依据文件。其中「验收判据」是可判定的条件，「依据文件」指向仓库内的源或文档，便于复核。
表 5-1 功能需求域与编号分配
| 域 | 编号区间 | 条数 | 一句话概括 |
|---|---|---|---|
| 判级与部件问题 | FR-01 至 FR-05 | 5 | 38 台乘九系统判级、四轴随时间窗重算、部件问题与依据 |
| 时间窗与自定义区间 | FR-06 至 FR-08 | 3 | 时间窗词表、自定义起止日期、按时间窗重算的等待契约 |
| 发电性能与可靠性 | FR-09 至 FR-12 | 4 | 七镜头、月度时序、控制参数一致性、损失与功率曲线 |
| 振动与融合面 | FR-13 至 FR-17 | 5 | 摄入、报告、融合判级、在升闭环、三层基线 |
| 停机与台账 | FR-18 至 FR-21 | 4 | 报警、工单、油样、停机与损失 |
| 本体与问答 | FR-22 至 FR-25 | 4 | 知识层、铺开、决策链与趋势、问答与校闸 |
| 报告导出 | FR-26 至 FR-28 | 3 | 标准模版报告、事实契约与派生、门户结论段与汇报纸 |
| 运维控制台与重算 | FR-29 至 FR-32 | 4 | 一条命令重算、控制台、清产物、数据扫描 |
| 门户与检索 | FR-33 至 FR-35 | 3 | 门户装配、页面归口与陈旧检测、检索索引 |
| 数据接入与体检 | FR-36 至 FR-38 | 3 | 落位与体检、场站辨识、同台多件与上游归档 |
| 安装与服务化与卸载 | FR-39 至 FR-43 | 5 | 离线安装、服务化、版本检查、卸载、打包与开箱验证 |
| 多风电场适用性 | FR-44 至 FR-52 | 9 | 场配置化、机组与机型与数据源替换、判据按场标定、跨场口径与换场验收 |
5.2 判级与部件问题
表 5-2 判级与部件问题（FR-01 至 FR-05，样本场实测（2026-09-22））
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-01 | 给出 38 台机组乘九系统的判级矩阵，逐台逐系统带判级与依据，四轴判级随所选时间窗重算 | scada_10min 与 scada_1min 序列、报警台账、振动报告转录、机型契约 | 工作台系统矩阵、逐台页、问题页；taxonomy.system_matrix 结果 | 判级报警机组数随所选时间窗变化（实测变桨 15 与 13 与 10、偏航 15 与 11 与 5、齿轮箱 7 与 4 与 4）；样本不足时如实写不可判 | docs/系统设计说明.md §16.2；src/windscada/taxonomy.py |
| FR-02 | 判级四轴（变桨、偏航、蓄能、温度）随时间窗重算，其中变桨按日粒度精确切片、其余走窄仓重算 | 窄仓 slim10min 公共列子集；pitch 面的日粒度件；1min 桨距角 | 各面 registry(span=) 结果与判级单元格 | 同一台同一系统在不同时间窗下可给出不同判级；温度面的对照基线 ref 与 ref_sm 故意固定并在页面标注 | docs/系统设计说明.md §16.2 与 §16.3；scripts/scada_slim_build.py |
| FR-03 | 部件可靠性表按所选时间窗重算，给出平均无故障间隔（MTBF）、平均停机间隔（MTBO）、单次停机时长（MDT）与停机时长 | 停机事件、报警事件（均为日粒度） | 可靠性表与部件问题页表格 | 停机事件与报警按时间窗精确过滤；三个指标随时间窗变化 | docs/系统设计说明.md §16.2；src/windscada/perf/availability |
| FR-04 | 部件问题下钻：问题页与问题接口按中文系统名取数，服务端做双向归一，认不出时如实报「系统标识无法识别」 | 台号、系统标识（中文名或前端标识或大小写变体）、时间窗 | 问题页、/api/problem 响应 | 传前端标识与中文名都能取到同一份问题；认不出时不写「本时间窗无异常」这类假陈述 | docs/系统设计说明.md §17.2；scripts/windscada_serve.py 的 sys_norm() |
| FR-05 | 需要关注的卡片必须给出完整依据，依据按本行字段自组句，永不为空 | 融合面链盘行、SCADA 关注集合、部件与链路进度 | 卡片依据文本 | 实测曾出现依据空白（WTG09 齿轮箱），现行口径为按部件、链路走到第几步、卡在哪一步、证据源自组句 | docs/系统设计说明.md §17.3；HISTORY 2.9.1 |
5.3 时间窗与自定义区间
时间窗是本版需求里最容易被误解的一块，因此口径要写死两句话：月度件按月取整，日粒度件按日精确；页面上要写明这两句，不让读者以为月度均值能切到天。
表 5-3 时间窗与自定义区间（FR-06 至 FR-08，样本场实测（2026-09-22））
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-06 | 提供预设时间窗词表：近30日、近90日、2026年、2026H1、2025H2、全程、单月、月区间 | 用户选择 | months_of(win) 与 win_range(win) 结果 | 每种写法都能落到覆盖的月集合与起止日期；近30日在末月只有 1 个节拍时如实按样本不足处理 | docs/系统设计说明.md §16.1 |
| FR-07 | 新增自定义起止日期时间窗，写法为起日期~止日期，含两端；顶栏提供两个日期输入框与「应用」并校验起不晚于止 | 两个日期输入框 | 与区间相交的月集合（月度件）、原样的日区间（日粒度件） | 非法输入被拒绝并给出提示；相交月取整与按日精确两套口径同时生效 | docs/系统设计说明.md §16.1；HISTORY 2.9.0 |
| FR-08 | 按时间窗重算一律「命中进程缓存即回，未命中先回等待状态并由页面轮询」，绝不静默拿旧口径当新时间窗 | 时间窗参数、进程缓存、后台重算线程 | 判级矩阵与七镜头结果、等待与构建中的状态标记 | 判级约 25 秒每个时间窗、镜头约 10 至 45 秒每个时间窗；等待期间页面写明「下面这几张卡还是上一份口径」；选到 2025-07 至 2025-12 时直接用正式产物不重算 | docs/系统设计说明.md §16.4；docs/系统设计说明.md §16.2 |
5.4 发电性能与可靠性
表 5-4 发电性能与可靠性（FR-09 至 FR-12，样本场实测（2026-09-22））
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-09 | 发电性能七镜头曲线随所选时间窗重算，曲线图注写明随所选时间窗且样本量随时间窗变化 | 窄仓 10min 子集、风速与功率通道、限电命令 | /api/curves 响应与七张镜头图 | 换时间窗后分箱结果变化，样本量变化；限电前干净判别窗（2025-07 至 2025-12）走正式产物 | docs/系统设计说明.md §16.2；HISTORY 2.9.0 |
| FR-10 | 发电性能七张月度时序图随时间窗过滤 | 月度派生件 | 七张月度时序图 | 图注写「随所选时间窗」；月度件按月取整 | docs/系统设计说明.md §16.2 |
| FR-11 | 控制参数一致性随时间窗重算，输出功率封顶与转速上限等一致性结论 | 窄仓补入的控制参数列（窄仓共 48 列） | 控制参数一致性卡片 | 按时间窗重算约 0.6 秒；功率封顶中位实测由 4,190（干净时间窗）变为 4,181.7（2026年）与 4,177.5（2026Q1） | HISTORY 2.9.0；docs/系统设计说明.md §16.3 |
| FR-12 | 损失、功率曲线与可用率派生件由原始件重算，替换随包件时逐值对拍 | scada_10min 与报警台账 | loss_monthly、powercurve_bins、powercurve_dev、stop_events 等 | 实测损失月表 3,729 行、功率曲线偏差 38 行、功率曲线分箱 912 行与基线逐值一致 | docs/数据目录结构与落位约定_v0.2.md §4 |
5.5 振动与融合面
振动这一域的写法要特别克制：它是全系统里人工判断成分最多的一段，因此需求必须区分「测量数据的函数」与「需要人工裁定的件」，不能把后者当成自动产物来承诺。
表 5-5 振动与融合面（FR-13 至 FR-17，样本场实测（2026-09-22））
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-13 | 振动窗索引与谱库摄入：解析厂家导出文件，按振动窗落索引表与谱分片，并登记清单 | windcms 下的解码导出文件（25,693 件） | 振动窗索引表（54 列）、谱分片、谱元数据、摄入清单 | 振动窗 w0316 索引 2,066,686 行、谱 420,742 条与 1,712 分片；重复摄入同名时间窗默认替换并留档旧窗 | docs/系统设计说明.md §13.1；docs/数据目录结构与落位约定_v0.2.md §2b |
| FR-14 | 生成 CMS 标准模版评估报告与逐台页、工作台页，缺融合级时如实写破折号 | 振动窗索引、标量缓存、三层基线 | 报告 md 与 docx、逐台页、总览页、登记 csv | 38 台判级齐全（实测报警 3 台、优秀 35 台）；缺融合级列时写破折号而不是编造 | docs/系统设计说明.md §13.1；HISTORY 2.6.0 |
| FR-15 | 融合面判级：由链盘、手交件与模型过闸线生成融合表与融合级，作为报告与判级矩阵的输入 | 振动窗索引、模型过闸线、厂家报告转录 | 融合表、handoff、全场标量 z 值 | 融合表 38 台逐台有裁决；handoff 与手交件同结构且标注由观澜自算 | docs/系统设计说明.md §13.1 与 §13.6 |
| FR-16 | 在升与换件闭环证据：逐振动窗标量算在升判据，给出检出、换件、复测回落的成对记录 | 振动窗索引、融合面链盘 | 部件历史件、趋势证据对象 | 时间窗数不足时如实出空表并写明数据边界；现场提交的数据包里没有成对记录时文案写「暂无端到端闭环证据」 | HISTORY 2.6.0 与 HISTORY 2.9.1 |
| FR-17 | 三层基线：自基线、机群基线与绝对限，用于振动判级的对照 | 振动窗索引标量、健康期分段 | 三层基线件 | 健康期分段中位与正常带按件算；绝对限引用标准限值；样本不足时如实空表 | docs/系统设计说明.md §13.1 |
5.6 停机与台账
表 5-6 停机与台账（FR-18 至 FR-21，样本场实测（2026-09-22））
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-18 | 报警台账摄入，按事件键集合并集去重，归属取最窄源件；源件删改后产物随之变化并大声报出 | 故障报警导出件（16 件） | 报警台账 | 39,211 行稳定；同一事件不重复计数；删一个源件不会让总数虚增 | HISTORY 2.8.0；docs/系统设计说明.md §13.1 |
| FR-19 | 工单台账摄入，按固定模板解析（第三行为列名，数据自第四行起），字符串化口径与随包件一致 | 风机故障记录（137 件，其中台账 123 件） | 工单台账 | 5,876 行；与基线差异逐条可归类 | docs/系统设计说明.md §13.1 |
| FR-20 | 油液化验索引，从文件名抽取台号、部件、日期与样品号，不读正文；采合并语义，认不出的历史行原样保留 | 油样报告（404 件） | 油样索引 | 404 行；2026-07 批 102 行的源件不在现场包内，清空重建会缺这 102 行，如实记账 | docs/系统设计说明.md §7 与 §13.1 |
| FR-21 | 停机事件与停机损失：由报警与运行状态派生停机记录并绑定损失，作为可靠性表的输入 | scada_10min、报警台账 | 停机事件件、损失月表 | 停机事件按台落盘；损失月表与输入跨度对拍通过 | docs/系统设计说明.md §13.1；docs/数据目录结构与落位约定_v0.2.md §4 |
5.7 本体与问答
表 5-7 本体与问答（FR-22 至 FR-25，样本场实测（2026-09-22））
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-22 | 本体知识层：把厂商技术资料（手册、对译表、维护作业指导书、图纸）结构化，每条声明出处 | 主机制造商（OEM）技术资料（318 件 / 2.94 GB） | 对象库、检索索引、实机参数表 | 故障码覆盖 263 与 322；本体审计 0 问题 | docs/系统设计说明.md §13.1 |
| FR-23 | 本体铺开：零判级权，只转录一层正本；同部件多源判级并存不合并；每条判定带审级与证据回溯 | 判级矩阵、融合表、各产物台账 | 对象库对象与判定条目 | 对象库实测规模为 9,613 对象（另见口径差异说明，§11.3）；审计退出码 0 | docs/系统设计说明.md §13.1 |
| FR-24 | 决策链进度与趋势证据：每台一个决策对象记六步状态、卡点与下一步；在升与闭环证据挂到机组与部件 | 运行时链盘接口、部件历史件 | 决策对象与趋势证据对象 | 需服务在跑；重复执行幂等覆盖 | docs/系统设计说明.md §13.1 |
| FR-25 | 问答：模型只转述本体与事实契约，不产生新判级；校闸拦不下的句子不出文并给原因；升档目标按「配置档位且确已安装」解析 | 问题文本、本体与契约、本机模型（可选） | 答案与引文块、校闸结论、模型审计日志 | 台号与数字能回抓源记录；两档都拦则不出文并给原因；升档目标没装时响亮回落并打日志 | docs/说明书_观澜…v0.2.md §4.2；HISTORY 2.9.1 |
5.8 报告导出
表 5-8 报告导出（FR-26 至 FR-28）
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-26 | 生成 CMS 标准模版评估报告，三轴表述：状态等级、证据状态、行动等级建议；同时出登记表 | 振动窗索引标量、三层基线、融合级 | 报告 md 与 docx、登记 csv | 38 台逐台有条目；报告章节可跳转；相对判据封顶为候选 | docs/系统设计说明.md §13.1；HISTORY 2.6.0 |
| FR-27 | 事实契约：每条结论含结论编号、脱敏来源引用（文件加 sha16 与章节）、本条 sha256、时间窗、聚合层级与裁决枚举；派生四个消费端 | 由重算台账生成的 claim、评审底稿 | 契约件与门户结论段、工作台卡片、问答引用、报告摘要 | 实测改一条 claim 则四个消费端全变；契约自检不过时报退出码 2 并需人看 | docs/系统设计说明.md §13.1 与 §13.2 |
| FR-28 | 门户结论段重装与汇报纸导出：产物变化后门户结论段随重装刷新；工作台可导出汇报纸 | 契约派生件、门户外壳与内嵌件 | 门户单文件页、汇报纸 | 装配先写临时文件再原子替换，失败不破坏在服务的门户；行尾强制 LF；产物挪走时缺该段属预期 | docs/数据目录结构与落位约定_v0.2.md §6；docs/系统设计说明.md §13.2 |
5.9 运维控制台与重算
表 5-9 运维控制台与重算（FR-29 至 FR-32）
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-29 | 一条命令重算全部：固定依赖顺序、写死验收锚点、幂等可整条重跑；默认 26 步，加跳过 SCADA 为 23 步 | data/raw 原始件、可选现场包目录 | 各仓产物、每步退出码与耗时汇总 | 实跑 --dry-run 得默认 26 步、跳过 SCADA 23 步；某步失败即停并打印该步说明；各步幂等 | scripts/rebuild_all.py；docs/src/_rebuild_plan.txt |
| FR-30 | 运维控制台：按钮按真实状态启用，一个时刻只允许一个动作，越权调用返回 409；显示端口、产物件数与来源台账、进度、退出码与日志尾巴 | 服务状态、产物状态、任务状态 | 控制台页面与动作接口 | 组件都在跑时点启动返回 409；有任务在跑时全按钮灰；停组件服务保留控制台 | docs/重算操作手册_v0.1.md §0b |
| FR-31 | 清除产物为直接删除不留备份，且不动原始件与交付层；运行期一律不从交付包补齐缺件 | 用户确认动作 | 产物清空后的状态与缺件说明 | 清除后再点返回 409；页面显示无产物并给出补件办法；补齐入口定位为离线人工补救 | docs/说明书_观澜…v0.2.md §4.1；docs/系统设计说明.md §13.5 |
| FR-32 | 输入数据自动扫描：逐族指纹发现新增与变化，列出该跑哪几步并记基线；支持自动取消跳过与可选看门狗 | data/raw 递归文件树、族表 | 扫描结论与基线快照、看门狗日志 | 退出码 0 表示无变化、4 表示有新数据（不是失败）、5 表示还没有基线；族表外的目录报未归类且不猜 | docs/输入数据放置指导_v0.1.md §4；HISTORY 2.8.0 |
5.10 门户与检索
表 5-10 门户与检索（FR-33 至 FR-35）
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-33 | 门户为单文件装配产物，壳与件分离；顶部菜单含总览、系统架构、方法、经验发现、案例、振动与 CMS、仿真与回放、交付文档、系统状态、数据重算、登录 | 受管外壳、内嵌交付件、契约派生件 | 门户单文件页 | 拆装回到逐字节相同；行尾 LF 有自检；数据重算页用内嵌版懒加载避免空转轮询 | docs/系统设计说明.md §5.2；docs/数据目录结构与落位约定_v0.2.md §6 |
| FR-34 | 页面归口：登记每一页与子页的内容类型、是否随输入数据变、凭什么这么判；对数据派生页面做陈旧检测 | 页面登记表、产物台账、页面实物 | 归口表与审计结论 | 实跑检查 21 项、不一致 0、已知缺口 19；陈旧检测报退出码 7；未登记页单独列出 | configs/portal_pages.yaml；scripts/pages_audit.py |
| FR-35 | 检索索引：由本体与知识层构建检索索引，词法检索在任何机器上可用，向量检索在装有嵌入模型时启用 | 对象库、CMS 知识库、嵌入模型（可选） | 检索索引件 | 无模型时保持纯词法可用并写明；索引缺失时页面如实说明而不是报错 | docs/数据目录结构与落位约定_v0.2.md §4；docs/系统设计说明.md §13.1 |
5.11 数据接入与体检
表 5-11 数据接入与体检（FR-36 至 FR-38，样本场实测（2026-09-22））
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-36 | 现场包按映射表落位，落位前自动体检：结构、命名、后缀与增量三清单（新增、相同跳过、冲突） | 现场包目录、约定目录树 | 落位结果与体检结论 | 同名不同大小判为冲突并默认拒绝落位；覆盖需显式确认；同尺寸自动跳过可反复跑 | docs/输入数据放置指导_v0.1.md §2 与 §3 |
| FR-37 | 场站扫描辨识：按四条规则辨识 data/raw 下的场站目录，多目录且都不匹配时报未识别并列出扫到的目录 | data/raw 下一级目录、场配置 | 辨识结论与依据 | 依据逐条打印；单站唯一性也要标注为凭唯一性而不是精确匹配；不猜 | docs/数据目录结构与落位约定_v0.2.md §2 |
| FR-38 | 同台多件的 10min 件合并与上游归档口径：同台补充件按列名对齐并按时间戳去重（主件优先）；类目库按信息级列出且不计变化 | 同台补充件、现场年度归档库、类目库 | 合并后的取数结果与扫描结论 | 实测 WTG01 主件 77,551 行加补充件 5,820 行合并 83,353 行、重叠 18 行去重；类目库不再造成每轮误报变化 | HISTORY 2.8.0 与 HISTORY 2.8.2；docs/输入数据放置指导_v0.1.md §4.1 |
5.12 安装、服务化与卸载
表 5-12 安装与服务化与卸载（FR-39 至 FR-43，样本场实测（2026-09-22））
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-39 | 离线安装：Windows 侧包内带全部离线依赖轮子可完全离线安装；无合格解释器时用包内便携运行时；安装目录不得含空格与中文 | 交付包、机器上的解释器与架构 | 虚拟环境与配置、安装记录 | 实装实测约 10 分钟量级（本机记录 172 秒）；麒麟与统信与 Ubuntu 与 CentOS 走对应脚本 | docs/说明书_观澜…v0.2.md §3；README_先读我.MD 第一节 |
| FR-40 | 服务化常驻：Windows 服务或 systemd 单元或登录自启三种形态，两平台共用同一工作体，行为与手工启动一致 | 服务注册器、服务体脚本、服务配置 | 托管进程与开机自启 | 巡检周期 15 秒；无权限时给出可执行建议并返回退出码 3 而不是抛异常 | docs/系统设计说明.md §14.1 与 §14.3 |
| FR-41 | 安装时版本检查：读安装记录与本包版本比对，分没装过、相同、升级、降级、老安装无记录五类提示并询问是否重装 | install-info.json、本包版本 | 提示与交互、更新的安装记录 | 五类提示文案与动作与规则一致；跳过询问的开关可用；非交互时自动继续并打印说明 | docs/系统设计说明.md §14.2 |
| FR-42 | 卸载闭环：默认只拆本程序装上去的东西（停服务、注销服务、撤自启、删快捷方式、清运行态、删安装记录），默认保留数据、产物、日志、虚拟环境与程序目录 | 卸载入口与实现脚本 | 卸载结果与手工收尾命令 | 自检两类断言：步骤齐全、只读预演无副作用；实跑断言记录与运行态与快捷方式都被拆掉且数据与产物一件不少 | docs/系统设计说明.md §14.5 |
| FR-43 | 打包与开箱验证：一条命令出包，默认不含输入数据、产物、运行日志与临时文件；打包器自带入口引用闭合与编码守则两道闸；开箱验证解压后真装真起 | 源码树、版本真源 | 交付包与清单文件、开箱验证结论 | 入口引用闭合实跑 48 条全在位；包内出现安装记录或快捷方式即删包并非零退出；页面可用数要求不少于 4 个 | docs/系统设计说明.md §9 与 §9.1 |
6 非功能需求
6.1 非功能需求清单
非功能需求编号 NFR-01 至 NFR-12，共 12 条。它们大多是「性质」而不是「功能」：判据往往是一次实跑的输出，或者一条机器守卫的退出码。
表 6-1 非功能需求（NFR-01 至 NFR-06，样本场实测（2026-09-22））
| 编号 | 需求 | 判据 | 依据文件 |
|---|---|---|---|
| NFR-01 | 离线性：全部计算与页面在本机完成，不依赖外网；本机模型为可选件，缺它时只有问答与本地初筛不可用 | 组件只绑回环地址；模型服务不可达时探针报失败但其余功能不受影响；远端未装模型时如实记录为遗留项 | docs/说明书_观澜…v0.2.md §3.3 与 §4.2；HISTORY 2.9.2 |
| NFR-02 | 单机性能：一条命令重算在单机上可完成，按时间窗重算的单次等待可控 | 实测量级见 6.2；判级约 25 秒每个时间窗、镜头约 10 至 45 秒每个时间窗；模型探针实测 0.77 秒 | docs/系统设计说明.md §16.4；F:\temp_req_check_out2.txt |
| NFR-03 | 可移植与零配置：路径只有一个真源，全部按安装根解析而不按当前工作目录；跨 Windows 与国产化 Linux | 路径助手清单与解析基准；便携运行时覆盖三平台；跨平台部署三条硬约定由脚本门禁 | docs/系统设计说明.md §3.1；docs/数据目录结构与落位约定_v0.2.md §7 |
| NFR-04 | 中文与描述口径：界面文案前后端成对，三条描述口径机器可查 | 语言包实跑 845 条成对；口径清扫覆盖时间窗写法、机组计量说法、英文简写三类 | F:\temp_req_check_out2.txt；docs/系统设计说明.md §17.1 |
| NFR-05 | 审计与可追溯：每件产物能说清谁生成、谁消费、来源是原始件重算还是随包补齐 | 逐件来源台账；反向呼应审计成立 3,548 件、不成立 0 件、未归类 0 件；契约每条带自身 sha256 | F:\temp_req_check_out2.txt；docs/系统设计说明.md §13.4 |
| NFR-06 | 可用性：没有产物也要能打开页面并说清缺件与补齐办法 | 清产物后工作台与振动页返回结构化缺件说明而不是白屏或掐断；无源件时返回 err=no_source | docs/系统设计说明.md §11.4；docs/数据目录结构与落位约定_v0.2.md §5 |
表 6-2 非功能需求（NFR-07 至 NFR-12，样本场实测（2026-09-22））
| 编号 | 需求 | 判据 | 依据文件 |
|---|---|---|---|
| NFR-07 | 可观测性：日志只有一个落点与统一行格式，服务状态与任务进度可见 | 日志实跑无不一致、提示 87 条；网关提供健康自检与版本指纹；控制台显示退出码与日志尾巴并有心跳 | F:\temp_req_check_out2.txt；docs/系统设计说明.md §11.2；docs/重算操作手册_v0.1.md §0b |
| NFR-08 | 数据体量：能在单机上承载本场当前的数据规模并给出资源下限 | 输入实测 26,504 件 / 224.67 GB、产物 3,549 件 / 7,157.5 MB；内存建议 16 GB 起、32 GB 更稳；磁盘 5 GB 加三维资产 1 GB、模型另计 30 至 60 GB | 2026-09-22 实测计数；docs/说明书_观澜…v0.2.md §2 |
| NFR-09 | 安全只读：不写回现场系统、不改原始件、不产生控制指令；对外暴露时须自行在网侧限来源 | 原始件按只读输入对待，落位冲突默认拒绝；对外只有一个网关入口；启动日志每次提醒页面无鉴权 | docs/输入数据放置指导_v0.1.md §3；README_先读我.MD 第二节 |
| NFR-10 | 可维护性：单一真源，改一处不必改多处；关键口径有机器守卫 | 版本号只有一行真源并由三处守卫盯住；路径、配置、日志、语言各有唯一取用口与审计器 | docs/系统设计说明.md §15.2 与 §11.1；docs/系统设计说明.md §3.1 |
| NFR-11 | 无人值守与自愈：长跑的服务要能被托管并自动拉起 | 服务体每 15 秒巡检并拉起掉线组件；崩溃重启策略；远程部署一律用服务，不用会话前台进程 | docs/系统设计说明.md §14.1 与 §14.4；README_先读我.MD 第二节 |
| NFR-12 | 收资清单按场裁剪：以通用收资模板为底，按本场的机型与数据源形态与专题范围裁剪，逐条写明必须、建议、可选或可替代以及「不收会怎样」 | 每一族都有必须性分级与缺件后果且可复核；换场时清单随场定义与机型变化，不是照抄样本场 | 本文第 11 章；《数据要求说明_观澜_2.68.0.docx》第 8 章与第 12 章 |
6.2 性能与耗时实测
性能需求不能只写「要快」，要写「在哪台机器上、什么规模、花了多久」。下表把已取证的耗时集中列出，未取证的项如实标注。
表 6-3 耗时实测汇总（来源见「证据」列；未标日期者为 HISTORY 或文档中的既有记录，样本场实测（2026-09-22））
| 环节 | 耗时 | 证据 |
|---|---|---|
| 自检整体与模型探针 | 模型探针 0.77 秒；同一次 check 结论为全绿 | guanlan.py check 实跑（2026-09-22，本机） |
| 一行命令重算（远端一轮 24 个实质步骤汇总） | 单步量级：输入扫描 53.7 秒、三门台账 164 秒、SCADA 侧 1,025 秒、月度派生 99 秒、振动摄入 2,118 秒、变桨面 385 秒、在升 41.6 秒、基线 15.3 秒、总览页 78 秒、本体审计 7.1 秒、门户重装 3 秒、页面归口 9.5 秒 | HISTORY 2.8.1（远端复核记录） |
| 窄仓全量扫（按时间窗重算的底座） | 约 2 分钟一次全量 | docs/系统设计说明.md §16.3 |
| 判级矩阵按时间窗重算 | 约 25 秒每个时间窗 | docs/系统设计说明.md §16.4 |
| 七镜头曲线按时间窗重算 | 约 10 至 45 秒每个时间窗 | docs/系统设计说明.md §16.4 |
| 控制参数一致性按时间窗重算 | 约 0.6 秒每个时间窗 | HISTORY 2.9.0 |
| SCADA 侧十个构建器（逐台读 10min） | 约 15 分钟 | scripts/rebuild_all.py 步说明 |
| 振动摄入（索引与谱） | 约 14 分钟；153 GB 量级导出约 25 分钟 | docs/系统设计说明.md §13.2；docs/输入数据放置指导_v0.1.md §4.1 |
| 启动到门户就绪 | 约 7 秒内健康自检就绪；批处理入口约 2.3 秒返回 | docs/系统设计说明.md §4.2 |
| 安装（Windows 离线） | 约 10 分钟量级；本机记录 172 秒 | docs/说明书_观澜…v0.2.md §3.1；docs/系统设计说明.md §4.2 |
| 本机问答 | 显存不足时首答 30 至 60 秒；复杂题在升档下 5 至 15 分钟 | docs/说明书_观澜…v0.2.md §2 与 §11 |
6.3 可移植与零配置
「零配置」在本系统里有一个明确的技术含义：路径只有一个真源，且解析基准是安装根而不是当前工作目录。这条需求来自一串真实缺陷：写死场站名的路径在多场部署时会静默串场；按当前目录解析的相对路径在从别处启动时会读不到；同一个规则在三个文件里各写一遍就会出现两套显示口径。现在的口径是：代码与配置里只写相对路径，运行期由路径助手解析成绝对路径；产物只落在产物仓，原始件只从原始件目录读，交付静态层只为分发而存在；三者不互相写。
与可移植相关的还有两条：一是解释器探测顺序（先看配置里指定的解释器，再看安装目录下的虚拟环境，最后回落到当前解释器），这让安装目录整体拷到别的盘或别的机器后仍然可用；二是输入输出脚本的字符守则（安装脚本用带 BOM 的 UTF-8 加 CRLF、批处理纯 ASCII 且 CRLF 无 BOM、shell 脚本 LF），三条都是现场真实事故换来的，并由打包、开箱验证与装机自检三处强制执行。
6.4 可维护性与单一真源
单一真源的范围在本版已经覆盖五项：版本号、路径、配置、日志、界面文案。每一项都配了「改一处、机器替你查其余几处」的守卫，例如版本号改动后由版本记录一致性门与打包器读真源保证同步，配置改动由配置审计器检查目录约定、命名、内容与引用闭合，日志改动由日志审计器检查唯一落点与行格式，界面文案改动由语言包检查保证前后端成对。
表 6-4 单一真源与对应守卫（样本场实测（2026-09-22））
| 真源 | 管什么 | 守卫与实跑结果 |
|---|---|---|
| src/version.py | 名称、版本、版本规则、版本史、包名 | 版本记录一致性检查；check 实跑报 v2.68.0 且记录表与代码一致 |
| src/paths.py | 一切路径解析的基准与助手 | 配置审计器检查不手拼路径；实跑无不一致 |
| configs 目录与登记表 | 端口、模型档、场配置、页面归口、配置登记 | 配置审计实跑已知缺口与白名单 14 条、提示 7 条 |
| src/logfile.py | 日志目录、命名、行格式、保留策略 | 日志审计实跑无不一致、提示 87 条 |
| src/windscada/lang.py | 中英界面文案成对 | 语言包实跑 845 条成对 |
| src/entry_refs.py | 入口脚本引用的文件必须都在包里 | check 实跑入口引用闭合 48 条全在位；编码守则通过 |
7 数据需求概述
7.1 数据族与功能映射
系统的数据需求可以概括成一句话：七类现场源件加一类共享机理资料，喂出九个产物仓，页面只读产物。每个源类目录名就是摄入接口，改名等于换接口。数据族与功能的对应关系如下表；逐类的字段、单位、必须性与质量要求见同批交付的《数据要求说明_观澜_2.68.0.docx》。
表 7-1 数据族到功能的映射（样本场实测（2026-09-22））
| 源族（约定落位） | 谁消费 | 喂出什么功能 | 进链步骤 | 现状 |
|---|---|---|---|---|
| 故障报警 | 报警摄入器 | 报警台账、停机损失、限电绑定 | ② 三门台账 | 16 件 / 23.8 MB，结构合规 |
| 风机故障记录 | 工单摄入器 | 检修工单台账、重复检修、闭环验证 | ② 三门台账 | 137 件 / 149.8 MB，其中台账 123 件、附件 14 件 |
| 油样报告 | 油样索引摄入器 | 油液化验索引、油液时效、融合面油样轴 | ② 三门台账 | 404 件 / 176.2 MB，两级目录合规 |
| scada_10min | 取数层与十个构建器 | 功率曲线、损失、温度、停机、偏航、液压、热链、变桨面日粒度 | ③ 与 ④ 与 ④c 与 ⑤b | 114 件 / 16.75 GB，含同台补充件 |
| scada_1min | 取数层 | 变桨面零位三口径与越线计数 | ④c 变桨面 | 38 件 / 13.71 GB |
| scada_mdb | 取数层（CSV 缺失时回落） | 同上（年度归档库） | ③ 与 ④ 与 ④c | 100 件 / 48.25 GB，其中消费 76 件、缺口 24 件 |
| windcms | 振动摄入与报告转录 | 振动窗索引、谱库、CMS 报告、逐台页、在升闭环、三层基线 | ④b 与 ④d 与 ④e | 25,693 件 / 161.22 GB，其中解码导出 25,679 件 |
| m5_cms_tcm | 融合面与报告侧 | 现场正本优先的 handoff 与部件历史、厂家报告转录 | ④b 振动摄入 | 1 件 / 21.8 MB；正本缺失时由观澜自算件顶上 |
| 主机制造商（OEM）技术资料（与场站并列的共享目录） | 本体层 | 码表、手册、工单展开、失效树、实机参数、检索索引 | ⑦ 本体层 | 318 件 / 2.94 GB，结构合规 |
7.2 体量与现状
表 7-2 数据与产物现状（源族数字取自 2026-09-21 的扫描快照，合计取自 2026-09-22 实测计数，样本场实测（2026-09-22））
| 项 | 数量 | 体积 | 备注 |
|---|---|---|---|
| 输入源件（data/raw/<场站>，递归） | 26,504 件 | 224.67 GB | 同一棵树在 guanlan.py check 里报 26,503 件，两者相差 1 件，计数口径差异未取证 |
| 产物（outputs/<场>，递归） | 3,549 件 | 7,157.5 MB | 含仓级台账 3 件；反向呼应审计报成立 3,548 件 |
| 其中振动窗与谱仓 | 3,417 件 | 占比最大 | 谱分片与窗级分析件 |
| 其中标准仓 | 57 件 | — | 含窄仓子目录与总览单页 |
| 未归类件 | 1 件 | — | 场站目录下的一份按月提取核对件，按设计不作为摄入源 |
| 缺口 | 24 项 | — | 年度归档库中 7 月的十个类目库，扫描器按缺口级列出并写明消费者口径 |
数据现状里有两处必须如实说明。第一处是缺口：年度归档库 2026 年 7 月有 10 个类目库不在位（每类一件，扫描器按缺口级列出并提供消费者口径），另外类目库本身是上游归档件，取数层不直接读它，需要先合成为同台补充件才会被摄入。第二处是按月提取核对件：场站目录下有一份按月提取的核对件，位置由用户指定、不是摄入源，扫描器按名字模式忽略，既不报未归类也不计入变化。
7.3 与数据要求说明的分工
本文只回答「要哪些数据、这些数据支撑什么功能」。数据的字段级要求（核心测点的名称、单位、必须性、缺失替代、对齐规则、质量门与核对锚点）以及面向现场的收资清单，写在《数据要求说明_观澜_2.68.0.docx》里。该文档按用户令要求与现场收资文件逐条对照，并对现场收资层面的已知缺失逐条如实记录，例如测风塔数据为零交付、故障录波只有 4 台、振动侧 handoff 正本缺失由观澜自算件顶上、远端机器未安装本机模型等。
8 页面与信息架构需求
8.1 页面归口规则
页面归口要回答两个问题：这一页该不该随输入数据变化；它算不算产物。答案落在五类内容类型上，每一类都有机器可查的规则，登记表里逐条写明判定依据（看的是页面里有没有内嵌数据、有没有实时取数、有没有产物引用，以及内容是不是由原始件算出来的）。要改分类，先改证据，这是需求层面的一条纪律。
表 8-1 五类页面内容类型与机器规则
| 类型 | 该随数据变 | 算不算产物 | 机器查什么 |
|---|---|---|---|
| 受管静态 | 否 | 不是 | 正文不得引用产物，引用了说明分类错了 |
| 实时取数 | 是，永远一致 | 页面本体不是 | 内嵌或链接的端口必须在已知服务表里 |
| 产物引用脚注 | 否，正文不变 | 正文不是，被引产物是 | 被引用的产物路径必须存在，悬空即报 |
| 数据派生 | 是 | 是 | 必须有来源加指纹或生成时间；有指纹就与当前产物比对做陈旧检测 |
| 冻结交付件 | 否，按交付版本变 | 不是运行时产物 | 文件名或正文必须能读到版本号与日期 |
8.2 门户页面归口表
表 8-2 按登记表逐条列出页面与子页的归口结论。登记表顶层条目 25 条，含 7 条子页共 32 条；归口审计实跑输出为「检查 21 项：不一致 0、已知缺口 19」，其中 21 项是审计的检查行数（19 条为引用悬空或溯源缺失的已知缺口项，2 条为两个数据派生页面的溯源检查项，均一致），与登记表的条目数不是同一个口径，两者都不矛盾，此处一并写明以免混淆。
表 8-2 门户页面与子页归口表（25 条顶层条目加 7 条子页，样本场实测（2026-09-22））
| 页面或子页 | 类型 | 随输入数据变 | 判定依据摘要 |
|---|---|---|---|
| index 总览 | 受管静态 | 否 | 外壳段约 2,519 字节，无内嵌与取数与产物引用，正文是产品承诺与入口导航 |
| architecture 系统架构 | 受管静态 | 否 | 外壳段约 3,037 字节，无数据引用，描述分层架构 |
| method 方法 | 受管静态 | 否 | 外壳段约 2,959 字节，无数据引用 |
| findings 经验发现 | 受管静态 | 否 | 外壳段约 2,322 字节，内容是公司级经验与内部检查条数，不是本场站数据的函数 |
| case_hydraulic 案例与液压 | 受管静态 | 否 | 外壳段约 6,187 字节，无数据引用 |
| cms 振动与 CMS | 实时取数 | 是 | 一个内嵌加两个链接指向振动服务，服务按需读产物，页面本身不存快照 |
| recalc 数据重算 | 实时取数 | 是 | 链接到运维控制台，后端即真实状态 |
| login 登录 | 实时取数 | 是 | 链接到工作台 |
| admin 系统状态 | 实时取数 | 是 | 外壳脚本拉健康自检接口渲染，段内无静态数字 |
| sim 仿真与回放 | 受管静态 | 否 | 外壳段约 50,767 字节为静态叙述，六个链接指向仿真台与三维台；输入是图纸与机型参数 |
| 子页 控制律仿真台资料包（5 页） | 冻结交付件 | 否 | 仿真合页服务直接从冻结资料包读取，日期在包名里 |
| 子页 三维拆装工作台 | 受管静态 | 否 | 三维资产由图纸与模型构建，与原始件无关 |
| 子页 控制律仪表台面板（门户内嵌） | 产物引用脚注 | 否 | 静态判据说明加一条产物脚注引用，被引目录不在包内，已按悬空如实记账 |
| 子页 四系统判据面板（门户内嵌 4 份） | 产物引用脚注 | 否 | 同上，静态正文加产物脚注 |
| documents 交付文档 | 受管静态 | 否 | 外壳段约 5,690 字节为导航页，一个内嵌指向网关下发的治理清单页，段内不含数据快照 |
| 子页 治理清单交付包 | 冻结交付件 | 否 | 文件名自带版本号与日期，客户交付件按交付版本冻结 |
| 子页 全场状态一览（脱敏） | 冻结交付件 | 否 | 性质是数据派生但无指纹无生成端，按用户裁决按冻结交付件管并把会变旧的风险如实记账 |
| 子页 场站取数单 | 冻结交付件 | 否 | 只有日期没有指纹，无生成端，且它引用的两棵产物树不在包内；保留不删并记账 |
| page_product_cms CMS 报告页与件 | 数据派生 | 是 | 振动服务读的就是产物页面件；已在产物台账中登记并有溯源 |
| page_product_vib_raw_manifest 振动摄入清单 | 数据派生 | 是 | 每次振动摄入重写，记件数、跨度与未随包缺口；已在台账中登记 |
| embed_replay_chain 传动链回放（内嵌） | 数据派生 | 是 | 内嵌数据带来源与指纹，源产物在本包不在位，故现只能按生成时间判新旧 |
| embed_standard_panel 标准面板（内嵌） | 数据派生 | 是 | 正文带生成时间与产物引用，缺指纹；被引的发布件不在包内 |
| embed_coverage_ch0 覆盖度报告（内嵌） | 数据派生 | 是 | 正文写有来源与指纹，但那份源件不在包内，溯源链断在包外 |
| embed_u6_sim 变桨液压仿真台（内嵌） | 受管静态 | 否 | 图纸派生的物理回路仿真面板，无内嵌数据与指纹 |
| embed_u6_health 液压公共站健康报告（内嵌） | 冻结交付件 | 否 | 客户交付报告，无数据指纹，按交付件冻结 |
| embed_gearbox_report 整机综合诊断报告（内嵌） | 冻结交付件 | 否 | 报告类交付件，文件名带修订版号 |
| embed_reports_4 分系统评估报告（内嵌 4 份） | 冻结交付件 | 否 | 交付报告，无内嵌数据与指纹 |
| embed_governance_12 治理清单分册（内嵌 12 份） | 冻结交付件 | 否 | 与交付层分册同源，冻结交付件 |
| embed_sc1_local 本地占位（内嵌） | 受管静态 | 否 | 小体积占位面板 |
| detail_tabs 工作台十个标签 | 实时取数 | 是 | 单页应用按标签现场取数，产物指纹变化自动重载，页面本体不存快照 |
| delivery_pages_all 交付页 | 冻结交付件 | 否 | 客户交付件自带版本号与日期；其中两页性质上是数据派生，另见逐页判定 |
| viewer_pages_all 三维页 | 受管静态 | 否 | 图纸与模型派生的资产页，与原始件无关 |
按类型统计的分布如图 3-1 所示。本表口径下 32 条条目中，受管静态 11 条、实时取数 5 条、数据派生 5 条、冻结交付件 9 条、产物引用脚注 2 条。这张统计的意义在于：真正需要随输入数据变的只有 5 条数据派生条目与 5 条实时取数条目，其余 22 条要么是受管正文、要么是按版本冻结的交付件，把它们混进「产物管理」只会制造无谓的维护负担。
8.3 页面陈旧检测要求
数据派生页面的核心风险是「数据换了页面没换」，也就是页面里烘进去的快照与当前产物不一致。需求因此要求三件事：一是每条数据派生条目必须有来源路径，并且有指纹或生成时间；二是有指纹的必须与当前产物比对（逐字节比对哈希），不一致即报陈旧；三是登记表里写清「为什么这么判」，可复核。检查器的退出码语义为：0 表示一致，5 表示缺文件或未登记，6 表示溯源缺失，7 表示页面陈旧，8 表示交付件缺版本号，9 表示分类错。
当前如实状态是：登记表里 19 条已知缺口全部是「页面引用了本包没有的产物树」，逐条写明理由而不装作通过；这些页面因此拿不到当前值做比对，其中两条数据派生页面没有生成端、三条内嵌快照缺指纹只能按生成时间判断。这三类都记账在案，待相应产物线随包后复检。
9 验收需求与质量门
9.1 质量门全景
系统的验收分两层：装机自检看「这台机器能不能用」，重算链验收看「这一轮数据算得对不对」。前者是 guanlan.py check 的四十余条判定行，后者是重建命令每一环的退出码与容忍口径。两层的关系是：自检不通过就不该跑重算（环境或依赖有问题），重算链跑完再由自检复核产物与台账。
表 9-1 验收门分类与数量（依据 guanlan.py check 实跑输出，2026-09-22，本机，样本场实测（2026-09-22））
| 分类 | 判定条数 | 代表门 | 实跑结果 |
|---|---|---|---|
| 运行环境与依赖 | 10 | Python 版本不低于 3.11（实测 3.12.10）；九个第三方依赖逐个导入 | 全 OK |
| 静态质量门 | 4 | 源码可编译 229 个文件；语言包 845 条成对；入口引用闭合 48 条；入口脚本编码守则 | 全 OK |
| 子进程口径 | 3 | 捕获输出可用；无窗口启动输出进日志；无窗口位已设，标志位 0x8000200 | 全 OK |
| 版本与卸载入口 | 2 | 版本管理与记录表一致（v2.68.0，包名 app_guanlang_v2.68.0.zip）；卸载入口两个都在位 | 全 OK |
| 制品与台账审计 | 5 | 反向呼应 3,548 件成立；页面归口检查 21 项；配置统一；日志统一；输入数据放置体检 26,503 件结构合规 | 全 OK |
| 产物与发布件在位 | 10 | 标准仓、本体对象库、findings、事实契约、门户、仿真合页服务与资料包、三维资产、仿真回放资产、治理清单交付件 | 全 OK |
| 原始件目录 | 1 | 原始件目录存在（无数据时此项不影响页面） | 全 OK |
| 模型闸 | 6 | 默认档探针 0.77 秒；四个模型档逐个在位；模型可用性正常并记录审计日志 | 全 OK |
| 合计 | 41 | 另有 6 条端口状态行不计入判定 | 结论全绿，可 serve，退出码 0 |
验收门的分类与数量如图 7-1 所示。该图与上表同源，都取自本次自检实跑的 41 条判定行；按上表的分类口径，环境与依赖一类共 10 条、静态质量门 4 条、子进程口径 3 条、版本与卸载入口 2 条、制品与台账审计 5 条、产物与发布件在位 10 条、原始件目录 1 条、模型闸 6 条。其中真正体现「这个系统有没有把口径管住」的是制品与台账审计那五条门与四条静态质量门。
9.2 重算链的逐步验收门
重算链默认 26 步，加跳过 SCADA 为 23 步（另有第 ① 步仅在给了现场包目录时才跑）。每一步都是一个验收门：非零退出即停下并打印该步说明，容忍清单里的退出码不算失败，但会在汇总行里如实标出退出码。这个设计的关键在于「容忍不等于通过」：例如月度派生件找不到基线时返回 5，含义是「跳过了等价验收」，而不是「验收通过」。
表 9-2 重算链逐步验收门（默认 26 步，样本场实测（2026-09-22））
| 序 | 步骤 | 主要脚本或命令 | 容忍退出码 | 非零的含义 |
|---|---|---|---|---|
| 1 | ① 放数据（仅当给了现场包目录） | place_raw_data.py | 无 | 落位失败或冲突被拦下 |
| 2 | ①b 输入数据扫描 | raw_scan.py --check --write | 4 与 5 | 4 表示有新数据（不是失败），5 表示还没有快照 |
| 3 | ② 三门台账 | rebuild_from_raw.py | 无 | 报警或工单或油样摄入失败 |
| 4 | ③ SCADA 侧十个构建器 | rebuild_from_raw.py --scada | 无 | 原始件缺失或读取失败 |
| 5 | ③b 标准仓窄仓 | scada_slim_build.py | 无 | 按时间窗重算的底座没建起来 |
| 6 | ④ 月度派生件 | windscada_monthly_build.py | 5 | 找不到随包基线，跳过等价验收 |
| 7 | ④b 振动摄入与报告与标量 | vib_raw_build.py | 无 | 解析出错；没有振动原始件时空跑属正常 |
| 8 | ④c 变桨面 | pitch_face_build.py | 4 | 找不到 SCADA 原始件，按缺件如实报 |
| 9 | ④d 振动在升与换件闭环 | component_history_build.py | 4 | 本机没有振动窗索引，按缺件如实报 |
| 10 | ④e 三层基线 | baseline_38_build.py | 4 | 同上 |
| 11 | ⑤b 由重算台账生成 claim | sop_findings_from_ledger.py | 无 | 台账不足以生成结论 |
| 12 | ⑤c 事实契约构建与渲染 | guanlan_facts_contract.py build | 2 | 契约自检不过，需要人看 |
| 13 | ⑤a 逐件来源台账 | products_restore_missing.py --refresh | 无 | 账实不符 |
| 14 | ⑤ 反向呼应审计 | products_reverse_audit.py --check | 5 | 有未归类件或判据失败，停下看清单 |
| 15 | ⑥ 重启组件服务（停，保留网关） | _ops_stop_keep_gateway.py | 无 | 停服务失败 |
| 16 | ⑥ 重启组件服务（起） | guanlan.py serve | 1 | 有模块未就绪属降级正常状态 |
| 17 | ⑦ 本体码表与手册与文档 | kb_ingest | 无 | 技术资料缺失会降级并打印提示 |
| 18 | ⑦ 本体铺开判级与台账 | populate | 无 | 一层正本缺失或来源不足 |
| 19 | ⑦ 本体决策链进度 | chain_ingest | 无 | 服务未在跑则取不到链盘 |
| 20 | ⑦ 本体在升与闭环证据 | trend_ingest | 无 | 源缺失 |
| 21 | ⑦ 本体检索索引 | retrieval.build | 无 | 索引构建失败 |
| 22 | ⑦ 本体实机参数表 | maintenance.refresh_params | 无 | 参数源缺失 |
| 23 | ⑦b 全场状态总览页 | windscada_overview_build.py | 无 | 缺产物时响亮报错，不产出半张页 |
| 24 | ⑧ 本体审计 | ontology.audit | 无 | 期望 0 问题 |
| 25 | ⑧b 重装门户 | portal_build.py | 1 | 缺契约产物时属预期，门户保留原样 |
| 26 | ⑧c 页面归口审计 | pages_audit.py --check | 5 与 6 与 7 | 7 表示有页面陈旧；5 表示被引产物不在位；6 表示溯源缺失 |
| 27 | ⑧d 版本记录一致性 | version_log.py --check | 6 | 文档与版本真源不一致，需同步文档 |
| 28 | ⑧ 台账等价验收（仅加开关时） | rebuild_from_raw.py --verify | 4 与 5 | 4 表示有需人工看的差异；5 表示没基线即没做验收 |
关于步数需要两点说明以免误读。第一，表中共列出 28 条命令行，其中第 1 步（放数据）仅在给了现场包目录时才执行，最后一步（台账等价验收）仅在加了对应开关时才执行，因此默认计划的实跑步数是 26 步，加跳过 SCADA 选项后是 23 步。第二，「门」与「步」不是一一对应：第 ⑥ 步拆成停与起两条命令各算一步，第 ⑦ 步拆成六条命令各算一步，所以表里的命令行数多于环节数。
9.3 检查器的退出码语义
表 9-3 主要检查器的退出码语义与容忍口径
| 检查器 | 退出码语义 | 链上容忍 |
|---|---|---|
| guanlan.py check | 0 全绿可启动；2 有失败项 | 不作为链上步骤，装机后人工核 |
| rebuild_all.py | 0 全部完成；1 有步骤失败（失败即停） | 汇总行逐条标 OK 或 OK 带退出码或 FAIL |
| pages_audit.py | 0 一致；5 缺文件或未登记；6 溯源缺失；7 页面陈旧；8 交付件缺版本；9 分类错 | 容忍 5 与 6 与 7 |
| products_reverse_audit.py | 0 全部有来路；5 有未归类件或判据失败 | 容忍 5 |
| version_log.py | 0 与版本真源一致；6 记录表需重生成 | 容忍 6 |
| config_audit.py | 0 无不一致；8 存在旧副本等结构问题 | 未进链，由 check 报 |
| raw_scan.py | 0 无变化；4 有新增或变化（不是失败）；5 还没有基线 | 容忍 4 与 5 |
| raw_data_check.py | 0 合规；5 结构或命名违例；6 增量冲突；7 缺源类或时间空洞；8 仅有提示 | 未进链，由 check 报 |
| rebuild_from_raw.py --verify | 0 逐值一致；4 有需人工看的差异；5 找不到基线即没做验收 | 容忍 4 与 5 |
| ontology.audit | 0 无问题 | 不容忍 |
| service_ctl.py | 0 成功；3 权限不足（给出可执行建议） | 未进链，人工执行 |
9.4 开箱验证与卸载核验
交付质量有两条独立的核验路径：打包后的开箱验证（在临时副本上真解压、真安装、真起服务、真核页面）与卸载核验（在刚装好的副本上真跑卸载并断言拆除范围与保留范围）。两条路径的意义是：它们都作用在副本上，不打扰正在运行的实例。
表 9-4 开箱验证与卸载核验的项与判据（样本场实测（2026-09-22））
| 核验路径 | 核验项 | 判据 | 实测记录 |
|---|---|---|---|
| 开箱验证 | 入口引用闭合与编码守则 | 入口脚本引用的文件必须都在包内；编码与字符守则全部通过 | 解压 3,734 件，入口引用闭合通过（2026-09-17 记录） |
| 开箱验证 | 离线安装 | 安装脚本退出码 0 | 本机记录 172 秒、退出码 0 |
| 开箱验证 | 快捷方式与无窗口 | 两份快捷方式在位；无控制台窗口断言成立；包内无被弃用的脚本宿主文件 | 窗口句柄为 0，断言通过 |
| 开箱验证 | 页面可用性 | 核验门户与工作台与振动与运维控制台与健康自检五个入口，要求不少于 4 个可用 | 实测 4 个可用（振动入口因无产物返回 503，属预期） |
| 开箱验证 | 逐件复核 | 包内每个文件与工作树逐字节相同 | 3,733 件逐字节相同 |
| 卸载核验 | 拆除范围 | 安装记录、运行态、快捷方式都被拆掉 | 在临时副本上真跑卸载，退出码 0 |
| 卸载核验 | 保留范围 | 数据与产物一件不少，端口已释放 | 件数不变，断言通过 |
| 卸载核验 | 只读预演 | 内容断言（步骤齐全）与副作用断言（预演后关键目录与文件的存在性与字节数完全不变） | 自检全绿 |
关于「五个入口全可用」这一条，需要如实说明：判据本身是「不少于 4 个可用」，实测记录为 4 个可用，第 5 个（振动入口）在没有产物的机器上按设计返回 503 并给出缺件说明。本次编写未取到 5 个全部可用的实测记录，因此本文不写「5 个全通过」，只写「判据为不少于 4 个、实测 4 个」，并把「在产物在位的机器上复跑取证」列为后续动作（未取证）。
9.5 本次实跑结论
本次编写期间对只读项做了三次实跑：自检（guanlan.py check）结论为全绿可启动、退出码 0、无失败项；归口审计（pages_audit.py --check）结论为全部一致、退出码 0、21 项检查里 19 项是已登记的已知缺口；重算计划（rebuild_all.py --dry-run）打印默认 26 步、跳过 SCADA 为 23 步，全部步骤命令与脚本都在位。没有执行任何重算或耗时计算，本文中与耗时有关的数字全部来自既有的 HISTORY 记录与设计文档，来源逐条列在表 6-3。
10 约束、假设与明确不做
需求的可信度一半来自「写清了不做什么」。本系统的边界不多但很硬：它是只读分析系统，不是控制系统，也不是云端服务。
表 10-1 约束、假设与明确不做（样本场实测（2026-09-22））
| 类别 | 条目 | 说明与依据 |
|---|---|---|
| 约束 | 不写回现场系统 | 全部产物落在本机产物仓，不下发指令、不修改现场任何系统；原始件按只读输入对待，落位冲突默认拒绝 |
| 约束 | 不做实时控制 | 最小时间粒度是分钟级数据（10min 与 1min），系统的输出是分析与建议（带证据级与处置措施），没有控制回路 |
| 约束 | 无外网 | 计算、页面、检索都在本机完成；Windows 侧离线安装件与便携运行时随包；本机模型为可选件且单独交付 |
| 约束 | 不做云端 | 事实契约层留有可上云面孔（脱敏派生件），但本版不部署云服务、不做账号体系、不做多租户 |
| 约束 | 页面无鉴权 | 这是知情取舍而非疏忽：对外监听等于把全场运行数据摊开，必须在网侧限来源或在反向代理加认证，启动日志每次提醒 |
| 约束 | 安装目录不得含空格与中文 | 安装脚本、批处理与部分第三方组件的既有约束，写在说明书的系统要求一节 |
| 约束 | 数据规模受单机资源限制 | 当前输入 26,504 件 / 224.67 GB；整条重算在单机上以小时计，建议内存 16 GB 起 |
| 假设 | 现场数据按约定目录与命名交付 | 源类目录名即摄入接口，改名或多套一层会导致摄入静默读不到，因此用体检器与落位脚本前置把关 |
| 假设 | 现场具备解释器或允许使用包内便携运行时 | 麒麟与统信自带解释器多为 3.7 与 3.9，跑不了本项目依赖，故包内带便携运行时 |
| 假设 | 有至少一份能解析的厂商报告与至少一段原始运行数据 | 否则相关面按缺件如实报，不产出假数；这也是标定一次基线的前提 |
| 假设 | 无人值守场景会使用服务而非会话前台进程 | 会话里起的进程会随会话关闭被一起收掉，远程部署必须用服务 |
| 不做 | 不做训练回路 | 本版不含训练，模型只做转述与解释，判断在代码里 |
| 不做 | 不做知识图谱的自动推断 | 本体层零判级权，只转录一层正本；同部件多源判级并存不合并 |
| 不做 | 不做实时数据流接入 | 数据以批的方式落位、体检、重算；服务侧看门狗只做到发现变化并列出该跑的步骤，不做流式处理 |
| 不做 | 不为「无生成端」的件做运行期补齐 | 运行期一律不从交付包补齐；缺件要么放原始件重算，要么由研发补生成端 |
| 不做 | 本版不承诺「多场并存运行」的完整交付 | 场配置机制与场定义装载已接通，但本版端到端跑通并留下实测记录的只有样本风电场；新场接入按第 11 章的多风电场适用性需求与换场验收检查表执行，不把「配置里放一个场文件」当作换场完成 |
11 多风电场适用性需求
11.1 适用性目标
本章回答一个问题：换一座风电场，要改什么、不要改什么。目标是同一套系统（同一份代码、同一个交付包）与同一份需求文档，在不改代码的前提下换场运行；换场时只改两类东西——配置与数据。凡是必须改代码才能换场的，都视为不满足本章要求，回到第 5 章走需求变更。本章的功能需求编号接着原有编号往下排，为 FR-44 至 FR-52；非功能需求为 NFR-12。
适用性目标分三层写清。入口不换：安装、落位、重算、页面与验收的入口和流程与样本场完全一致，现场人员不需要学第二套操作。口径不散：场名、机组数与机组清单、机型参数、原始件路径、判据阈值与界面单位都从配置取，不在代码里写死；一旦写死，多场并存时就会静默串场。缺件不造：新场某一族数据没到位时，系统如实标注缺件并按缺族降级，绝不拿别的场的数字顶替，也不把样本场的阈值当成新场的阈值。
本章有两个词要先定义。「本场」指当前被选中的场，由配置选定，不必然等于本文取数的样本风电场；「换场」指从一场切到另一场运行的整套动作（改配置、放数据、重跑、按检查表复验），不是把两场的数据混在一棵树里。本章沿用的占位符与附录 A 一致：<场>、<场站>、<机型> 按实际风电场替换。
本章需求与《数据要求说明_观澜_2.68.0.docx》《系统设计说明_观澜_2.68.0.docx》配套使用：本章讲「换场要满足什么」，数据要求说明讲「要向新场收哪些数据、哪些可以裁剪」，《设计说明》讲「配置在哪一层生效、哪些参数属于场相关层」。
取证边界要如实写一句：FR-44 至 FR-51 与 NFR-12 有既有的场配置层、摄入层与场级字段语义登记作依据；FR-52 的跨场横向对比是本次新增的口径要求，其实跑记录与机器守卫随后续版本补齐——本文不谎称已经通过。
11.2 场配置化需求
场相关的一切取值都落在场定义文件 app_ETL/configs/farms/<场>.yaml 里，它是场相关事实的唯一真源：代码只读它，不在代码里写场名、机组数或原始件路径。当前场由环境变量 WINDSCADA_FARM=<场> 或程序内的 set_current() 选择，命令行脚本与服务走同一条路。
表 11-1 场配置化需求（FR-44 至 FR-46）
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-44 | 场定义必须有七个必填键：name、n_turbines、turbines、src_10min、src_alarm、store、rated_kw；缺任何一个都在装载时响亮报出缺少的键名，绝不带病进入分析 |
场定义文件 app_ETL/configs/farms/<场>.yaml |
通过校验的场对象 | 七个必填键逐个在位；人为删去任一键时启动即报错并打印所缺键名 | src/windscada/config.py 的 REQUIRED 与 _expand() |
| FR-45 | 当前场由 WINDSCADA_FARM=<场> 或 set_current() 选择，切换只改选择不改代码；以 app_ETL/configs/farms/<场>.yaml 为准（历史 json 兼容）；选到未定义的场，或选到「文件存在但不是场定义」的机型与物理约束 profile 时，必须报未知场并列出可用场 |
环境变量或选择调用、场定义文件 | 当前场对象与其派生的原始件根、标准仓与契约路径 | 换到另一份场定义后，重算与页面取到的是新场的路径与机组数，没有一处残留上一场的取值（不串场） | src/windscada/config.py 的 farm() 与 set_current() 与 available() |
| FR-46 | 场站目录按规则扫描辨识而不写死：场定义里的场站名与目录名完全相同者优先，其次是场名写法互为子串，再次是单站唯一性并标注「凭唯一性」；多个目录且都不匹配时如实报未识别并列出扫到的目录，不猜 | data/raw 下一级目录、场定义 |
辨识结论与依据、本场原始件根 | 四条规则的依据逐条可打印；未识别时页面显示无数据并给出约定位置而不是空路径 | src/windscada/config.py 的 station_scan() 与 station_report()；FR-37 |
11.3 机组与机型可替换
机组数、台号、机型与主机制造商（OEM）的差异不进入引擎：引擎按场对象给出的机组清单与额定容量工作，机型差异通过机型—场站数据契约 app_ETL/configs/contracts/<机型>_<场>.yaml 落到列名、单位与阈值上。换机型等于换契约，不改引擎。
表 11-2 机组与机型替换需求（FR-47）
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-47 | 机组清单、机组数、额定容量与机型参数一律取自场定义与机型契约；turbines 同时支持逐台列举与「前缀加台号区间」两种写法，且 n_turbines 与 turbines 必须自洽；机型的拓扑差异（例如有无齿轮箱）只体现在契约与阈值层，不产生引擎分支 |
场定义的 turbines、n_turbines、rated_kw；app_ETL/configs/contracts/<机型>_<场>.yaml |
逐台循环范围、列名与单位映射、额定容量 | 换一个机组数不同的场后，矩阵行数与台账件数随 n_turbines 变化；同一份判据代码在有机型差异的两场上都能跑完 |
src/windscada/config.py 的 _expand()；app_ETL/configs/farms/<场>.yaml；appETL/configs/contracts/<机型><场>.yaml |
11.4 数据源形态可适配与缺族降级
现场给什么形态，系统都得能接：同一族数据可能以 CSV 转发层、现场月度类目归档库，或其它主机制造商（OEM）的导出形态到场。形态差异由取数层吸收，判据、报告与页面不变。缺族时的口径与「能接」同等重要：如实标注、按缺族降级，不造数。
表 11-3 数据源形态适配与缺族降级需求（FR-48 至 FR-49）
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-48 | 数据源形态可适配：同一族数据以 CSV 转发层、现场月度类目归档库（需先落位成同台补充件）或其它主机制造商（OEM）导出形态到场时，取数层按族统一入口读取，字段语义按本场登记对齐，形态差异不下传到判据、报告与页面 | 各族源件与同台补充件、类目归档库、场级字段语义登记 | 统一取数结果与合并后的序列 | 同台多件按列名对齐并按时间戳去重（主件优先），合并行数与重叠行数如实打印；类目库按信息级列出且不计变化；字段语义与登记不一致时如实标注，不照名字硬用 | FR-38；app_ETL/configs/farms/<场>/field_semantic_registry.yaml；docs/输入数据放置指导_v0.1.md §4.1 |
| FR-49 | 缺族降级口径：某族缺件或缺列时，该族消费者按缺件如实标注并降级，不造数、不用他场数字顶替、不把「认不出」写成「无异常」；缺件清单与补齐办法在页面上可读到 | 各族在位情况、场定义 | 缺件标注、降级后的产物与页面提示 | 每一族的缺失都对应一句可复核的缺件说明；降级不改变其它族的结论；清空产物后页面仍可打开并说清缺件与补齐办法 | FR-31 与 NFR-06；docs/系统设计说明.md §11.4 |
11.5 判据与阈值按场标定
同一套判据结构，参数必须按场标定：结构不变、参数随场变。引擎与判据的层级、判级四轴与七镜头的算法、口径的写法都不因场而异，变的只是参数值。
至少要按场标定的有六类：判级阈值（偏航与变桨的 P95 告警线、绕组与轴承温度的预警与告警档、健康分档线）；额定功率与切入切出风速；时间窗锚点（对照基线与健康期分段的起止）；限电窗（可作为干净判别时间窗的起止区间）；温度档带宽（对照基线与正常带）；机组数与额定容量。标定值落场定义或其引用的机型与物理约束件，不落代码。
参数整组省略是合法写法而不是缺件：直驱机型没有齿轮箱，齿轮箱温度档整组省略即不判该轴；省略要在页面与依据里写明「本场无此判据」，不取一套默认阈值继续判。
表 11-4 判据与阈值按场标定需求（FR-50）
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-50 | 阈值、时间窗锚点、限电窗、温度档带宽等场相关参数一律按场标定并可配：参数落场定义或其引用的机型与物理约束件，同一份判据代码用不同参数跑不同场；本场用不到的参数可以整组省略，省略即不判该轴而不是取默认值硬判 | 场定义的参数段、机型与物理约束件 | 本场生效的阈值集合与判据结果 | 同一台同一系统在两场不同阈值下可以得出不同判级且各自可复算；整组省略的参数在页面与依据里写明「本场无此判据」 | app_ETL/configs/farms/<场>.yaml 的参数段与机型契约；docs/系统设计说明.md §16.2 |
11.6 术语、单位与语言可配
术语与单位不写在页面里，随场取：部件与系统名的写法、功率与温度与转速与风速的单位、中英界面文案三样都要可配；同一字段在不同主机制造商（OEM）的导出里叫法不同时，按本场的字段语义登记对齐，不按名字猜。写英文简写时一律写成「中文（英文简写）」，英文映射的键与中文成对；某条术语或单位在本场没有对应写法时，页面回落中文并如实标注未配置，不显示空白，也不沿用上一场的写法。
表 11-5 术语、单位与语言可配需求（FR-51）
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-51 | 术语、单位与界面语言按场可配：部件与系统名的写法、功率与温度与转速与风速的单位、中英界面文案从配置取；字段语义按本场登记对齐；英文简写一律写成「中文（英文简写）」且中英键成对；缺映射时回落中文并标注 | 场级字段语义登记、机型契约里的单位写法、语言包 | 页面与报告里的术语、单位与文案 | 语言包前后端成对（样本场实测（2026-09-22）为 845 条成对）；换场后单位随配置变化且报告与页面一致；缺映射不显示空白 | src/windscada/lang.py；app_ETL/configs/farms/<场>/field_semantic_registry.yaml；NFR-04 |
11.7 跨场统一口径与横向对比
多场并用时，最容易被误读的是「同一个指标在不同场之间能不能直接比」。本文的口径是：先同口径，再横向比。同口径的前提有四项：同一套判据结构与版本、同一套单位与术语写法、同一套时间窗锚点与样本量判据、同一版本文档与产物口径。四项都成立时，跨场对比只在同一指标、同一时间窗、同一聚合层级上做，并同时给出各场样本量；任一项不成立时，该行标注「口径不可比」并写明差在哪一项，不给可被误读的数字。跨场比的是场与场之间的差异；机组绝对值的对照要在场内做（机群基线与绝对限）。
表 11-6 跨场统一口径与横向对比需求（FR-52）
| 编号 | 需求描述 | 输入 | 输出 | 验收判据 | 依据文件 |
|---|---|---|---|---|---|
| FR-52 | 多场结果按同一判据结构、同一单位与术语、同一时间窗锚点与同一聚合层级输出，支持同口径横向对比；口径不一致时必须标注「口径不可比」并写明差在哪一项，不给可被误读的数字 | 各场同口径产物、场定义、版本真源 | 跨场对比表与其口径说明 | 对比表逐行写出指标、时间窗、聚合层级与各场样本量；任一口径项不一致时该行标注不可比而不是照常出数 | 第 5 章各条判据；NFR-10 |
11.8 按场裁剪的收资清单
收资不是「有多少收多少」，而是按场裁剪：先按通用收资模板判定每一族是必须、建议、可选还是可替代，再按本场的机型拓扑、数据源形态与专题范围裁掉用不上的条目（例如直驱机型不收齿轮箱相关件，不做振动专题的场把振动侧整族列为可选）。裁剪后的清单要写清「不收会怎样」，并作为换场验收的数据侧判据。
表 11-7 按场裁剪的收资清单需求（NFR-12）
| 编号 | 需求 | 判据 | 依据文件 |
|---|---|---|---|
| NFR-12 | 收资清单按场裁剪：以通用收资模板为底，按本场的机型、数据源形态与专题范围裁剪，逐条写明必须、建议、可选或可替代以及「不收会怎样」 | 每一族都有必须性分级与缺件后果且可复核；换场时清单随场定义与机型变化，不是照抄样本场 | 《数据要求说明_观澜_2.68.0.docx》第 8 章与第 12 章；docs/输入数据放置指导_v0.1.md |
11.9 换场验收需求
换场不等于「放完数据能打开页面」，要按固定检查表逐项复验。检查表分五类：配置（场定义本身对不对）、数据（源件在位且可解析）、产物（重算是否真跑出来）、页面（换场后能不能用）、门禁（机器守卫是否全绿）。每一类的通过口径如表 11-8 所示；任一项不通过即视为换场未完成，不允许「先上线再补验」。
表 11-8 换场验收检查表（配置与数据与产物与页面与门禁）
| 类别 | 检查项 | 通过口径 | 对应需求 |
|---|---|---|---|
| 配置 | 场定义七个必填键齐全且自洽 | 装载无报错；n_turbines 与 turbines 的台数一致；rated_kw 与本场容量一致 |
FR-44 |
| 配置 | 选择当前场的方式生效 | WINDSCADA_FARM=<场> 或 set_current() 选定后，取到的路径与机组数都属本场，无上一场残留 |
FR-45 |
| 配置 | 场站目录辨识有依据 | 辨识结论与依据可打印；未识别时指向约定位置而不是空路径 | FR-46 |
| 配置 | 机型契约按机型就位 | app_ETL/configs/contracts/<机型>_<场>.yaml 在位，列名与单位可加载 |
FR-47 |
| 配置 | 判据参数按场标定 | 阈值、时间窗锚点、限电窗、温度档带宽逐项有值，或有「本场不判该轴」的明确省略记录 | FR-50 |
| 数据 | 各族源件按约定目录与命名就位 | 体检结论为结构合规；冲突默认拦下；同尺寸件可反复跳过 | FR-36 |
| 数据 | 源件形态能被取数层读到 | 各族消费者实跑到数；同台多件合并行数与重叠行数如实打印 | FR-48 |
| 数据 | 缺族如实记账 | 每一族缺失都有缺件说明与补齐办法且页面可读到；无造数 | FR-49 |
| 产物 | 一条命令重算全链走通 | 重算按默认步数跑完，每步退出码在容忍口径内或明确报出，整轮退出码 0 | FR-29 |
| 产物 | 产物件数与输入跨度对得上 | 核对锚点逐项达标；台账等价验收通过，或如实标注「没做验收」 | FR-12 与 FR-21 |
| 产物 | 逐件有来路 | 反向呼应审计无未归类件 | NFR-05 |
| 页面 | 门户与各服务按本场数据可用 | 门户、工作台、振动、运维控制台与健康自检五个入口中可用数不少于 4 个；无产物时返回结构化缺件说明 | NFR-06 与 FR-43 |
| 页面 | 页面归口与陈旧检测通过 | 归口审计无不一致；本场数据派生页面无陈旧项（陈旧检测退出码 7 为 0 项） | FR-34 |
| 页面 | 术语、单位与语言随场生效 | 页面与报告的单位、术语、语言与配置一致；未配置项回落中文并标注 | FR-51 |
| 门禁 | 装机自检全绿 | guanlan.py check 无失败项，退出码 0 | NFR-07 与 FR-41 |
| 门禁 | 版本与文档一致 | 版本记录一致性检查通过；安装记录版本与本包版本一致 | FR-41 与 FR-42 |
| 门禁 | 对外口径与去标识化 | 交付文档对样本场标识 0 命中；描述口径（时间窗、影响机组、中文（英文简写））机器可查 | NFR-04 |
换场要动的配置与数据，逐条对应到需求、配置项与验收方式，如表 11-9 所示。这张表是换场作业单的底稿：第一列是需求，第二列是要改或要核对的东西，后两列是凭什么算通过、换场时具体做什么。
表 11-9 多风电场适用性需求与配置项与验收对照
| 需求 | 配置项或真源 | 验收方式 | 换场时的动作 |
|---|---|---|---|
| FR-44 | app_ETL/configs/farms/<场>.yaml 的 name、n_turbines、turbines、src_10min、src_alarm、store、rated_kw |
装载报错清单为空；台数与机组清单一致 | 新建或改写场定义并填齐七个必填键 |
| FR-45 | WINDSCADA_FARM=<场> 或 set_current()；app_ETL/configs/farms/<场>.yaml |
换场后路径与机组数无残留（不串场） | 设定场选择并确认取到本场路径 |
| FR-46 | data/raw/<场站> 的目录名与场名写法 |
辨识依据逐条打印；未识别时报出扫到的目录 | 按约定改名或补场名写法 |
| FR-47 | turbines、n_turbines、rated_kw；app_ETL/configs/contracts/<机型>_<场>.yaml |
机组数变化则矩阵行数与台账件数随之变化 | 换机型契约，台号按实际替换 |
| FR-48 | 取数层的族入口；类目归档库与同台补充件；场级字段语义登记 | 合并行数与重叠行数打印；类目库不计变化 | 按现场形态落位并体检 |
| FR-49 | 各族在位情况与缺件标注 | 每一族缺失都有可复核的缺件说明；无造数 | 能补的补件，补不了的如实记账 |
| FR-50 | 场定义与机型契约里的参数段 | 同系统在两场不同阈值下判级可各自复算；省略项写明不判该轴 | 按新场标定阈值、时间窗锚点、限电窗与温度档带宽 |
| FR-51 | 场级字段语义登记、单位写法、语言包 | 页面与报告单位一致；语言包成对；缺映射回落中文 | 配置本场的术语与单位写法 |
| FR-52 | 各场同口径产物 | 对比表逐行写口径与样本量；不一致标不可比 | 口径项齐备后再出对比 |
| NFR-12 | 通用收资模板加本场裁剪清单 | 逐族必须性分级与缺件后果可复核 | 按本场机型与专题裁剪清单 |
| 换场验收 | 表 11-8 检查表 | 配置、数据、产物、页面、门禁五类逐项通过 | 换场后逐项复验并留记录 |
12 需求跟踪矩阵
跟踪矩阵把 52 条功能需求接到实现、页面或产物、验收门三列上。用它的方式很简单：改一条需求，先在矩阵里找到它对应的实现与验收门，改完之后按验收门那一列重跑对应检查；如果某一行的验收门是「人工核」，说明这条目前没有机器守卫，评审时要特别留意。
表 12-1 需求跟踪矩阵
| 编号 | 实现（脚本或模块） | 页面或产物 | 验收门 |
|---|---|---|---|
| FR-01 | taxonomy.system_matrix；scripts/windscada_serve.py | 系统矩阵、逐台页、问题页 | 判级随所选时间窗变化的实测记录；check 归口与反向呼应 |
| FR-02 | scada_slim_build.py；subsys 各面 registry | 窄仓、判级单元格 | 重算链 ③b 步；窄仓列数与口径同源 |
| FR-03 | perf/availability；reliability.overview | 可靠性表、部件问题页 | 判级与可靠性随时间窗变化的实测记录 |
| FR-04 | windscada_serve.py 的 sys_norm() | 问题页与问题接口 | 传前端标识与中文名都能取到同一份问题（HTTP 抽样） |
| FR-05 | 组件页面自组句逻辑 | 需要关注卡片 | HTTP 抽样：依据不再为空（WTG09 齿轮箱） |
| FR-06 | months_of；win_range；in_win | v2 顶栏时间窗控件 | 时间窗词表逐项验证；退化时间窗按样本不足处理 |
| FR-07 | 顶栏两个日期输入框与校验 | v2 页面自定义起止控件 | 起晚于止时拒绝并提示 |
| FR-08 | 进程缓存与后台线程与预热 | 等待与构建中状态标记 | 判级约 25 秒每个时间窗；等待期页面写明旧口径 |
| FR-09 | curves.build_store；/api/curves | 七镜头曲线 | 图注写随所选时间窗；样本量随时间窗变化 |
| FR-10 | 月度派生件过滤 | 七张月度时序图 | 图注与按月取整口径 |
| FR-11 | control.registry(span=) | 控制参数一致性卡片 | 按时间窗重算约 0.6 秒；封顶中位随窗变化 |
| FR-12 | rebuild_from_raw.py --scada | 损失、功率曲线、停机事件 | 与基线逐值对拍；重算链 ③ 步 |
| FR-13 | <场>_tcm_index.py；<场>_tcm_spectra.py；vib_raw_build.py | 振动窗索引、谱分片、摄入清单 | 振动窗 w0316 索引 2,066,686 行、谱 420,742 条 |
| FR-14 | windcms.py report；report_std 与 report 构建器 | 报告 md 与 docx、逐台页、总览页 | 38 台判级齐；缺融合级写破折号 |
| FR-15 | <场>_fusion_run.py；<场>_fusion_handoff.py；fusion 模块 | 融合表、handoff、全场标量 | 反向呼应审计按族逐件成立 |
| FR-16 | component_history_build.py；trend_ingest | 部件历史件、趋势证据对象 | 重算链 ④d 步；时间窗不足出空表并写边界 |
| FR-17 | baseline_38_build.py | 三层基线件 | 重算链 ④e 步；样本不足如实空表 |
| FR-18 | windscada_alarms_ingest.py | 报警台账 | 39,211 行；键集合并集去重 |
| FR-19 | windscada_workorder_ingest.py | 工单台账 | 5,876 行；差异可归类 |
| FR-20 | windscada_watch_channels_build.py | 油样索引 | 404 行；102 行缺口如实记账 |
| FR-21 | 停机与损失构建器 | 停机事件件、损失月表 | 与输入跨度对拍 |
| FR-22 | app_ontology/.../ontology/kb_ingest.py | 对象库、检索索引、实机参数表 | 本体审计退出码 0；故障码覆盖 263 与 322 |
| FR-23 | app_ontology/.../ontology/populate.py | 对象库对象 | 本体审计退出码 0 |
| FR-24 | chain_ingest；trend_ingest | 决策对象与趋势证据对象 | 幂等覆盖；服务在跑时取链盘 |
| FR-25 | app_ontology/.../ontology/fast_agent.py；llm_gate；检索 | 问答区与引文块、模型审计日志 | 已知答案回放；两档都拦时不出文并给原因 |
| FR-26 | src/windcms/report_std.py；report.py | 报告 md 与 docx、登记 csv | 38 台逐台有条目；相对判据封顶候选 |
| FR-27 | guanlan_facts_contract.py | 契约件与四个消费端派生件 | 改一条 claim 四个消费端全变；自检不过报 2 |
| FR-28 | portal_build.py；门户装配脚本 | 门户单文件页、汇报纸 | 拆装逐字节相同；产物挪走时缺结论段属预期 |
| FR-29 | scripts/rebuild_all.py | 各仓产物与步汇总 | 计划步数实跑；失败即停；幂等 |
| FR-30 | guanlan_ops.py；_ops_run.py；_ops_launch.py | 运维控制台 | 并发动作返回 409；停组件保留控制台 |
| FR-31 | products_state.py；products_restore_missing.py | 产物状态与缺件说明 | 清除后再点返回 409；补齐定位为离线人工补救 |
| FR-32 | raw_scan.py；rebuild_all --auto；service_worker 的看门狗 | 扫描结论与基线快照、看门狗日志 | 退出码 0 与 4 与 5；族表外目录不猜 |
| FR-33 | portal_build.py；shell 与模板装配 | 门户单文件页 | 拆装逐字节相同；行尾 LF 自检 |
| FR-34 | configs/portal_pages.yaml；pages_audit.py | 归口表与审计结论 | 检查 21 项、不一致 0；陈旧报 7 |
| FR-35 | retrieval.build；windcms 知识库构建 | 检索索引件 | 无模型时纯词法可用；索引缺失如实说明 |
| FR-36 | place_raw_data.py；raw_data_check.py | 落位结果与体检结论 | 冲突默认拒绝；同尺寸跳过 |
| FR-37 | scan_stations.py；config 场站辨识 | 辨识结论与依据 | 四条规则逐条打印；多目录不匹配报未识别 |
| FR-38 | scada_source 取数层；raw_scan 族表 | 合并取数结果与扫描结论 | 主件与补充件合并行数与重叠数打印；类目库不计变化 |
| FR-39 | install.bat 与 install.ps1 与 install.sh；便携运行时 | 虚拟环境、配置、安装记录 | 离线安装退出码 0；入口引用闭合 |
| FR-40 | service_ctl.py；win_service.py；service_main.py；service_worker.py | 托管进程与自启项 | 巡检 15 秒；无权限返回 3 并给建议 |
| FR-41 | 安装脚本的版本检查步骤；src/version.py | 安装记录与提示 | 五类提示与动作；check 版本行一致 |
| FR-42 | guanlan_uninstall.py；uninstall 入口两个 | 卸载结果 | 自检两类断言；实跑断言拆除与保留范围 |
| FR-43 | pack_dist.py；pack 入口；开箱验证入口 | 交付包与清单文件 | 两道闸；包内不得有安装记录或快捷方式；页面可用不少于 4 个 |
| FR-44 | src/windscada/config.py 的 REQUIRED 与 _expand() | 场定义装载与报错清单 | 七个必填键逐个在位；缺键即报并打印键名 |
| FR-45 | src/windscada/config.py 的 farm() 与 set_current() 与 available() | 当前场对象与派生路径 | 换场后路径与机组数不串场 |
| FR-46 | src/windscada/config.py 的 station_scan() 与 station_report() | 数据层维护页的辨识结论 | 辨识规则逐条打印；未识别时不猜 |
| FR-47 | _expand()；appETL/configs/contracts/<机型><场>.yaml | 机组清单、列名与单位映射 | 矩阵行数随 n_turbines 变化；两场同代码可跑完 |
| FR-48 | 取数层族入口；app_ETL/configs/farms/<场>/field_semantic_registry.yaml | 合并取数结果与字段对齐 | 合并与重叠行数打印；类目库不计变化 |
| FR-49 | 各族消费者的缺件分支；products_state.py | 缺件标注与降级产物 | 每族缺失有可复核缺件说明；无造数 |
| FR-50 | 场定义与机型契约的参数段 | 本场阈值集合与判据结果 | 两场不同阈值各自可复算；省略项写明不判该轴 |
| FR-51 | src/windscada/lang.py；场级字段语义登记；契约单位写法 | 页面与报告的术语与单位 | 语言包成对；单位随场变；缺映射回落中文 |
| FR-52 | 各场同口径产物 | 跨场对比表与口径说明 | 逐行写口径与样本量；不一致标不可比 |
附录 A 编写依据
表 A-1 编写依据（章节或事实与来源文件） | 章节或事实 | 来源文件（仓库相对路径） | |---|---| | 版本号真源、版本规则、12 条版本史、包名 | src/version.py | | 系统是什么、产物全景、路径约定、进程口径、页面取数 | docs/系统设计说明.md 第 1 至第 6 章 | | 缺口与边界（未随包脚本、缺件、源件缺失） | docs/系统设计说明.md 第 7 章 | | 变更记录（按日期逐条事故与处置） | docs/系统设计说明.md 第 8 章 | | 交付包组成与入口引用闭合 | docs/系统设计说明.md 第 9 章与 §9.1 | | 页面归口规则、五类内容类型、门户逐页识别、全部网页总清点 | docs/系统设计说明.md 第 10 章与第 12 章 | | 配置与日志统一口径、无产物时的可用性 | docs/系统设计说明.md 第 11 章 | | 输入到功能到算法到产物、端到端顺序、反向呼应审计、可逆性 | docs/系统设计说明.md 第 13 章与 §13.6 | | 服务化安装与卸载、安装时版本检查 | docs/系统设计说明.md 第 14 章 | | 版本管理与打包命名、单一真源与三处守卫 | docs/系统设计说明.md 第 15 章 | | 时间窗词表、随窗与不随窗、窄仓、等待契约 | docs/系统设计说明.md 第 16 章 | | 三条描述口径与服务端链接契约、依据不得为空 | docs/系统设计说明.md 第 17 章 | | 面向用户的功能与使用、系统要求、模型档、目录结构、常见故障、已知限制 | docs/说明书_观澜…v0.2.md | | 页面与子页的归口登记（类型、依据、已知缺口） | configs/portal_pages.yaml | | 服务端口与监听地址真源、看门狗开关 | configs/serve.json | | 模型档位与拉取命令 | configs/models.json | | 自检门清单与退出码、服务定义 | guanlan.py | | 重算链步骤、容忍口径、自动取消跳过 | scripts/rebuild_all.py | | 归口审计规则与退出码语义 | scripts/pages_audit.py | | 输入数据放置规则、增量语义、放完跑什么 | docs/输入数据放置指导_v0.1.md | | 落位约定、场站辨识四条规则、各目录功用、能重建与不能重建 | docs/数据目录结构与落位约定_v0.2.md | | 手工重算步骤、运维控制台三条纪律、二次启动原因 | docs/重算操作手册_v0.1.md | | 页面输出体检的判定口径与逐页原因 | docs/页面输出体检_v0.1.md 与 docs/页面输出体检_逐页原因_v0.1.md | | 打包与安装与卸载与版本检查的用户视角说明 | README_先读我.MD | | 自检实跑输出（41 条判定行） | docs/src/_guanlan_check.txt 与本机 2026-09-22 实跑 | | 重算计划实跑输出（23 步） | docs/src/_rebuild_plan.txt | | 四张插图的数字来源 | docs/figures 下的四张需求分析插图与其生成器 scripts/delivery_docs_figures.py | | 场定义必填键、场选择与场站目录辨识 | src/windscada/config.py 的 REQUIRED 与 farm() 与 set_current() 与 station_scan() | | 场定义与机型与物理约束参数的写法样例 | app_ETL/configs/farms/<场>.yaml | | 机型—场站数据契约与字段单位真源 | appETL/configs/contracts/<机型><场>.yaml 与 app_ETL/configs/canonical/dictionary.yaml | | 场级字段语义登记与其它厂商导出形态的对齐 | app_ETL/configs/farms/<场>/field_semantic_registry.yaml | | 按场裁剪的收资清单与必须性分级 | docs/src/数据要求说明_观澜_2.68.0.md | | 场无关引擎与场相关参数的分层与换场作业单 | docs/src/系统设计说明_观澜_2.68.0.md |
表中 <场>、<场站>、<机型> 为占位符，按实际风电场替换。
附录 B 术语表
表 B-1 术语表（按主题分组）
| 术语 | 英文或写法 | 含义 | 出处 |
|---|---|---|---|
| 时间窗 | — | 一个由用户选择或自定义的数据观察区间；月度件按月取整、日粒度件按日精确 | docs/系统设计说明.md §16 |
| 预设时间窗 | — | 词表内置的时间窗：近30日、近90日、2026年、2026H1、2025H2、全程 | docs/系统设计说明.md §16.1 |
| 自定义起止日期时间窗 | — | 写法为起日期~止日期的时间窗，含两端 | docs/系统设计说明.md §16.1 |
| 判级时间窗 | — | 判级矩阵与四轴重算所用的时间窗 | docs/系统设计说明.md §17.1 |
| 证据时间窗 | — | 支撑某条结论的证据所在的时间窗，随判定一并给出 | docs/系统设计说明.md §17.1 |
| 天气窗 | — | 领域词，指气象条件适合的时段，不属于时间窗口径的统一范围 | docs/系统设计说明.md §17.1 |
| 作业窗 | — | 领域词，指检修作业可实施的时段，保持原样 | docs/系统设计说明.md §17.1 |
| 平均无故障间隔（MTBF） | MTBF | 相邻两次故障之间的平均运行时长，按所选时间窗内的停机事件与报警计算 | docs/系统设计说明.md §16.2 与 §17.1 |
| 平均停机间隔（MTBO） | MTBO | 相邻两次停机之间的平均间隔，与可靠性表同源 | docs/系统设计说明.md §17.1 |
| 单次停机时长（MDT） | MDT | 每次停机的平均持续时长 | docs/系统设计说明.md §17.1 |
| 窄仓 | slim10min | 由十分钟数据抽出的公共列子集（不裁剪行），作为按时间窗重算的秒级底座 | docs/系统设计说明.md §16.3 |
| 等待契约 | pending | 按时间窗重算未命中缓存时先回等待或构建中，由页面轮询，绝不静默用旧口径 | docs/系统设计说明.md §16.4 |
| 判级四轴 | — | 变桨、偏航、蓄能、温度四个随所选时间窗重算的判级方向 | docs/系统设计说明.md §16.2 |
| 融合面 | — | 把模型过闸线与振动窗索引裁决合到一起的判级面，输出融合级 | docs/系统设计说明.md §13.1 |
| 链盘 | — | 运行时的决策链进度集合，每台一个对象记六步状态、卡点与下一步 | docs/系统设计说明.md §13.1 |
| 产物 | outputs | 由原始件算出来、页面只读的输出数据，统一落在产物仓 | docs/系统设计说明.md §3 与 §13.4 |
| 逐件来源台账 | — | 记录每件产物属于原始件重算还是随包补齐的台账 | docs/系统设计说明.md §2.1 |
| 反向呼应审计 | — | 从输出回溯到生成端与输入的审计，检查每件产物有没有来路 | docs/系统设计说明.md §13.6 |
| 页面归口 | — | 判定每一页是否随输入数据变、是否算产物，并逐条写明依据 | configs/portal_pages.yaml |
| 陈旧检测 | — | 对数据派生页面比对内嵌指纹与当前产物，不一致即报页面陈旧 | scripts/pages_audit.py |
| 数据派生 | data-derived | 五类页面内容类型之一：把产物烘进页面，属于产物，必须登记来源并做陈旧检测 | configs/portal_pages.yaml 头部 |
| 受管静态 | static | 受管外壳正文，不随输入数据变，也不得引用产物 | configs/portal_pages.yaml 头部 |
| 实时取数 | live | 页面本体不存快照，永远与产物一致 | configs/portal_pages.yaml 头部 |
| 产物引用脚注 | data-citing | 静态正文加产物引用，正文不变但被引产物必须在位 | configs/portal_pages.yaml 头部 |
| 冻结交付件 | frozen-delivery | 带版本号与日期的客户交付件，按交付版本冻结，不随数据自动变 | configs/portal_pages.yaml 头部 |
| 开箱验证 | — | 打包后在临时副本上真解压真安装真起服务的核验路径 | docs/系统设计说明.md §9 |
| 容忍口径 | tolerate | 重算链允许某步返回特定退出码而不打断整条链，且明确「容忍不等于通过」 | scripts/rebuild_all.py |
| 核对锚点 | — | 重算后应达到的条数指标，用于快速判断数据是否真的进去了 | docs/输入数据放置指导_v0.1.md §4 |
| 收资 | — | 向现场收集原始数据与资料的过程与其清单要求 | docs/现场收资接入_v0.1.md |
| 场定义 | farm config | 一个场的最小事实集合：名称、机组数与机组清单、原始件路径、标准仓与额定容量；落 app_ETL/configs/farms/<场>.yaml |
src/windscada/config.py 的 REQUIRED |
| 换场 | — | 从一场切到另一场运行的整套动作：改配置、放数据、重跑、按检查表复验 | 本文 §11.9 |
| 缺族降级 | — | 某族数据缺失时按缺件如实标注并降低该族功能，不造数、不用他场数字顶替 | 本文 FR-49 |
| 按场标定 | — | 把阈值、时间窗锚点、限电窗、温度档带宽等场相关参数按本场取值 | 本文 FR-50 |
| 通用收资模板 | — | 与场无关的收资条目底稿，按场裁剪后作为现场收资清单 | docs/src/数据要求说明_观澜_2.68.0.md |