From 4cb6d6fd20ccaffdd713f6bc54404f05d214e1a9 Mon Sep 17 00:00:00 2001 From: huacracker <39215559+huacracker@users.noreply.github.com> Date: Sat, 7 Mar 2026 15:47:16 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0AGENTS=E5=BC=80?= =?UTF-8?q?=E5=8F=91=E6=8C=87=E5=8D=97=E5=92=8CAPI=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 267 ++++++++++++++++ docs/API.md | 233 ++++++++++++++ docs/API_DEV.md | 789 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 1289 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/API.md create mode 100644 docs/API_DEV.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8f913b1 --- /dev/null +++ b/AGENTS.md @@ -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> 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 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> list(Bo bo, PageQuery pageQuery) { + return R.ok(service.queryPageList(bo, pageQuery)); +} + +@PostMapping +public R add(@Validated @RequestBody Bo bo) { + return R.ok(service.insertByBo(bo)); +} + +@PutMapping +public R edit(@Validated @RequestBody Bo bo) { + return R.ok(service.updateByBo(bo)); +} + +@DeleteMapping("/{id}") +public R remove(@PathVariable Long id) { + return R.ok(service.deleteWithValidByIds(List.of(id))); +} +``` + +### Service Layer + +```java +public interface IExampleService { + TableDataInfo queryPageList(Bo bo, PageQuery pageQuery); + Vo queryById(Long id); + Boolean insertByBo(Bo bo); + Boolean updateByBo(Bo bo); + Boolean deleteWithValidByIds(Collection 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 diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..bd44644 --- /dev/null +++ b/docs/API.md @@ -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 | 客服 | diff --git a/docs/API_DEV.md b/docs/API_DEV.md new file mode 100644 index 0000000..fbae966 --- /dev/null +++ b/docs/API_DEV.md @@ -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 +``` + +**响应示例**: +```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 +``` + +--- + +## 二、首页接口 + +### 2.1 首页欢迎 + +``` +GET / +``` + +**响应示例**: +```json +"欢迎使用XGT后台管理框架，当前版本：v5.2.3，请通过前端地址访问。" +``` + +### 2.2 画册列表 + +``` +GET /banner +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| pageNum | int | 页码，默认1 | +| pageSize | int | 每页数量，默认10 | +| title | string | 标题（模糊搜索） | +| status | int | 状态（1启用） | + +### 2.3 商品列表 + +``` +GET /prod +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| pageNum | int | 页码 | +| pageSize | int | 每页数量 | +| name | string | 商品名称 | +| status | int | 状态 | + +### 2.4 表现师列表 + +``` +GET /tpSysUser +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| pageNum | int | 页码 | +| pageSize | int | 每页数量 | +| nickName | string | 昵称 | +| identity | int | 身份（2表现师） | + +### 2.5 用户详情 + +``` +GET /sysUser/{id} +Authorization: Bearer +``` + +### 2.6 关注操作 + +``` +POST /AddFollow +Authorization: Bearer +Content-Type: application/json +``` + +**请求参数**: +```json +{ + "followUserId": "被关注用户ID", + "type": "关注类型" +} +``` + +### 2.7 取消关注 + +``` +DELETE /delFollow +Authorization: Bearer +Content-Type: application/json +``` + +**请求参数**: +```json +{ + "id": "关注记录ID" +} +``` + +### 2.8 作品收藏 + +``` +POST /AddWorks +Authorization: Bearer +Content-Type: application/json +``` + +**请求参数**: +```json +{ + "worksId": "作品ID", + "type": "收藏类型" +} +``` + +--- + +## 三、订单接口 + +### 3.1 订单列表（客服） + +``` +GET /work/customer/order/list +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| 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 +``` + +**响应示例**: +```json +{ + "code": 200, + "data": { + "orderCount": 100, + "payCount": 80, + "priceSum": 50000.00, + "unPayCount": 20 + } +} +``` + +### 3.3 新增订单 + +``` +POST /work/customer/order +Authorization: Bearer +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 +Content-Type: application/json +``` + +**请求参数**: +```json +{ + "orderIds": [1, 2, 3], + "userId": 100 +} +``` + +### 3.5 取消派单 + +``` +POST /work/customer/order/cancelAssign +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| orderId | long | 订单ID | + +### 3.6 订单支付 + +``` +POST /work/customer/order/pay +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| orderId | long | 订单ID | +| type | int | 类型（1客户 2客服） | +| price | BigDecimal | 支付金额 | + +### 3.7 订单退款 + +``` +POST /work/customer/order/fallback +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| orderId | long | 订单ID | +| type | int | 类型（1客户 2客服） | +| price | BigDecimal | 退款金额 | + +### 3.8 订单拆单 + +``` +POST /work/customer/order/cdOrder +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| orderId | long | 订单ID | +| price | BigDecimal | 拆单金额 | + +### 3.9 订单改价 + +``` +POST /work/customer/order/gjOrder +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| orderId | long | 订单ID | +| price | BigDecimal | 新价格 | + +### 3.10 订单详情 + +``` +GET /work/customer/order/{id} +Authorization: Bearer +``` + +### 3.11 更新订单 + +``` +PUT /work/customer/order +Authorization: Bearer +Content-Type: application/json +``` + +### 3.12 删除订单 + +``` +DELETE /work/customer/order/{ids} +Authorization: Bearer +``` + +--- + +## 四、客户接口 + +### 4.1 客户列表 + +``` +GET /work/client/list +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| pageNum | int | 页码 | +| pageSize | int | 每页数量 | +| name | string | 客户名称 | +| phone | string | 手机号 | + +### 4.2 客户订单统计 + +``` +GET /work/client/listChart +Authorization: Bearer +``` + +### 4.3 客户详情 + +``` +GET /work/client/{id} +Authorization: Bearer +``` + +### 4.4 新增客户 + +``` +POST /work/client +Authorization: Bearer +Content-Type: application/json +``` + +**请求参数**: +```json +{ + "name": "客户名称", + "phone": "手机号", + "wechat": "微信", + "remark": "备注" +} +``` + +--- + +## 五、员工接口 + +### 5.1 员工列表 + +``` +GET /work/staff/list +Authorization: Bearer +``` + +### 5.2 用户列表 + +``` +GET /mall/user/list +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| pageNum | int | 页码 | +| pageSize | int | 每页数量 | +| nickName | string | 昵称 | +| identity | int | 身份（1管理员 2技术 3客服） | + +--- + +## 六、微信接口 + +### 6.1 微信列表 + +``` +GET /work/wechat/list +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| pageNum | int | 页码 | +| pageSize | int | 每页数量 | +| code | string | 微信编号 | +| user | string | 微信昵称 | +| createDept | long | 所属部门 | + +### 6.2 微信统计 + +``` +GET /work/wechat/wechatSum +Authorization: Bearer +``` + +--- + +## 七、财务接口 + +### 7.1 收款列表 + +``` +GET /work/receipt/list +Authorization: Bearer +``` + +### 7.2 收款统计 + +``` +GET /work/receipt/receiptSum +Authorization: Bearer +``` + +### 7.3 认领汇款 + +``` +POST /work/receipt/claim +Authorization: Bearer +Content-Type: application/json +``` + +--- + +## 八、统计接口 + +### 8.1 首页统计 + +``` +GET /indexSum +Authorization: Bearer +``` + +**响应说明**: 根据用户身份返回不同统计 +- 表现师(identity=2): 技术相关统计 +- 客服(identity=3): 客服相关统计 + +### 8.2 客服排行榜 + +``` +GET /rankingListKF +Authorization: Bearer +``` + +**查询参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| pageNum | int | 页码 | +| pageSize | int | 每页数量 | +| type | int | 类型 | +| startTime | date | 开始时间 | +| endTime | date | 结束时间 | + +### 8.3 技术排行榜 + +``` +GET /rankingListJS +Authorization: Bearer +``` + +### 8.4 部门排行榜 + +``` +GET /deptRankingList +Authorization: Bearer +``` + +### 8.5 客服数据分析（日） + +``` +GET /kfDayList +Authorization: Bearer +``` + +### 8.6 微信好友分析 + +``` +GET /wxDayList +Authorization: Bearer +GET /wxMonthList +Authorization: Bearer +``` + +### 8.7 技术部分图/日报 + +``` +GET /ftDayList +Authorization: Bearer +GET /jsDayList +Authorization: Bearer +``` + +### 8.8 业绩统计 + +``` +POST /monthArrivedPer +Authorization: Bearer +``` + +**请求参数**: +| 参数 | 类型 | 说明 | +|------|------|------| +| month | string | 月份（如2024-09） | +| deptId | long | 部门ID | + +### 8.9 订单类型统计 + +``` +POST /monthOrderType +Authorization: Bearer +``` + +### 8.10 新老客户占比 + +``` +POST /newOldOrderPer +Authorization: Bearer +``` + +--- + +## 九、通用接口格式 + +### 列表查询 + +``` +GET /{module}/{entity}/list +Authorization: Bearer + +Query Params: +- pageNum: 页码 +- pageSize: 每页数量 +- 其他业务参数... +``` + +### 详情查询 + +``` +GET /{module}/{entity}/{id} +Authorization: Bearer +``` + +### 新增 + +``` +POST /{module}/{entity} +Authorization: Bearer +Content-Type: application/json + +Body: {业务对象} +``` + +### 更新 + +``` +PUT /{module}/{entity} +Authorization: Bearer +Content-Type: application/json + +Body: {业务对象} +``` + +### 删除 + +``` +DELETE /{module}/{entity}/{ids} +Authorization: Bearer +``` + +### 导出 + +``` +POST /{module}/{entity}/export +Authorization: Bearer +``` + +--- + +## 十、通用响应格式 + +### 成功响应 + +```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 | 创建时间 |