# 变更审计记录：助教看板和客户看板懒加载（分页加载）

| 字段 | 值 |
|------|-----|
| 日期 | 2026-03-29 05:49:50 |
| Prompt-ID | P20260329-054800 |

## 操作摘要

为助教看板（BOARD-1）和客户看板（BOARD-2）添加懒加载（分页加载）功能。后端 `get_coach_board` 新增 `page`/`page_size` 参数和内存分页逻辑，`CoachBoardResponse` 新增 `total`/`page`/`page_size` 字段。前端两个看板页面新增分页状态管理（`currentPage`/`pageSize`/`totalCount`/`hasMore`/`isLoadingMore`）、`onReachBottom` 触底加载、筛选变更时重置分页，以及加载更多/已加载全部的 UI 提示。

## 改动注解

### `apps/backend/app/schemas/xcx_board.py`
- 变更类型：修改
- 原始原因：后端需要返回分页元数据，前端才能判断是否还有更多数据
- 思路分析：在 `CoachBoardResponse` 中新增 `total`、`page`、`page_size` 三个字段，与客户看板 `CustomerBoardResponse` 保持一致的分页响应结构。同时本次 diff 包含了之前的 AreaFilterEnum 重建（7→9 项）、OverviewPanel 现金流字段 Optional 化、RevenuePanel/CashflowPanel 环比字段扩展等财务看板改动
- 修改结果：助教看板响应现在携带分页信息，前端可据此判断 hasMore 状态

### `apps/backend/app/routers/xcx_board.py`
- 变更类型：修改
- 原始原因：路由层需要接收前端传入的分页参数
- 思路分析：`get_coach_board` 路由新增 `page`（默认 1，≥1）和 `page_size`（默认 20，1~100）两个 Query 参数，透传给 service 层。同时添加了 `@trace_service` 装饰器用于链路追踪
- 修改结果：助教看板 API 支持 `?page=1&page_size=20` 分页查询

### `apps/backend/app/services/board_service.py`
- 变更类型：修改
- 原始原因：service 层需要实现分页逻辑，将全量数据切片返回
- 思路分析：采用内存分页策略——先查询全部助教数据并排序，再根据 `page`/`page_size` 切片。这种方式适合助教数量不大（通常 <100）的场景，避免了 SQL 层分页的复杂性。同时本次 diff 包含大量其他改动：环比同期对比重构、档位距升档计算、项目标签映射、客户看板批量查询优化、财务看板区域日粒度重构等
- 修改结果：`get_coach_board` 返回 `{items, total, page, page_size, dim_type}`，items 为当前页数据

### `apps/miniprogram/miniprogram/services/api.ts`
- 变更类型：修改
- 原始原因：API 层需要支持分页参数传递，并返回完整响应（含 total）而非仅 items
- 思路分析：`fetchBoardCoaches` 新增 `page`/`pageSize` 参数，返回类型从 `CoachCard[]` 改为 `{ items, total, page, pageSize }`（返回完整 data 而非 `data.items`）。`fetchBoardCustomers` 同样改为返回完整响应。这样前端页面可以从响应中获取 total 来计算 hasMore
- 修改结果：两个看板 API 函数现在返回分页元数据，前端可实现无限滚动

### `apps/miniprogram/miniprogram/pages/board-coach/board-coach.ts`
- 变更类型：修改
- 原始原因：助教看板页面需要实现触底加载更多的交互
- 思路分析：新增分页状态字段（`currentPage`/`pageSize`/`totalCount`/`hasMore`/`isLoadingMore`）。`loadData` 改为 async 函数，首页显示 loading，后续页显示底部加载指示器。新增 `onReachBottom` 生命周期函数实现触底加载。筛选变更（sort/skill/time）时重置分页状态并重新加载。同时将 Mock 数据替换为真实 API 调用
- 修改结果：助教看板支持下拉刷新 + 触底加载更多，每页 20 条

### `apps/miniprogram/miniprogram/pages/board-coach/board-coach.wxml`
- 变更类型：修改
- 原始原因：需要在列表底部显示加载状态提示
- 思路分析：在列表末尾新增两个条件渲染块：`isLoadingMore` 时显示 loading 动画 + "加载中..."，`!hasMore && coaches.length > 0` 时显示"已加载全部"。同时引入 WXS 格式化工具 `fmt`，将硬编码值替换为 `fmt.safe()` 调用
- 修改结果：用户滚动到底部时有明确的加载反馈

### `apps/miniprogram/miniprogram/pages/board-coach/board-coach.wxss`
- 变更类型：修改
- 原始原因：新增的加载更多 UI 需要样式支持
- 思路分析：新增 `.load-more` 容器（flex 居中、padding 36rpx）、`.load-more-text`（24rpx 灰色）、`.load-more-text--end`（更浅灰色表示已加载全部）
- 修改结果：加载更多区域视觉效果与整体页面风格一致

### `apps/miniprogram/miniprogram/pages/board-customer/board-customer.ts`
- 变更类型：修改
- 原始原因：客户看板同样需要懒加载功能，移除硬编码的 pageSize:100
- 思路分析：与助教看板相同的分页模式——新增分页状态、async loadData、onReachBottom、筛选重置分页。将 Mock 数据替换为真实 API 调用，新增头像颜色计算和项目标签映射。PROJECT_OPTIONS 的 value 从小写改为大写（与后端枚举一致）
- 修改结果：客户看板支持触底加载更多，默认每页 20 条，不再硬编码 100 条限制

### `apps/miniprogram/miniprogram/pages/board-customer/board-customer.wxml`
- 变更类型：修改
- 原始原因：移除"前100名"硬编码文案，新增加载更多 UI
- 思路分析：删除列表头部的"· 前100名"文案，totalCount 改用 `fmt.safe()` 格式化。列表末尾新增与助教看板相同的加载更多/已加载全部提示。同时新增客户项目标签（skill-tag）渲染
- 修改结果：客户列表不再暗示 100 条限制，底部有加载状态反馈

### `apps/miniprogram/miniprogram/pages/board-customer/board-customer.wxss`
- 变更类型：修改
- 原始原因：新增加载更多样式和项目标签样式
- 思路分析：新增 `.load-more` 系列样式（与助教看板一致）。新增 `.skill-tag` 及 4 种项目颜色类（chinese/snooker/mahjong/karaoke），样式与助教看板 skill-tag 保持一致。调整 `.card-grid--4` 列宽比例为 `1fr 0.6fr 0.5fr 0.6fr`
- 修改结果：加载更多和项目标签的视觉效果统一

## 风险评估

- 影响范围：助教看板和客户看板的前后端全链路
- 风险等级：中（接口契约变更，但向后兼容——新增字段不影响旧客户端）
- 注意事项：助教看板采用内存分页（先全量查询再切片），当助教数量较大时可能有性能问题，但当前业务场景下助教数量通常 <100，可接受