增加项目侧重构文档

docs/enum_refactor/project.md

@@ -29,7 +29,7 @@
 
 当前使用：
 
-- `ProjectService._init_project_data()` 用它作为初始化路由键，去取 `preparation_{project_type}`、`production_{project_type}`、`power_{project_type}` 等配置
+- `ProjectService.init_project_data)` 用它作为初始化路由键，去取 `preparation_{project_type}`、`production_{project_type}`、`power_{project_type}` 等配置
 - construction 模块的部分接口和工具也直接复用 `ProjectType`
 
 当前问题：
@@ -164,23 +164,26 @@
 - 定义重复
 - 模型层不是 enum
 - 当前状态值由服务逻辑推导，但接口层没有统一约束
-- `early` 是否正式存在还没定
+- 当前正式状态集合必须补上 `early`
+- 当前库里还存在 `NULL`，这说明状态机和历史数据都还没收口干净
 
 项目侧取值范围：
 
-- `app/common/enums.py` 和 `app/modules/project/enums.py` 当前都只有 4 个正式值：`preparation`、`started`、`partially_connected`、`completed`
-- `ProjectService.change_project_status()` 当前实际也只会写入这 4 个值，或者写入 `None`
+- 目标正式值应为：`early`、`preparation`、`started`、`partially_connected`、`completed`
+- 当前代码定义和服务推导还没有完整覆盖这 5 个值
+- 当前实际数据里还存在 `NULL`，这应视为待清理异常值，而不是正式取值
 
 集团侧差异：
 
-- 集团侧比项目侧多一个值：`early`
-- 其余 `preparation`、`started`、`partially_connected`、`completed` 两边都能对上
+- 项目侧最终也要纳入 `early`
+- 因此这个字段的目标差异不是“是否要 early”，而是“项目侧何时补齐 early 并清掉 NULL”
 - 同步 schema 里的 `status` 当前也是 `Optional[str]`，没有正式 enum 类型
 
 结论：
 
-- 暂不拍板
-- 先确认正式状态集合，再决定保留代码 enum 还是转 `field_config`
+- 保留为代码 enum
+- 正式状态集合按 `early`、`preparation`、`started`、`partially_connected`、`completed` 收口
+- `NULL` 不是正式值，必须通过数据修复和状态回填消除
 
 ### 2.5 `progress_type`
 
@@ -244,33 +247,27 @@
 
 - 定义分叉
 - 主表是 enum，但部分接口入参仍是字符串
+- 项目侧正式口径应保留 `OTHER`
 
 项目侧取值范围：
 
-- `app/modules/project/enums.py` 当前是 4 个值：`NONE`、`LAND`、`TRANSMISSION`、`BOTH`
-- `app/common/enums.py` 和初始化 `dict_data.csv` 当前是 5 个值：`NONE`、`LAND`、`TRANSMISSION`、`BOTH`、`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`
-- 项目侧 `app/common/enums.py` + 初始化数据当前是：`NONE`、`LAND`、`TRANSMISSION`、`BOTH`、`OTHER`
-- 项目侧 `app/modules/project/enums.py` 当前是：`NONE`、`LAND`、`TRANSMISSION`、`BOTH`
-
-可见当前不是“无法对照”，而是至少存在两层明确差异：
-
-- 集团侧同步 schema 用的是 `QT`
-- 项目侧本地一处用 `OTHER`，一处甚至没有第五个值
-
-困难：
-
-- 项目侧自己就已经分叉，当前无法直接写出唯一正式范围
-- 在先统一本地定义前，任何“正式取值范围”都只能算候选，不算最终结论
+- 项目侧正式口径保留 `OTHER`
+- 这里需要备注的差异只有一条：集团侧用 `QT`，项目侧用 `OTHER`
 
 结论：
 
 - 保留为代码 enum
-- 先统一正式定义，再补 schema 校验
+- 项目侧按 `OTHER` 收口
+- 在同步和推送链路上单独备注 `OTHER/QT` 差异
+- 同时补齐 project 模块那套缺失的 `OTHER`
 
 ### 2.7 `build_methods`
 
@@ -325,28 +322,78 @@
 - `project_type` 是初始化路由键，必须保留为代码 enum。
 - `project_subtype`、`syxs` 是典型的按项目类型变化字段，应迁到 `field_config`。
 - `progress_type`、`key_constraints`、`build_methods` 都已经在项目侧真实使用，不是可忽略字段；它们应保留为代码 enum，但当前实现没有收紧干净。
-- `status` 当前最不稳定，因为它一边像固定状态，一边又还没把正式状态集合收敛清楚。
+- `status` 也应保留为代码 enum，正式集合必须包含 `early`，并且要清掉历史 `NULL`。
+- `key_constraints` 项目侧正式口径保留 `OTHER`，只需要在文档和同步链路上备注集团侧使用 `QT`。
 
 ## 4. 待修改项清单
 
 1. 统一 `ProjectType` 定义，只保留一套正式 enum。
-2. 统一 `ProjectStatus` 定义，并先确认是否正式支持 `early`。
+2. 统一 `ProjectStatus` 定义，并把 `early` 纳入正式状态集合。
 3. 统一 `ProgressType` 定义，只保留一套正式 enum。
-4. 统一 `KeyConstraints` 定义，先确定 `OTHER` 是否保留。
+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` 模型中的 `project_type`、`status`、`build_methods` 是否要收紧为数据库 enum；如果暂不收紧，也要先统一 schema 校验。
-12. 为 `project_subtype`、`syxs` 增加统一读取入口：`get_field_options()` / `validate_field_value()`。
-13. 明确 `status` 的唯一来源：是继续由 `change_project_status()` 推导，还是允许手动写入。
-14. 明确 `progress_type` / `key_constraints` 在 `project_detail_data` 链路中的正式定义源，避免主表和详情链路再各用一套。
+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. 再把 `project_subtype`、`syxs` 迁到 `field_config`。
-4. 最后处理 `status`，因为它依赖正式状态集合先收敛。
+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`。