msw/xgt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 添加AGENTS开发指南和API接口文档

Browse Source
This commit is contained in:
huacracker
2026-03-07 15:47:16 +08:00
parent 2640aeb97c
commit 4cb6d6fd20
3 changed files with 1289 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
AGENTS.md Normal file
View File

@@ -0,0 +1,267 @@
# AGENTS.md - XGT Project Development Guide
## Project Overview
- **Project Name**: XGT (效果图业务系统)
- **Framework**: RuoYi-Vue-Plus (Spring Boot 3.3.5 + MyBatis-Plus)
- **Java Version**: 22
- **Build Tool**: Maven
---
## Build Commands
### Environment Setup
```bash
# Set Java 22 and Maven
export JAVA_HOME=/usr/local/opt/amazon-corretto-22.jdk/Contents/Home
export PATH=$JAVA_HOME/bin:/usr/local/Cellar/maven/3.9.12/bin:$PATH
```
### Build & Run
```bash
# Compile project
mvn clean compile -DskipTests
# Install to local repository
mvn clean install -DskipTests
# Run application (dev profile)
cd ruoyi-admin
mvn spring-boot:run -Dspring-boot.run.profiles=dev
# Run with hot reload (DevTools)
mvn spring-boot:run -Dspring-boot.run.profiles=dev
# Press Ctrl+F10 to reload changed classes
```
### Test Commands
```bash
# Run all tests
mvn test
# Run single test class
mvn test -Dtest=DemoUnitTest
# Run single test method
mvn test -Dtest=DemoUnitTest#testTest
# Run tests with specific tag (based on profile)
mvn test -Dgroups=dev
# Skip tests
mvn clean install -DskipTests
```
---
## Code Style Guidelines
### EditorConfig
The project uses `.editorconfig` for consistent formatting:
- **Indentation**: 4 spaces for Java, 2 spaces for YAML/JSON
- **Charset**: UTF-8
- **Line endings**: LF
- **Trailing whitespace**: Trimmed
### Java Conventions
#### Package & Import Organization
```java
// 1. Package declaration
package org.dromara.web.controller;
// 2. Third-party imports (alphabetical)
import cn.dev33.satoken.annotation.SaCheckPermission;
import cn.hutool.core.util.ObjectUtil;
// 3. Spring imports
import org.springframework.web.bind.annotation.*;
// 4. Project common imports
import org.dromara.common.core.domain.R;
import org.dromara.common.satoken.utils.LoginHelper;
// 5. Module imports
import org.dromara.system.domain.bo.SysUserBo;
import org.dromara.work.domain.TpOrder;
// 6. Java standard library
import java.util.List;
import java.util.Map;
```
#### Naming Conventions
| Element | Convention | Example |
|---------|------------|---------|
| Packages | lowercase | `org.dromara.work.service` |
| Classes | PascalCase | `IndexController`, `TpOrderService` |
| Methods | camelCase | `queryPageList()`, `selectById()` |
| Variables | camelCase | `loginUser`, `pageQuery` |
| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `DEFAULT_PAGE_SIZE` |
| BO/VO/DAO | PascalCase + suffix | `SysUserBo`, `TpOrderVo` |
#### Class Structure
```java
/**
* Class description
*
* @author AuthorName
*/
@RequiredArgsConstructor
@RestController
@RequestMapping("/api/path")
public class ExampleController {
// 1. Static constants (if any)
private static final String PREFIX = "prefix:";
// 2. Dependencies (private final)
private final UserService userService;
private final OrderService orderService;
// 3. Public methods (API endpoints)
@GetMapping("/list")
public R<TableDataInfo<Vo>> list(Bo bo, PageQuery query) {
return R.ok(service.queryPageList(bo, query));
}
// 4. Private methods
private void validateParams(Bo bo) {
// validation logic
}
}
```
#### Error Handling
```java
// Use R.fail() for business errors
return R.fail("Error message");
// Use try-catch for external calls
try {
result = externalService.call();
} catch (Exception e) {
log.error("Failed to call external service", e);
return R.fail("Service unavailable");
}
// Use ServiceException for framework errors
throw new ServiceException("Validation failed");
```
#### Logging
```java
// Use Lombok's @Slf4j
@Slf4j
public class ExampleService {
// Appropriate log levels
log.debug("Debug info: {}", data);
log.info("Operation completed: {}", result);
log.warn("Potential issue: {}", warning);
log.error("Error occurred", exception);
}
```
#### Database (MyBatis-Plus)
```java
// Query examples
LambdaQueryWrapper<TpOrder> wrapper = new LambdaQueryWrapper<>();
wrapper.eq(TpOrder::getStatus, 1)
.like(TpOrder::getName, keyword)
.orderByDesc(TpOrder::getCreateTime);
// Use service methods
return R.ok(service.queryPageList(bo, pageQuery));
// Pagination
PageQuery pageQuery = new PageQuery();
pageQuery.setPageNum(1);
pageQuery.setPageSize(10);
```
---
## Security Guidelines
### Sensitive Data
- **NEVER** hardcode credentials in source code
- Use environment variables or config center for secrets
- Never log passwords or sensitive information
### API Security
- Use `@SaCheckPermission` for permission control
- Use `@SaIgnore` for public endpoints
- Validate all input parameters
- Use `@RepeatSubmit` for idempotent requests
---
## Common Patterns
### REST Controller
```java
@GetMapping("/list")
public R<TableDataInfo<Vo>> list(Bo bo, PageQuery pageQuery) {
return R.ok(service.queryPageList(bo, pageQuery));
}
@PostMapping
public R<Boolean> add(@Validated @RequestBody Bo bo) {
return R.ok(service.insertByBo(bo));
}
@PutMapping
public R<Boolean> edit(@Validated @RequestBody Bo bo) {
return R.ok(service.updateByBo(bo));
}
@DeleteMapping("/{id}")
public R<Boolean> remove(@PathVariable Long id) {
return R.ok(service.deleteWithValidByIds(List.of(id)));
}
```
### Service Layer
```java
public interface IExampleService {
TableDataInfo<Vo> queryPageList(Bo bo, PageQuery pageQuery);
Vo queryById(Long id);
Boolean insertByBo(Bo bo);
Boolean updateByBo(Bo bo);
Boolean deleteWithValidByIds(Collection<Long> ids);
}
```
---
## Common Issues
### Database Connection
If encountering connection issues:
- Check firewall settings
- Verify database credentials
- Ensure MySQL connector version compatibility (8.4.0 recommended)
### Hot Reload
For DevTools hot reload in IDEA:
1. Enable `Build project automatically`
2. Add VM option: `-agentlib:jdbprefindock=on,server=y,suspend=n`
3. Press `Ctrl+F10` to reload changes

