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>
2026-04-20 06:32:58 +08:00
parent 2a7a5d68aa
commit 80bda9b991
9 changed files with 914 additions and 366 deletions
--- a/apps/backend/docs/API-REFERENCE.md
+++ b/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/*` 路径。
--- a/apps/etl/connectors/feiqiu/docs/architecture/data_flow.md
+++ b/apps/etl/connectors/feiqiu/docs/architecture/data_flow.md
@@ -19,9 +19,17 @@
 │  明细数据 — 清洗、标准化、关联          │
 │  维度表走 SCD2（缓慢变化维度）          │
 │  事实表按时间增量写入                   │
-└───────────────┬───────────────────────┘
-                │ DWS 汇总任务
-                ▼
+└───────┬───────────────┬───────────────┘
+        │               │ CORE_DIM_SYNC
+        │ DWS 汇总任务   ▼
+        │       ┌───────────────────────┐
+        │       │  Core 层（core）      │
+        │       │  跨平台统一维度层      │
+        │       │  dim_assistant / dim_ │
+        │       │  member / dim_site /  │
+        │       │  dim_table            │
+        │       └───────────────────────┘
+        ▼
 ┌───────────────────────────────────────┐
 │  DWS 层（dws）                         │
 │  数据服务 — 汇总、指标                  │
@@ -34,6 +42,7 @@
 │  INDEX 层（dws）                       │
 │  自定义指数算法                         │
 │  WBI / NCI / RS / OS / MS / ML         │
+│  日快照存储（stat_date）               │
 └───────────────────────────────────────┘
 ```

@@ -86,6 +95,7 @@
 | 会员分析 | `DWS_MEMBER_CONSUMPTION`、`DWS_MEMBER_VISIT` | 每日 |
 | 工资计算 | `DWS_ASSISTANT_SALARY` | 每月（月初） |
 | 指数算法 | `DWS_WINBACK_INDEX`、`DWS_NEWCONV_INDEX`、`DWS_RELATION_INDEX` | 每 2-4 小时 |
+| Core 维度同步 | `CORE_DIM_SYNC` | 每日（DWD_LOAD_FROM_ODS 之后） |

 ### 自定义指数算法

@@ -102,6 +112,44 @@

 公共参数：`percentile_lower/upper`（分位截断锚点）、`ewma_alpha`（指数加权移动平均平滑系数）。

+### 指数日快照（2026-04 重构）
+
+三张指数表（`relation_index` / `winback_index` / `newconv_index`）新增 `stat_date DATE NOT NULL DEFAULT CURRENT_DATE` 字段，唯一约束扩展为 `(site_id, member_id[, assistant_id], stat_date)`。每次任务运行追加当日快照而非覆盖历史，为指数回测、历史演化分析提供原始数据基础。Winback 任务配套 365 天保留策略，清理超过 365 天的历史快照以控制表体积。
+
+## Core 维度层（跨平台统一维度）
+
+- Schema：`core`
+- 定位：跨平台统一维度层，屏蔽 ODS/DWD 多数据源（飞球 / 美团 / 后续新平台）的字段差异，供 `app` 视图层和业务库 FDW 统一引用
+- 核心任务：`CORE_DIM_SYNC`（归属 DWS 层任务目录 `tasks/dws/core_dim_sync_task.py`）
+- 上游依赖：`DWD_LOAD_FROM_ODS`（必须先完成 DWD 维度表 SCD2 写入）
+- 同步范围：4 张维度表 — `dim_assistant` / `dim_member` / `dim_site` / `dim_table`
+- 数据来源：DWD 层 `scd2_is_current = 1` 的当前版本快照
+- 同步策略：TRUNCATE + 全量 INSERT（维度表行数较小，执行时间极短，避免增量合并复杂度）
+- 起因：修复 `app` 视图在 core 维度为空时返回空结果的问题（关联审计 `docs/audit/changes/2026-04-15__meituan-settle-core-sync.md`）
+
+## Utility 工具任务
+
+工具任务位于 `tasks/utility/`，不在日常编排链路中，由手动 CLI 触发，服务于 schema 初始化、历史数据回填和回测推演等一次性或周期性离线需求。
+
+### DWS_INDEX_BACKFILL（指数历史快照回填）
+
+- 源码：`tasks/utility/index_backfill_task.py`
+- 职责：逐天调用三个指数任务（`DWS_RELATION_INDEX` / `DWS_WINBACK_INDEX` / `DWS_NEWCONV_INDEX`）生成历史日快照，回填缺失的 `stat_date` 行
+- 性能优化：三个指数任务实例在整轮回填中创建 1 次、循环 N 天复用，避免 N×3 次初始化开销（以 255 天为例避免 765 次初始化）
+- 前置条件：三张指数表已完成日快照改造（`stat_date` 字段 + 复合唯一约束）
+- 用途：指数算法参数调优验证、历史对照、补齐生产数据缺口
+- 关联专题：P19 指数回测框架 Phase 1e
+
+### DWS_TASK_SIMULATION（任务引擎历史推演）
+
+- 源码：`tasks/utility/task_simulation_task.py`
+- 职责：基于指数日快照，逐天重放 `task_generator` + `recall_detector` 逻辑，还原任务的完整生命周期（生成 / 升级 / 转移 / 完成 / follow_up）
+- 前置条件：需先运行 `DWS_INDEX_BACKFILL` 产出完整的历史指数快照作为推演输入
+- 数据库连接：额外使用业务库独立连接（`APP_DB_DSN` 环境变量），推演结果写入业务库任务相关表
+- 任务引擎双模式配合：`task_engine.py` 同期升级为双模式 — HTTP 实时模式（日常生产）+ 推演模式（回测，由 `as_of_date` 参数驱动），两种模式共用核心规则逻辑
+- 用途：回测验证分级分配、升级、转移规则的参数配置与边界行为
+- 关联专题：P19 指数回测框架 Phase 2
+
 ## ETL 管理层

 - Schema：`meta`
--- a/apps/etl/connectors/feiqiu/docs/architecture/system_overview.md
+++ b/apps/etl/connectors/feiqiu/docs/architecture/system_overview.md
@@ -44,8 +44,10 @@
 │  ├── ods/                 ODS 抓取任务（23 个业务实体）   │
 │  ├── dwd/                 DWD 装载任务（维度/事实/质检）  │
 │  ├── dws/                 DWS 汇总与指数任务             │
-│  │   └── index/           指数计算（WBI/NCI/RS/OS/MS/ML）│
-│  ├── utility/             工具任务（Schema 初始化等）     │
+│  │   ├── index/           指数计算（WBI/NCI/RS/OS/MS/ML）│
+│  │   └── core_dim_sync    Core 维度层全量同步（4 维度）   │
+│  ├── utility/             工具任务（Schema 初始化 /      │
+│  │                        指数回填 / 任务引擎推演）       │
 │  └── verification/        ETL 后置校验                   │
 └──────────┬──────────────────────────────────────────────┘
           │
--- a/apps/miniprogram/README.md
+++ b/apps/miniprogram/README.md
@@ -89,6 +89,7 @@ apps/miniprogram/
 | `pages/customer-detail/customer-detail` | 客户详情页（完整档案 + AI 洞察 + 维客线索） | |
 | `pages/customer-service-records/customer-service-records` | 客户服务记录页（按日期分组的消费记录） | |
 | `pages/coach-detail/coach-detail` | 助教详情页（业绩数据 + 客户列表） | |
+| `pages/coach-service-records/coach-service-records` | 助教业绩明细页（管理者视角，查看指定助教的业绩明细） | |
 | `pages/chat/chat` | AI 对话页（SSE 流式输出，按上下文进入对话） | |
 | `pages/chat-history/chat-history` | 对话历史列表页 | |
 | `pages/dev-tools/dev-tools` | 开发调试面板（仅 develop 环境，通过 dev-fab 浮动按钮进入） | |
@@ -118,6 +119,50 @@ apps/miniprogram/
 | service-record-card | `components/service-record-card/` | 服务记录单项卡片 |
 | star-rating | `components/star-rating/` | 星级评分组件 |

+## 业绩明细双视角
+
+业绩明细存在两个严格隔离的页面，职责互不交叉：
+
+- `performance-records`（助教自查）
+  - 视角：当前登录用户（无需 coachId）
+  - 权限：无需额外守卫
+  - 点击单条记录：跳 `task-detail?taskId=xxx`（关注任务）
+- `coach-service-records`（管理者查看）
+  - 视角：指定助教，coachId 必传（来自 URL query）
+  - 权限：`view_board_coach`
+  - 点击单条记录：跳 `customer-detail?memberId=xxx`（关注客户）
+
+coach-service-records 页面约定：
+
+- 入口：`coach-detail` 页面的"查看更多"按钮
+- `onShow` 必须通过 `checkPageAccess('view_board_coach')` 守卫
+- 数据源：
+  - Banner：`fetchCoachBanner(coachId)` 轻量接口
+  - 记录：`fetchPerformanceRecords({ year, month, coachId, page, pageSize })`
+- 源码：`miniprogram/pages/coach-service-records/*`
+
+## 共享工具
+
+业绩进度条动画参数与计算逻辑的单一源头：`miniprogram/utils/perf-progress.ts`。被 `task-list.ts` 与 `coach-detail.ts` 共同使用，避免双份漂移。
+
+导出清单：
+
+- 常量：`SHINE_SPEED`、`SPARK_DELAY_MS`、`SPARK_DUR_MS`、`NEXT_LOOP_DELAY_MS`、`SHINE_WIDTH_RPX`
+- 类型：`TickItem` 接口
+- 函数：`calcShineDur`、`buildTicks`、`buildProgressBarData`
+
+新建同类动画参数或档位刻度逻辑时，统一落在此文件，禁止在页面脚本内就地写常量。
+
+## 数据规范
+
+### 散客标记（isScattered）
+
+后端判定规则：`member_id <= 0` 时在响应字段上标记 `isScattered = true`，标识该条记录为散客（无会员档案）。
+
+涉及页面：`coach-detail`、`performance-records`、`coach-service-records`、`customer-detail`。
+
+前端渲染约定：为承载散客信息的节点追加 CSS 类 `--scattered`，以置灰方式区分于实名会员；散客条目不提供跳转到 `customer-detail` 的入口。
+
 ## 后端 API 集成

 ### API 地址配置
@@ -210,6 +255,11 @@ POST /api/xcx-auth/login  →  重新登录获取完整令牌（含 site_id + ro
 | `/api/xcx/chat/messages` | GET | 通过上下文查消息 |
 | `/api/xcx/chat/stream` | POST | SSE 流式对话 |

+### services/api.ts 近期新增
+
+- `fetchCoachBanner(coachId: number)` — 轻量助教 banner 数据，供 `coach-service-records` 顶部卡片复用
+- `fetchPerformanceRecords({ year, month, page, pageSize, coachId? })` — 新增可选 `coachId` 参数；不传为助教自查视角（后端以当前登录用户过滤），传入则为管理者查看视角（后端按权限码 `view_board_coach` 分流校验）
+
 > 完整接口契约见 [`docs/miniprogram-dev/API-contract.md`](../../docs/miniprogram-dev/API-contract.md)
 > 后端 API 参考见 [`apps/backend/docs/API-REFERENCE.md`](../backend/docs/API-REFERENCE.md)