1069 lines
40 KiB
Markdown
1069 lines
40 KiB
Markdown
# 技术设计文档 — RNS1.2：客户与助教接口
|
||
|
||
## 概述
|
||
|
||
RNS1.2 实现客户详情（CUST-1）、客户服务记录（CUST-2）、助教详情（COACH-1）3 个接口，覆盖 6 个任务：
|
||
|
||
1. **T2-1 CUST-1 客户详情**：Banner 概览 + AI 洞察 + 维客线索 + 消费记录嵌套结构 + 备注
|
||
2. **T2-2 CUST-1 coachTasks**：关联助教任务列表（近 60 天统计）
|
||
3. **T2-3 CUST-1 favoriteCoaches**：最亲密助教（关系指数排序）
|
||
4. **T2-4 CUST-2 客户服务记录**：按月查询 + 月度统计汇总
|
||
5. **T2-5 COACH-1 助教详情**：绩效 + 收入 + 档位 + TOP 客户 + 任务分组 + 备注
|
||
6. **T2-6 COACH-1 historyMonths**：历史月份统计（最近 5+ 个月）
|
||
|
||
### 设计原则
|
||
|
||
- **增量扩展**：在现有 `fdw_queries.py` 基础上新增查询方法，新建 `customer_service.py` 和 `coach_service.py`
|
||
- **FDW 查询集中化**：所有 ETL 查询封装在 `fdw_queries.py`，路由层不直接操作数据库
|
||
- **DWD-DOC 强制规则**：金额 `items_sum` 口径、助教费用 `assistant_pd_money` + `assistant_cx_money` 拆分、会员信息通过 `member_id` JOIN `v_dim_member`
|
||
- **契约驱动**：响应结构严格遵循 `API-contract.md` 中 CUST-1、CUST-2、COACH-1 定义
|
||
- **优雅降级**：扩展模块查询失败返回空默认值，不影响核心响应
|
||
|
||
### 依赖
|
||
|
||
- RNS1.0 已完成：`ResponseWrapperMiddleware`、`CamelModel`、前端 `request()` 解包
|
||
- 现有代码：`fdw_queries.py`（已有 6 个查询函数）、`task_manager.py`、`note_service.py`
|
||
- RNS1.1 可并行：无直接依赖
|
||
|
||
## 架构
|
||
|
||
### 模块交互
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "微信小程序"
|
||
A[customer-detail 页面] --> B[services/api.ts]
|
||
C[customer-service-records 页面] --> B
|
||
D[coach-detail 页面] --> B
|
||
end
|
||
|
||
subgraph "FastAPI 后端"
|
||
E[routers/xcx_customers.py<br/>CUST-1, CUST-2 — 新增]
|
||
F[routers/xcx_coaches.py<br/>COACH-1 — 新增]
|
||
G[services/customer_service.py<br/>客户查询 — 新增]
|
||
H[services/coach_service.py<br/>助教查询 — 新增]
|
||
I[services/fdw_queries.py<br/>FDW 查询封装 — 扩展]
|
||
J[services/note_service.py<br/>备注查询 — 已有]
|
||
end
|
||
|
||
subgraph "数据库"
|
||
K[(zqyy_app<br/>biz.coach_tasks<br/>biz.ai_cache<br/>biz.notes<br/>public.member_retention_clue)]
|
||
L[(etl_feiqiu 直连<br/>app.v_dwd_assistant_service_log<br/>app.v_dws_assistant_salary_calc<br/>app.v_dws_member_assistant_relation_index<br/>app.v_dws_member_consumption_summary<br/>app.v_dim_member<br/>app.v_dim_member_card_account<br/>app.v_dim_assistant<br/>app.v_dwd_table_fee_log)]
|
||
end
|
||
|
||
B -->|HTTP JSON| E
|
||
B -->|HTTP JSON| F
|
||
E --> G
|
||
F --> H
|
||
G --> I
|
||
H --> I
|
||
G --> K
|
||
H --> K
|
||
G --> J
|
||
H --> J
|
||
I -->|直连 ETL + SET LOCAL| L
|
||
|
||
style E fill:#9f9,stroke:#333
|
||
style F fill:#9f9,stroke:#333
|
||
style G fill:#9f9,stroke:#333
|
||
style H fill:#9f9,stroke:#333
|
||
```
|
||
|
||
### 请求流程（以 CUST-1 为例）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant MP as 小程序
|
||
participant R as xcx_customers Router
|
||
participant CS as customer_service
|
||
participant FDW as fdw_queries
|
||
participant BIZ as zqyy_app
|
||
participant ETL as etl_feiqiu 直连
|
||
|
||
MP->>R: GET /api/xcx/customers/{customerId}
|
||
R->>CS: get_customer_detail(customerId, site_id)
|
||
|
||
par 基础信息 + Banner
|
||
CS->>FDW: get_member_info([customerId])
|
||
FDW->>ETL: SET LOCAL + SELECT v_dim_member
|
||
CS->>FDW: get_member_balance([customerId])
|
||
FDW->>ETL: SELECT v_dim_member_card_account
|
||
CS->>FDW: get_last_visit_days([customerId])
|
||
FDW->>ETL: SELECT v_dwd_assistant_service_log
|
||
CS->>FDW: get_consumption_60d(customerId)
|
||
FDW->>ETL: SELECT v_dws_member_consumption_summary
|
||
end
|
||
|
||
par 扩展模块（优雅降级）
|
||
CS->>BIZ: SELECT ai_cache (aiInsight)
|
||
CS->>BIZ: SELECT member_retention_clue (retentionClues)
|
||
CS->>BIZ: SELECT notes (备注)
|
||
CS->>FDW: get_consumption_records(customerId)
|
||
FDW->>ETL: SELECT v_dwd_assistant_service_log + JOIN
|
||
CS->>BIZ: SELECT coach_tasks (coachTasks)
|
||
CS->>FDW: get_favorite_coaches(customerId)
|
||
FDW->>ETL: SELECT v_dws_member_assistant_relation_index
|
||
end
|
||
|
||
CS-->>R: CustomerDetailResponse
|
||
R-->>MP: { code: 0, data: CustomerDetailResponse }
|
||
```
|
||
|
||
## 组件与接口
|
||
|
||
### 组件 1：xcx_customers Router（新增）
|
||
|
||
**位置**：`apps/backend/app/routers/xcx_customers.py`
|
||
|
||
**职责**：客户详情和客户服务记录两个端点。
|
||
|
||
```python
|
||
router = APIRouter(prefix="/api/xcx/customers", tags=["小程序客户"])
|
||
|
||
@router.get("/{customer_id}", response_model=CustomerDetailResponse)
|
||
async def get_customer_detail(
|
||
customer_id: int,
|
||
user: CurrentUser = Depends(require_approved()),
|
||
):
|
||
"""客户详情（CUST-1）。"""
|
||
return await customer_service.get_customer_detail(
|
||
customer_id, user.site_id
|
||
)
|
||
|
||
@router.get("/{customer_id}/records", response_model=CustomerRecordsResponse)
|
||
async def get_customer_records(
|
||
customer_id: int,
|
||
year: int = Query(...),
|
||
month: int = Query(..., ge=1, le=12),
|
||
table: str | None = Query(None),
|
||
page: int = Query(1, ge=1),
|
||
page_size: int = Query(20, ge=1, le=100),
|
||
user: CurrentUser = Depends(require_approved()),
|
||
):
|
||
"""客户服务记录（CUST-2）。"""
|
||
return await customer_service.get_customer_records(
|
||
customer_id, user.site_id, year, month, table, page, page_size
|
||
)
|
||
```
|
||
|
||
**注册**（`main.py`）：
|
||
```python
|
||
from app.routers import xcx_customers
|
||
app.include_router(xcx_customers.router)
|
||
```
|
||
|
||
### 组件 2：xcx_coaches Router（新增）
|
||
|
||
**位置**：`apps/backend/app/routers/xcx_coaches.py`
|
||
|
||
**职责**：助教详情端点。
|
||
|
||
```python
|
||
router = APIRouter(prefix="/api/xcx/coaches", tags=["小程序助教"])
|
||
|
||
@router.get("/{coach_id}", response_model=CoachDetailResponse)
|
||
async def get_coach_detail(
|
||
coach_id: int,
|
||
user: CurrentUser = Depends(require_approved()),
|
||
):
|
||
"""助教详情（COACH-1）。"""
|
||
return await coach_service.get_coach_detail(
|
||
coach_id, user.site_id
|
||
)
|
||
```
|
||
|
||
**注册**（`main.py`）：
|
||
```python
|
||
from app.routers import xcx_coaches
|
||
app.include_router(xcx_coaches.router)
|
||
```
|
||
|
||
### 组件 3：customer_service（新增）
|
||
|
||
**位置**：`apps/backend/app/services/customer_service.py`
|
||
|
||
**核心函数**：
|
||
|
||
```python
|
||
async def get_customer_detail(customer_id: int, site_id: int) -> dict:
|
||
"""
|
||
客户详情（CUST-1）。
|
||
1. fdw_queries.get_member_info() → 基础信息（name/phone/avatar/memberLevel）
|
||
2. fdw_queries.get_member_balance() → balance
|
||
3. fdw_queries.get_consumption_60d() → consumption60d
|
||
4. fdw_queries.get_last_visit_days() → daysSinceVisit
|
||
5. biz.ai_cache → aiInsight（cache_type='app4_analysis'）
|
||
6. public.member_retention_clue → retentionClues
|
||
7. biz.coach_tasks + FDW 聚合 → coachTasks
|
||
8. fdw_queries.get_favorite_coaches() → favoriteCoaches
|
||
9. fdw_queries.get_consumption_records() → consumptionRecords
|
||
10. biz.notes → notes（target_type='member'，最多 20 条）
|
||
扩展模块（5-10）查询失败返回空默认值。
|
||
"""
|
||
|
||
async def get_customer_records(
|
||
customer_id: int, site_id: int,
|
||
year: int, month: int,
|
||
table: str | None,
|
||
page: int, page_size: int,
|
||
) -> dict:
|
||
"""
|
||
客户服务记录（CUST-2）。
|
||
1. fdw_queries.get_member_info() → customerName/customerPhone
|
||
2. fdw_queries.get_customer_service_records() → 按月分页记录
|
||
3. 聚合 monthCount/monthHours
|
||
4. fdw_queries.get_total_service_count() → totalServiceCount（跨月）
|
||
5. 返回 { customerName, records, monthCount, monthHours, totalServiceCount, hasMore }
|
||
"""
|
||
|
||
def _build_coach_tasks(customer_id: int, site_id: int, conn) -> list[dict]:
|
||
"""
|
||
构建 coachTasks 模块。
|
||
1. 查询 biz.coach_tasks WHERE member_id=customer_id
|
||
2. 对每位助教：fdw_queries 获取等级、近 60 天统计
|
||
3. 映射 levelColor/taskColor/bgClass
|
||
"""
|
||
|
||
def _build_favorite_coaches(customer_id: int, site_id: int, conn) -> list[dict]:
|
||
"""
|
||
构建 favoriteCoaches 模块。
|
||
1. fdw_queries.get_relation_index() → 关系指数列表
|
||
2. 按关系指数降序排列
|
||
3. 映射 emoji（≥0.7→💖，<0.7→💛）、indexColor、bgClass
|
||
4. fdw_queries 聚合 stats（基础课时/激励课时/上课次数/充值金额）
|
||
"""
|
||
|
||
def _build_consumption_records(customer_id: int, site_id: int, conn) -> list[dict]:
|
||
"""
|
||
构建 consumptionRecords 模块。
|
||
1. fdw_queries.get_consumption_records() → 结算单列表
|
||
2. 对每条结算单：关联 v_dwd_assistant_service_log 获取 coaches 子数组
|
||
3. coaches[].fee 使用 assistant_pd_money / assistant_cx_money 拆分
|
||
4. totalAmount 使用 items_sum 口径
|
||
5. 过滤 settle_type IN (1, 3)，排除 is_delete != 0
|
||
"""
|
||
```
|
||
|
||
### 组件 4：coach_service（新增）
|
||
|
||
**位置**：`apps/backend/app/services/coach_service.py`
|
||
|
||
**核心函数**：
|
||
|
||
```python
|
||
async def get_coach_detail(coach_id: int, site_id: int) -> dict:
|
||
"""
|
||
助教详情（COACH-1）。
|
||
1. fdw_queries.get_assistant_info() → 基础信息
|
||
2. fdw_queries.get_salary_calc() → 绩效/收入/档位（当月+上月）
|
||
3. fdw_queries.get_member_balance() → customerBalance（该助教所有客户余额合计）
|
||
4. biz.coach_tasks → tasksCompleted + 任务分组
|
||
5. fdw_queries.get_top_customers() → topCustomers
|
||
6. fdw_queries.get_service_records() → serviceRecords
|
||
7. _build_history_months() → historyMonths
|
||
8. biz.notes → notes（最多 20 条）
|
||
扩展模块查询失败返回空默认值。
|
||
"""
|
||
|
||
def _build_income(salary_this: dict, salary_last: dict) -> dict:
|
||
"""
|
||
构建 income 模块。
|
||
thisMonth/lastMonth 各含 4 项：
|
||
- 基础课时费（assistant_pd_money / base_income）
|
||
- 激励课时费（assistant_cx_money / bonus_income）
|
||
- 充值提成（从 salary_calc 获取）
|
||
- 酒水提成（从 salary_calc 获取）
|
||
"""
|
||
|
||
def _build_task_groups(coach_id: int, site_id: int, conn) -> dict:
|
||
"""
|
||
构建任务分组。
|
||
1. 查询 biz.coach_tasks WHERE assistant_id=coach_id
|
||
2. 按 status 分组：active→visibleTasks, inactive→hiddenTasks, abandoned→abandonedTasks
|
||
3. 对 visible/hidden：关联 biz.notes 获取备注列表
|
||
4. 对 abandoned：取 abandon_reason
|
||
"""
|
||
|
||
def _build_history_months(coach_id: int, site_id: int, conn) -> list[dict]:
|
||
"""
|
||
构建 historyMonths 模块。
|
||
1. fdw_queries.get_salary_calc_multi_months() → 最近 6 个月工时/工资
|
||
2. fdw_queries.get_monthly_customer_count() → 各月客户数
|
||
3. biz.coach_tasks → 各月回访/召回完成数
|
||
4. 本月 estimated=True，历史月份 estimated=False
|
||
5. 格式化：customers→"22人"，hours→"87.5h"，salary→"¥6,950"
|
||
"""
|
||
|
||
def _build_top_customers(coach_id: int, site_id: int, conn) -> list[dict]:
|
||
"""
|
||
构建 topCustomers 模块（最多 20 条）。
|
||
1. fdw_queries.get_coach_top_customers() → 按服务次数/消费排序
|
||
2. fdw_queries.get_member_info() → 客户姓名（DQ-6）
|
||
3. fdw_queries.get_member_balance() → 余额（DQ-7）
|
||
4. 映射 heartEmoji（≥0.7→❤️，0.3-0.7→💛，<0.3→🤍）
|
||
5. consume 使用 items_sum 口径
|
||
"""
|
||
```
|
||
|
||
### 组件 5：fdw_queries 扩展
|
||
|
||
**位置**：`apps/backend/app/services/fdw_queries.py`（在现有模块上新增函数）
|
||
|
||
**新增函数**：
|
||
|
||
```python
|
||
def get_consumption_60d(conn, site_id: int, member_id: int) -> Decimal | None:
|
||
"""
|
||
查询客户近 60 天消费金额。
|
||
来源：app.v_dwd_assistant_service_log。
|
||
⚠️ DWD-DOC 规则 1：使用 ledger_amount（items_sum 口径）。
|
||
⚠️ 废单排除：is_delete = 0。
|
||
"""
|
||
|
||
def get_relation_index(
|
||
conn, site_id: int, member_id: int
|
||
) -> list[dict]:
|
||
"""
|
||
查询客户与助教的关系指数列表。
|
||
来源：app.v_dws_member_assistant_relation_index。
|
||
返回 [{assistant_id, relation_index, ...}]，按 relation_index 降序。
|
||
"""
|
||
|
||
def get_consumption_records(
|
||
conn, site_id: int, member_id: int, limit: int, offset: int
|
||
) -> list[dict]:
|
||
"""
|
||
查询客户消费记录（嵌套结构用）。
|
||
来源：app.v_dwd_assistant_service_log + v_dwd_table_fee_log。
|
||
⚠️ DWD-DOC 规则 1：totalAmount 使用 ledger_amount。
|
||
⚠️ DWD-DOC 规则 2：coaches fee 使用 assistant_pd_money / assistant_cx_money。
|
||
⚠️ 废单排除：is_delete = 0。
|
||
⚠️ 正向交易：settle_type IN (1, 3)。
|
||
"""
|
||
|
||
def get_customer_service_records(
|
||
conn, site_id: int, member_id: int,
|
||
year: int, month: int,
|
||
table: str | None, limit: int, offset: int
|
||
) -> tuple[list[dict], int]:
|
||
"""
|
||
查询客户按月服务记录（CUST-2 用）。
|
||
来源：app.v_dwd_assistant_service_log。
|
||
返回 (records, total_count)。
|
||
⚠️ DQ-6：助教姓名通过 site_assistant_id JOIN v_dim_assistant。
|
||
⚠️ 废单排除：is_delete = 0。
|
||
"""
|
||
|
||
def get_total_service_count(conn, site_id: int, member_id: int) -> int:
|
||
"""
|
||
查询客户累计服务总次数（跨所有月份）。
|
||
来源：app.v_dwd_assistant_service_log，COUNT WHERE is_delete = 0。
|
||
"""
|
||
|
||
def get_assistant_info(conn, site_id: int, assistant_id: int) -> dict | None:
|
||
"""
|
||
查询助教基本信息。
|
||
来源：app.v_dim_assistant。
|
||
返回 {name, avatar, skills, work_years, hire_date}。
|
||
"""
|
||
|
||
def get_salary_calc_multi_months(
|
||
conn, site_id: int, assistant_id: int, months: list[str]
|
||
) -> dict[str, dict]:
|
||
"""
|
||
批量查询多个月份的绩效数据。
|
||
来源：app.v_dws_assistant_salary_calc。
|
||
返回 {month_str: salary_data}。
|
||
"""
|
||
|
||
def get_monthly_customer_count(
|
||
conn, site_id: int, assistant_id: int, months: list[str]
|
||
) -> dict[str, int]:
|
||
"""
|
||
批量查询各月不重复客户数。
|
||
来源：app.v_dwd_assistant_service_log，COUNT(DISTINCT tenant_member_id)。
|
||
⚠️ 废单排除：is_delete = 0。
|
||
"""
|
||
|
||
def get_coach_top_customers(
|
||
conn, site_id: int, assistant_id: int, limit: int = 20
|
||
) -> list[dict]:
|
||
"""
|
||
查询助教 TOP 客户（按服务次数降序）。
|
||
来源：app.v_dwd_assistant_service_log + v_dim_member + v_dim_member_card_account。
|
||
⚠️ DQ-6：客户姓名通过 tenant_member_id JOIN v_dim_member。
|
||
⚠️ DQ-7：余额通过 tenant_member_id JOIN v_dim_member_card_account。
|
||
⚠️ DWD-DOC 规则 1：consume 使用 ledger_amount（items_sum 口径）。
|
||
⚠️ 废单排除：is_delete = 0。
|
||
"""
|
||
|
||
def get_coach_60d_stats(
|
||
conn, site_id: int, assistant_id: int, member_id: int
|
||
) -> dict:
|
||
"""
|
||
查询特定助教对特定客户的近 60 天统计。
|
||
返回 {service_count, total_hours, avg_hours}。
|
||
来源：app.v_dwd_assistant_service_log。
|
||
⚠️ 废单排除：is_delete = 0。
|
||
"""
|
||
```
|
||
|
||
### 组件 6：Pydantic Schema（新增）
|
||
|
||
**位置**：`apps/backend/app/schemas/xcx_customers.py`（新增）+ `apps/backend/app/schemas/xcx_coaches.py`（新增）
|
||
|
||
#### 客户相关 Schema
|
||
|
||
```python
|
||
# ── xcx_customers.py ──
|
||
|
||
class AiInsight(CamelModel):
|
||
summary: str = ""
|
||
strategies: list[AiStrategy] = []
|
||
|
||
class AiStrategy(CamelModel):
|
||
color: str
|
||
text: str
|
||
|
||
class MetricItem(CamelModel):
|
||
label: str
|
||
value: str
|
||
color: str | None = None
|
||
|
||
class CoachTask(CamelModel):
|
||
name: str
|
||
level: str # star / senior / middle / junior
|
||
level_color: str
|
||
task_type: str
|
||
task_color: str
|
||
bg_class: str
|
||
status: str
|
||
last_service: str | None = None
|
||
metrics: list[MetricItem] = []
|
||
|
||
class FavoriteCoach(CamelModel):
|
||
emoji: str # 💖 / 💛
|
||
name: str
|
||
relation_index: str
|
||
index_color: str
|
||
bg_class: str
|
||
stats: list[MetricItem] = []
|
||
|
||
class CoachServiceItem(CamelModel):
|
||
name: str
|
||
level: str
|
||
level_color: str
|
||
course_type: str # "基础课" / "激励课"
|
||
hours: float
|
||
perf_hours: float | None = None
|
||
fee: float
|
||
|
||
class ConsumptionRecord(CamelModel):
|
||
id: str
|
||
type: str # table / shop / recharge
|
||
date: str
|
||
table_name: str | None = None
|
||
start_time: str | None = None
|
||
end_time: str | None = None
|
||
duration: int | None = None
|
||
table_fee: float | None = None
|
||
table_orig_price: float | None = None
|
||
coaches: list[CoachServiceItem] = []
|
||
food_amount: float | None = None
|
||
food_orig_price: float | None = None
|
||
total_amount: float
|
||
total_orig_price: float
|
||
pay_method: str
|
||
recharge_amount: float | None = None
|
||
|
||
class RetentionClue(CamelModel):
|
||
type: str
|
||
text: str
|
||
|
||
class CustomerNote(CamelModel):
|
||
id: int
|
||
tag_label: str
|
||
created_at: str
|
||
content: str
|
||
|
||
class CustomerDetailResponse(CamelModel):
|
||
"""CUST-1 响应。"""
|
||
# 基础信息
|
||
id: int
|
||
name: str
|
||
phone: str
|
||
phone_full: str
|
||
avatar: str
|
||
member_level: str
|
||
relation_index: str
|
||
tags: list[str] = []
|
||
# Banner 概览
|
||
balance: float | None = None
|
||
consumption_60d: float | None = None
|
||
ideal_interval: int | None = None
|
||
days_since_visit: int | None = None
|
||
# 扩展模块
|
||
ai_insight: AiInsight = AiInsight()
|
||
coach_tasks: list[CoachTask] = []
|
||
favorite_coaches: list[FavoriteCoach] = []
|
||
retention_clues: list[RetentionClue] = []
|
||
consumption_records: list[ConsumptionRecord] = []
|
||
notes: list[CustomerNote] = []
|
||
|
||
class ServiceRecordItem(CamelModel):
|
||
id: str
|
||
date: str
|
||
time_range: str | None = None
|
||
table: str | None = None
|
||
type: str
|
||
type_class: str
|
||
record_type: str | None = None # course / recharge
|
||
duration: float
|
||
duration_raw: float | None = None
|
||
income: float
|
||
is_estimate: bool = False
|
||
drinks: str | None = None
|
||
|
||
class CustomerRecordsResponse(CamelModel):
|
||
"""CUST-2 响应。"""
|
||
customer_name: str
|
||
customer_phone: str
|
||
customer_phone_full: str
|
||
relation_index: str
|
||
tables: list[dict] = []
|
||
total_service_count: int
|
||
month_count: int
|
||
month_hours: float
|
||
records: list[ServiceRecordItem] = []
|
||
has_more: bool = False
|
||
```
|
||
|
||
#### 助教相关 Schema
|
||
|
||
```python
|
||
# ── xcx_coaches.py ──
|
||
|
||
class PerformanceMetrics(CamelModel):
|
||
monthly_hours: float
|
||
monthly_salary: float
|
||
customer_balance: float
|
||
tasks_completed: int
|
||
perf_current: float
|
||
perf_target: float
|
||
|
||
class IncomeItem(CamelModel):
|
||
label: str
|
||
amount: str
|
||
color: str
|
||
|
||
class IncomeSection(CamelModel):
|
||
this_month: list[IncomeItem] = []
|
||
last_month: list[IncomeItem] = []
|
||
|
||
class CoachTaskItem(CamelModel):
|
||
type_label: str
|
||
type_class: str
|
||
customer_name: str
|
||
customer_id: int | None = None
|
||
note_count: int = 0
|
||
pinned: bool = False
|
||
notes: list[dict] | None = None
|
||
|
||
class AbandonedTask(CamelModel):
|
||
customer_name: str
|
||
reason: str
|
||
|
||
class TopCustomer(CamelModel):
|
||
id: int
|
||
name: str
|
||
initial: str
|
||
avatar_gradient: str
|
||
heart_emoji: str # ❤️ / 💛 / 🤍
|
||
score: str
|
||
score_color: str
|
||
service_count: int
|
||
balance: str
|
||
consume: str
|
||
|
||
class CoachServiceRecord(CamelModel):
|
||
customer_id: int | None = None
|
||
customer_name: str
|
||
initial: str
|
||
avatar_gradient: str
|
||
type: str
|
||
type_class: str
|
||
table: str | None = None
|
||
duration: str
|
||
income: str
|
||
date: str
|
||
perf_hours: str | None = None
|
||
|
||
class HistoryMonth(CamelModel):
|
||
month: str
|
||
estimated: bool
|
||
customers: str
|
||
hours: str
|
||
salary: str
|
||
callback_done: int
|
||
recall_done: int
|
||
|
||
class CoachNoteItem(CamelModel):
|
||
id: int
|
||
content: str
|
||
timestamp: str
|
||
score: int | None = None
|
||
customer_name: str
|
||
tag_label: str
|
||
created_at: str
|
||
|
||
class CoachDetailResponse(CamelModel):
|
||
"""COACH-1 响应。"""
|
||
# 基础信息
|
||
id: int
|
||
name: str
|
||
avatar: str
|
||
level: str
|
||
skills: list[str] = []
|
||
work_years: float = 0
|
||
customer_count: int = 0
|
||
hire_date: str | None = None
|
||
# 绩效
|
||
performance: PerformanceMetrics
|
||
# 收入
|
||
income: IncomeSection
|
||
# 档位
|
||
tier_nodes: list[float] = []
|
||
# 任务分组
|
||
visible_tasks: list[CoachTaskItem] = []
|
||
hidden_tasks: list[CoachTaskItem] = []
|
||
abandoned_tasks: list[AbandonedTask] = []
|
||
# TOP 客户
|
||
top_customers: list[TopCustomer] = []
|
||
# 近期服务记录
|
||
service_records: list[CoachServiceRecord] = []
|
||
# 历史月份
|
||
history_months: list[HistoryMonth] = []
|
||
# 备注
|
||
notes: list[CoachNoteItem] = []
|
||
```
|
||
|
||
## 数据模型
|
||
|
||
### FDW 查询模式
|
||
|
||
所有 FDW 查询遵循 `fdw_queries.py` 已有的统一模式：
|
||
|
||
```python
|
||
# 通过 _fdw_context() 上下文管理器：
|
||
# 1. 获取 ETL 直连（get_etl_readonly_connection(site_id)）
|
||
# 2. BEGIN + SET LOCAL app.current_site_id = site_id
|
||
# 3. 执行查询
|
||
# 4. COMMIT + 关闭连接
|
||
with _fdw_context(conn, site_id) as cur:
|
||
cur.execute("SELECT ... FROM app.v_* WHERE ...", params)
|
||
```
|
||
|
||
### 核心 SQL 查询设计
|
||
|
||
#### Q1: 客户近 60 天消费（CUST-1 Banner）
|
||
|
||
```sql
|
||
-- ⚠️ DWD-DOC 规则 1: 使用 ledger_amount（items_sum 口径）
|
||
-- ⚠️ 废单排除: is_delete = 0
|
||
SELECT COALESCE(SUM(ledger_amount), 0) AS consumption_60d
|
||
FROM app.v_dwd_assistant_service_log
|
||
WHERE tenant_member_id = %s
|
||
AND is_delete = 0
|
||
AND create_time >= (CURRENT_DATE - INTERVAL '60 days')::timestamptz
|
||
```
|
||
|
||
#### Q2: 关系指数查询（CUST-1 favoriteCoaches）
|
||
|
||
```sql
|
||
-- 按关系指数降序排列
|
||
SELECT site_assistant_id AS assistant_id,
|
||
relation_index,
|
||
service_count,
|
||
total_hours,
|
||
total_income
|
||
FROM app.v_dws_member_assistant_relation_index
|
||
WHERE tenant_member_id = %s
|
||
ORDER BY relation_index DESC
|
||
```
|
||
|
||
#### Q3: 消费记录嵌套查询（CUST-1 consumptionRecords）
|
||
|
||
```sql
|
||
-- 主查询：结算单级别
|
||
-- ⚠️ DWD-DOC 规则 1: totalAmount 使用 ledger_amount
|
||
-- ⚠️ 废单排除: is_delete = 0
|
||
SELECT sl.assistant_service_id AS id,
|
||
sl.create_time AS settle_time,
|
||
sl.start_use_time AS start_time,
|
||
sl.last_use_time AS end_time,
|
||
sl.income_seconds / 3600.0 AS service_hours,
|
||
sl.ledger_amount AS total_amount,
|
||
sl.skill_name AS course_type,
|
||
sl.site_table_id AS table_id,
|
||
sl.site_assistant_id AS assistant_id,
|
||
da.assistant_name,
|
||
da.assistant_level_name AS level
|
||
FROM app.v_dwd_assistant_service_log sl
|
||
LEFT JOIN app.v_dim_assistant da
|
||
ON sl.site_assistant_id = da.assistant_id
|
||
WHERE sl.tenant_member_id = %s
|
||
AND sl.is_delete = 0
|
||
ORDER BY sl.create_time DESC
|
||
LIMIT %s OFFSET %s
|
||
```
|
||
|
||
#### Q4: 客户按月服务记录（CUST-2）
|
||
|
||
```sql
|
||
-- ⚠️ DQ-6: 助教姓名通过 v_dim_assistant 获取
|
||
-- ⚠️ DWD-DOC 规则 1: income 使用 ledger_amount
|
||
-- ⚠️ 废单排除: is_delete = 0
|
||
SELECT sl.assistant_service_id AS id,
|
||
sl.create_time,
|
||
sl.start_use_time,
|
||
sl.last_use_time,
|
||
sl.income_seconds / 3600.0 AS service_hours,
|
||
sl.real_use_seconds / 3600.0 AS service_hours_raw,
|
||
sl.ledger_amount AS income,
|
||
sl.skill_name AS course_type,
|
||
sl.site_table_id AS table_id,
|
||
da.assistant_name
|
||
FROM app.v_dwd_assistant_service_log sl
|
||
LEFT JOIN app.v_dim_assistant da
|
||
ON sl.site_assistant_id = da.assistant_id
|
||
WHERE sl.tenant_member_id = %s
|
||
AND sl.is_delete = 0
|
||
AND sl.create_time >= %s::timestamptz
|
||
AND sl.create_time < %s::timestamptz
|
||
ORDER BY sl.create_time DESC
|
||
LIMIT %s OFFSET %s
|
||
|
||
-- 月度统计汇总
|
||
SELECT COUNT(*) AS month_count,
|
||
COALESCE(SUM(income_seconds / 3600.0), 0) AS month_hours
|
||
FROM app.v_dwd_assistant_service_log
|
||
WHERE tenant_member_id = %s
|
||
AND is_delete = 0
|
||
AND create_time >= %s::timestamptz
|
||
AND create_time < %s::timestamptz
|
||
|
||
-- 累计服务总次数
|
||
SELECT COUNT(*) AS total_service_count
|
||
FROM app.v_dwd_assistant_service_log
|
||
WHERE tenant_member_id = %s AND is_delete = 0
|
||
```
|
||
|
||
#### Q5: 助教基本信息（COACH-1）
|
||
|
||
```sql
|
||
SELECT assistant_id,
|
||
assistant_name AS name,
|
||
assistant_level_name AS level,
|
||
-- skills/work_years/hire_date 视图中可能不存在，使用默认值
|
||
created_at AS hire_date
|
||
FROM app.v_dim_assistant
|
||
WHERE assistant_id = %s
|
||
```
|
||
|
||
#### Q6: 助教 TOP 客户（COACH-1）
|
||
|
||
```sql
|
||
-- ⚠️ DQ-6: 客户姓名通过 tenant_member_id JOIN v_dim_member
|
||
-- ⚠️ DQ-7: 余额通过 tenant_member_id JOIN v_dim_member_card_account
|
||
-- ⚠️ DWD-DOC 规则 1: consume 使用 ledger_amount
|
||
-- ⚠️ 废单排除: is_delete = 0
|
||
SELECT sl.tenant_member_id AS member_id,
|
||
dm.nickname AS customer_name,
|
||
COUNT(*) AS service_count,
|
||
COALESCE(SUM(sl.ledger_amount), 0) AS total_consume,
|
||
mca.balance AS customer_balance
|
||
FROM app.v_dwd_assistant_service_log sl
|
||
LEFT JOIN app.v_dim_member dm
|
||
ON sl.tenant_member_id = dm.member_id AND dm.scd2_is_current = 1
|
||
LEFT JOIN app.v_dim_member_card_account mca
|
||
ON sl.tenant_member_id = mca.tenant_member_id AND mca.scd2_is_current = 1
|
||
WHERE sl.site_assistant_id = %s
|
||
AND sl.is_delete = 0
|
||
GROUP BY sl.tenant_member_id, dm.nickname, mca.balance
|
||
ORDER BY service_count DESC
|
||
LIMIT %s
|
||
```
|
||
|
||
#### Q7: 历史月份统计（COACH-1 historyMonths）
|
||
|
||
```sql
|
||
-- 多月绩效数据批量查询
|
||
SELECT salary_month,
|
||
effective_hours,
|
||
gross_salary,
|
||
base_income,
|
||
bonus_income
|
||
FROM app.v_dws_assistant_salary_calc
|
||
WHERE assistant_id = %s
|
||
AND salary_month = ANY(%s::date[])
|
||
ORDER BY salary_month DESC
|
||
|
||
-- 各月不重复客户数
|
||
SELECT DATE_TRUNC('month', create_time)::date AS month,
|
||
COUNT(DISTINCT tenant_member_id) AS customer_count
|
||
FROM app.v_dwd_assistant_service_log
|
||
WHERE site_assistant_id = %s
|
||
AND is_delete = 0
|
||
AND create_time >= %s::timestamptz
|
||
AND create_time < %s::timestamptz
|
||
GROUP BY DATE_TRUNC('month', create_time)::date
|
||
```
|
||
|
||
#### Q8: 助教近 60 天统计（CUST-1 coachTasks metrics）
|
||
|
||
```sql
|
||
-- 特定助教对特定客户的近 60 天统计
|
||
-- ⚠️ 废单排除: is_delete = 0
|
||
SELECT COUNT(*) AS service_count,
|
||
COALESCE(SUM(income_seconds / 3600.0), 0) AS total_hours,
|
||
CASE WHEN COUNT(*) > 0
|
||
THEN SUM(income_seconds / 3600.0) / COUNT(*)
|
||
ELSE 0 END AS avg_hours
|
||
FROM app.v_dwd_assistant_service_log
|
||
WHERE site_assistant_id = %s
|
||
AND tenant_member_id = %s
|
||
AND is_delete = 0
|
||
AND create_time >= (CURRENT_DATE - INTERVAL '60 days')::timestamptz
|
||
```
|
||
|
||
### 列名映射汇总
|
||
|
||
| 代码语义 | 实际视图列名 | 视图 | 说明 |
|
||
|----------|-------------|------|------|
|
||
| member_id | `tenant_member_id` | v_dwd_assistant_service_log | 会员 ID |
|
||
| assistant_id (WHERE) | `site_assistant_id` | v_dwd_assistant_service_log | 助教 ID |
|
||
| settle_time | `create_time` | v_dwd_assistant_service_log | 结算时间 |
|
||
| income | `ledger_amount` | v_dwd_assistant_service_log | items_sum 口径 |
|
||
| service_hours | `income_seconds / 3600.0` | v_dwd_assistant_service_log | 折算工时 |
|
||
| is_trash=false | `is_delete = 0` | v_dwd_assistant_service_log | 废单排除 |
|
||
| course_type | `skill_name` | v_dwd_assistant_service_log | 课程类型 |
|
||
| calc_month | `salary_month` | v_dws_assistant_salary_calc | 月份（date） |
|
||
| coach_level | `assistant_level_name` | v_dws_assistant_salary_calc | 档位名称 |
|
||
| total_hours | `effective_hours` | v_dws_assistant_salary_calc | 有效总工时 |
|
||
| total_income | `gross_salary` | v_dws_assistant_salary_calc | 总收入 |
|
||
| pd_money_total | `base_income` | v_dws_assistant_salary_calc | 基础课总收入 |
|
||
| cx_money_total | `bonus_income` | v_dws_assistant_salary_calc | 激励课总收入 |
|
||
|
||
### DWD-DOC 强制规则实施位置
|
||
|
||
| 规则 | 实施位置 | 具体措施 |
|
||
|------|---------|---------|
|
||
| 规则 1: `items_sum` 口径 | `fdw_queries.py` 所有金额查询 | SQL 中使用 `ledger_amount`，禁止 `consume_money` |
|
||
| 规则 2: 助教费用拆分 | `fdw_queries.py` + `customer_service.py` | 使用 `base_income`/`bonus_income`，禁止 `service_fee` |
|
||
| DQ-6: 会员信息 JOIN | `fdw_queries.py` 所有含客户姓名的查询 | `tenant_member_id JOIN v_dim_member WHERE scd2_is_current=1` |
|
||
| DQ-7: 会员卡 JOIN | `fdw_queries.py` 余额查询 | `tenant_member_id JOIN v_dim_member_card_account WHERE scd2_is_current=1` |
|
||
| 废单排除 | `fdw_queries.py` 所有服务记录查询 | `WHERE is_delete = 0`，禁止引用 `dwd_assistant_trash_event` |
|
||
|
||
## 正确性属性
|
||
|
||
*属性（Property）是一个在系统所有合法执行路径上都应成立的特征或行为——本质上是对"系统应该做什么"的形式化陈述。属性是人类可读规格与机器可验证正确性保证之间的桥梁。*
|
||
|
||
### Property 1: 消费记录金额拆分不变量
|
||
|
||
*For any* 消费记录，`totalAmount` 应等于 `tableFee + foodAmount + SUM(coaches[].fee)`（在浮点精度 0.01 范围内）。这验证了 `items_sum` 口径拆分的一致性——各子项之和必须等于总额。
|
||
|
||
**Validates: Requirements 14.1, 4.4**
|
||
|
||
### Property 2: 废单排除一致性
|
||
|
||
*For any* 服务记录查询（CUST-1 consumptionRecords、CUST-2 records、COACH-1 serviceRecords/topCustomers），返回的记录集合中不应包含 `is_delete != 0` 的记录。即对所有返回记录，`is_delete` 字段值必须为 0。
|
||
|
||
**Validates: Requirements 14.8, 4.6, 7.8, 10.7**
|
||
|
||
### Property 3: 助教费用拆分正确性
|
||
|
||
*For any* 消费记录中的 `coaches` 子数组，`courseType` 为 `"基础课"` 的记录其 `fee` 应对应 `assistant_pd_money`，`courseType` 为 `"激励课"` 的记录其 `fee` 应对应 `assistant_cx_money`。两者之和应等于该结算单的助教费用总额。
|
||
|
||
**Validates: Requirements 14.2, 4.3, 9.2**
|
||
|
||
### Property 4: favoriteCoaches 排序不变量
|
||
|
||
*For any* CUST-1 响应中的 `favoriteCoaches` 列表，列表应按 `relationIndex` 降序排列——即对于相邻两项 `favoriteCoaches[i]` 和 `favoriteCoaches[i+1]`，`float(favoriteCoaches[i].relationIndex) >= float(favoriteCoaches[i+1].relationIndex)` 恒成立。
|
||
|
||
**Validates: Requirements 14.5, 6.1**
|
||
|
||
### Property 5: historyMonths 排序与预估标记
|
||
|
||
*For any* COACH-1 响应中的 `historyMonths` 列表，列表应按月份降序排列（最近月份在前），且第一条的 `estimated` 必须为 `true`（本月为预估数据），其余条目的 `estimated` 必须为 `false`。
|
||
|
||
**Validates: Requirements 14.6, 12.5**
|
||
|
||
### Property 6: 列表上限约束
|
||
|
||
*For any* CUST-1 响应中的 `notes` 列表长度应 ≤ 20，COACH-1 响应中的 `topCustomers` 列表长度应 ≤ 20，COACH-1 响应中的 `notes` 列表长度应 ≤ 20。即所有带上限的列表返回数量不超过其指定上限。
|
||
|
||
**Validates: Requirements 3.2, 10.1, 11.5**
|
||
|
||
### Property 7: 月度汇总聚合正确性
|
||
|
||
*For any* 服务记录集合，CUST-2 的 `monthCount` 应等于当月返回的记录总数，`monthHours` 应等于当月所有记录 `service_hours` 之和（在浮点精度 0.01 范围内）。同理，CUST-1 coachTasks 的 `metrics` 中近 60 天统计的 `service_count` 应等于实际记录数，`total_hours` 应等于各记录工时之和。
|
||
|
||
**Validates: Requirements 7.6, 5.3**
|
||
|
||
### Property 8: daysSinceVisit 计算正确性
|
||
|
||
*For any* 有效日期 `lastVisitDate`（不晚于今天），`daysSinceVisit` 应等于 `(current_date - lastVisitDate).days`，且结果为非负整数。无服务记录时应返回 `null`。
|
||
|
||
**Validates: Requirements 1.6**
|
||
|
||
### Property 9: emoji 映射正确性
|
||
|
||
*For any* 关系指数值 `relationIndex`（0.0 到 1.0 之间的浮点数）：
|
||
- CUST-1 favoriteCoaches：`relationIndex >= 0.7` 时 `emoji` 应为 `"💖"`，`relationIndex < 0.7` 时应为 `"💛"`
|
||
- COACH-1 topCustomers：`score >= 0.7` 时 `heartEmoji` 应为 `"❤️"`，`0.3 <= score < 0.7` 时应为 `"💛"`，`score < 0.3` 时应为 `"🤍"`
|
||
|
||
映射函数应对相同输入始终产生相同输出（确定性）。
|
||
|
||
**Validates: Requirements 6.4**
|
||
|
||
### Property 10: 优雅降级
|
||
|
||
*For any* 扩展模块（`aiInsight`/`coachTasks`/`favoriteCoaches`/`consumptionRecords`/`historyMonths`）的数据源查询失败时，该模块应返回空默认值（空数组或空对象），不影响其他模块和整体响应的 HTTP 200 状态码。
|
||
|
||
**Validates: Requirements 1.7, 13.8**
|
||
|
||
### Property 11: 任务分组正确性
|
||
|
||
*For any* 助教的任务集合，按 `status` 分组后：`active` 状态任务应全部出现在 `visibleTasks` 中，`inactive` 状态任务应全部出现在 `hiddenTasks` 中，`abandoned` 状态任务应全部出现在 `abandonedTasks` 中。三组之间无交集，且三组之并等于原始任务集合（不含 `completed` 状态）。
|
||
|
||
**Validates: Requirements 11.1**
|
||
|
||
### Property 12: 数据隔离不变量
|
||
|
||
*For any* CUST-1 响应中的 `coachTasks`，每条任务的 `member_id` 应等于请求路径中的 `customerId`。*For any* COACH-1 响应中的 `serviceRecords`，每条记录的 `assistant_id` 应等于请求路径中的 `coachId`。
|
||
|
||
**Validates: Requirements 14.3, 14.4**
|
||
|
||
### Property 13: 分页与 hasMore 正确性
|
||
|
||
*For any* CUST-2 记录集合和分页参数 `(page, pageSize)`，返回的记录数应 ≤ `pageSize`，`hasMore` 为 `true` 当且仅当总记录数 > `page * pageSize`。记录应按 `create_time` 倒序排列。
|
||
|
||
**Validates: Requirements 7.9**
|
||
|
||
### Property 14: 幂等性
|
||
|
||
*For any* 相同参数的 CUST-2 请求（相同 `customerId`、`year`、`month`），在数据未变更的情况下，两次请求应返回相同的 `monthCount` 和 `monthHours` 值。即 `f(x) == f(x)` 对所有合法输入成立。
|
||
|
||
**Validates: Requirements 14.7**
|
||
|
||
## 错误处理
|
||
|
||
### 后端错误处理
|
||
|
||
| 错误场景 | HTTP 状态码 | 响应 | 触发位置 |
|
||
|---------|:----------:|------|---------|
|
||
| 用户未通过审核 | 403 | `{ code: 403, message: "用户未通过审核，无法访问此资源" }` | `require_approved()` |
|
||
| 客户不存在 | 404 | `{ code: 404, message: "客户不存在" }` | `customer_service.get_customer_detail()` |
|
||
| 助教不存在 | 404 | `{ code: 404, message: "助教不存在" }` | `coach_service.get_coach_detail()` |
|
||
| year/month 参数无效 | 422 | Pydantic 验证错误 | FastAPI 参数校验 |
|
||
| page/pageSize 参数无效 | 422 | Pydantic 验证错误 | FastAPI 参数校验 |
|
||
| FDW 查询超时/失败（核心字段） | 500 | `{ code: 500, message: "Internal Server Error" }` | `unhandled_exception_handler` |
|
||
| FDW 查询失败（扩展模块） | 200 | 该模块返回空默认值 | 各 `_build_*` 函数 |
|
||
| 数据库连接失败 | 500 | `{ code: 500, message: "Internal Server Error" }` | `unhandled_exception_handler` |
|
||
|
||
### FDW 查询容错策略
|
||
|
||
**核心字段**（基础信息、Banner 概览）查询失败直接抛出 500。
|
||
|
||
**扩展模块**（aiInsight/coachTasks/favoriteCoaches/consumptionRecords/historyMonths）采用优雅降级：
|
||
|
||
```python
|
||
# 每个扩展模块独立 try/except
|
||
try:
|
||
ai_insight = _build_ai_insight(customer_id, site_id, conn)
|
||
except Exception:
|
||
logger.warning("构建 aiInsight 失败，降级为空", exc_info=True)
|
||
ai_insight = {"summary": "", "strategies": []}
|
||
|
||
try:
|
||
coach_tasks = _build_coach_tasks(customer_id, site_id, conn)
|
||
except Exception:
|
||
logger.warning("构建 coachTasks 失败，降级为空列表", exc_info=True)
|
||
coach_tasks = []
|
||
|
||
# ... 其他扩展模块同理
|
||
```
|
||
|
||
### 前端错误处理
|
||
|
||
| 场景 | 处理方式 |
|
||
|------|---------|
|
||
| API 返回 403 | 显示"权限不足"提示 |
|
||
| API 返回 404 | 显示"数据不存在"提示，返回上一页 |
|
||
| API 返回 500 | 显示"服务器错误"toast |
|
||
| 扩展模块字段为空数组/空对象 | 前端隐藏对应 UI 区域 |
|
||
| 月份切换期间网络失败 | 恢复上一月份状态，显示重试提示 |
|
||
| Banner 字段为 null | 显示 `"--"` 占位符 |
|
||
|
||
## 测试策略
|
||
|
||
### 双轨测试方法
|
||
|
||
RNS1.2 采用属性测试（Property-Based Testing）+ 单元测试（Unit Testing）双轨并行：
|
||
|
||
- **属性测试**：验证金额拆分、排序不变量、聚合正确性、映射函数、分页逻辑等通用规则在所有输入上的正确性
|
||
- **单元测试**：验证具体的 API 端点行为、权限校验、FDW 查询集成、边界条件、优雅降级
|
||
|
||
### 属性测试配置
|
||
|
||
- **测试库**：[Hypothesis](https://hypothesis.readthedocs.io/)（Python，项目已使用）
|
||
- **测试位置**：`tests/` 目录（Monorepo 级属性测试）
|
||
- **最小迭代次数**：每个属性测试 100 次（`@settings(max_examples=100)`）
|
||
- **标签格式**：每个测试函数的 docstring 中标注 `Feature: rns1-customer-coach-api, Property {N}: {property_text}`
|
||
- **每个正确性属性由一个属性测试实现**
|
||
|
||
### 属性测试清单
|
||
|
||
| Property | 测试函数 | 生成器 | 验证逻辑 |
|
||
|----------|---------|--------|---------|
|
||
| P1: 金额拆分不变量 | `test_consumption_amount_split` | `st.floats(min_value=0, max_value=1e5)` 生成 tableFee/foodAmount/coachFees | `abs(totalAmount - (tableFee + foodAmount + sum(fees))) < 0.01` |
|
||
| P2: 废单排除一致性 | `test_deleted_records_excluded` | `st.lists(st.fixed_dictionaries({is_delete: st.integers(0,2), ...}))` | 过滤后结果中所有 `is_delete == 0` |
|
||
| P3: 助教费用拆分 | `test_coach_fee_split` | `st.floats` 生成 pd_money/cx_money + `st.sampled_from(["基础课","激励课"])` | 基础课→pd_money，激励课→cx_money，两者之和=总额 |
|
||
| P4: favoriteCoaches 排序 | `test_favorite_coaches_ordering` | `st.lists(st.floats(0, 1))` 生成 relationIndex 列表 | 排序后每项 ≥ 下一项 |
|
||
| P5: historyMonths 排序与标记 | `test_history_months_ordering` | `st.lists(st.dates(), min_size=1)` 生成月份列表 | 降序排列，首项 estimated=True，其余 False |
|
||
| P6: 列表上限 | `test_list_size_limits` | `st.integers(0, 100)` 生成记录数 | notes ≤ 20，topCustomers ≤ 20 |
|
||
| P7: 月度汇总聚合 | `test_monthly_summary_aggregation` | `st.lists(st.fixed_dictionaries({hours: st.floats(0,10), income: st.floats(0,1e4)}))` | count=len，hours=sum(hours)，monthHours=sum(hours) |
|
||
| P8: daysSinceVisit 计算 | `test_days_since_visit` | `st.dates(max_value=date.today())` | days = (today - date).days，非负 |
|
||
| P9: emoji 映射 | `test_emoji_mapping` | `st.floats(0, 1)` 生成 relationIndex | ≥0.7→💖，<0.7→💛；heartEmoji 三级映射正确 |
|
||
| P10: 优雅降级 | `test_graceful_degradation` | `st.sampled_from(MODULES)` 选择失败模块 | 失败模块返回空默认值，其他模块正常 |
|
||
| P11: 任务分组 | `test_task_grouping` | `st.lists(st.fixed_dictionaries({status: st.sampled_from(STATUSES)}))` | active→visible，inactive→hidden，abandoned→abandoned，无交集 |
|
||
| P12: 数据隔离 | `test_data_isolation` | `st.integers(1, 1000)` 生成 customerId/coachId | coachTasks 每条 member_id=customerId，serviceRecords 每条 assistant_id=coachId |
|
||
| P13: 分页与 hasMore | `test_pagination_has_more` | `st.integers(1,100)` total + `st.integers(1,10)` page/pageSize | 记录数 ≤ pageSize，hasMore = (total > page*pageSize) |
|
||
| P14: 幂等性 | `test_idempotent_query` | `st.integers(1,12)` month + `st.integers(2020,2026)` year | f(x) == f(x) 对 monthCount/monthHours |
|
||
|
||
### 单元测试清单
|
||
|
||
| 测试目标 | 测试文件 | 关键用例 |
|
||
|---------|---------|---------|
|
||
| CUST-1 端点 | `tests/unit/test_customer_detail.py` | 完整响应结构；Banner 字段正确；aiInsight 无缓存降级；consumptionRecords 嵌套结构 |
|
||
| CUST-1 coachTasks | `tests/unit/test_customer_coach_tasks.py` | 关联助教列表；metrics 近 60 天统计；levelColor 映射 |
|
||
| CUST-1 favoriteCoaches | `tests/unit/test_customer_favorites.py` | 关系指数排序；emoji 映射；stats 4 项指标 |
|
||
| CUST-2 端点 | `tests/unit/test_customer_records.py` | 按月查询；monthCount/monthHours 汇总；totalServiceCount 跨月；hasMore 分页 |
|
||
| COACH-1 端点 | `tests/unit/test_coach_detail.py` | 完整响应结构；performance 6 指标；income thisMonth/lastMonth 各 4 项 |
|
||
| COACH-1 topCustomers | `tests/unit/test_coach_top_customers.py` | 最多 20 条；heartEmoji 三级映射；consume items_sum 口径 |
|
||
| COACH-1 historyMonths | `tests/unit/test_coach_history.py` | 最近 5+ 个月；本月 estimated=true；回访/召回完成数 |
|
||
| COACH-1 任务分组 | `tests/unit/test_coach_task_groups.py` | 三组分组正确；abandonedTasks 含 reason；notes 关联 |
|
||
| 权限校验 | `tests/unit/test_auth_rns12.py` | 未审核用户 403；客户不存在 404；助教不存在 404 |
|
||
| FDW 查询扩展 | `tests/unit/test_fdw_queries_rns12.py` | DQ-6 JOIN 正确；DQ-7 余额查询；is_delete=0 排除；items_sum 口径 |
|
||
| 优雅降级 | `tests/unit/test_degradation_rns12.py` | aiInsight 失败→空；coachTasks 失败→空列表；favoriteCoaches 失败→空列表 |
|
||
|
||
### 测试执行命令
|
||
|
||
```bash
|
||
# 属性测试（Hypothesis）
|
||
cd C:\NeoZQYY && pytest tests/ -v -k "rns1_customer_coach"
|
||
|
||
# 单元测试
|
||
cd apps/backend && pytest tests/unit/ -v -k "customer_detail or customer_records or coach_detail or coach_top or coach_history or coach_task_groups or auth_rns12 or fdw_queries_rns12 or degradation_rns12"
|
||
```
|