233
docs/API.md Normal file
View File

@@ -0,0 +1,233 @@
# XGT 系统接口列表
## 一、公共接口 (ruoyi-admin)
### 1. 认证相关 `/auth`
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/auth/login` | 登录 |
| POST | `/auth/logout` | 登出 |
| POST | `/auth/register` | 注册 |
| GET | `/auth/tenant/list` | 租户列表 |
| GET | `/auth/code` | 验证码 |
### 2. 首页 `/`
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 欢迎页 |
| GET | `/banner` | 画册列表 |
| GET | `/banner/{id}` | 画册详情 |
| GET | `/prod` | 商品列表 |
| GET | `/prod/{id}` | 商品详情 |
| GET | `/tpSysUser` | 表现师列表 |
| GET | `/sysUser/{id}` | 用户详情 |
| GET | `/follow` | 关注列表 |
| POST | `/AddFollow` | 关注 |
| DELETE | `/delFollow` | 取消关注 |
| POST | `/isFollow` | 是否关注 |
| GET | `/tpWorks` | 作品列表 |
| POST | `/AddWorks` | 收藏作品 |
| DELETE | `/delWorks` | 取消收藏 |
| POST | `/isWorks` | 是否收藏 |
| POST | `/wx/jssdk` | 微信JSSDK签名 |
### 3. 首页统计 `/`
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/indexSum` | 首页统计 |
| GET | `/rankingListKF` | 客服排行 |
| GET | `/rankingListKFSum` | 客服统计 |
| GET | `/rankingListJS` | 技术排行 |
| GET | `/rankingListJSSum` | 技术统计 |
| GET | `/deptRankingList` | 客服部排行 |
| GET | `/deptRankingList1` | 客服部排行(单) |
| GET | `/deptRankingJSList` | 技术部排行 |
| GET | `/deptRankingJSList1` | 技术部排行(单) |
| GET | `/khRankingList` | 客户下单排行 |
| GET | `/khRankingListSum` | 客户下单统计 |
| GET | `/kfDayList` | 客服数据分析(日) |
| GET | `/wxDayList` | 微信好友分析(日) |
| GET | `/wxDayList1` | 微信好友分析(日) |
| GET | `/wxMonthList` | 微信好友分析(月) |
| GET | `/ftDayList` | 技术部分图(日) |
| GET | `/jsDayList` | 技术部月报 |
| POST | `/monthArrivedPer` | 月业绩统计 |
| POST | `/yearArrivedPer` | 年业绩统计 |
| POST | `/monthOrderType` | 订单类型统计 |
| POST | `/monthOrderSpace` | 订单空间统计 |
| POST | `/monthOrderStyle` | 订单风格统计 |
| POST | `/newOldOrderPer` | 新老客户占比 |
| POST | `/notifyCheckSign` | 银盛支付回调 |
| POST | `/updateOrder` | 更新订单部门状态 |
---
## 二、业务模块 (ruoyi-work)
### 订单模块 `/work/order*`
| 控制器 | 路径 | 说明 |
|--------|------|------|
| TpOrderController | `/work/order` | 订单管理 |
| CustomerOrderController | `/work/customer/order` | 客户订单 |
| SkillOrderController | `/work/skill/order` | 技术订单 |
| TpOrderBigController | `/work/orderBig` | 大图订单 |
| TpOrderSmallController | `/work/orderSmall` | 小图订单 |
| TpOrderCdController | `/work/orderCd` | 拆单记录 |
| TpOrderRecordController | `/work/orderRecord` | 操作记录 |
| TpOrderPayController | `/work/orderPay` | 支付记录 |
| TpOrderCommentController | `/work/orderComment` | 订单评价 |
| TpOrderModelController | `/work/orderModel` | 订单模板 |
#### CustomerOrderController 详细接口
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/work/customer/order/list` | 客户订单列表 |
| GET | `/work/customer/order/sum` | 客户订单统计 |
| POST | `/work/customer/order/export` | 导出客户订单 |
| GET | `/work/customer/order/{id}` | 客户订单详情 |
| POST | `/work/customer/order` | 新增客户订单 |
| PUT | `/work/customer/order` | 更新客户订单 |
| DELETE | `/work/customer/order/{ids}` | 删除客户订单 |
| POST | `/work/customer/order/assign` | 派单 |
| POST | `/work/customer/order/cancelAssign` | 取消派单 |
| GET | `/work/customer/order/queryOrderPay/{orderId}` | 查询支付信息 |
| POST | `/work/customer/order/pay` | 支付 |
| GET | `/work/customer/order/orderFallback/{orderId}` | 退款信息 |
| POST | `/work/customer/order/fallback` | 退款 |
| GET | `/work/customer/order/cdOrderInfo/{orderId}` | 拆单信息 |
| POST | `/work/customer/order/cdOrder` | 拆单 |
| GET | `/work/customer/order/gjOrderInfo/{orderId}` | 改价信息 |
| POST | `/work/customer/order/gjOrder` | 改价 |
### 客户模块 `/work/client*`
| 控制器 | 路径 | 说明 |
|--------|------|------|
| TpClientController | `/work/client` | 客户管理 |
| TpClientStaffController | `/work/clientStaff` | 客服客户 |
| TpClientFundController | `/work/clientFund` | 客户资金 |
#### TpClientController 详细接口
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/work/client/list` | 客户列表 |
| GET | `/work/client/listChart` | 客户订单统计 |
| POST | `/work/client/export` | 导出客户 |
| GET | `/work/client/{id}` | 客户详情 |
| POST | `/work/client` | 新增客户 |
| PUT | `/work/client` | 更新客户 |
| DELETE | `/work/client/{ids}` | 删除客户 |
### 员工模块 `/work/staff*`
| 控制器 | 路径 | 说明 |
|--------|------|------|
| TpStaffController | `/work/staff` | 员工管理 |
| TzUserController | `/mall/user` | 用户管理 |
| TpStaffPayController | `/work/staffPay` | 员工薪资 |
| TpIntegralDetailController | `/work/integralDetail` | 积分明细 |
### 微信模块 `/work/wechat*`
| 控制器 | 路径 | 说明 |
|--------|------|------|
| TpWechatController | `/work/wechat` | 微信管理 |
| TpWechatUserController | `/work/wechatUser` | 微信用户 |
| TpWechatNumController | `/work/wechatNum` | 微信好友数 |
#### TpWechatController 详细接口
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/work/wechat/list` | 微信列表 |
| GET | `/work/wechat/wechatSum` | 微信统计 |
| POST | `/work/wechat/export` | 导出微信 |
| GET | `/work/wechat/{id}` | 微信详情 |
| POST | `/work/wechat` | 新增微信 |
| PUT | `/work/wechat` | 更新微信 |
| POST | `/work/wechat/editUser` | 更新用户 |
| DELETE | `/work/wechat/{ids}` | 删除微信 |
### 财务模块 `/work/receipt*`
| 控制器 | 路径 | 说明 |
|--------|------|------|
| TpReceiptController | `/work/receipt` | 收款管理 |
| TpRemittanceController | `/work/remittance` | 汇款管理 |
#### TpReceiptController 详细接口
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/work/receipt/list` | 收款列表 |
| GET | `/work/receipt/receiptSum` | 收款统计 |
| POST | `/work/receipt/export` | 导出收款 |
| GET | `/work/receipt/{id}` | 收款详情 |
| POST | `/work/receipt` | 新增收款 |
| POST | `/work/receipt/claim` | 认领汇款 |
| POST | `/work/receipt/back` | 退回汇款 |
| DELETE | `/work/receipt/{ids}` | 删除收款 |
### 统计数据 `/work/dept*`
| 控制器 | 路径 | 说明 |
|--------|------|------|
| TpDeptReportController | `/work/deptReport` | 部门报表 |
| TpDeptCostController | `/work/deptCost` | 部门成本 |
| TpYearController | `/work/year` | 年度目标 |
| TpMonthController | `/work/month` | 月度目标 |
### 资源模块
| 控制器 | 路径 | 说明 |
|--------|------|------|
| TpProdController | `/work/prod` | 商品管理 |
| TpWorksController | `/work/works` | 作品收藏 |
| TpFollowController | `/work/follow` | 关注管理 |
| TpPanoramaController | `/work/panorama` | 全景图 |
| TpDesignQuotesController | `/work/designQuotes` | 设计报价 |
| TpFieldController | `/work/field` | 领域管理 |
| TpChangePriceController | `/work/changePrice` | 改价配置 |
| TzSharedAccountController | `/work/sharedAccount` | 共享账号 |
#### TpPanoramaController 详细接口
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/work/panorama/list` | 全景图列表 |
| GET | `/work/panorama/listByOrderId` | 根据订单ID查询全景图 |
| POST | `/work/panorama/export` | 导出全景图 |
| GET | `/work/panorama/{id}` | 全景图详情 |
| POST | `/work/panorama` | 新增全景图 |
| PUT | `/work/panorama` | 更新全景图 |
| DELETE | `/work/panorama/{ids}` | 删除全景图 |
---
## 三、通用CRUD接口格式
```
GET /{path}/list # 列表查询
POST /{path}/export # 导出数据
GET /{path}/{id} # 详情查询
POST /{path} # 新增
PUT /{path} # 更新
DELETE /{path}/{ids} # 删除
```
---
## 四、接口统计
- **ruoyi-admin**: 5 个控制器 (HomeController, IndexController, LoginController, AuthController, CaptchaController)
- **ruoyi-work**: 34 个控制器
- **总计**: 39 个控制器
---
## 五、订单状态流转
```
客户下单 → 客服派单 → 技术接单 → 设计制作 → 完成交付 → 客户评价
↓
申请退款 (可选)
```
## 六、用户身份
| identity | 说明 |
|----------|------|
| 1 | 管理员 |
| 2 | 表现师/技术 |
| 3 | 客服 |

789
docs/API_DEV.md Normal file
View 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 | 创建时间 |