增加重构文档

docs/enum_refactor/personnel.md

@@ -0,0 +1,105 @@
+# Personnel 领域重构指南
+
+## 1. 范围
+
+当前仓库里没有独立的 `personnel` 项目业务模块。
+
+最接近的本地实现是：
+
+- `app/modules/safety/models/safety_personnel_qualification.py`
+- `app/modules/safety/schemas/personnel_qualification.py`
+
+因此本文档先按“人员资质”这一真实落点梳理，而不是假设仓库里已经有独立 `personnel` 主表。
+
+当前优先关注：
+
+- `personnel_type`
+- `task_type`
+- `is_duty`
+
+## 2. 字段盘点
+
+### 2.1 `personnel_type`
+
+当前实现：
+
+- 模型里通过类常量定义两个值：`safe`、`special`
+- 模型字段本身是 `String`
+- schema 里仍是 `str`
+
+项目侧取值范围：
+
+- `safe`
+- `special`
+
+集团侧差异：
+
+- 集团侧 `enum_config.Personnel` 里并没有 `personnel_type`
+- 集团侧更像是在描述“人员/吊装设备”等资源配置编码，而不是人员资质类型
+- 当前仓库里也没有 standalone 的 sync schema 对这个领域建模
+
+结论：
+
+- 这是本地代码级 enum 字段
+- 可保留为代码 enum
+
+### 2.2 `task_type`
+
+当前实现：
+
+- 模型里通过 `PERSONNEL_TASK_TYPE` 类常量给出候选项
+- 字段本身是 `String`
+- schema 里仍是 `str`
+
+项目侧取值范围：
+
+- `电工`
+- `焊工`
+- `高空作业人员`
+- `无人机操作员`
+- `其他`
+
+集团侧差异：
+
+- 集团侧 `enum_config.Personnel` 没有这个字段
+- 当前仓库里也没有 sync schema 对应
+
+结论：
+
+- 这是本地代码级候选项字段
+- 可以保留为代码常量，但要补 schema 校验
+
+### 2.3 `is_duty`
+
+当前实现：
+
+- 模型里通过类常量定义：`1` 在场，`2` 退场
+- 字段本身是 `SmallInteger`
+- schema 里是 `int`
+
+项目侧取值范围：
+
+- `1`
+- `2`
+
+集团侧差异：
+
+- 集团侧 `enum_config.Personnel.status` 给的是 `-1`、`0`、`1`
+- 这更像资源进度状态，不是本地 `is_duty` 语义
+- 两边不是同一字段，不应强行对齐
+
+结论：
+
+- 保留为本地数值常量字段
+
+## 3. 重点结论
+
+- 当前所谓 `personnel` 领域，在本地真实落点是“人员资质”，不是集团侧 `Personnel` 那套资源配置模型。
+- 因此这里最重要的不是照抄集团侧，而是先承认两个系统的领域边界不一致。
+
+## 4. 待修改项清单
+
+1. 明确 `personnel` 在本地的正式领域名是否就是 `safety_personnel_qualification`。
+2. 为 `personnel_type` 补正式 enum/schema 校验。
+3. 为 `task_type` 补统一白名单校验。
+4. 不要把集团侧 `Personnel.code/status` 直接映射到本地 `personnel_type/is_duty`。