junhong_cmp_fiber/openspec/specs/shop-bulk-import/spec.md

shop-bulk-import Specification

Purpose

定义受控离线迁移工具从已核对的代理商 CSV 生成店铺初始事实 SQL，使维护者可以在执行前审核输入解析、目标库守卫和逐行计划，并以单事务手工执行。

Requirements

Requirement: 导入输入必须在生成 SQL 前完成全量预检

系统 SHALL 在生成 SQL 前校验 CSV 必备列、店铺名称/初始用户名/初始手机号同批唯一性、11 位手机号格式、上下级代理引用、业务员映射、默认角色、迁移操作者和稳定生成的店铺编号。上级代理必须按 CSV 的“奇成代理名称”唯一解析。

Scenario: 输入或映射错误被发现

• WHEN 工具发现任一 CSV 行、配置项或同批关系错误
• THEN 工具输出带 CSV 行号和原因的错误清单，不生成可执行导入 SQL

Scenario: 上级代理按 CSV 标识解析

• WHEN 子店铺的上级代理名称在同一 CSV 中唯一对应一个代理记录
• THEN 工具将该代理记录排在子店铺之前，并在结果清单中记录上级解析结果

Requirement: 生成的 SQL 必须在写入前校验目标库状态

系统 SHALL 在单事务 SQL 的任何店铺、账号、角色、钱包或审计写入前，校验配置指定的默认角色为启用客户角色、业务员映射为启用平台账号、迁移操作者为可用超级管理员，且目标库不存在同店铺编号、用户名或手机号的有效记录。

Scenario: 目标库冲突被发现

• WHEN 维护者执行的 SQL 发现角色、账号映射或任一目标记录冲突
• THEN SQL 以包含对应 CSV 行号和原因的错误终止，且不写入本批店铺、账号、角色、钱包或成功审计事实

Requirement: 批量导入 SQL 必须创建完整的店铺初始事实

系统 SHALL 为每个通过预检和目标库守卫的 CSV 记录创建启用的店铺、一个启用的店铺主账号、该账号和店铺的默认客户角色关联、主钱包和佣金钱包，并按配置写入平台业务员归属和成功审计。店铺默认角色必须是配置指定的启用客户角色。

Scenario: 成功导入店铺

• WHEN 维护者以单事务执行通过审核的导入 SQL
• THEN 每家店铺具有稳定生成的店铺编号、正确的上级层级和业务员归属，并拥有一个主账号、默认角色关联、主钱包、佣金钱包及成功创建审计

Scenario: SQL 中保存初始账号密码哈希

• WHEN 工具根据配置的初始密码规则生成店铺主账号 SQL
• THEN SQL 将该账号的 bcrypt 密码哈希写入数据库，结果清单、错误清单、摘要和控制台输出不包含初始密码明文

Requirement: 导入执行必须由维护者审核后以单事务手工确认

系统 SHALL 只生成 SQL 和审核产物，不直接连接或写入目标 PostgreSQL。维护者 SHALL 在审核通过后以 PostgreSQL 单事务模式执行生成的 SQL；任一记录创建失败时回滚整批。

Scenario: 仅运行生成器

• WHEN 操作者运行 Python 导入生成器
• THEN 工具仅生成审核产物和 SQL，不写入目标 PostgreSQL

Scenario: SQL 执行期间发生创建失败

• WHEN 维护者以单事务模式执行 SQL，且任一记录无法创建
• THEN PostgreSQL 回滚整批，且本批次不保留任何店铺、账号、角色关联、钱包或成功创建审计事实

Requirement: 导入结果必须可审核和重跑定位

系统 SHALL 为每次 SQL 生成输出不含明文密码的结果清单与摘要，至少包含源 CSV 行号、稳定店铺编号、店铺名称、层级、上级解析结果、业务员映射结果、计划状态和成功/失败统计。生成的 SQL、结果清单、错误清单和摘要 SHALL 使用同一批次标识以便审核和定位。

Scenario: 生成完成后审核

• WHEN 工具成功完成 SQL 生成
• THEN 操作者可通过结果清单核对每条源记录及其生成的店铺编号、层级和业务员归属，并通过摘要确认总数和待执行 SQL 文件