# 阶段一接口定义 — 基础设施与用户体系

> 接口总数：25 个
> 覆盖功能点：20/20

---

## 一、接口总览

| 模块 | 接口数 | 说明 |
|------|--------|------|
| 认证模块 | 5 | 登录、登出、身份选择、Token刷新、密码修改 |
| 用户模块 | 4 | 用户信息、状态管理、身份绑定、创建用户 |
| 系统管理 | 8 | 角色、账号、字典、权限、操作日志 |
| 审核模块 | 3 | 审核列表、审核操作、审核详情 |
| 首页模块 | 5 | 果农/工人/客商/农资商首页、行情数据 |

**总计**: 25 个接口

---

## 二、认证模块接口

### 2.1 POST /api/wx/auth/login — 微信登录

**描述**: 小程序用户通过微信 code 登录

**请求头**:
```
Content-Type: application/json
```

**请求参数**:
```json
{
  "code": "string" // 必填，微信 wx.login() 获取的 code
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "string", // JWT Token
    "userId": "long", // 用户ID
    "identities": [ // 身份列表
      {
        "identityId": "long",
        "identityType": "string", // GROWER/WORKER/BUYER/SUPPLIER
        "identityName": "string"
      }
    ]
  }
}
```

**错误码**:
- 1001: 未找到用户信息，请联系村委会
- 1002: 微信接口调用失败

---

### 2.2 POST /api/admin/auth/login — 后台登录

**描述**: 后台管理员通过用户名密码登录

**请求参数**:
```json
{
  "username": "string", // 必填，用户名
  "password": "string"  // 必填，密码
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "string",
    "userId": "long",
    "username": "string",
    "realName": "string",
    "roleId": "long",
    "roleName": "string"
  }
}
```

**错误码**:
- 1003: 用户名或密码错误
- 1004: 账号已禁用
- 1005: 账号已锁定，请30分钟后重试

---

### 2.3 POST /api/wx/auth/select-identity — 选择身份

**描述**: 多身份用户选择当前使用的身份

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "identityId": "long" // 必填，身份ID
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "string" // 包含新身份信息的 Token
  }
}
```

**错误码**:
- 1006: 身份不存在

---

### 2.4 POST /api/wx/auth/refresh — 刷新Token

**描述**: 刷新当前 Token 有效期

**请求头**:
```
Authorization: Bearer {token}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "string"
  }
}
```

---

### 2.5 PUT /api/admin/auth/password — 修改密码

**描述**: 后台管理员修改密码

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "oldPassword": "string", // 必填，旧密码
  "newPassword": "string"  // 必填，新密码
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

**错误码**:
- 1007: 旧密码错误
- 1008: 新密码强度不足

---

## 三、用户模块接口

### 3.1 GET /api/wx/user/info — 获取用户信息

**描述**: 获取当前登录用户的基本信息

**请求头**:
```
Authorization: Bearer {token}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "userId": "long",
    "realName": "string",
    "phone": "string", // 脱敏显示：138****8888
    "identities": [
      {
        "identityId": "long",
        "identityType": "string",
        "identityName": "string"
      }
    ],
    "currentIdentity": {
      "identityId": "long",
      "identityType": "string"
    }
  }
}
```

---

### 3.2 PUT /api/admin/user/status — 修改用户状态

**描述**: 管理员修改用户账号状态

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "userId": "long",    // 必填，用户ID
  "status": "int",     // 必填，状态：0正常 1禁用 2锁定
  "lockReason": "string" // 锁定时必填
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

**错误码**:
- 1009: 用户不存在
- 1010: 不可禁用超级管理员
- 1011: 锁定原因不能为空

---

### 3.3 POST /api/admin/user/bind-identity — 绑定身份

**描述**: 管理员为用户绑定新身份

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "userId": "long",        // 必填，用户ID
  "identityType": "string", // 必填，身份类型
  "profileData": {}         // 身份详细信息（JSON）
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "identityId": "long"
  }
}
```

**错误码**:
- 1012: 用户已有该身份

---

### 3.4 POST /api/admin/user — 创建用户

**描述**: 管理员创建新用户

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "realName": "string",    // 必填，真实姓名
  "phone": "string",       // 必填，手机号
  "identityType": "string", // 必填，身份类型
  "profileData": {}         // 身份详细信息
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "userId": "long"
  }
}
```

**错误码**:
- 1013: 手机号已注册

---

## 四、系统管理接口

### 4.1 GET /api/admin/role/list — 角色列表

**描述**: 获取系统角色列表

**请求头**:
```
Authorization: Bearer {token}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "long",
      "roleName": "string",
      "roleCode": "string",
      "description": "string",
      "status": "int",
      "isSystem": "int"
    }
  ]
}
```

---

### 4.2 GET /api/admin/role/{id}/permissions — 角色权限

**描述**: 获取指定角色的权限列表

**请求头**:
```
Authorization: Bearer {token}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "long",
      "permName": "string",
      "permCode": "string",
      "permType": "string",
      "path": "string"
    }
  ]
}
```

---

### 4.3 PUT /api/admin/role/{id}/permissions — 分配权限

**描述**: 为角色分配权限

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "permissionIds": ["long"] // 权限ID列表
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

---

### 4.4 GET /api/admin/account/list — 账号列表

**描述**: 获取管理员账号列表（分页）

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```
?page=1&pageSize=10&keyword=string
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": "long",
    "page": "int",
    "pageSize": "int",
    "list": [
      {
        "id": "long",
        "username": "string",
        "realName": "string",
        "phone": "string", // 脱敏
        "roleName": "string",
        "status": "int",
        "createdAt": "string"
      }
    ]
  }
}
```

---

### 4.5 POST /api/admin/account — 创建账号

**描述**: 创建管理员账号

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "username": "string", // 必填，用户名
  "password": "string", // 必填，密码
  "realName": "string", // 必填，真实姓名
  "phone": "string",    // 必填，手机号
  "roleId": "long"      // 必填，角色ID
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "accountId": "long"
  }
}
```

