Neo-ZQYY/docs/prd/specs/miniapp-page-refinement-2026-03-27.md

# 小程序多页面联调改造任务书

> 创建日期：2026-03-27
> 来源：本轮对话排查 customer-service-records 页面加载问题后，用户提出的 4 页面改造需求
> 状态：第 1 步后端改造已完成，第 2-4 步待执行

---

## 一、背景与前提

### 1.1 已完成的工作（本轮对话）

1. **权限守卫修复**：`auth-guard.ts` 的 `PAGE_ROLES` 中 `customer-detail`、`customer-service-records`、`coach-detail` 三个页面加入了 `coach` 角色，解决了 coach 进入后被 `reLaunch` 踢回首页的问题。

2. **ETL 连接复用**：`fdw_queries.py` 的 `_fdw_context` 新增 `etl_conn` 可选参数，`customer_service.py` 的 `get_customer_records` 中只创建一个 ETL 连接传给所有子查询，连接开销从 ~10s 降到 ~2.6s。

3. **后端 assistant_id 过滤**：
   - `customer_service.py` 新增 `_get_assistant_id()` 从 `auth.user_assistant_binding` 获取 assistant_id
   - `get_customer_records` 签名新增 `user_id` 参数，内部获取 assistant_id 后传给所有 fdw_queries 调用
   - `fdw_queries.get_customer_service_records` 和 `get_total_service_count` 加入可选 `assistant_id` 过滤（`site_assistant_id = %s`）
   - `_get_month_aggregation` 同步加入 `assistant_id` 过滤
   - 路由层 `xcx_customers.py` 传入 `user.user_id`

4. **后端到手收入计算**：
   - `get_customer_records` 中查询 `v_dws_assistant_salary_calc` 获取当月费率
   - 基础课到手 = hours × (base_course_price - base_deduction)
   - 激励课到手 = hours × bonus_course_price × (1 - bonus_deduction_ratio)
   - 充值提成到手 = ledger_amount（直接取）
   - Schema 新增 `month_income: float` 字段

5. **BACKLOG 更新**：`docs/roadmap/BACKLOG.md` 新增 AI BudgetTracker 和 admin_db_health UnicodeDecodeError 两条待办。

6. **联调规范更新**：`docs/guides/FRONTEND-BACKEND-INTEGRATION.md` 和 `.kiro/steering/frontend-backend-integration.md` 新增 ETL 连接复用规则。

### 1.2 已识别但未修复的数据问题

通过开发者工具读取页面 data 发现以下问题：

| # | 问题 | 原因 | 影响 |
|---|------|------|------|
| 1 | `customerName` 为空 | `loadCustomerInfo` 调的 `get_customer_detail` 还没做 ETL 连接复用优化，可能超时 | 顶部不显示客户名 |
| 2 | `totalServiceCount: 0` | 后端 `get_total_service_count` 返回 0，需排查 assistant_id 是否正确传入 | 顶部"服务X次"显示 0 |
| 3 | `monthHours: "0.0h"` | 后端返回 `duration` 是小时数（如 1.1），前端 `loadMonthRecords` 中 `rawRecords.reduce` 累加的是 `r.duration`，但后端字段名是 `duration`（CamelModel 输出 camelCase），需确认字段映射 | 月度时长显示 0 |
| 4 | `income: 0` | 后端到手收入计算中 `salary_calc` 可能没查到数据（assistant_id 为 None 或费率为 0） | 列表收入全部显示 0 |
| 5 | `displayDate` 格式错误 | 前端 `generateTimeRange` 把 `r.duration`（小时数）当分钟数处理，导致 `19:1.116...` | 时间显示乱码 |
| 6 | `table` 显示 ID | 后端返回 `table_id`（数字 ID），前端直接显示，应该显示台桌名称 | 台桌号显示为长数字 |
| 7 | `durationHours: 0` | 前端 `(r.duration \|\| 0) / 60` 把小时数再除以 60 变成了接近 0 的值 | 列表时长显示 0 |

### 1.3 开发环境

- Windows + PowerShell
- 后端：`start-admin.bat` 启动（uvicorn --reload 端口 8000）
- 前端：微信开发者工具（自动化端口 9420）
- 数据库：ETL 库（PG_DSN）+ 业务库（APP_DB_DSN），ETL 连接耗时 ~2.6s
- 可用调试工具：weixin-devtools MCP power（连接 `ws://127.0.0.1:9420`）

### 1.4 关键文件位置

