# shop-management Specification

## Purpose
TBD - created by archiving change add-shop-account-management. Update Purpose after archive.
## Requirements
### Requirement: 店铺分页列表查询

系统 SHALL 提供店铺分页列表查询功能，支持按店铺名称模糊查询，返回详细的店铺信息。

#### Scenario: 查询所有店铺（平台管理员）

- **WHEN** 平台管理员访问店铺列表（不传店铺名称过滤条件）
- **THEN** 返回所有未删除的店铺列表
- **AND** 包含分页信息（总数、当前页、每页数量）
- **AND** 每条记录包含：店铺名称、店铺编号、上级店铺名称、层级、联系人、联系电话、省市区（合并字段）、创建时间、创建人

#### Scenario: 按店铺名称模糊查询

- **WHEN** 用户传入店铺名称查询参数（如"华东"）
- **THEN** 返回店铺名称包含"华东"的所有店铺
- **AND** 使用 LIKE 模糊匹配
- **AND** 支持分页

#### Scenario: 代理账号查询（数据权限过滤）

- **WHEN** 代理账号访问店铺列表
- **THEN** 只返回当前店铺及所有下级店铺
- **AND** 通过 GORM Callback 自动应用过滤条件
- **AND** 支持分页

#### Scenario: 空结果处理

- **WHEN** 查询条件无匹配结果
- **THEN** 返回空数组
- **AND** 总数为 0
- **AND** HTTP 状态码 200

### Requirement: 店铺新增

系统 SHALL 提供店铺新增功能，支持完整的店铺信息录入，并自动创建店铺初始账号。

#### Scenario: 新增一级代理店铺

- **WHEN** 用户提交新增店铺请求（未填写上级店铺）
- **AND** 提供店铺名称、店铺编号、联系电话、初始密码
- **THEN** 创建店铺记录，层级设为 1
- **AND** 自动创建初始账号（用户类型=3，shop_id=新店铺ID）
- **AND** 账号手机号和登录账号使用联系电话
- **AND** 密码使用 bcrypt 加密
- **AND** 返回新创建的店铺信息

#### Scenario: 新增下级代理店铺

- **WHEN** 用户提交新增店铺请求（填写上级店铺ID）
- **THEN** 验证上级店铺存在且未删除
- **AND** 计算层级（上级层级 + 1）
- **AND** 验证层级不超过 7
- **AND** 创建店铺记录
- **AND** 自动创建初始账号

#### Scenario: 店铺编号唯一性校验

- **WHEN** 用户提交的店铺编号已存在（未删除记录）
- **THEN** 返回错误码 2101（店铺编号已存在）
- **AND** HTTP 状态码 400
- **AND** 不创建店铺记录

#### Scenario: 层级超过限制

- **WHEN** 用户尝试创建第 8 级店铺
- **THEN** 返回错误码 2102（超过最大层级限制）
- **AND** HTTP 状态码 400

#### Scenario: 联系电话必填校验

- **WHEN** 用户提交新增请求时未填写联系电话
- **THEN** 返回参数验证错误
- **AND** HTTP 状态码 400

### Requirement: 店铺编辑

系统 SHALL 提供店铺编辑功能，支持更新店铺信息，但不允许修改密码和登录账号。

#### Scenario: 更新店铺基本信息

- **WHEN** 用户提交编辑店铺请求（更新店铺名称、联系人等）
- **THEN** 验证店铺存在且未删除
- **AND** 更新允许编辑的字段
- **AND** 更新 updater 字段为当前用户ID
- **AND** 返回更新后的店铺信息

#### Scenario: 不允许修改店铺编号

- **WHEN** 编辑请求中包含店铺编号字段
- **THEN** 忽略该字段
- **AND** 不更新店铺编号

#### Scenario: 不允许修改上级店铺

- **WHEN** 编辑请求中包含上级店铺字段
- **THEN** 忽略该字段
- **AND** 不更新上级店铺和层级

#### Scenario: 编辑不存在的店铺

- **WHEN** 用户尝试编辑不存在或已删除的店铺
- **THEN** 返回错误码 2103（店铺不存在）
- **AND** HTTP 状态码 404

### Requirement: 店铺删除

系统 SHALL 提供店铺删除功能，执行软删除并同步禁用店铺下的所有账号。

#### Scenario: 删除店铺并禁用账号

- **WHEN** 用户提交删除店铺请求
- **THEN** 验证店铺存在且未删除
- **AND** 执行软删除（设置 deleted_at）
- **AND** 查询该店铺的所有账号（shop_id = 店铺ID）
- **AND** 批量更新所有账号状态为 0（禁用）
- **AND** 使用事务保证原子性
- **AND** 返回成功响应

#### Scenario: 删除不存在的店铺

- **WHEN** 用户尝试删除不存在或已删除的店铺
- **THEN** 返回错误码 2103（店铺不存在）
- **AND** HTTP 状态码 404

#### Scenario: 删除有下级店铺的店铺

- **WHEN** 用户尝试删除有下级店铺的店铺
- **THEN** 返回错误码 2104（存在下级店铺，无法删除）
- **AND** HTTP 状态码 400
- **AND** 不执行删除操作