**错误码**:
- 1014: 用户名已存在
- 1015: 手机号已注册
- 1016: 密码强度不足

---

### 4.6 GET /api/admin/dict/list — 字典列表

**描述**: 获取指定类型的字典列表

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```
?dictType=string
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "long",
      "dictType": "string",
      "dictCode": "string",
      "dictName": "string",
      "sortOrder": "int"
    }
  ]
}
```

---

### 4.7 POST /api/admin/dict — 新增字典项

**描述**: 新增字典项

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "dictType": "string",  // 必填，字典类型
  "dictCode": "string",  // 必填，字典编码
  "dictName": "string",  // 必填，字典名称
  "sortOrder": "int"     // 排序号
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "dictId": "long"
  }
}
```

**错误码**:
- 1017: 字典编码已存在
- 1018: 系统内置字典不可删除

---

### 4.8 GET /api/admin/operation-log/list — 操作日志列表

**描述**: 获取操作日志列表（分页）

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```
?page=1&pageSize=10&operatorId=long&startTime=string&endTime=string
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": "long",
    "page": "int",
    "pageSize": "int",
    "list": [
      {
        "id": "long",
        "operatorName": "string",
        "operationType": "string",
        "operationModule": "string",
        "operationContent": "string",
        "ipAddress": "string",
        "result": "int",
        "createdAt": "string"
      }
    ]
  }
}
```

---

## 五、审核模块接口

### 5.1 GET /api/admin/audit/list — 审核列表

**描述**: 获取审核列表（分页）

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```
?page=1&pageSize=10&targetType=string&status=string
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": "long",
    "page": "int",
    "pageSize": "int",
    "list": [
      {
        "id": "long",
        "targetType": "string",
        "targetId": "long",
        "submitterName": "string",
        "status": "string",
        "createdAt": "string"
      }
    ]
  }
}
```

---

### 5.2 PUT /api/admin/audit/{id} — 审核操作

**描述**: 执行审核操作（通过/驳回）

**请求头**:
```
Authorization: Bearer {token}
```

**请求参数**:
```json
{
  "action": "string", // 必填，APPROVE/REJECT
  "reason": "string"  // 驳回时必填
}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

**错误码**:
- 1019: 审核记录不存在
- 1020: 驳回原因不能为空

---

### 5.3 GET /api/admin/audit/{id} — 审核详情

**描述**: 获取审核详情

**请求头**:
```
Authorization: Bearer {token}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "long",
    "targetType": "string",
    "targetId": "long",
    "targetData": {}, // 审核对象的详细数据
    "submitterName": "string",
    "status": "string",
    "createdAt": "string"
  }
}
```

---

## 六、首页模块接口

### 6.1 GET /api/wx/home/grower — 果农首页

**描述**: 获取果农首页数据

**请求头**:
```
Authorization: Bearer {token}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "greeting": "string", // 问候语
    "marketPrices": [
      {
        "variety": "string",
        "priceMin": "decimal",
        "priceMax": "decimal",
        "trend": "string", // up/down/stable
        "updateTime": "string"
      }
    ],
    "quickEntries": [
      {
        "name": "string",
        "icon": "string",
        "path": "string"
      }
    ]
  }
}
```

---

### 6.2 GET /api/wx/home/worker — 工人首页

**描述**: 获取工人首页推荐招工

**请求头**:
```
Authorization: Bearer {token}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "recommendedRecruits": [
      {
        "id": "long",
        "workType": "string",
        "price": "decimal",
        "priceUnit": "string",
        "days": "int",
        "peopleCount": "int",
        "growerName": "string",
        "distance": "decimal" // 公里
      }
    ]
  }
}
```

---

### 6.3 GET /api/wx/home/buyer — 客商首页

**描述**: 获取客商首页数据

**请求头**:
```
Authorization: Bearer {token}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "marketPrices": [...],
    "recommendedGrowers": [
      {
        "identityId": "long",
        "variety": "string",
        "production": "decimal", // 斤
        "expectedPrice": "decimal",
        "orchardAddress": "string",
        "distance": "decimal"
      }
    ]
  }
}
```

---

### 6.4 GET /api/wx/home/supplier — 农资商首页

**描述**: 获取农资商首页数据

**请求头**:
```
Authorization: Bearer {token}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "shopInfo": {
      "shopName": "string",
      "mainProducts": "string",
      "productCount": "int"
    },
    "quickEntries": [
      {"name": "商品管理", "path": "/pages/product/list"},
      {"name": "订单管理", "path": "/pages/order/list"},
      {"name": "店铺设置", "path": "/pages/shop/setting"}
    ]
  }
}
```

---

### 6.5 GET /api/wx/market-price — 行情数据

**描述**: 获取今日行情数据

**请求头**:
```
Authorization: Bearer {token}
```

**响应参数**:
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "variety": "string",
      "priceMin": "decimal",
      "priceMax": "decimal",
      "trend": "string",
      "updateTime": "string"
    }
  ]
}
```

---

## 七、接口统计

| 模块 | 接口数 | 方法 |
|------|--------|------|
| 认证模块 | 5 | POST×3, PUT×1, GET×1 |
| 用户模块 | 4 | GET×1, PUT×1, POST×2 |
| 系统管理 | 8 | GET×5, POST×2, PUT×1 |
| 审核模块 | 3 | GET×2, PUT×1 |
| 首页模块 | 5 | GET×5 |
| **总计** | **25** | GET×16, POST×7, PUT×2 |