# 订单结算模块 (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