| 文件 | 说明 |
|------|------|
| `apps/miniprogram/miniprogram/pages/customer-service-records/customer-service-records.ts` | 前端页面逻辑 |
| `apps/miniprogram/miniprogram/pages/customer-service-records/customer-service-records.wxml` | 前端页面模板 |
| `apps/miniprogram/miniprogram/pages/customer-service-records/customer-service-records.wxss` | 前端页面样式 |
| `apps/miniprogram/miniprogram/services/api.ts` | 前端 API 调用层 |
| `apps/miniprogram/miniprogram/utils/request.ts` | 前端请求封装（含 ResponseWrapper 解包） |
| `apps/miniprogram/miniprogram/utils/auth-guard.ts` | 权限守卫 |
| `apps/miniprogram/miniprogram/pages/task-detail/task-detail.ts` | 任务详情页（参考：60天服务记录列表格式） |
| `apps/miniprogram/miniprogram/pages/task-detail/task-detail.wxml` | 任务详情页模板（参考：service-record-card） |
| `apps/miniprogram/miniprogram/pages/performance/performance.ts` | 绩效页 |
| `apps/miniprogram/miniprogram/pages/performance/performance.wxml` | 绩效页模板 |
| `apps/miniprogram/miniprogram/pages/task-list/task-list.ts` | 任务列表页 |
| `apps/miniprogram/miniprogram/pages/task-list/task-list.wxml` | 任务列表页模板 |
| `apps/backend/app/services/customer_service.py` | 后端客户服务 |
| `apps/backend/app/services/fdw_queries.py` | 后端 FDW 查询 |
| `apps/backend/app/routers/xcx_customers.py` | 后端客户路由 |
| `apps/backend/app/schemas/xcx_customers.py` | 后端响应 Schema |
| `apps/backend/app/routers/xcx_auth.py` | 后端认证路由（/api/xcx/me） |
| `apps/backend/app/auth/dependencies.py` | JWT 解析（CurrentUser） |

### 1.5 关键数据口径

- **到手收入**：基础课 = hours × (base_course_price - base_deduction)；激励课 = hours × bonus_course_price × (1 - bonus_deduction_ratio)；充值提成 = ledger_amount
- **费率来源**：`v_dws_assistant_salary_calc`，按 `assistant_id + salary_month` 查询
- **DWD 层助教字段**：`site_assistant_id`（与 `auth.user_assistant_binding.assistant_id` 相同）
- **废单排除**：`is_delete = 0`
- **会员信息**：通过 `member_id` JOIN `v_dim_member (scd2_is_current=1)`
- **CamelModel**：后端 Pydantic schema 自动将 snake_case 转 camelCase 输出
- **ResponseWrapper**：后端中间件将 2xx JSON 包装为 `{ code: 0, data: <原始body> }`，前端 `request.ts` 自动解包

---

## 二、待执行任务

### 任务 A：customer-service-records 前端改造（优先级最高）

#### A1. 修复数据转换逻辑

前端 `loadMonthRecords` 中的字段映射需要对齐后端 CamelModel 输出：

```
后端返回（camelCase）    前端当前读取        问题
─────────────────────────────────────────────────
duration (float, 小时)   r.duration / 60     多除了一次 60
durationRaw (float, 小时) 未使用              应直接用
income (float, 到手元)   r.amount            字段名不匹配
timeRange (string|null)  未使用              后端已返回，前端用 generateTimeRange 自己算
courseType (string)       r.courseType        ✓ 正确
table (string|null)      r.table             后端返回 table_id 数字，需要改为台桌名
recordType (string)      前端自己判断         后端已返回，应直接用
isEstimate (bool)        r.isEstimate        ✓ 正确
drinks (string|null)     r.drinks            后端当前返回 null，后续需补齐
```

修改要点：
- `durationHours` 直接用 `r.duration`（已是小时数），不再 `/60`
- `durationRaw` 直接用 `r.durationRaw`
- `income` 用 `r.income`（后端已计算到手）
- `displayDate` 优先用后端返回的 `r.timeRange`，无值时才用 `generateTimeRange`
- `generateTimeRange` 的参数是小时数不是分钟数，需修正或移除
- `table` 字段：后端当前返回 `table_id`（数字），需要后端改为返回台桌名称，或前端做映射

#### A2. 修复月度统计

- `monthHours` 累加逻辑：`rawRecords.reduce((sum, r) => sum + (r.duration || 0), 0)` — 后端返回的 `duration` 已是小时数，不需要再 `/60`
- 新增 `monthIncome`：从后端返回的 `monthIncome` 字段读取并展示

#### A3. 修复顶部信息

- `customerName`：`loadCustomerInfo` 调的 `fetchCustomerDetail` 超时问题 — 方案 1：给 `get_customer_detail` 也做 ETL 连接复用；方案 2：从 `get_customer_records` 的返回值中直接取 `customerName`（后端已返回）
- `totalServiceCount`：从 `get_customer_records` 返回值中取（后端已返回 `totalServiceCount`）
- 手机号查看/复制交互：对齐 task-detail 页面的实现
- 首字母头像：使用通用颜色规则（`nameToAvatarColor`）

