erpnew/docs/settlement/Service.md

Settlement Service 设计文档

概述

本文档描述 settlement 模块的 service 层设计，遵循职责分离原则，每个函数职责单一、可测试。

函数列表

1. get_plate_order_summary_by_customer

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

参数:

• merchant_id: int - 商户ID
• settlement_date: datetime.date - 统计日期
• user: User | None - 当前用户（用于客户可见性过滤）

返回:

• list[dict] - 客户统计列表

职责:

• 参数验证
• 调用底层数据查询函数
• 应用客户可见性过滤
• 数据格式化

参数校验规则:

• merchant_id 必须是正整数
• settlement_date 必须是 date 或 datetime 类型（datetime 会自动转换为 date）
• 参数非法时抛出 ValueError

---

2. _get_plate_order_queryset

获取开版订单的基础查询集。

参数:

• merchant_id: int - 商户ID
• user: User | None - 当前用户（用于客户可见性过滤）

返回:

• QuerySet[PlateOrder] - 过滤后的查询集

职责:

• 应用商户隔离
• 应用客户可见性过滤
• 过滤 plate_type 不为空的订单
• 过滤 production_method 不为空的订单
• 优化查询（select_related）

---

3. _get_month_date_range

获取从月初到指定日期的日期范围。

参数:

• settlement_date: datetime.date - 统计日期

返回:

• tuple[date, date] - (月初日期, 统计日期)

职责:

• 计算当月第一天
• 返回日期范围元组

---

4. _aggregate_plate_orders_by_customer_and_type

按客户和类型分组聚合订单数据。

参数:

• queryset: QuerySet[PlateOrder] - 基础查询集
• settlement_date: datetime.date - 统计日期

返回:

• QuerySet[PlateOrder] - 添加了聚合标注的查询集

职责:

• 按 customer_id、customer_name、plate_type、production_method 分组
• 计算今日数量（条件聚合）
• 计算本月累计数量（条件聚合）
• 生成 type 字段（plate_type + '-' + production_method）

---

5. _format_plate_order_summary

格式化聚合结果为 API 返回格式。

参数:

• aggregated_data: QuerySet[PlateOrder] - 聚合后的查询集

返回:

• list[dict] - 格式化后的数据

职责:

• 遍历聚合结果
• 按客户分组
• 返回客户ID（client_id）和客户名称（client_name）
• 过滤全0数据
• 生成最终的 API 返回格式

---

6. _filter_zero_data

过滤全0数据。

参数:

• plate_order_counts: list[dict] - 订单统计列表

返回:

• list[dict] - 过滤后的列表

职责:

• 移除 today 和 current_month 都为 0 的数据

---

数据流程

get_plate_order_summary_by_customer
    ↓
_get_plate_order_queryset (获取基础查询集)
    ↓
_aggregate_plate_orders_by_customer_and_type (分组聚合)
    ↓
    _get_month_date_range (获取日期范围)
    ↓
_format_plate_order_summary (格式化结果)
    ↓
    _filter_zero_data (过滤全0数据)

过滤规则

1. 商户隔离: 只查询指定商户的订单
2. plate_type 过滤: plate_type 为空的订单不纳入统计
3. production_method 过滤: production_method 为空的订单不纳入统计
4. 客户可见性: 非超级用户只能看到自己创建的客户或被授权可见的客户
5. 全0数据过滤: today 和 current_month 都为 0 的类型组合不返回
6. 客户分组稳健性: 以 customer_id 分组，避免同名客户被合并

type 组合规则

格式: {plate_type}-{production_method}

plate_type 可能的值:

• 首版
• 修改

production_method 可能的值:

• 定位
• 匹布

组合示例:

• 首版-定位
• 首版-匹布
• 修改-定位
• 修改-匹布

测试策略

每个函数都应该有独立的单元测试：

• _get_plate_order_queryset: 测试商户隔离、客户可见性过滤、plate_type 和 production_method 过滤
• _get_month_date_range: 测试日期范围计算
• _aggregate_plate_orders_by_customer_and_type: 测试分组聚合逻辑
• _format_plate_order_summary: 测试数据格式化
• _filter_zero_data: 测试全0数据过滤
• get_plate_order_summary_by_customer: 集成测试

性能优化

1. 使用 select_related 减少查询次数
2. 使用 annotate 和聚合函数避免 N+1 查询
3. 使用条件聚合（Case/When）一次查询获取 today 和 current_month

PostgreSQL 优化评估记录

1. 已评估数据库层优化（索引、视图、物化视图）
2. 当前决策：暂不实施结构性优化，优先保持线上稳定性
3. 后续若优化，优先级为：索引 > 表达式索引 > 物化视图
4. 生产约束：索引变更需使用并发建索引方式并在低峰执行