# 源代码梳理 v0.1（2026-09-28）

> 用户令：**「梳理源代码，及清理无用源代码程序。」**
> 本文是**可核对底稿**：先把"现在有哪些源代码、怎么跑起来、谁被谁引用"讲清，再逐件列出**零引用件**与**建议保留的架构占位**，每一条都带机器可复核的证据（引用计数 / 出处文件）。

## 1 规模总览（`git ls-files` 口径）

| 项 | 数量 |
|---|---|
| 受管文件 | **761 件** |
| Python 文件 | **437 件 / 72,787 行** |
| 其中**兼容转发壳** | **158 件**（src 109 · scripts 47 · 根 `guanlan.py` 1 · app_qualityGate 1） |
| 模块目录 | 7 个（公共 / 数据接入 / 算法 / 本体 / 前端 / 后端 / 质量门） |
| 模块公开面公开名 | **136 名**（7 个 `api.py` 的 `_TARGETS` 合计） |
| 配置 | configs 172 件 · reference 38 件 · resources 30 件 |
| 文档 | docs 35 件（含三份交付文档源与 17 份专题说明） |

## 2 分层结构（每模块一个目录 + 一个公开面）

| 模块 | 件数 | 行数 | 职责 | 允许依赖 | 阶段 |
|---|---|---|---|---|---|
| `app_common/` | 14（含壳 0） | 1,768 | 路径/版本/日志/进程/入口引用/运行态作业/派生台账（公共层，不依赖任何业务模块） | （无） | 已完成 |
| `app_ETL/` | 23（含壳 0） | 5,442 | 源件摄入、放置与增量体检、标准仓、机型与场站契约、canonical 词典 + 12 构建器 | app_common | 已完成 |
| `app_algorithmModel/` | 31（含壳 0） | 3,953 | 七系统判级矩阵、七镜头曲线、可靠性、控制参数一致性、融合面、振动与温度面、趋势与可用率 | app_common, app_ETL | 已完成 |
| `app_ontology/` | 64（含壳 0） | 20,035 | 本体（对象库/码表/摄入六步/检索/决策台/模型闸）与 SOP 知识层（契约闸/判别器/调查/案例/台账） | app_common | 已完成 |
| `app_backEnd/` | 26（含壳 0） | 6,833 | 组件服务、统一网关、运维控制台与重算编排、作业状态、CLI 与进程管理 | app_common, app_ETL, app_algorithmModel, app_ontology, app_frontEnd | 已完成 |
| `app_frontEnd/` | 15（含壳 0） | 2,164 | 工作台单页与资源件、页面装配与经典页模板、设计系统、界面文案与术语、门户装配器 | app_common | 已完成 |
| `app_qualityGate/` | 30（含壳 1） | 7,663 | 审计器、交付文档三检、版本记录、打包器与开箱验证、卸载器 | 全部业务模块 | 已完成 |

**`src/` 的定位（P0–P7 之后）**：140 件里 **109 件是旧路径兼容壳**，31 件是**尚未划归模块**的既有实体（`src/windscada/maint/*`、`src/windcms/*` 剩余件等）。壳的作用只有一个：让 `from src.<旧路径> import …` 与`python -m src.<旧路径>` 这两种写法继续可用；P0–P7 的每一阶段都以"行为逐字节不变"验收，靠的就是它们。

**`scripts/` 的定位**：102 件 = 47 个 CLI 兼容壳 + 48 个独立工具（重算链脚本、词汇表构建、收资与上云工具、仿真页生成器等）+ 7 个服务体/辅助（`win_service.py`、`service_main.py`、`service_worker.py` 等）。

## 3 入口与运行链（十条根入口都在原位）

```
install.bat/.ps1 / install.sh      安装（建 .venv、装依赖、自检、注册服务）
check.bat                          → guanlan.py check（自检门）
start.bat / stop.bat               启动 / 停止（调 scripts/guanlan_start_hidden.py、guanlan.py stop）
pack.bat / pack.sh                 打包 + 开箱验证入口（scripts/pack_dist.py、pack_verify_entry.py）
uninstall.bat / uninstall.sh       卸载（scripts/guanlan_uninstall.py）
guanlan.py                         CLI：check · serve · status · stop · open · qa
  └─ app_backEnd/app_backEnd_guanlan/cli.py
       ├─ 组件：detail(18033) / cms(18020) / viewer(64292) / sim(18791) / sim_sys(18792)
       ├─ 网关：gateway(28084)  → 统一入口（门户 / detail / cms / sim / viewer / ops）
       └─ 模块公开面：app_ETL.api · app_algorithmModel.api · app_ontology.api · app_frontEnd.api
```

