增加字段config重构文档

2026-03-12 11:39:57 +08:00
parent e786bd5bf0
commit 0ae2db1808
2 changed files with 623 additions and 0 deletions
@@ -0,0 +1,183 @@
+# Construction 领域重构指南
+
+## 1. 范围
+
+本文档只讨论 construction 领域中，与集团侧 `enum_config` 对应、且和项目类型初始化有关的字段。
+
+当前本轮只聚焦一条主线：
+
+- `construction.section_type_code`
+
+以下复杂问题本轮先明确跳过，不在本文展开：
+
+- `task_id`
+- `task_type`
+- 其它施工节点层级和映射规则特别复杂的问题
+
+也就是说，施工文档本轮先解决 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`
+
+推荐结构：
+
+```json
+{
+  "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` 中哪些数据只是节点补充信息，哪些其实已经在承担字段候选项职责。
+
+如果发现某字段既参与初始化又参与手动创建，就应优先考虑迁到字段级配置。