ecm_sync_system/docs/enum_refactor/project.md

Project 领域重构指南

1. 范围

本文档只做 Project 领域的项目侧梳理。

必须覆盖两类字段：

• 集团侧 enum_config 对应到 Project 的字段：project_type、project_subtype、syxs、status
• depm 本地已经做成 enum / 类 enum，或者已经承担初始化、创建校验、业务分支职责的字段：progress_type、key_constraints、build_methods

本文重点只回答四件事：

• 当前有几种实现
• 模型层怎么存
• 是否真的用到了
• 创建、校验、初始化时怎么取值，以及下一步怎么改

2. 字段盘点

2.1 project_type

当前实现：

• app/common/enums.py 有一套 ProjectType
• app/modules/project/enums.py 又有一套 ProjectType
• Project 模型里是 String
• ProjectCreate / ProjectUpdate 里是 str

当前使用：

• ProjectService.init_project_data) 用它作为初始化路由键，去取 preparation_{project_type}、production_{project_type}、power_{project_type} 等配置
• construction 模块的部分接口和工具也直接复用 ProjectType

当前问题：

• 定义重复
• 模型层不是 enum
• 创建 / 更新入口没有真正按 enum 校验

项目侧取值范围：

• 当前代码里的正式候选项是：photovoltaic、onshore_wind、offshore_wind、pumped_storage、hydropower、thermal_power、gas_turbine
• app/common/enums.py、app/modules/project/enums.py、初始化 dict_data.csv 当前三处是一致的

集团侧差异：

• 当前未看到和项目侧不同的取值项
• 这个字段目前可视为两边一致
• 但同步 schema 里的 project_type 字段当前仍写成 str，并没有直接收紧成 ProjectType

结论：

• 保留为代码 enum
• 它是核心路由字段，不迁到 field_config

2.2 project_subtype

当前实现：

• 模型里是 String
• ProjectCreate / ProjectUpdate 里是 str
• 没看到本地正式 enum

当前使用：

• 当前主要是项目主表字段
• 在 Project 模块内没看到稳定初始化使用点

当前问题：

• 没有统一候选项来源
• 没有统一校验
• 现在只是“字符串字段”

项目侧取值范围：

• 目前列不出权威范围
• 当前项目侧没有正式 enum、没有 field_config、没有 schema 白名单
• 从代码看，它现在理论上就是任意字符串

项目侧可举例范围：

• 目前只能借集团侧样例来猜测，例如光伏下可能是 centralized、distributed

集团侧差异：

• 集团侧至少给出了光伏下的两个候选项：centralized、distributed
• 项目侧目前一个正式值都没有落下来
• 其它项目类型在集团侧也基本还是空占位，所以当前只能确认“项目侧缺正式范围，集团侧只给了局部样例”
• 同步 schema 对应字段名是 sub_type，当前类型是 Optional[str]，也还没有 enum 化

困难：

• 项目侧没有正式定义源，无法从代码中反推出完整候选项集合
• 集团侧除光伏外也没有给出有效值，导致现在只能列出局部范围，不能写成全项目类型完整表

结论：

• 改为 field_config
• 建议 key：project.project_subtype

2.3 syxs

当前实现：

• 模型里是 String
• 当前 ProjectCreate / ProjectUpdate 里没有这个字段
• 没看到本地正式 enum

当前使用：

• 在 Project 模块内暂时没看到明确创建、初始化或校验使用点
• 当前更像是“模型里已有字段，但项目侧链路尚未收敛”的状态

当前问题：

• 有字段，但没有统一入口
• 没有统一候选项来源
• 没有统一校验

项目侧取值范围：

• 目前列不出权威范围
• 项目模型里有这个字段，但 Project 创建 schema 里没有该字段
• 代码中也没找到项目侧正式 enum 或统一校验入口

项目侧可举例范围：

• 当前只能参考集团侧海风场景，例如 hssy、lssy

集团侧差异：

• 集团侧至少给出了海风下的两个候选项：hssy、lssy
• 项目侧目前还没有正式范围、正式入口和正式校验
• 其它项目类型在集团侧也基本还是空占位，所以当前差异主要是“集团侧有局部定义，项目侧还没落下来”
• 同步 schema 中 syxs 当前也是 Optional[str]，还没有 enum 化

困难：

• 项目侧没有正式输入入口，也没有权威候选项定义
• 集团侧只有海风场景给了有效值，因此暂时只能列局部范围

结论：

• 改为 field_config
• 建议 key：project.syxs

2.4 status

当前实现：

