ecm_sync_system/docs/enum_refactor/construction.md

Construction 领域重构指南

1. 范围

本文档应覆盖 construction 领域中两部分字段的并集：

• 集团侧 enum_config 中 construction 相关的全部字段
• depm 中所有已经使用代码 enum、代码中的初始化列表、硬编码 dict、类 enum、config 表、dict 表承载，并且会影响施工初始化、手动创建、手动编辑、接口展示或业务校验的相关字段

当前这份文档先给出 construction 领域的总范围和主线判断，再把本轮优先落地对象收敛到一条主线：

• construction.section_type_code

以下复杂问题本轮先不展开具体迁移方案，但仍属于 construction 领域后续必须补齐的梳理范围：

• task_id
• task_type
• 其它施工节点层级和映射规则特别复杂的问题

也就是说，施工文档不是永久只看 section，而是本轮先把 section 这一层讲清楚，同时把 task 相关复杂问题明确记为后续梳理项，而不是视为领域外问题。

2. 当前现状

construction 领域当前至少有两类配置来源：

2.1 construction_section_config

当前按项目类型配置 section 信息，例如光伏下的：

• code
• name
• weight
• project_root_nodes

这份配置同时承担：

• section 候选项来源
• 施工初始化入口信息来源

2.2 construction_node_config

当前按项目类型配置节点信息，例如：

• task_code
• type_id
• type_name
• unit
• weight
• is_primary
• section

这份配置描述的是节点补充信息，不是字段级配置。

3. 重构目标

construction 领域本轮的目标不是重写全部施工配置，而是：

• 把 section 候选项迁到新的字段级配置
• 保留 construction_node_config 作为自由业务配置
• 让施工初始化和手动校验可以逐步复用统一的字段级入口

4. construction.section_type_code 的新结构

construction_section_config 应改造成新的字段级 key：

• construction.section_type_code

它的 JSON 中必须包含：

• field_config

并且可以额外包含业务自定义字段，例如：

• description
• init_config

推荐结构：

{
  "description": "施工区字段配置",
  "field_config": [
    {"value": "GF", "label": "光伏场区", "weight": 1.4},
    {"value": "SY", "label": "升压站", "weight": 1.4},
    {"value": "SC", "label": "送出(自建)", "weight": 1.2},
    {"value": "SCDW", "label": "送出(电网建设)", "weight": 1.0}
  ],
  "init_config": {
    "root_nodes_by_value": {
      "GF": [
        {"type_id": "01", "type_code": "01", "type_name": "光伏区土建工程"},
        {"type_id": "03", "type_code": "03", "type_name": "光伏区安装工程"}
      ],
      "SY": [
        {"type_id": "02", "type_code": "02", "type_name": "升压站土建工程"}
      ]
    }
  }
}

这里的原则是：

• field_config 负责 section 候选项
• init_config 负责 section 相关初始化附属数据
• 两者可以同处一个 JSON 中，不需要再拆第二份 section 配置

5. construction_node_config 的定位

construction_node_config 不迁到字段级配置。

它仍然是自由业务配置，负责描述：

• 可能节点有哪些种类
• 哪些节点是主节点
• 节点单位、权重等补充信息

建议只做一项统一性改造：

• 顶层补 description

6. 需要迁移到 field_config 的功能

construction 领域应重点梳理下面两类功能：

6.1 项目初始化链路

需要明确：

• 初始化 section 时，候选项是否改由 get_field_options(project_type, "construction.section_type_code") 提供
• 初始化 root node 时，是否从同一配置对象中的业务自定义字段读取附属数据

也就是说，初始化链路应逐步从“直接解释旧 construction_section_config”迁移到“先读取字段级配置，再读取其业务附属字段”。

6.2 手动创建 / 编辑链路

需要明确：

• 如果某接口允许手动传 section_type_code
• 是否应改为调用 validate_field_value(project_type, "construction.section_type_code", value)

这样可以保证手动写入与初始化使用同一套候选项来源。

7. 当前迁移示例

示例 1：section 候选项读取

当前：

• 通过 construction 私有 helper 直接读取并解释 construction_section_config

目标：

• 通过 ConfigService.get_field_options(project_type, "construction.section_type_code") 获取 section 列表

示例 2：section 合法值校验

当前：

• 可能由业务代码自行判断，或者根本没有统一校验入口

目标：

• 统一走 ConfigService.validate_field_value(...)

示例 3：初始化附属数据读取

当前：

• 直接从旧 construction_section_config 读取 project_root_nodes

目标：

• 从 construction.section_type_code 的完整配置对象中读取业务自定义字段

8. 梳理清单

construction 领域后续梳理时，至少要回答下面这些问题：

1. 哪些字段属于集团侧 enum_config 已覆盖或可对应的字段。
2. 哪些字段在初始化时使用候选项，哪些字段在手动创建时也要校验。
3. 哪些逻辑仍在直接解释旧 JSON，而不是通过统一 helper 读取。
4. 哪些逻辑仍在使用硬编码白名单。
5. construction_node_config 中哪些数据只是节点补充信息，哪些其实已经在承担字段候选项职责。

如果发现某字段既参与初始化又参与手动创建，就应优先考虑迁到字段级配置。

9. 按本轮要求的改造落点

construction 领域这轮不是泛泛地“改配置”，而是明确围绕 3 条链路收口：

• 初始化
• create 校验
• 下拉列表

9.1 初始化

当前施工初始化本来就不是 dict 驱动，而是：

• construction_section_config
• ConstructionTypeTree
• ConstructionTypeMapping

因此本轮初始化改造的重点不是“把 dict 搬到 config”，而是：

• 把 section_type_code 的候选项读取统一收口到新的 config 工具
• 保留类型树和 root node 等结构化数据，但不再让 section 候选项散落在私有 helper 里

9.2 Create 校验

当前 ConstructionService.create() / create_for_scdw() 已经在 service 开头做了较强校验：

• section_type_code 来自 construction_section_config
• section_sub_type_code 来自 section config 和类型树映射
• type_id 来自施工类型树或 SCDW 专用配置

本轮目标是：

• section_type_code 统一改成通过 ConfigService.validate_field_value(project_type, "construction.section_type_code", value) 校验
• section_sub_type_code、type_id 继续走配置/类型树校验，不做降级

9.3 下拉列表

当前施工下拉接口已经基本同源：

• /construction/section/type/list
• /construction/section/sub/type/list
• /construction/task/type/list

它们当前都来自 construction_section_config + 类型树。

本轮目标不是重做接口，而是：

• 让 section 级选项由新的 config 工具统一返回
• 保证下拉、初始化、create 校验继续同源

9.4 清理项

construction 领域这轮优先清理的是“section 候选项读取分散”问题，不是一次性重写全部施工结构。

完成后应清理：

• 只负责 section 候选项翻译的旧 helper 直接解析逻辑
• 不再适合作为 section 真源的旧硬编码映射

但下面这些不属于本轮删除目标：

• ConstructionTypeTree
• ConstructionTypeMapping
• 与节点树生成强绑定的结构化配置

10. 测试关注点

construction 领域 service 层集成测试至少覆盖：

1. 初始化：项目初始化后生成的 section / root node / 主施工任务是否来自目标 config。
2. 下拉：section / sub type / task type 列表是否和初始化使用同源配置。
3. Create：合法 section_type_code、section_sub_type_code、type_id 可以创建，非法值明确报错。