msw/xgt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0d6efb3e4e48a4da4a8b263a3ba627db5489f6e6
xgt/docs/API_DEV.md
huacracker 4cb6d6fd20 docs: 添加AGENTS开发指南和API接口文档
2026-03-07 15:47:16 +08:00

12 KiB
Raw Blame History

XGT 效果图业务系统 - 开发接口对接文档

版本: 1.0
日期: 2026-03-07
基础URL: http://localhost:8088

一、认证接口

1.1 登录

POST /auth/login
Content-Type: application/json

请求参数:

{
  "username": "用户名",
  "password": "密码",
  "code": "验证码",
  "uuid": "验证码ID",
  "tenantId": "租户ID",
  "grantType": "password",
  "clientId": "客户端ID"
}

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "accessToken": "xxx",
    "expiresIn": 1209600,
    "refreshToken": "xxx",
    "refreshExpiresIn": 2592000,
    "tokenType": "Bearer"
  }
}

1.2 退出登录

POST /auth/logout
Authorization: Bearer <token>

响应示例:

{
  "code": 200,
  "msg": "退出成功"
}

1.3 注册

POST /auth/register
Content-Type: application/json

请求参数:

{
  "username": "用户名",
  "password": "密码",
  "nickName": "昵称",
  "phone": "手机号",
  "tenantId": "租户ID"
}

1.4 获取租户列表

GET /auth/tenant/list

响应示例:

{
  "code": 200,
  "data": {
    "tenantEnabled": true,
    "voList": [
      {
        "tenantId": "1",
        "tenantName": "默认租户",
        "domain": "localhost"
      }
    ]
  }
}

1.5 获取用户信息

GET /auth/login/info
Authorization: Bearer <token>

二、首页接口

2.1 首页欢迎

GET /

响应示例:

"欢迎使用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

请求参数:

{
  "followUserId": "被关注用户ID",
  "type": "关注类型"
}

2.7 取消关注

DELETE /delFollow
Authorization: Bearer <token>
Content-Type: application/json

请求参数:

{
  "id": "关注记录ID"
}

2.8 作品收藏

POST /AddWorks
Authorization: Bearer <token>
Content-Type: application/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>

响应示例:

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

请求参数:

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

请求参数:

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

请求参数:

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

十、通用响应格式

成功响应

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

分页响应

{
  "code": 200,
  "msg": "success",
  "rows": [],
  "total": 100
}

失败响应

{
  "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 View Git Blame Copy Permalink