# Change: 实现代理商（店铺）管理和代理商账号管理

## Why

当前系统已实现店铺（Shop）和账号（Account）基础模型，但缺少完整的代理商管理功能。业务需求包括：
1. 店铺（代理商）的完整生命周期管理（新增、编辑、删除、查询）
2. 店铺账号的管理（新增、编辑、密码修改、启用/禁用）
3. 店铺删除时需同步禁用所有关联账号

这是实现多级代理商体系的基础功能模块。

## What Changes

### 新增功能模块

1. **代理商（店铺）管理模块** (`shop-management`)
   - 店铺分页列表查询（支持店铺名称模糊查询，返回详细信息）
   - 店铺新增/编辑（包含地址信息、联系方式、初始密码）
   - 店铺删除（软删除，同步禁用所有关联账号）

2. **代理商账号管理模块** (`shop-account-management`)
   - 代理商账号分页列表查询（按店铺ID过滤）
   - 代理商账号新增/编辑（账号名称、手机号、密码、状态）
   - 修改密码（不需要旧密码，管理员重置场景）
   - 启用/禁用账号

### 技术实现

- 新增 Handler：`internal/handler/admin/shop.go`、`internal/handler/admin/shop_account.go`
- 新增 Service：`internal/service/shop/service.go`、`internal/service/shop_account/service.go`
- 扩展 Store：`internal/store/postgres/shop_store.go`、`internal/store/postgres/account_store.go`（新增方法）
- 新增 DTO：`internal/model/shop_dto.go`、`internal/model/shop_account_dto.go`
- 新增常量：`pkg/constants/shop.go`
- 新增错误码：`pkg/errors/codes.go`（扩展）

### 数据库变更

**无需新增表**，使用现有表：
- `tb_shop`：已存在，无需修改
- `tb_account`：已存在，无需修改

### API 端点

**店铺管理**：
- `GET /api/admin/shops` - 店铺分页列表
- `POST /api/admin/shops` - 新增店铺
- `PUT /api/admin/shops/:id` - 编辑店铺
- `DELETE /api/admin/shops/:id` - 删除店铺

**代理商账号管理**：
- `GET /api/admin/shop-accounts` - 代理商账号分页列表
- `POST /api/admin/shop-accounts` - 新增代理商账号
- `PUT /api/admin/shop-accounts/:id` - 编辑代理商账号
- `PUT /api/admin/shop-accounts/:id/password` - 修改密码
- `PUT /api/admin/shop-accounts/:id/status` - 启用/禁用账号

## Impact

### 影响的规范

- **新增 Capability**：`shop-management`（店铺管理）
- **新增 Capability**：`shop-account-management`（店铺账号管理）
- **依赖现有规范**：
  - `auth`：使用认证中间件保护端点
  - `error-handling`：使用统一错误处理
  - `data-permission`：使用数据权限过滤（代理账号只能看到自己店铺及下级）

### 影响的代码

**新增文件**（约 800 行）：
- `internal/handler/admin/shop.go`（~150 行）
- `internal/handler/admin/shop_account.go`（~150 行）
- `internal/service/shop/service.go`（~200 行）
- `internal/service/shop_account/service.go`（~150 行）
- `internal/model/shop_dto.go`（~100 行）
- `internal/model/shop_account_dto.go`（~100 行）
- `pkg/constants/shop.go`（~50 行）

**修改文件**（约 50 行）：
- `internal/store/postgres/shop_store.go`（新增 List、Delete 方法）
- `internal/store/postgres/account_store.go`（新增 GetByShopID、BulkUpdateStatus 方法）
- `pkg/errors/codes.go`（新增 4 个错误码）
- `internal/bootstrap/stores.go`、`services.go`、`handlers.go`（注册新组件）

### 兼容性

- ✅ **向后兼容**：无破坏性变更
- ✅ **数据库兼容**：无需迁移，使用现有表
- ✅ **API 兼容**：新增端点，不影响现有 API

### 风险评估

- **低风险**：功能独立，不影响现有模块
- **依赖现有**：复用已验证的认证、错误处理、数据权限机制
- **测试覆盖**：计划编写单元测试和集成测试

## Dependencies

- 依赖现有 `Shop` 和 `Account` 模型
- 依赖现有 `auth` 中间件
- 依赖现有 `error-handling` 和 `response` 包
- 依赖现有 `data-permission` 自动过滤机制

## Testing Strategy

1. **单元测试**：
   - Service 层业务逻辑（覆盖率 ≥ 90%）
   - 边界条件测试（空值、无效参数、权限校验）

2. **集成测试**：
   - 完整 API 流程测试（创建 → 查询 → 编辑 → 删除）
   - 关联关系测试（删除店铺 → 验证账号被禁用）

3. **手动测试**：
   - 分页功能测试（边界页码、空结果）
   - 数据权限测试（代理账号只能看到自己的数据）

## Documentation

- 更新 `README.md`：添加功能模块说明
- 创建 `docs/shop-management/` 目录：
  - 使用指南（API 文档）
  - 业务规则说明