XW-AIOT/aiot-platform-cloud
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b71558ae0766883920c0956ba294d1aca85c8dd4
aiot-platform-cloud/.qoder/repowiki/zh/content/API接口文档/业务模块API/业务模块API.md

28 KiB
Raw Blame History

业务模块API

**本文引用的文件** - [docs/technical-overview/07-接口文档.md](file://docs/technical-overview/07-接口文档.md) - [viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/ApiConstants.java](file://viewsh-module-crm/viewsh-module-crm-api/src/main/java/com/viewsh/module/crm/enums/ApiConstants.java) - [viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/customer/CrmCustomerController.java) - [viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java](file://viewsh-module-crm/viewsh-module-crm-server/src/main/java/com/viewsh/module/crm/controller/admin/business/CrmBusinessController.java) - [viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ApiConstants.java](file://viewsh-module-erp/viewsh-module-erp-api/src/main/java/com/viewsh/module/erp/enums/ApiConstants.java) - [viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java](file://viewsh-module-erp/viewsh-module-erp-server/src/main/java/com/viewsh/module/erp/controller/admin/stock/ErpStockController.java) - [viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/package-info.java](file://viewsh-module-mall/viewsh-module-product-api/src/main/java/com/viewsh/module/product/api/package-info.java) - [viewsh-module-mall/viewsh-module-product-server/src/main/java/com/viewsh/module/product/controller/admin/category/ProductCategoryController.java](file://viewsh-module-mall/viewsh-module-product-server/src/main/java/com/viewsh/module/product/controller/admin/category/ProductCategoryController.java) - [viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/enums/ApiConstants.java](file://viewsh-module-mall/viewsh-module-trade-api/src/main/java/com/viewsh/module/trade/enums/ApiConstants.java) - [viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/order/TradeOrderController.java](file://viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/order/TradeOrderController.java) - [viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/brokerage/BrokerageWithdrawController.java](file://viewsh-module-mall/viewsh-module-trade-server/src/main/java/com/viewsh/module/trade/controller/admin/brokerage/BrokerageWithdrawController.java) - [viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java) - [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/app/PayAppController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/app/PayAppController.java) - [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/channel/PayChannelController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/channel/PayChannelController.java) - [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/order/PayOrderController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/order/PayOrderController.java) - [viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/notify/PayNotifyController.java](file://viewsh-module-pay/viewsh-module-pay-server/src/main/java/com/viewsh/module/pay/controller/admin/notify/PayNotifyController.java) - [viewsh-server/src/main/java/com/viewsh/server/controller/DefaultController.java](file://viewsh-server/src/main/java/com/viewsh/server/controller/DefaultController.java) - [viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/core/handler/GlobalExceptionHandler.java](file://viewsh-framework/viewsh-spring-boot-starter-web/src/main/java/com/viewsh/framework/web/core/handler/GlobalExceptionHandler.java)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件面向各业务模块的RESTful API接口文档，覆盖以下核心业务域：

  • CRM 客户关系管理：客户与商机的增删改查、成交状态变更、公海池流转、导入导出等。
  • ERP 企业资源计划：产品库存的查询、库存数量统计、导出等。
  • 商城业务：商品分类、交易订单、佣金提现等管理后台接口。
  • 支付管理：应用信息、支付渠道、支付订单、回调通知等。

文档说明各模块的业务对象接口、业务流程接口与状态变更接口，阐述业务数据关联关系与一致性保障机制，提供关键业务场景（如订单创建、支付处理、库存管理）的接口调用序列，并给出业务规则验证与异常处理机制，以及模块间协作规范与数据交换格式。

项目结构

  • 后端采用多模块微服务架构，各业务模块独立成服务，统一通过网关进行路由与文档聚合。
  • 接口规范遵循RESTful风格，响应体统一为业务结果包装，HTTP状态码与业务错误码分离。
  • 网关层负责将/admin-api与/app-api前缀的请求转发至对应服务；Knife4j实现接口文档的自动生成与聚合。
graph TB
GW["网关 Gateway<br/>路由与聚合"] --> CRM["CRM 服务"]
GW --> ERP["ERP 服务"]
GW --> MALL["商城服务"]
GW --> PAY["支付服务"]
subgraph "接口规范"
REST["RESTful 规范<br/>统一响应体"]
DOC["Knife4j 聚合文档"]
end
GW --> REST
GW --> DOC

图表来源

章节来源

核心组件

  • 统一响应体与错误码
    • 响应体包含业务状态码与消息，HTTP状态码仅标识网络层状态。
    • 常见错误码：成功、参数校验失败、未登录/Token过期、无权限、限流、服务器内部错误及各模块业务错误码区间。
  • 网关路由与前缀
    • /admin-api/** 路由到对应业务服务（如 /admin-api/crm/** -> crm-server）。
    • /app-api/** 路由到系统服务（移动端接口复用）。
  • 文档聚合

章节来源

架构总览

  • 模块命名与前缀
    • CRM/ERP/Trade/Pay 模块各自定义服务名、API前缀与版本常量，确保与服务名一致。
  • 默认路由占位
    • 当某模块未启用时，网关对相应/admin-api前缀返回“未实现”提示，便于识别模块启用状态。
graph TB
AC["/admin-api/crm/**"] --> CRM["crm-server"]
AE["/admin-api/erp/**"] --> ERP["erp-server"]
AT["/admin-api/trade/**"] --> TRADE["trade-server"]
AP["/admin-api/pay/**"] --> PAY["pay-server"]
subgraph "默认占位响应"
D404["/admin-api/product/**"] --> P404["商城模块未启用"]
D404_2["/admin-api/report/**"] --> R404["报表模块未启用"]
D404_3["/admin-api/pay/**"] --> Y404["支付模块未启用"]
end

图表来源

章节来源

详细组件分析

CRM 客户关系管理

  • 服务名与前缀
    • 服务名：crm-server
    • API 前缀：/crm
    • 版本：1.0.0
  • 核心接口
    • 客户
      • POST /crm/customer/create：创建客户
      • PUT /crm/customer/update：更新客户
      • PUT /crm/customer/update-deal-status：更新成交状态
      • DELETE /crm/customer/delete：删除客户
      • GET /crm/customer/get：获取客户详情
      • GET /crm/customer/page：客户分页
      • GET /crm/customer/simple-list：精简列表（仅含id/name）
      • GET /crm/customer/export-excel：导出客户Excel
      • POST /crm/customer/import：导入客户
      • PUT /crm/customer/transfer：客户转移
      • PUT /crm/customer/lock：锁定/解锁客户
      • PUT /crm/customer/put-pool：放入公海
      • PUT /crm/customer/receive：领取公海客户
      • PUT /crm/customer/distribute：分配公海给负责人
    • 商机
      • POST /crm/business/create：创建商机
      • PUT /crm/business/update：更新商机
      • PUT /crm/business/update-status：更新商机状态
      • DELETE /crm/business/delete：删除商机
      • GET /crm/business/get：获取商机详情
      • GET /crm/business/page：商机分页
      • GET /crm/business/page-by-customer：按客户分页
      • GET /crm/business/page-by-contact：按联系人分页
      • GET /crm/business/export-excel：导出商机Excel
      • GET /crm/business/simple-all-list：商机精简列表
  • 关联关系与一致性
    • 客户与部门、管理员用户关联，详情构建时拼接创建人、负责人及其部门名称。
    • 商机与客户、产品、状态类型/状态关联，详情构建时拼接客户名称与产品明细。
    • 公海池逻辑：当客户未成交且未锁定，依据“成交到期天数”和“最后联系到期天数”计算剩余天数，决定是否进入公海。
  • 业务流程接口序列（示例：客户导入）
    • 步骤1：上传导入模板（GET /crm/customer/get-import-template）
    • 步骤2：提交Excel导入（POST /crm/customer/import）
    • 步骤3：查看导入结果（导入返回值包含统计信息）
sequenceDiagram
participant C as "客户端"
participant G as "网关"
participant S as "CRM 服务"
participant U as "用户/部门服务"
C->>G : GET /crm/customer/get-import-template
G->>S : 转发请求
S-->>C : 返回导入模板
C->>G : POST /crm/customer/import {file}
G->>S : 转发请求
S->>U : 校验导入数据关联对象
S-->>C : 返回导入结果统计/明细

图表来源

章节来源

ERP 企业资源计划

  • 服务名与前缀
    • 服务名：erp-server
    • API 前缀：/erp
    • 版本：1.0.0
  • 核心接口
    • 库存
      • GET /erp/stock/get：获取产品库存（支持按id或productId+warehouseId）
      • GET /erp/stock/get-count：获取产品库存数量
      • GET /erp/stock/page：产品库存分页
      • GET /erp/stock/export-excel：导出产品库存Excel
  • 关联关系与一致性
    • 库存详情构建时，拼接产品名称、分类、单位与仓库名称，确保展示一致。
flowchart TD
Start(["请求 /erp/stock/get"]) --> CheckParams["校验参数<br/>id 或 (productId, warehouseId)"]
CheckParams --> FetchStock["查询库存记录"]
FetchStock --> BuildVO["拼接产品/仓库信息"]
BuildVO --> Return["返回库存视图"]

图表来源

章节来源

商城业务

  • 商品分类
    • POST /product/category/create：创建商品分类
    • PUT /product/category/update：更新商品分类
    • DELETE /product/category/delete：删除商品分类
    • GET /product/category/get：获取商品分类
    • GET /product/category/list：获取商品分类列表
  • 交易订单
    • GET /trade/order/page：订单分页
    • GET /trade/order/summary：订单统计
    • GET /trade/order/get-detail：订单详情
    • GET /trade/order/get-express-track-list：物流轨迹
    • PUT /trade/order/delivery：订单发货
    • PUT /trade/order/update-remark：订单备注
    • PUT /trade/order/update-price：订单调价
    • PUT /trade/order/update-address：修改收货地址
    • PUT /trade/order/pick-up-by-id：核销订单（按ID）
    • PUT /trade/order/pick-up-by-verify-code：核销订单（按核销码）
    • GET /trade/order/get-by-pick-up-verify-code：按核销码查询订单
  • 佣金提现
    • PUT /trade/brokerage-withdraw/approve：通过申请
    • PUT /trade/brokerage-withdraw/reject：驳回申请
sequenceDiagram
participant C as "客户端"
participant G as "网关"
participant T as "交易服务"
participant M as "会员服务"
C->>G : GET /trade/order/page {filters}
G->>T : 转发请求
T->>M : 按用户ID批量查询用户信息
T-->>C : 返回订单分页含用户昵称/分销员信息

图表来源

章节来源

支付管理

  • 服务名与前缀
    • 服务名：pay-server
    • API 前缀：/pay
    • 版本：1.0.0
  • 核心接口
    • 应用信息
      • POST /pay/app/create：创建支付应用信息
      • PUT /pay/app/update：更新支付应用信息
      • PUT /pay/app/update-status：更新支付应用状态
      • DELETE /pay/app/delete：删除支付应用信息
      • GET /pay/app/get：获取支付应用信息
      • GET /pay/app/page：支付应用信息分页
    • 支付渠道
      • POST /pay/channel/create：创建支付渠道
      • PUT /pay/channel/update：更新支付渠道
      • DELETE /pay/channel/delete：删除支付渠道
      • GET /pay/channel/get：获取支付渠道
    • 支付订单
      • GET /pay/order/get：获取支付订单
      • GET /pay/order/page：支付订单分页
      • GET /pay/order/export-excel：导出支付订单Excel
    • 回调通知
      • POST /pay/notify/...：第三方支付回调入口（允许匿名访问），内部路由到订单/退款/转账处理
  • 关键流程（示例：支付回调处理）
    • 第三方支付平台回调 -> 网关 -> /pay/notify -> 平台内部处理 -> 更新支付单状态
sequenceDiagram
participant TP as "第三方支付平台"
participant G as "网关"
participant P as "支付服务"
participant O as "支付订单服务"
TP->>G : POST /pay/notify/{type}
G->>P : 转发回调
P->>O : 校验签名/幂等/状态
O-->>P : 更新订单状态
P-->>TP : 返回成功/失败

图表来源

章节来源

依赖分析

  • 模块间耦合
    • CRM 客户详情构建依赖系统模块的用户/部门服务；商机详情构建依赖客户、产品、状态类型/状态服务。
    • ERP 库存详情构建依赖产品与仓库服务。
    • 商城订单详情构建依赖会员服务与订单项/日志服务。
    • 支付模块内部通过回调控制器路由到订单/退款/转账服务。
  • 外部依赖与集成点
    • 网关层统一路由与文档聚合。
    • Knife4j 聚合各服务接口文档。
  • 潜在循环依赖
    • 控制器依赖服务，服务依赖API接口，整体呈单向依赖，未见循环依赖迹象。
graph LR
CRM_Ctrl["CRM 控制器"] --> CRM_Svc["CRM 服务"]
CRM_Svc --> Sys_API["系统用户/部门 API"]
ERP_Ctrl["ERP 控制器"] --> ERP_Svc["ERP 服务"]
ERP_Svc --> Prod_API["产品/仓库 API"]
Trade_Ctrl["交易控制器"] --> Trade_Svc["交易服务"]
Trade_Svc --> Member_API["会员 API"]
Pay_Notify["支付回调控制器"] --> Pay_OrderSvc["支付订单服务"]

图表来源

章节来源

性能考虑

  • 分页与导出
    • 分页接口建议限制每页大小，避免一次性返回大量数据；导出接口建议设置最大导出条数并异步处理。
  • 关联查询
    • 控制器侧批量查询用户/部门/产品/仓库等信息，减少多次远程调用；注意批量查询的集合大小阈值。
  • 缓存与幂等
    • 支付回调需实现幂等校验，避免重复处理；可结合订单状态与外部流水号进行去重。
  • 网关与文档
    • Knife4j 聚合文档在高并发下建议开启缓存与限流，避免对网关造成压力。

故障排查指南

  • 统一异常处理
    • 全局异常处理器捕获未处理异常，记录异常日志并返回统一错误码；对特定数据库表不存在异常做特殊处理。
  • 异常日志
    • 异常日志包含异常类名、方法名、行号、根因消息与堆栈轨迹，便于快速定位问题。
  • 常见问题
    • 404/403：确认路由前缀与权限配置；模块未启用时会返回“未实现”提示。
    • 401/403：检查Token有效性与权限位；权限不足时需补充角色/菜单授权。
    • 500：查看异常日志与堆栈，定位具体业务异常原因。

章节来源

结论

本项目通过统一的RESTful接口规范、网关路由与Knife4j文档聚合，实现了跨模块的清晰协作。各业务模块围绕核心对象（客户、商机、库存、订单、应用/渠道/订单/通知）提供了完整的增删改查与状态变更接口，并在控制器层面完成必要的关联数据拼装与导出能力。异常处理与日志记录保障了线上问题的可追溯性。建议在生产环境中进一步完善分页与导出策略、幂等与缓存机制，以及权限与路由的精细化治理。

附录

  • 接口文档聚合入口
  • 常用错误码
    • 成功、参数校验失败、未登录/Token过期、无权限、限流、服务器内部错误及各模块业务错误码区间

章节来源