Strona główna Odkrywaj Pomoc
Zarejestruj się Zaloguj się
zhouyang.xie
/
guanlan-src
1
0
Forkuj 0
Pliki Problemy 0 Oczekujące zmiany 0 Wiki
Drzewo: 6076957aba
Gałęzie Tagi
guanlan-src
/
docs
/
重构方案_模块化_v0.1.md

重构方案_模块化_v0.1.md 9.5 KB
Historia Czysty

观澜 · 源代码模块化重构方案 v0.1（2026-09-22）

本文用途：给开发团队做源代码组织层面的重构依据。本次只重构目录与接口（用户令 2026-09-22）： 暂不引入 TiDB / MinIO / Redis / Nginx，只在存储、缓存、网关三处留好接入点。 兼容底线：零行为变化、逐版本可回滚 —— 页面、CLI、产物、审计门、交付包的产出一律不变， 每阶段独立提交、跑通全部门禁才推进，出问题按提交回退。

1 为什么这样分（按"变化的原因"切，而不是按技术层切）

观澜现在有两处"变化速率完全不同"的东西混在一起：

  • 业务逻辑（判级口径、曲线镜头、可靠性指标、融合判据）—— 变化快，且跨风电场/机型必须能替换与扩展；
  • 运行与交付（服务、网关、重算编排、审计门、打包安装）—— 变化慢，但一堆硬约束（离线单包、无外网、可移植、版本纪律）。

把它们分层，才能做到"改算法不动服务、换存储不动算法"。所以按六个业务模块 + 一个公共层切：

模块目录 中文职责 变化原因 关键约束
app_common/ 公共层：路径真源、版本真源、日志、进程、入口引用、控制台输出 极少变 只被依赖，不依赖任何业务模块
app_dataAccess/ 数据接入管理：摄入、体检与落位、标准仓、契约与词典 随现场数据形态变 源件只读；缺族如实标注；列名绑定
app_algorithm/ 算法：判级矩阵、七镜头曲线、可靠性、融合面、振动与温度面、趋势 最快 纯函数优先；输入是标准仓，输出是判定；不得直接读原始件
app_ontology/ 本体与知识层：对象库、机制链、检索、SOP 与验收状态机、模型闸 中 只读复用；不写业务产物
app_backEnd/ 后端：组件服务、网关、运维控制台、重算编排、CLI 慢 端口/入口/日志口径统一；不缓存产物口径
app_frontEnd/ 前端：页面与交互、图表、静态件与门户 中 只读接口；不内嵌业务判据
app_qualityGate/ 质量门与审计 + 打包安装：审计器、门禁、打包器、安装/卸载 慢 门禁必须能独立重跑、逐条给退出码

依赖方向（单向，无环）： app_frontEnd → app_backEnd → {app_algorithm, app_ontology, app_dataAccess} → app_common； app_qualityGate 只读依赖全部模块（审计者不参与业务调用链）。

2 目录结构（每个模块一个目录）

用户令给的前端示例照此推广——模块根下 common/ 放跨模块可复用的公共组件，app_<模块>_guanlan/ 放观澜在该模块的实现：

app_common/
  |__common/
       |__app_common_guanlan/          [观澜公共层：paths/version/logfile/proc/entry_refs/console/opsjob/derived_manifest/tabfmt]
            |____init__.py
            |__api.py                  ← 对外公开面（其他模块只许从这里 import）
  |__README.md
app_dataAccess/
  |__common/
       |__app_dataAccess_guanlan/      [数据接入管理]
app_algorithm/
  |__common/
       |__app_algorithm_guanlan/       [算法]
app_ontology/
  |__common/
       |__app_ontology_guanlan/        [本体与知识层]
app_backEnd/
  |__common/
       |__app_backEnd_guanlan/         [后端]
app_frontEnd/
  |__common/
       |__app_frontEnd_guanlan/        [前端]
app_qualityGate/
  |__common/
       |__app_qualityGate_guanlan/     [质量门与审计 + 打包安装]

边界规则（机器可查，见 scripts/module_boundary_audit.py）：

  1. 跨模块调用只许经由对方的 api.py；模块内部实现不得被别的模块直接 import。
  2. 依赖方向不得反向、不得成环（按 configs/modules.yaml 的 allow 判定）。
  3. 每个模块必须有 README.md（职责/公开面/依赖/迁移进度）与 api.py。
  4. 公共层 app_common 不得依赖任何业务模块（否则公共层变成"上帝模块"）。

3 现有代码 → 目标模块（映射表）

阶段 0（本轮）只建骨架与接口，下面的文件原地不动；各模块 api.py 现在转发到既有实现， 保证"接口先立、行为不变"。后续阶段逐个 git mv 到目标目录，并在旧路径留转发壳。

