文档: README_先读我.txt 补运维控制台与相关操作(并改正指向不存在的文件) + 说明书同步

用户令: 把新增的 /ops 页面及相关操作, 基于 README_先读我.txt 现有内容并完善。

## README_先读我.txt (748 B → 5.3 KB, 保持原风格: 编号步骤 + 纯文本 + LF 无 BOM)

保留原有五步与"包内含", 并补/改:

- **改正一处错指向**: 原文写 `docs\说明书_观澜如东样板v2_Windows_v0.1.md`, 该文件**根本不存在**
  (真名 `docs\说明书_观澜如东样板v2_v0.2.md`; 也没有 `dist\` 目录)。已改为实际存在的四个文档清单。
- **新增第 5 条: 运维控制台** `http://127.0.0.1:28084/ops` —— 六个按钮逐个写明"什么时候可用/点了做什么",
  以及三条纪律: 按钮按真实状态启用(后端同样拒绝并返回 409) · 停组件服务保留控制台(否则点完页面就没了) ·
  同一时刻只允许一个动作(有任务在跑时五个按钮全灰, 但能看到进度/退出码/日志尾巴)。
- **新增第三、四节: 换数据后重算** —— 放数据(place_raw_data --scope full) 与一条命令重算
  (`rebuild_all.py` / `--skip-scada` / `--dry-run` / `--with-verify` / `--src`), 并给出**验收锚点**
  (报警 39211 · 工单 5876 · 油样 404 · temp_monthly 19494 · 本体 9702 对象 / 审计 0 问题)。
- **新增第四节: "随包补齐"是什么意思** —— `outputs\rudong\_provenance.json` 逐件来源台账
  (raw-derived 20 件 / shipped 568 件); 清产物≠清数据(只挪产物, 不动 data\raw\、release\、logs\)。
- **新增第五节: 某页没数据怎么办** —— 先看控制台的最近动作退出码与 logs\, 再看缺口清单。
- 第 4 条补上事实: `start.bat` **会自动打开**门户; `stop.bat` 连网关一起停(停完控制台也打不开)。

## docs\说明书_观澜如东样板v2_v0.2.md (同步两处, 否则用户手册与控制台脱节)

- §4.1 增一行: 运维控制台怎么用(按钮规则/自动打开门户/停服务保留控制台/清产物可恢复/页面展示什么)。
- §8 **改正一句过时的话**: 原文"本版 (v0.1) 包内**不含**从原始 SCADA 重生成产物的链 (计划 P0 补入)"
  —— 这条链 2026-09-12 已经进包并实测跑通, 现改为: 一条命令 `rebuild_all.py`(约 15 分钟 / `--skip-scada` 约 2 分钟)、
  通道与顺序、**两条如实边界**(① 一批产物没有生成端, 重算后由随包件补齐并记进 _provenance.json;
  ② 仍有缺件看缺口清单), 并保留原有"更新包"交付路径的说明。

## start.bat

启动成功后额外打印控制台地址与三条要点(原来只打开门户, 用户不会知道有 /ops)。行尾保持 CRLF。

自检: README 里**每一个引用路径都存在**(写了个校验脚本逐个核, 全在);
行尾约定逐字节核对无变化(.bat = CRLF, .md/.txt = LF); 页面上线状态未受影响(6/7 模块 ok)。

README_先读我.txt

@@ -1,9 +1,56 @@
 观澜·如东样板 v2 0.2.0 (Windows 纯离线应用) — 单包全量
 
+一、首次安装
 1. 把本压缩包解压到 D:\guanlan\app (目录不要带空格和中文)
 2. 装 Python 3.12 (勾 Add to PATH), 在该目录运行: powershell -ExecutionPolicy Bypass -File install.ps1
 3. 装 Ollama Windows 版, 拉模型: ollama pull qwen3:8b / deepseek-r1:14b / bge-m3 (显存≥24G 再 qwen3.8:27b)
-4. 双击 check.bat 全绿 → start.bat → 浏览器 http://127.0.0.1:28084/
-5. 详细说明: docs\说明书_观澜如东样板v2_Windows_v0.1.md (同名副本在 dist\)
+   (本机模型只影响问答/本地审核页; 没装也不影响其它页面, 只会在自检里显示一项未就绪)
 
-包内含: 程序与配置 / 如东分析产物 / 门户与仿真 / 三维资产 (release\viewer) / 治理清单交付件 (release\如东, 客户交付物请勿外传) / Windows 离线依赖轮子
+二、日常使用
+4. 双击 check.bat 全绿 → 双击 start.bat → 会自动打开 http://127.0.0.1:28084/
+   停服务: 双击 stop.bat (它连网关一起停, 停完控制台页面也打不开, 要再起就用 start.bat)
+5. 运维控制台: http://127.0.0.1:28084/ops —— 一个按钮一件事: 停/启服务 · 执行重算 · 清除产物
+   · 按钮按真实状态启用: 不能做的动作按钮是灰的; 后端也会拒绝(直接打 API 一样返回 409)
+   · 启动服务(并打开门户)   有组件服务未运行时可用; 起来后自动打开 http://127.0.0.1:28084/
+   · 停止组件服务(保留控制台) 有组件在运行时可用; 只停 detail/cms/sim/sim_sys/viewer, 保留网关
+                            (保留的理由: 本页面就是网关提供的, 否则点完按钮页面就没了)
+   · 完整重启(含网关)       有组件在运行时可用; 页面会断开约 15 秒, 之后自己恢复
+   · 执行重算               没有任务在跑时可用; 等价于下面第 7 条的命令行, 可勾选含 SCADA / 末尾加等价验收
+   · 清除产物(可恢复)       产物在位时可用; 是"挪到 _products_off"不是删除, 随时能恢复
+   · 恢复产物               产物被清空过时可用 (恢复后请点"启动服务", 页面才有数)
+   · 同一时刻只允许一个动作: 有任务在跑时五个按钮全灰, 会话里能看到执行到哪一步、退出码与日志尾巴
+   · 页面同时显示: 各服务端口通不通 · 产物件数与分仓 · 来源台账 · 验收锚点 · 最近一次动作的状态
+
+三、换数据后重算 (命令行; 控制台里点"执行重算"等价)
+6. 放数据 (现场包 → 约定目录; 同尺寸文件自动跳过, 可反复跑):
+   .venv\Scripts\python.exe scripts\place_raw_data.py --src <现场包目录> --scope full
+7. 重算全部 (台账 → 月度派生件 → 补齐 → 本体 → 审计, 自动重启组件服务):
+   .venv\Scripts\python.exe scripts\rebuild_all.py              含 SCADA 侧 10 个构建器, 逐台读 ~14 GB, 约 15 分钟
+   .venv\Scripts\python.exe scripts\rebuild_all.py --skip-scada 只换了台账类数据时的常用档
+   可加 --src <现场包目录> 连"放数据"一起做; --dry-run 只看计划不执行; --with-verify 末尾加台账等价验收
+8. 怎么算"算成功了":
+   浏览器 http://127.0.0.1:28084/detail/ → 左栏「系统维护」两屏 (数据层/机理层, 每行给出条数/覆盖/末次更新)
+   命令行   .venv\Scripts\python.exe -m src.ontology.maintenance
+   本包锚点: 报警 39211 行 · 工单 5876 · 油样 404 · temp_monthly 19494 行 · 本体 9702 对象 (审计 0 问题)
+
+四、产物是什么、"随包补齐"是什么意思
+9. 页面上的数来自 outputs\rudong\ 里的产物; 产物由 data\raw\ 下的原始件算出来; data\raw\ 的下一级目录名
+   就是场站名称(扫描辨识, 不写死)。清产物≠清数据: 清的是产物, 不动 data\raw\、release\、logs\。
+10. outputs\rudong\_provenance.json 逐件记着来源:
+      raw-derived = 由 data\raw 重算出来的 (能证明的才这么标, 如 temp_monthly 与随包件逐值 19494/19494 一致)
+      shipped     = 包内没有生成端(或口径未复现), 用随包件补齐的
+    本包现状: raw 重算 20 件 + 随包补齐 568 件。想知道"这一页的数是自己算的还是随包带的", 查这份台账即可。
+
+五、某页没数据 / 报错怎么办
+11. 先看 运维控制台「最近一次动作」的退出码与日志尾巴, 以及 logs\ 下对应服务的日志。
+12. 再看 docs\重算缺口与补件清单_v0.1.md: 哪件产物缺、卡住哪个页面、找谁补、拿到后按什么判据验收。
+    (/cms/ 503、工作台"无产物"、油样 404 行这类都有逐条说明, 多数是"源件或生成端不在包内")
+
+包内含: 程序与配置 / 如东分析产物(+ outputs\rudong\_provenance.json 来源台账) / 门户与仿真 / 三维资产 (release\viewer) / 治理清单交付件 (release\如东, 客户交付物请勿外传) / Windows 离线依赖轮子 / 运维控制台 (http://127.0.0.1:28084/ops)
+
+详细说明 (本机 docs\ 下, 按需要看):
+  docs\说明书_观澜如东样板v2_v0.2.md      安装/日常使用/配置/常见故障 (用户向)
+  docs\重算操作手册_v0.1.md               手动与一条命令重算 · 清产物/恢复 · 运维控制台 (§0/§0b/§5b)
+  docs\数据目录结构与落位约定_v0.2.md      data\raw 落位约定 · 能重算什么/不能重算什么 (§4)
+  docs\重算缺口与补件清单_v0.1.md          缺件台账: 现象 · 原因 · 找谁 · 补齐判据
+  _修复记录_20260911\README.md            现场修复记录 (启动报错/路径跨平台化/数据链/本体审计等)

docs/说明书_观澜如东样板v2_v0.2.md

@@ -74,6 +74,11 @@ ollama serve &
 - 门户每页首屏一句话; "经验发现" 与 "案例" 页的每条结论旁有三枚标签: **证据级** (定论 / 准定论·预警 / 候选 / 参考 / 数据不足 / 撤回)、**审级**、**处置措施** (谁、什么时候、做什么)。候选不进业主正文。
 - 工作台 `/detail/`: 系统矩阵 (38 台 × 九系统判级) → 点台号看证据窗; 检修助手 (检修四链); **问答区**: 选模型 (默认 8B; 复杂问题会自动升档到 27B 并在尾注标明), 回答后自动附"结构化事实契约"引文块; 引不到契约条时会明写"未被契约背书"。汇报纸可导出。
 - `/cms/`: 每台机组六层判读, 机制未定不点零件。
+- **运维控制台 `/ops`** (2026-09-12 新增): 停/启服务 · 执行重算 · 清除产物 —— 一个按钮一件事。
+  按钮按**真实状态**启用 (不能做的动作是灰的; 后端同样校验并返回 409, 直接打 API 也绕不过);
+  "启动服务"起来后会自动打开门户; "停止组件服务"**保留控制台本身**(否则点完页面就没了);
+  "清除产物"是把产物挪到 `_products_off\` (可恢复), 不动 `data\raw\`。页面同时显示各服务端口状态、
+  产物件数、逐件来源台账、验收锚点, 以及当前任务的进度/退出码/日志尾巴。
 
 ### 4.2 问答的可信边界
 - 台号与数字必须能回抓到源记录, 回抓不到的句子被校闸拦下并提示; 两档模型都拦则**不出文并给原因** (不会硬编)。
@@ -115,7 +120,18 @@ D:\guanlan\app\
 - **编码**: 启动器与批处理已设 `PYTHONUTF8=1`; 若终端显示乱码, 先 `chcp 65001`。
 
 ## 8. 每期数据分析与升级
-- 本版 (v0.1) 包内**不含**从原始 SCADA 重生成产物的链 (计划 P0 补入)。如东新一期数据的分析由维护方 (Claude + 工程师) 在分析机上执行, 以**更新包**交付: 包含新的 `outputs\rudong\` 与 `release\` 及变化摘要、审级件、人裁记录。
+- ~~本版 (v0.1) 包内**不含**从原始 SCADA 重生成产物的链~~ → **2026-09-12 更新: 重算链已进包**。
+  一条命令: `.venv\Scripts\python.exe scripts\rebuild_all.py` (含 SCADA 侧 10 个构建器, 逐台读 ~14 GB, 约 15 分钟;
+  只换了台账类数据时加 `--skip-scada`, 约 2 分钟); 等价操作: 运维控制台 `/ops` → "执行重算"。
+  链路: 放数据 → 三门台账 → 月度派生件 → 补齐缺件 → 本体(码表/铺开/决策链/趋势/检索/参数表) → 本体审计,
+  并自动重启组件服务 (网关保留, 所以控制台页面不会断)。
+  两条**必须如实知道的边界**: ① 随包里有一批产物**没有生成端** (如 `pitch_daily`、`pc_monthly_bins`、
+  CMS/TCM 兼容链), 重算后再由随包件补齐 —— 每件的来源逐条记在 `outputs\rudong\_provenance.json`
+  (`raw-derived` = 由 `data\raw` 重算 / `shipped` = 用随包件补齐); ② 补齐后某页仍无数据,
+  看 `docs\重算缺口与补件清单_v0.1.md` (哪件缺 · 卡住哪个页面 · 找谁补 · 补齐判据)。
+- 新一期数据的分析仍可由维护方 (Claude + 工程师) 在分析机上执行, 以**更新包**交付: 包含新的
+  `outputs\rudong\` 与 `release\` 及变化摘要、审级件、人裁记录。有了重算链, 现场换数据也可自行重算,
+  步骤与验收见 `docs\重算操作手册_v0.1.md` (§0 一条命令 · §0b 控制台 · §5b 清产物/恢复)。
 - **应用更新包**: `stop.bat` → 把当前 `outputs\` 与 `release\` 整目录复制到 `D:\guanlan\backup\<日期>\` → 解压更新包覆盖 → `check.bat` → `start.bat` → 打开 `/api/version` 核对指纹与更新说明一致。
 - **程序升级**: 同上, 先备份再覆盖程序文件; 数据不动; 升级后必跑 `check.bat` 与 `guanlan.py qa`。回滚 = 用备份目录覆盖回去。
 - 每期出门前的审级 (离线): 本地两票初筛 + 工程师审; 确诊与含经济数字的结论额外要求数据回抓、两票一致、签字。

start.bat

@@ -30,3 +30,8 @@ if errorlevel 1 (
   echo     Details: logs\ for the degraded module.
 )
 start "" http://127.0.0.1:28084/
+echo.
+echo [i] Ops console - stop/start services, rebuild, clear products:
+echo     http://127.0.0.1:28084/ops
+echo     It stays available while component services are stopped (only the gateway must be up);
+echo     buttons follow real state and the backend refuses impossible actions (HTTP 409).