2.13.0 P9 源码目录结构变更: 实现包上提模块根(app_X/app_X_guanlan)+旧前缀别名(同名同体)+每模块 common/configs/data/README.MD/install-run-uninstall 包装+配置双根(app_ETL/app_frontEnd configs 下放, 取用口多根+单源+owner); 修文档构建器死循环(落单反引号)并支持代码栅栏

app_ETL/README.md

@@ -8,6 +8,32 @@
 
 **当前实现落点（P2 已实体迁入）**：src/windscada/{data,scada_source,slim,mdb_names}.py + scripts/{rebuild_*,scada_*,raw_scan,raw_data_check,place_raw_data,pitch_face_build,baseline_38_build,component_history_build,csv_to_mdb}.py
 
-**迁移状态**：**P2 已完成（2026-09-22）** —— 4 个库模块（data/scada_source/slim/mdb_names）实体迁入本目录（旧路径 `src/windscada/<件>.py` 留模块别名壳）；12 个构建器迁入 `builders/`（`scripts/<同名>.py` 留 CLI 壳，链/审计/文档里约 269 处路径引用因此保持不变）；构建器的安装根推算改用公共层公开面 `app_common.common.app_common_guanlan.api.install_root`（不再依赖 `__file__.parents[1]`）。实逮并修掉：包内相对导入（`from .config` 等 6 处）在搬家后指向不存在的模块 ⇒ 改为绝对导入。
+**迁移状态**：**P2 已完成（2026-09-22）** —— 4 个库模块（data/scada_source/slim/mdb_names）实体迁入本目录（旧路径 `src/windscada/<件>.py` 留模块别名壳）；12 个构建器迁入 `builders/`（`scripts/<同名>.py` 留 CLI 壳，链/审计/文档里约 269 处路径引用因此保持不变）；构建器的安装根推算改用公共层公开面 `app_common.app_common_guanlan.api.install_root`（不再依赖 `__file__.parents[1]`）。实逮并修掉：包内相对导入（`from .config` 等 6 处）在搬家后指向不存在的模块 ⇒ 改为绝对导入。
 
 > 依据：`docs/重构方案_模块化_v0.1.md`（用户令 2026-09-22：只重构目录与接口、零行为变化、逐版本可回滚）。
+
+## 安装部署与运行
+
+本系统是**单包离线交付**：解压到无空格无中文路径 → 安装 → 自检 → 启动（一套安装，七个模块共用一份 `.venv`）。
+本模块目录里的脚本只是**入口包装**，内部调安装根的统一入口，保证"进模块目录也能装/跑/卸"：
+
+| 动作 | Windows | Linux/macOS | 内部实际调用 |
+|---|---|---|---|
+| 安装 | `install.bat` | `sh install.sh` | 安装根 `install.bat` / `install.sh`（建 `.venv`、装依赖、自检、注册服务） |
+| 运行 | `run.bat` | `sh run.sh` | 安装根 `start.bat`（Windows）／`python guanlan.py serve`（跨平台） |
+| 卸载 | `uninstall.bat` | `sh uninstall.sh` | 安装根 `uninstall.bat` / `uninstall.sh` |
+
+目录约定（P9，2026-09-28 用户令）：
+
+```
+app_ETL/
+  common/               模块内通用插件/组件（旧导入前缀的兼容别名在此保留一个版本）
+  configs/              本模块专属配置域（共用单件在安装根 configs/）
+  data/                 模块相关数据件（运行期数据在安装根 data/、outputs/）
+  app_ETL_guanlan/                观澜在本模块的实现包（模块间调用只许经其中的 api.py）
+  README.MD             本文件（职责 / 公开面 / 安装部署与运行）
+  install.bat|sh  uninstall.bat|sh  run.bat|sh
+```
+
+自检与打包：安装根 `check.bat`（=`python guanlan.py check`）、`pack.bat` / `sh pack.sh`
+（打包 + 开箱验证：页面 5/5 + 卸载核验）。

app_ETL/app_ETL_guanlan/__init__.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+r"""数据接入管理模块实现包（P2 起）。"""

app_ETL/common/app_ETL_guanlan/api.py → app_ETL/app_ETL_guanlan/api.py

