chore(audit): 2026-04-20 历史批次预审 + 文档同步 + .gitignore 修正

- 新增 docs/audit/changes/2026-04-20__historical-batch-pre-audit.md
  157 文件分批盘点审计（7 条主线 + 10 项高/中风险 + 2 份迁移 SQL DDL 清单）
- 补追 docs/audit/changes/2026-04-15__meituan-settle-core-sync.md
  原审计产物因 .gitignore 屏蔽长期未入仓，本次一并追回
- 刷新 docs/audit/audit_dashboard.md（33 条审计记录）
- .gitignore 白名单放行 docs/audit/changes/*.md 与 audit_dashboard.md
  同时屏蔽 changes/changes/ 嵌套误产物目录
- 新增 docs/specs/audit-gap-recovery/tasks.md
  扫描嵌套目录发现 96 份 D 类孤本（从未入过 git history），
  生成独立 PRD 供单开任务清理与补追
- 文档同步（高风险项）：
  - apps/backend/docs/API-REFERENCE.md (+69)
  - apps/miniprogram/README.md (+50)
  - apps/etl/connectors/feiqiu/docs/architecture/data_flow.md (+52/-2)
  - apps/etl/connectors/feiqiu/docs/architecture/system_overview.md (+5/-3)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

apps/backend/docs/API-REFERENCE.md

@@ -463,9 +463,21 @@ MVP 全链路验证端点，从 `test."xcx-test"` 表读取数据。
 绩效明细（PERF-2）。返回指定月份的服务记录明细，按日期分组，支持分页。
 
 查询参数：
-- `month`：月份（格式 `YYYY-MM`，默认当月）
+- `year`：年份（必填）
+- `month`：月份（`1-12`，必填）
 - `page`：页码（默认 1）
-- `page_size`：每页条数（默认 20）
+- `page_size`：每页条数（默认 20，最大 100）
+- `coach_id`：目标助教 ID（可选，管理者视角）
+
+权限分流（运行时通过 `get_user_permissions()` 实时检查，非 `require_permission` 中间件）：
+- 不带 `coach_id`（查自己）：需 `view_tasks` 权限，`assistant_id` 由当前登录用户绑定决定
+- 带 `coach_id`（查他人）：需 `view_board_coach` 权限（`manager`/`head_coach`/`staff`），`assistant_id` 使用传入值；同 site 约束由 `user.site_id` 隐式保证
+- 缺少对应权限统一返回 `HTTP 403 权限不足`
+
+对应服务层变更：`performance_service.get_records()` 新增 `assistant_id_override` 参数。
+
+响应字段新增：
+- `dateGroups[].records[].isScattered`：散客标记（`member_id ≤ 0` 时为 `true`），前端据此将客户姓名置灰
 
 ---
 
@@ -573,6 +585,63 @@ MVP 全链路验证端点，从 `test."xcx-test"` 表读取数据。
 
 ---
 
+## 17A. 小程序助教详情 `/api/xcx/coaches`
+
+所有端点需 JWT（approved 状态）+ `view_board_coach` 权限。
+
+### GET `/api/xcx/coaches/{coach_id}/banner`
+助教 banner 轻量信息。仅返回 `id` / `name` / `level` / `storeName`，用于 `coach-service-records` 等只需 banner 数据的页面首屏快速加载。
+
+比 `/{coach_id}` 详情快一个数量级。
+
+权限：`view_board_coach`
+
+响应：`CoachBannerResponse`
+```json
+{ "id": 123, "name": "张三", "level": "金牌", "storeName": "朗朗桌球（总店）" }
+```
+
+### GET `/api/xcx/coaches/{coach_id}`
+助教详情（COACH-1）。返回助教基础信息、绩效、收入、档位、任务分组、TOP 客户、近期服务、历史月份、备注。
+
+权限：`view_board_coach`（2026-03-27 权限改造 W4：助教详情跟助教看板走）
+
+响应：`CoachDetailResponse`
+
+字段说明：
+
+- `storeName`：助教所在门店名（跟随被查看助教所在门店，供小程序 banner 展示）
+- `performance`：`PerformanceMetrics`，与任务页 `PerformanceSummary` 同源（来自 `monthly_summary` 实时值）。字段从 6 扩展到 25：
+  - 核心字段：`totalHours`、`totalIncome`、`totalCustomers`、`monthLabel`、`tierNodes`、`basicHours`、`bonusHours`、`currentTier`（数组下标 0-based）、`nextTierHours`、`tierCompleted`、`bonusMoney`、`incomeTrend`、`incomeTrendDir`、`prevMonth`、`currentTierLabel`
+  - 详情专属扩展：`customerBalance`、`tasksCompleted`
+  - 兼容旧字段（前端渐进适配）：`monthlyHours`、`monthlySalary`
+- `taskStats`：`CoachTaskStats`，当月任务完成统计（按 `task_type` 分类计数，数据源 `coach_tasks` 表）
+  - `callback`：`follow_up_visit` 完成数
+  - `recall`：`high_priority_recall` + `priority_recall` 完成数
+- `topCustomers[].isScattered`：散客标识（`member_id ≤ 0`），前端据此将客户姓名置灰
+- `serviceRecords[].isScattered`：同上，作用于近期服务记录
+
+---
+
+## 17B. 小程序客户详情 `/api/xcx/customers`
+
+所有端点需 JWT（approved 状态）+ `view_board_customer` 权限。
+
+### GET `/api/xcx/customers/{customer_id}`
+客户详情（CUST-1）。返回客户基础信息、Banner 概览、AI 洞察、助教任务、心动助教、维客线索、消费记录、备注。
+
+权限：`view_board_customer`（2026-03-27 权限改造 W4：客户详情跟客户看板走）
+
+响应：`CustomerDetailResponse`
+
+字段说明（本次新增）：
+
+- `consumptionRecords[].foodDetail`：自定义食品类目名称（`string | null`）。为空时前端降级展示「食品酒水」
+- `notes[].creatorName`：备注创建者姓名
+- `notes[].creatorRole`：备注创建者角色
+
+---
+
 ## 18. 小程序 CHAT `/api/xcx/chat`
 
 所有端点需 JWT（approved 状态）。替代原 `xcx_ai_chat`（`/api/ai/*`），统一迁移到 `/api/xcx/chat/*` 路径。