源代码梳理_v0.1.md 14 KB
源代码梳理 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/common/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/common/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/common/app_ETL_guanlan/objectstore.py |
26 | MinIO 接入点契约（源件与产物对象存储） |
app_backEnd/common/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 取证口径（可复跑，不靠印象）
- 受管件＝
git ls-files（761 件）；文本受管件＝后缀在.py/.md/.yaml/.yml/.json/.bat/.sh/.ps1/.txt/.html/.js且 < 3 MB。 - 引用＝在除自身外的全部文本受管件里出现下列任一形态：
- 实路径
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。
- 实路径
- api 公开面＝各
api.py的_TARGETS（AnnAssign/Assign都算）值，也是引用。 - 分类：零引用（无代码/文档/壳/api 提及）＝候选；只被自己的壳提及且壳路径无人当命令行用＝等价零引用；只被文档提及＝"文档工具"（保留，删文档前不动）。
- 复跑脚本：
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/common/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 + 卸载核验通过。