root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
675301f38b31212a0dd959db6a4b090d28892997
Neo-ZQYY/.kiro/specs/rns1-task-performance-api/design.md

34 KiB
Raw Blame History

技术设计文档 — 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（备注路由）

架构

模块交互

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 扩展为例）

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
@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

职责：绩效概览和绩效明细两个端点。

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）：

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。

核心函数：

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

新增函数：

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

核心函数：

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 扩展

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

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

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 查询遵循统一模式：

# 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）

-- ⚠️ 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）

-- 当月 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

后端计算逻辑：

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）

-- ⚠️ 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: 任务项扩展字段查询

-- 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）

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）

-- 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）

-- 新客：本月首次服务的客户
-- ⚠️ 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）采用优雅降级策略：

# 单个扩展字段查询失败不影响整体响应
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（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

测试执行命令

# 属性测试（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"
Reference in New Issue View Git Blame Copy Permalink