• app/modules/project/enums.py 里有 ProjectStatus
• app/common/enums.py 里也有一套 ProjectStatus
• 模型里是 String
• 响应 schema 里是 str

当前使用：

• ProjectService.change_project_status() 会根据 investment_decision_date、actual_construction_date、actual_production_date、actual_full_production_date 计算并写回 status

当前问题：

• 定义重复
• 模型层不是 enum
• 当前状态值由服务逻辑推导，但接口层没有统一约束
• 当前正式状态集合必须补上 early
• 当前库里还存在 NULL，这说明状态机和历史数据都还没收口干净

项目侧取值范围：

• 目标正式值应为：early、preparation、started、partially_connected、completed
• 当前代码定义和服务推导还没有完整覆盖这 5 个值
• 当前实际数据里还存在 NULL，这应视为待清理异常值，而不是正式取值

集团侧差异：

• 项目侧最终也要纳入 early
• 因此这个字段的目标差异不是“是否要 early”，而是“项目侧何时补齐 early 并清掉 NULL”
• 同步 schema 里的 status 当前也是 Optional[str]，没有正式 enum 类型

结论：

• 保留为代码 enum
• 正式状态集合按 early、preparation、started、partially_connected、completed 收口
• NULL 不是正式值，必须通过数据修复和状态回填消除

2.5 progress_type

当前实现：

• app/common/enums.py 和 app/modules/project/enums.py 都定义了 ProgressType
• 模型里是 SQLEnum(ProgressType)
• ProjectInfoResponse 里使用 ProgressType
• ProjectCreate 里仍是 str

当前使用：

• 是 Project 主表正式字段
• project_detail_data 初始化时会写入 progress_type
• 列表筛选也会直接按它查询

当前问题：

• 定义重复
• 模型层已收紧，但创建入口还没收紧

项目侧取值范围：

• 当前正式值是：A、B、C
• app/common/enums.py、app/modules/project/enums.py、初始化 dict_data.csv 当前是一致的

集团侧差异：

• 集团侧同步 schema 中，progress_type 也是正式 enum
• 同步 schema 的取值项是：A、B、C
• 这一点和项目侧代码 enum 一致
• 当前真正的差异不在取值范围，而在项目侧创建入口仍是 str，还没有像同步 schema 一样收紧到 enum 类型

困难：

• 这个字段属于 depm 本地已枚举化字段，不是集团侧 Project 段直出字段
• 因此这里只能写“项目侧权威范围明确，集团侧暂无直连字段”

结论：

• 保留为代码 enum
• 不迁到 field_config

2.6 key_constraints

当前实现：

• app/common/enums.py 和 app/modules/project/enums.py 都定义了 KeyConstraints
• 两套定义已分叉：common 里有 OTHER，project 模块里没有
• 模型里是 SQLEnum(KeyConstraints)
• ProjectInfoResponse 里使用 KeyConstraints
• ProjectSquareUpdate 里还是 str

当前使用：

• 是 Project 主表正式字段
• project_detail_data 初始化时会和 progress_type 一起写入
• project_detail_data 审批回写时也会更新 Project 主表

当前问题：

• 定义分叉
• 主表是 enum，但部分接口入参仍是字符串
• 项目侧正式口径应保留 OTHER

项目侧取值范围：

• 项目侧正式值应为：NONE、LAND、TRANSMISSION、BOTH、OTHER
• 当前 app/common/enums.py 和初始化 dict_data.csv 已包含这 5 个值
• 当前 app/modules/project/enums.py 还少 OTHER

集团侧差异：

• 集团侧同步 schema 中，key_constraints 也是正式 enum
• 同步 schema 的取值项是：NONE、LAND、TRANSMISSION、BOTH、QT
• 项目侧正式口径保留 OTHER
• 这里需要备注的差异只有一条：集团侧用 QT，项目侧用 OTHER

结论：

• 保留为代码 enum
• 项目侧按 OTHER 收口
• 在同步和推送链路上单独备注 OTHER/QT 差异
• 同时补齐 project 模块那套缺失的 OTHER

2.7 build_methods

当前实现：

• app/modules/project/enums.py 里有 BuildMethod
• 模型里是 String
• ProjectCreate 里是 str
• 响应 schema 通过 enum_to_build_method_name 做名称映射

当前使用：

• construction 服务里确实使用了 project.build_methods
• 它会影响施工分支判断，例如 power、mixed、none、self

当前问题：

• 模型层不是 enum
• 创建入口不是 enum
• 已经参与业务分支，但没有统一校验

项目侧取值范围：

• 当前代码 enum 给出的值是：self、power、mixed、none
• construction 分支判断当前也确实在使用这 4 个值