@@ -15,16 +15,16 @@ import importlib
 
 # 模块（按名惰性转发）—— P2 起实现就在本模块目录内
 _TARGETS: dict[str, str] = {
-    'data': 'app_ETL.common.app_ETL_guanlan.data',
-    'scada_source': 'app_ETL.common.app_ETL_guanlan.scada_source',
-    'slim': 'app_ETL.common.app_ETL_guanlan.slim',
-    'mdb_names': 'app_ETL.common.app_ETL_guanlan.mdb_names',
+    'data': 'app_ETL.app_ETL_guanlan.data',
+    'scada_source': 'app_ETL.app_ETL_guanlan.scada_source',
+    'slim': 'app_ETL.app_ETL_guanlan.slim',
+    'mdb_names': 'app_ETL.app_ETL_guanlan.mdb_names',
 }
 
 # ★2026-09-22 P3 增设: 常用的**函数级**公开名（算法层经本公开面取数，不再直接 import 本模块内部实现）。
-#   `from app_ETL.common.app_ETL_guanlan.api import load_10min` 这类写法由此成立。
-from app_ETL.common.app_ETL_guanlan.data import contracted_cols, load_10min   # noqa: E402,F401
-from app_ETL.common.app_ETL_guanlan import slim                               # noqa: E402,F401
+#   `from app_ETL.app_ETL_guanlan.api import load_10min` 这类写法由此成立。
+from app_ETL.app_ETL_guanlan.data import contracted_cols, load_10min   # noqa: E402,F401
+from app_ETL.app_ETL_guanlan import slim                               # noqa: E402,F401
 
 __all__ = list(_TARGETS) + ['load_10min', 'contracted_cols']
 

app_ETL/common/app_ETL_guanlan/builders/baseline_38_build.py → app_ETL/app_ETL_guanlan/builders/baseline_38_build.py

@@ -63,7 +63,7 @@ r"""三层基线生成端 —— 补上"包内没有生成端"的 `m5_cms_tcm/ba
 from __future__ import annotations
 
 try:
-    from app_common.common.app_common_guanlan.api import install_root as _install_root
+    from app_common.app_common_guanlan.api import install_root as _install_root
 except ImportError:                     # 理论不可达；包结构异常时回退到按位置上跳
     from pathlib import Path as _P
     def _install_root(_f): return _P(_f).resolve().parents[3]

app_ETL/common/app_ETL_guanlan/builders/component_history_build.py → app_ETL/app_ETL_guanlan/builders/component_history_build.py

@@ -66,7 +66,7 @@ trigger_time 2026-03-16 17:27 → 2026-04-21 10:18)。窗数 < 3 ⇒ 自动降
 from __future__ import annotations
 
 try:
-    from app_common.common.app_common_guanlan.api import install_root as _install_root
+    from app_common.app_common_guanlan.api import install_root as _install_root
 except ImportError:                     # 理论不可达；包结构异常时回退到按位置上跳
     from pathlib import Path as _P
     def _install_root(_f): return _P(_f).resolve().parents[3]

app_ETL/common/app_ETL_guanlan/builders/csv_to_mdb.py → app_ETL/app_ETL_guanlan/builders/csv_to_mdb.py

@@ -22,7 +22,7 @@ r"""CSV → MDB（仿照现场 `25年.zip`/`26年.zip` 的形态） + 全量核
 from __future__ import annotations
 
 try:
-    from app_common.common.app_common_guanlan.api import install_root as _install_root
+    from app_common.app_common_guanlan.api import install_root as _install_root
 except ImportError:                     # 理论不可达；包结构异常时回退到按位置上跳
     from pathlib import Path as _P
     def _install_root(_f): return _P(_f).resolve().parents[3]

app_ETL/common/app_ETL_guanlan/builders/pitch_face_build.py → app_ETL/app_ETL_guanlan/builders/pitch_face_build.py

@@ -82,7 +82,7 @@ n_op=48，本器同日在位运行段 61 段），故**旧件只作量级对拍
 from __future__ import annotations
 
 try:
-    from app_common.common.app_common_guanlan.api import install_root as _install_root
+    from app_common.app_common_guanlan.api import install_root as _install_root
 except ImportError:                     # 理论不可达；包结构异常时回退到按位置上跳
     from pathlib import Path as _P
     def _install_root(_f): return _P(_f).resolve().parents[3]

app_ETL/common/app_ETL_guanlan/builders/place_raw_data.py → app_ETL/app_ETL_guanlan/builders/place_raw_data.py

