931 lines
34 KiB
Markdown
931 lines
34 KiB
Markdown
# 技术设计文档 — RNS1.1：任务与绩效接口
|
||
|
||
## 概述
|
||
|
||
RNS1.1 实现助教日常使用频率最高的 4 个核心接口及配套前端适配，覆盖 6 个任务：
|
||
|
||
1. **T1-1 扩展 TASK-1**：任务列表 `performance` 从 4 字段扩展到 15+ 字段；`enrichTask` 补充 `lastVisitDays`/`balance`/`aiSuggestion`
|
||
2. **T1-2 实现 TASK-2**：任务详情完整版（维客线索、话术、服务记录、AI 分析、备注）
|
||
3. **T1-3 实现 PERF-1**：绩效概览（DateGroup 分组、收入档位、新客/常客列表）
|
||
4. **T1-4 实现 PERF-2**：绩效明细（按月分页、DateGroup 分组）
|
||
5. **T1-5 pin/unpin**：已有端点的响应格式对齐契约
|
||
6. **T1-6 前端适配**：createNote 补 score、月份切换、avatarChar/avatarColor 前端计算
|
||
|
||
### 设计原则
|
||
|
||
- **增量扩展**：在现有 `xcx_tasks.py` 路由和 `task_manager.py` 服务基础上扩展，不重写
|
||
- **FDW 查询集中化**：所有 FDW 查询封装在 service 层，路由层不直接操作数据库
|
||
- **DWD-DOC 强制规则**：金额 `items_sum` 口径、助教费用 `assistant_pd_money` + `assistant_cx_money` 拆分、会员信息通过 `member_id` JOIN `dim_member`
|
||
- **契约驱动**：响应结构严格遵循 `API-contract.md` 定义
|
||
|
||
### 依赖
|
||
|
||
- RNS1.0 已完成：`ResponseWrapperMiddleware`、`CamelModel`、前端 `request()` 解包
|
||
- 现有代码：`xcx_tasks.py`（路由）、`task_manager.py`（服务）、`xcx_notes.py`（备注路由）
|
||
|
||
## 架构
|
||
|
||
### 模块交互
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "微信小程序"
|
||
A[task-list 页面] --> B[services/api.ts]
|
||
C[task-detail 页面] --> B
|
||
D[performance 页面] --> B
|
||
E[performance-records 页面] --> B
|
||
end
|
||
|
||
subgraph "FastAPI 后端"
|
||
F[routers/xcx_tasks.py<br/>TASK-1/2, PIN/UNPIN]
|
||
G[routers/xcx_performance.py<br/>PERF-1/2 — 新增]
|
||
H[services/task_manager.py<br/>任务 CRUD + 扩展]
|
||
I[services/performance_service.py<br/>绩效查询 — 新增]
|
||
J[services/fdw_queries.py<br/>FDW 查询封装 — 新增]
|
||
end
|
||
|
||
subgraph "数据库"
|
||
K[(zqyy_app<br/>biz.coach_tasks<br/>biz.ai_cache<br/>biz.notes<br/>auth.user_assistant_binding<br/>public.member_retention_clue)]
|
||
L[(etl_feiqiu via FDW<br/>fdw_etl.v_dws_assistant_salary_calc<br/>fdw_etl.v_dwd_assistant_service_log<br/>fdw_etl.v_dim_member<br/>fdw_etl.v_dim_member_card_account)]
|
||
end
|
||
|
||
B -->|HTTP JSON| F
|
||
B -->|HTTP JSON| G
|
||
F --> H
|
||
G --> I
|
||
H --> J
|
||
I --> J
|
||
H --> K
|
||
I --> K
|
||
J -->|FDW + SET LOCAL| L
|
||
|
||
style G fill:#9f9,stroke:#333
|
||
style I fill:#9f9,stroke:#333
|
||
style J fill:#9f9,stroke:#333
|
||
```
|
||
|
||
### 请求流程（以 TASK-1 扩展为例）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant MP as 小程序
|
||
participant R as xcx_tasks Router
|
||
participant TM as task_manager
|
||
participant FDW as fdw_queries
|
||
participant BIZ as zqyy_app
|
||
participant ETL as etl via FDW
|
||
|
||
MP->>R: GET /api/xcx/tasks?status=pending&page=1
|
||
R->>TM: get_task_list(user_id, site_id, status, page, pageSize)
|
||
TM->>BIZ: SELECT assistant_id FROM user_assistant_binding
|
||
TM->>BIZ: SELECT tasks FROM coach_tasks
|
||
TM->>FDW: enrich_tasks(member_ids, assistant_id, site_id)
|
||
FDW->>ETL: SET LOCAL app.current_site_id
|
||
FDW->>ETL: SELECT dim_member (姓名)
|
||
FDW->>ETL: SELECT dim_member_card_account (余额)
|
||
FDW->>ETL: SELECT dwd_settlement_head (lastVisitDays)
|
||
FDW-->>TM: enriched data
|
||
TM->>FDW: get_performance_summary(assistant_id, site_id)
|
||
FDW->>ETL: SELECT v_dws_assistant_salary_calc (档位/收入)
|
||
FDW-->>TM: PerformanceSummary
|
||
TM->>BIZ: SELECT ai_cache (aiSuggestion)
|
||
TM-->>R: TaskListResponse
|
||
R-->>MP: { code: 0, data: TaskListResponse }
|
||
```
|
||
|
||
## 组件与接口
|
||
|
||
### 组件 1：xcx_tasks Router 扩展
|
||
|
||
**位置**：`apps/backend/app/routers/xcx_tasks.py`
|
||
|
||
**改动**：
|
||
- `GET /api/xcx/tasks` — 响应从 `list[TaskListItem]` 改为 `TaskListResponse`（含 `items` + `performance` + 分页）
|
||
- 新增 `GET /api/xcx/tasks/{taskId}` — 任务详情端点
|
||
- `POST .../pin` 和 `POST .../unpin` — 响应对齐契约格式 `{ isPinned: bool }`
|
||
- 新增查询参数：`status`（筛选）、`page`、`pageSize`
|
||
|
||
```python
|
||
@router.get("", response_model=TaskListResponse)
|
||
async def get_tasks(
|
||
status: str = Query("pending", regex="^(pending|completed|abandoned)$"),
|
||
page: int = Query(1, ge=1),
|
||
page_size: int = Query(20, ge=1, le=100),
|
||
user: CurrentUser = Depends(require_approved()),
|
||
):
|
||
"""获取任务列表 + 绩效概览。"""
|
||
return await task_manager.get_task_list_v2(
|
||
user.user_id, user.site_id, status, page, page_size
|
||
)
|
||
|
||
@router.get("/{task_id}", response_model=TaskDetailResponse)
|
||
async def get_task_detail(
|
||
task_id: int,
|
||
user: CurrentUser = Depends(require_approved()),
|
||
):
|
||
"""获取任务详情完整版。"""
|
||
return await task_manager.get_task_detail(
|
||
task_id, user.user_id, user.site_id
|
||
)
|
||
```
|
||
|
||
### 组件 2：xcx_performance Router（新增）
|
||
|
||
**位置**：`apps/backend/app/routers/xcx_performance.py`
|
||
|
||
**职责**：绩效概览和绩效明细两个端点。
|
||
|
||
```python
|
||
router = APIRouter(prefix="/api/xcx/performance", tags=["小程序绩效"])
|
||
|
||
@router.get("", response_model=PerformanceOverviewResponse)
|
||
async def get_performance_overview(
|
||
year: int = Query(...),
|
||
month: int = Query(..., ge=1, le=12),
|
||
user: CurrentUser = Depends(require_approved()),
|
||
):
|
||
"""绩效概览（PERF-1）。"""
|
||
return await performance_service.get_overview(
|
||
user.user_id, user.site_id, year, month
|
||
)
|
||
|
||
@router.get("/records", response_model=PerformanceRecordsResponse)
|
||
async def get_performance_records(
|
||
year: int = Query(...),
|
||
month: int = Query(..., ge=1, le=12),
|
||
page: int = Query(1, ge=1),
|
||
page_size: int = Query(20, ge=1, le=100),
|
||
user: CurrentUser = Depends(require_approved()),
|
||
):
|
||
"""绩效明细（PERF-2）。"""
|
||
return await performance_service.get_records(
|
||
user.user_id, user.site_id, year, month, page, page_size
|
||
)
|
||
```
|
||
|
||
**注册**（`main.py`）：
|
||
```python
|
||
from app.routers import xcx_performance
|
||
app.include_router(xcx_performance.router)
|
||
```
|
||
|
||
### 组件 3：fdw_queries 服务（新增）
|
||
|
||
**位置**：`apps/backend/app/services/fdw_queries.py`
|
||
|
||
**职责**：封装所有 FDW 查询，统一 `SET LOCAL app.current_site_id` 隔离。所有 FDW 查询集中在此模块，避免 service 层散落 SQL。
|
||
|
||
**核心函数**：
|
||
|
||
```python
|
||
def _fdw_context(conn, site_id: int):
|
||
"""上下文管理器：BEGIN + SET LOCAL app.current_site_id。"""
|
||
...
|
||
|
||
def get_member_info(conn, site_id: int, member_ids: list[int]) -> dict[int, MemberInfo]:
|
||
"""
|
||
批量查询会员信息。
|
||
⚠️ DQ-6：通过 member_id JOIN fdw_etl.v_dim_member 获取 nickname/mobile，
|
||
禁止使用 settlement_head.member_phone/member_name。
|
||
"""
|
||
# SELECT member_id, nickname, mobile
|
||
# FROM fdw_etl.v_dim_member
|
||
# WHERE member_id = ANY(%s) AND scd2_is_current = 1
|
||
|
||
def get_member_balance(conn, site_id: int, member_ids: list[int]) -> dict[int, Decimal]:
|
||
"""
|
||
批量查询会员储值卡余额。
|
||
⚠️ DQ-7：通过 member_id JOIN fdw_etl.v_dim_member_card_account。
|
||
"""
|
||
|
||
def get_last_visit_days(conn, site_id: int, member_ids: list[int]) -> dict[int, int | None]:
|
||
"""
|
||
批量查询客户距上次到店天数。
|
||
来源：fdw_etl.v_dwd_assistant_service_log 或 dwd_settlement_head。
|
||
"""
|
||
|
||
def get_salary_calc(conn, site_id: int, assistant_id: int, year: int, month: int) -> dict | None:
|
||
"""
|
||
查询助教绩效/档位/收入数据。
|
||
来源：fdw_etl.v_dws_assistant_salary_calc。
|
||
⚠️ DWD-DOC 规则 1：收入使用 items_sum 口径。
|
||
⚠️ DWD-DOC 规则 2：费用使用 assistant_pd_money + assistant_cx_money。
|
||
"""
|
||
|
||
def get_service_records(
|
||
conn, site_id: int, assistant_id: int,
|
||
year: int, month: int, limit: int, offset: int
|
||
) -> list[dict]:
|
||
"""
|
||
查询助教服务记录明细。
|
||
来源：fdw_etl.v_dwd_assistant_service_log。
|
||
⚠️ 废单排除：WHERE is_trash = false。
|
||
⚠️ DQ-6：客户姓名通过 member_id JOIN dim_member。
|
||
"""
|
||
|
||
def get_service_records_for_task(
|
||
conn, site_id: int, assistant_id: int, member_id: int, limit: int
|
||
) -> list[dict]:
|
||
"""查询特定客户的服务记录（TASK-2 用）。"""
|
||
```
|
||
|
||
### 组件 4：task_manager 服务扩展
|
||
|
||
**位置**：`apps/backend/app/services/task_manager.py`
|
||
|
||
**新增函数**：
|
||
|
||
```python
|
||
async def get_task_list_v2(
|
||
user_id: int, site_id: int,
|
||
status: str, page: int, page_size: int
|
||
) -> dict:
|
||
"""
|
||
扩展版任务列表（TASK-1）。
|
||
返回 { items, total, page, pageSize, performance }。
|
||
"""
|
||
|
||
async def get_task_detail(
|
||
task_id: int, user_id: int, site_id: int
|
||
) -> dict:
|
||
"""
|
||
任务详情完整版（TASK-2）。
|
||
返回基础信息 + retentionClues + talkingPoints + serviceSummary
|
||
+ serviceRecords + aiAnalysis + notes + customerId。
|
||
"""
|
||
```
|
||
|
||
**`get_task_list_v2` 逻辑**：
|
||
1. `_get_assistant_id()` 获取 `assistant_id`
|
||
2. 查询 `biz.coach_tasks` 带分页（`LIMIT/OFFSET` + `COUNT(*)`）
|
||
3. 调用 `fdw_queries` 批量获取会员信息、余额、lastVisitDays
|
||
4. 调用 `fdw_queries.get_salary_calc()` 获取绩效概览
|
||
5. 查询 `biz.ai_cache` 获取 aiSuggestion
|
||
6. 组装 `TaskListResponse`
|
||
|
||
**`get_task_detail` 逻辑**：
|
||
1. `_get_assistant_id()` + `_verify_task_ownership()` 权限校验
|
||
2. 查询 `biz.coach_tasks` 基础信息
|
||
3. 查询 `public.member_retention_clue` 维客线索
|
||
4. 查询 `biz.ai_cache`（`app5_talking_points` → talkingPoints，`app4_analysis` → aiAnalysis）
|
||
5. 调用 `fdw_queries.get_service_records_for_task()` 获取服务记录（最多 20 条）
|
||
6. 查询 `biz.notes` 获取备注（最多 20 条）
|
||
7. 组装 `TaskDetailResponse`
|
||
|
||
### 组件 5：performance_service（新增）
|
||
|
||
**位置**：`apps/backend/app/services/performance_service.py`
|
||
|
||
**核心函数**：
|
||
|
||
```python
|
||
async def get_overview(
|
||
user_id: int, site_id: int, year: int, month: int
|
||
) -> dict:
|
||
"""
|
||
绩效概览（PERF-1）。
|
||
1. 获取 assistant_id
|
||
2. fdw_queries.get_salary_calc() → 档位/收入/费率
|
||
3. fdw_queries.get_service_records() → 按日期分组为 DateGroup
|
||
4. 聚合新客/常客列表
|
||
5. 计算 incomeItems（含 desc 费率描述）
|
||
6. 查询上月收入 lastMonthIncome
|
||
"""
|
||
|
||
async def get_records(
|
||
user_id: int, site_id: int,
|
||
year: int, month: int, page: int, page_size: int
|
||
) -> dict:
|
||
"""
|
||
绩效明细（PERF-2）。
|
||
1. 获取 assistant_id
|
||
2. fdw_queries.get_service_records() 带分页
|
||
3. 按日期分组为 dateGroups
|
||
4. 计算 summary 汇总
|
||
5. 返回 { summary, dateGroups, hasMore }
|
||
"""
|
||
```
|
||
|
||
### 组件 6：Pydantic Schema（新增/扩展）
|
||
|
||
**位置**：`apps/backend/app/schemas/xcx_tasks.py`（扩展）+ `apps/backend/app/schemas/xcx_performance.py`（新增）
|
||
|
||
#### 任务相关 Schema 扩展
|
||
|
||
```python
|
||
class PerformanceSummary(CamelModel):
|
||
"""绩效概览（附带在任务列表响应中）。"""
|
||
total_hours: float
|
||
total_income: float
|
||
total_customers: int
|
||
month_label: str
|
||
tier_nodes: list[float]
|
||
basic_hours: float
|
||
bonus_hours: float
|
||
current_tier: int
|
||
next_tier_hours: float
|
||
tier_completed: bool
|
||
bonus_money: float
|
||
income_trend: str
|
||
income_trend_dir: str # 'up' | 'down'
|
||
prev_month: str
|
||
current_tier_label: str
|
||
|
||
class TaskItem(CamelModel):
|
||
"""任务列表项（扩展版）。"""
|
||
id: int
|
||
customer_name: str
|
||
customer_avatar: str
|
||
task_type: str
|
||
task_type_label: str
|
||
deadline: str | None
|
||
heart_score: float
|
||
hobbies: list[str]
|
||
is_pinned: bool
|
||
has_note: bool
|
||
status: str
|
||
last_visit_days: int | None = None
|
||
balance: float | None = None
|
||
ai_suggestion: str | None = None
|
||
|
||
class TaskListResponse(CamelModel):
|
||
"""TASK-1 响应。"""
|
||
items: list[TaskItem]
|
||
total: int
|
||
page: int
|
||
page_size: int
|
||
performance: PerformanceSummary
|
||
```
|
||
|
||
#### 任务详情 Schema
|
||
|
||
```python
|
||
class RetentionClue(CamelModel):
|
||
tag: str
|
||
tag_color: str
|
||
emoji: str
|
||
text: str
|
||
source: str # 'manual' | 'ai_consumption' | 'ai_note'
|
||
desc: str | None = None
|
||
|
||
class ServiceRecord(CamelModel):
|
||
table: str | None = None
|
||
type: str
|
||
type_class: str # 'basic' | 'vip' | 'tip' | 'recharge' | 'incentive'
|
||
record_type: str | None = None # 'course' | 'recharge'
|
||
duration: float
|
||
duration_raw: float | None = None
|
||
income: float
|
||
is_estimate: bool | None = None
|
||
drinks: str | None = None
|
||
date: str
|
||
|
||
class AiAnalysis(CamelModel):
|
||
summary: str
|
||
suggestions: list[str]
|
||
|
||
class NoteItem(CamelModel):
|
||
id: int
|
||
content: str
|
||
tag_type: str
|
||
tag_label: str
|
||
created_at: str
|
||
score: int | None = None
|
||
|
||
class ServiceSummary(CamelModel):
|
||
total_hours: float
|
||
total_income: float
|
||
avg_income: float
|
||
|
||
class TaskDetailResponse(CamelModel):
|
||
"""TASK-2 响应。"""
|
||
# 基础信息
|
||
id: int
|
||
customer_name: str
|
||
customer_avatar: str
|
||
task_type: str
|
||
task_type_label: str
|
||
deadline: str | None
|
||
heart_score: float
|
||
hobbies: list[str]
|
||
is_pinned: bool
|
||
has_note: bool
|
||
status: str
|
||
customer_id: int
|
||
# 扩展模块
|
||
retention_clues: list[RetentionClue]
|
||
talking_points: list[str]
|
||
service_summary: ServiceSummary
|
||
service_records: list[ServiceRecord]
|
||
ai_analysis: AiAnalysis
|
||
notes: list[NoteItem]
|
||
```
|
||
|
||
#### 绩效 Schema
|
||
|
||
```python
|
||
class DateGroupRecord(CamelModel):
|
||
customer_name: str
|
||
avatar_char: str | None = None # PERF-1 返回，PERF-2 不返回
|
||
avatar_color: str | None = None # PERF-1 返回，PERF-2 不返回
|
||
time_range: str
|
||
hours: str
|
||
course_type: str
|
||
course_type_class: str # 'basic' | 'vip' | 'tip'
|
||
location: str
|
||
income: str
|
||
|
||
class DateGroup(CamelModel):
|
||
date: str
|
||
total_hours: str
|
||
total_income: str
|
||
records: list[DateGroupRecord]
|
||
|
||
class TierInfo(CamelModel):
|
||
basic_rate: float
|
||
incentive_rate: float
|
||
|
||
class IncomeItem(CamelModel):
|
||
icon: str
|
||
label: str
|
||
desc: str
|
||
value: str
|
||
|
||
class CustomerSummary(CamelModel):
|
||
name: str
|
||
avatar_char: str
|
||
avatar_color: str
|
||
|
||
class NewCustomer(CustomerSummary):
|
||
last_service: str
|
||
count: int
|
||
|
||
class RegularCustomer(CustomerSummary):
|
||
hours: float
|
||
income: str
|
||
count: int
|
||
|
||
class PerformanceOverviewResponse(CamelModel):
|
||
"""PERF-1 响应。"""
|
||
coach_name: str
|
||
coach_role: str
|
||
store_name: str
|
||
monthly_income: str
|
||
last_month_income: str
|
||
current_tier: TierInfo
|
||
next_tier: TierInfo
|
||
upgrade_hours_needed: float
|
||
upgrade_bonus: float
|
||
income_items: list[IncomeItem]
|
||
monthly_total: str
|
||
this_month_records: list[DateGroup]
|
||
new_customers: list[NewCustomer]
|
||
regular_customers: list[RegularCustomer]
|
||
|
||
class RecordsSummary(CamelModel):
|
||
total_count: int
|
||
total_hours: float
|
||
total_hours_raw: float
|
||
total_income: float
|
||
|
||
class PerformanceRecordsResponse(CamelModel):
|
||
"""PERF-2 响应。"""
|
||
summary: RecordsSummary
|
||
date_groups: list[DateGroup]
|
||
has_more: bool
|
||
```
|
||
|
||
### 组件 7：前端适配
|
||
|
||
**涉及文件与改动**：
|
||
|
||
| 文件 | 改动 |
|
||
|------|------|
|
||
| `services/api.ts` | 新增 `pinTask()`、`unpinTask()`；`createNote()` 增加 `score` 参数；新增 `fetchTaskDetail()`、`fetchPerformanceOverview(year, month)`、`fetchPerformanceRecords(year, month, page)` |
|
||
| `pages/task-list/task-list.ts` | 消费 `TaskListResponse` 新结构；`buildPerfData()` 使用 15+ 字段绩效数据 |
|
||
| `pages/task-detail/task-detail.ts` | 调用 `fetchTaskDetail()`；`storageLevel`/`relationLevel` 前端本地计算 |
|
||
| `pages/performance/performance.ts` | 添加月份切换控件；切换时重新调用 API |
|
||
| `pages/performance-records/performance-records.ts` | 月份切换时重置 `page=1`；`avatarChar`/`avatarColor` 使用 `nameToAvatarColor()` 前端计算 |
|
||
|
||
|
||
|
||
## 数据模型
|
||
|
||
### FDW 查询模式
|
||
|
||
所有 FDW 查询遵循统一模式：
|
||
|
||
```python
|
||
# 1. 使用业务库连接（get_connection() → zqyy_app）
|
||
conn = get_connection()
|
||
|
||
# 2. 开启事务 + 设置门店隔离
|
||
with conn.cursor() as cur:
|
||
cur.execute("BEGIN")
|
||
cur.execute("SET LOCAL app.current_site_id = %s", (str(site_id),))
|
||
|
||
# 3. 通过 fdw_etl schema 访问 ETL 视图
|
||
cur.execute("""
|
||
SELECT ...
|
||
FROM fdw_etl.v_dws_assistant_salary_calc
|
||
WHERE assistant_id = %s AND calc_month = %s
|
||
""", (assistant_id, f"{year}-{month:02d}"))
|
||
|
||
conn.commit()
|
||
```
|
||
|
||
### 核心 SQL 查询设计
|
||
|
||
#### Q1: 绩效概览查询（TASK-1 performance + PERF-1）
|
||
|
||
```sql
|
||
-- ⚠️ DWD-DOC 规则 1: 收入使用 items_sum 口径
|
||
-- ⚠️ DWD-DOC 规则 2: 费用使用 assistant_pd_money + assistant_cx_money
|
||
SELECT
|
||
calc_month,
|
||
coach_level, -- 当前档位名称
|
||
tier_index, -- 当前档位索引
|
||
tier_nodes, -- 档位节点数组 (JSON)
|
||
basic_hours, -- 基础课时 (assistant_pd_money 对应)
|
||
bonus_hours, -- 激励课时 (assistant_cx_money 对应)
|
||
total_hours, -- 总工时
|
||
total_income, -- 总收入 (items_sum 口径)
|
||
total_customers, -- 服务客户数
|
||
basic_rate, -- 基础课时费率
|
||
incentive_rate, -- 激励课时费率
|
||
next_tier_basic_rate, -- 下一档基础课时费率
|
||
next_tier_incentive_rate, -- 下一档激励课时费率
|
||
next_tier_hours, -- 下一档工时阈值
|
||
tier_completed, -- 是否已达最高档
|
||
bonus_money, -- 升档奖金
|
||
assistant_pd_money_total, -- 基础课总费用
|
||
assistant_cx_money_total -- 激励课总费用
|
||
FROM fdw_etl.v_dws_assistant_salary_calc
|
||
WHERE assistant_id = %s
|
||
AND calc_month = %s
|
||
```
|
||
|
||
#### Q2: 收入趋势计算（TASK-1 performance）
|
||
|
||
```sql
|
||
-- 当月 vs 上月收入对比
|
||
WITH months AS (
|
||
SELECT total_income, calc_month
|
||
FROM fdw_etl.v_dws_assistant_salary_calc
|
||
WHERE assistant_id = %s
|
||
AND calc_month IN (%s, %s) -- 当月, 上月
|
||
)
|
||
SELECT * FROM months ORDER BY calc_month
|
||
```
|
||
|
||
后端计算逻辑：
|
||
```python
|
||
diff = current_income - prev_income
|
||
income_trend = f"{'↑' if diff >= 0 else '↓'}{abs(diff):.0f}"
|
||
income_trend_dir = "up" if diff >= 0 else "down"
|
||
```
|
||
|
||
#### Q3: 服务记录查询（PERF-1 thisMonthRecords / PERF-2 dateGroups / TASK-2 serviceRecords）
|
||
|
||
```sql
|
||
-- ⚠️ DWD-DOC 规则 DQ-6: 客户姓名通过 member_id JOIN dim_member
|
||
-- ⚠️ 废单排除: is_trash = false
|
||
SELECT
|
||
sl.id,
|
||
dm.nickname AS customer_name,
|
||
sl.settle_time,
|
||
sl.start_time,
|
||
sl.end_time,
|
||
sl.service_hours, -- 折算工时
|
||
sl.service_hours_raw, -- 原始工时
|
||
sl.course_type, -- 课程类型
|
||
sl.table_name, -- 台桌名
|
||
sl.items_sum AS income, -- ⚠️ items_sum 口径
|
||
sl.is_estimate
|
||
FROM fdw_etl.v_dwd_assistant_service_log sl
|
||
LEFT JOIN fdw_etl.v_dim_member dm
|
||
ON sl.member_id = dm.member_id
|
||
AND dm.scd2_is_current = 1 -- ⚠️ SCD2 当前记录
|
||
WHERE sl.assistant_id = %s
|
||
AND sl.is_trash = false -- ⚠️ 废单排除
|
||
AND sl.settle_time >= %s -- 月份起始
|
||
AND sl.settle_time < %s -- 月份结束
|
||
ORDER BY sl.settle_time DESC
|
||
LIMIT %s OFFSET %s
|
||
```
|
||
|
||
#### Q4: 任务项扩展字段查询
|
||
|
||
```sql
|
||
-- lastVisitDays: 距上次到店天数
|
||
SELECT member_id,
|
||
CURRENT_DATE - MAX(settle_time::date) AS days_since_visit
|
||
FROM fdw_etl.v_dwd_assistant_service_log
|
||
WHERE member_id = ANY(%s)
|
||
AND is_trash = false
|
||
GROUP BY member_id
|
||
|
||
-- balance: 客户储值卡余额
|
||
-- ⚠️ DQ-7: 通过 member_id JOIN dim_member_card_account
|
||
SELECT tenant_member_id AS member_id,
|
||
balance
|
||
FROM fdw_etl.v_dim_member_card_account
|
||
WHERE tenant_member_id = ANY(%s)
|
||
AND scd2_is_current = 1
|
||
```
|
||
|
||
#### Q5: 维客线索查询（TASK-2）
|
||
|
||
```sql
|
||
SELECT id, tag, tag_color, emoji, text, source, description
|
||
FROM public.member_retention_clue
|
||
WHERE member_id = %s
|
||
AND site_id = %s
|
||
ORDER BY created_at DESC
|
||
```
|
||
|
||
#### Q6: AI 缓存查询（TASK-2）
|
||
|
||
```sql
|
||
-- aiAnalysis: cache_type = 'app4_analysis'
|
||
-- talkingPoints: cache_type = 'app5_talking_points'
|
||
SELECT cache_type, cache_value
|
||
FROM biz.ai_cache
|
||
WHERE target_id = %s
|
||
AND site_id = %s
|
||
AND cache_type IN ('app4_analysis', 'app5_talking_points')
|
||
```
|
||
|
||
#### Q7: 新客/常客列表（PERF-1）
|
||
|
||
```sql
|
||
-- 新客：本月首次服务的客户
|
||
-- ⚠️ DQ-6: 客户姓名通过 member_id JOIN dim_member
|
||
WITH month_records AS (
|
||
SELECT sl.member_id,
|
||
dm.nickname AS customer_name,
|
||
COUNT(*) AS service_count,
|
||
MAX(sl.settle_time) AS last_service
|
||
FROM fdw_etl.v_dwd_assistant_service_log sl
|
||
LEFT JOIN fdw_etl.v_dim_member dm
|
||
ON sl.member_id = dm.member_id AND dm.scd2_is_current = 1
|
||
WHERE sl.assistant_id = %s
|
||
AND sl.is_trash = false
|
||
AND sl.settle_time >= %s AND sl.settle_time < %s
|
||
GROUP BY sl.member_id, dm.nickname
|
||
),
|
||
historical AS (
|
||
SELECT DISTINCT member_id
|
||
FROM fdw_etl.v_dwd_assistant_service_log
|
||
WHERE assistant_id = %s
|
||
AND is_trash = false
|
||
AND settle_time < %s -- 本月之前
|
||
)
|
||
SELECT mr.member_id, mr.customer_name, mr.service_count, mr.last_service
|
||
FROM month_records mr
|
||
LEFT JOIN historical h ON mr.member_id = h.member_id
|
||
WHERE h.member_id IS NULL -- 新客：历史无记录
|
||
ORDER BY mr.last_service DESC
|
||
|
||
-- 常客：本月服务 ≥ 2 次的客户
|
||
SELECT mr.member_id, mr.customer_name,
|
||
SUM(sl.service_hours) AS total_hours,
|
||
SUM(sl.items_sum) AS total_income, -- ⚠️ items_sum 口径
|
||
COUNT(*) AS service_count
|
||
FROM month_records mr
|
||
JOIN fdw_etl.v_dwd_assistant_service_log sl
|
||
ON mr.member_id = sl.member_id
|
||
WHERE mr.service_count >= 2
|
||
GROUP BY mr.member_id, mr.customer_name
|
||
ORDER BY total_income DESC
|
||
```
|
||
|
||
### courseTypeClass 枚举映射
|
||
|
||
后端根据 `v_dwd_assistant_service_log.course_type` 映射：
|
||
|
||
| 原始值 | courseTypeClass | courseType 中文 |
|
||
|--------|----------------|----------------|
|
||
| `basic` / `陪打` / `基础课` | `basic` | 基础课 |
|
||
| `vip` / `包厢` / `包厢课` | `vip` | 包厢课 |
|
||
| `tip` / `超休` / `激励课` | `tip` | 激励课 |
|
||
| `recharge` / `充值` | `recharge` | 充值 |
|
||
| `incentive` / `激励` | `incentive` | 激励 |
|
||
|
||
统一不带 `tag-` 前缀（契约要求）。
|
||
|
||
### DWD-DOC 强制规则实施位置
|
||
|
||
| 规则 | 实施位置 | 具体措施 |
|
||
|------|---------|---------|
|
||
| 规则 1: `items_sum` 口径 | `fdw_queries.py` 所有金额查询 | SQL 中使用 `items_sum` 字段，禁止 `consume_money` |
|
||
| 规则 2: 助教费用拆分 | `fdw_queries.get_salary_calc()` | 使用 `assistant_pd_money` + `assistant_cx_money`，禁止 `service_fee` |
|
||
| DQ-6: 会员信息 JOIN | `fdw_queries.get_member_info()` + 所有含客户姓名的查询 | `member_id JOIN fdw_etl.v_dim_member WHERE scd2_is_current=1` |
|
||
| DQ-7: 会员卡 JOIN | `fdw_queries.get_member_balance()` | `member_id JOIN fdw_etl.v_dim_member_card_account WHERE scd2_is_current=1` |
|
||
| 废单排除 | `fdw_queries` 所有服务记录查询 | `WHERE is_trash = false`，禁止引用 `dwd_assistant_trash_event` |
|
||
|
||
|
||
|
||
## 正确性属性
|
||
|
||
*属性（Property）是一个在系统所有合法执行路径上都应成立的特征或行为——本质上是对"系统应该做什么"的形式化陈述。属性是人类可读规格与机器可验证正确性保证之间的桥梁。*
|
||
|
||
### Property 1: 收入趋势计算正确性
|
||
|
||
*For any* 两个非负收入值 `currentIncome` 和 `prevIncome`，计算 `incomeTrend` 和 `incomeTrendDir` 时：
|
||
- `incomeTrendDir` 应为 `"up"` 当 `currentIncome >= prevIncome`，否则为 `"down"`
|
||
- `incomeTrend` 应包含绝对差值 `abs(currentIncome - prevIncome)` 的整数表示
|
||
- `incomeTrend` 应以 `"↑"` 或 `"↓"` 开头，与 `incomeTrendDir` 一致
|
||
|
||
**Validates: Requirements 1.4**
|
||
|
||
### Property 2: lastVisitDays 计算正确性
|
||
|
||
*For any* 有效日期 `lastVisitDate`（不晚于今天），`lastVisitDays` 应等于 `(current_date - lastVisitDate).days`，且结果为非负整数。
|
||
|
||
**Validates: Requirements 1.7**
|
||
|
||
### Property 3: 维客线索 tag 净化与 source 枚举
|
||
|
||
*For any* 维客线索记录，经过后端处理后：
|
||
- `tag` 字段不应包含换行符 `\n`（多行标签使用空格分隔）
|
||
- `source` 字段必须是 `manual`、`ai_consumption`、`ai_note` 三者之一
|
||
|
||
**Validates: Requirements 2.4, 2.5**
|
||
|
||
### Property 4: courseTypeClass 枚举映射
|
||
|
||
*For any* 服务记录的原始课程类型值，经过 `map_course_type_class()` 映射后：
|
||
- 结果必须是 `basic`、`vip`、`tip`、`recharge`、`incentive` 五者之一
|
||
- 结果不应包含 `tag-` 前缀
|
||
|
||
**Validates: Requirements 2.9, 4.4**
|
||
|
||
### Property 5: 列表分页与排序
|
||
|
||
*For any* 记录集合和分页参数 `(page, pageSize)`：
|
||
- 返回的记录数 ≤ `pageSize`
|
||
- `hasMore` 为 `true` 当且仅当总记录数 > `page * pageSize`
|
||
- 服务记录在每个 DateGroup 内按时间倒序排列
|
||
- 备注列表按 `created_at` 倒序排列
|
||
|
||
**Validates: Requirements 2.3, 4.2**
|
||
|
||
### Property 6: DateGroup 分组正确性
|
||
|
||
*For any* 服务记录集合，按日期分组后：
|
||
- 每个 DateGroup 的 `date` 在结果中唯一
|
||
- 每个 DateGroup 内的所有记录的日期部分相同
|
||
- `totalHours` 等于该组内所有记录 `hours` 之和
|
||
- `totalIncome` 等于该组内所有记录 `income` 之和
|
||
- DateGroup 列表按日期倒序排列
|
||
|
||
**Validates: Requirements 3.3, 4.3**
|
||
|
||
### Property 7: incomeItems desc 格式化
|
||
|
||
*For any* 费率 `rate`（正数）和工时 `hours`（非负数），生成的 `desc` 字段应包含费率值和工时值，格式为 `"{rate}元/h × {hours}h"`。
|
||
|
||
**Validates: Requirements 3.9**
|
||
|
||
### Property 8: 月度汇总聚合正确性
|
||
|
||
*For any* 服务记录集合，`summary` 的聚合应满足：
|
||
- `totalCount` 等于记录总数
|
||
- `totalHours` 等于所有记录折算工时之和
|
||
- `totalHoursRaw` 等于所有记录原始工时之和
|
||
- `totalIncome` 等于所有记录收入之和（`items_sum` 口径）
|
||
|
||
**Validates: Requirements 4.6**
|
||
|
||
### Property 9: Pin/Unpin 状态往返
|
||
|
||
*For any* 有效任务，执行 `pin` 后 `isPinned` 应为 `true`，再执行 `unpin` 后 `isPinned` 应恢复为 `false`。即 `unpin(pin(task))` 的 `isPinned` 状态等于原始状态（假设原始为 `false`）。
|
||
|
||
**Validates: Requirements 5.1, 5.2, 5.3**
|
||
|
||
### Property 10: 权限与数据隔离
|
||
|
||
*For any* 请求，若用户状态非 `approved`、缺少 `view_tasks` 权限、或在 `user_assistant_binding` 中无绑定记录，则所有 RNS1.1 端点应返回 HTTP 403。若请求的 `taskId` 不属于当前助教的 `assistant_id`，也应返回 HTTP 403。
|
||
|
||
**Validates: Requirements 2.13, 8.1, 8.2, 8.4**
|
||
|
||
### Property 11: 前端派生字段计算
|
||
|
||
*For any* 客户姓名字符串 `name`（非空），`nameToAvatarColor(name)` 应返回：
|
||
- `avatarChar` 等于 `name` 的第一个字符
|
||
- `avatarColor` 为预定义颜色集合中的一个值
|
||
- 相同 `name` 输入始终产生相同输出（确定性）
|
||
|
||
*For any* 余额值 `balance`（非负数），`computeStorageLevel(balance)` 应返回预定义等级之一（如 "非常多"/"较多"/"一般"/"较少"），且等级随余额单调递增。
|
||
|
||
*For any* 亲密度分数 `heartScore`（0-10），`computeRelationLevel(heartScore)` 应返回预定义等级之一，且等级随分数单调递增。
|
||
|
||
**Validates: Requirements 6.4, 6.5, 7.6**
|
||
|
||
### Property 12: 备注 score 输入验证
|
||
|
||
*For any* 整数 `score`，若 `score` 在 1-5 范围内，`POST /api/xcx/notes` 应接受并存储；若 `score` 超出范围（<1 或 >5），应返回 422 错误。`score` 为 `null` 时应正常创建备注（score 可选）。
|
||
|
||
**Validates: Requirements 6.3**
|
||
|
||
## 错误处理
|
||
|
||
### 后端错误处理
|
||
|
||
| 错误场景 | HTTP 状态码 | 响应 | 触发位置 |
|
||
|---------|:----------:|------|---------|
|
||
| 用户未通过审核 | 403 | `{ code: 403, message: "用户未通过审核，无法访问此资源" }` | `require_approved()` |
|
||
| 用户无 `view_tasks` 权限 | 403 | `{ code: 403, message: "权限不足" }` | `require_permission("view_tasks")` |
|
||
| 用户未绑定助教身份 | 403 | `{ code: 403, message: "未绑定助教身份" }` | `_get_assistant_id()` |
|
||
| 任务不属于当前助教 | 403 | `{ code: 403, message: "无权访问该任务" }` | `_verify_task_ownership()` |
|
||
| 任务不存在 | 404 | `{ code: 404, message: "任务不存在" }` | `get_task_detail()` / `pin_task()` |
|
||
| score 超出 1-5 范围 | 422 | `{ code: 422, message: "评分必须在 1-5 范围内" }` | `create_note()` |
|
||
| 无效的 status 参数 | 422 | Pydantic 验证错误 | FastAPI 参数校验 |
|
||
| year/month 参数无效 | 422 | Pydantic 验证错误 | FastAPI 参数校验 |
|
||
| FDW 查询超时/失败 | 500 | `{ code: 500, message: "Internal Server Error" }` | `unhandled_exception_handler` |
|
||
| 数据库连接失败 | 500 | `{ code: 500, message: "Internal Server Error" }` | `unhandled_exception_handler` |
|
||
|
||
### FDW 查询容错策略
|
||
|
||
任务列表扩展字段（`lastVisitDays`、`balance`、`aiSuggestion`）采用**优雅降级**策略：
|
||
|
||
```python
|
||
# 单个扩展字段查询失败不影响整体响应
|
||
try:
|
||
last_visit_map = fdw_queries.get_last_visit_days(conn, site_id, member_ids)
|
||
except Exception:
|
||
logger.warning("FDW 查询 lastVisitDays 失败", exc_info=True)
|
||
last_visit_map = {}
|
||
```
|
||
|
||
核心字段（绩效概览、服务记录）查询失败则直接抛出 500。
|
||
|
||
### 前端错误处理
|
||
|
||
| 场景 | 处理方式 |
|
||
|------|---------|
|
||
| API 返回 403 | 显示"权限不足"提示，不跳转 |
|
||
| API 返回 404 | 显示"任务不存在"提示，返回列表页 |
|
||
| API 返回 500 | 显示"服务器错误"toast |
|
||
| 月份切换期间网络失败 | 恢复上一月份状态，显示重试提示 |
|
||
| 扩展字段为 null | 前端隐藏对应 UI 元素（如不显示余额标签） |
|
||
|
||
## 测试策略
|
||
|
||
### 双轨测试方法
|
||
|
||
RNS1.1 采用属性测试（Property-Based Testing）+ 单元测试（Unit Testing）双轨并行：
|
||
|
||
- **属性测试**：验证计算逻辑、枚举映射、分页排序、聚合等通用规则在所有输入上的正确性
|
||
- **单元测试**：验证具体的 API 端点行为、权限校验、FDW 查询集成、边界条件
|
||
|
||
### 属性测试配置
|
||
|
||
- **测试库**：[Hypothesis](https://hypothesis.readthedocs.io/)（Python，项目已使用）
|
||
- **测试位置**：`tests/` 目录（Monorepo 级属性测试）
|
||
- **最小迭代次数**：每个属性测试 100 次（`@settings(max_examples=100)`）
|
||
- **标签格式**：每个测试函数的 docstring 中标注 `Feature: rns1-task-performance-api, Property {N}: {property_text}`
|
||
- **每个正确性属性由一个属性测试实现**
|
||
|
||
### 属性测试清单
|
||
|
||
| Property | 测试函数 | 生成器 | 验证逻辑 |
|
||
|----------|---------|--------|---------|
|
||
| P1: 收入趋势计算 | `test_income_trend_computation` | `st.floats(min_value=0, max_value=1e6)` × 2 | 方向正确、差值正确、前缀符号一致 |
|
||
| P2: lastVisitDays 计算 | `test_last_visit_days_computation` | `st.dates(max_value=date.today())` | 天数差 = (today - date).days，非负 |
|
||
| P3: 维客线索净化 | `test_retention_clue_sanitization` | `st.text()` 生成含 `\n` 的 tag + `st.sampled_from` source | tag 无换行、source 在枚举内 |
|
||
| P4: courseTypeClass 映射 | `test_course_type_class_mapping` | `st.sampled_from(ALL_COURSE_TYPES)` | 结果在枚举内、无 `tag-` 前缀 |
|
||
| P5: 分页与排序 | `test_pagination_and_ordering` | `st.lists(st.fixed_dictionaries(...))` + `st.integers(1,10)` page/pageSize | 记录数 ≤ pageSize、hasMore 正确、排序正确 |
|
||
| P6: DateGroup 分组 | `test_date_group_correctness` | `st.lists(st.fixed_dictionaries({date, hours, income}))` | 日期唯一、组内日期一致、汇总正确 |
|
||
| P7: incomeItems desc 格式化 | `test_income_item_desc_format` | `st.floats(min_value=0.01)` rate × `st.floats(min_value=0)` hours | 包含费率和工时值 |
|
||
| P8: 月度汇总聚合 | `test_monthly_summary_aggregation` | `st.lists(st.fixed_dictionaries({hours, hours_raw, income}))` | count/hours/hours_raw/income 聚合正确 |
|
||
| P9: Pin/Unpin 往返 | `test_pin_unpin_roundtrip` | `st.booleans()` 初始状态 | pin→true、unpin→false、往返恢复 |
|
||
| P10: 权限隔离 | `test_authorization_enforcement` | `st.sampled_from(INVALID_USER_SCENARIOS)` | 所有场景返回 403 |
|
||
| P11: 前端派生字段 | `test_frontend_derived_fields` | `st.text(min_size=1)` name + `st.floats(0, 1e6)` balance + `st.floats(0, 10)` heartScore | avatarChar=name[0]、确定性、单调性 |
|
||
| P12: score 输入验证 | `test_note_score_validation` | `st.integers()` | 1-5 接受、超范围拒绝、null 接受 |
|
||
|
||
### 单元测试清单
|
||
|
||
| 测试目标 | 测试文件 | 关键用例 |
|
||
|---------|---------|---------|
|
||
| TASK-1 端点 | `tests/unit/test_xcx_tasks_v2.py` | 正常返回 TaskListResponse 结构；performance 含 15+ 字段；扩展字段 null 降级 |
|
||
| TASK-2 端点 | `tests/unit/test_task_detail.py` | 完整详情返回；customerId 正确；serviceRecords ≤ 20 条；notes ≤ 20 条 |
|
||
| PERF-1 端点 | `tests/unit/test_performance_overview.py` | DateGroup 结构正确；收入档位数据完整；新客/常客列表 |
|
||
| PERF-2 端点 | `tests/unit/test_performance_records.py` | 分页正确；summary 聚合正确；hasMore 标记 |
|
||
| PIN/UNPIN | `tests/unit/test_pin_unpin.py` | 响应格式 `{ isPinned: bool }`；404 不存在；403 非本人任务 |
|
||
| 权限校验 | `tests/unit/test_auth_rns11.py` | 未审核用户 403；无绑定 403；无权限 403 |
|
||
| FDW 查询 | `tests/unit/test_fdw_queries.py` | DQ-6 JOIN 正确；is_trash 排除；items_sum 口径 |
|
||
| AI 缓存降级 | `tests/unit/test_ai_cache_fallback.py` | 无缓存返回空；cache_type 映射正确 |
|
||
| tierCompleted 边界 | `tests/unit/test_tier_completed.py` | tierCompleted=true 时 bonusMoney=0 |
|
||
|
||
### 测试执行命令
|
||
|
||
```bash
|
||
# 属性测试（Hypothesis）
|
||
cd C:\NeoZQYY && pytest tests/ -v -k "rns1_task_performance"
|
||
|
||
# 单元测试
|
||
cd apps/backend && pytest tests/unit/ -v -k "xcx_tasks_v2 or task_detail or performance or pin_unpin or auth_rns11 or fdw_queries"
|
||
```
|