Merge branch 'main' of https://git.getaix.tech/strepsiades/ecm_sync_system

docs/enum_refactor/plan.md

@@ -110,6 +110,12 @@
 - 创建：通过统一配置工具校验 code 类字段
 - 下拉：通过统一配置工具返回选项列表
 
+对本轮来说，这里的“统一出口”不是泛指，而是明确服务于 3 条业务链路：
+
+- 初始化：通过统一配置工具取候选项并创建数据
+- 创建：通过统一配置工具校验 code 类字段
+- 下拉：通过统一配置工具返回选项列表
+
 ## 3. 不在本次范围内的内容
 
 以下内容明确不在本次重构范围：
@@ -126,6 +132,11 @@
 - 不允许为了兼容旧逻辑继续新增 dict `remark` 之类的隐式字段承载方式。
 - 不允许为了减少改动，在新工具落地后继续保留“前端下拉走 config、初始化走 dict、create 校验走代码字典”的三头并存状态。
 
+这里补充两条边界：
+
+- 不允许为了兼容旧逻辑继续新增 dict `remark` 之类的隐式字段承载方式。
+- 不允许为了减少改动，在新工具落地后继续保留“前端下拉走 config、初始化走 dict、create 校验走代码字典”的三头并存状态。
+
 因此，本次允许字段级配置中的 `value / label` 与现有 dict 翻译短期重复。后续如有需要，可再通过脚本生成 dict 或做统一翻译收敛。
 
 ## 4. 核心设计
@@ -297,6 +308,17 @@ async def get_field_options_for_frontend(project_type: str, key: str, tenant_id:
     ...
 
 
+async def validate_field_values(project_type: str, items: list[tuple[str, str]], tenant_id: str | None = None) -> None:
+    ...
+```
+
+如果后续需要覆盖“批量校验多个字段”或“直接返回下拉结构”的场景，可以继续补：
+
+```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:
     ...
 ```
@@ -337,6 +359,12 @@ async def validate_field_values(project_type: str, items: list[tuple[str, str]],
 - 创建和编辑时：`validate_field_value()`
 - 下拉接口时：`get_field_options_for_frontend()` 或 `get_field_options()`
 
+另外，本轮会直接用到两种典型调用方式：
+
+- 初始化时：`get_field_options()` / `get_field_option_map()`
+- 创建和编辑时：`validate_field_value()`
+- 下拉接口时：`get_field_options_for_frontend()` 或 `get_field_options()`
+
 这里特别强调：
 
 - `validate` 是手动调用的
@@ -413,6 +441,12 @@ async def validate_field_values(project_type: str, items: list[tuple[str, str]],
 - 初始化改造前后，可以快速对比 config 差异
 - 下拉列表和创建校验依赖的 config，可以单独导出检查，不再手工翻长 CSV
 
+这块和本轮目标直接对应：
+
+- 字段级配置调整后，可以直接导出为 `config.csv`
+- 初始化改造前后，可以快速对比 config 差异
+- 下拉列表和创建校验依赖的 config，可以单独导出检查，不再手工翻长 CSV
+
 建议目录：
 
 - `scripts/initdata/json_config/`
@@ -507,6 +541,12 @@ async def validate_field_values(project_type: str, items: list[tuple[str, str]],
 - 创建：这个字段 create service 当前怎么校验，迁移后改成哪个 `validate_field_value()` 调用
 - 下拉：这个字段前端当前通过哪个接口取值，迁移后改成哪个 config key 统一返回
 
+对本轮来说，每个领域文档都至少要把下面 3 条链路写清楚：
+
+- 初始化：这个字段初始化时从哪里取候选项，迁移后改成哪个 config key
+- 创建：这个字段 create service 当前怎么校验，迁移后改成哪个 `validate_field_value()` 调用
+- 下拉：这个字段前端当前通过哪个接口取值，迁移后改成哪个 config key 统一返回
+
 ### 8.4 必须完整对齐集团侧 `enum_config`
 
 领域梳理时，不能只挑 depm 里已经处理过的字段，也不能只挑“看起来最容易改”的字段。
@@ -526,6 +566,7 @@ async def validate_field_values(project_type: str, items: list[tuple[str, str]],
 
 ## 9. 实施步骤
 
+### 第一阶段：公共能力
 ### 第一阶段：公共能力
 
 - 明确字段级配置固定 JSON 结构
@@ -549,6 +590,7 @@ async def validate_field_values(project_type: str, items: list[tuple[str, str]],
 - 把当前分散在 service 内的硬编码白名单逐步迁到 config 工具
 - 保留真正应该继续存在的代码 enum，不把固定语义状态误迁到 config
 
+### 第四阶段：下拉列表改造
 ### 第四阶段：下拉列表改造
 
 - 梳理 code 类下拉接口
@@ -558,6 +600,16 @@ async def validate_field_values(project_type: str, items: list[tuple[str, str]],
 
 ### 第五阶段：清理和测试
 
+- 删除废弃 enum 和废弃代码字典
+- 删除不再适合作为真源的 dict 依赖
+- 补 service 层集成测试和初始化测试
+- 梳理 code 类下拉接口
+- 下拉统一改成通过 config 工具返回
+- 少量仍写死的下拉改为动态获取
+- 保证前端下拉、初始化候选项、create 校验三者同源
+
+### 第五阶段：清理和测试
+
 - 删除废弃 enum 和废弃代码字典
 - 删除不再适合作为真源的 dict 依赖
 - 补 service 层集成测试和初始化测试
@@ -572,6 +624,7 @@ async def validate_field_values(project_type: str, items: list[tuple[str, str]],
 - 一套 JSON / CSV / DB 三者之间的转换与维护规范
 - 一组领域级重构文档
 - 一组初始化 / 下拉 / create 的 service 层集成测试
+- 一组初始化 / 下拉 / create 的 service 层集成测试
 
 判断本次重构是否成功的标准不是“历史实现全部统一”，而是：
 
@@ -607,6 +660,38 @@ async def validate_field_values(project_type: str, items: list[tuple[str, str]],
 
 ### 11.4 测试组织方式
 
+- 测试代码写在 `tests/` 下
+- 优先写 service 层集成测试，不在项目根目录放临时脚本
+- 如果需要初始化测试数据，应复用现有测试体系，不改 `schemas/`、不改 `filtered_datasource/`
+- 前端下拉、初始化、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/`