junhong_cmp_fiber/docs/shop-management/使用指南.md

# 商户管理模块 - 使用指南

## 概述

商户管理模块提供了完整的商户（Shop）和商户账号（ShopAccount）管理功能，支持商户的创建、更新、删除、查询，以及商户账号的全生命周期管理。

## 核心功能

### 1. 商户管理
- **创建商户**：创建新商户的同时自动创建一个初始坐席账号
- **查询商户**：支持分页查询、模糊搜索、状态筛选
- **更新商户**：更新商户基本信息（名称、编码、等级、状态等）
- **删除商户**：软删除商户，同时批量禁用所有关联的商户账号

### 2. 商户账号管理
- **创建账号**：为商户创建新的坐席账号
- **查询账号**：支持分页查询、按商户筛选、状态筛选
- **更新账号**：更新账号用户名（手机号和密码不可通过此接口修改）
- **重置密码**：管理员为账号重置密码（无需原密码）
- **启用/禁用账号**：控制账号的启用状态

## 业务规则

### 商户规则
1. **商户编码唯一性**：商户编码（ShopCode）必须全局唯一
2. **商户等级**：等级范围为 1-7，表示商户层级结构
3. **商户状态**：
   - `1` - 正常
   - `2` - 禁用
4. **关联删除**：删除商户时，所有关联的商户账号将被批量禁用（不删除）

### 商户账号规则
1. **账号类型**：所有商户账号的用户类型固定为 `3`（坐席/Agent）
2. **初始账号**：创建商户时必须提供初始账号的用户名、手机号和密码
3. **密码安全**：密码采用 bcrypt 加密存储
4. **账号状态**：
   - `1` - 正常
   - `2` - 禁用
5. **字段限制**：
   - 更新账号时，手机号和密码不可修改（需通过专用接口）
   - 密码重置由管理员操作，无需提供原密码

### 数据权限
- 所有查询操作会根据当前登录用户的数据权限自动过滤结果
- 使用 GORM 回调机制自动处理数据权限逻辑

## API 端点

### 商户管理 API

#### 1. 查询商户列表
```http
GET /api/admin/shops
```

**查询参数**：
- `page` (int, 可选): 页码，默认 1
- `size` (int, 可选): 每页数量，默认 20，最大 100
- `name` (string, 可选): 商户名称模糊搜索
- `shop_code` (string, 可选): 商户编码精确搜索
- `status` (int, 可选): 状态筛选（1=正常，2=禁用）
- `level` (int, 可选): 等级筛选

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "测试商户",
        "shop_code": "SHOP001",
        "level": 1,
        "status": 1,
        "created_at": "2024-01-01T10:00:00Z",
        "updated_at": "2024-01-01T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20
  },
  "timestamp": 1704096000
}
```

#### 2. 创建商户
```http
POST /api/admin/shops
```

**请求体**：
```json
{
  "name": "测试商户",
  "shop_code": "SHOP001",
  "level": 1,
  "status": 1,
  "init_username": "admin",
  "init_phone": "13800138000",
  "init_password": "password123"
}
```

**字段说明**：
- `name` (string, 必填): 商户名称
- `shop_code` (string, 必填): 商户编码，全局唯一
- `level` (int, 必填): 商户等级，范围 1-7
- `status` (int, 必填): 状态（1=正常，2=禁用）
- `init_username` (string, 必填): 初始账号用户名
- `init_phone` (string, 必填): 初始账号手机号
- `init_password` (string, 必填): 初始账号密码

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 1,
    "name": "测试商户",
    "shop_code": "SHOP001",
    "level": 1,
    "status": 1,
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T10:00:00Z"
  },
  "timestamp": 1704096000
}
```

#### 3. 更新商户
```http
PUT /api/admin/shops/:id
```

**路径参数**：
- `id` (uint): 商户ID

**请求体**：
```json
{
  "name": "更新后的商户名称",
  "shop_code": "SHOP001",
  "level": 2,
  "status": 1
}
```

**响应示例**：同创建商户

#### 4. 删除商户
```http
DELETE /api/admin/shops/:id
```

**路径参数**：
- `id` (uint): 商户ID

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": null,
  "timestamp": 1704096000
}
```

**注意**：删除商户时，所有关联的商户账号将被自动禁用。

---

### 商户账号管理 API

#### 1. 查询商户账号列表
```http
GET /api/admin/shop-accounts
```

**查询参数**：
- `page` (int, 可选): 页码，默认 1
- `size` (int, 可选): 每页数量，默认 20，最大 100
- `shop_id` (uint, 可选): 商户ID筛选
- `status` (int, 可选): 状态筛选（1=正常，2=禁用）
- `username` (string, 可选): 用户名模糊搜索
- `phone` (string, 可选): 手机号模糊搜索

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "username": "admin",
        "phone": "13800138000",
        "user_type": 3,
        "status": 1,
        "shop_id": 1,
        "shop_name": "测试商户",
        "created_at": "2024-01-01T10:00:00Z",
        "updated_at": "2024-01-01T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20
  },
  "timestamp": 1704096000
}
```