## 4 质量门清单（23 个工具，全部走 `scripts/<件>.py` 壳调用，实现在 `app_qualityGate/`）

| 工具 | 查什么 |
|---|---|
| `config_audit.py` | 配置统一：目录约定 / 命名 / 内容 / 引用闭合 / 不手拼路径（rc=8 为配置违规） |
| `pages_audit.py` | 页面归口：每一页该不该随输入数据变、算不算产物 |
| `products_reverse_audit.py` | 产物反向呼应：无生成端的件能否从原件推出来 |
| `chain_gap_check.py` | 重算链缺口：四步脚本与关键产物是否都在位 |
| `check_portability.py` | 可移植：无机器相关绝对路径 / 无 cwd 相对路径 / 不手拼库存字符串 |
| `check_transferable.py` | 换机可跑性大扫描（虚拟环境 / 轮子 / 便携运行时） |
| `module_boundary_audit.py` | 模块边界 R1–R8（结构 / 只经 api / 依赖方向 / 公共层纯净 / 接口在位 / 入口解耦 / 编码 / 壳同面） |
| `detail_deps.py` | /detail 页 → 接口 → 产物 → 来源 台账一致性 |
| `page_fingerprint.py` | 页面/接口指纹（改造前后与换机部署的回归判据） |
| `pages_sweep.py` | 逐页"有没有输出"体检 |
| `inventory_products.py` | 产物清点与输入↔产物呼应 |
| `products_state.py` | 产物状态总览 |
| `products_restore_missing.py` | 补齐无生成端产物（只补缺件） |
| `security_scan.py` | 安全扫描（密钥 / 越界写 / 敏感路径） |
| `log_audit.py` | 日志规范与保留策略 |
| `audit_chinese_terms.py` | 中文表达审核（OEM 术语基准 + 行话规则） |
| `guanlan_baseline_manifest.py` | 工作台视觉基线清单（从源重建 zh 页比对） |
| `delivery_docs_build.py` | 三件交付文档构建 + 自检（去标识化 / 表号引用闭合 / 域 / 页眉） |
| `delivery_docs_figures.py` | 交付文档插图（10 张） |
| `version_log.py` | 版本记录与 `HISTORY` 一致 |
| `pack_dist.py` | 打包（白名单 + 入口引用闭合 + 编码守则 + 无装机产物） |
| `pack_verify_entry.py` | 开箱验证入口（解压 → 安装 → 页面 5/5 → 卸载核验） |
| `guanlan_uninstall.py` | 卸载（停服 / 撤自启 / 删快捷方式 / 清运行态 / 删安装记录） |

`guanlan.py check` 把其中关键几门串成一条自检；**当前全绿**（唯一已知项：远端机器未装 Ollama）。

## 5 无用件取证结果（逐件可复核）

取证口径见 §7。分五类：**A 确证死代码** · **B 零引用一次性生成器** · **C 架构接入点（建议保留）** · **D 兼容壳可收敛** · **E 本地未跟踪残留**。

### A. 确证死代码（零引用 + 功能另有实现）

| 件 | 行数 | 证据 |
|---|---|---|
| `app_ontology/app_ontology_guanlan/sop/cms_availability.py` | 275 | 全仓无调用；L0 数据可用性判据在 `scripts/rudong_model_run.py::l0_layer` **另有实现**（重算链跑的是后者）；只在 `app_ontology/api.py` 的公开面里挂了个名字 |
| `src/sop/cms_availability.py` | 23 | 上面那件的兼容壳；旧路径无人使用 |

### B. 零引用一次性生成器（产物已随包；删了不影响运行，但失去"可重生成"）

