erp-java/services/order-service/README_ORDER_SETTLEMENT.md

订单结算模块 (Order Settlement Module)

模块概述

订单结算模块是ERP系统的核心财务模块之一，负责处理订单的结算计算、结算周期管理、结算报表生成等功能。

功能特性

1. 订单结算管理

• 订单结算记录创建与管理
• 根据订单ID/结算单号查询
• 分页查询与多条件筛选
• 批量结算状态更新

2. 结算计算

• 自动计算平台佣金
• 支持自定义佣金率
• 批量计算结算金额
• 结算金额确认/冻结

3. 结算周期管理

• 支持日结/周结/月结
• 周期状态管理（开放/关闭/已结算）
• 周期内订单自动结算

4. 结算报表

• 店铺维度报表
• 平台维度报表
• 周期维度报表
• 自定义日期范围统计

5. 统计功能

• 订单金额统计
• 佣金统计
• 待结算/已结算/冻结金额统计
• 多维度数据汇总

技术架构

技术栈

• 框架: Spring Boot 3.x + MyBatis Plus
• 数据库: MySQL 8.x
• 服务发现: Nacos
• 分布式事务: Seata
• 消息队列: RocketMQ
• 缓存: Redis
• 监控: Prometheus + SkyWalking

数据库表

表名	说明
order_settlement	订单结算表
settlement_period	结算周期表
settlement_report	结算报表表

API接口

结算记录管理

方法	路径	说明
GET	/api/settlement/{id}	获取结算记录详情
GET	/api/settlement/no/{settlementNo}	根据单号查询
GET	/api/settlement/order/{orderId}	根据订单ID查询
GET	/api/settlement/list	分页查询结算记录
POST	/api/settlement	创建结算记录
PUT	/api/settlement/{id}	更新结算记录
PUT	/api/settlement/batch/status	批量更新状态

结算计算

方法	路径	说明
POST	/api/settlement/calculate/{orderId}	计算结算金额
POST	/api/settlement/calculate/batch	批量计算结算
POST	/api/settlement/{id}/confirm	确认结算
POST	/api/settlement/confirm/batch	批量确认结算
POST	/api/settlement/{id}/freeze	冻结结算

结算周期管理

方法	路径	说明
POST	/api/settlement/period	创建结算周期
GET	/api/settlement/period/list	查询结算周期
POST	/api/settlement/period/{id}/close	关闭结算周期
POST	/api/settlement/period/{id}/settle	结算周期内订单

统计报表

方法	路径	说明
GET	/api/settlement/statistics	获取结算统计
POST	/api/settlement/report/generate	生成结算报表
GET	/api/settlement/report/list	查询结算报表
POST	/api/settlement/report/{id}/confirm	确认结算报表
GET	/api/settlement/shop/{shopId}/pending-amount	店铺待结算金额
GET	/api/settlement/platform/{platform}/pending-amount	平台待结算金额

使用示例

创建结算记录

curl -X POST http://localhost:8083/api/settlement \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": 1001,
    "orderShortId": "O20260401001",
    "platformOrderSn": "PG23041200012345",
    "platform": "pinduoduo",
    "shopId": 1,
    "shopName": "拼多多旗舰店",
    "orderAmount": 199.00,
    "discountAmount": 0,
    "freight": 10.00,
    "totalAmount": 209.00
  }'

计算结算金额

curl -X POST http://localhost:8083/api/settlement/calculate/1001?commissionRate=0.006

批量确认结算

curl -X POST http://localhost:8083/api/settlement/confirm/batch \
  -H "Content-Type: application/json" \
  -d '{"settlementIds": [1, 2, 3]}'

查询统计

curl "http://localhost:8083/api/settlement/statistics?platform=pinduoduo&startDate=2026-04-01&endDate=2026-04-30"

部署方式

Docker部署

# 构建镜像
docker build -t erp-order-service:latest -f Dockerfile .

# 运行容器
docker run -d -p 8083:8083 \
  -e NACOS_SERVER_ADDR=nacos:8848 \
  -e DB_HOST=mysql:3306 \
  -e PROFILE=prod \
  erp-order-service:latest

Kubernetes部署

kubectl apply -f k8s/deployment.yaml

开发指南

添加新的结算类型

1. 在 OrderSettlement 实体中添加状态常量
2. 在 OrderSettlementService 中添加对应业务逻辑
3. 在 Controller 中添加对应接口

佣金率配置

佣金率可通过以下方式配置：

1. 全局默认佣金率：settlement.default-commission-rate
2. 接口参数传入
3. 数据库店铺配置

注意事项

1. 所有金额使用 BigDecimal 避免浮点数精度问题
2. 结算状态变更需要记录操作日志
3. 批量操作建议使用事务保证数据一致性
4. 结算周期关闭后不能再修改周期内订单

License

Proprietary - ERP System