集团侧差异：

• 集团侧同步 schema 里没有 build_methods 这个名字，对应字段是 scgc_type
• scgc_type 当前在同步 schema 里是 Optional[str]
• 目前没有看到同步 schema 中为 scgc_type 定义正式 enum

也就是说：

• 语义上两边大概率是在说同一个字段
• 但集团侧当前还没有把它收紧成正式 enum
• 因此这个字段更像“项目侧本地先有 enum，集团侧 schema 还停留在字符串字段”

困难：

• 这是项目侧本地业务字段，不是集团侧 Project 段直出字段
• 项目侧虽然已有 enum，但模型和 schema 还没完全收紧

结论：

• 保留为代码 enum
• 不迁到 field_config
• 需要把模型层和 schema 层一起收紧

3. 重点结论

• project_type 是初始化路由键，必须保留为代码 enum。
• project_subtype、syxs 是典型的按项目类型变化字段，应迁到 field_config。
• progress_type、key_constraints、build_methods 都已经在项目侧真实使用，不是可忽略字段；它们应保留为代码 enum，但当前实现没有收紧干净。
• status 也应保留为代码 enum，正式集合必须包含 early，并且要清掉历史 NULL。
• key_constraints 项目侧正式口径保留 OTHER，只需要在文档和同步链路上备注集团侧使用 QT。

4. 待修改项清单

1. 统一 ProjectType 定义，只保留一套正式 enum。
2. 统一 ProjectStatus 定义，并把 early 纳入正式状态集合。
3. 统一 ProgressType 定义，只保留一套正式 enum。
4. 统一 KeyConstraints 定义，项目侧正式保留 OTHER。
5. 将 project.project_subtype 改为字段级配置，放入 field_config。
6. 将 project.syxs 改为字段级配置，放入 field_config。
7. 为 project_type 在 schema 层增加正式 enum 校验，不再使用裸 str。
8. 为 progress_type 在创建入口增加正式 enum 校验。
9. 为 build_methods 在 schema 层增加正式 enum 校验。
10. 为 key_constraints 在仍使用字符串入参的接口上补 enum 校验。
11. 清理 Project.status 的历史 NULL 数据，并补状态回填逻辑，确保 NULL 不再出现。
12. 评估 Project 模型中的 project_type、status、build_methods 是否要收紧为数据库 enum；如果暂不收紧，也要先统一 schema 校验。
13. 为 project_subtype、syxs 增加统一读取入口：get_field_options() / validate_field_value()。
14. 明确 status 的唯一来源：是继续由 change_project_status() 推导，还是允许手动写入。

5. 推荐落地顺序

1. 先统一 ProjectType、ProgressType、KeyConstraints、ProjectStatus 的定义源。
2. 再补 schema 层校验，把 project_type、progress_type、build_methods、key_constraints 的裸字符串入口收紧。
3. 先补 status=early 和历史 NULL 清理，再把 project_subtype、syxs 迁到 field_config。

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

project 领域这轮要区分两类字段：

• 固定语义枚举：继续保留代码 enum
• 按项目类型变化的候选项：迁到 field config

6.1 初始化

Project 本身不直接批量初始化子表候选项，但 project_type 是整个初始化流程的路由键。

因此本轮在 project 领域的初始化要求是：

• project_type 继续保留代码 enum，作为 config 路由键
• project_subtype、syxs 如果进入初始化或默认值链路，应直接从 field config 读取

6.2 Create / Update 校验

这轮 project 领域要分开处理：

• project_type、status、progress_type、key_constraints、build_methods：继续按代码 enum 收紧
• project_subtype、syxs：通过新的 config 工具校验

也就是说，project 领域不是“全部配置化”，而是“固定 enum 和 field config 分流后分别收紧”。

6.3 下拉列表

当前 project 领域里：

• project_type、progress_type、key_constraints、build_methods 更适合继续由代码 enum 提供候选项
• project_subtype、syxs 后续如果提供前端下拉，应直接走 field config

本轮目标是明确边界，避免把本地固定枚举误迁到 config，也避免把按项目类型变化字段继续留成自由字符串。

6.4 清理项

project 领域本轮改造完成后，应清理：

• 重复的 enum 定义源
• 仍以裸字符串接收固定 enum 字段的入口
• status 历史 NULL 值

7. 测试关注点

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

1. project_type、progress_type、key_constraints、build_methods 的合法/非法值校验。
2. project_subtype、syxs 的 field config 读取与校验。
3. status 状态推导补齐 early 且不再产生 NULL。