feat: 累积功能变更 — 聊天集成、租户管理、小程序更新、ETL 增强、迁移脚本

包含多个会话的累积代码变更： - backend: AI 聊天服务、触发器调度、认证增强、WebSocket、调度器最小间隔 - admin-web: ETL 状态页、任务管理、调度配置、登录优化 - miniprogram: 看板页面、聊天集成、UI 组件、导航更新 - etl: DWS 新任务（finance_area_daily/board_cache）、连接器增强 - tenant-admin: 项目初始化 - db: 19 个迁移脚本（etl_feiqiu 11 + zqyy_app 8） - packages/shared: 枚举和工具函数更新 - tools: 数据库工具、报表生成、健康检查 - docs: PRD/架构/部署/合约文档更新 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-06 00:03:48 +08:00
parent 70324d8542
commit 6f8f12314f
515 changed files with 76604 additions and 7456 deletions
--- a/apps/backend/README.md
+++ b/apps/backend/README.md
@@ -21,10 +21,28 @@ apps/backend/
 │   ├── auth/                # 认证模块
 │   │   ├── dependencies.py  # FastAPI 依赖注入（CurrentUser）
 │   │   └── jwt.py           # JWT 签发/验证/密码哈希
-│   ├── routers/             # 17 个路由模块（详见 API 参考）
+│   ├── routers/             # 18 个路由模块（详见 API 参考）
 │   ├── schemas/             # Pydantic 请求/响应模型
 │   ├── services/            # 业务逻辑层
 │   ├── middleware/          # 中间件（ResponseWrapper 全局响应包装）
+│   ├── ai/                  # AI 模块（DashScope Application API + 8 个应用）
+│   │   ├── config.py            # AIConfig — 环境变量加载（DASHSCOPE_*）
+│   │   ├── dashscope_client.py  # DashScope Application API 统一封装
+│   │   ├── dispatcher.py        # AIDispatcher — 事件调度 + 调用链编排
+│   │   ├── circuit_breaker.py   # 熔断器（按 app_id 独立）
+│   │   ├── rate_limiter.py      # 限流器（用户/门店维度）
+│   │   ├── budget_tracker.py    # Token 预算追踪（日/月限额）
+│   │   ├── run_log_service.py   # AI 运行日志 CRUD
+│   │   ├── exceptions.py        # 异常层级（DashScopeError 基类）
+│   │   ├── cache_service.py     # AI 缓存读写（biz.ai_cache + status 状态控制）
+│   │   ├── conversation_service.py  # 对话管理（session_id 双轨）
+│   │   ├── schemas.py           # AI 相关 Schema（SSEEvent 等）
+│   │   ├── apps/                # 8 个 AI 应用（app1_chat ~ app8_consolidation）
+│   │   ├── prompts/             # Prompt 模板（app2/app8 独立模板）
+│   │   └── data_fetchers/       # 共享数据获取层（NS2 新增）
+│   │       ├── member_data.py   # 客户消费/会员卡/备注数据
+│   │       ├── assistant_data.py # 助教信息/服务记录
+│   │       └── page_context.py  # 页面上下文文本化（10 种入口）
 │   └── ws/                  # WebSocket（实时日志）
 ├── tests/                   # 后端测试
 ├── pyproject.toml           # 依赖声明
