# shop-account-management Specification

## Purpose
TBD - created by archiving change add-shop-account-management. Update Purpose after archive.
## Requirements
### Requirement: 代理商账号分页列表查询

系统 SHALL 提供代理商账号分页列表查询功能，支持按店铺ID和账号名称过滤（均为可选条件），返回账号基本信息。

#### Scenario: 查询指定店铺的账号列表

- **WHEN** 用户传入店铺ID查询参数（不传账号名称）
- **THEN** 返回该店铺的所有账号（user_type=3 且 shop_id=指定店铺ID）
- **AND** 包含分页信息（总数、当前页、每页数量）
- **AND** 每条记录包含：账号名称（username）、手机号、创建时间

#### Scenario: 按账号名称模糊查询

- **WHEN** 用户传入账号名称查询参数（不传店铺ID）
- **THEN** 返回账号名称包含该关键字的所有代理商账号（user_type=3）
- **AND** 使用 LIKE 模糊匹配
- **AND** 支持分页

#### Scenario: 组合条件查询

- **WHEN** 用户同时传入店铺ID和账号名称查询参数
- **THEN** 返回同时满足两个条件的账号
- **AND** 使用 AND 逻辑组合条件
- **AND** shop_id = 指定店铺ID AND username LIKE '%关键字%'

#### Scenario: 查询所有代理商账号（无过滤条件）

- **WHEN** 用户不传任何查询条件（店铺ID和账号名称都为空）
- **AND** 当前用户是平台管理员
- **THEN** 返回所有代理商账号（user_type=3）
- **AND** 支持分页

#### Scenario: 数据权限过滤

- **WHEN** 代理账号访问账号列表（无论是否传查询条件）
- **THEN** 通过 GORM Callback 自动过滤
- **AND** 只返回当前店铺及下级店铺的账号
- **AND** 在数据权限过滤的基础上，再应用用户传入的查询条件

#### Scenario: 空结果处理

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

### Requirement: 代理商账号新增

系统 SHALL 提供代理商账号新增功能，支持创建绑定到指定店铺的代理账号。

#### Scenario: 新增代理商账号

- **WHEN** 用户提交新增账号请求
- **AND** 提供账号名称、手机号、登录密码、关联店铺ID
- **THEN** 验证店铺存在且未删除
- **AND** 验证手机号唯一性（未被使用）
- **AND** 验证账号名称唯一性（未被使用）
- **AND** 密码使用 bcrypt 加密
- **AND** 创建账号（user_type=3，shop_id=指定店铺ID）
- **AND** 状态默认为启用（status=1）
- **AND** 返回新创建的账号信息（不包含密码）

#### Scenario: 手机号已存在

- **WHEN** 用户提交的手机号已被使用
- **THEN** 返回错误码 2002（手机号已存在）
- **AND** HTTP 状态码 400

#### Scenario: 账号名称已存在

- **WHEN** 用户提交的账号名称已被使用
- **THEN** 返回错误码 2001（用户名已存在）
- **AND** HTTP 状态码 400

#### Scenario: 关联店铺不存在

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

### Requirement: 代理商账号编辑

系统 SHALL 提供代理商账号编辑功能，支持更新账号名称，但不允许修改密码和手机号。

#### Scenario: 更新账号名称

- **WHEN** 用户提交编辑账号请求（更新账号名称）
- **THEN** 验证账号存在且未删除
- **AND** 验证新账号名称唯一性（如果修改）
- **AND** 更新账号名称
- **AND** 更新 updater 字段为当前用户ID
- **AND** 返回更新后的账号信息

#### Scenario: 不允许修改手机号

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

#### Scenario: 不允许修改密码

- **WHEN** 编辑请求中包含密码字段
- **THEN** 忽略该字段
- **AND** 不更新密码
- **AND** 密码修改需通过专用接口

#### Scenario: 编辑不存在的账号

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

### Requirement: 代理商账号密码修改

系统 SHALL 提供代理商账号密码修改功能，支持管理员重置密码，不需要验证旧密码。

#### Scenario: 管理员重置密码

- **WHEN** 管理员提交密码修改请求
- **AND** 提供新密码
- **THEN** 验证账号存在且未删除
- **AND** 验证新密码格式（8-32位）
- **AND** 使用 bcrypt 加密新密码
- **AND** 更新账号密码
- **AND** 更新 updater 字段为当前用户ID
- **AND** 返回成功响应

#### Scenario: 新密码格式验证

- **WHEN** 用户提交的新密码不符合要求（长度不在8-32位）
- **THEN** 返回参数验证错误
- **AND** HTTP 状态码 400

#### Scenario: 修改不存在账号的密码

- **WHEN** 用户尝试修改不存在或已删除账号的密码
- **THEN** 返回错误码 2101（账号不存在）
- **AND** HTTP 状态码 404

### Requirement: 代理商账号启用/禁用

系统 SHALL 提供代理商账号启用/禁用功能，支持快速切换账号状态。

#### Scenario: 启用账号

- **WHEN** 管理员提交启用账号请求
- **THEN** 验证账号存在且未删除
- **AND** 更新账号状态为 1（启用）
- **AND** 更新 updater 字段为当前用户ID
- **AND** 返回成功响应

#### Scenario: 禁用账号

- **WHEN** 管理员提交禁用账号请求
- **THEN** 验证账号存在且未删除
- **AND** 更新账号状态为 0（禁用）
- **AND** 更新 updater 字段为当前用户ID
- **AND** 返回成功响应

#### Scenario: 禁用后的账号无法登录

- **WHEN** 账号状态为禁用（status=0）
- **AND** 用户尝试使用该账号登录
- **THEN** 登录失败
- **AND** 返回账号已禁用错误

#### Scenario: 操作不存在的账号

- **WHEN** 用户尝试启用/禁用不存在或已删除的账号
- **THEN** 返回错误码 2101（账号不存在）
- **AND** HTTP 状态码 404