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

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

一、接口总览

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

总计: 25 个接口

二、认证模块接口

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

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

请求头:

Content-Type: application/json

请求参数:

{
  "code": "string" // 必填，微信 wx.login() 获取的 code
}

响应参数:

{
  "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 — 后台登录

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

请求参数:

{
  "username": "string", // 必填，用户名
  "password": "string"  // 必填，密码
}

响应参数:

{
  "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}

请求参数:

{
  "identityId": "long" // 必填，身份ID
}

响应参数:

{
  "code": 200,
  "message": "success",
  "data": {
    "token": "string" // 包含新身份信息的 Token
  }
}

错误码:

1006: 身份不存在

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

描述: 刷新当前 Token 有效期

请求头:

Authorization: Bearer {token}

响应参数:

{
  "code": 200,
  "message": "success",
  "data": {
    "token": "string"
  }
}

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

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

请求头:

Authorization: Bearer {token}

请求参数:

{
  "oldPassword": "string", // 必填，旧密码
  "newPassword": "string"  // 必填，新密码
}

响应参数:

{
  "code": 200,
  "message": "success",
  "data": null
}

错误码:

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

三、用户模块接口

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

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

请求头:

Authorization: Bearer {token}

响应参数:

{
  "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}

请求参数:

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

响应参数:

{
  "code": 200,
  "message": "success",
  "data": null
}

错误码:

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

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

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

请求头:

Authorization: Bearer {token}

请求参数:

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

响应参数:

{
  "code": 200,
  "message": "success",
  "data": {
    "identityId": "long"
  }
}

错误码:

1012: 用户已有该身份

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

描述: 管理员创建新用户

请求头:

Authorization: Bearer {token}

请求参数:

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

响应参数:

{
  "code": 200,
  "message": "success",
  "data": {
    "userId": "long"
  }
}

错误码:

1013: 手机号已注册

四、系统管理接口

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

描述: 获取系统角色列表

请求头:

Authorization: Bearer {token}

响应参数:

{
  "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}

响应参数:

{
  "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}

请求参数:

{
  "permissionIds": ["long"] // 权限ID列表
}

响应参数:

{
  "code": 200,
  "message": "success",
  "data": null
}

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

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

请求头:

Authorization: Bearer {token}

请求参数:

?page=1&pageSize=10&keyword=string

响应参数:

{
  "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}

请求参数:

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

响应参数:

{
  "code": 200,
  "message": "success",
  "data": {
    "accountId": "long"
  }
}

错误码:

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

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

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

请求头:

Authorization: Bearer {token}

请求参数:

?dictType=string

响应参数:

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "long",
      "dictType": "string",
      "dictCode": "string",
      "dictName": "string",
      "sortOrder": "int"
    }
  ]
}

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

描述: 新增字典项

请求头:

Authorization: Bearer {token}

请求参数:

{
  "dictType": "string",  // 必填，字典类型
  "dictCode": "string",  // 必填，字典编码
  "dictName": "string",  // 必填，字典名称
  "sortOrder": "int"     // 排序号
}

响应参数:

{
  "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

响应参数:

{
  "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

响应参数:

{
  "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}

请求参数:

{
  "action": "string", // 必填，APPROVE/REJECT
  "reason": "string"  // 驳回时必填
}

响应参数:

{
  "code": 200,
  "message": "success",
  "data": null
}

错误码:

1019: 审核记录不存在
1020: 驳回原因不能为空

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

描述: 获取审核详情

请求头:

Authorization: Bearer {token}

响应参数:

{
  "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}

响应参数:

{
  "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}

响应参数:

{
  "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}

响应参数:

{
  "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}

响应参数:

{
  "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}

响应参数:

{
  "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

api-definition.md 14 KB Historie Surový

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

一、接口总览

二、认证模块接口

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

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

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

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

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

三、用户模块接口

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

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

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

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

四、系统管理接口

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

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

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

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

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

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

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

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

五、审核模块接口

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

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

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

六、首页模块接口

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

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

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

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

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

七、接口统计

api-definition.md 14 KB

Historie Surový