@@ -71,6 +89,7 @@ ETL 只读连接自动设置 `default_transaction_read_only = on` 和 RLS `app.c

 1. 管理后台认证（`/api/auth/*`）：用户名 + 密码 → JWT
 2. 小程序认证（`/api/xcx-auth/*`）：微信 code → openid → JWT
+3. 租户管理后台认证（`/api/tenant/auth/*`）：用户名 + 密码 → JWT（`aud=tenant-admin`，与小程序完全隔离）

 JWT 令牌分两种：
 - 完整令牌：已审批用户，包含 `user_id` + `site_id` + `roles`
@@ -128,7 +147,20 @@ JWT 令牌分两种：
 | `/api/xcx-test` | `xcx_test.py` | MVP 全链路验证 | 无 |
 | `/api/wx-callback` | `wx_callback.py` | 微信消息推送回调 | 签名验证 |
 | `/api/retention-clue` | `member_retention_clue.py` | 维客线索 CRUD | JWT |
+| `/api/tenant/auth` | `tenant_auth.py` | 租户管理员登录/刷新令牌 | 无 |
+| `/api/tenant` | `tenant_users.py` | 租户用户审核/管理（申请列表/关联建议/审核/用户编辑/绑定） | 租户JWT |
+| `/api/tenant/excel` | `tenant_excel.py` | 租户 Excel 上传/校验/冲突/确认/记录/模板下载 | 租户JWT |
+| `/api/tenant` | `tenant_clues.py` | 租户维客线索管理（客户搜索/线索CRUD/隐藏显示） | 租户JWT |
+| `/api/tenant/site-admins` | `tenant_site_admins.py` | 店铺管理员 CRUD（列表/创建/编辑/删除/重置密码，仅 tenant_admin） | 租户JWT |
+| `/api/admin` | `admin_tenant_admins.py` | 管理端租户管理员 CRUD（列表/创建/编辑/删除/重置密码） | JWT+管理员 |
+| `/api/admin` | `admin_registry.py` | 注册体系管理（租户列表/店铺列表/简写ID/店铺同步） | JWT+管理员 |
+| `/api/admin/ai` | `admin_ai.py` | AI 监控后台（Dashboard/调度状态/调用明细/缓存/预算/批量/告警，13 端点） | JWT+管理员 |
+| `/api/admin/dev-trace` | `admin_dev_trace.py` | 开发调试全链路日志（日期/请求列表/详情/清理/设置/覆盖率，8 端点） | JWT+管理员 |
+| `/api/admin/task-engine` | `admin_task_engine.py` | P18 任务引擎运营看板（转移日志分页+历史、待审核任务分页+重新分配+关闭、参数管理 CRUD，9 端点） | JWT+管理员 |
 | `/api/xcx/chat` | `xcx_chat.py` | 小程序 CHAT 对话/消息/发送/SSE 流式 | JWT |
+| `/api/admin/db-health` | `admin_db_health.py` | 数据库健康监控（4 库连接池/大小/慢查询） | JWT |
+| `/api/admin/triggers` | `admin_triggers.py` | 触发器统一视图（biz/ai/etl 三源聚合） | JWT |
+| `/api/trigger-jobs` | `trigger_jobs.py` | 触发器任务管理（列表/详情/PATCH 配置编辑） | JWT |
 | `/api/ops` | `ops_panel.py` | 运维面板（服务启停/Git/系统信息） | 无 |
 | `/ws/logs` | `ws/logs.py` | WebSocket 实时日志推送 | — |
 | `/health` | `main.py` | 健康检查 | 无 |
@@ -148,17 +180,57 @@ JWT 令牌分两种：
 | `task_queue.py` | 任务队列管理（入队/消费/重排） |
 | `task_registry.py` | ETL 任务/Flow/DWD 表静态注册表 |
 | `cli_builder.py` | ETL CLI 命令构建器 |
-| `task_generator.py` | 任务生成器（基于 WBI/NCI 指数） |
+| `task_generator.py` | 任务生成器（四级漏斗 + 保底 relationship_building，独立连接） |
 | `task_manager.py` | 任务管理（置顶/放弃/状态变更） |
 | `task_expiry.py` | 任务过期检查与处理 |
 | `task_manager.py` | 任务管理（CRUD + 列表扩展 + 详情） |
 | `performance_service.py` | 绩效概览 + 明细（ETL 直连查询） |
 | `note_service.py` | 备注服务（CRUD + 星星评分） |
-| `fdw_queries.py` | ETL 查询集中封装（直连 ETL 库 + 门店隔离 RLS） |
+| `fdw_queries.py` | ETL 查询集中封装（直连 ETL 库 + 门店隔离 RLS），含区域日粒度查询（`get_finance_overview_area`/`get_finance_revenue_area`）和缓存读写（`get_finance_board_cache`/`set_finance_board_cache`） |
 | `note_reclassifier.py` | 备注重分类（召回完成后回填） |
 | `recall_detector.py` | 召回完成检测（ETL 数据更新触发） |
 | `trigger_scheduler.py` | 触发器调度器（cron/interval/event） |
 | `chat_service.py` | CHAT 模块业务逻辑（对话管理/消息持久化/referenceCard） |
+| `ai/admin_service.py` | AI 监控后台聚合服务（Dashboard 统计/批量执行/告警管理） |
+| `ai/cleanup_service.py` | AI 数据清理服务（90 天保留 + 缓存上限 20000/App） |
+| `admin_task_engine.py` | P18 任务引擎运营看板路由（转移日志/待审核任务/参数管理，9 端点） |
+
+## AI 模块（NS2 Prompt 细化）
+
+8 个千问 AI 应用，通过百炼平台调用 Qwen3.5-Plus 模型。分三层架构：
+
+```
+应用层（apps/app1_chat ~ app8_consolidation）
+  ↓ 调用
+数据获取层（data_fetchers/）          ← NS2 新增
+  ↓ 查询
+基础设施层（database.py / cache_service.py / dashscope_client.py）
+```
+
+### 数据获取层（`app/ai/data_fetchers/`）
+
+NS2 新增的共享模块，封装 FDW 查询逻辑，供多个应用复用：
+
+| 函数 | 数据来源 | 消费方 |
+|------|---------|--------|
+| `fetch_member_consumption_data()` | ETL FDW 视图（结算/商品/会员卡/到店） | App3/6/7 |
+| `fetch_member_notes()` | `biz.notes` | App4/6 |
+| `fetch_assistant_info()` | ETL FDW 视图（助教维度/月度汇总） | App4/5 |
+| `fetch_service_history()` | ETL FDW 视图（服务日志/亲密度） | App4/5 |
+| `build_page_text()` | 多数据源（按 contextType 路由） | App1 |
+
+关键约束：
+- 金额口径使用 `items_sum`，禁止 `consume_money`
+- 所有 FDW 查询通过 `SET LOCAL app.current_site_id` 实现 RLS 隔离
+- 部分数据获取失败不阻断 Prompt 生成（错误降级）
+
+### 页面上下文（App1）
+
+App1 通用对话支持 10 种页面入口，通过 `contextType` 路由到对应的文本化函数：
+
+`task-detail` / `customer-detail` / `coach-detail` / `task-list` / `customer-service-records` / `board-finance` / `board-customer` / `board-coach` / `performance` / `my-profile`
+
+每种入口自动获取页面数据并格式化为结构化中文文本，注入 system prompt。

 ## 依赖