feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations

docs/database/BD_Manual_biz_tables.md

@@ -16,7 +16,7 @@
 |---|------|------|--------|
 | 1 | `biz.coach_tasks` | 助教任务表：存储任务分配、状态、有效期、置顶、放弃原因等 | 15 |
 | 2 | `biz.coach_task_history` | 任务变更历史表：记录任务关闭/新建/置顶/放弃的追溯链 | 9 |
-| 3 | `biz.notes` | 统一备注表：通过 `type` 字段区分普通备注/回访备注/放弃原因，含星星评分 | 14 |
+| 3 | `biz.notes` | 统一备注表：通过 `type` 字段区分普通备注/回访备注/放弃原因，含星星评分 | 15 |
 | 4 | `biz.trigger_jobs` | 触发器配置表：存储 cron/interval/event 三种触发方式的配置与执行状态 | 9 |
 
 ### 表字段明细
@@ -55,7 +55,7 @@
 | `detail` | JSONB | 可空 | 附加详情（如放弃原因等） |
 | `created_at` | TIMESTAMPTZ | DEFAULT NOW() | 记录时间 |
 
-#### biz.notes（14 字段）
+#### biz.notes（15 字段）
 
 | 字段 | 类型 | 约束 | 说明 |
 |------|------|------|------|
@@ -73,6 +73,7 @@
 | `ai_analysis` | TEXT | 可空 | AI 分析结果（P5 实现） |
 | `created_at` | TIMESTAMPTZ | DEFAULT NOW() | 创建时间 |
 | `updated_at` | TIMESTAMPTZ | DEFAULT NOW() | 更新时间 |
+| `score` | SMALLINT | CHECK (1-5)，可空 | 备注星星评分，助教创建备注时可选填写，不参与 AI 分析（RNS1.1 新增） |
 
 #### biz.trigger_jobs（9 字段）
 
@@ -99,6 +100,7 @@
 | `notes` | `idx_notes_target` | INDEX | `(site_id, target_type, target_id)`，按目标查询备注加速 |
 | `notes` | CHECK `rating_service_willingness` | CHECK | `BETWEEN 1 AND 5` |
 | `notes` | CHECK `rating_revisit_likelihood` | CHECK | `BETWEEN 1 AND 5` |
+| `notes` | CHECK `score` | CHECK | `score IS NULL OR (score >= 1 AND score <= 5)`（RNS1.1 新增） |
 | `notes` | FK `task_id` | FK | → `biz.coach_tasks(id)` |
 | `trigger_jobs` | UNIQUE `job_name` | UNIQUE | 触发器名称唯一 |
 
@@ -128,6 +130,44 @@
 
 ---
 
+## 2.1 RNS1.3 看板接口引用说明（2026-03-20 补充）
+
+RNS1.3（三看板接口）BOARD-1 助教看板的任务维度查询引用了 `biz.coach_tasks`（无 schema 变更，仅新增读取路径）：
+
+| 表 | 引用接口 | 用途 |
+|----|---------|------|
+| `biz.coach_tasks` | BOARD-1 `_query_coach_tasks()` | 按 `site_id` + `assistant_id` + 日期范围查询任务完成数，按 `task_type` 分类统计 `recall`（召回类：`high_priority_recall` / `priority_recall`）和 `callback`（回访类：`follow_up_visit` / `relationship_building`），筛选条件 `status = 'completed'` + `completed_at BETWEEN start_date AND end_date` |
+
+查询模式：
+```sql
+SELECT assistant_id, task_type, COUNT(*) AS cnt
+FROM biz.coach_tasks
+WHERE site_id = :site_id
+  AND assistant_id = ANY(:assistant_ids)
+  AND status = 'completed'
+  AND completed_at BETWEEN :start_date AND :end_date
+GROUP BY assistant_id, task_type
+```
+
+> 该查询走 `idx_coach_tasks_assistant_status` 索引（`site_id, assistant_id, status`），无需新增索引。
+
+---
+
+## 2.2 RNS1.2 接口引用说明（2026-03-18 补充）
+
+RNS1.2（客户与助教接口）新增 3 个端点，引用了以下 biz/public 表（无 schema 变更，仅新增读取路径）：
+
+| 表 | 引用接口 | 用途 |
+|----|---------|------|
+| `biz.coach_tasks` | CUST-1 `coachTasks` 模块、COACH-1 `visibleTasks`/`hiddenTasks`/`abandonedTasks`/`tasksCompleted` | 查询客户关联的助教任务（按 `member_id`）；查询助教任务分组（按 `assistant_id`、`status` 分组）；统计当月完成任务数 |
+| `biz.notes` | CUST-1 `notes` 模块、COACH-1 `notes`/任务备注 | 查询客户备注（`target_type='member'`，最多 20 条）；查询助教相关备注（最多 20 条）；查询任务关联备注（`task_id` 关联） |
+| `biz.ai_cache` | CUST-1 `aiInsight` 模块 | 查询 AI 分析缓存（`cache_type='app4_analysis'`，`target_id=customerId`），解析 `cache_value` JSON 生成洞察摘要和策略建议 |
+| `public.member_retention_clue` | CUST-1 `retentionClues` 模块 | 查询维客线索（按 `created_at` 倒序），格式与 TASK-2 一致 |
+
+> 以上均为只读查询，不涉及表结构变更。`biz.ai_cache` 表由 P5（AI 集成）创建，`public.member_retention_clue` 表由独立迁移创建。
+
+---
+
 ## 3. 回滚策略
 
 按逆序 `DROP TABLE IF EXISTS CASCADE`（迁移脚本末尾已包含注释形式的回滚语句）：