Neo-ZQYY/docs/prd/Neo_Specs/review-audit/P9-NS1-23.md

P9→NS1/RNS1 缺失项 #23：客户详情页"可用月数"的计算说明

简要结论

• 状态：❌ 未解决
• 风险等级：🟡 低
• available_months 字段仅在客户看板 Schema 中定义，客户详情页 API 未返回该字段，计算公式未在代码中实现

详细审查

审查范围

• apps/backend/app/services/customer_service.py — get_customer_detail() 返回字段
• apps/backend/app/schemas/xcx_board.py — Schema 定义
• apps/backend/app/services/board_service.py — 看板服务
• apps/backend/app/services/fdw_queries.py — 数据查询

发现

1. xcx_board.py 中定义了 available_months: str # "约0.8个月" 和 monthly_consume: float
2. fdw_queries.py 中查询了 monthly_consume 字段（来自 v_dws_member_consumption_summary）
3. 但在整个后端代码中，未找到 available_months 的计算赋值逻辑——仅有 Schema 定义
4. customer_service.py 的 get_customer_detail() 返回字段中无 available_months
5. 客户详情页前端也未展示"可用月数"字段
6. P9 定义的计算公式（余额 ÷ 月均消耗）和边界处理（月均消耗为 0 时）均未实现

证据

# xcx_board.py — 仅有 Schema 定义
class CustomerBoardItem(BaseModel):
    monthly_consume: float
    available_months: str  # "约0.8个月"

# customer_service.py — get_customer_detail() 返回值中无 available_months
return {
    "id": customer_id,
    "name": name,
    "phone": phone,
    "balance": balance,
    "consumption_60d": consumption_60d,
    "days_since_visit": days_since_visit,
    # 无 available_months
}

# 全局搜索 available_months 赋值逻辑 → 无结果
# 仅在 Schema 定义中出现

建议

1. 在 customer_service.py 或 board_service.py 中实现计算逻辑：

   def _calc_available_months(balance: float, monthly_consume: float) -> str:
       if monthly_consume <= 0:
           return "—"  # 月均消耗为 0，无法计算
       months = balance / monthly_consume
       return f"约{months:.1f}个月"
   

2. 需要确认 monthly_consume 的口径：是 60 天月均还是历史全量月均
3. 边界处理：余额为 0 → "0个月"；月均消耗为 0 → 显示"—"或"充足"
4. 将计算结果添加到 get_customer_detail() 返回值中，前端在 Banner 统计区域展示