# init_project_data 现状分析 ## 1. 范围 本文档只分析 backend 里的 `ProjectService.init_project_data)` 当前到底做了什么。 重点回答 4 个问题： - 这个函数当前创建了哪些业务数据。 - 它直接读取了哪些 `config` 和 `dict`。 - 哪些 `dict` 是真的在负责初始化，哪些只是历史残留。 - 如果把这里 `dict` 负责的部分迁到 `config`，复杂度到底高不高。 ## 2. 触发时机 `init_project_data)` 在项目审批通过后执行。 调用链是： - `ProjectService.audit_project()` - `ProjectService._audit_approval()` - `ProjectService.init_project_data)` 也就是说，这不是“创建项目主表时立即执行”的逻辑，而是“审批通过后批量灌初始化数据”的逻辑。 ## 3. 函数当前做的 6 件事 按执行顺序，当前函数会做下面 6 件事： 1. 读取当前 `project_type` 整个 category 下的全部 config。 2. 读取 6 组 dict 数据。 3. 初始化 `preparation` 里程碑节点。 4. 初始化 `production` 投产节点。 5. 初始化 `contract` 合同，并在合同初始化内部继续初始化 `contract_settlement` 和 `material`。 6. 初始化 `power` 力能配置、`construction` 施工任务、`archive` 电子档案。 注意： - 这个函数表面上不长，但它本质上是一个“项目初始化编排器”。 - 真正复杂的地方不只在它自己，而在它调用出去的各个 `init_from_*`。 ## 4. 直接读取了什么 ### 4.1 直接读取的 config 函数一开始会调用： - `config_service.get_category_config(category=project.project_type)` 这一步不是只读某一个 key，而是把当前 `project_type` 这个 category 下的全部 config 都读出来，再做： - `configs = {config_key: decoded_json}` 但在 `init_project_data)` 自己内部，真正直接用到的 config 只有 1 个： - `contract_config` 也就是说： - 直接读取：整类 config - 直接消费：只有 `contract_config` - 其余 config 在这个函数里只是被一并装进了 `configs`，并没有直接使用 ### 4.2 直接读取的 dict 函数会一次性读取 6 个 dict key： - `preparation_{project_type}` - `production_{project_type}` - `construction_contract_{project_type}` - `service_contract_{project_type}` - `material_contract_{project_type}` - `power_{project_type}` 但这 6 个 key 不是都真正被当前函数消费了。 ## 5. 哪些数据是怎么创建出来的 ### 5.1 Preparation 创建来源： - 直接使用 dict：`preparation_{project_type}` 创建方式： - 读取 dict 项的 `code`、`name` - 先删项目下旧的 `Preparation` - 再批量插入新的 `Preparation` 涉及配置数量： - `config`: 0 - `dict`: 1 组 当前种子数据条目数： - `preparation_photovoltaic`: 12 条 - `preparation_onshore_wind`: 13 条 - `preparation_offshore_wind`: 14 条 结论： - 这是最典型的“dict 直接承担初始化模板”场景。 - 结构非常简单，迁到 `config` 不复杂。 ### 5.2 Production 创建来源： - 直接使用 dict：`production_{project_type}` 创建方式： - 读取 dict 项的 `code`、`name` - 先删项目下旧的 `Production` - 再批量插入新的 `Production` 涉及配置数量： - `config`: 0 - `dict`: 1 组 当前种子数据条目数： - `production_photovoltaic`: 9 条 - `production_onshore_wind`: 9 条 - `production_offshore_wind`: 9 条 结论： - 和 `preparation` 一样，是平铺型 code/name 列表。 - 迁到 `config` 也不复杂。 ### 5.3 Contract 创建来源： - 直接使用 config：`contract_config` 创建方式： - `init_project_data)` 从 `configs["contract_config"]` 取出列表 - `ContractService.init_from_project()` 根据每项的 `code`、`name`、`contract_type` 创建合同 - 先删项目下旧合同，再批量插入新合同 后续联动： - 初始化 `contract_settlement` - 初始化 `material` 涉及配置数量： - `config`: 1 个 key - `dict`: 0 组直接参与合同创建 当前 `contract_config` 条目数： - `photovoltaic`: 21 条 - `onshore_wind`: 20 条 - `offshore_wind`: 20 条 结论： - 合同初始化本体已经是 config 驱动，不是 dict 驱动。 - 所以这里真正要迁移的不是“合同本身”，而是合同初始化后还依赖的那些配套 dict。 ### 5.4 Material 创建来源： - 不是 `init_project_data)` 直接创建。 - 它是 `contract.init_from_project()` 内部继续调用 `material.init_from_contract()` 创建。 当前来源拆分： - 合同列表来源：`contract_config` - 物资单位来源：`material_contract_{project_type}` dict 也就是说，当前 `material` 初始化其实是两段拼起来的： - 先由 `contract_config` 决定会创建哪些货物类合同 - 再由 `material_contract_*` dict 给这些物资补 `unit` 涉及配置数量： - `config`: 1 个上游 key `contract_config` - `dict`: 1 组 `material_contract_{project_type}` 当前种子数据条目数： - `material_contract_photovoltaic`: 14 条 - `material_contract_onshore_wind`: 12 条 - `material_contract_offshore_wind`: 7 条 这里有一个关键现状： - `material` 实际创建多少条，取决于 `contract_config` 里有多少 `product` 合同。 - `material_contract_*` dict 只负责补充单位和名称，不负责决定是否创建。 - 因此这两套来源当前不是同一个真源。 已看到的分叉： - 光伏 `contract_config` 里的货物类候选项和 `material_contract_photovoltaic` 并不完全一致。 - 陆风也存在类似分叉。 - 海风更明显：当前能看到 `contract_config` 已有较完整货物类合同，但 `dict` 侧条目明显更少。 结论： - `material` 不是简单的“把一个 dict 搬到 config”。 - 真正要做的是先合并“合同货物候选项”和“物资单位/展示信息”两套来源。 - 这块复杂度中等，不是最高，但已经不是平铺搬运。 ### 5.5 Power 创建来源： - 直接使用 dict：`power_{project_type}` 创建方式： - 读取 dict 项的 `code`、`name` - 统一绑定到 `contract_data.get("EPC")` - 先删项目下旧 `Power` - 再批量插入新 `Power` 涉及配置数量： - `config`: 0 - `dict`: 1 组 当前种子数据条目数： - `power_photovoltaic`: 1 条 - `power_onshore_wind`: 2 条 - `power_offshore_wind`: 2 条 结论： - 也是平铺型初始化模板，迁到 `config` 不复杂。 - 但它和合同存在一条强耦合：默认绑定 `EPC` 合同。 ### 5.6 Construction 创建来源： - `init_project_data)` 自己没有直接给施工传 dict 或 config 数据 - 只调用：`create_constructions_for_project(tenant_id, project_id)` 但施工初始化内部会继续读取： - `construction_section_config` 并依赖： - `BuildMethod` - `ConstructionTypeTree` - `ConstructionTypeMapping` 实际创建内容： - 按 `construction_section_config.sections[*].project_root_nodes` 创建项目根单位工程 - 基于这些根节点再创建主施工任务 - 对质量验收类施工继续创建施工树 - 对主施工继续自动补次级施工 涉及配置数量： - `config`: 至少 1 个 key `construction_section_config` - `dict`: 0 - 另外强依赖数据库里的施工类型树，不是简单 JSON 配置 结论： - 施工初始化本来就不是 dict 驱动，已经是 config + 类型树驱动。 - 这里真正复杂的不是“dict 要不要迁 config”，而是施工本身就已经是结构化初始化。 ### 5.7 Archive 创建来源： - 不依赖 dict - 也不依赖 `init_project_data)` 读出来的 config 当前方式： - 按 `template/{project_type}_archive.xlsx` 模板文件初始化电子档案树 涉及配置数量： - `config`: 0（对 `_init_project_data` 而言） - `dict`: 0 - 外部模板文件: 1 份 Excel 结论： - 电子档案初始化不属于这次 dict/config 收敛的核心问题。 ## 6. 这 6 组 dict 里，哪些真的在负责事情 ### 6.1 直接被 `init_project_data)` 消费的 dict - `preparation_{project_type}` - `production_{project_type}` - `power_{project_type}` 这 3 组 dict 是真的在当前函数里直接承担初始化模板职责。 ### 6.2 被 `init_project_data)` 取了，但当前函数里没有直接消费的 dict - `construction_contract_{project_type}` - `service_contract_{project_type}` - `material_contract_{project_type}` 其中： - `construction_contract_*`：当前只看到被 `init_project_data)` 取出，但没有实际使用。 - `service_contract_*`：当前也只看到被 `init_project_data)` 取出，但没有实际使用。 - `material_contract_*`：当前函数本身没用，但会在 `MaterialService.init_from_contract()` 里被重新读取一次，用于补单位。 这说明当前 `init_project_data)` 至少存在两类历史包袱： - 取了但没用的 dict key - 同一套语义在上游合同 config 和下游 material dict 之间分叉 ## 7. 把 dict 迁到 config，会不会太复杂 ### 7.1 不复杂的部分 下面 3 组迁移到 config，复杂度不高： - `preparation_{project_type}` - `production_{project_type}` - `power_{project_type}` 原因很简单： - 它们当前就是平铺的 `code/name` 列表 - 服务接口已经接受 `list[dict]` - 初始化逻辑只做“删旧 + 批量重建” - 不依赖复杂树结构，也不依赖额外业务联动 如果迁移： - `preparation`、`production` 很适合直接改成 `field_config` - `power` 更像一个小型初始化模板，也可以直接放到 config，但不一定要走 `field_config` 这个名字 ### 7.2 中等复杂的部分 `material_contract_{project_type}` 迁移到 `config`，复杂度中等。 原因不是数据量大，而是来源分叉： - 哪些货物类记录会被创建，取决于 `contract_config` - 每种物资的显示名、单位，又取决于 `material_contract_*` dict 所以这块不是“dict 搬家”，而是“先统一真源”。 更稳妥的做法是： - 先把 `contract_config` 和 `material_contract_*` 合并成一套正式结构 - 再决定是否把单位、显示名、parts 一并并到 `material.field_config` 或其它 config key ### 7.3 高复杂的部分其实不在 dict 真正复杂的初始化不是 dict，而是施工： - 它已经依赖 `construction_section_config` - 又依赖 `ConstructionTypeTree` - 又依赖 `ConstructionTypeMapping` - 还会继续生成施工树和次级施工 所以如果目标是“降低 `init_project_data` 初始化复杂度”，优先清理 dict 只能解决一部分表层问题，不能解决施工初始化本身的结构复杂度。 ## 8. 额外现状问题 ### 8.1 `init_project_data)` 读了整类 config，但只直接用了 `contract_config` 这会导致： - 函数看起来像“config 驱动” - 实际上只有合同初始化是直接 config 驱动 ### 8.2 有 3 个 dict key 在当前函数里不是实际输入 - `construction_contract_*` - `service_contract_*` - `material_contract_*` 其中前 2 个当前更像历史残留。 ### 8.3 当前只明显覆盖了 3 类项目类型的初始化种子 从现有 `dict.csv` / `config.csv` 看，当前明确有初始化种子的主要是： - `photovoltaic` - `onshore_wind` - `offshore_wind` 而 `project_type` 枚举里其实还有： - `pumped_storage` - `hydropower` - `thermal_power` - `gas_turbine` 也就是说，`project_type` 枚举范围和初始化种子覆盖范围并不一致。 ### 8.4 海风配置目前看起来不完整 当前能直接看到： - `offshore_wind` 有 `contract_config` - 也有 `preparation_*`、`production_*`、`power_*`、`material_contract_*` dict 但当前 `config.csv` 里没看到海风的： - `construction_section_config` - `construction_node_config` - `material_types` - `supply_chain_group` 这意味着海风初始化链路当前很可能并不完整，至少配置层不齐。 ## 9. 结论 可以把 `init_project_data)` 当前的配置来源，拆成 4 类理解： 1. 纯 dict 初始化：`preparation`、`production`、`power` 2. 纯 config 初始化：`contract` 3. config + dict 混合初始化：`material` 4. config + 类型树 + 模板文件初始化：`construction`、`archive` 所以“把这里 dict 负责的东西迁到 config 会不会太复杂”的答案不是一个统一结论： - `preparation`、`production`、`power`：不复杂，可以迁。 - `material_contract`：中等复杂，先统一真源再迁。 - `construction`：复杂点不在 dict，本来就不是 dict 驱动。 ## 10. 建议落地顺序 1. 先把 `init_project_data)` 里“取了但没直接用”的 `construction_contract_*`、`service_contract_*` 从函数里清出来，确认是否还能删掉。 2. 再把 `preparation_{project_type}`、`production_{project_type}`、`power_{project_type}` 迁到 config。 3. 再处理 `material_contract_*`，但前提是先统一 `contract_config` 和 material 初始化所需的单位/展示信息来源。 4. 施工初始化不要和这批 dict 迁移混做，单独处理。 ## 10.1 按本轮改造目标，初始化链路具体要改什么 如果把这次目标收敛成“初始化统一走配置工具”，那么 `init_project_data)` 不应该再只是分析对象，而是明确要往下面的形态改。 ### A. 保留并整理的 config 初始化链路应继续保留并整理这几类 config： - `contract_config`：合同初始化候选项 - `construction_section_config`：施工区域 / 单位工程 / 任务入口配置 - `material_types`：物资类型、展示名、单位、parts 等字段配置 - 后续新增的字段级配置 key，例如： - `preparation.code` - `production.code` - `power.code` 这里的关键不是 config 数量多少，而是把“初始化真的要用的候选项”收口到 config 工具统一读取。 ### B. 应从 dict 迁出的初始化候选项 下面这几类当前属于平铺型初始化模板，适合迁出 dict： - `preparation_{project_type}` - `production_{project_type}` - `power_{project_type}` 迁移后的目标形态是： - `init_project_data)` 不再直接读这些 dict key - 改由 `ConfigService.get_field_options()` 或等价工具读取字段候选项 - service 仍只负责“删旧 + 批量重建”，不再关心候选项来自 dict 还是 config ### C. 应去掉的不适当 dict 用法 本轮最典型的不适当 dict 用法是： - `material_contract_{project_type}` 用 `remark` 存物资单位 这类做法的问题不是“它现在不能工作”，而是： - 含义不显式 - 初始化、创建、下拉三条链路都没法自然共用 - 后续导出 CSV / 校验时也不容易发现结构错误 迁移方向应是： - 把 `unit`、`label`、`parts` 等字段并回正式 config 结构 - 不再让单位这类业务字段挂在 dict `remark` 上 ### D. `init_project_data)` 迁移后的读取原则 迁移后，`init_project_data)` 本身应只做 2 件事： - 找到当前项目类型下所需的候选项配置 - 把候选项列表传给各领域初始化 service 它不应该继续承担： - 现场拼 JSON 结构 - 自己手工区分 dict / config / remark - 同时取一堆历史 key 再由下游各自二次分叉读取 ### E. 初始化改造完成后的判定标准 初始化侧改造完成后，至少应满足： - `preparation`、`production`、`power` 初始化不再依赖 dict - `material` 初始化不再依赖 dict `remark` 补单位 - 初始化候选项与前端下拉、create 校验使用同一套 config 真源 - `init_project_data)` 中不再保留只读取不用的 dict key ## 11. 从接口创建视角反看这些字段是不是已经“主要 config 化” 只看 `init_project_data)`，容易得出“系统已经比较 config 驱动”的印象。 但如果再抽样看接口创建路径，会发现当前真实情况是： - 初始化层里，确实有一部分已经走 `config` - 但创建接口里，很多 enum-like 字段仍然主要靠代码常量或 service 层校验 - schema 层大多还是普通 `str`，并没有把这些候选值正式收口到统一配置来源 ### 11.1 Contract 创建 接口入参： - `ContractCreate` 里的 `contract_type`、`code` 都只是普通字符串 创建时字段来源： - `contract_type`、`code` 直接来自接口传参 - 合同名称不是前端传，而是 service 根据 `contract_code_dict` 动态拼出来 当前校验方式： - schema 层：只有长度约束，没有枚举白名单 - service 层： - `code` 必须在 `contract_code_dict` - `contract_type` 必须在 `contarct_type_dict` - `service` 合同再限制为 `JL`、`KY`、`E`、`SCYW` - `product` 合同再限制为一组硬编码产品 code 结论： - 合同初始化是 `contract_config` 驱动 - 但合同接口创建仍然主要依赖代码字典和硬编码白名单 - 这说明“初始化层已 config 化”并不等于“合同域已经完成 config 收口” ### 11.2 Material 创建 接口入参： - `MaterialCreate.material_type`、`approval_party` 也都是普通字符串 创建时字段来源： - `material_type` 直接来自接口传参 - `show_name`、`unit` 不是前端传，而是 `MaterialService.get_material_info_by_code()` 从 `contract_product_type_list` 里反查 - 创建物资时还会同步创建一个 `product` 合同，合同 code 直接复用 `material_type` 当前校验方式： - schema 层： - `material_type` 只是示例值来自 `contract_product_type_list` - `approval_party` 只有示例，没有正式白名单 - service 层： - 强校验的是 `contract_quantity > 0`、项目存在、tenant 存在 - `material_type` 本身没有显式抛错白名单 - 如果 code 不在 `contract_product_type_list`，`get_material_info_by_code()` 会退回默认值 `支架/组` - 随后又会去调用合同创建，而合同创建对 `code` 有一层更严格的白名单校验 结论： - material 创建不是 config 驱动，而是代码常量驱动 - 而且 `material_type` 的直接校验位置并不清晰，存在“本服务默认值兜底，合同服务再拦截”的现状 - 这正是还需要整理 config/真源的证据，不适合直接认为已经收口完成 ### 11.3 Construction 创建 接口入参： - `ConstructionCreate.section_type_code`、`section_sub_type_code`、`type_id` 都是普通字符串 创建时字段来源： - `section_type_code`、`section_sub_type_code`、`type_id` 直接来自接口传参 - `section_type_name`、`section_sub_type_name`、`task_code`、`task_type` 则由 service 根据配置和类型树反查生成 当前校验方式： - schema 层：只有字符串长度和数值范围，没有枚举白名单 - service 层： - `section_type_code` 必须存在于 `construction_section_config` - `section_sub_type_code` 必须能映射到统一类型节点 - `type_id` 必须能映射到施工类型树节点 - `SCDW` 分支还会单独校验专用任务编码列表 结论： - 施工创建是这 3 个抽样域里最接近“配置/类型树驱动”的 - 但即便如此，接口 schema 本身仍未把候选值正式声明出来，真正校验仍落在 service 里 ### 11.4 总判断 如果只问“初始化层面能不能看出 enum_config 类字段怎么来的”，答案是： - 能看出一部分。 - `preparation`、`production`、`power` 明显还来自 dict。 - `contract` 初始化候选项明显来自 `contract_config`。 - `material` 初始化候选项来自 `contract_config`，单位补充来自 `material_contract_*` dict。 - `construction` 初始化候选项来自 config + 类型树。 但如果进一步问“那是不是已经主要用 config 写了，所以没必要再整理 config”，答案是否定的。 原因是当前系统仍然存在 3 个没有收口的问题： - 初始化来源和接口创建来源不是同一套真源。 - schema 层没有把这些字段正式建模成受控候选值。 - service 层仍保留大量代码字典、硬编码白名单和默认兜底。 所以现在做 config 整理仍然有必要，而且必要性不在“把所有东西都搬到 config”，而在： - 明确每个字段的唯一真源 - 消除 dict/config/代码常量三头并存 - 让初始化和接口创建共用同一套候选值与校验逻辑 ## 12. 前端下拉选项当前是通过什么路径返回的 除了创建接口本身，前端通常会先调一些 list 接口拿可选项。 这部分如果和初始化来源不一致，就会出现： - 初始化能创建出来的值，不一定和前端可选项完全一致 - 前端下拉看到的值，也不一定就是创建 service 实际校验使用的那套真源 下面按合同、物资、施工 3 类抽样。 ### 12.1 Contract 的前端下拉路径 当前相关接口主要有： - `/contract/type/list` - `/contract/sub-type/list` 返回路径： - `router -> ContractService.get_contract_type_list()` - `router -> ContractService.get_sub_type_list(contract_type)` 数据来源： - `get_contract_type_list()` 直接读代码里的 `contarct_type_dict` - `get_sub_type_list()` 先根据传入 `contract_type` 选一组硬编码 `filter_key_list` - 再去代码里的 `contract_code_dict` 组装返回值 和初始化是否一致： - 不一致。 - 初始化合同候选项来自 `contract_config`。 - 但前端拿到的合同类型/子类型下拉，来自代码字典和硬编码列表。 这意味着： - 前端创建合同时看到的 code/type 候选，不是直接从初始化同源配置拿出来的。 - 如果未来 `contract_config` 改了，但代码字典没改，就会分叉。 ### 12.2 Material 的前端下拉路径 当前至少有两条相关路径： - `/material/material-types` - `/material-detail/contract-product-type/list` 第一条路径：`/material/material-types` - `router` 先根据 `project_id` 查项目类型 - 再调用 `config_service.get_config_json(project.project_type, "material_types")` - 返回 `material_types` 里的 `label/value` 它的数据来源是： - config：`material_types` 第二条路径：`/material-detail/contract-product-type/list` - `router -> MaterialDetailService.get_material_part_options()` - service 内部同样会先读项目的 `material_types` config - 再按当前 material 的 `material_type` 找到对应 kit 和 parts 它的数据来源也是： - config：`material_types` 但同时，物资模块里还保留了老的代码常量路径： - `MaterialService.get_material_info_by_code()` 直接读 `contract_product_type_list` - `MaterialDetailService.get_kit_options()` 也直接读 `contract_product_type_list` 和初始化是否一致： - 也不一致。 - 前端下拉主要已经走 `material_types` config。 - 但初始化物资时，候选项来源还是 `contract_config`，单位来源还是 `material_contract_*` dict。 - 而创建 service 内部补 `show_name/unit` 时，又还在读代码常量 `contract_product_type_list`。 这是当前分叉最明显的一类： - 前端选项：config - 初始化来源：config + dict - 创建补充逻辑：代码常量 ### 12.3 Construction 的前端下拉路径 当前相关接口主要有： - `/construction/section/type/list` - `/construction/section/sub/type/list` - `/construction/task/type/list` 返回路径： - `router -> ConstructionService.get_section_type_list(project_type)` - `router -> ConstructionService.get_section_sub_type_list(section_type_code, project_type)` - `router -> ConstructionService.get_task_type_list(section_type_code, section_sub_type_code, project_type)` 数据来源： - `section_type_list` 通过 `config_helper.section_type_id_dict()` 读取 `construction_section_config` - `section_sub_type_list` 通过 `config_helper.section_type_project_root_node_mapping()` 读取 `construction_section_config.project_root_nodes` - `task_type_list` 则继续基于 `construction_section_config` 和 `ConstructionTypeTree` 生成 和初始化是否一致： - 基本一致。 - 施工初始化本来就是 `construction_section_config + 类型树` 驱动。 - 前端下拉接口也是同一条配置/类型树路径。 所以施工是目前 3 类里最接近“初始化与前端下拉同源”的。 ### 12.4 总结 从前端下拉接口角度看，当前 3 类字段的真实状态可以概括成： 1. Contract：前端下拉走代码字典，和初始化 `contract_config` 不一致。 2. Material：前端下拉主要走 `material_types` config，但初始化和创建内部仍分别依赖 `contract_config`、`material_contract_*` dict、`contract_product_type_list` 代码常量，分叉最严重。 3. Construction：前端下拉和初始化都主要走 `construction_section_config + 类型树`，相对一致。 所以如果后续要做收口，优先级也比较明确： - 合同：先统一 `contract_config` 与前端 `type/sub-type list`。 - 物资：先统一 `material_types`、`contract_config`、`material_contract_*`、`contract_product_type_list` 四套来源。 - 施工：优先补 schema/创建校验与配置同源，配置来源本身相对已经收敛。