docs: 添加AGENTS开发指南和API接口文档
This commit is contained in:
huacracker
789
docs/API_DEV.md
Normal file
789
docs/API_DEV.md
Normal file
@@ -0,0 +1,789 @@
|
||||
# XGT 效果图业务系统 - 开发接口对接文档
|
||||
|
||||
**版本**: 1.0
|
||||
**日期**: 2026-03-07
|
||||
**基础URL**: `http://localhost:8088`
|
||||
|
||||
---
|
||||
|
||||
## 一、认证接口
|
||||
|
||||
### 1.1 登录
|
||||
|
||||
```
|
||||
POST /auth/login
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"username": "用户名",
|
||||
"password": "密码",
|
||||
"code": "验证码",
|
||||
"uuid": "验证码ID",
|
||||
"tenantId": "租户ID",
|
||||
"grantType": "password",
|
||||
"clientId": "客户端ID"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {
|
||||
"accessToken": "xxx",
|
||||
"expiresIn": 1209600,
|
||||
"refreshToken": "xxx",
|
||||
"refreshExpiresIn": 2592000,
|
||||
"tokenType": "Bearer"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 退出登录
|
||||
|
||||
```
|
||||
POST /auth/logout
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "退出成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 1.3 注册
|
||||
|
||||
```
|
||||
POST /auth/register
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"username": "用户名",
|
||||
"password": "密码",
|
||||
"nickName": "昵称",
|
||||
"phone": "手机号",
|
||||
"tenantId": "租户ID"
|
||||
}
|
||||
```
|
||||
|
||||
### 1.4 获取租户列表
|
||||
|
||||
```
|
||||
GET /auth/tenant/list
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"tenantEnabled": true,
|
||||
"voList": [
|
||||
{
|
||||
"tenantId": "1",
|
||||
"tenantName": "默认租户",
|
||||
"domain": "localhost"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 1.5 获取用户信息
|
||||
|
||||
```
|
||||
GET /auth/login/info
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、首页接口
|
||||
|
||||
### 2.1 首页欢迎
|
||||
|
||||
```
|
||||
GET /
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
"欢迎使用XGT后台管理框架，当前版本：v5.2.3，请通过前端地址访问。"
|
||||
```
|
||||
|
||||
### 2.2 画册列表
|
||||
|
||||
```
|
||||
GET /banner
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| pageNum | int | 页码，默认1 |
|
||||
| pageSize | int | 每页数量，默认10 |
|
||||
| title | string | 标题（模糊搜索） |
|
||||
| status | int | 状态（1启用） |
|
||||
|
||||
### 2.3 商品列表
|
||||
|
||||
```
|
||||
GET /prod
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| pageNum | int | 页码 |
|
||||
| pageSize | int | 每页数量 |
|
||||
| name | string | 商品名称 |
|
||||
| status | int | 状态 |
|
||||
|
||||
### 2.4 表现师列表
|
||||
|
||||
```
|
||||
GET /tpSysUser
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| pageNum | int | 页码 |
|
||||
| pageSize | int | 每页数量 |
|
||||
| nickName | string | 昵称 |
|
||||
| identity | int | 身份（2表现师） |
|
||||
|
||||
### 2.5 用户详情
|
||||
|
||||
```
|
||||
GET /sysUser/{id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 2.6 关注操作
|
||||
|
||||
```
|
||||
POST /AddFollow
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"followUserId": "被关注用户ID",
|
||||
"type": "关注类型"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.7 取消关注
|
||||
|
||||
```
|
||||
DELETE /delFollow
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"id": "关注记录ID"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.8 作品收藏
|
||||
|
||||
```
|
||||
POST /AddWorks
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"worksId": "作品ID",
|
||||
"type": "收藏类型"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、订单接口
|
||||
|
||||
### 3.1 订单列表（客服）
|
||||
|
||||
```
|
||||
GET /work/customer/order/list
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| pageNum | int | 页码 |
|
||||
| pageSize | int | 每页数量 |
|
||||
| orderId | string | 订单编号 |
|
||||
| kid | long | 客户ID |
|
||||
| sid | long | 客服ID |
|
||||
| state | int | 订单状态 |
|
||||
| deptId | long | 部门ID |
|
||||
| startTime | date | 开始时间 |
|
||||
| endTime | date | 结束时间 |
|
||||
|
||||
**订单状态说明**:
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| 1 | 录入订单 |
|
||||
| 2 | 上传小图 |
|
||||
| 3 | 上传大图 |
|
||||
| 4 | 已完成 |
|
||||
| 5 | 已评价 |
|
||||
|
||||
### 3.2 订单统计（客服）
|
||||
|
||||
```
|
||||
GET /work/customer/order/sum
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"data": {
|
||||
"orderCount": 100,
|
||||
"payCount": 80,
|
||||
"priceSum": 50000.00,
|
||||
"unPayCount": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 新增订单
|
||||
|
||||
```
|
||||
POST /work/customer/order
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"orderId": "订单编号(自动生成)",
|
||||
"kid": 1,
|
||||
"wid": 1,
|
||||
"style": 1,
|
||||
"space": "客厅",
|
||||
"quality": 1,
|
||||
"num": 5,
|
||||
"price": 500.00,
|
||||
"remark": "备注",
|
||||
"type": 1
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 订单派单
|
||||
|
||||
```
|
||||
POST /work/customer/order/assign
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"orderIds": [1, 2, 3],
|
||||
"userId": 100
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 取消派单
|
||||
|
||||
```
|
||||
POST /work/customer/order/cancelAssign
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| orderId | long | 订单ID |
|
||||
|
||||
### 3.6 订单支付
|
||||
|
||||
```
|
||||
POST /work/customer/order/pay
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| orderId | long | 订单ID |
|
||||
| type | int | 类型（1客户 2客服） |
|
||||
| price | BigDecimal | 支付金额 |
|
||||
|
||||
### 3.7 订单退款
|
||||
|
||||
```
|
||||
POST /work/customer/order/fallback
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| orderId | long | 订单ID |
|
||||
| type | int | 类型（1客户 2客服） |
|
||||
| price | BigDecimal | 退款金额 |
|
||||
|
||||
### 3.8 订单拆单
|
||||
|
||||
```
|
||||
POST /work/customer/order/cdOrder
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| orderId | long | 订单ID |
|
||||
| price | BigDecimal | 拆单金额 |
|
||||
|
||||
### 3.9 订单改价
|
||||
|
||||
```
|
||||
POST /work/customer/order/gjOrder
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| orderId | long | 订单ID |
|
||||
| price | BigDecimal | 新价格 |
|
||||
|
||||
### 3.10 订单详情
|
||||
|
||||
```
|
||||
GET /work/customer/order/{id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 3.11 更新订单
|
||||
|
||||
```
|
||||
PUT /work/customer/order
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
### 3.12 删除订单
|
||||
|
||||
```
|
||||
DELETE /work/customer/order/{ids}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、客户接口
|
||||
|
||||
### 4.1 客户列表
|
||||
|
||||
```
|
||||
GET /work/client/list
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| pageNum | int | 页码 |
|
||||
| pageSize | int | 每页数量 |
|
||||
| name | string | 客户名称 |
|
||||
| phone | string | 手机号 |
|
||||
|
||||
### 4.2 客户订单统计
|
||||
|
||||
```
|
||||
GET /work/client/listChart
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 4.3 客户详情
|
||||
|
||||
```
|
||||
GET /work/client/{id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 4.4 新增客户
|
||||
|
||||
```
|
||||
POST /work/client
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
```json
|
||||
{
|
||||
"name": "客户名称",
|
||||
"phone": "手机号",
|
||||
"wechat": "微信",
|
||||
"remark": "备注"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、员工接口
|
||||
|
||||
### 5.1 员工列表
|
||||
|
||||
```
|
||||
GET /work/staff/list
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 5.2 用户列表
|
||||
|
||||
```
|
||||
GET /mall/user/list
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| pageNum | int | 页码 |
|
||||
| pageSize | int | 每页数量 |
|
||||
| nickName | string | 昵称 |
|
||||
| identity | int | 身份（1管理员 2技术 3客服） |
|
||||
|
||||
---
|
||||
|
||||
## 六、微信接口
|
||||
|
||||
### 6.1 微信列表
|
||||
|
||||
```
|
||||
GET /work/wechat/list
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| pageNum | int | 页码 |
|
||||
| pageSize | int | 每页数量 |
|
||||
| code | string | 微信编号 |
|
||||
| user | string | 微信昵称 |
|
||||
| createDept | long | 所属部门 |
|
||||
|
||||
### 6.2 微信统计
|
||||
|
||||
```
|
||||
GET /work/wechat/wechatSum
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、财务接口
|
||||
|
||||
### 7.1 收款列表
|
||||
|
||||
```
|
||||
GET /work/receipt/list
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 7.2 收款统计
|
||||
|
||||
```
|
||||
GET /work/receipt/receiptSum
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 7.3 认领汇款
|
||||
|
||||
```
|
||||
POST /work/receipt/claim
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、统计接口
|
||||
|
||||
### 8.1 首页统计
|
||||
|
||||
```
|
||||
GET /indexSum
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应说明**: 根据用户身份返回不同统计
|
||||
- 表现师(identity=2): 技术相关统计
|
||||
- 客服(identity=3): 客服相关统计
|
||||
|
||||
### 8.2 客服排行榜
|
||||
|
||||
```
|
||||
GET /rankingListKF
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| pageNum | int | 页码 |
|
||||
| pageSize | int | 每页数量 |
|
||||
| type | int | 类型 |
|
||||
| startTime | date | 开始时间 |
|
||||
| endTime | date | 结束时间 |
|
||||
|
||||
### 8.3 技术排行榜
|
||||
|
||||
```
|
||||
GET /rankingListJS
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 8.4 部门排行榜
|
||||
|
||||
```
|
||||
GET /deptRankingList
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 8.5 客服数据分析（日）
|
||||
|
||||
```
|
||||
GET /kfDayList
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 8.6 微信好友分析
|
||||
|
||||
```
|
||||
GET /wxDayList
|
||||
Authorization: Bearer <token>
|
||||
GET /wxMonthList
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 8.7 技术部分图/日报
|
||||
|
||||
```
|
||||
GET /ftDayList
|
||||
Authorization: Bearer <token>
|
||||
GET /jsDayList
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 8.8 业绩统计
|
||||
|
||||
```
|
||||
POST /monthArrivedPer
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| month | string | 月份（如2024-09） |
|
||||
| deptId | long | 部门ID |
|
||||
|
||||
### 8.9 订单类型统计
|
||||
|
||||
```
|
||||
POST /monthOrderType
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 8.10 新老客户占比
|
||||
|
||||
```
|
||||
POST /newOldOrderPer
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 九、通用接口格式
|
||||
|
||||
### 列表查询
|
||||
|
||||
```
|
||||
GET /{module}/{entity}/list
|
||||
Authorization: Bearer <token>
|
||||
|
||||
Query Params:
|
||||
- pageNum: 页码
|
||||
- pageSize: 每页数量
|
||||
- 其他业务参数...
|
||||
```
|
||||
|
||||
### 详情查询
|
||||
|
||||
```
|
||||
GET /{module}/{entity}/{id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 新增
|
||||
|
||||
```
|
||||
POST /{module}/{entity}
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
Body: {业务对象}
|
||||
```
|
||||
|
||||
### 更新
|
||||
|
||||
```
|
||||
PUT /{module}/{entity}
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
|
||||
Body: {业务对象}
|
||||
```
|
||||
|
||||
### 删除
|
||||
|
||||
```
|
||||
DELETE /{module}/{entity}/{ids}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
### 导出
|
||||
|
||||
```
|
||||
POST /{module}/{entity}/export
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十、通用响应格式
|
||||
|
||||
### 成功响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
### 分页响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "success",
|
||||
"rows": [],
|
||||
"total": 100
|
||||
}
|
||||
```
|
||||
|
||||
### 失败响应
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 500,
|
||||
"msg": "操作失败",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十一、错误码说明
|
||||
|
||||
| 错误码 | 说明 |
|
||||
|--------|------|
|
||||
| 200 | 成功 |
|
||||
| 401 | 未授权 |
|
||||
| 403 | 无权限 |
|
||||
| 404 | 资源不存在 |
|
||||
| 500 | 服务器内部错误 |
|
||||
|
||||
---
|
||||
|
||||
## 十二、数据模型
|
||||
|
||||
### 订单 (tp_order)
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | Long | ID |
|
||||
| orderId | String | 订单编号 |
|
||||
| kid | Long | 客户ID |
|
||||
| wid | Long | 微信ID |
|
||||
| style | Long | 风格 |
|
||||
| space | String | 空间 |
|
||||
| quality | Long | 品质 |
|
||||
| num | Long | 图纸数量 |
|
||||
| price | BigDecimal | 订单价格 |
|
||||
| state | Integer | 订单状态 |
|
||||
| sid | Long | 客服ID |
|
||||
| bid | String | 表现师ID |
|
||||
| addTime | Date | 下单时间 |
|
||||
| finishTime | Date | 完成时间 |
|
||||
|
||||
### 客户 (tp_client)
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | Long | ID |
|
||||
| name | String | 客户名称 |
|
||||
| phone | String | 手机号 |
|
||||
| wechat | String | 微信 |
|
||||
| remark | String | 备注 |
|
||||
| createTime | Date | 创建时间 |
|
||||
|
||||
### 员工 (tp_staff)
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | Long | ID |
|
||||
| name | String | 姓名 |
|
||||
| phone | String | 手机号 |
|
||||
| deptId | Long | 部门ID |
|
||||
| identity | Integer | 身份（1管理员 2技术 3客服） |
|
||||
| status | String | 状态 |
|
||||
|
||||
### 微信 (tp_wechat)
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | Long | ID |
|
||||
| code | String | 微信编号 |
|
||||
| user | String | 微信昵称 |
|
||||
| phone | String | 手机号 |
|
||||
| deptId | Long | 部门ID |
|
||||
| createTime | Date | 创建时间 |
|
||||
Reference in New Issue
Block a user