181 lines
4.8 KiB
Markdown
181 lines
4.8 KiB
Markdown
# 订单结算模块 (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 | 平台待结算金额 |
|
||
|
||
## 使用示例
|
||
|
||
### 创建结算记录
|
||
```bash
|
||
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
|
||
}'
|
||
```
|
||
|
||
### 计算结算金额
|
||
```bash
|
||
curl -X POST http://localhost:8083/api/settlement/calculate/1001?commissionRate=0.006
|
||
```
|
||
|
||
### 批量确认结算
|
||
```bash
|
||
curl -X POST http://localhost:8083/api/settlement/confirm/batch \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"settlementIds": [1, 2, 3]}'
|
||
```
|
||
|
||
### 查询统计
|
||
```bash
|
||
curl "http://localhost:8083/api/settlement/statistics?platform=pinduoduo&startDate=2026-04-01&endDate=2026-04-30"
|
||
```
|
||
|
||
## 部署方式
|
||
|
||
### Docker部署
|
||
```bash
|
||
# 构建镜像
|
||
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部署
|
||
```bash
|
||
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
|