目标模块 迁移来源（现有路径） 现有规模
app_common src/{paths,version,logfile,proc,entry_refs,console,opsjob,derived_manifest,tabfmt}.py、configs/registry.yaml（配置登记） 9 文件 / 1,683 行
app_dataAccess src/windscada/{data,scada_source,slim,mdb_names}.py、scripts/{rebuild_from_raw,rebuild_all,scada_slim_build,windscada_monthly_build,vib_raw_build,raw_scan,raw_data_check,place_raw_data,pitch_face_build,baseline_38_build,component_history_build,csv_to_mdb}.py、configs/{canonical,contracts,farms} 约 30 文件
app_algorithm src/windscada/{taxonomy,audit}.py、src/windscada/perf/*、src/windscada/subsys/*、src/windcms/{report_std,tcm,knowledge,cross_review,audit_rules,pipeline}.py 约 40 文件 / 2 万行
app_ontology src/ontology/*、src/sop/* 60 文件 / 19,775 行
app_backEnd guanlan.py、scripts/{windscada_serve,guanlan_gateway,guanlan_ops,_ops_launch,_ops_run,_ops_stop_keep_gateway,service_ctl,guanlan_start_hidden}.py、src/windscada/{config,terms,i18n,lang,report_export}.py、src/windcms/{serve,orchestrator,llm,agent}.py 约 20 文件
app_frontEnd src/windscada/ui/{app.js,charts.js,build.py,snapshot.py}、windscada_serve.py 内的页面模板（PAGE_*）、release/portal.html、release/viewer/ 2 JS / 1,360 行 + 模板
app_qualityGate scripts/{*_audit,check_*,detail_deps,page_fingerprint,pack_dist,pack_verify_entry,guanlan_uninstall,delivery_docs_build,delivery_docs_figures}.py、install.ps1、install.sh、uninstall.*、check.bat 约 25 文件

4 分阶段迁移（每阶段一个提交，随时可回退）

阶段 内容 验收（全绿才进下一阶段） 回滚
P0（本轮） 建 7 个模块目录 + common/<pkg>/{__init__,api}.py + README；configs/modules.yaml 登记；新增 scripts/module_boundary_audit.py 并接入 guanlan.py check 边界审计 rc=0；guanlan.py check 全绿；三份交付文档重渲通过 删目录即可
P1 app_common 平台件实体迁移，src/<同名>.py 变转发壳 全部门禁 + 页面抽样对拍 revert 该提交
P2 app_dataAccess 迁移（构建器按 CLI 入口迁，scripts/ 留转发） 重算链 --dry-run 计划不变 + 全门禁 同上
P3 app_algorithm 迁移（判级/曲线/可靠性/融合纯函数化） 判级与曲线逐值对拍（同一时间窗结果一致）+ 全门禁 同上
P4 app_backEnd 迁移（服务、网关、编排、CLI） 端口/入口/日志口径不变 + 页面 5/5 同上
P5 app_frontEnd 迁移（JS/图表/模板/门户） 页面渲染逐页对拍 + 门禁 同上
P6 app_ontology 迁移 对象库与检索行为不变 + 门禁 同上
P7 app_qualityGate 迁移（审计器、打包、安装） 审计全绿 + 打包开箱验证 5/5 + 卸载核验 同上

旧路径转发壳约定（保证兼容性）：迁移后旧路径保留一个薄文件，例如 src/paths.py → from app_common.common.app_common_guanlan.paths import * # 兼容转发，勿新增逻辑。 这样 scripts/**、审计器、文档里的既有引用不需要一次性改完，可以按阶段收敛。

5 为四个系统组件留的接入点（本轮只留接口，不接实现）

组件 接入点（本轮建立的边界） 后续替换方式
TiDB community app_dataAccess 的"标准仓读写"接口（现为 parquet 仓）：表↔仓的映射与事务边界在接口层确定 新增 TiDB 实现，配置切换；算法层不变
MinIO app_dataAccess 的"源件与产物对象存储"接口（现为本地目录）：以对象键替代绝对路径 新增 MinIO 实现；app_common 的路径真源继续提供逻辑键
Redis app_backEnd 的"按时间窗缓存与任务状态"接口（现为进程内 _WIN_CACHE 与 run/ops_job.json） 新增 Redis 实现，支持多实例共享与分布式锁
Nginx app_backEnd 的"统一入口/静态件"接口（现为 Python 网关 guanlan_gateway.py） Nginx 反代 + 静态托管，网关退化为路由表

约束：上表四项都是"可插拔实现"，默认实现仍是本地/进程内，因此离线单包交付形态与现有验收链不变。

6 与既有纪律的关系（不得破的底线）

  • 版本纪律：本重构按中版本升位（源码组织层重构，运行形态与核心功能未变），src/version.py 单点真源；
  • 审计纪绿：guanlan.py check、反向呼应、页面归口、配置统一、链缺口、可移植性、文档三检必须保持全绿；
  • 交付纪律：交付包默认不含输入数据/产物/日志；install.ps1/uninstall.* 行为不变；
  • 文档纪律：三份交付文档（需求分析 / 系统设计说明 / 数据要求说明）随版本号改名并重渲，内容口径不变。

7 当前进度（2026-09-22）

  • P0 已完成：7 个模块目录、接口与 README、configs/modules.yaml、scripts/module_boundary_audit.py（接入 guanlan.py check）。
  • P1–P7 未开始；本轮未移动任何业务代码，行为与产物零变化。