| 件 | 行数 | 自述 / 现状 |
|---|---|---|
| `scripts/guanlan_cloud_page.py` | 178 | 云端版·方案 A 中文单文件（脱敏面孔）生成器 |
| `scripts/guanlan_cloud_qa.py` | 324 | 云端 `/api/qa` 代理**草案（未部署）** |
| `scripts/sim_hub/apply_theme.py` | 79 | 给仿真页注入统一外壳（顶栏 + 配色 token） |
| `scripts/sim_hub/build_collapse_3d.py` | 160 | 生成「运行形态塌陷·动态三维」页 |
| `scripts/sim_hub/build_viv_page.py` | 173 | 生成「涡激振荡仿真台」单页（自述数据源写死 macOS 路径） |
| `scripts/sim_hub/pain_pitch_imbalance.py` | 89 | 变桨/叶轮不平衡机理页数据生成 |
| `scripts/sim_hub/pain_viv.py` | 82 | VIV 原理演示页数据生成 |
| `scripts/sim_hub/pain_yawslip.py` | 115 | 偏航滑移实测页数据生成 |

> 注：`sim_hub/pain_*.py` 的产物（`assets/pain_*.png`）**被 `build_hub.py` 以 PNG 资产引用**，`build_hub.py` / `mk_share.py` / `wake*.py` 本身仍被 `scripts/sim_hub/README.md` 记录为内容源 —— 所以"生成器一删，这三张图就只能手改，不能再重生成"。

### C. 架构接入点（零引用但**建议保留**）

| 件 | 行数 | 说明 |
|---|---|---|
| `app_ETL/app_ETL_guanlan/objectstore.py` | 26 | **MinIO** 接入点契约（源件与产物对象存储） |
| `app_backEnd/app_backEnd_guanlan/cache.py` | 30 | **Redis** 接入点契约（按时间窗缓存与作业状态） |

它们与已被引用的另两件同批（`app_ETL/.../store.py` = TiDB、`app_backEnd/.../gateway_contract.py` = Nginx），是"四组件可插拔"的接口面；删掉它们等于删掉后续接入的落点。

### D. 兼容壳可收敛（旧路径已无人使用的 33 件）

壳总 158 件；其中 **33 件的旧路径在所有受管文件里都没有任何引用**（含文档与配置），即"不会再有人从旧路径进来"：

```
src/logfile.py
src/opsjob.py
src/tabfmt.py
src/ontology/acceptance_fsm.py
src/ontology/codes.py
src/ontology/decisions.py
src/ontology/llm_gate.py
src/ontology/schema.py
src/sop/cms_availability.py
src/sop/contract_gate.py
src/sop/derive10min.py
src/sop/farm_pipeline.py
src/sop/fatigue_validation.py
src/sop/fleet_query.py
src/sop/fusion_diag.py
src/sop/goem.py
src/sop/hydraulic_validation.py
src/sop/icing_validation.py
src/sop/pitch_validation.py
src/sop/reactive_validation.py
src/sop/scenarios.py
src/sop/sensor_validation.py
src/sop/survey.py
src/sop/thermreg_validation.py
src/sop/vib_confidence.py
src/sop/wind_coupling.py
src/sop/xlsx_read.py
src/sop/yaw_validation.py
src/windcms/agent.py
src/windscada/lang.py
src/windscada/scada_source.py
src/windscada/slim.py
src/windscada/ui/snapshot.py
```

**建议**：这一级是"兼容性 vs 清爽"的取舍 —— 删了旧路径就断（但模块路径/api 全通、门禁全绿）。若确定后续只按模块路径开发，可整批删除，并在 `docs/重构方案_模块化_v0.1.md` 记"P8 壳收敛"。

### E. 本地未跟踪残留（不进版本库，但占空间/易误入包）

- `scripts/sim_hub/frames/*.png`：**37 张**，已被 `.gitignore` 忽略（构建中间件，可重生成）。
- 各目录 `__pycache__/`（含 `scripts/sim_hub/__pycache__/` 11 个 .pyc）。
- 历史交付 zip（`F:\temp\app_guanlang_v2*.zip`、`app_guanlang_v2.9.2.zip`）不在仓库内，另行处置。

## 6 清理建议与执行顺序

| 批次 | 内容 | 影响面 | 需要的前置 |
|---|---|---|---|
| ① | A 类：删 `cms_availability` 实现 + 壳，并从 `app_ontology/api.py` 摘掉 `sop_cms_availability` | 无（无调用） | 全门禁 + 三份文档重出 |
| ② | B 类：删 8 件零引用一次性生成器（1,200 行） | 失去"重生成"能力；运行与页面不受影响 | 需确认云上/仿真的产物是否还要重建 |
| ③ | D 类：整批删 33 个无人使用的旧路径壳 | 旧路径写法失效（模块路径与 api 全通） | 需确认后续开发不再走旧路径 |
| ④ | E 类：清本地 `frames/`、`__pycache__/` | 本地磁盘 | 无 |