#### A4. 列表记录格式对齐 task-detail

- 对齐 task-detail 的"60天内服务记录"列表的 `service-record-card` 组件格式
- 确认 `service-record-card` 组件是否已存在，还是内联在 task-detail 的 WXML 中
- 到手收入显示：`¥XXX`
- 课程类型标签：基础课/激励课/充值
- 折前/折后时长：`durationRaw !== durationHours` 时才显示折前

#### A5. 加速加载

- `loadCustomerInfo` 可以去掉（改为从 `loadMonthRecords` 的返回值中取 `customerName` 和 `customerPhone`）
- 减少一个 API 请求 = 减少一次 ETL 连接开销

---

### 任务 B：task-detail 折前时长条件显示

文件：`apps/miniprogram/miniprogram/pages/task-detail/task-detail.wxml`

- 找到服务记录列表中显示"折前X.Xh"的位置
- 加条件判断：`wx:if="{{item.durationRaw && item.durationRaw !== item.durationHours}}"`
- 折前和折后相等时隐藏折前标签

---

### 任务 C：performance 页面改造

文件：`apps/miniprogram/miniprogram/pages/performance/performance.ts` + `.wxml`

#### C1. 未知客户点击拦截

- 找到客户卡片点击跳转逻辑
- 判断 `memberId <= 0`（散客/未知客户）时，`wx.showToast({ title: '未知客户不提供查看客户任务详情', icon: 'none' })` 并 return
- 非散客正常跳转

#### C2. 角色标签对齐 task-list

- 查看 task-list 页面的角色标签展示方式（WXML + WXSS）
- 对齐 performance 页面顶部的角色标签样式

---

### 任务 D：头像修复（performance + task-list）

文件：`performance.ts`、`task-list.ts`、对应 `.wxml`

- 后端 `/api/xcx/me` 已返回 `avatarUrl` 字段（apply 时上传的头像）
- 前端 `fetchMe()` 返回的 `data.avatarUrl` 需要绑定到页面 data
- WXML 中头像 `<image>` 的 `src` 应优先用 `avatarUrl`，无值时 fallback 到默认占位图或首字母头像
- 确认 task-list 和 performance 两个页面的 banner 区域头像都使用此逻辑

---

### 任务 E：后端补充优化（可选）

#### E1. get_customer_detail ETL 连接复用

- 与 `get_customer_records` 相同的模式：创建一个 ETL 连接传给所有 fdw_queries 调用
- 涉及的子查询：`get_member_info`、`get_member_balance`、`get_consumption_60d`、`get_last_visit_days`、`_build_consumption_records`、`_build_coach_tasks`、`_build_favorite_coaches`

#### E2. 台桌名称返回

- 当前 `get_customer_service_records` 返回 `site_table_id`（数字 ID）
- 需要 JOIN `v_dim_table`（或类似维度表）获取台桌名称
- 或者前端做映射（不推荐，增加前端复杂度）

#### E3. 到手收入排查

- 确认 `_get_assistant_id` 返回值是否正确（可能 `user_assistant_binding` 中没有对应记录）
- 确认 `get_salary_calc` 是否能查到当月数据（可能该月还没有 salary_calc 记录）
- 费率为 0 时的兜底处理

---

## 三、执行顺序建议

1. **E3**（排查到手收入为 0 的原因）→ 确认后端数据正确性
2. **A1 + A2 + A3**（前端数据转换修复）→ 页面能正确展示数据
3. **A4**（列表格式对齐 task-detail）→ UI 一致性
4. **A5**（加速加载）→ 去掉多余 API 请求
5. **B**（task-detail 折前时长）→ 小改动
6. **C**（performance 页面）→ 独立改动
7. **D**（头像修复）→ 独立改动
8. **E1 + E2**（后端补充优化）→ 可选

---

## 四、验证方式

每步完成后：
1. 微信开发者工具编译（Ctrl+B）
2. 操作路径：任务列表 → 轩哥 → 任务详情 → 查看全部服务记录
3. 用 weixin-devtools MCP power 的 `evaluate_script` 读取页面 data 验证字段值
4. 用 `list_console_messages` 检查是否有错误
5. 后端改动通过 uvicorn `--reload` 自动加载，看后端窗口有无报错

---

## 五、参考文档

- `docs/guides/FRONTEND-BACKEND-INTEGRATION.md` — 联调规范（字段命名、到手收入口径、ETL 连接复用等）
- `.kiro/steering/frontend-backend-integration.md` — 联调规范摘要
- `.kiro/steering/feiqiu-data-rules.md` — 飞球数据规范索引
- `apps/backend/app/schemas/xcx_customers.py` — 后端响应 Schema（CamelModel 自动转 camelCase）
- `apps/miniprogram/miniprogram/utils/request.ts` — 前端请求封装（ResponseWrapper 解包逻辑）