ecm_sync_system/docs/enum_refactor/preparation.md

Preparation 领域重构指南

1. 范围

本文档对应 backend 的 preparation 里程碑节点表。

当前优先关注：

• preparation.code
• preparation.approval_status
• preparation.is_exist

2. 字段盘点

2.1 code

当前实现：

• 模型里是 String
• 没有本地 enum 类
• 项目初始化时，节点集合来自 preparation_{project_type} 字典数据
• 同步 schema project_extensions/preparation.py 里也是 str

项目侧取值范围：

• 当前无法从单一代码 enum 列出完整范围
• 已知典型值包括：JSZB、HZBA、KYNS、TZJC、YDYS、LCPF、YDPF、JRPF、HPPF、SGXK、SBPF

集团侧差异：

• 集团侧 enum_config.Preparation.code 已明确把该字段作为按项目类型变化的正式候选项
• 本地当前仍主要靠初始化字典/字符串承载

结论：

• 更适合迁到 field_config
• 不应继续只靠初始化字典和自由字符串

2.2 approval_status

当前实现：

• backend 依赖 ApprovalMixin
• 本地 PreparationApproval schema 仍使用 int
• 同步 schema PreparationDetail 里是 Optional[str]

项目侧取值范围：

• 当前本地未在 preparation 模块中沉成独立 enum

集团侧差异：

• 同步 schema 有字段，但没有正式 enum

结论：

• 应统一接入通用审批状态体系

2.3 is_exist

当前实现：

• 模型里是 Boolean
• backend 和 sync schema 均有该字段

项目侧取值范围：

• true
• false

集团侧差异：

• 当前没看到 enum_config 对这个字段给出候选项

结论：

• 保持布尔字段即可

3. 重点结论

• preparation.code 是标准的初始化候选项字段，最适合迁到 field_config。
• approval_status 不需要在本领域单独发明枚举，应直接接入通用审批体系。
• is_exist 是布尔存在性字段，不在本轮字段级配置重点内。

4. 待修改项清单

1. 将 preparation.code 正式迁到 field_config。
2. 区分“节点编码范围”与“审批状态/存在性”这两类字段，不要混在一个配置源里。
3. 将 approval_status 接入通用审批状态定义。

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

preparation 属于本轮最适合先收口的一类：

• 初始化平铺
• code 字段明确
• 旧代码里已经出现多份硬编码映射

5.1 初始化

当前 preparation 初始化直接来自 preparation_{project_type} dict。

同时本地还存在：

• PreparationCode enum
• name_to_code
• dict_to_preparation_code_name
• list_to_preparation_code_name

本轮目标是：

• 把 preparation.code 迁到 field config
• 初始化改成通过 config 工具读取候选项再批量创建
• 不再依赖 dict 作为初始化真源

5.2 Create 校验

当前 PreparationCreate / PreparationService 没有统一的 code 白名单校验入口。

本轮目标是：

• 在 create / update 对应的 service 入口开头，基于 config 校验 preparation.code
• 不再新增本地 code 白名单或名称反查表来兜底

5.3 下拉列表

preparation 当前没有单独的“节点编码下拉接口”，前端更多拿的是项目实例列表 /preparation/list。

这轮文档上的要求是：

• 如果后续需要独立 code 候选项下拉，应直接从 preparation.code field config 返回
• 不再把 list_to_preparation_code_name 当成前端下拉真源

5.4 清理项

preparation 领域本轮改造完成后，应优先清理：

• preparation_{project_type} dict 的初始化真源职责
• PreparationCode 相关重复映射表
• 列表排序里写死的 sort_code

排序如果仍需要固定顺序，应迁到 field config 的附属字段中表达，例如 weight 或 sort。

6. 测试关注点

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

1. 初始化：项目初始化时生成的节点是否来自目标 field config。
2. Create / Update：合法 code 可以写入，非法 code 明确报错。
3. 列表：项目实例列表顺序是否来自配置顺序，而不是硬编码 sort_code。