**C 类（MinIO / Redis 接入点）建议一律保留**：它们是架构接口，不是"没用的代码"。

## 7 取证口径（可复跑，不靠印象）

1. **受管件**＝`git ls-files`（761 件）；**文本受管件**＝后缀在 `.py/.md/.yaml/.yml/.json/.bat/.sh/.ps1/.txt/.html/.js` 且 < 3 MB。
2. **引用**＝在**除自身外**的全部文本受管件里出现下列任一形态：
   - 实路径 `a/b/c.py`；· 点号名 `a.b.c`；· 点号斜杠 `a.b.c/leaf.py`（P1–P7 壳的 docstring 写法）；
   - 导入语句 `from a.b import c`、`import a.b.c`、裸名 `from x import …` / `import x`（`scripts/` 下工具常被这样用）；
   - **包内相对导入**按本文件所在包解析：`from . import x`、`from .x import y`、`from ..pkg import z`。
3. **api 公开面**＝各 `api.py` 的 `_TARGETS`（`AnnAssign`/`Assign` 都算）值，也是引用。
4. **分类**：零引用（无代码/文档/壳/api 提及）＝候选；只被**自己的壳**提及且壳路径无人当命令行用＝等价零引用；只被文档提及＝"文档工具"（保留，删文档前不动）。
5. 复跑脚本：`F:\temp\_h9\p8_scan5.py`（引用计数）、`F:\temp\_h9\p8_extra2.py`（可疑件引用面 + 壳体检）、`F:\temp\_h9\p8_stats.py`（本文表格取数）。

## 8 清理执行记录（2026-09-28，用户批 ①+④ 两批）

| 批次 | 处置 | 具体 |
|---|---|---|
| ① A 类 | **已删** | `app_ontology/app_ontology_guanlan/sop/cms_availability.py`（275 行）与壳 `src/sop/cms_availability.py`（23 行）；并从 `app_ontology/api.py` 摘掉公开名 `sop_cms_availability` |
| ④ E 类 | **已清** | `scripts/sim_hub/frames/`（37 张 PNG，8.7 MB，本已 .gitignore）+ 全仓 46 个 `__pycache__/` 与散落 `.pyc`，合计释放 **约 15.4 MB**（`.venv/` 未动） |
| ② B 类 | **保留（待定）** | 8 件零引用一次性生成器仍在原位；若要删，需先确认云端页与仿真页产物**不再需要重生成** |
| ③ D 类 | **保留** | 33 个"旧路径已无人使用"的兼容壳仍在原位（保留旧路径写法可用） |
| C 类 | **保留** | `objectstore.py`（MinIO）、`cache.py`（Redis）接入点契约不动 |

清理后的复检：全门禁 rc=0（含模块边界 R1–R8、配置统一、页面归口）+ `guanlan.py check` 全绿 + 起服务逐页探活 + 打包开箱验证 5/5 + 卸载核验通过。

## 9 P9 结构变更后的实况（2026-09-28）

* 实现包上提到模块根：`app_<模块>/app_<模块>_guanlan/`；旧前缀 `app_<模块>.common.app_<模块>_guanlan.*`
  由前缀重定向别名保留**一个版本**（同名同体）。
* 每模块新增 `common/`（模块内通用组件）、`configs/`（模块专属配置域）、`data/`（模块数据件预留）、
  `README.MD`（含安装部署与运行）、`install/uninstall/run`（bat+sh，内部调安装根统一入口）。
* 配置双根：安装根 `configs/` = 跨模块共用单件（5 件）；`app_ETL/configs/` = canonical·contracts·farms（164 件）；
  `app_frontEnd/configs/` = terms（3 件）。取用口多根查找 + 单源校验。
* 清理实况：A 类死代码（`cms_availability` 275 行 + 壳）**已删**；E 类本地残留（`frames/` 37 张 + 46 个
  `__pycache__`，约 15.4 MB）**已清**；B 类（8 件零引用一次性生成器）与 D 类（旧路径壳）经用户裁示**保留**。