#### 2. 创建商户账号
```http
POST /api/admin/shop-accounts
```

**请求体**：
```json
{
  "shop_id": 1,
  "username": "agent01",
  "phone": "13800138001",
  "password": "password123"
}
```

**字段说明**：
- `shop_id` (uint, 必填): 商户ID
- `username` (string, 必填): 用户名
- `phone` (string, 必填): 手机号
- `password` (string, 必填): 密码

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 2,
    "username": "agent01",
    "phone": "13800138001",
    "user_type": 3,
    "status": 1,
    "shop_id": 1,
    "shop_name": "测试商户",
    "created_at": "2024-01-01T10:05:00Z",
    "updated_at": "2024-01-01T10:05:00Z"
  },
  "timestamp": 1704096300
}
```

#### 3. 更新商户账号
```http
PUT /api/admin/shop-accounts/:id
```

**路径参数**：
- `id` (uint): 账号ID

**请求体**：
```json
{
  "username": "new_username"
}
```

**注意**：此接口只能更新用户名，手机号和密码不可通过此接口修改。

**响应示例**：同创建商户账号

#### 4. 重置账号密码
```http
PUT /api/admin/shop-accounts/:id/password
```

**路径参数**：
- `id` (uint): 账号ID

**请求体**：
```json
{
  "new_password": "newpassword123"
}
```

**字段说明**：
- `new_password` (string, 必填): 新密码

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": null,
  "timestamp": 1704096600
}
```

**注意**：此操作为管理员重置密码，无需提供原密码。

#### 5. 启用/禁用账号
```http
PUT /api/admin/shop-accounts/:id/status
```

**路径参数**：
- `id` (uint): 账号ID

**请求体**：
```json
{
  "status": 2
}
```

**字段说明**：
- `status` (int, 必填): 状态（1=正常，2=禁用）

**响应示例**：
```json
{
  "code": 0,
  "msg": "success",
  "data": null,
  "timestamp": 1704096900
}
```

## 错误码

| 错误码 | 说明 |
|--------|------|
| `40001` | 商户不存在 |
| `40002` | 商户编码已存在 |
| `40003` | 商户状态无效 |
| `40004` | 商户等级无效 |
| `50001` | 账号不存在 |
| `50002` | 账号已存在 |
| `50003` | 账号状态无效 |

## 使用场景示例

### 场景1：创建新商户并设置初始账号
```bash
curl -X POST http://localhost:3000/api/admin/shops \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "示例商户",
    "shop_code": "DEMO001",
    "level": 1,
    "status": 1,
    "init_username": "admin",
    "init_phone": "13800138000",
    "init_password": "admin123"
  }'
```

### 场景2：为商户添加新的坐席账号
```bash
curl -X POST http://localhost:3000/api/admin/shop-accounts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "shop_id": 1,
    "username": "agent01",
    "phone": "13800138001",
    "password": "agent123"
  }'
```

### 场景3：管理员重置账号密码
```bash
curl -X PUT http://localhost:3000/api/admin/shop-accounts/2/password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "new_password": "newpassword123"
  }'
```

### 场景4：删除商户（自动禁用关联账号）
```bash
curl -X DELETE http://localhost:3000/api/admin/shops/1 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## 注意事项

1. **认证要求**：所有接口需要在请求头中携带有效的认证 Token
2. **数据权限**：查询结果会根据当前用户的数据权限自动过滤
3. **密码安全**：
   - 密码在存储前会自动使用 bcrypt 加密
   - 建议密码长度至少 8 位，包含字母和数字
4. **关联关系**：
   - 删除商户不会删除关联账号，只会禁用
   - 禁用商户不会影响已存在账号的状态
5. **并发控制**：更新操作会检查记录是否存在，避免并发冲突
6. **日志记录**：所有操作会记录到访问日志（access.log）

## 技术实现细节

- **框架**：Fiber v2.x (HTTP)
- **ORM**：GORM v1.25.x
- **密码加密**：bcrypt
- **数据权限**：GORM 回调自动处理
- **错误处理**：统一错误码系统（pkg/errors）
- **响应格式**：统一响应格式（pkg/response）
- **分层架构**：Handler → Service → Store → Model

## 相关文档

- [API 文档](./API文档.md) - 详细的 API 接口文档
- [项目开发规范](../../AGENTS.md) - 项目整体开发规范
- [错误码定义](../../pkg/errors/codes.go) - 完整错误码列表