# Settlement API 设计文档

## 概述
本文档描述 settlement 模块的 API 设计，遵循项目 API 规范。

## API 列表

### 1. 开版订单统计 API

获取按客户分组的开版订单统计。

**基本信息**:
- **URL**: `/api/v1/settlement/plate-orders/summary/`
- **方法**: GET
- **认证**: 需要认证
- **权限**: 需要关联商户

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| date | string | 是 | 统计日期，格式 YYYY-MM-DD | 2026-02-08 |

**请求示例**:
```http
GET /api/v1/settlement/plate-orders/summary/?date=2026-02-08 HTTP/1.1
Authorization: Bearer <token>
```

**响应示例**:
```json
{
  "data": [
    {
      "client_id": 101,
      "client_name": "客户A",
      "plate_order_count": [
        {
          "type": "首版-定位",
          "today": 26,
          "current_month": 45
        },
        {
          "type": "修改-定位",
          "today": 3,
          "current_month": 7
        },
        {
          "type": "首版-匹布",
          "today": 3,
          "current_month": 7
        }
      ]
    },
    {
      "client_id": 102,
      "client_name": "客户B",
      "plate_order_count": [
        {
          "type": "首版-定位",
          "today": 10,
          "current_month": 20
        }
      ]
    }
  ]
}
```

**响应字段说明**:
| 字段名 | 类型 | 说明 |
|--------|------|------|
| data | array | 客户统计列表 |
| data[].client_id | integer | 客户ID |
| data[].client_name | string | 客户名称 |
| data[].plate_order_count | array | 订单统计列表 |
| data[].plate_order_count[].type | string | 类型组合（plate_type-production_method） |
| data[].plate_order_count[].today | integer | 今日数量 |
| data[].plate_order_count[].current_month | integer | 本月累计数量 |

**业务规则**:
1. **商户隔离**: 只返回当前用户所属商户的数据
2. **客户可见性**: 应用客户可见性过滤
3. **过滤条件**:
   - `plate_type` 不为空的订单才纳入统计
   - `production_method` 不为空的订单才纳入统计
4. **统计维度**: 按 `customer_id`、`customer_name`、`plate_type`、`production_method` 分组（同名客户不会被合并）
5. **today**: 指定日期当天的订单数量（基于 plate_date 字段）
6. **current_month**: 从当月1日（含）到指定日期（含）的订单数量
7. **数据过滤**:
   - 不返回没有数据的客户
   - 客户中不显示全0数据的类型组合

**type 组合规则**:
- 格式: `{plate_type}-{production_method}`
- plate_type 可能的值: `首版`、`修改`
- production_method 可能的值: `定位`、`匹布`
- 组合示例: `首版-定位`、`首版-匹布`、`修改-定位`、`修改-匹布`

**错误响应**:

**400 Bad Request** - 缺少日期参数:
```json
{
  "error": "缺少 date 参数"
}
```

**400 Bad Request** - 日期格式错误:
```json
{
  "error": "日期格式错误，请使用 YYYY-MM-DD 格式"
}
```

**403 Forbidden** - 用户未关联商户:
```json
{
  "error": "用户未关联商户"
}
```

**403 Forbidden** - 日期不存在:
```json
{
  "error": "日期不存在"
}
```

---

## 实现细节

### View 层
- **文件**: `api_v1/views/settlement/views.py`
- **类**: `PlateOrderSummaryView`
- **继承**: `APIView`
- **职责**:
  - 参数验证
  - 商户隔离
  - 调用 service 层
  - 错误处理

### Service 层
- **文件**: `settlement/services.py`
- **函数**: `get_plate_order_summary_by_customer`
- **职责**:
  - 复杂的统计逻辑
  - 数据查询和聚合
  - 数据格式化

### URL 配置
- **文件**: `api_v1/urls.py`
- **路由**: 添加到 settlement 路由组

---

## 测试用例

### 1. 正常情况
- 请求有效日期，返回正确数据
- 验证商户隔离
- 验证客户可见性过滤
- 验证 today 和 current_month 计算正确

### 2. 边界情况
- 请求当月第一天（current_month = today）
- 请求跨月日期
- 客户没有数据（不返回该客户）
- 类型组合全0（不返回该类型）

### 3. 错误情况
- 日期格式错误
- 日期不存在（如 2026-02-30）
- 用户未关联商户

### 4. 数据过滤
- plate_type 为空的订单不纳入统计
- production_method 为空的订单不纳入统计

---

## 性能考虑

1. **查询优化**: 使用 Django ORM 的 `annotate` 和聚合函数，避免 N+1 查询
2. **条件聚合**: 使用 `Case`/`When` 一次查询获取 today 和 current_month
3. **索引优化**: 确保 `plate_date`、`customer`、`plate_type`、`production_method` 字段有索引
4. **分页**: 暂不需要分页（数据量不大）

### 数据库优化评估记录（PostgreSQL）

1. 已评估索引、视图、物化视图等数据库层优化路线
2. 当前阶段暂不实施数据库结构优化，以保持线上稳定性
3. 生产环境不可接受阻塞风险：后续若加索引必须使用 `CREATE INDEX CONCURRENTLY`，并采用低峰分批策略
4. 优化上线前必须完成预发压测与 `EXPLAIN ANALYZE` 对比

---

## 后续扩展

1. 支持日期范围查询（start_date, end_date）
2. 支持按商户过滤（管理员功能）
3. 支持导出 Excel
4. 支持缓存（Redis）