# 观澜 · 本体与知识层（`app_ontology/`）

**职责**：对象库与码表摄入、机制链、决策台、检索索引、实机参数表、SOP 场景与验收状态机、本机模型闸

**允许依赖**：app_common

**对外公开面**：`common/app_ontology_guanlan/api.py` —— 模块间调用**只许**走这里（`scripts/module_boundary_audit.py` 机器检查）。

**目录（P6 起，2026-09-28）**：

```
common/app_ontology_guanlan/
  api.py        公开面（本体 19 名 + SOP 39 名；PEP 562 惰性转发）
  ontology/     本体：store · schema · codes · kb_ingest · populate · chain_ingest · trend_ingest ·
                retrieval · maintenance · decisions · audit · fast_agent · llm_gate · acceptance_fsm ·
                mcp_server · migrate · monthly_roll · scenario_29 · seed_rudong29
  sop/          SOP 与知识层：schemas · contract_gate · analysis_kit · discriminators · farm_pipeline ·
                survey · goem · vib_impact · vib_confidence · fusion_diag · cases · scenarios ·
                ledger_dates · price · backfill · wrapup · learn_loop · schema_guard · fleet_query ·
                assistant(_llm) · agent_query_common · 各类 *_validation · validate_pair · stat_clean ·
                derive10min · farm_paths · analysis_lock · schedule · wind_coupling · xlsx_read
```

**迁移状态**：**P6 已完成（2026-09-28）** —— 58 个模块（20 本体件 + 38 SOP 件，约 19,775 行）实体迁入本模块；
旧路径 `src/ontology/<件>.py`、`src/sop/<件>.py` **全部留模块别名壳**：`from src.sop.cases import …` 与
`python -m src.ontology.kb_ingest`（重算链 ⑦ 步的入口）都照旧可用（壳里 `runpy` 按 `__main__` 重跑实现）。

**本轮实逮**：① 包内 `from .. import paths as P`（23 处）在迁入子包后要改**绝对路径**（`from src import paths as P`）；
② 19 处 `__file__` 取根（`parents[2]`）改公共层 `install_root()`；③ **`-m` 入口**必须由壳用 `runpy.run_module(..., run_name="__main__")`
兜住，否则 `python -m src.ontology.<件>` 会静默不出活（重算链 ⑦ 步依赖它）；④ 按源码路径读本层文件的审计器
（`audit_chinese_terms` 的 DEFAULT_TARGETS、`check_portability` 的 ALLOW 键、`products_reverse_audit` 的生成端路径、
`configs/{registry,terms/jargon_rules}.yaml` 的 consumers/referenced_by）要同步改到新位置，否则门禁会读壳或误报。

**验收**：58/58 模块新旧路径均可导入且同体；取根抽查全部等于安装根；9 条稳定路由（门户 / `/ops` / `/cms/` /
`/api/ont_list` / `/api/ont_chain` / `/api/maint_survey` / `/api/maint_std` / `/api/maint_framework` /
`/api/dq_findings` / `/api/facts`）响应体 sha256 与迁移前一致；全门禁 rc=0。

**清理（2.12.1 / 2026-09-28）**：`sop/cms_availability.py`（275 行，L0 数据可用性判据）**已删除** —— 全仓无调用，
且 L0 判据的实际实现是 `scripts/rudong_model_run.py::l0_layer`（重算链跑的是后者）；`api.py` 的 `sop_cms_availability`
公开名与旧路径壳 `src/sop/cms_availability.py` 一并摘除。取证见 `docs/源代码梳理_v0.1.md` §5。

> 依据：`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_ontology/
  common/               模块内通用插件/组件（旧导入前缀的兼容别名在此保留一个版本）
  configs/              本模块专属配置域（共用单件在安装根 configs/）
  data/                 模块相关数据件（运行期数据在安装根 data/、outputs/）
  app_ontology_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 + 卸载核验）。