增加项目侧重构文档

docs/enum_refactor/plan.md

@@ -22,6 +22,60 @@
 - enum 字段：继续留在代码中，由 enum 表达固定约束。
 - field_config 字段：迁到配置中，由字段级配置表达候选项。
 
+## 1.1 本轮实际要改的内容
+
+这次文档和后续代码改造，不再停留在“抽象上应该统一”的层面，而是直接围绕下面 5 件事展开。
+
+### 0. 通用能力
+
+要补两类公共能力：
+
+- 增强现有配置类，在 `ConfigService` 上新增字段级配置读取、映射、校验工具。
+- 增强基于 JSON 导出 CSV 的工具，使字段级配置和现有 config 维护流程能直接联动。
+
+### 1. 优化项目初始化过程
+
+目标不是只分析 `init_project_data)`，而是把初始化链路改成统一从配置工具取候选项：
+
+- 整理项目初始化当前实际使用到的 config。
+- 把适合迁移的初始化候选项改为通过新的 config 工具获取后创建。
+- 去掉不适当的 dict 用法，例如把单位塞在 dict `remark` 里。
+
+### 2. 优化创建数据的验证
+
+这次不改 schema 目录类型系统，但要改 service 层入口。
+
+要求是：
+
+- 在 create 类接口对应的 service 业务入口开头，基于 config 工具校验 code 类字段。
+- 不再继续新增代码字典白名单、硬编码 if/else 白名单。
+
+### 3. 统一下拉列表来源
+
+这次不仅要梳理下拉列表，还要把它们收口到新的 config 工具：
+
+- 梳理所有 code 类下拉列表当前返回路径。
+- 能迁移的下拉统一改成通过 config 工具返回。
+- 少量现有写死的下拉列表，例如合同结算类型列表，也要改成动态获取。
+
+### 4. 删除废弃 enum / 硬编码字典
+
+完成上述迁移后，要清掉已经不再适合作为真源的：
+
+- 废弃 enum
+- 废弃硬编码 dict
+- 只用于旧下拉或旧创建校验的代码常量
+
+### 5. 自动化测试脚本
+
+这次不是只改文档和代码，还要补自动化测试，覆盖至少 3 类集成场景：
+
+- 初始化脚本 / 初始化 service 集成测试
+- 各业务下拉列表获取集成测试
+- 各业务 create service 集成测试
+
+测试脚本写在 `tests` 下，不写到项目根目录。
+
 ## 2. 重构范围
 
 本次重构只覆盖一类字段：
@@ -50,6 +104,12 @@
 
 本次要做的不是一次性清理所有来源，而是为这些字段补一个统一的字段级配置出口。
 
+对本轮来说，这里的“统一出口”不是泛指，而是明确服务于 3 条业务链路：
+
+- 初始化：通过统一配置工具取候选项并创建数据
+- 创建：通过统一配置工具校验 code 类字段
+- 下拉：通过统一配置工具返回选项列表
+
 ## 3. 不在本次范围内的内容
 
 以下内容明确不在本次重构范围：
@@ -61,6 +121,11 @@
 - schema 目录下的类型系统改造
 - 运行时直接读取 JSON 文件作为配置源
 
+这里补充两条边界：
+
+- 不允许为了兼容旧逻辑继续新增 dict `remark` 之类的隐式字段承载方式。
+- 不允许为了减少改动，在新工具落地后继续保留“前端下拉走 config、初始化走 dict、create 校验走代码字典”的三头并存状态。
+
 因此，本次允许字段级配置中的 `value / label` 与现有 dict 翻译短期重复。后续如有需要，可再通过脚本生成 dict 或做统一翻译收敛。
 
 ## 4. 核心设计
