Neo-ZQYY/docs/prd/Neo_Specs/review-audit/P7-NS1-12.md

P7→NS1/RNS1 缺失项 #12：业绩明细页的口径选择交互

简要结论

• 状态：❌ 未解决
• 风险等级：🟡 低
• 后端 PERF-2 API 仅支持 year/month 参数（月口径），不支持周口径参数。前端 performance-records 页面仅有月份切换，无周口径切换 UI。

详细审查

审查范围

• apps/backend/app/routers/xcx_performance.py — PERF-2 端点参数定义
• apps/backend/app/services/performance_service.py — get_records() 函数签名
• apps/backend/app/services/fdw_queries.py — get_service_records() 查询条件
• apps/miniprogram/miniprogram/pages/performance-records/performance-records.ts — 口径切换逻辑
• apps/miniprogram/miniprogram/pages/performance-records/performance-records.wxml — 口径切换 UI

发现

1. 后端 PERF-2 仅支持月口径：

   • 路由参数：year: int, month: int, page: int, page_size: int
   • 无 period_type（月/周）、week_start/week_end 等周口径参数
   • get_records() 函数签名：(user_id, site_id, year, month, page, page_size)

2. FDW 查询按月过滤：get_service_records() 使用 create_time >= '{year}-{month:02d}-01' 和 create_time < '{year}-{month+1:02d}-01' 作为时间范围，硬编码为自然月。

3. 前端无周口径切换：

   • performance-records.ts 中仅有 switchMonth() 方法
   • WXML 中仅有月份切换器（month-switcher），无"本周/上周"切换 UI
   • 全局搜索 week|周|weekly 在后端绩效文件中无匹配

4. P7 提到"本周/上周"口径：原始 PRD 中定义了周维度的业绩查看，但 NS1/RNS1 仅实现了月维度。

证据

后端 PERF-2 路由定义（xcx_performance.py）：

@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()),
):

FDW 查询时间范围（fdw_queries.py:get_service_records）：

start_date = f"{year}-{month:02d}-01"
if month == 12:
    end_date = f"{year + 1}-01-01"
else:
    end_date = f"{year}-{month + 1:02d}-01"

前端仅有月份切换（performance-records.wxml）：

<view class="month-switcher">
    <view class="month-btn" data-direction="prev" bindtap="switchMonth">...</view>
    <text class="month-label">{{monthLabel}}</text>
    <view class="month-btn" data-direction="next" bindtap="switchMonth">...</view>
</view>

建议

1. 评估必要性：周口径在绩效场景中的实际使用频率较低（助教薪资按月结算），建议与产品确认是否为 MVP 必需。
2. 如需实现：
   • 后端：PERF-2 增加可选参数 period_type: str = Query("month", regex="^(month|week)$")，以及 week_start: date | None、week_end: date | None
   • FDW 查询：get_service_records() 支持自定义时间范围（start_date/end_date）而非固定月份
   • 前端：在月份切换器上方增加 Tab 切换（"按月" / "按周"），按周模式下展示"本周/上周"切换器
3. 渐进方案：可先在前端增加"自定义日期范围"筛选器，后端接受 start_date/end_date 参数，同时覆盖周口径和任意时间段需求。