@@ -106,7 +106,7 @@ A2 定了四项数据源的落位: data/raw/<场站名称>/{scada_10min, 故障
 from __future__ import annotations
 
 try:
-    from app_common.common.app_common_guanlan.api import install_root as _install_root
+    from app_common.app_common_guanlan.api import install_root as _install_root
 except ImportError:                     # 理论不可达；包结构异常时回退到按位置上跳
     from pathlib import Path as _P
     def _install_root(_f): return _P(_f).resolve().parents[3]

app_ETL/common/app_ETL_guanlan/builders/raw_data_check.py → app_ETL/app_ETL_guanlan/builders/raw_data_check.py

@@ -40,7 +40,7 @@ r"""输入数据放置体检 + 增量放置指导 (2026-09-17 用户令 3)。
 from __future__ import annotations
 
 try:
-    from app_common.common.app_common_guanlan.api import install_root as _install_root
+    from app_common.app_common_guanlan.api import install_root as _install_root
 except ImportError:                     # 理论不可达；包结构异常时回退到按位置上跳
     from pathlib import Path as _P
     def _install_root(_f): return _P(_f).resolve().parents[3]

app_ETL/common/app_ETL_guanlan/builders/raw_scan.py → app_ETL/app_ETL_guanlan/builders/raw_scan.py

@@ -36,7 +36,7 @@ r"""输入数据自动扫描识别 —— 发现 `<安装目录>/data/raw` 下
 from __future__ import annotations
 
 try:
-    from app_common.common.app_common_guanlan.api import install_root as _install_root
+    from app_common.app_common_guanlan.api import install_root as _install_root
 except ImportError:                     # 理论不可达；包结构异常时回退到按位置上跳
     from pathlib import Path as _P
     def _install_root(_f): return _P(_f).resolve().parents[3]

app_ETL/common/app_ETL_guanlan/builders/rebuild_all.py → app_ETL/app_ETL_guanlan/builders/rebuild_all.py

@@ -35,7 +35,7 @@ r"""一条命令重算全部 (2026-09-12) —— 把散在各脚本里的重算
 from __future__ import annotations
 
 try:
-    from app_common.common.app_common_guanlan.api import install_root as _install_root
+    from app_common.app_common_guanlan.api import install_root as _install_root
 except ImportError:                     # 理论不可达；包结构异常时回退到按位置上跳
     from pathlib import Path as _P
     def _install_root(_f): return _P(_f).resolve().parents[3]

app_ETL/common/app_ETL_guanlan/builders/rebuild_from_raw.py → app_ETL/app_ETL_guanlan/builders/rebuild_from_raw.py

@@ -34,7 +34,7 @@ r"""从 data/raw 重算/更新产物 (2026-09-11) —— 维护页那四条「
 from __future__ import annotations
 
 try:
-    from app_common.common.app_common_guanlan.api import install_root as _install_root
+    from app_common.app_common_guanlan.api import install_root as _install_root
 except ImportError:                     # 理论不可达；包结构异常时回退到按位置上跳
     from pathlib import Path as _P
     def _install_root(_f): return _P(_f).resolve().parents[3]

app_ETL/common/app_ETL_guanlan/builders/scada_slim_build.py → app_ETL/app_ETL_guanlan/builders/scada_slim_build.py

@@ -31,7 +31,7 @@ r"""SCADA 10min **精简轴仓**（slim10min）：按窗重算的公共底座（
 from __future__ import annotations
 
 try:
-    from app_common.common.app_common_guanlan.api import install_root as _install_root
+    from app_common.app_common_guanlan.api import install_root as _install_root
 except ImportError:                     # 理论不可达；包结构异常时回退到按位置上跳
     from pathlib import Path as _P
     def _install_root(_f): return _P(_f).resolve().parents[3]

app_ETL/common/app_ETL_guanlan/builders/vib_raw_build.py → app_ETL/app_ETL_guanlan/builders/vib_raw_build.py

@@ -61,7 +61,7 @@
 from __future__ import annotations
 
 try:
-    from app_common.common.app_common_guanlan.api import install_root as _install_root
+    from app_common.app_common_guanlan.api import install_root as _install_root
 except ImportError:                     # 理论不可达；包结构异常时回退到按位置上跳
     from pathlib import Path as _P
     def _install_root(_f): return _P(_f).resolve().parents[3]

app_ETL/common/app_ETL_guanlan/builders/windscada_monthly_build.py → app_ETL/app_ETL_guanlan/builders/windscada_monthly_build.py

@@ -28,7 +28,7 @@
 from __future__ import annotations
 
 try:
-    from app_common.common.app_common_guanlan.api import install_root as _install_root
+    from app_common.app_common_guanlan.api import install_root as _install_root
 except ImportError:                     # 理论不可达；包结构异常时回退到按位置上跳
     from pathlib import Path as _P
     def _install_root(_f): return _P(_f).resolve().parents[3]

app_ETL/common/app_ETL_guanlan/data.py → app_ETL/app_ETL_guanlan/data.py

@@ -39,7 +39,7 @@ def load_10min(turbine, cfg=None, groups=None):
         raise RuntimeError(f"L0 校验门不过: {g['note']}")
     c = contract(cfg)
     want = [c['ts_col']] + contracted_cols(cfg, groups)
-    from app_ETL.common.app_ETL_guanlan import scada_source as SS
+    from app_ETL.app_ETL_guanlan import scada_source as SS
     d = SS.load('10min', turbine, columns=want, cfg=cfg)
     src = str(d.attrs.get('scada_source') or '?')
     _note_source(src)
@@ -69,7 +69,7 @@ def _note_source(src: str) -> None:
 
 def source_report(cfg=None) -> dict:
     """本机 SCADA 收资形态盘点（页面/自检用）: 各形态件数 + 逐台会走哪种。"""
-    from app_ETL.common.app_ETL_guanlan import scada_source as SS
+    from app_ETL.app_ETL_guanlan import scada_source as SS
     cfg = cfg or farm()
     out = {}
     for cls in ('10min', '1min'):

app_ETL/common/app_ETL_guanlan/scada_source.py → app_ETL/app_ETL_guanlan/scada_source.py

@@ -327,7 +327,7 @@ def load(cls: str, turbine: str, columns=None, cfg=None, month: str | None = Non
 def read_mdb(cls: str, turbine: str, columns=None, cfg=None, month: str | None = None):
     """从月库里取一台：逐分片表按 (rid, turbine) 拼列。"""
     import pandas as pd
-    from app_ETL.common.app_ETL_guanlan.mdb_names import safe_name
+    from app_ETL.app_ETL_guanlan.mdb_names import safe_name
     s = sources(cls, cfg)
     mdbs = [m for m in s['mdbs'] if not month or m.stem.startswith(month)]
     if not mdbs:

app_ETL/common/README.md

@@ -0,0 +1,8 @@
+# `common/` —— 本模块的通用插件 / 组件
+
+跨模块复用的公共层是 **`app_common/`**（路径真源、版本、日志、进程、入口引用…）。
+本目录放**本模块内部**可复用的通用插件/组件（不含观澜业务语义）。
+
+现状：本模块的实现包是 `../app_ETL_guanlan/`（观澜业务实现），模块内暂未拆出"通用 vs 业务"两层，
+因此本目录当前只保留包标记与这份说明。旧导入前缀的兼容别名包
+`common/app_ETL_guanlan/`（`from app_ETL.common.app_ETL_guanlan.…`）在此保留**一个版本**，下版删除。

app_ETL/common/app_ETL_guanlan/__init__.py

@@ -1,2 +1,16 @@
 # -*- coding: utf-8 -*-
-r"""数据接入管理模块实现包（P2 起）。"""
+r"""兼容别名（P9，2026-09-28）：实现已上提到 `app_ETL/app_ETL_guanlan/`。**本包只做前缀别名，下个版本删除。**
+
+用户令 2026-09-28 新结构：每个模块的实现包直接挂在模块根下。旧写法
+`from app_ETL.common.app_ETL_guanlan.<子件> import …` 在一个版本内继续可用，且**与新版是同一个模块对象**
+（同名同体，见 `app_common/app_common_guanlan/_alias.py`）。
+"""
+from __future__ import annotations
+
+import sys
+
+from app_common.app_common_guanlan.api import alias_prefix
+from app_ETL import app_ETL_guanlan as _new
+
+alias_prefix(__name__, _new.__name__)
+sys.modules[__name__] = _new

app_ETL/configs/README.md

@@ -0,0 +1,7 @@
+# `configs/` —— 本模块的专属配置
+
+* **本目录**：本模块专属的配置域（见安装根 `configs/registry.yaml` 的 `domains[].owner`）。
+* **安装根 `configs/`**：跨模块**共用单件**配置（`serve.json` 端口/路径真源、`models.json` 本机模型档、
+  `portal_pages.yaml` 页面归口、`modules.yaml` 模块登记、`registry.yaml` 配置登记）。
+* 代码**只许**用取用口读配置：`from app_common.app_common_guanlan.api import paths as P` →
+  `P.config('terms', 'display_map.yaml')` / `P.config_dir('farms')`（多根查找 + 单源校验，手拼路径会被门禁拦）。