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>
This commit is contained in:
Neo
2026-04-06 00:03:48 +08:00
parent 70324d8542
commit 6f8f12314f
515 changed files with 76604 additions and 7456 deletions

View File

@@ -2,7 +2,7 @@
> 本文档记录项目中所有文档资产的位置、类型和内容概要,方便快速定位。
> 归档规则见末尾「文档归档规则」章节;程序输出路径规范见 `docs/deployment/EXPORT-PATHS.md`。
> 最后更新2026-03-20RNS1.4 CHAT 模块重建 + FDW→直连统一 + R3 筛选修复 审计收口
> 最后更新2026-03-28board-finance-dws-area-refactor 财务看板区域维度重构
---
@@ -33,9 +33,13 @@
| `BD_Manual_biz_tables.md` | biz Schema 核心业务表coach_tasks、coach_task_history、notes、trigger_jobs、AI 表等) |
| `BD_Manual_auth_biz_schemas.md` | auth + biz Schema 创建 |
| `BD_Manual_fdw_etl_setup.md` | FDW 跨库访问配置zqyy_app → etl_feiqiu |
| `BD_Manual_fdw_finance_area.md` | FDW 财务区域查询映射(后端直连 ETL 库访问 v_dws_finance_area_daily / v_dws_finance_board_cache |
| `BD_Manual_app_schema_rls_views.md` | app Schema RLS 视图 |
| `BD_Manual_ai_tables.md` | AI 相关表ai_chat_sessions、ai_chat_messages 等) |
| `BD_Manual_member_retention_clue.md` | 会员留存线索表 |
| `BD_Manual_tenant_admin_tables.md` | NS4 租户管理后台 6 张表tenant_admins、excel_upload_log、salary_adjustments、3 张 staging 表) |
| `BD_Manual_biz_registry_tables.md` | biz Schema 注册体系四张表connectors、tenants、sites、site_code_history |
| `BD_Manual_scheduled_tasks.md` | scheduled_tasks P16 新增字段min_run_interval_value、min_run_interval_unit、last_success_at |
| `README.md` | 数据库文档目录说明 |
子目录:
@@ -145,14 +149,17 @@ H5 静态原型页面,用于小程序 UI 设计参考。
| `etl-calibration/` | ETL 校准报告DWS BD 手册校准(2026-03-07)、DWS 代码校准(2026-03-07)、财务看板 DWS 审计(2026-03-07) |
| `h5-mp-conversion/` | H5 转小程序报告:财务看板审计(`board-finance-h5-mp-audit.md`)、H5 UI 提取(`h5-ui-extraction.md`) |
| `p4-task/` | P4 任务报告Spec 与实现差距分析、任务生命周期全景 |
| `tech-solution/` | 技术方案:百炼技术方案(`bailian-technical-solution.md`) |
| `tech-solution/` | 技术方案`_archived/bailian-technical-solution.md` ⚠️ 已归档,基于旧 OpenAI 兼容方案P14 迁移后由 DashScope Application API 替代) |
| `vi-color-audit/` | VI 配色审计:详细审计(Phase2)、完成报告、实施文档、合规审计 |
| `2026-03-20__ai_app_page_mapping.md` | AI 应用→页面消费映射报告8 个 AI 应用的触发方式、数据流向、页面展示位置汇总 |
| `_archived/2026-03-21__ai_full_chain_test.md` | ⚠️ 已归档2026-03-21— AI 全链路测试报告,基于旧 openai SDKP14 迁移后由新测试替代 |
### 2.11 架构文档 `docs/architecture/`
| 文件 | 内容 |
|------|------|
| `etl-feiqiu-architecture.md` | ETL Connector 整体架构说明数据流、DWS/INDEX 任务、调度编排、CLI |
| `backend-architecture.md` | 后端 FastAPI 服务层架构(路由/服务/FDW/Trace 模块清单、数据流、设计决策) |
### 2.12 MCP 文档 `docs/mcp/`
@@ -182,8 +189,8 @@ H5 静态原型页面,用于小程序 UI 设计参考。
| 文件 | 内容 |
|------|------|
| `README.md` | 架构概览、双库连接、认证系统、17 个路由模块摘要、服务层、配置加载、触发器系统 |
| `docs/API-REFERENCE.md` | 完整 API 参考:17 个路由模块的所有端点、请求/响应示例、认证要求、错误码 |
| `README.md` | 架构概览、双库连接、认证系统、路由模块摘要(含 admin_ai 13 端点、admin_dev_trace 8 端点)、服务层(含 admin_service/cleanup_service、配置加载、触发器系统 |
| `docs/API-REFERENCE.md` | 完整 API 参考:26 个路由模块的所有端点、请求/响应示例、认证要求、错误码(含 P15 admin AI 13 端点、DevTrace 8 端点) |
RNS1.2 新增模块(客户与助教接口):
@@ -231,6 +238,161 @@ Monorepo 级属性测试(`tests/`
| `tests/test_rns1_chat_sse_properties.py` | RNS1.4 属性测试SSE 事件类型有效性Property 9 |
| `tests/test_rns1_chat_ordering_properties.py` | RNS1.4 属性测试列表排序不变量Property 3 |
NS2 新增模块AI Prompt 细化):
| 路径 | 内容 |
|------|------|
| `app/ai/data_fetchers/member_data.py` | 客户消费数据获取(消费记录、会员卡、备注) |
| `app/ai/data_fetchers/assistant_data.py` | 助教信息与服务记录获取 |
| `app/ai/data_fetchers/page_context.py` | 页面上下文文本化10 种入口 contextType |
| `app/ai/apps/app3_clue.py` | 应用 3 Prompt 拼接(客户数据维客线索分析) |
| `app/ai/apps/app4_analysis.py` | 应用 4 Prompt 拼接(关系分析/任务建议) |
| `app/ai/apps/app5_tactics.py` | 应用 5 Prompt 拼接(话术参考) |
| `app/ai/apps/app6_note.py` | 应用 6 Prompt 拼接(备注分析) |
| `app/ai/apps/app7_customer.py` | 应用 7 Prompt 拼接(客户分析) |
| `app/ai/apps/app1_chat.py` | 应用 1 页面上下文集成async `_build_page_context` |
Monorepo 级属性测试NS2
| 路径 | 内容 |
|------|------|
| `tests/test_data_fetchers/test_member_data_props.py` | 客户数据获取属性测试P1-P4, P6, P17 |
| `tests/test_data_fetchers/test_assistant_data_props.py` | 助教数据获取属性测试P5 |
| `tests/test_data_fetchers/test_page_context_props.py` | 页面上下文属性测试P10-P12 |
| `tests/test_data_fetchers/test_data_fetchers_unit.py` | 数据获取层单元测试 |
| `tests/test_ai_apps/test_build_prompt_props.py` | Prompt 拼接属性测试P7-P9, P14-P17 |
| `tests/test_ai_apps/test_app1_props.py` | 应用 1 属性测试P13, P16 |
| `tests/test_ai_apps/test_ai_apps_unit.py` | 应用层单元测试 |
P14 新增模块AI DashScope 迁移):
| 路径 | 内容 |
|------|------|
| `tests/test_ai_config_props.py` | AIConfig 属性测试Property 2环境变量校验完整性 |
| `tests/test_dashscope_client_props.py` | DashScopeClient 属性测试Property 1重试策略、Property 20响应解析 |
| `tests/test_circuit_breaker_props.py` | 熔断器属性测试Property 5app_id 隔离、Property 6状态机转换 |
| `tests/test_circuit_breaker_unit.py` | 熔断器单元测试 |
| `tests/test_rate_limiter_props.py` | 限流器属性测试Property 7窗口控制 |
| `tests/test_budget_tracker_props.py` | Token 预算属性测试Property 8预算检查正确性 |
| `tests/test_budget_tracker_unit.py` | Token 预算单元测试 |
| `tests/test_run_log_props.py` | 运行日志属性测试Property 18状态机、Property 19Prompt 截断) |
| `tests/test_dispatcher_props.py` | 调度器属性测试Property 9事件链映射、Property 10容错、Property 12去重 |
| `tests/test_dispatcher_unit.py` | 调度器单元测试 |
| `tests/test_internal_ai_api.py` | 内部 AI API 属性测试Property 11认证 |
| `tests/test_sse_props.py` | SSE 事件流属性测试Property 17事件格式 |
| `tests/test_session_props.py` | session_id 属性测试Property 3格式、Property 4对话复用 |
| `tests/test_cache_service_props.py` | 缓存服务属性测试Property 14-16过期策略、查询过滤、保留上限 |
| `tests/test_app8_idempotent.py` | App8 幂等写入属性测试Property 13 |
P15 新增模块AI 监控后台):
| 路径 | 内容 |
|------|------|
| `app/routers/admin_ai.py` | AI 监控后台路由13 个端点Dashboard/调度/调用/缓存/预算/批量/告警) |
| `app/services/ai/admin_service.py` | AI 监控后台聚合服务AdminAIService |
| `app/services/ai/cleanup_service.py` | AI 数据清理服务AICleanupService每日 03:00 |
| `app/schemas/admin_ai.py` | AI 监控后台 Pydantic Schema |
| `tests/unit/test_admin_ai_router.py` | admin AI 路由单元测试16 个测试) |
| `tests/unit/test_admin_ai_service.py` | AdminAIService 单元测试9 个测试) |
| `tests/unit/test_ai_cleanup_service.py` | 清理服务单元测试7 个测试) |
| `tests/unit/test_backfill_script.py` | 回填脚本单元测试13 个测试) |
| `tests/integration/test_ai_full_chain.py` | AI 全链路测试15 个场景Mock/Real 双轨) |
Monorepo 级属性测试P15
| 路径 | 内容 |
|------|------|
| `tests/test_admin_ai_dashboard_props.py` | Property 8Dashboard 聚合正确性 |
| `tests/test_admin_ai_alert_props.py` | Property 9告警筛选与状态转换 |
| `tests/test_admin_ai_cache_props.py` | Property 10缓存失效精确性 |
| `tests/test_admin_ai_batch_props.py` | Property 11批量执行预估公式 |
| `tests/test_admin_ai_pagination_props.py` | Property 12分页与筛选正确性 |
| `tests/test_backfill_props.py` | Property 13回填断点续跑 round-trip |
| `tests/test_ai_cleanup_props.py` | Property 14数据保留不变量 |
DevTrace 全链路日志模块:
| 路径 | 内容 |
|------|------|
| `app/trace/config.py` | TraceConfig 配置类(环境变量读取 + 运行时动态修改) |
| `app/trace/context.py` | TraceContext + TraceSpan 数据模型contextvars 请求级隔离23 种 span_type |
| `app/trace/writer.py` | JSON Lines 日志写入器按日期分目录、按小时分文件、10MB 自动轮转) |
| `app/trace/cleanup.py` | 日志自动清理(按保留天数删除过期目录) |
| `app/trace/middleware.py` | TraceMiddleware ASGI 中间件(拦截 xcx_* 路由) |
| `app/trace/decorators.py` | @trace_service 装饰器Service 层追踪) |
| `app/trace/db_wrapper.py` | 数据库连接生命周期追踪DB_QUERY/DB_CONN/DB_CONN_RELEASE/DB_ERROR |
| `app/trace/error_handler.py` | 异常/错误全链路追踪ERROR span |
| `app/trace/sse_wrapper.py` | SSE 流式响应追踪SSE_START/SSE_EVENT/SSE_END/AI_CALL |
| `app/trace/ws_wrapper.py` | WebSocket 连接追踪WS_CONNECT/WS_MESSAGE/WS_DISCONNECT |
| `app/trace/job_wrapper.py` | 后台 Job 执行追踪JOB_START/JOB_END/JOB_ERROR |
| `app/trace/coverage.py` | 覆盖率扫描器(路由/Service/Job/SSE/WS 五维度) |
| `app/routers/admin_dev_trace.py` | DevTrace 管理 API8 端点:日期/请求列表/详情/清理/设置/覆盖率) |
Monorepo 级属性测试DevTrace
| 路径 | 内容 |
|------|------|
| `tests/test_trace_context_props.py` | Property 1Request ID 唯一性、Property 2Span 顺序保持 |
| `tests/test_trace_writer_props.py` | Property 3TraceSpan 结构完整性、Property 5JSON 序列化往返一致性、Property 6日志文件路径生成 |
| `tests/test_trace_cleanup_props.py` | Property 8清理保留期正确性 |
| `tests/test_trace_auth_props.py` | Property 4Token 前缀截断、Property 20鉴权失败原因分类 |
| `tests/test_trace_switch_props.py` | Property 13开关关闭时无 Trace 产出、Property 14功能开关控制 Span 内容 |
| `tests/test_trace_middleware_props.py` | Property 15路由前缀过滤 |
| `tests/test_trace_error_props.py` | Property 16异常时 Trace 完整性 |
| `tests/test_trace_sse_props.py` | Property 17SSE 流式 Trace 完整性 |
| `tests/test_trace_ws_props.py` | Property 18WebSocket Trace 生命周期 |
| `tests/test_trace_job_props.py` | Property 19后台 Job Trace 完整性 |
| `tests/test_trace_db_props.py` | Property 21数据库连接生命周期配对 |
admin-web-restructure 新增模块(管理后台重构):
| 路径 | 内容 |
|------|------|
| `app/routers/admin_db_health.py` | 数据库健康监控路由GET /api/admin/db-health4 库连接池/大小/慢查询) |
| `app/routers/admin_triggers.py` | 触发器统一视图路由GET /api/admin/triggers/unifiedbiz/ai/etl 三源聚合) |
| `app/utils/cron_validator.py` | cron 表达式校验工具函数5 字段格式验证) |
| `app/schemas/admin_db_health.py` | DbHealthItem Pydantic Schema |
| `app/schemas/admin_triggers.py` | UnifiedTriggerItem Pydantic Schema |
| `app/schemas/trigger_jobs.py` | UpdateTriggerConfigRequest Pydantic SchemaPATCH 配置编辑) |
| `tests/unit/test_cron_and_models.py` | cron 校验与 Pydantic 模型单元测试 |
| `tests/unit/test_admin_db_health.py` | DB 健康端点单元测试 |
| `tests/unit/test_admin_triggers.py` | 统一触发器端点单元测试 |
| `tests/unit/test_trigger_jobs_patch.py` | PATCH 触发器配置端点单元测试 |
Monorepo 级属性测试admin-web-restructure
| 路径 | 内容 |
|------|------|
| `tests/test_admin_web_db_health_props.py` | Property 1DB 健康 API 已连接数据库返回完整指标 |
| `tests/test_admin_web_unified_triggers_props.py` | Property 3触发器统一视图数据完整性与字段完整性 |
| `tests/test_admin_web_trigger_config_props.py` | Property 4/5触发器配置编辑不变量与更新正确性 |
| `tests/test_admin_web_cron_validator_props.py` | Property 6cron 表达式校验拒绝无效输入 |
board-finance-dws-area-refactor 新增模块(财务看板区域维度重构):
| 路径 | 内容 |
|------|------|
| `tests/test_area_mapping_props.py` | Property 1-2区域映射 round-trip + 未知区域返回 None |
| `tests/test_area_mapping_unit.py` | 区域映射边界条件单元测试 |
| `tests/test_finance_area_daily_props.py` | Property 3-7日粒度恒等式/非 all 零值/输出完整性/幂等性/settle_type 过滤 |
| `tests/test_finance_board_cache_props.py` | Property 8-9数据指纹确定性/当期不缓存 |
| `tests/test_board_service_props.py` | Property 10-14查询路由/区域过滤/revenue 项数/overview 覆盖/回归一致性 |
| `scripts/ops/backfill_finance_area_daily.py` | 历史数据回填脚本(日粒度 + 缓存重算) |
| `scripts/ops/validate_board_finance.py` | 144 组合全量验证脚本8 time_range × 9 area_code × 2 compare |
| 路径 | 内容 |
|------|------|
| `app/routers/tenant_auth.py` | 租户认证端点:登录、刷新令牌 |
| `app/routers/tenant_users.py` | 租户用户端点:申请列表、关联建议、审核通过/拒绝、用户列表/编辑/绑定 |
| `app/routers/tenant_excel.py` | 租户 Excel 端点:上传解析、确认写入、上传记录、模板下载 |
| `app/routers/tenant_clues.py` | 租户线索端点:客户搜索、线索列表/编辑/删除/隐藏显示 |
| `app/routers/admin_tenant_admins.py` | 管理端租户管理员 CRUD列表、创建、编辑、重置密码 |
| `app/auth/tenant_admins.py` | 租户管理员认证依赖注入(`require_tenant_admin``site_filter_clause``verify_site_access` |
| `app/schemas/tenant_users.py` | 租户用户相关 Pydantic Schema |
| `app/schemas/tenant_excel.py` | 租户 Excel 相关 Pydantic Schema |
| `app/schemas/tenant_clues.py` | 租户线索相关 Pydantic Schema |
| `app/schemas/admin_tenant_admins.py` | 管理端租户管理员 Pydantic Schema |
### 3.2 ETL Connector `apps/etl/connectors/feiqiu/`
| 路径 | 内容 |
@@ -257,15 +419,34 @@ Monorepo 级属性测试(`tests/`
| 文件 | 内容 |
|------|------|
| `README.md` | 8 个页面、组件体系含营业日提示、API 层、状态管理、开发指南 |
| `README.md` | 13 个页面(含 P15 AI 监控 4 页面、DevTrace 日志页面、组件体系、API 层(含 adminAI、devTrace、状态管理、开发指南 |
### 3.5 MCP Server `apps/mcp-server/`
### 3.5 租户管理后台 `apps/tenant-admin/`
NS4 租户管理后台,独立 React 应用面向租户管理员Tenant_Admin
| 路径 | 内容 |
|------|------|
| `src/pages/Login/` | 登录页(用户名+密码) |
| `src/pages/UserApproval/` | 用户审核(申请列表 + 关联建议 + 审核操作) |
| `src/pages/UserManagement/` | 用户管理(列表 + 编辑 + 绑定) |
| `src/pages/ExcelUpload/` | Excel 上传4 种模板 + 校验 + 冲突 diff + 确认写入) |
| `src/pages/RetentionClues/` | 维客线索管理(客户搜索 + 线索 CRUD + 隐藏/显示) |
| `src/components/SiteSelector/` | 门店筛选器组件 |
| `src/components/DiffTable/` | 冲突 diff 交互表格 |
| `src/components/ClueEditor/` | 线索编辑表单 |
| `src/services/api.ts` | API 调用封装JWT 自动附加/刷新) |
| `src/hooks/useAuth.ts` | 认证状态管理 |
后端路由:`tenant_auth.py``tenant_users.py``tenant_excel.py``tenant_clues.py`(均注册在 `/api/tenant/*`)。管理端租户管理员 CRUD 由 `admin_tenant_admins.py``/api/admin/*`提供admin-web 前端调用。
### 3.6 MCP Server `apps/mcp-server/`
| 文件 | 内容 |
|------|------|
| `README.md` | MCP Server 功能说明、工具列表、配置方式 |
### 3.6 共享包 `packages/shared/`
### 3.7 共享包 `packages/shared/`
| 文件 | 内容 |
|------|------|
@@ -279,7 +460,7 @@ Monorepo 级属性测试(`tests/`
|------|------|
| `README.md` | 数据库目录总览、四库架构说明 |
| `zqyy_app/README.md` | 业务库文档auth Schema 8 张表字段说明、迁移顺序、FDW 跨库访问 |
| `zqyy_app/migrations/` | 业务库迁移脚本(已合并入 DDL 基线,目录保留 .gitkeep |
| `zqyy_app/migrations/` | 业务库迁移脚本`2026-03-22__p14_ai_module.sql`P14ai_run_logs、ai_trigger_jobs 新表 + ai_conversations.session_id`2026-03-22__ns41_registry_tables.sql`NS4.1biz.connectors/tenants/sites/site_code_history 四张新表 + 种子数据迁移)、`2026-03-22__p16_min_run_interval.sql`P16scheduled_tasks 三字段)、`2026-03-23__p15_ai_monitoring.sql`P15ai_run_logs.alert_status + BRIN 索引 |
| `etl_feiqiu/README.md` | ETL 库文档:六层 Schema 说明、表清单 |
| `etl_feiqiu/migrations/` | ETL 库迁移脚本(已合并入 DDL 基线,目录保留 .gitkeep |
| `fdw/` | FDWForeign Data Wrapper跨库访问配置脚本4 个,运行时资产) |
@@ -397,7 +578,15 @@ Monorepo 级属性测试(`tests/`
| `rns1-customer-coach-api` | RNS1.2 客户与助教接口CUST-1 客户详情、CUST-2 客户服务记录、COACH-1 助教详情) |
| `rns1-board-apis` | RNS1.3 三看板接口BOARD-1 助教看板、BOARD-2 客户看板、BOARD-3 财务看板、CONFIG-1 技能类型) |
| `rns1-chat-integration` | RNS1.4 CHAT 对齐与联调收尾CHAT-1/2/3/4 路径迁移、对话复用、referenceCard、SSE 流式、FDW 验证、13 页面联调) |
| `tenant-admin-web` | NS4 租户管理后台(独立认证、用户审核/管理、Excel 数据上传、维客线索管理、管理端租户管理员 CRUD |
| `spi-spending-power-index` | SPI 消费力指数 |
| `ai-prompt-refinement` | NS2 AI Prompt 细化共享数据获取层、6 个应用 Prompt 拼接、页面上下文文本化、17 个属性测试) |
| `P14-ai-dashscope-migration` | P14 AI 模块 DashScope 迁移openai→dashscope Application API、熔断/限流/预算防护、运行日志、事件触发链、ETL 集成、DB 迁移、20 个属性测试) |
| `admin-web-enhancement` | NS4.1 + P16 管理后台增强(注册体系 + 租户管理员重构 + 调度任务间隔) |
| `ai-monitoring-testing` | P15 AI 监控后台 + 测试重建 + 回填admin-web 4 页面、13 API 端点、15 全链路测试、14 属性测试、数据清理、回填脚本) |
| `dev-trace-log` | 开发调试全链路日志系统Trace 基础设施 12 模块、8 API 端点、DevTrace 前端页面、22 属性测试,覆盖 HTTP/SSE/WS/Job/异常/DB/中间件) |
| `admin-web-restructure` | 管理后台重构优化18 页面→7 模块菜单重组、Dashboard 仪表盘、ETLTasks Tab 合并、TriggerManager 统一管理、3 新后端 API、8 属性测试、LogViewer 归档) |
| `board-finance-dws-area-refactor` | 财务看板 DWS 区域维度重构dws_finance_area_daily 原子层 + dws_finance_board_cache 缓存层 + 后端缓存优先查询 + 区域映射共享包 + 14 属性测试) |
---