# 观澜 · 配置登记表 (2026-09-17 用户令 2「统一系统的配置目录及配置文件」)
#
# 这份表回答三件事, 且**由机器核对**(scripts/config_audit.py):
#   ① configs/ 下每个目录/文件是什么、谁读它 (消费者), 不允许"有件不知谁用";
#   ② 代码引用的配置到底在不在 (悬空引用 = 文件没随包, 代码却在读);
#   ③ 命名/格式/内容三条底线 (无备份垃圾文件、无本机绝对路径、顶层只放运行期单件配置)。
#
# 约定 (与 src/paths.py 的"配置目录约定"一节同源, 代码只许走 P.config()/P.config_dir()):
#   configs/serve.json          运行期单件: 端口/路径真源
#   configs/models.json         运行期单件: 本机模型档
#   configs/portal_pages.yaml   运行期单件: 门户页面归口登记表 (docs §10)
#   configs/<域>/…              域 = canonical | contracts | farms | terms
#   新域必须在本表登记 (kind + consumers), 否则审计报"未登记域"。
version: 1

top_level:
  - file: serve.json
    kind: 运行期单件配置
    consumers: [guanlan.py, scripts/guanlan_ops.py, scripts/page_fingerprint.py, scripts/guanlan_gateway.py, scripts/check_transferable.py]
    schema: "{host, gateway, detail, cms, sim, sim_sys, viewer, ollama, python?, raw_dir?}"
  - file: models.json
    kind: 运行期单件配置
    consumers: [guanlan.py, src/ontology/llm_gate.py, src/ontology/fast_agent.py]
    schema: "{tiers: {<档>: {model, pull_commands?}}, ...}"
  - file: portal_pages.yaml
    kind: 运行期单件配置 (页面归口登记表)
    consumers: [scripts/pages_audit.py]
    schema: "见 docs §10 / 本文件头"
  - file: modules.yaml
    kind: "开发期配置 (模块登记表：每个模块一个目录 + 边界与依赖方向)"
    consumers: [scripts/module_boundary_audit.py]
    schema: "{layout: {module_root, common_dir, package_pattern, public_face}, modules: [{name, cn, resp, allow, impl_now, phase}]}"
    note: "用户令 2026-09-22 按算法/数据接入管理/前端/后端等模块重构源代码; 设计见 docs/重构方案_模块化_v0.1.md"

domains:
  - dir: canonical
    kind: 通道/测点 canonical 字典 (内部说法 ↔ 现场说法的单一真源)
    consumers: [src/sop/contract_gate.py, src/sop/discriminators.py]
    consumed_by: 随包代码 + 未随包的分析链 (见 docs §7)
    files: 3
  - dir: canonical/alias
    kind: canonical 别名字典 (场站/机型/测点别名)
    consumers: []
    consumed_by: 未随包的分析链 (本包 0 处按名读取; 保留为数据字典)
    files: 71
    no_reader_ok: true
    why: 别名表由分析链与本体侧的术语映射消费; 本包在位的同类是 configs/terms/display_map.yaml
  - dir: contracts
    kind: 字段契约 / 机型-场站对照表 (csv 与 yaml 混放)
    consumers: [scripts/sim_hub/wake_anim.py, scripts/sim_hub/wake_real.py]
    files: 74
  - dir: farms
    kind: 场配置 (两种 schema 混放, 见下两条)
    consumers: [src/windscada/config.py]
    files: 15
    subkinds:
      - name: 场定义 (windscada 用)
        match: "*.yaml|*.json"
        require_keys: [name, n_turbines, turbines, src_10min, src_alarm, store, rated_kw]
        note: "约定用 YAML (新场写 yaml); 这类文件必须能被 available() 列出并加载"
        present: 0
      - name: 机型/场站物理约束 profile (非场定义)
        match: "*.yaml"
        require_keys: [meta, physical_constraints]
        note: "另一条分析链的 schema (物理约束/脱敏词表); 本包**无读者** ⇒ 不参与场加载, 由 config_audit 记账"
        present: 10
      - name: CSV 交付/对照表
        match: "*.csv"
        note: "放在 farms/ 下的数据表 (机组清单/改造矩阵); 属数据而非配置, 见 docs §11 的处置"
        present: 4
  - dir: terms
    kind: 术语库与规则 (显示层映射 / OEM 术语基准 / 行话规则)
    consumers: [src/windscada/terms.py, src/windscada/ui/build.py, scripts/audit_chinese_terms.py, scripts/curate_oem_lexicon.py]
    files: 3

# 代码引用的配置, 在包里**不存在** —— 不是"忘了拷", 而是那条线的配置从未随包 (与 docs §7 的缺口同源)。
# 审计按"悬空引用"逐条报出; 每条的**影响**必须写清 (缺了会怎样), 不许含糊。
known_missing:
  - file: analysis_lock.yaml
    referenced_by: [src/sop/analysis_lock.py]
    impact: 分析锁校验不可用 (该模块会返回"找不到锁"并给出建文件指引, 不会崩)
    fix: 需要哪一场就建 configs/analysis_lock_<场>.yaml (六项冻结字段见模块头)
    also_missing: [analysis_lock_<场>.yaml]
  - file: scenario_registry.yaml
    referenced_by: [src/sop/scenarios.py]
    impact: SOP 场景解析不可用 (load_registry 直接 FileNotFoundError; 本包无调用方, 故不影响页面)
    fix: 从研发侧取回场景注册表; 或该功能不使用则明确删除该模块的入口引用
  - file: discriminator_registry.yaml
    referenced_by: [src/sop/cases.py]
    impact: 案例标题 → 判别器正式 id 的外键校验缺失 (cases 侧退化为 slug)
    fix: 随包补齐
  - file: analysis_modules.yaml
    referenced_by: [src/sop/schemas.py]
    impact: 分析模块标准卡的必填键校验缺单源 (schema 校验只在内存里做)
    fix: 随包补齐
  - file: value_assumptions/<场>.yaml
    referenced_by: [src/sop/wrapup.py]
    impact: 经济性换算的价参假设取不到 ⇒ 退回命令行参数/内置假设 (wrapup 里已显式标注 benchmark_assumed)
    fix: 建 configs/value_assumptions/<场>.yaml (price 段)
  - file: terms/oem_lexicon.yaml
    referenced_by: [scripts/build_oem_lexicon.py]
    impact: 无 (它是该脚本的**输出**, 首次运行生成)
    fix: 跑一次 scripts/build_oem_lexicon.py 即生成 (需要 --roots 指向文档根)