@@ -225,6 +290,17 @@ async def validate_field_value(
     ...
 ```
 
+如果后续需要覆盖“批量校验多个字段”或“直接返回下拉结构”的场景，可以继续补：
+
+```python
+async def get_field_options_for_frontend(project_type: str, key: str, tenant_id: str | None = None) -> list[dict[str, Any]]:
+    ...
+
+
+async def validate_field_values(project_type: str, items: list[tuple[str, str]], tenant_id: str | None = None) -> None:
+    ...
+```
+
 ### 6.2 各接口职责
 
 `get_field_config()`：
@@ -255,6 +331,12 @@ async def validate_field_value(
 - 校验给定值是否在当前项目类型该字段的候选项中
 - 校验失败时抛出业务异常
 
+另外，本轮会直接用到两种典型调用方式：
+
+- 初始化时：`get_field_options()` / `get_field_option_map()`
+- 创建和编辑时：`validate_field_value()`
+- 下拉接口时：`get_field_options_for_frontend()` 或 `get_field_options()`
+
 这里特别强调：
 
 - `validate` 是手动调用的
@@ -325,6 +407,12 @@ async def validate_field_value(
 - JSON 文件仍然采用 config 行列表格式
 - 工具负责 JSON 和 `config.csv`、数据库之间的转换
 
+这块和本轮目标直接对应：
+
+- 字段级配置调整后，可以直接导出为 `config.csv`
+- 初始化改造前后，可以快速对比 config 差异
+- 下拉列表和创建校验依赖的 config，可以单独导出检查，不再手工翻长 CSV
+
 建议目录：
 
 - `scripts/initdata/json_config/`
@@ -413,6 +501,12 @@ async def validate_field_value(
 - 手动创建时从硬编码 dict 判断合法值，改为调用 `validate_field_value()`
 - 展示名称时从字段选项里直接拿 `label`
 
+对本轮来说，每个领域文档都至少要把下面 3 条链路写清楚：
+
+- 初始化：这个字段初始化时从哪里取候选项，迁移后改成哪个 config key
+- 创建：这个字段 create service 当前怎么校验，迁移后改成哪个 `validate_field_value()` 调用
+- 下拉：这个字段前端当前通过哪个接口取值，迁移后改成哪个 config key 统一返回
+
 ### 8.4 必须完整对齐集团侧 `enum_config`
 
 领域梳理时，不能只挑 depm 里已经处理过的字段，也不能只挑“看起来最容易改”的字段。
@@ -432,7 +526,7 @@ async def validate_field_value(
 
 ## 9. 实施步骤
 
-### 第一阶段：定义公共 schema 和 `ConfigService` 接口
+### 第一阶段：公共能力
 
 - 明确字段级配置固定 JSON 结构
 - 新增 `FieldOptionItem`
@@ -440,21 +534,33 @@ async def validate_field_value(
 - 给关键读取方法加缓存
 - 补齐 JSON 序列化 / 反序列化统一处理
 - 明确错误处理规则：配置结构不合法时直接报错
+- 增强 JSON / CSV 工具，支持字段级配置导入导出
 
-### 第二阶段：重整 JSON / CSV 工具
+### 第二阶段：初始化改造
 
-- 建立 `scripts/initdata/json_config/` 目录规范
-- 支持一 key 一文件
-- 支持 `json_config` 批量生成 `config.csv`
-- 支持 `json_config` 批量导入数据库
-- 支持从 `config.csv` / 数据库反向导出 JSON
+- 逐项整理 `init_project_data)` 当前真实依赖的 config / dict
+- 把 `preparation`、`production`、`power` 这类平铺型初始化模板迁到 config
+- 整理 `material` 初始化，把单位等附属属性从不适当的 dict 备注迁出
+- 清理 `init_project_data)` 中取了但不该继续作为真源的 dict 依赖
 
-### 第三阶段：按领域逐个梳理并迁移
+### 第三阶段：创建校验改造
 
-- 按领域编写独立重构文档
-- 明确该领域哪些字段迁到 `field_config`
-- 改造初始化流程和手动创建校验流程
-- 下线对应的硬编码白名单和不再适合承担初始化来源的 dict 使用方式
+- 为 contract / material / construction 等 create service 入口补基于 config 的 code 校验
+- 把当前分散在 service 内的硬编码白名单逐步迁到 config 工具
+- 保留真正应该继续存在的代码 enum，不把固定语义状态误迁到 config
+
+### 第四阶段：下拉列表改造
+
+- 梳理 code 类下拉接口
+- 下拉统一改成通过 config 工具返回
+- 少量仍写死的下拉改为动态获取
+- 保证前端下拉、初始化候选项、create 校验三者同源
+
+### 第五阶段：清理和测试
+
+- 删除废弃 enum 和废弃代码字典
+- 删除不再适合作为真源的 dict 依赖
+- 补 service 层集成测试和初始化测试
 
 ## 10. 产出要求
 
@@ -465,9 +571,42 @@ async def validate_field_value(
 - 一套明确的缓存与缓存失效规则
 - 一套 JSON / CSV / DB 三者之间的转换与维护规范
 - 一组领域级重构文档
+- 一组初始化 / 下拉 / create 的 service 层集成测试
 
 判断本次重构是否成功的标准不是“历史实现全部统一”，而是：
 
 - 后续新增一个与项目类型初始化相关的字段时，知道应优先写入字段级配置总表
 - 业务代码可以通过 `ConfigService` 统一获取 options / map / label / validate
-- 初始化流程和手动创建校验可以逐步收敛到同一来源
+- 初始化流程和手动创建校验可以逐步收敛到同一来源
+- 前端下拉、初始化、create 校验不再各自读不同真源
+
+## 11. 自动化测试要求
+
+这次测试不是只补 unit test，而是以 service 层集成测试为主。
+
+至少覆盖下面 3 组：
+
+### 11.1 初始化测试
+
+- 覆盖项目初始化入口
+- 校验初始化创建出的 preparation / production / contract / material / power / construction 数据是否来自目标 config
+- 校验错误配置时直接报错，不做静默降级
+
+### 11.2 下拉列表测试
+
+- 覆盖 contract / material / construction 等核心下拉接口或对应 service
+- 校验返回项是否来自预期 config key
+- 校验下拉返回和初始化候选项是否一致
+
+### 11.3 Create 校验测试
+
+- 直接走 service 层 create
+- 对合法 code 校验通过
+- 对非法 code 明确抛错
+- 校验不再依赖旧硬编码字典或 dict `remark`
+
+### 11.4 测试组织方式
+
+- 测试代码写在 `tests/` 下
+- 优先写 service 层集成测试，不在项目根目录放临时脚本
+- 如果需要初始化测试数据，应复用现有测试体系，不改 `schemas/`、不改 `filtered_datasource/`