From caf179a5da927e40f65842cfbdf3f025c5166ccc Mon Sep 17 00:00:00 2001 From: Neo Date: Mon, 4 May 2026 02:30:19 +0800 Subject: [PATCH] =?UTF-8?q?feat:=202026-04-15~05-02=20=E7=B4=AF=E7=A7=AF?= =?UTF-8?q?=E5=8F=98=E6=9B=B4=E5=9F=BA=E7=BA=BF=20=E2=80=94=20AI=20?= =?UTF-8?q?=E9=87=8D=E6=9E=84=20+=20Runtime=20Context=20+=20DWS=20?= =?UTF-8?q?=E4=BF=AE=E5=A4=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 涵盖（每条对应已存的审计记录）： - AI 模块拆分：apps/backend/app/ai/apps -> prompts/（8 个 APP + app2a 派生） audit: 2026-04-20__ai-module-complete.md - admin-web AI 管理套件：AIDashboard / AIOperations / AIRunLogs / AITriggers / TriggerManager audit: 2026-04-21__admin-web-ai-management-suite.md - App2 财务洞察 prompt v3 -> v5.1 + 小程序 AI 接入（chat / board-finance） audit: 2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md - App2 prewarm 全过滤器 + AI 触发器 cron reschedule audit: 2026-04-21__app2-finance-prewarm-all-filters.md migration: 20260420_ai_trigger_jobs_and_app2_prewarm.sql / 20260421_app2_prewarm_cron_reschedule.sql - AppType 联合类型对齐 + adminAiAppTypes.test.ts audit: 2026-04-30__admin_web_ai_app_type_alignment.md - DashScope tokens_used 提取修复 audit: 2026-04-30__backend_dashscope_tokens_used_extraction.md - App3 线索完整详情 prompt audit: 2026-05-01__backend_app3_full_detail_prompt.md - Runtime Context 沙箱（5-1~5-2 主线）： - 后端 schema/service + admin_runtime_context / xcx_runtime_clock 两个 router - admin-web RuntimeContext.tsx + miniprogram runtime-clock.ts - migration: 20260501__runtime_context_sandbox.sql - tools/db/verify_admin_web_sandbox.py + verify_sandbox_end_to_end.py - database/changes: 7 份 sandbox_* 验证报告 - 飞球 DWS 修复：finance_area_daily 区域汇总 + task_engine 调整 + RLS 视图业务日上界（migration 20260502 + scripts/ops/gen_rls_business_date_migration.py） 合规： - .gitignore 启用 tmp/ 排除 - 不入仓：apps/etl/connectors/feiqiu/.env（API_TOKEN secret，本地修改保留） 待验证清单： - docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md 每个主题的功能完整性 / 上线验证几乎都未收口，按优先级 P0~P3 逐一处理 --- .gitignore | 2 +- apps/admin-web/src/App.tsx | 31 +- .../src/__tests__/adminAiAppTypes.test.ts | 43 + apps/admin-web/src/api/adminAI.ts | 31 +- apps/admin-web/src/api/runtimeContext.ts | 78 + apps/admin-web/src/pages/AIDashboard.tsx | 122 +- apps/admin-web/src/pages/AIOperations.tsx | 21 +- apps/admin-web/src/pages/AIRunLogs.tsx | 12 +- apps/admin-web/src/pages/AITriggers.tsx | 243 ++++ apps/admin-web/src/pages/RuntimeContext.tsx | 335 +++++ apps/admin-web/src/pages/TriggerManager.tsx | 4 +- apps/backend/app/ai/apps/__init__.py | 1 - apps/backend/app/ai/apps/app1_chat.py | 274 ---- apps/backend/app/ai/apps/app2_finance.py | 210 --- apps/backend/app/ai/apps/app3_clue.py | 263 ---- apps/backend/app/ai/apps/app4_analysis.py | 300 ---- apps/backend/app/ai/apps/app5_tactics.py | 288 ---- apps/backend/app/ai/apps/app6_note.py | 289 ---- apps/backend/app/ai/apps/app7_customer.py | 282 ---- .../backend/app/ai/apps/app8_consolidation.py | 211 --- apps/backend/app/ai/cache_service.py | 52 +- apps/backend/app/ai/dashscope_client.py | 81 +- .../app/ai/data_fetchers/assistant_data.py | 27 +- .../app/ai/data_fetchers/member_data.py | 39 +- .../app/ai/data_fetchers/page_context.py | 29 +- apps/backend/app/ai/dispatcher.py | 28 +- apps/backend/app/ai/event_bus.py | 123 ++ .../app/ai/prompts/app2_finance_prompt.py | 978 +++++++++++-- .../ai/prompts/app2a_finance_area_prompt.py | 7 +- .../app/ai/prompts/app3_clue_prompt.py | 131 ++ .../app/ai/prompts/app4_analysis_prompt.py | 177 +++ .../app/ai/prompts/app5_tactics_prompt.py | 170 +++ .../app/ai/prompts/app6_note_prompt.py | 160 +++ .../app/ai/prompts/app7_customer_prompt.py | 165 +++ .../ai/prompts/app8_consolidation_prompt.py | 85 +- apps/backend/app/ai/references.py | 137 ++ apps/backend/app/ai/run_log_service.py | 19 +- apps/backend/app/main.py | 36 +- .../app/routers/admin_runtime_context.py | 309 ++++ apps/backend/app/routers/admin_task_engine.py | 18 + apps/backend/app/routers/internal_events.py | 27 + apps/backend/app/routers/tenant_users.py | 10 +- apps/backend/app/routers/xcx_chat.py | 37 +- apps/backend/app/routers/xcx_runtime_clock.py | 61 + apps/backend/app/schemas/admin_ai.py | 92 ++ apps/backend/app/schemas/runtime_context.py | 48 + apps/backend/app/services/ai/admin_service.py | 200 ++- apps/backend/app/services/board_service.py | 36 +- apps/backend/app/services/chat_service.py | 65 +- apps/backend/app/services/coach_service.py | 8 +- apps/backend/app/services/customer_service.py | 8 +- apps/backend/app/services/fdw_queries.py | 219 ++- apps/backend/app/services/note_service.py | 22 + apps/backend/app/services/recall_detector.py | 67 +- apps/backend/app/services/runtime_context.py | 263 ++++ apps/backend/app/services/task_expiry.py | 39 +- apps/backend/app/services/task_generator.py | 83 +- apps/backend/app/services/task_manager.py | 64 +- .../backend/app/services/trigger_scheduler.py | 39 +- apps/backend/app/ws/ai_events.py | 80 ++ apps/backend/pytest.ini | 1 + .../feiqiu/tasks/dws/finance_area_daily.py | 66 +- .../feiqiu/tasks/dws/task_engine.py | 5 +- .../ai-float-button/ai-float-button.ts | 36 +- .../pages/board-finance/board-finance.wxml | 107 +- .../pages/board-finance/board-finance.wxss | 353 ++++- .../miniprogram/pages/chat/chat.ts | 62 +- .../miniprogram/pages/chat/chat.wxml | 11 +- .../pages/customer-detail/customer-detail.ts | 20 +- .../customer-records/customer-records.ts | 11 +- .../customer-service-records.ts | 12 +- .../performance-records.ts | 37 +- .../pages/performance/performance.ts | 13 +- .../miniprogram/pages/task-list/task-list.ts | 12 +- apps/miniprogram/miniprogram/services/api.ts | 45 + .../miniprogram/utils/runtime-clock.ts | 83 ++ ...2__rls_views_business_date_upper_bound.sql | 1258 +++++++++++++++++ db/etl_feiqiu/schemas/app.sql | 50 +- ...60420_ai_trigger_jobs_and_app2_prewarm.sql | 89 ++ .../20260421_app2_prewarm_cron_reschedule.sql | 42 + .../20260501__runtime_context_sandbox.sql | 117 ++ db/zqyy_app/schemas/biz.sql | 80 +- docs/ai/ai_apps_feature_acceptance_spec.md | 1039 ++++++++++++++ docs/ai/ai_system_prompt_by_app.md | 317 +++++ .../ai/app2_finance_prompt_version_history.md | 42 + .../ai/app2_finance_system_prompt_20260422.md | 158 +++ ...nance_system_prompt_20260422_v4_concise.md | 58 + .../app2_finance_system_prompt_20260422_v5.md | 220 +++ ...pp2_finance_system_prompt_20260422_v5_1.md | 232 +++ docs/ai/app2_finance_system_prompt_v3.md | 227 +++ docs/audit/audit_dashboard.md | 17 +- .../changes/2026-04-20__ai-module-complete.md | 110 ++ ...26-04-21__admin-web-ai-management-suite.md | 120 ++ ...04-21__app2-finance-prewarm-all-filters.md | 75 + ...4-21__board-finance-ai-insights-verify.png | Bin 0 -> 4339 bytes ..._prompt_v5_1_and_miniprogram_ai_insight.md | 202 +++ ...-04-30__admin_web_ai_app_type_alignment.md | 109 ++ ...ackend_dashscope_tokens_used_extraction.md | 113 ++ ...-05-01__backend_app3_full_detail_prompt.md | 80 ++ ...umulative_baseline_pending_verification.md | 183 +++ .../BD_Manual_runtime_context_sandbox.md | 152 ++ .../BD_manual_ai_trigger_jobs_register.md | 116 ++ .../2026-05-01__runtime_context_sandbox.md | 293 ++++ ...-02__sandbox_admin_web_manual_checklist.md | 262 ++++ ...02__sandbox_admin_web_playwright_report.md | 231 +++ ...-05-02__sandbox_admin_web_verify_report.md | 72 + .../2026-05-02__sandbox_complete_refactor.md | 136 ++ .../2026-05-02__sandbox_e2e_verify_report.md | 78 + ...2026-05-02__sandbox_no_future_data_plan.md | 246 ++++ docs/database/ddl/etl_feiqiu__app.sql | 50 +- docs/database/ddl/etl_feiqiu__core.sql | 2 +- docs/database/ddl/etl_feiqiu__dwd.sql | 10 +- docs/database/ddl/etl_feiqiu__dws.sql | 8 +- docs/database/ddl/etl_feiqiu__meta.sql | 2 +- docs/database/ddl/etl_feiqiu__ods.sql | 2 +- docs/database/ddl/fdw.sql | 2 +- docs/database/ddl/zqyy_app__auth.sql | 2 +- docs/database/ddl/zqyy_app__biz.sql | 52 +- docs/database/ddl/zqyy_app__public.sql | 2 +- docs/deployment/LAUNCH-CHECKLIST.md | 1 + docs/deployment/SERVER-ACCESS.md | 121 ++ scripts/ab_test_app2_prompt.py | 223 +++ scripts/analyze_ab_content_quality.py | 336 +++++ scripts/analyze_store_manager_quality.py | 531 +++++++ scripts/dump_app2_prompt.py | 45 + scripts/gen_app2_v6_md.py | 31 + .../ops/gen_rls_business_date_migration.py | 180 +++ scripts/test_app2_new_system_prompt.py | 66 + tools/db/verify_admin_web_sandbox.py | 475 +++++++ tools/db/verify_sandbox_end_to_end.py | 442 ++++++ 130 files changed, 14543 insertions(+), 2717 deletions(-) create mode 100644 apps/admin-web/src/__tests__/adminAiAppTypes.test.ts create mode 100644 apps/admin-web/src/api/runtimeContext.ts create mode 100644 apps/admin-web/src/pages/AITriggers.tsx create mode 100644 apps/admin-web/src/pages/RuntimeContext.tsx delete mode 100644 apps/backend/app/ai/apps/__init__.py delete mode 100644 apps/backend/app/ai/apps/app1_chat.py delete mode 100644 apps/backend/app/ai/apps/app2_finance.py delete mode 100644 apps/backend/app/ai/apps/app3_clue.py delete mode 100644 apps/backend/app/ai/apps/app4_analysis.py delete mode 100644 apps/backend/app/ai/apps/app5_tactics.py delete mode 100644 apps/backend/app/ai/apps/app6_note.py delete mode 100644 apps/backend/app/ai/apps/app7_customer.py delete mode 100644 apps/backend/app/ai/apps/app8_consolidation.py create mode 100644 apps/backend/app/ai/event_bus.py create mode 100644 apps/backend/app/ai/prompts/app3_clue_prompt.py create mode 100644 apps/backend/app/ai/prompts/app4_analysis_prompt.py create mode 100644 apps/backend/app/ai/prompts/app5_tactics_prompt.py create mode 100644 apps/backend/app/ai/prompts/app6_note_prompt.py create mode 100644 apps/backend/app/ai/prompts/app7_customer_prompt.py create mode 100644 apps/backend/app/ai/references.py create mode 100644 apps/backend/app/routers/admin_runtime_context.py create mode 100644 apps/backend/app/routers/xcx_runtime_clock.py create mode 100644 apps/backend/app/schemas/runtime_context.py create mode 100644 apps/backend/app/services/runtime_context.py create mode 100644 apps/backend/app/ws/ai_events.py create mode 100644 apps/miniprogram/miniprogram/utils/runtime-clock.ts create mode 100644 db/etl_feiqiu/migrations/20260502__rls_views_business_date_upper_bound.sql create mode 100644 db/zqyy_app/migrations/20260420_ai_trigger_jobs_and_app2_prewarm.sql create mode 100644 db/zqyy_app/migrations/20260421_app2_prewarm_cron_reschedule.sql create mode 100644 db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql create mode 100644 docs/ai/ai_apps_feature_acceptance_spec.md create mode 100644 docs/ai/ai_system_prompt_by_app.md create mode 100644 docs/ai/app2_finance_prompt_version_history.md create mode 100644 docs/ai/app2_finance_system_prompt_20260422.md create mode 100644 docs/ai/app2_finance_system_prompt_20260422_v4_concise.md create mode 100644 docs/ai/app2_finance_system_prompt_20260422_v5.md create mode 100644 docs/ai/app2_finance_system_prompt_20260422_v5_1.md create mode 100644 docs/ai/app2_finance_system_prompt_v3.md create mode 100644 docs/audit/changes/2026-04-20__ai-module-complete.md create mode 100644 docs/audit/changes/2026-04-21__admin-web-ai-management-suite.md create mode 100644 docs/audit/changes/2026-04-21__app2-finance-prewarm-all-filters.md create mode 100644 docs/audit/changes/2026-04-21__board-finance-ai-insights-verify.png create mode 100644 docs/audit/changes/2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md create mode 100644 docs/audit/changes/2026-04-30__admin_web_ai_app_type_alignment.md create mode 100644 docs/audit/changes/2026-04-30__backend_dashscope_tokens_used_extraction.md create mode 100644 docs/audit/changes/2026-05-01__backend_app3_full_detail_prompt.md create mode 100644 docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md create mode 100644 docs/database/BD_Manual_runtime_context_sandbox.md create mode 100644 docs/database/BD_manual_ai_trigger_jobs_register.md create mode 100644 docs/database/changes/2026-05-01__runtime_context_sandbox.md create mode 100644 docs/database/changes/2026-05-02__sandbox_admin_web_manual_checklist.md create mode 100644 docs/database/changes/2026-05-02__sandbox_admin_web_playwright_report.md create mode 100644 docs/database/changes/2026-05-02__sandbox_admin_web_verify_report.md create mode 100644 docs/database/changes/2026-05-02__sandbox_complete_refactor.md create mode 100644 docs/database/changes/2026-05-02__sandbox_e2e_verify_report.md create mode 100644 docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md create mode 100644 docs/deployment/SERVER-ACCESS.md create mode 100644 scripts/ab_test_app2_prompt.py create mode 100644 scripts/analyze_ab_content_quality.py create mode 100644 scripts/analyze_store_manager_quality.py create mode 100644 scripts/dump_app2_prompt.py create mode 100644 scripts/gen_app2_v6_md.py create mode 100644 scripts/ops/gen_rls_business_date_migration.py create mode 100644 scripts/test_app2_new_system_prompt.py create mode 100644 tools/db/verify_admin_web_sandbox.py create mode 100644 tools/db/verify_sandbox_end_to_end.py diff --git a/.gitignore b/.gitignore index 4b584db..be611b8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ # ===== 临时与缓存 ===== -# tmp/ +tmp/ __pycache__/ *.pyc *.py[cod] diff --git a/apps/admin-web/src/App.tsx b/apps/admin-web/src/App.tsx index 42edf68..f2195db 100644 --- a/apps/admin-web/src/App.tsx +++ b/apps/admin-web/src/App.tsx @@ -25,6 +25,7 @@ import { TeamOutlined, BugOutlined, ApartmentOutlined, + RobotOutlined, } from "@ant-design/icons"; import type { MenuProps } from "antd"; import { useAuthStore } from "./store/authStore"; @@ -36,6 +37,10 @@ import EnvConfig from "./pages/EnvConfig"; import DBViewer from "./pages/DBViewer"; import TenantAdmins from "./pages/TenantAdmins"; import AIRunLogs from "./pages/AIRunLogs"; +import AIDashboard from "./pages/AIDashboard"; +import AIOperations from "./pages/AIOperations"; +import AITriggerJobs from "./pages/AITriggerJobs"; +import AIPrewarm from "./pages/AIPrewarm"; import DevTrace from "./pages/DevTrace"; import TriggerJobs from "./pages/TriggerJobs"; import TransferLog from "./pages/TransferLog"; @@ -44,6 +49,7 @@ import TaskEngineConfig from "./pages/TaskEngineConfig"; import Dashboard from "./pages/Dashboard"; import ETLTasks from "./pages/ETLTasks"; import TriggerManager from "./pages/TriggerManager"; +import RuntimeContextPage from "./pages/RuntimeContext"; const { Sider, Content, Footer } = Layout; const { Text } = Typography; @@ -65,11 +71,22 @@ export const NAV_ITEMS: MenuProps["items"] = [ ], }, { key: "/triggers", icon: , label: "触发器管理" }, + { + key: "ai-group", icon: , label: "AI 管理", + children: [ + { key: "/ai/dashboard", label: "总览" }, + { key: "/ai/operations", label: "手动操作" }, + { key: "/ai/prewarm", label: "预热进度" }, + { key: "/triggers?tab=ai", label: "触发器设置" }, + { key: "/ai/trigger-jobs", label: "调度历史" }, + ], + }, { key: "/tenant-admins", icon: , label: "租户管理员" }, { key: "settings-group", icon: , label: "系统设置", children: [ { key: "/settings/env-config", label: "环境配置" }, + { key: "/settings/runtime-context", label: "业务运行上下文 / 沙箱" }, { key: "/triggers?tab=biz", label: "触发器配置" }, ], }, @@ -90,12 +107,14 @@ export const NAV_ITEMS: MenuProps["items"] = [ /** 根据当前路径计算 selectedKeys */ export function getSelectedKeys(pathname: string, search: string): string[] { const fullPath = pathname + search; - // 精确匹配含查询参数的菜单项（如 /triggers?tab=biz） + // 精确匹配含查询参数的菜单项（如 /triggers?tab=biz / ?tab=ai） if (fullPath === "/triggers?tab=biz") return ["/triggers?tab=biz"]; + if (fullPath === "/triggers?tab=ai") return ["/triggers?tab=ai"]; // 子路由匹配 if (pathname.startsWith("/task-engine/")) return [pathname]; if (pathname.startsWith("/settings/")) return [pathname]; if (pathname.startsWith("/logs/")) return [pathname]; + if (pathname.startsWith("/ai/")) return [pathname]; // 一级路由直接匹配 return [pathname]; } @@ -106,6 +125,9 @@ export function getDefaultOpenKeys(pathname: string): string[] { if (pathname.startsWith("/task-engine/")) keys.push("task-engine-group"); if (pathname.startsWith("/settings/")) keys.push("settings-group"); if (pathname.startsWith("/logs/")) keys.push("logs-group"); + if (pathname.startsWith("/ai/")) keys.push("ai-group"); + // 从 AI 菜单跳过来的"触发器设置"（/triggers?tab=ai）也展开 ai-group + // 注：此函数参数只接收 pathname，无法判断 tab，交由路由侧 searchParams 处理默认展开 // 触发器配置跳转入口也需要展开系统设置 if (pathname === "/triggers") keys.push("settings-group"); return keys; @@ -225,6 +247,13 @@ const AppLayout: React.FC = () => { {/* 系统设置 */} } /> + } /> + + {/* AI 管理 */} + } /> + } /> + } /> + } /> {/* 日志调试 */} } /> diff --git a/apps/admin-web/src/__tests__/adminAiAppTypes.test.ts b/apps/admin-web/src/__tests__/adminAiAppTypes.test.ts new file mode 100644 index 0000000..d4210aa --- /dev/null +++ b/apps/admin-web/src/__tests__/adminAiAppTypes.test.ts @@ -0,0 +1,43 @@ +/** + * 回归测试：admin-web 手动执行 App 类型必须与后端 /api/admin/ai/run/{app_type} 对齐。 + * + * 缓存类型仍使用 `*_analysis` / `*_consolidated`，但手动执行和 run log + * 应使用 dispatcher 支持的 app_type，避免前端发出后端 400 的路径。 + */ + +import { describe, expect, it } from "vitest"; +import { RUN_APP_TYPES } from "../api/adminAI"; +import { CACHE_TYPE_OPTIONS, RUN_APP_TYPE_OPTIONS } from "../pages/AIOperations"; +import { RUN_LOG_APP_TYPE_OPTIONS } from "../pages/AIRunLogs"; + +describe("admin AI app_type 对齐", () => { + it("手动执行类型使用后端支持的 app_type，而不是缓存类型", () => { + const apiTypes = [...RUN_APP_TYPES]; + const runOptionValues = RUN_APP_TYPE_OPTIONS.map((item) => item.value); + + for (const appType of ["app6_note", "app7_customer", "app8_consolidation"]) { + expect(apiTypes).toContain(appType); + expect(runOptionValues).toContain(appType); + } + + for (const cacheType of ["app6_note_analysis", "app7_customer_analysis", "app8_clue_consolidated"]) { + expect(runOptionValues).not.toContain(cacheType); + } + }); + + it("缓存失效继续使用 cache_type，避免破坏已有缓存管理", () => { + const cacheOptionValues = CACHE_TYPE_OPTIONS.map((item) => item.value); + + expect(cacheOptionValues).toContain("app6_note_analysis"); + expect(cacheOptionValues).toContain("app7_customer_analysis"); + expect(cacheOptionValues).toContain("app8_clue_consolidated"); + }); + + it("调用记录筛选包含真实写入 ai_run_logs 的 app_type", () => { + const runLogOptionValues = RUN_LOG_APP_TYPE_OPTIONS.map((item) => item.value); + + expect(runLogOptionValues).toContain("app6_note"); + expect(runLogOptionValues).toContain("app7_customer"); + expect(runLogOptionValues).toContain("app8_consolidate"); + }); +}); diff --git a/apps/admin-web/src/api/adminAI.ts b/apps/admin-web/src/api/adminAI.ts index 1fb1e1b..22714a6 100644 --- a/apps/admin-web/src/api/adminAI.ts +++ b/apps/admin-web/src/api/adminAI.ts @@ -9,29 +9,30 @@ import { apiClient } from "./client"; // ---- 公共类型 ---- +export const RUN_APP_TYPES = [ + "app2_finance", + "app2a_finance_area", + "app3_clue", + "app4_analysis", + "app5_tactics", + "app6_note", + "app7_customer", + "app8_consolidation", +] as const; + /** - * AI APP 类型联合（与后端 `CacheTypeEnum` / `_SUPPORTED_APP_TYPES` 同步）。 + * 按需执行 App 类型联合（与后端 `/api/admin/ai/run/{app_type}` 同步）。 * - * - app1_chat · 小程序聊天（无缓存） * - app2_finance · 全域财务洞察（area = 'all'，8 组合） * - app2a_finance_area · 区域财务洞察（area != 'all'，64 组合，2026-04-23 新增） * - app3_clue · 客户线索分析 * - app4_analysis · 助教关系分析 * - app5_tactics · 话术参考 - * - app6_note_analysis · 备注分析 - * - app7_customer_analysis · 客户综合分析 - * - app8_clue_consolidated · 线索整合 + * - app6_note · 备注分析 + * - app7_customer · 客户综合分析 + * - app8_consolidation · 线索整合 */ -export type AppType = - | "app1_chat" - | "app2_finance" - | "app2a_finance_area" - | "app3_clue" - | "app4_analysis" - | "app5_tactics" - | "app6_note_analysis" - | "app7_customer_analysis" - | "app8_clue_consolidated"; +export type AppType = (typeof RUN_APP_TYPES)[number]; // ---- 类型定义 ---- diff --git a/apps/admin-web/src/api/runtimeContext.ts b/apps/admin-web/src/api/runtimeContext.ts new file mode 100644 index 0000000..491924b --- /dev/null +++ b/apps/admin-web/src/api/runtimeContext.ts @@ -0,0 +1,78 @@ +/** + * 业务运行上下文 / 沙箱配置 API。 + */ + +import { apiClient } from "./client"; + +export type RuntimeMode = "live" | "sandbox"; +export type AIMode = "live"; +export type RuntimeStepStatus = "success" | "skipped" | "warning" | "failed"; + +export interface RuntimeContext { + site_id: number; + mode: RuntimeMode; + business_day_start_hour: number; + business_date: string; + business_now: string; + sandbox_date: string | null; + sandbox_instance_id: string | null; + ai_mode: AIMode; + status: string; + is_sandbox: boolean; +} + +export interface RuntimeSiteItem { + site_id: number; + site_name: string | null; + site_code: string | null; + is_active: boolean; + mode: RuntimeMode | null; + sandbox_date: string | null; + sandbox_instance_id: string | null; + ai_mode: AIMode | null; + status: string | null; + updated_at: string | null; +} + +export interface RuntimeSwitchRequest { + site_id: number; + mode: RuntimeMode; + sandbox_date?: string | null; + reset_sandbox?: boolean; + reason?: string | null; +} + +export interface RuntimeTransitionStep { + key: string; + title: string; + status: RuntimeStepStatus; + detail: string; + count: number; +} + +export interface RuntimeSwitchResponse { + context: RuntimeContext; + steps: RuntimeTransitionStep[]; +} + +export async function fetchRuntimeSites(): Promise { + const { data } = await apiClient.get("/admin/runtime-context/sites"); + return data; +} + +export async function fetchRuntimeContext(siteId: number): Promise { + const { data } = await apiClient.get("/admin/runtime-context", { + params: { site_id: siteId }, + }); + return data; +} + +export async function switchRuntimeContext( + payload: RuntimeSwitchRequest, +): Promise { + const { data } = await apiClient.patch( + "/admin/runtime-context", + payload, + ); + return data; +} diff --git a/apps/admin-web/src/pages/AIDashboard.tsx b/apps/admin-web/src/pages/AIDashboard.tsx index 2799ace..57d7d0e 100644 --- a/apps/admin-web/src/pages/AIDashboard.tsx +++ b/apps/admin-web/src/pages/AIDashboard.tsx @@ -8,12 +8,27 @@ * - 第四行：告警列表 */ -import React, { useEffect, useState, useCallback } from "react"; +import React, { useEffect, useRef, useState, useCallback } from "react"; import { Card, Row, Col, Statistic, Table, Tag, Badge, Progress, - Select, Button, message, Typography, Space, + Select, Button, message, Typography, Space, DatePicker, } from "antd"; -import { ReloadOutlined } from "@ant-design/icons"; +import { ReloadOutlined, WifiOutlined } from "@ant-design/icons"; +import type { Dayjs } from "dayjs"; + +const { RangePicker } = DatePicker; + +const RANGE_OPTIONS = [ + { label: "今日", value: 1 }, + { label: "近 3 天", value: 3 }, + { label: "近 7 天", value: 7 }, + { label: "近 10 天", value: 10 }, + { label: "指定日期", value: 0 }, // 0 = 启用 RangePicker +]; + +const RANGE_LABEL: Record = { + 1: "今日", 3: "近 3 天", 7: "近 7 天", 10: "近 10 天", +}; import type { ColumnsType } from "antd/es/table"; import { getDashboard, @@ -85,51 +100,119 @@ const AIDashboard: React.FC = () => { const [data, setData] = useState(null); const [loading, setLoading] = useState(false); const [siteId, setSiteId] = useState(undefined); + const [rangeDays, setRangeDays] = useState(1); // 0=自定义日期 / 1/3/7/10 + const [customRange, setCustomRange] = useState<[Dayjs, Dayjs] | null>(null); + const [wsStatus, setWsStatus] = useState<"connecting" | "connected" | "disconnected">("disconnected"); + const [realtimeAlerts, setRealtimeAlerts] = useState([]); + const wsRef = useRef(null); const load = useCallback(async () => { setLoading(true); try { - const res = await getDashboard(siteId); + const query: { site_id?: number; range_days?: number; date_from?: string; date_to?: string } = {}; + if (siteId != null) query.site_id = siteId; + if (rangeDays === 0 && customRange) { + query.date_from = customRange[0].format("YYYY-MM-DD"); + query.date_to = customRange[1].format("YYYY-MM-DD"); + } else if (rangeDays > 0) { + query.range_days = rangeDays; + } + const res = await getDashboard(query); setData(res); } catch { message.error("加载 Dashboard 失败"); } finally { setLoading(false); } - }, [siteId]); + }, [siteId, rangeDays, customRange]); useEffect(() => { load(); }, [load]); + const statLabel = rangeDays === 0 + ? (customRange ? `${customRange[0].format("MM-DD")} ~ ${customRange[1].format("MM-DD")}` : "指定日期") + : (RANGE_LABEL[rangeDays] || "今日"); + + // WebSocket 实时告警订阅 + useEffect(() => { + const wsKey = siteId ?? -1; + const proto = window.location.protocol === "https:" ? "wss" : "ws"; + const url = `${proto}://${window.location.host}/ws/ai-alerts/${wsKey}`; + setWsStatus("connecting"); + + const ws = new WebSocket(url); + wsRef.current = ws; + + ws.onopen = () => setWsStatus("connected"); + ws.onclose = () => setWsStatus("disconnected"); + ws.onerror = () => setWsStatus("disconnected"); + ws.onmessage = (evt) => { + try { + const msg = JSON.parse(evt.data as string) as { + type: string; + payload: AlertItem; + }; + if (msg.type === "alert_created" && msg.payload) { + setRealtimeAlerts((prev) => [msg.payload, ...prev].slice(0, 20)); + message.warning(`[实时] ${msg.payload.app_type} ${msg.payload.status}`); + } + } catch { + // 忽略非 JSON 消息 + } + }; + + return () => { + ws.close(); + wsRef.current = null; + setWsStatus("disconnected"); + }; + }, [siteId]); + return (
{/* 顶部：门店筛选 + 刷新 */} - + AI 运行总览 + {rangeDays === 0 && ( + setCustomRange(v as [Dayjs, Dayjs] | null)} + /> + )} + + + 实时 {wsStatus === "connected" ? "已连接" : wsStatus === "connecting" ? "连接中" : "断开"}} + /> + - {/* 第一行：4 个统计卡片 */} - + - + @@ -201,11 +284,22 @@ const AIDashboard: React.FC = () => { - {/* 第四行：告警列表 */} - + {/* 第四行：告警列表（实时 + 历史合并） */} + 0 && ( + {realtimeAlerts.length} 条实时 + )} + > columns={alertColumns} - dataSource={data?.recent_alerts ?? []} + dataSource={[ + ...realtimeAlerts, + ...(data?.recent_alerts ?? []).filter( + (a) => !realtimeAlerts.some((r) => r.id === a.id) + ), + ]} rowKey="id" size="small" pagination={{ pageSize: 10 }} loading={loading} /> diff --git a/apps/admin-web/src/pages/AIOperations.tsx b/apps/admin-web/src/pages/AIOperations.tsx index ebae7e4..a196be9 100644 --- a/apps/admin-web/src/pages/AIOperations.tsx +++ b/apps/admin-web/src/pages/AIOperations.tsx @@ -31,7 +31,7 @@ const EVENT_TYPE_OPTIONS = [ const { TextArea } = Input; const { Title } = Typography; -const APP_TYPE_OPTIONS = [ +export const CACHE_TYPE_OPTIONS = [ { label: "App3 维客线索", value: "app3_clue" }, { label: "App4 关系分析", value: "app4_analysis" }, { label: "App5 话术参考", value: "app5_tactics" }, @@ -40,6 +40,15 @@ const APP_TYPE_OPTIONS = [ { label: "App8 线索整理", value: "app8_clue_consolidated" }, ]; +export const RUN_APP_TYPE_OPTIONS: { label: string; value: AppType }[] = [ + { label: "App3 维客线索", value: "app3_clue" }, + { label: "App4 关系分析", value: "app4_analysis" }, + { label: "App5 话术参考", value: "app5_tactics" }, + { label: "App6 备注分析", value: "app6_note" }, + { label: "App7 客户分析", value: "app7_customer" }, + { label: "App8 线索整理", value: "app8_consolidation" }, +]; + const ALERT_STATUS_COLOR: Record = { failed: "red", timeout: "orange", circuit_open: "volcano", }; @@ -160,7 +169,7 @@ const AIOperations: React.FC = () => { }; // ---- Card 3: 批量执行 ---- - const [batchAppTypes, setBatchAppTypes] = useState([]); + const [batchAppTypes, setBatchAppTypes] = useState([]); const [batchMemberIds, setBatchMemberIds] = useState(""); const [batchSiteId, setBatchSiteId] = useState(2790685415443269); const [batchLoading, setBatchLoading] = useState(false); @@ -294,7 +303,7 @@ const AIOperations: React.FC = () => { { setEditCron(e.target.value)} + placeholder="标准 5 段 cron，例如 0 10 * * *" + /> + + 格式：分 时 日 月 周。示例：0 10 * * *（每日 10:00）、*/30 * * * *（每 30 分钟）。 + +
+ )} + +
+
描述
+ setEditDesc(e.target.value)} + rows={3} + /> +
+ + )} + + + ); +}; + +export default AITriggers; diff --git a/apps/admin-web/src/pages/RuntimeContext.tsx b/apps/admin-web/src/pages/RuntimeContext.tsx new file mode 100644 index 0000000..f12877a --- /dev/null +++ b/apps/admin-web/src/pages/RuntimeContext.tsx @@ -0,0 +1,335 @@ +/** + * 业务运行上下文 / 沙箱设置页面。 + * + * 仅限超级管理员：列出门店当前模式，支持切换到 sandbox 指定历史日期或切回 live。 + * 切换会按 site_id 暂停或恢复 biz.trigger_jobs，确保多门店隔离。 + */ + +import React, { useEffect, useMemo, useState, useCallback } from "react"; +import { + Alert, Button, Card, DatePicker, Form, Input, Modal, Popconfirm, Space, + Switch, Table, Tag, Tooltip, Typography, message, +} from "antd"; +import { ReloadOutlined, SwapOutlined } from "@ant-design/icons"; +import type { ColumnsType } from "antd/es/table"; +import dayjs, { type Dayjs } from "dayjs"; +import { + fetchRuntimeSites, switchRuntimeContext, + type RuntimeSiteItem, type RuntimeMode, type RuntimeTransitionStep, +} from "../api/runtimeContext"; +import { useAuthStore } from "../store/authStore"; + +const { Title, Text } = Typography; + +interface SwitchFormValues { + mode: RuntimeMode; + sandbox_date: Dayjs | null; + reset_sandbox: boolean; + reason: string; +} + +const stepStatusColor: Record = { + success: "green", + skipped: "default", + warning: "orange", + failed: "red", +}; + +const RuntimeContextPage: React.FC = () => { + const user = useAuthStore((s) => s.user); + const isSuperAdmin = user?.roles?.includes("super_admin") ?? false; + + const [sites, setSites] = useState([]); + const [loading, setLoading] = useState(false); + const [switchTarget, setSwitchTarget] = useState(null); + const [submitting, setSubmitting] = useState(false); + const [stepsModal, setStepsModal] = useState<{ siteName: string; steps: RuntimeTransitionStep[] } | null>(null); + const [form] = Form.useForm(); + + const load = useCallback(async () => { + setLoading(true); + try { + const data = await fetchRuntimeSites(); + setSites(data); + } catch { + message.error("加载门店运行上下文失败"); + } finally { + setLoading(false); + } + }, []); + + useEffect(() => { + if (isSuperAdmin) { + load(); + } + }, [isSuperAdmin, load]); + + const openSwitch = (record: RuntimeSiteItem, mode: RuntimeMode) => { + setSwitchTarget(record); + form.resetFields(); + form.setFieldsValue({ + mode, + sandbox_date: record.sandbox_date ? dayjs(record.sandbox_date) : null, + reset_sandbox: true, + reason: "", + }); + }; + + const handleSubmit = async () => { + if (!switchTarget) return; + let values: SwitchFormValues; + try { + values = await form.validateFields(); + } catch { + return; + } + setSubmitting(true); + try { + const resp = await switchRuntimeContext({ + site_id: switchTarget.site_id, + mode: values.mode, + sandbox_date: values.mode === "sandbox" ? values.sandbox_date?.format("YYYY-MM-DD") : null, + reset_sandbox: values.mode === "sandbox" ? values.reset_sandbox : true, + reason: values.reason || null, + }); + message.success(values.mode === "sandbox" ? "已切换为沙箱模式" : "已切回 live 模式"); + setStepsModal({ + siteName: switchTarget.site_name || `#${switchTarget.site_id}`, + steps: resp.steps, + }); + setSwitchTarget(null); + form.resetFields(); + load(); + } catch (err: unknown) { + const msg = (err as { response?: { data?: { detail?: string } } })?.response?.data?.detail; + message.error(msg || "切换失败"); + } finally { + setSubmitting(false); + } + }; + + const columns: ColumnsType = useMemo( + () => [ + { + title: "门店", + key: "site", + width: 200, + render: (_: unknown, r) => ( + + {r.site_name || `#${r.site_id}`} + + {r.site_code ? `${r.site_code} · ` : ""}site_id={r.site_id} + + + ), + }, + { + title: "运行模式", + key: "mode", + width: 140, + render: (_: unknown, r) => { + const mode = (r.mode ?? "live") as RuntimeMode; + return mode === "sandbox" ? ( + 沙箱模式 + ) : ( + 正式 live + ); + }, + }, + { + title: "业务日期", + key: "business_date", + width: 160, + render: (_: unknown, r) => + r.mode === "sandbox" && r.sandbox_date ? ( + + {r.sandbox_date} + + ) : ( + 真实日期 + ), + }, + { + title: "沙箱实例", + dataIndex: "sandbox_instance_id", + key: "sandbox_instance_id", + width: 240, + render: (v: string | null) => (v ? {v} : "—"), + }, + { + title: "AI 模式", + dataIndex: "ai_mode", + key: "ai_mode", + width: 100, + render: (v: string | null) => v ?? "live", + }, + { + title: "更新时间", + dataIndex: "updated_at", + key: "updated_at", + width: 170, + render: (v: string | null) => (v ? dayjs(v).format("YYYY-MM-DD HH:mm") : "—"), + }, + { + title: "操作", + key: "action", + fixed: "right", + width: 220, + render: (_: unknown, r) => { + const mode = (r.mode ?? "live") as RuntimeMode; + if (mode === "sandbox") { + return ( + + + openSwitch(r, "live")} + > + + + + ); + } + return ( + + ); + }, + }, + ], + [form], + ); + + if (!isSuperAdmin) { + return ( + + ); + } + + const target = switchTarget; + const targetMode = Form.useWatch("mode", form) ?? "live"; + + return ( + 业务运行上下文 / 沙箱} + extra={ + + } + > + + live 模式：使用真实系统日期，正常生产逻辑。 + + sandbox 模式：业务上假设是 sandbox_date，按 sandbox_instance_id 隔离写入； + 切换会终止当前 ETL、取消未完成 AI 触发记录，但不会暂停全局 biz.trigger_jobs（多门店共用）。 + + + 真实预算、AI tokens 计费、运行日志写入时间、调度元数据仍按真实系统时间，不受沙箱影响。 + + + 本次改造目标是让看板 / 任务 / 会员 / AI 等数据读取也按 sandbox_date 截断， + 进度详见 docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md。 + + + } + /> + + { + if (!submitting) { + setSwitchTarget(null); + form.resetFields(); + } + }} + onOk={handleSubmit} + okText="确认切换" + cancelText="取消" + confirmLoading={submitting} + destroyOnClose + width={640} + > +
+ + + + {targetMode === "sandbox" && ( + <> + + d && d.isAfter(dayjs(), "day")} + /> + + + + + + )} + + + + + + setStepsModal(null)} + onOk={() => setStepsModal(null)} + okText="知道了" + cancelButtonProps={{ style: { display: "none" } }} + width={640} + destroyOnClose + > + + {(stepsModal?.steps ?? []).map((s) => ( +
+ {s.title} + {s.count ? 影响 {s.count} 条 : null} + {s.detail} +
+ ))} + + + + ); +}; + +export default RuntimeContextPage; diff --git a/apps/admin-web/src/pages/TriggerManager.tsx b/apps/admin-web/src/pages/TriggerManager.tsx index 43761ba..d26835f 100644 --- a/apps/admin-web/src/pages/TriggerManager.tsx +++ b/apps/admin-web/src/pages/TriggerManager.tsx @@ -6,7 +6,7 @@ * - destroyInactiveTabPane={false} 保持 Tab 状态不丢失 * - "全部"Tab 调用 fetchUnifiedTriggers()，展示统一字段表格 * - "业务"Tab 复用 TriggerJobs 组件 + 编辑 Modal - * - "AI"Tab 复用 AIOperations + AITriggerJobs 组件 + * - "AI"Tab 复用 AITriggers（触发器设置）+ AIOperations + AITriggerJobs 组件 * - "ETL"Tab 展示 scheduled_tasks 数据 * * CHANGE 2026-07-15 | Task 10.1：创建 TriggerManager 页面 @@ -37,6 +37,7 @@ import { fetchSchedules } from '../api/schedules'; import type { ScheduledTask } from '../types'; import AIOperations from './AIOperations'; import AITriggerJobs from './AITriggerJobs'; +import AITriggers from './AITriggers'; const { Title } = Typography; @@ -319,6 +320,7 @@ const BizTriggersTab: React.FC = () => { const AITriggersTab: React.FC = () => ( + diff --git a/apps/backend/app/ai/apps/__init__.py b/apps/backend/app/ai/apps/__init__.py deleted file mode 100644 index f8316e7..0000000 --- a/apps/backend/app/ai/apps/__init__.py +++ /dev/null @@ -1 +0,0 @@ -# AI 应用子模块：app1_chat ~ app8_consolidation diff --git a/apps/backend/app/ai/apps/app1_chat.py b/apps/backend/app/ai/apps/app1_chat.py deleted file mode 100644 index 05f6774..0000000 --- a/apps/backend/app/ai/apps/app1_chat.py +++ /dev/null @@ -1,274 +0,0 @@ -"""应用 1：通用对话（SSE 流式）。 - -每次进入 chat 页面新建 ai_conversations 记录（不复用）， -首条消息注入页面上下文，流式返回 AI 回复。 - -app_id = "app1_chat" -""" - -from __future__ import annotations - -import json -import logging -from typing import AsyncGenerator - -from app.ai.dashscope_client import DashScopeClient -from app.ai.cache_service import AICacheService -from app.ai.conversation_service import ConversationService -from app.ai.data_fetchers import build_page_text -from app.ai.schemas import SSEEvent - -logger = logging.getLogger(__name__) - -APP_ID = "app1_chat" - -# system prompt 总字符数上限 -_MAX_SYSTEM_PROMPT_LEN = 4000 - - -async def chat_stream( - *, - message: str, - user_id: int | str, - nickname: str, - role: str, - site_id: int, - source_page: str | None = None, - page_context: dict | None = None, - screen_content: str | None = None, - client: DashScopeClient, - conv_svc: ConversationService, -) -> AsyncGenerator[SSEEvent, None]: - """流式对话入口，返回 SSEEvent 异步生成器。 - - 流程： - 1. 创建 conversation 记录 - 2. 写入 user message - 3. 构建 system prompt（注入页面上下文） - 4. 调用 bailian.chat_stream 流式获取回复 - 5. 逐 chunk yield SSEEvent(type="chunk") - 6. 完成后写入 assistant message，yield SSEEvent(type="done") - 7. 异常时 yield SSEEvent(type="error") - """ - conversation_id: int | None = None - - try: - # 1. 每次新建 conversation（不复用） - source_ctx = _build_source_context( - source_page=source_page, - page_context=page_context, - screen_content=screen_content, - ) - conversation_id = conv_svc.create_conversation( - user_id=user_id, - nickname=nickname, - app_id=APP_ID, - site_id=site_id, - source_page=source_page, - source_context=source_ctx, - ) - logger.info( - "App1 新建对话: conversation_id=%s user_id=%s site_id=%s", - conversation_id, user_id, site_id, - ) - - # 2. 立即写入 user message - conv_svc.add_message( - conversation_id=conversation_id, - role="user", - content=message, - ) - - # 3. 构建消息列表（system prompt + user message） - messages = await _build_messages( - message=message, - user_id=user_id, - nickname=nickname, - role=role, - site_id=site_id, - source_page=source_page, - page_context=page_context, - screen_content=screen_content, - ) - - # 4-5. 流式调用百炼，逐 chunk yield - full_reply_parts: list[str] = [] - async for chunk in bailian.chat_stream(messages): - full_reply_parts.append(chunk) - yield SSEEvent(type="chunk", content=chunk) - - # 6. 流式完成，拼接完整回复并写入 assistant message - full_reply = "".join(full_reply_parts) - # 百炼流式模式不返回 tokens_used，按字符数估算（粗略） - estimated_tokens = len(full_reply) - conv_svc.add_message( - conversation_id=conversation_id, - role="assistant", - content=full_reply, - tokens_used=estimated_tokens, - ) - - yield SSEEvent( - type="done", - conversation_id=conversation_id, - tokens_used=estimated_tokens, - ) - - except Exception as e: - logger.error( - "App1 对话异常: conversation_id=%s error=%s", - conversation_id, e, - exc_info=True, - ) - yield SSEEvent(type="error", message=str(e)) - - -async def _build_messages( - *, - message: str, - user_id: int | str, - nickname: str, - role: str, - site_id: int, - source_page: str | None, - page_context: dict | None, - screen_content: str | None, -) -> list[dict]: - """构建发送给百炼的消息列表。 - - 首条 system 消息注入页面上下文和用户信息。 - """ - system_content = await _build_system_prompt( - user_id=user_id, - nickname=nickname, - role=role, - site_id=site_id, - source_page=source_page, - page_context=page_context, - screen_content=screen_content, - ) - - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - # system prompt 总字符数控制 - if len(content_str) > _MAX_SYSTEM_PROMPT_LEN: - # 截断 page_context 中的 data_text - pc = system_content.get("page_context", {}) - dt = pc.get("data_text", "") - if dt and len(dt) > 500: - pc["data_text"] = dt[:500] + "…（已截断）" - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - - return [ - {"role": "system", "content": content_str}, - {"role": "user", "content": message}, - ] - - -async def _build_system_prompt( - *, - user_id: int | str, - nickname: str, - role: str, - site_id: int, - source_page: str | None, - page_context: dict | None, - screen_content: str | None, -) -> dict: - """构建 system prompt JSON。 - - 通过 biz_params.user_prompt_params 传入用户信息， - 注入页面上下文供 AI 理解当前场景。 - """ - prompt: dict = { - "task": ( - "你是台球门店的 AI 助手，根据用户的问题和当前页面上下文提供帮助。" - "当 page_context 中包含 memberNickname、contextId 或 data_text 时，" - "你必须直接使用这些信息回答问题，不要再向用户索要已有的信息。" - "例如用户在客户详情页提问时，直接基于该客户的数据回答，无需要求提供会员 ID。" - ), - "biz_params": { - "user_prompt_params": { - "User_ID": str(user_id), - "Role": role, - "Nickname": nickname, - }, - }, - } - - # 注入页面上下文（首条消息） - page_ctx = await _build_page_context( - source_page=source_page, - page_context=page_context, - screen_content=screen_content, - site_id=site_id, - ) - if page_ctx: - prompt["page_context"] = page_ctx - - return prompt - - -async def _build_page_context( - *, - source_page: str | None, - page_context: dict | None, - screen_content: str | None, - site_id: int, -) -> dict: - """构建页面上下文信息。 - - 根据 source_page（contextType）调用 build_page_text 获取结构化文本， - 看板类页面从 page_context 提取筛选参数传入 filters。 - contextType 为空或未识别时返回空 dict（跳过注入）。 - """ - ctx: dict = {} - - if source_page: - ctx["source_page"] = source_page - - # 从 page_context 提取 contextId 和筛选参数 - context_id = None - filters: dict = {} - if page_context: - context_id = page_context.get("contextId") - # 看板类页面筛选参数透传 - for key in ("timeDimension", "areaFilter", "dimension", "typeFilter", "projectFilter"): - if key in page_context: - filters[key] = page_context[key] - - # 调用 data_fetcher 获取页面数据文本 - try: - data_text = await build_page_text( - source_page=source_page, - context_id=context_id, - site_id=site_id, - filters=filters if filters else None, - ) - if data_text: - ctx["data_text"] = data_text - except Exception: - logger.warning("页面上下文文本化失败: source_page=%s", source_page, exc_info=True) - - if page_context: - ctx["page_context"] = page_context - if screen_content: - ctx["screen_content"] = screen_content - - return ctx - - -def _build_source_context( - *, - source_page: str | None, - page_context: dict | None, - screen_content: str | None, -) -> dict | None: - """构建存入 ai_conversations.source_context 的 JSON。""" - ctx: dict = {} - if source_page: - ctx["source_page"] = source_page - if page_context: - ctx["page_context"] = page_context - if screen_content: - ctx["screen_content"] = screen_content - return ctx if ctx else None diff --git a/apps/backend/app/ai/apps/app2_finance.py b/apps/backend/app/ai/apps/app2_finance.py deleted file mode 100644 index ff90c07..0000000 --- a/apps/backend/app/ai/apps/app2_finance.py +++ /dev/null @@ -1,210 +0,0 @@ -"""应用 2：财务洞察。 - -8 个时间维度独立调用，每次调用结果写入 ai_cache， -同时创建 ai_conversations + ai_messages 记录。 - -营业日分界点：每日 08:00（BUSINESS_DAY_START_HOUR 环境变量，默认 8）。 - -app_id = "app2_finance" -""" - -from __future__ import annotations - -import json -import logging -import os -from datetime import date, datetime, timedelta - -from app.ai.dashscope_client import DashScopeClient -from app.ai.cache_service import AICacheService -from app.ai.conversation_service import ConversationService -from app.ai.prompts.app2_finance_prompt import build_prompt -from app.ai.schemas import CacheTypeEnum - -logger = logging.getLogger(__name__) - -APP_ID = "app2_finance" - -# 8 个时间维度编码 -TIME_DIMENSIONS = ( - "this_month", - "last_month", - "this_week", - "last_week", - "last_3_months", - "this_quarter", - "last_quarter", - "last_6_months", -) - - -def get_business_date() -> date: - """根据营业日分界点计算当前营业日。 - - 分界点前（如 07:59）视为前一天营业日， - 分界点及之后（如 08:00）视为当天营业日。 - """ - hour = int(os.environ.get("BUSINESS_DAY_START_HOUR", "8")) - now = datetime.now() - if now.hour < hour: - return (now - timedelta(days=1)).date() - return now.date() - - -def compute_time_range(dimension: str, business_date: date) -> tuple[date, date]: - """计算时间维度对应的日期范围 [start, end]（闭区间）。 - - Args: - dimension: 时间维度编码 - business_date: 当前营业日 - - Returns: - (start_date, end_date) 元组 - """ - y, m, d = business_date.year, business_date.month, business_date.day - - if dimension == "this_month": - start = date(y, m, 1) - return start, business_date - - if dimension == "last_month": - prev = _month_offset(y, m, -1) - start = date(prev[0], prev[1], 1) - end = date(y, m, 1) - timedelta(days=1) - return start, end - - if dimension == "this_week": - # 周一起算 - weekday = business_date.weekday() # 0=周一 - start = business_date - timedelta(days=weekday) - return start, business_date - - if dimension == "last_week": - weekday = business_date.weekday() - this_monday = business_date - timedelta(days=weekday) - last_monday = this_monday - timedelta(days=7) - last_sunday = this_monday - timedelta(days=1) - return last_monday, last_sunday - - if dimension == "last_3_months": - # 当前月 - 3 ~ 当前月 - 1 - end_ym = _month_offset(y, m, -1) - start_ym = _month_offset(y, m, -3) - start = date(start_ym[0], start_ym[1], 1) - # end = 上月最后一天 - end = date(y, m, 1) - timedelta(days=1) - return start, end - - if dimension == "this_quarter": - q_start_month = ((m - 1) // 3) * 3 + 1 - start = date(y, q_start_month, 1) - return start, business_date - - if dimension == "last_quarter": - q_start_month = ((m - 1) // 3) * 3 + 1 - # 上季度结束 = 本季度第一天 - 1 - this_q_start = date(y, q_start_month, 1) - end = this_q_start - timedelta(days=1) - # 上季度开始 - ly, lm = end.year, end.month - lq_start_month = ((lm - 1) // 3) * 3 + 1 - start = date(ly, lq_start_month, 1) - return start, end - - if dimension == "last_6_months": - # 当前月 - 6 ~ 当前月 - 1 - end_ym = _month_offset(y, m, -1) - start_ym = _month_offset(y, m, -6) - start = date(start_ym[0], start_ym[1], 1) - end = date(y, m, 1) - timedelta(days=1) - return start, end - - raise ValueError(f"未知时间维度: {dimension}") - - -async def run( - context: dict, - client: DashScopeClient, - cache_svc: AICacheService, - conv_svc: ConversationService, -) -> dict: - """执行 App2 财务洞察调用。 - - Args: - context: 包含 site_id, time_dimension, user_id(默认'system'), nickname(默认'') - bailian: 百炼客户端 - cache_svc: 缓存服务 - conv_svc: 对话服务 - - Returns: - 百炼返回的结构化 JSON（insights 数组） - """ - site_id = context["site_id"] - time_dimension = context["time_dimension"] - user_id = context.get("user_id", "system") - nickname = context.get("nickname", "") - - # 构建 Prompt - prompt_context = { - "site_id": site_id, - "time_dimension": time_dimension, - "current_data": context.get("current_data", {}), - "previous_data": context.get("previous_data", {}), - } - messages = build_prompt(prompt_context) - - # 创建对话记录 - conversation_id = conv_svc.create_conversation( - user_id=user_id, - nickname=nickname, - app_id=APP_ID, - site_id=site_id, - source_context={"time_dimension": time_dimension}, - ) - - # 写入 system prompt 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="system", - content=messages[0]["content"], - ) - # 写入 user 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="user", - content=messages[1]["content"], - ) - - # 调用百炼 API - result, tokens_used = await bailian.chat_json(messages) - - # 写入 assistant 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="assistant", - content=json.dumps(result, ensure_ascii=False), - tokens_used=tokens_used, - ) - - # 写入缓存 - cache_svc.write_cache( - cache_type=CacheTypeEnum.APP2_FINANCE.value, - site_id=site_id, - target_id=time_dimension, - result_json=result, - triggered_by=f"user:{user_id}", - ) - - logger.info( - "App2 财务洞察完成: site_id=%s dimension=%s conversation_id=%s tokens=%d", - site_id, time_dimension, conversation_id, tokens_used, - ) - - return result - - -def _month_offset(year: int, month: int, offset: int) -> tuple[int, int]: - """计算月份偏移，返回 (year, month)。""" - # 转为 0-based 计算 - total = (year * 12 + (month - 1)) + offset - return total // 12, total % 12 + 1 diff --git a/apps/backend/app/ai/apps/app3_clue.py b/apps/backend/app/ai/apps/app3_clue.py deleted file mode 100644 index 6eb8280..0000000 --- a/apps/backend/app/ai/apps/app3_clue.py +++ /dev/null @@ -1,263 +0,0 @@ -"""应用 3：客户数据维客线索分析（骨架）。 - -客户新增消费时自动触发，通过 AI 分析客户数据提取维客线索。 -线索 category 限定 3 个枚举值：客户基础、消费习惯、玩法偏好。 -线索提供者统一标记为"系统"。 - -使用 items_sum 口径（= table_charge_money + goods_money -+ assistant_pd_money + assistant_cx_money + electricity_money）， -禁止使用 consume_money。 - -app_id = "app3_clue" -""" - -from __future__ import annotations - -import json -import logging -from datetime import datetime - -from app.ai.dashscope_client import DashScopeClient -from app.ai.cache_service import AICacheService -from app.ai.conversation_service import ConversationService -from app.ai.data_fetchers import fetch_member_consumption_data -from app.ai.schemas import CacheTypeEnum - -logger = logging.getLogger(__name__) - -APP_ID = "app3_clue" - -# system message content 上限 -_MAX_SYSTEM_CONTENT_LEN = 8000 - - -def _default_member_data() -> dict: - """数据获取失败时的默认空值。""" - return { - "member_nickname": "", - "consumption_records": [], - "member_cards": [], - "card_balance_total": 0, - "stored_value_balance_total": 0, - "expected_visit_date": None, - "days_since_last_visit": None, - } - - -async def build_prompt( - context: dict, - cache_svc: AICacheService | None = None, -) -> list[dict]: - """构建 Prompt 消息列表。 - - 从 data_fetchers 获取真实消费数据，失败时降级为空值。 - - Args: - context: 包含 site_id, member_id, nickname 等 - cache_svc: 缓存服务，用于获取 reference 历史数据 - - Returns: - 消息列表 [{"role": "system", "content": ...}, {"role": "user", ...}] - """ - site_id = context["site_id"] - member_id = context["member_id"] - - # 获取消费数据（失败时降级） - data_fetch_failed = False - try: - member_data = await fetch_member_consumption_data(site_id, member_id) - except Exception: - logger.warning("App3 消费数据获取失败，使用默认空值: site_id=%s member_id=%s", site_id, member_id, exc_info=True) - member_data = _default_member_data() - data_fetch_failed = True - - # 构建 reference：App6 线索 + 最近 2 套 App8 历史（附 generated_at） - reference = _build_reference(site_id, member_id, cache_svc) - - member_nickname = member_data.get("member_nickname", "") - consumption_records = member_data.get("consumption_records", []) - - # 空数据标注 - if not consumption_records: - if data_fetch_failed: - consumption_records = "⚠ 消费数据获取失败，该客户暂无消费记录可供分析" - else: - consumption_records = "该客户暂无消费记录" - - system_content = { - "task": "分析客户消费数据，提取维客线索。", - "app_id": APP_ID, - "rules": { - "category_enum": ["客户基础", "消费习惯", "玩法偏好"], - "providers": "系统", - "amount_caliber": "items_sum = table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money", - "禁止使用": "consume_money", - }, - "output_format": { - "clues": [ - { - "category": "枚举值（客户基础/消费习惯/玩法偏好）", - "summary": "一句话摘要", - "detail": "详细说明", - "emoji": "表情符号", - } - ] - }, - "current_time": datetime.now().strftime("%Y-%m-%d %H:%M"), - "member_nickname": member_nickname, - "main_data": { - "consumption_records": consumption_records, - "member_cards": member_data.get("member_cards", []), - "card_balance_total": member_data.get("card_balance_total", 0), - "stored_value_balance_total": member_data.get("stored_value_balance_total", 0), - "expected_visit_date": member_data.get("expected_visit_date"), - "days_since_last_visit": member_data.get("days_since_last_visit"), - }, - "reference": reference, - } - - # Token 预算控制：截断 consumption_records - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - if len(content_str) > _MAX_SYSTEM_CONTENT_LEN: - records = system_content["main_data"].get("consumption_records") - if isinstance(records, list) and len(records) > 5: - system_content["main_data"]["consumption_records"] = records[:5] - system_content["main_data"]["_truncated"] = f"消费记录已截断，原始共 {len(records)} 条" - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - - user_content = ( - f"请分析会员 {member_id} 的消费数据，提取维客线索。" - "每条线索包含 category、summary、detail、emoji 四个字段。" - "category 必须是：客户基础、消费习惯、玩法偏好 之一。" - ) - - return [ - {"role": "system", "content": content_str}, - {"role": "user", "content": user_content}, - ] - - -def _build_reference( - site_id: int, - member_id: int, - cache_svc: AICacheService | None, -) -> dict: - """构建 Prompt reference 字段。 - - 包含： - - App6 备注分析线索（最新一条，如有） - - 最近 2 套 App8 维客线索整理历史（附 generated_at） - - 缓存不存在时返回空对象 {}。 - """ - if cache_svc is None: - return {} - - reference: dict = {} - target_id = str(member_id) - - # App6 备注分析线索 - app6_latest = cache_svc.get_latest( - CacheTypeEnum.APP6_NOTE_ANALYSIS.value, site_id, target_id, - ) - if app6_latest: - reference["app6_note_clues"] = { - "result_json": app6_latest.get("result_json"), - "generated_at": app6_latest.get("created_at"), - } - - # 最近 2 套 App8 历史 - app8_history = cache_svc.get_history( - CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, limit=2, - ) - if app8_history: - reference["app8_history"] = [ - { - "result_json": h.get("result_json"), - "generated_at": h.get("created_at"), - } - for h in app8_history - ] - - return reference - - -async def run( - context: dict, - client: DashScopeClient, - cache_svc: AICacheService, - conv_svc: ConversationService, -) -> dict: - """执行 App3 客户数据维客线索分析。 - - 流程： - 1. build_prompt 构建 Prompt - 2. bailian.chat_json 调用百炼 - 3. 写入 conversation + messages - 4. 写入 ai_cache - 5. 返回结果 - - Args: - context: site_id, member_id, user_id(默认'system'), nickname(默认'') - bailian: 百炼客户端 - cache_svc: 缓存服务 - conv_svc: 对话服务 - - Returns: - 百炼返回的结构化 JSON（clues 数组） - """ - site_id = context["site_id"] - member_id = context["member_id"] - user_id = context.get("user_id", "system") - nickname = context.get("nickname", "") - - # 1. 构建 Prompt - messages = await build_prompt(context, cache_svc) - - # 2. 创建对话记录 - conversation_id = conv_svc.create_conversation( - user_id=user_id, - nickname=nickname, - app_id=APP_ID, - site_id=site_id, - source_context={"member_id": member_id}, - ) - - # 写入 system + user 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="system", - content=messages[0]["content"], - ) - conv_svc.add_message( - conversation_id=conversation_id, - role="user", - content=messages[1]["content"], - ) - - # 3. 调用百炼 API - result, tokens_used = await bailian.chat_json(messages) - - # 4. 写入 assistant 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="assistant", - content=json.dumps(result, ensure_ascii=False), - tokens_used=tokens_used, - ) - - # 5. 写入缓存 - cache_svc.write_cache( - cache_type=CacheTypeEnum.APP3_CLUE.value, - site_id=site_id, - target_id=str(member_id), - result_json=result, - triggered_by=f"user:{user_id}", - ) - - logger.info( - "App3 线索分析完成: site_id=%s member_id=%s conversation_id=%s tokens=%d", - site_id, member_id, conversation_id, tokens_used, - ) - - return result diff --git a/apps/backend/app/ai/apps/app4_analysis.py b/apps/backend/app/ai/apps/app4_analysis.py deleted file mode 100644 index 61e4c12..0000000 --- a/apps/backend/app/ai/apps/app4_analysis.py +++ /dev/null @@ -1,300 +0,0 @@ -"""应用 4：关系分析/任务建议（骨架）。 - -助教参与新结算或被分配召回任务时自动触发， -生成关系分析和任务建议。 - -Prompt reference 包含 App8 最新 + 最近 2 套历史（附 generated_at）。 -缓存不存在时 reference 传空对象，标注"暂无历史线索"。 - -app_id = "app4_analysis" -""" - -from __future__ import annotations - -import asyncio -import json -import logging -from datetime import datetime - -from app.ai.dashscope_client import DashScopeClient -from app.ai.cache_service import AICacheService -from app.ai.conversation_service import ConversationService -from app.ai.data_fetchers import ( - fetch_assistant_info, - fetch_member_consumption_data, - fetch_member_notes, - fetch_service_history, -) -from app.ai.schemas import CacheTypeEnum - -logger = logging.getLogger(__name__) - -APP_ID = "app4_analysis" - -# system message content 上限 -_MAX_SYSTEM_CONTENT_LEN = 8000 - - -def _default_member_data() -> dict: - """数据获取失败时的默认空值。""" - return { - "member_nickname": "", - "consumption_records": [], - "member_cards": [], - "card_balance_total": 0, - "stored_value_balance_total": 0, - "expected_visit_date": None, - "days_since_last_visit": None, - } - - -async def build_prompt( - context: dict, - cache_svc: AICacheService | None = None, -) -> list[dict]: - """构建 Prompt 消息列表。 - - 并发获取助教信息、服务历史、客户消费数据、备注，部分失败不阻断。 - - Args: - context: 包含 site_id, assistant_id, member_id - cache_svc: 缓存服务，用于获取 reference 历史数据 - - Returns: - 消息列表 - """ - site_id = context["site_id"] - assistant_id = context["assistant_id"] - member_id = context["member_id"] - - # 并发获取 4 类数据，部分失败不阻断 - results = await asyncio.gather( - fetch_assistant_info(site_id, assistant_id), - fetch_service_history(site_id, assistant_id, member_id), - fetch_member_consumption_data(site_id, member_id), - fetch_member_notes(site_id, member_id), - return_exceptions=True, - ) - - # 降级处理 - fetch_errors: list[str] = [] - - if isinstance(results[0], Exception): - logger.warning("App4 助教信息获取失败: %s", results[0]) - assistant_info = {} - fetch_errors.append("助教信息获取失败") - else: - assistant_info = results[0] - - if isinstance(results[1], Exception): - logger.warning("App4 服务历史获取失败: %s", results[1]) - service_history: list = [] - fetch_errors.append("服务历史获取失败") - else: - service_history = results[1] - - if isinstance(results[2], Exception): - logger.warning("App4 消费数据获取失败: %s", results[2]) - member_data = _default_member_data() - fetch_errors.append("消费数据获取失败") - else: - member_data = results[2] - - if isinstance(results[3], Exception): - logger.warning("App4 备注获取失败: %s", results[3]) - notes: list = [] - fetch_errors.append("备注获取失败") - else: - notes = results[3] - - # 构建 reference：App8 最新 + 最近 2 套历史 - reference = _build_reference(site_id, member_id, cache_svc) - - system_content: dict = { - "task": "分析助教与客户的关系，生成任务建议。", - "app_id": APP_ID, - "output_format": { - "task_description": "任务描述文本", - "action_suggestions": ["建议1", "建议2"], - "one_line_summary": "一句话总结", - }, - "current_time": datetime.now().strftime("%Y-%m-%d %H:%M"), - "assistant_info": assistant_info if assistant_info else "⚠ 助教信息获取失败", - "service_history": service_history if service_history else "暂无服务记录", - "task_assignment_basis": { - "consumption_records": member_data.get("consumption_records", []) or "该客户暂无消费记录", - "member_cards": member_data.get("member_cards", []), - "card_balance_total": member_data.get("card_balance_total", 0), - "stored_value_balance_total": member_data.get("stored_value_balance_total", 0), - "expected_visit_date": member_data.get("expected_visit_date"), - "days_since_last_visit": member_data.get("days_since_last_visit"), - }, - "customer_data": { - "system_data": { - "member_nickname": member_data.get("member_nickname", ""), - }, - "notes": notes if notes else "暂无备注", - }, - "reference": reference, - } - - if fetch_errors: - system_content["_data_warnings"] = fetch_errors - - # Token 预算控制 - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - if len(content_str) > _MAX_SYSTEM_CONTENT_LEN: - # 优先截断 service_history - sh = system_content.get("service_history") - if isinstance(sh, list) and len(sh) > 5: - system_content["service_history"] = sh[:5] - system_content["_truncated_service_history"] = f"服务记录已截断，原始共 {len(sh)} 条" - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - if len(content_str) > _MAX_SYSTEM_CONTENT_LEN: - records = system_content["task_assignment_basis"].get("consumption_records") - if isinstance(records, list) and len(records) > 5: - system_content["task_assignment_basis"]["consumption_records"] = records[:5] - system_content["task_assignment_basis"]["_truncated"] = f"消费记录已截断，原始共 {len(records)} 条" - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - if len(content_str) > _MAX_SYSTEM_CONTENT_LEN: - n = system_content["customer_data"].get("notes") - if isinstance(n, list) and len(n) > 10: - system_content["customer_data"]["notes"] = n[:10] - system_content["customer_data"]["_truncated_notes"] = f"备注已截断，原始共 {len(n)} 条" - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - - # 缓存不存在时在 user prompt 中标注 - no_history_hint = "" - if not reference: - no_history_hint = "（暂无历史线索，请基于现有信息分析）" - - user_content = ( - f"请分析助教 {assistant_id} 与会员 {member_id} 的关系，" - f"生成任务建议。{no_history_hint}" - "返回 task_description、action_suggestions、one_line_summary 三个字段。" - ) - - return [ - {"role": "system", "content": content_str}, - {"role": "user", "content": user_content}, - ] - - -def _build_reference( - site_id: int, - member_id: int, - cache_svc: AICacheService | None, -) -> dict: - """构建 Prompt reference 字段。 - - 包含： - - App8 最新维客线索（如有） - - 最近 2 套 App8 历史（附 generated_at） - - 缓存不存在时返回空对象 {}。 - """ - if cache_svc is None: - return {} - - reference: dict = {} - target_id = str(member_id) - - # App8 最新 - app8_latest = cache_svc.get_latest( - CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, - ) - if app8_latest: - reference["app8_latest"] = { - "result_json": app8_latest.get("result_json"), - "generated_at": app8_latest.get("created_at"), - } - - # 最近 2 套 App8 历史 - app8_history = cache_svc.get_history( - CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, limit=2, - ) - if app8_history: - reference["app8_history"] = [ - { - "result_json": h.get("result_json"), - "generated_at": h.get("created_at"), - } - for h in app8_history - ] - - return reference - - -async def run( - context: dict, - client: DashScopeClient, - cache_svc: AICacheService, - conv_svc: ConversationService, -) -> dict: - """执行 App4 关系分析。 - - Args: - context: site_id, assistant_id, member_id - bailian: 百炼客户端 - cache_svc: 缓存服务 - conv_svc: 对话服务 - - Returns: - 百炼返回的结构化 JSON（task_description, action_suggestions, one_line_summary） - """ - site_id = context["site_id"] - assistant_id = context["assistant_id"] - member_id = context["member_id"] - user_id = context.get("user_id", "system") - nickname = context.get("nickname", "") - - # 1. 构建 Prompt - messages = await build_prompt(context, cache_svc) - - # 2. 创建对话记录 - conversation_id = conv_svc.create_conversation( - user_id=user_id, - nickname=nickname, - app_id=APP_ID, - site_id=site_id, - source_context={"assistant_id": assistant_id, "member_id": member_id}, - ) - - # 写入 system + user 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="system", - content=messages[0]["content"], - ) - conv_svc.add_message( - conversation_id=conversation_id, - role="user", - content=messages[1]["content"], - ) - - # 3. 调用百炼 API - result, tokens_used = await bailian.chat_json(messages) - - # 4. 写入 assistant 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="assistant", - content=json.dumps(result, ensure_ascii=False), - tokens_used=tokens_used, - ) - - # 5. 写入缓存（target_id = {assistant_id}_{member_id}） - cache_svc.write_cache( - cache_type=CacheTypeEnum.APP4_ANALYSIS.value, - site_id=site_id, - target_id=f"{assistant_id}_{member_id}", - result_json=result, - triggered_by=f"user:{user_id}", - ) - - logger.info( - "App4 关系分析完成: site_id=%s assistant=%s member=%s conversation_id=%s tokens=%d", - site_id, assistant_id, member_id, conversation_id, tokens_used, - ) - - return result diff --git a/apps/backend/app/ai/apps/app5_tactics.py b/apps/backend/app/ai/apps/app5_tactics.py deleted file mode 100644 index 2700a08..0000000 --- a/apps/backend/app/ai/apps/app5_tactics.py +++ /dev/null @@ -1,288 +0,0 @@ -"""应用 5：话术参考（骨架）。 - -App4 完成后自动联动触发，接收 App4 完整返回结果 -作为 Prompt 中的 task_suggestion 字段。 - -Prompt reference 包含最近 2 套 App8 历史（附 generated_at）。 - -app_id = "app5_tactics" -""" - -from __future__ import annotations - -import asyncio -import json -import logging -from datetime import datetime - -from app.ai.dashscope_client import DashScopeClient -from app.ai.cache_service import AICacheService -from app.ai.conversation_service import ConversationService -from app.ai.data_fetchers import ( - fetch_assistant_info, - fetch_member_consumption_data, - fetch_member_notes, - fetch_service_history, -) -from app.ai.schemas import CacheTypeEnum - -logger = logging.getLogger(__name__) - -APP_ID = "app5_tactics" - -# system message content 上限 -_MAX_SYSTEM_CONTENT_LEN = 8000 - - -def _default_member_data() -> dict: - """数据获取失败时的默认空值。""" - return { - "member_nickname": "", - "consumption_records": [], - "member_cards": [], - "card_balance_total": 0, - "stored_value_balance_total": 0, - "expected_visit_date": None, - "days_since_last_visit": None, - } - - -async def build_prompt( - context: dict, - cache_svc: AICacheService | None = None, -) -> list[dict]: - """构建 Prompt 消息列表。 - - 复用 App4 的数据获取逻辑（并发获取助教信息、服务历史、消费数据、备注）， - 额外从 context["app4_result"] 获取 task_suggestion。 - - Args: - context: 包含 site_id, assistant_id, member_id, app4_result(dict) - cache_svc: 缓存服务，用于获取 reference 历史数据 - - Returns: - 消息列表 - """ - site_id = context["site_id"] - assistant_id = context["assistant_id"] - member_id = context["member_id"] - # App4 结果作为 task_suggestion，缺失时设为空对象 - task_suggestion = context.get("app4_result") or {} - - # 并发获取 4 类数据，部分失败不阻断 - results = await asyncio.gather( - fetch_assistant_info(site_id, assistant_id), - fetch_service_history(site_id, assistant_id, member_id), - fetch_member_consumption_data(site_id, member_id), - fetch_member_notes(site_id, member_id), - return_exceptions=True, - ) - - # 降级处理 - fetch_errors: list[str] = [] - - if isinstance(results[0], Exception): - logger.warning("App5 助教信息获取失败: %s", results[0]) - assistant_info = {} - fetch_errors.append("助教信息获取失败") - else: - assistant_info = results[0] - - if isinstance(results[1], Exception): - logger.warning("App5 服务历史获取失败: %s", results[1]) - service_history: list = [] - fetch_errors.append("服务历史获取失败") - else: - service_history = results[1] - - if isinstance(results[2], Exception): - logger.warning("App5 消费数据获取失败: %s", results[2]) - member_data = _default_member_data() - fetch_errors.append("消费数据获取失败") - else: - member_data = results[2] - - if isinstance(results[3], Exception): - logger.warning("App5 备注获取失败: %s", results[3]) - notes: list = [] - fetch_errors.append("备注获取失败") - else: - notes = results[3] - - # 构建 reference：最近 2 套 App8 历史 - reference = _build_reference(site_id, member_id, cache_svc) - - system_content: dict = { - "task": ( - "基于关系分析和任务建议，生成沟通话术参考。" - "输出必须严格遵循 output_format 中定义的 JSON 结构，" - "每条话术必须包含 scenario（场景描述）和 script（话术内容）两个字段，" - "禁止使用 content 或其他字段名替代。" - ), - "app_id": APP_ID, - "task_suggestion": task_suggestion, - "output_format": { - "tactics": [ - {"scenario": "场景描述", "script": "话术内容"} - ] - }, - "current_time": datetime.now().strftime("%Y-%m-%d %H:%M"), - "assistant_info": assistant_info if assistant_info else "⚠ 助教信息获取失败", - "service_history": service_history if service_history else "暂无服务记录", - "task_assignment_basis": { - "consumption_records": member_data.get("consumption_records", []) or "该客户暂无消费记录", - "member_cards": member_data.get("member_cards", []), - "card_balance_total": member_data.get("card_balance_total", 0), - "stored_value_balance_total": member_data.get("stored_value_balance_total", 0), - "expected_visit_date": member_data.get("expected_visit_date"), - "days_since_last_visit": member_data.get("days_since_last_visit"), - }, - "customer_data": { - "system_data": { - "member_nickname": member_data.get("member_nickname", ""), - }, - "notes": notes if notes else "暂无备注", - }, - "reference": reference, - } - - if fetch_errors: - system_content["_data_warnings"] = fetch_errors - - # Token 预算控制 - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - if len(content_str) > _MAX_SYSTEM_CONTENT_LEN: - sh = system_content.get("service_history") - if isinstance(sh, list) and len(sh) > 5: - system_content["service_history"] = sh[:5] - system_content["_truncated_service_history"] = f"服务记录已截断，原始共 {len(sh)} 条" - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - if len(content_str) > _MAX_SYSTEM_CONTENT_LEN: - records = system_content["task_assignment_basis"].get("consumption_records") - if isinstance(records, list) and len(records) > 5: - system_content["task_assignment_basis"]["consumption_records"] = records[:5] - system_content["task_assignment_basis"]["_truncated"] = f"消费记录已截断，原始共 {len(records)} 条" - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - if len(content_str) > _MAX_SYSTEM_CONTENT_LEN: - n = system_content["customer_data"].get("notes") - if isinstance(n, list) and len(n) > 10: - system_content["customer_data"]["notes"] = n[:10] - system_content["customer_data"]["_truncated_notes"] = f"备注已截断，原始共 {len(n)} 条" - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - - user_content = ( - f"请为助教 {assistant_id} 生成与会员 {member_id} 沟通的话术参考。" - "返回 tactics 数组，每条包含 scenario 和 script 字段。" - ) - - return [ - {"role": "system", "content": content_str}, - {"role": "user", "content": user_content}, - ] - - -def _build_reference( - site_id: int, - member_id: int, - cache_svc: AICacheService | None, -) -> dict: - """构建 Prompt reference 字段。 - - 包含最近 2 套 App8 历史（附 generated_at）。 - 缓存不存在时返回空对象 {}。 - """ - if cache_svc is None: - return {} - - reference: dict = {} - target_id = str(member_id) - - # 最近 2 套 App8 历史 - app8_history = cache_svc.get_history( - CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, limit=2, - ) - if app8_history: - reference["app8_history"] = [ - { - "result_json": h.get("result_json"), - "generated_at": h.get("created_at"), - } - for h in app8_history - ] - - return reference - - -async def run( - context: dict, - client: DashScopeClient, - cache_svc: AICacheService, - conv_svc: ConversationService, -) -> dict: - """执行 App5 话术参考。 - - Args: - context: site_id, assistant_id, member_id, app4_result(dict) - bailian: 百炼客户端 - cache_svc: 缓存服务 - conv_svc: 对话服务 - - Returns: - 百炼返回的结构化 JSON（tactics 数组） - """ - site_id = context["site_id"] - assistant_id = context["assistant_id"] - member_id = context["member_id"] - user_id = context.get("user_id", "system") - nickname = context.get("nickname", "") - - # 1. 构建 Prompt - messages = await build_prompt(context, cache_svc) - - # 2. 创建对话记录 - conversation_id = conv_svc.create_conversation( - user_id=user_id, - nickname=nickname, - app_id=APP_ID, - site_id=site_id, - source_context={"assistant_id": assistant_id, "member_id": member_id}, - ) - - # 写入 system + user 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="system", - content=messages[0]["content"], - ) - conv_svc.add_message( - conversation_id=conversation_id, - role="user", - content=messages[1]["content"], - ) - - # 3. 调用百炼 API - result, tokens_used = await bailian.chat_json(messages) - - # 4. 写入 assistant 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="assistant", - content=json.dumps(result, ensure_ascii=False), - tokens_used=tokens_used, - ) - - # 5. 写入缓存（target_id = {assistant_id}_{member_id}） - cache_svc.write_cache( - cache_type=CacheTypeEnum.APP5_TACTICS.value, - site_id=site_id, - target_id=f"{assistant_id}_{member_id}", - result_json=result, - triggered_by=f"user:{user_id}", - ) - - logger.info( - "App5 话术参考完成: site_id=%s assistant=%s member=%s conversation_id=%s tokens=%d", - site_id, assistant_id, member_id, conversation_id, tokens_used, - ) - - return result diff --git a/apps/backend/app/ai/apps/app6_note.py b/apps/backend/app/ai/apps/app6_note.py deleted file mode 100644 index 0430554..0000000 --- a/apps/backend/app/ai/apps/app6_note.py +++ /dev/null @@ -1,289 +0,0 @@ -"""应用 6：备注分析（骨架）。 - -助教提交备注后自动触发，通过 AI 分析备注内容， -提取维客线索并评分。 - -返回 score（1-10）+ clues 数组。 -评分规则：6 分为标准分，重复/低价值/时效性低酌情扣分，高价值信息酌情加分。 -线索 category 限定 6 个枚举值。 -线索提供者标记为当前备注提供人（context.noted_by_name）。 - -app_id = "app6_note" -""" - -from __future__ import annotations - -import asyncio -import json -import logging -from datetime import datetime - -from app.ai.dashscope_client import DashScopeClient -from app.ai.cache_service import AICacheService -from app.ai.conversation_service import ConversationService -from app.ai.data_fetchers import fetch_member_consumption_data, fetch_member_notes -from app.ai.schemas import CacheTypeEnum - -logger = logging.getLogger(__name__) - -APP_ID = "app6_note" - -# system message content 上限 -_MAX_SYSTEM_CONTENT_LEN = 8000 - - -def _default_member_data() -> dict: - """数据获取失败时的默认空值。""" - return { - "member_nickname": "", - "consumption_records": [], - "member_cards": [], - "card_balance_total": 0, - "stored_value_balance_total": 0, - "expected_visit_date": None, - "days_since_last_visit": None, - } - - -async def build_prompt( - context: dict, - cache_svc: AICacheService | None = None, -) -> list[dict]: - """构建 Prompt 消息列表。 - - 并发获取消费数据和备注，失败时降级为空值。 - - Args: - context: 包含 site_id, member_id, note_content, noted_by_name - cache_svc: 缓存服务，用于获取 reference 历史数据 - - Returns: - 消息列表 - """ - site_id = context["site_id"] - member_id = context["member_id"] - note_content = context.get("note_content", "") - noted_by_name = context.get("noted_by_name", "") - noted_by_created_at = context.get("noted_by_created_at", "") - - # 并发获取消费数据和备注 - results = await asyncio.gather( - fetch_member_consumption_data(site_id, member_id), - fetch_member_notes(site_id, member_id), - return_exceptions=True, - ) - - fetch_errors: list[str] = [] - - if isinstance(results[0], Exception): - logger.warning("App6 消费数据获取失败: %s", results[0]) - member_data = _default_member_data() - fetch_errors.append("消费数据获取失败") - else: - member_data = results[0] - - if isinstance(results[1], Exception): - logger.warning("App6 备注获取失败: %s", results[1]) - all_notes: list = [] - fetch_errors.append("备注获取失败") - else: - all_notes = results[1] - - # 构建 reference：App3 线索 + 最近 2 套 App8 历史 - reference = _build_reference(site_id, member_id, cache_svc) - - # 将消费数据和备注注入 reference - reference["member_nickname"] = member_data.get("member_nickname", "") - reference["consumption_data"] = { - "consumption_records": member_data.get("consumption_records", []) or "该客户暂无消费记录", - "member_cards": member_data.get("member_cards", []), - "card_balance_total": member_data.get("card_balance_total", 0), - "stored_value_balance_total": member_data.get("stored_value_balance_total", 0), - "expected_visit_date": member_data.get("expected_visit_date"), - "days_since_last_visit": member_data.get("days_since_last_visit"), - } - reference["all_notes"] = all_notes if all_notes else [] - - system_content: dict = { - "task": "分析备注内容，提取维客线索并评分。", - "app_id": APP_ID, - "rules": { - "category_enum": [ - "客户基础", "消费习惯", "玩法偏好", - "促销偏好", "社交关系", "重要反馈", - ], - "providers": noted_by_name, - "scoring": "6 分为标准分，重复/低价值/时效性低酌情扣分，高价值信息酌情加分", - "score_range": "1-10", - }, - "output_format": { - "score": "1-10 整数", - "clues": [ - { - "category": "枚举值（6 选 1）", - "summary": "一句话摘要", - "detail": "详细说明", - "emoji": "表情符号", - } - ], - }, - "current_time": datetime.now().strftime("%Y-%m-%d %H:%M"), - "current_note": { - "content": note_content, - "recorded_by": noted_by_name, - "created_at": noted_by_created_at, - }, - "reference": reference, - } - - if fetch_errors: - system_content["_data_warnings"] = fetch_errors - - # Token 预算控制 - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - if len(content_str) > _MAX_SYSTEM_CONTENT_LEN: - records = system_content["reference"].get("consumption_data", {}).get("consumption_records") - if isinstance(records, list) and len(records) > 5: - system_content["reference"]["consumption_data"]["consumption_records"] = records[:5] - system_content["reference"]["consumption_data"]["_truncated"] = f"消费记录已截断，原始共 {len(records)} 条" - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - if len(content_str) > _MAX_SYSTEM_CONTENT_LEN: - n = system_content["reference"].get("all_notes") - if isinstance(n, list) and len(n) > 10: - system_content["reference"]["all_notes"] = n[:10] - system_content["reference"]["_truncated_notes"] = f"备注已截断，原始共 {len(n)} 条" - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - - user_content = ( - f"请分析以下备注内容，提取维客线索并评分。\n" - f"备注提供人：{noted_by_name}\n" - f"备注内容：{note_content}\n" - "返回 score（1-10 整数）和 clues 数组。" - "category 必须是：客户基础、消费习惯、玩法偏好、促销偏好、社交关系、重要反馈 之一。" - ) - - return [ - {"role": "system", "content": content_str}, - {"role": "user", "content": user_content}, - ] - - -def _build_reference( - site_id: int, - member_id: int, - cache_svc: AICacheService | None, -) -> dict: - """构建 Prompt reference 字段。 - - 包含： - - App3 客户数据线索（最新一条，如有） - - 最近 2 套 App8 维客线索整理历史（附 generated_at） - - 缓存不存在时返回空对象 {}。 - """ - if cache_svc is None: - return {} - - reference: dict = {} - target_id = str(member_id) - - # App3 客户数据线索 - app3_latest = cache_svc.get_latest( - CacheTypeEnum.APP3_CLUE.value, site_id, target_id, - ) - if app3_latest: - reference["app3_clues"] = { - "result_json": app3_latest.get("result_json"), - "generated_at": app3_latest.get("created_at"), - } - - # 最近 2 套 App8 历史 - app8_history = cache_svc.get_history( - CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, limit=2, - ) - if app8_history: - reference["app8_history"] = [ - { - "result_json": h.get("result_json"), - "generated_at": h.get("created_at"), - } - for h in app8_history - ] - - return reference - - -async def run( - context: dict, - client: DashScopeClient, - cache_svc: AICacheService, - conv_svc: ConversationService, -) -> dict: - """执行 App6 备注分析。 - - Args: - context: site_id, member_id, note_content, noted_by_name - bailian: 百炼客户端 - cache_svc: 缓存服务 - conv_svc: 对话服务 - - Returns: - 百炼返回的结构化 JSON（score + clues 数组） - """ - site_id = context["site_id"] - member_id = context["member_id"] - user_id = context.get("user_id", "system") - nickname = context.get("nickname", "") - - # 1. 构建 Prompt - messages = await build_prompt(context, cache_svc) - - # 2. 创建对话记录 - conversation_id = conv_svc.create_conversation( - user_id=user_id, - nickname=nickname, - app_id=APP_ID, - site_id=site_id, - source_context={"member_id": member_id}, - ) - - # 写入 system + user 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="system", - content=messages[0]["content"], - ) - conv_svc.add_message( - conversation_id=conversation_id, - role="user", - content=messages[1]["content"], - ) - - # 3. 调用百炼 API - result, tokens_used = await bailian.chat_json(messages) - - # 4. 写入 assistant 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="assistant", - content=json.dumps(result, ensure_ascii=False), - tokens_used=tokens_used, - ) - - # 5. 写入缓存（score 存入 ai_cache.score） - score = result.get("score") - cache_svc.write_cache( - cache_type=CacheTypeEnum.APP6_NOTE_ANALYSIS.value, - site_id=site_id, - target_id=str(member_id), - result_json=result, - triggered_by=f"user:{user_id}", - score=score, - ) - - logger.info( - "App6 备注分析完成: site_id=%s member_id=%s score=%s conversation_id=%s tokens=%d", - site_id, member_id, score, conversation_id, tokens_used, - ) - - return result diff --git a/apps/backend/app/ai/apps/app7_customer.py b/apps/backend/app/ai/apps/app7_customer.py deleted file mode 100644 index b50d82d..0000000 --- a/apps/backend/app/ai/apps/app7_customer.py +++ /dev/null @@ -1,282 +0,0 @@ -"""应用 7：客户分析（骨架）。 - -消费事件链中 App8 完成后串行触发，生成客户全量分析与运营建议。 - -使用 items_sum 口径（= table_charge_money + goods_money -+ assistant_pd_money + assistant_cx_money + electricity_money）， -禁止使用 consume_money。 - -对主观信息（来自备注）标注【来源：XXX，请甄别信息真实性】。 - -app_id = "app7_customer" -""" - -from __future__ import annotations - -import asyncio -import json -import logging -from datetime import datetime - -from app.ai.dashscope_client import DashScopeClient -from app.ai.cache_service import AICacheService -from app.ai.conversation_service import ConversationService -from app.ai.data_fetchers import fetch_member_consumption_data, fetch_member_notes -from app.ai.schemas import CacheTypeEnum - -logger = logging.getLogger(__name__) - -APP_ID = "app7_customer" - -# system message content 上限 -_MAX_SYSTEM_CONTENT_LEN = 8000 - - -def _default_member_data() -> dict: - """数据获取失败时的默认空值。""" - return { - "member_nickname": "", - "consumption_records": [], - "member_cards": [], - "card_balance_total": 0, - "stored_value_balance_total": 0, - "expected_visit_date": None, - "days_since_last_visit": None, - } - - -async def build_prompt( - context: dict, - cache_svc: AICacheService | None = None, -) -> list[dict]: - """构建 Prompt 消息列表。 - - 并发获取消费数据和备注，备注标注来源信息。 - - Args: - context: 包含 site_id, member_id - cache_svc: 缓存服务，用于获取 reference 历史数据 - - Returns: - 消息列表 - """ - site_id = context["site_id"] - member_id = context["member_id"] - - # 并发获取消费数据和备注 - results = await asyncio.gather( - fetch_member_consumption_data(site_id, member_id), - fetch_member_notes(site_id, member_id), - return_exceptions=True, - ) - - fetch_errors: list[str] = [] - - if isinstance(results[0], Exception): - logger.warning("App7 消费数据获取失败: %s", results[0]) - member_data = _default_member_data() - fetch_errors.append("消费数据获取失败") - else: - member_data = results[0] - - if isinstance(results[1], Exception): - logger.warning("App7 备注获取失败: %s", results[1]) - notes_raw: list = [] - fetch_errors.append("备注获取失败") - else: - notes_raw = results[1] - - # 备注标注来源信息 - if notes_raw: - subjective_notes = [] - for note in notes_raw: - recorded_by = note.get("recorded_by", "未知") - annotated = dict(note) - annotated["content"] = f"{note.get('content', '')}【来源：{recorded_by}，请甄别信息真实性】" - subjective_notes.append(annotated) - else: - subjective_notes = "该客户暂无主观备注信息" - - member_nickname = member_data.get("member_nickname", "") - - # 构建 reference：最新 + 最近 2 套 App8 历史 - reference = _build_reference(site_id, member_id, cache_svc) - - system_content: dict = { - "task": "综合分析客户数据，生成运营策略建议。", - "app_id": APP_ID, - "rules": { - "amount_caliber": "items_sum = table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money", - "禁止使用": "consume_money", - "subjective_info_label": "对主观信息（来自备注）标注【来源：XXX，请甄别信息真实性】", - }, - "output_format": { - "strategies": [ - {"title": "策略标题", "content": "策略内容"} - ], - "summary": "一句话总结", - }, - "current_time": datetime.now().strftime("%Y-%m-%d %H:%M"), - "member_id": member_id, - "member_nickname": member_nickname, - "objective_data": { - "consumption_records": member_data.get("consumption_records", []) or "该客户暂无消费记录", - "member_cards": member_data.get("member_cards", []), - "card_balance_total": member_data.get("card_balance_total", 0), - "stored_value_balance_total": member_data.get("stored_value_balance_total", 0), - "expected_visit_date": member_data.get("expected_visit_date"), - "days_since_last_visit": member_data.get("days_since_last_visit"), - }, - "subjective_data": { - "notes": subjective_notes, - }, - "reference": reference, - } - - if fetch_errors: - system_content["_data_warnings"] = fetch_errors - - # Token 预算控制 - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - if len(content_str) > _MAX_SYSTEM_CONTENT_LEN: - records = system_content["objective_data"].get("consumption_records") - if isinstance(records, list) and len(records) > 5: - system_content["objective_data"]["consumption_records"] = records[:5] - system_content["objective_data"]["_truncated"] = f"消费记录已截断，原始共 {len(records)} 条" - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - if len(content_str) > _MAX_SYSTEM_CONTENT_LEN: - n = system_content["subjective_data"].get("notes") - if isinstance(n, list) and len(n) > 10: - system_content["subjective_data"]["notes"] = n[:10] - system_content["subjective_data"]["_truncated_notes"] = f"备注已截断，原始共 {len(n)} 条" - content_str = json.dumps(system_content, ensure_ascii=False, default=str) - - user_content = ( - f"请综合分析会员 {member_id} 的客户数据，生成运营策略建议。" - "返回 strategies 数组（每条含 title 和 content）和 summary 字段。" - "对来自备注的主观信息，请标注【来源：XXX，请甄别信息真实性】。" - ) - - return [ - {"role": "system", "content": content_str}, - {"role": "user", "content": user_content}, - ] - - -def _build_reference( - site_id: int, - member_id: int, - cache_svc: AICacheService | None, -) -> dict: - """构建 Prompt reference 字段。 - - 包含： - - App8 最新维客线索（如有） - - 最近 2 套 App8 历史（附 generated_at） - - 缓存不存在时返回空对象 {}。 - """ - if cache_svc is None: - return {} - - reference: dict = {} - target_id = str(member_id) - - # App8 最新 - app8_latest = cache_svc.get_latest( - CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, - ) - if app8_latest: - reference["app8_latest"] = { - "result_json": app8_latest.get("result_json"), - "generated_at": app8_latest.get("created_at"), - } - - # 最近 2 套 App8 历史 - app8_history = cache_svc.get_history( - CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, limit=2, - ) - if app8_history: - reference["app8_history"] = [ - { - "result_json": h.get("result_json"), - "generated_at": h.get("created_at"), - } - for h in app8_history - ] - - return reference - - -async def run( - context: dict, - client: DashScopeClient, - cache_svc: AICacheService, - conv_svc: ConversationService, -) -> dict: - """执行 App7 客户分析。 - - Args: - context: site_id, member_id - bailian: 百炼客户端 - cache_svc: 缓存服务 - conv_svc: 对话服务 - - Returns: - 百炼返回的结构化 JSON（strategies 数组 + summary） - """ - site_id = context["site_id"] - member_id = context["member_id"] - user_id = context.get("user_id", "system") - nickname = context.get("nickname", "") - - # 1. 构建 Prompt - messages = await build_prompt(context, cache_svc) - - # 2. 创建对话记录 - conversation_id = conv_svc.create_conversation( - user_id=user_id, - nickname=nickname, - app_id=APP_ID, - site_id=site_id, - source_context={"member_id": member_id}, - ) - - # 写入 system + user 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="system", - content=messages[0]["content"], - ) - conv_svc.add_message( - conversation_id=conversation_id, - role="user", - content=messages[1]["content"], - ) - - # 3. 调用百炼 API - result, tokens_used = await bailian.chat_json(messages) - - # 4. 写入 assistant 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="assistant", - content=json.dumps(result, ensure_ascii=False), - tokens_used=tokens_used, - ) - - # 5. 写入缓存 - cache_svc.write_cache( - cache_type=CacheTypeEnum.APP7_CUSTOMER_ANALYSIS.value, - site_id=site_id, - target_id=str(member_id), - result_json=result, - triggered_by=f"user:{user_id}", - ) - - logger.info( - "App7 客户分析完成: site_id=%s member_id=%s conversation_id=%s tokens=%d", - site_id, member_id, conversation_id, tokens_used, - ) - - return result diff --git a/apps/backend/app/ai/apps/app8_consolidation.py b/apps/backend/app/ai/apps/app8_consolidation.py deleted file mode 100644 index 3dc7c89..0000000 --- a/apps/backend/app/ai/apps/app8_consolidation.py +++ /dev/null @@ -1,211 +0,0 @@ -"""应用 8：维客线索整理。 - -接收 App3（消费分析）和 App6（备注分析）的线索， -通过百炼 AI 整合去重，然后全量替换写入 member_retention_clue 表。 - -app_id = "app8_consolidation" -""" - -from __future__ import annotations - -import json -import logging - -from app.ai.dashscope_client import DashScopeClient -from app.ai.cache_service import AICacheService -from app.ai.conversation_service import ConversationService -from app.ai.prompts.app8_consolidation_prompt import build_prompt -from app.ai.schemas import CacheTypeEnum -from app.database import get_connection - -logger = logging.getLogger(__name__) - -APP_ID = "app8_consolidation" - - -class ClueWriter: - """维客线索全量替换写入器。 - - DELETE source IN ('ai_consumption', 'ai_note') → INSERT 新线索（事务）。 - 人工线索（source='manual'）不受影响。 - """ - - def replace_ai_clues( - self, - member_id: int, - site_id: int, - clues: list[dict], - ) -> int: - """全量替换该客户的 AI 来源线索，返回写入数量。 - - 在单个事务中执行 DELETE + INSERT，失败时回滚保留原有线索。 - - 字段映射： - - category → category - - emoji + " " + summary → summary（如 "📅 偏好周末下午时段消费"） - - detail → detail - - providers → recorded_by_name - - source: 根据 providers 判断（见 _determine_source） - - recorded_by_assistant_id: NULL（系统触发） - """ - conn = get_connection() - try: - with conn.cursor() as cur: - # 1. 删除该客户所有 AI 来源线索 - cur.execute( - """ - DELETE FROM member_retention_clue - WHERE member_id = %s AND site_id = %s - AND source IN ('ai_consumption', 'ai_note') - """, - (member_id, site_id), - ) - - # 2. 插入新线索 - for clue in clues: - emoji = clue.get("emoji", "") - raw_summary = clue.get("summary", "") - summary = f"{emoji} {raw_summary}" if emoji else raw_summary - source = _determine_source(clue.get("providers", "")) - - cur.execute( - """ - INSERT INTO member_retention_clue - (member_id, site_id, category, summary, detail, - source, recorded_by_name, recorded_by_assistant_id) - VALUES (%s, %s, %s, %s, %s, %s, %s, NULL) - """, - ( - member_id, - site_id, - clue.get("category", ""), - summary, - clue.get("detail", ""), - source, - clue.get("providers", ""), - ), - ) - - conn.commit() - return len(clues) - except Exception: - conn.rollback() - raise - finally: - conn.close() - - -def _determine_source(providers: str) -> str: - """根据 providers 判断 source 值。 - - - 纯 App3（providers 仅含"系统"）→ ai_consumption - - 纯 App6（providers 不含"系统"）→ ai_note - - 混合来源 → ai_consumption - """ - if not providers: - return "ai_consumption" - provider_list = [p.strip() for p in providers.split(",")] - has_system = "系统" in provider_list - has_human = any(p != "系统" for p in provider_list if p) - if has_system and not has_human: - # 纯 App3（系统自动分析） - return "ai_consumption" - elif has_human and not has_system: - # 纯 App6（人工备注分析） - return "ai_note" - else: - # 混合来源 - return "ai_consumption" - - -async def run( - context: dict, - client: DashScopeClient, - cache_svc: AICacheService, - conv_svc: ConversationService, -) -> dict: - """执行 App8 维客线索整理。 - - 流程： - 1. build_prompt 构建 Prompt - 2. bailian.chat_json 调用百炼 - 3. 写入 conversation + messages - 4. 写入 ai_cache - 5. ClueWriter 全量替换 member_retention_clue - 6. 返回结果 - - Args: - context: site_id, member_id, app3_clues, app6_clues, - app3_generated_at, app6_generated_at - bailian: 百炼客户端 - cache_svc: 缓存服务 - conv_svc: 对话服务 - - Returns: - 百炼返回的结构化 JSON（clues 数组） - """ - site_id = context["site_id"] - member_id = context["member_id"] - user_id = context.get("user_id", "system") - nickname = context.get("nickname", "") - - # 1. 构建 Prompt - messages = build_prompt(context) - - # 2. 创建对话记录 - conversation_id = conv_svc.create_conversation( - user_id=user_id, - nickname=nickname, - app_id=APP_ID, - site_id=site_id, - source_context={"member_id": member_id}, - ) - - # 写入 system + user 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="system", - content=messages[0]["content"], - ) - conv_svc.add_message( - conversation_id=conversation_id, - role="user", - content=messages[1]["content"], - ) - - # 3. 调用百炼 API - result, tokens_used = await bailian.chat_json(messages) - - # 4. 写入 assistant 消息 - conv_svc.add_message( - conversation_id=conversation_id, - role="assistant", - content=json.dumps(result, ensure_ascii=False), - tokens_used=tokens_used, - ) - - # 5. 写入缓存 - cache_svc.write_cache( - cache_type=CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, - site_id=site_id, - target_id=str(member_id), - result_json=result, - triggered_by=f"user:{user_id}", - ) - - # 6. 全量替换 member_retention_clue - clues = result.get("clues", []) - if clues: - writer = ClueWriter() - written = writer.replace_ai_clues(member_id, site_id, clues) - logger.info( - "App8 线索写入完成: site_id=%s member_id=%s written=%d", - site_id, member_id, written, - ) - - logger.info( - "App8 线索整理完成: site_id=%s member_id=%s conversation_id=%s tokens=%d", - site_id, member_id, conversation_id, tokens_used, - ) - - return result diff --git a/apps/backend/app/ai/cache_service.py b/apps/backend/app/ai/cache_service.py index 761321c..e7fd19b 100644 --- a/apps/backend/app/ai/cache_service.py +++ b/apps/backend/app/ai/cache_service.py @@ -18,6 +18,12 @@ import logging from datetime import datetime, timedelta, timezone from app.database import get_connection +from app.services.runtime_context import ( + LIVE_INSTANCE_ID, + MODE_LIVE, + MODE_SANDBOX, + get_runtime_context, +) logger = logging.getLogger(__name__) @@ -39,6 +45,14 @@ CACHE_MAX_PER_APP = 20_000 class AICacheService: """AI 缓存读写服务。""" + @staticmethod + def _runtime_scope(site_id: int, target_id: str, conn) -> tuple[str, str, str]: + """返回运行模式、实例 ID 和实际 cache target_id。""" + ctx = get_runtime_context(site_id, conn=conn) + if ctx.is_sandbox and ctx.sandbox_instance_id: + return MODE_SANDBOX, ctx.sandbox_instance_id, f"{ctx.sandbox_instance_id}:{target_id}" + return MODE_LIVE, LIVE_INSTANCE_ID, target_id + def get_latest( self, cache_type: str, @@ -52,6 +66,9 @@ class AICacheService: """ conn = get_connection() try: + runtime_mode, sandbox_instance_id, scoped_target_id = self._runtime_scope( + site_id, target_id, conn + ) with conn.cursor() as cur: cur.execute( """ @@ -60,12 +77,14 @@ class AICacheService: created_at, expires_at, status FROM biz.ai_cache WHERE cache_type = %s AND site_id = %s AND target_id = %s + AND COALESCE(runtime_mode, 'live') = %s + AND COALESCE(sandbox_instance_id, 'live') = %s AND (status = 'valid' OR status IS NULL) AND (expires_at IS NULL OR expires_at > now()) ORDER BY created_at DESC LIMIT 1 """, - (cache_type, site_id, target_id), + (cache_type, site_id, scoped_target_id, runtime_mode, sandbox_instance_id), ) columns = [desc[0] for desc in cur.description] row = cur.fetchone() @@ -88,6 +107,9 @@ class AICacheService: """ conn = get_connection() try: + runtime_mode, sandbox_instance_id, scoped_target_id = self._runtime_scope( + site_id, target_id, conn + ) with conn.cursor() as cur: cur.execute( """ @@ -96,10 +118,12 @@ class AICacheService: created_at, expires_at FROM biz.ai_cache WHERE cache_type = %s AND site_id = %s AND target_id = %s + AND COALESCE(runtime_mode, 'live') = %s + AND COALESCE(sandbox_instance_id, 'live') = %s ORDER BY created_at DESC LIMIT %s """, - (cache_type, site_id, target_id, limit), + (cache_type, site_id, scoped_target_id, runtime_mode, sandbox_instance_id, limit), ) columns = [desc[0] for desc in cur.description] rows = cur.fetchall() @@ -128,23 +152,29 @@ class AICacheService: conn = get_connection() try: + runtime_mode, sandbox_instance_id, scoped_target_id = self._runtime_scope( + site_id, target_id, conn + ) with conn.cursor() as cur: cur.execute( """ INSERT INTO biz.ai_cache (cache_type, site_id, target_id, result_json, - triggered_by, score, expires_at, status) - VALUES (%s, %s, %s, %s, %s, %s, %s, 'valid') + triggered_by, score, expires_at, status, + runtime_mode, sandbox_instance_id) + VALUES (%s, %s, %s, %s, %s, %s, %s, 'valid', %s, %s) RETURNING id """, ( cache_type, site_id, - target_id, + scoped_target_id, json.dumps(result_json, ensure_ascii=False), triggered_by, score, expires_at, + runtime_mode, + sandbox_instance_id, ), ) row = cur.fetchone() @@ -158,7 +188,7 @@ class AICacheService: # 写入成功后清理超限记录 try: - deleted = self._cleanup_excess(cache_type, site_id, target_id) + deleted = self._cleanup_excess(cache_type, site_id, scoped_target_id) if deleted > 0: logger.info( "清理超限缓存: cache_type=%s site_id=%s target_id=%s 删除=%d", @@ -183,15 +213,19 @@ class AICacheService: """写入 generating 状态占位记录，返回 id。完成后调用 finalize_cache 更新。""" conn = get_connection() try: + runtime_mode, sandbox_instance_id, scoped_target_id = self._runtime_scope( + site_id, target_id, conn + ) with conn.cursor() as cur: cur.execute( """ INSERT INTO biz.ai_cache - (cache_type, site_id, target_id, result_json, status, triggered_by) - VALUES (%s, %s, %s, '{}', 'generating', %s) + (cache_type, site_id, target_id, result_json, status, triggered_by, + runtime_mode, sandbox_instance_id) + VALUES (%s, %s, %s, '{}', 'generating', %s, %s, %s) RETURNING id """, - (cache_type, site_id, target_id, triggered_by), + (cache_type, site_id, scoped_target_id, triggered_by, runtime_mode, sandbox_instance_id), ) row = cur.fetchone() conn.commit() diff --git a/apps/backend/app/ai/dashscope_client.py b/apps/backend/app/ai/dashscope_client.py index 3a3e00b..ad4fa9f 100644 --- a/apps/backend/app/ai/dashscope_client.py +++ b/apps/backend/app/ai/dashscope_client.py @@ -28,6 +28,44 @@ from app.ai.exceptions import ( logger = logging.getLogger(__name__) +def _field_value(source: Any, key: str, default: Any = None) -> Any: + """兼容 dict、DashScope DictMixin 和普通对象取字段。""" + if isinstance(source, dict): + return source.get(key, default) + return getattr(source, key, default) + + +def _safe_int(value: Any) -> int: + """把 token 字段安全转换为 int，异常值按 0 处理。""" + try: + return int(value or 0) + except (TypeError, ValueError): + return 0 + + +def _extract_tokens_used(usage: Any) -> int: + """从 DashScope usage 多种结构中提取 tokens_used。""" + if not usage: + return 0 + + models = _field_value(usage, "models") + if models: + total = 0 + for model_usage in models: + total += _safe_int(_field_value(model_usage, "input_tokens")) + total += _safe_int(_field_value(model_usage, "output_tokens")) + return total + + total_tokens = _field_value(usage, "total_tokens") + if total_tokens is not None: + return _safe_int(total_tokens) + + return ( + _safe_int(_field_value(usage, "input_tokens")) + + _safe_int(_field_value(usage, "output_tokens")) + ) + + class DashScopeClient: """DashScope Application API 统一封装层。 @@ -54,22 +92,28 @@ class DashScopeClient: prompt: str, session_id: str | None = None, biz_params: dict | None = None, - ) -> AsyncGenerator[str, None]: - """App1 流式调用。 + ) -> AsyncGenerator[tuple[str, str | None], None]: + """App1 流式调用，支持 multi-turn session_id 透传。 在线程中消费同步迭代器，通过 asyncio.Queue 桥接到 async generator。 - 错误通过 queue 传递给调用方。 + 每个 yield 返回 (text_chunk, session_id_or_none) 元组： + - 首次调用（传入 session_id=None）时，百炼在流中会返回新 session_id， + 应由调用方在流结束后回写 DB。 + - 后续调用传入 DB 中的 session_id 后，百炼自动关联历史上下文， + 返回的 session_id 通常一致。 Args: app_id: 百炼应用 ID prompt: 用户输入 - session_id: 百炼 session_id（多轮对话） + session_id: 百炼 session_id；首次对话传 None biz_params: 业务参数（如 user_prompt_params） Yields: - 文本 chunk + (text_chunk, session_id_or_none) 元组。 + text_chunk 为空字符串时（例如仅承载 session_id 的心跳 chunk）， + 调用方应忽略文本但保留 session_id。 """ - queue: asyncio.Queue[str | BaseException | None] = asyncio.Queue() + queue: asyncio.Queue[tuple[str, str | None] | BaseException | None] = asyncio.Queue() loop = asyncio.get_running_loop() def _consume_in_thread() -> None: @@ -91,10 +135,17 @@ class DashScopeClient: response = Application.call(**call_kwargs) for chunk in response: if chunk.status_code == 200: - text = chunk.output.get("text", "") - if text: + output = chunk.output if hasattr(chunk, "output") else {} + if isinstance(output, dict): + text = output.get("text", "") or "" + new_sid = output.get("session_id") + else: + text = getattr(output, "text", "") or "" + new_sid = getattr(output, "session_id", None) + # 文本或 session_id 任一非空都推入（心跳 chunk 也传出 session_id） + if text or new_sid: asyncio.run_coroutine_threadsafe( - queue.put(text), loop + queue.put((text, new_sid)), loop ) else: # 非 200 状态码，构造异常传递给调用方 @@ -180,16 +231,12 @@ class DashScopeClient: raw_text = output.text or "" # 提取 tokens_used + # DashScope Application.call() 返回的 usage 实际结构（2026-04 验证）： + # ApplicationUsage(models=[ApplicationModelUsage(model_id, input_tokens, output_tokens)]) + # 旧代码只处理 dict / total_tokens 两种分支，导致该嵌套结构下 tokens_used 恒为 0 tokens_used = 0 if hasattr(response, "usage") and response.usage: - usage = response.usage - if isinstance(usage, dict): - # input_tokens + output_tokens - tokens_used = usage.get("input_tokens", 0) + usage.get( - "output_tokens", 0 - ) - elif hasattr(usage, "total_tokens"): - tokens_used = usage.total_tokens or 0 + tokens_used = _extract_tokens_used(response.usage) # 提取 new_session_id new_session_id: str | None = None diff --git a/apps/backend/app/ai/data_fetchers/assistant_data.py b/apps/backend/app/ai/data_fetchers/assistant_data.py index ebc966a..c293f29 100644 --- a/apps/backend/app/ai/data_fetchers/assistant_data.py +++ b/apps/backend/app/ai/data_fetchers/assistant_data.py @@ -58,10 +58,16 @@ def _fetch_assistant_info_sync(site_id: int, assistant_id: int) -> dict[str, Any conn = get_etl_readonly_connection(site_id) # RLS 隔离 + 语句超时（get_etl_readonly_connection 的 SET LOCAL 在 commit 后失效， # 需在查询事务中重新设置） + # CHANGE 2026-05-02 | 同时下发 app.current_business_date，供 RLS 视图业务日上界裁剪 + from app.services.runtime_context import as_runtime_today_param as _rt_today + _ref_date = _rt_today(site_id) with conn.cursor() as cur: cur.execute( "SET LOCAL app.current_site_id = %s", (str(site_id),) ) + cur.execute( + "SET LOCAL app.current_business_date = %s", (_ref_date.isoformat(),) + ) cur.execute( "SET LOCAL statement_timeout = %s", (f"{FDW_QUERY_TIMEOUT_SEC * 1000}",), @@ -86,11 +92,12 @@ def _fetch_assistant_info_sync(site_id: int, assistant_id: int) -> dict[str, Any level = row[1] or "" hire_date = row[2] - # 计算工龄 + # 计算工龄（CHANGE 2026-05-02 | 用 business_date 替代 today，沙箱按当时工龄） + from app.services.runtime_context import as_runtime_today_param + ref_date = as_runtime_today_param(site_id) tenure_months = 0 if hire_date and isinstance(hire_date, date): - today = date.today() - tenure_months = (today.year - hire_date.year) * 12 + (today.month - hire_date.month) + tenure_months = (ref_date.year - hire_date.year) * 12 + (ref_date.month - hire_date.month) # 绩效数据 # ⚠️ 列名映射: monthly_customers 不存在（用 0 占位），performance_tier→tier_name @@ -184,10 +191,16 @@ def _fetch_service_history_sync( conn = get_etl_readonly_connection(site_id) # RLS 隔离 + 语句超时（get_etl_readonly_connection 的 SET LOCAL 在 commit 后失效， # 需在查询事务中重新设置） + # CHANGE 2026-05-02 | 同时下发 app.current_business_date，供 RLS 视图业务日上界裁剪 + from app.services.runtime_context import as_runtime_today_param as _rt_today2 + _ref_date_outer = _rt_today2(site_id) with conn.cursor() as cur: cur.execute( "SET LOCAL app.current_site_id = %s", (str(site_id),) ) + cur.execute( + "SET LOCAL app.current_business_date = %s", (_ref_date_outer.isoformat(),) + ) cur.execute( "SET LOCAL statement_timeout = %s", (f"{FDW_QUERY_TIMEOUT_SEC * 1000}",), @@ -197,6 +210,9 @@ def _fetch_service_history_sync( # is_trash=false→is_delete=0, service_date→create_time, # duration_minutes→real_use_seconds/60, items_sum→ledger_amount, # room_name→site_table_id, is_pd→(order_assistant_type=1) + # CHANGE 2026-05-02 | 用 business_date 替代 CURRENT_DATE，沙箱不读「未来」服务记录 + from app.services.runtime_context import as_runtime_today_param + ref_date = as_runtime_today_param(site_id) cur.execute( """ SELECT @@ -209,10 +225,11 @@ def _fetch_service_history_sync( WHERE site_assistant_id = %s AND tenant_member_id = %s AND is_delete = 0 - AND create_time >= (CURRENT_DATE - INTERVAL '%s months') + AND create_time >= (%s::date - (INTERVAL '1 month' * %s)) + AND create_time < (%s::date + INTERVAL '1 day') ORDER BY create_time DESC """, - (assistant_id, member_id, months), + (assistant_id, member_id, ref_date, months, ref_date), ) columns = [desc[0] for desc in cur.description] rows = cur.fetchall() diff --git a/apps/backend/app/ai/data_fetchers/member_data.py b/apps/backend/app/ai/data_fetchers/member_data.py index 9fc8939..5658e6b 100644 --- a/apps/backend/app/ai/data_fetchers/member_data.py +++ b/apps/backend/app/ai/data_fetchers/member_data.py @@ -63,16 +63,27 @@ def _fetch_member_consumption_data_sync( member_id: int, months: int, ) -> dict[str, Any]: - """同步实现：在单个 FDW 连接上串行执行多个查询。""" + """同步实现：在单个 FDW 连接上串行执行多个查询。 + + CHANGE 2026-05-02 | 所有窗口查询都按业务日上界裁剪， + sandbox 模式下不再读取 sandbox_date 之后的真实消费 / 到店。 + """ + from app.services.runtime_context import as_runtime_today_param + conn = None try: conn = get_etl_readonly_connection(site_id) + ref_date = as_runtime_today_param(site_id) # RLS 隔离 + 语句超时（get_etl_readonly_connection 的 SET LOCAL 在 commit 后失效， # 需在查询事务中重新设置） + # CHANGE 2026-05-02 | 同时下发 app.current_business_date，供 RLS 视图业务日上界裁剪 with conn.cursor() as cur: cur.execute( "SET LOCAL app.current_site_id = %s", (str(site_id),) ) + cur.execute( + "SET LOCAL app.current_business_date = %s", (ref_date.isoformat(),) + ) cur.execute( "SET LOCAL statement_timeout = %s", (f"{FDW_QUERY_TIMEOUT_SEC * 1000}",), # 毫秒 @@ -82,7 +93,7 @@ def _fetch_member_consumption_data_sync( nickname = _query_member_nickname(conn, member_id) # 2. 消费记录（台桌结账 + 商城订单） - records, total_count = _query_consumption_records(conn, member_id, months) + records, total_count = _query_consumption_records(conn, member_id, months, ref_date) # 3. 会员卡明细 cards = _query_member_cards(conn, member_id) @@ -91,7 +102,7 @@ def _fetch_member_consumption_data_sync( balance_info = _query_balance_summary(conn, member_id) # 5. 到店数据 - visit_info = _query_visit_info(conn, member_id) + visit_info = _query_visit_info(conn, member_id, ref_date) result: dict[str, Any] = { "member_nickname": nickname, @@ -145,7 +156,7 @@ def _query_member_nickname(conn: Any, member_id: int) -> str: def _query_consumption_records( - conn: Any, member_id: int, months: int + conn: Any, member_id: int, months: int, ref_date: date ) -> tuple[list[dict], int]: """从 app.v_dwd_settlement_head + app.v_dwd_table_fee_log 获取消费记录。 @@ -153,6 +164,7 @@ def _query_consumption_records( ⚠️ 费用拆分字段（table_charge_money, assistant_pd/cx_money）在 settlement_head 上。 ⚠️ table_fee_log 提供台桌时长（real_table_use_seconds）和桌台ID（site_table_id）。 ⚠️ 列名映射: settle_date→create_time, settle_id→order_settle_id, sale_amount→ledger_amount。 + CHANGE 2026-05-02 | 用 ref_date（业务日）替代 CURRENT_DATE，沙箱不读「未来」消费。 返回 (records, total_count)。 """ with conn.cursor() as cur: @@ -163,9 +175,10 @@ def _query_consumption_records( FROM app.v_dwd_settlement_head sh WHERE sh.member_id = %s AND sh.settle_type IN (1, 3) - AND sh.create_time >= (CURRENT_DATE - INTERVAL '%s months') + AND sh.create_time >= (%s::date - (INTERVAL '1 month' * %s)) + AND sh.create_time < (%s::date + INTERVAL '1 day') """, - (member_id, months), + (member_id, ref_date, months, ref_date), ) total_count = cur.fetchone()[0] @@ -208,11 +221,12 @@ def _query_consumption_records( ) coaches ON true WHERE sh.member_id = %s AND sh.settle_type IN (1, 3) - AND sh.create_time >= (CURRENT_DATE - INTERVAL '%s months') + AND sh.create_time >= (%s::date - (INTERVAL '1 month' * %s)) + AND sh.create_time < (%s::date + INTERVAL '1 day') ORDER BY sh.create_time DESC LIMIT %s """, - (member_id, months, MAX_CONSUMPTION_RECORDS), + (member_id, ref_date, months, ref_date, MAX_CONSUMPTION_RECORDS), ) columns = [desc[0] for desc in cur.description] rows = cur.fetchall() @@ -294,9 +308,10 @@ def _query_balance_summary(conn: Any, member_id: int) -> dict: } -def _query_visit_info(conn: Any, member_id: int) -> dict: +def _query_visit_info(conn: Any, member_id: int, ref_date: date) -> dict: """从 app.v_dws_member_visit_detail 获取到店数据，推算预计到店日期。 ⚠️ 列名映射: last_visit_date→MAX(visit_date), avg_visit_interval_days 需从明细计算。 + CHANGE 2026-05-02 | 仅取 ref_date 及之前的到店明细，days_since 按 ref_date 计算。 """ with conn.cursor() as cur: # 获取最近到店日期和平均到店间隔 @@ -307,6 +322,7 @@ def _query_visit_info(conn: Any, member_id: int) -> dict: LAG(visit_date) OVER (ORDER BY visit_date) AS prev_visit FROM app.v_dws_member_visit_detail WHERE member_id = %s + AND visit_date <= %s ) SELECT MAX(visit_date) AS last_visit_date, @@ -314,7 +330,7 @@ def _query_visit_info(conn: Any, member_id: int) -> dict: FROM visits WHERE prev_visit IS NOT NULL """, - (member_id,), + (member_id, ref_date), ) row = cur.fetchone() @@ -323,8 +339,7 @@ def _query_visit_info(conn: Any, member_id: int) -> dict: last_visit = row[0] avg_interval = row[1] - today = date.today() - days_since = (today - last_visit).days if isinstance(last_visit, date) else None + days_since = (ref_date - last_visit).days if isinstance(last_visit, date) else None expected = None if avg_interval and last_visit: diff --git a/apps/backend/app/ai/data_fetchers/page_context.py b/apps/backend/app/ai/data_fetchers/page_context.py index 4bc0f9c..589ba5d 100644 --- a/apps/backend/app/ai/data_fetchers/page_context.py +++ b/apps/backend/app/ai/data_fetchers/page_context.py @@ -352,7 +352,9 @@ def _text_board_finance( "SET LOCAL statement_timeout = %s", (f"{FDW_QUERY_TIMEOUT_SEC * 1000}",), ) - # 简化查询：获取汇总数据 + # 简化查询：获取汇总数据（CHANGE 2026-05-02 | 用 business_date 替代 CURRENT_DATE） + from app.services.runtime_context import as_runtime_today_param + _ref_date = as_runtime_today_param(site_id) cur.execute( """ SELECT @@ -361,8 +363,10 @@ def _text_board_finance( COALESCE(AVG(items_sum), 0) AS avg_revenue FROM app.v_dwd_settlement_head WHERE settle_type IN (1, 3) - AND settle_date >= (CURRENT_DATE - INTERVAL '1 month') + AND settle_date >= (%s::date - INTERVAL '1 month') + AND settle_date <= %s::date """, + (_ref_date, _ref_date), ) row = cur.fetchone() etl_conn.commit() @@ -399,7 +403,9 @@ def _text_board_customer( "SET LOCAL statement_timeout = %s", (f"{FDW_QUERY_TIMEOUT_SEC * 1000}",), ) - # Top 10 客户 + # Top 10 客户（CHANGE 2026-05-02 | 用 business_date 替代 CURRENT_DATE） + from app.services.runtime_context import as_runtime_today_param + _ref_date = as_runtime_today_param(site_id) cur.execute( """ SELECT @@ -410,11 +416,13 @@ def _text_board_customer( ON dm.member_id = sh.member_id AND dm.scd2_is_current = 1 WHERE sh.settle_type IN (1, 3) AND sh.member_id > 0 - AND sh.settle_date >= (CURRENT_DATE - INTERVAL '1 month') + AND sh.settle_date >= (%s::date - INTERVAL '1 month') + AND sh.settle_date <= %s::date GROUP BY dm.nickname ORDER BY total_consumption DESC LIMIT 10 """, + (_ref_date, _ref_date), ) rows = cur.fetchall() etl_conn.commit() @@ -452,6 +460,9 @@ def _text_board_coach( "SET LOCAL statement_timeout = %s", (f"{FDW_QUERY_TIMEOUT_SEC * 1000}",), ) + # CHANGE 2026-05-02 | 用 business_date 替代 CURRENT_DATE + from app.services.runtime_context import as_runtime_today_param + _ref_date = as_runtime_today_param(site_id) cur.execute( """ SELECT @@ -462,11 +473,13 @@ def _text_board_coach( JOIN app.v_dim_assistant da ON da.assistant_id = sl.site_assistant_id WHERE sl.is_delete = 0 - AND sl.create_time >= (CURRENT_DATE - INTERVAL '1 month') + AND sl.create_time >= (%s::date - INTERVAL '1 month') + AND sl.create_time < (%s::date + INTERVAL '1 day') GROUP BY da.nickname ORDER BY service_count DESC LIMIT 10 """, + (_ref_date, _ref_date), ) rows = cur.fetchall() etl_conn.commit() @@ -590,6 +603,9 @@ def _text_customer_service_records( "SET LOCAL statement_timeout = %s", (f"{FDW_QUERY_TIMEOUT_SEC * 1000}",), ) + # CHANGE 2026-05-02 | 仅取业务日及之前的服务记录，沙箱不读「未来」 + from app.services.runtime_context import as_runtime_today_param + _ref_date = as_runtime_today_param(site_id) cur.execute( """ SELECT @@ -599,10 +615,11 @@ def _text_customer_service_records( site_table_id FROM app.v_dwd_assistant_service_log WHERE tenant_member_id = %s AND is_delete = 0 + AND create_time < (%s::date + INTERVAL '1 day') ORDER BY create_time DESC LIMIT 10 """, - (member_id,), + (member_id, _ref_date), ) rows = cur.fetchall() etl_conn.commit() diff --git a/apps/backend/app/ai/dispatcher.py b/apps/backend/app/ai/dispatcher.py index cba9905..87e611b 100644 --- a/apps/backend/app/ai/dispatcher.py +++ b/apps/backend/app/ai/dispatcher.py @@ -207,6 +207,25 @@ class AIDispatcher: # 内存 trigger_job 计数器（DB 迁移完成后改为 INSERT RETURNING id） self._next_job_id = 1 + self._running_tasks: dict[int, asyncio.Task] = {} + self._running_task_sites: dict[int, int] = {} + + def _forget_running_task(self, job_id: int) -> None: + self._running_tasks.pop(job_id, None) + self._running_task_sites.pop(job_id, None) + + def cancel_running(self, site_id: int) -> int: + """取消当前进程内指定门店未完成的 AI 调用链。""" + cancelled = 0 + for job_id, task in list(self._running_tasks.items()): + if self._running_task_sites.get(job_id) != site_id: + continue + if task.done(): + self._forget_running_task(job_id) + continue + task.cancel() + cancelled += 1 + return cancelled # ── 统一事件入口 ───────────────────────────────────── @@ -242,7 +261,10 @@ class AIDispatcher: self._dedup_set.add(dedup_key) # 后台异步执行调用链，不阻塞返回 - asyncio.create_task(self._execute_chain(job_id, event)) + task = asyncio.create_task(self._execute_chain(job_id, event)) + self._running_tasks[job_id] = task + self._running_task_sites[job_id] = event.site_id + task.add_done_callback(lambda _task, _job_id=job_id: self._forget_running_task(_job_id)) return job_id # ── 调用链分发 ─────────────────────────────────────── @@ -278,6 +300,10 @@ class AIDispatcher: await asyncio.wait_for(handler(event), timeout=chain_timeout) logger.info("调用链完成: job_id=%d event_type=%s", job_id, event.event_type) _update_trigger_job_status(job_id, "completed", set_finished=True) + except asyncio.CancelledError: + logger.warning("调用链已取消: job_id=%d event_type=%s", job_id, event.event_type) + _update_trigger_job_status(job_id, "cancelled", error_message="业务运行上下文切换取消", set_finished=True) + raise except asyncio.TimeoutError: logger.error("调用链超时: job_id=%d event_type=%s", job_id, event.event_type) _update_trigger_job_status(job_id, "failed", error_message="调用链超时", set_finished=True) diff --git a/apps/backend/app/ai/event_bus.py b/apps/backend/app/ai/event_bus.py new file mode 100644 index 0000000..0ad3ff7 --- /dev/null +++ b/apps/backend/app/ai/event_bus.py @@ -0,0 +1,123 @@ +"""AI 事件广播总线（in-process pub/sub）。 + +支持按 site_id 订阅的异步事件分发，用于： +- Phase 1.4：AI 缓存主动失效 / 更新通知 → admin-web、小程序刷新 +- Phase 3.1：AI 告警实时推送（告警发生 / 确认 / 忽略） + +设计要点： +- 仿 TaskExecutor.subscribe/unsubscribe 模式（单进程共享） +- 每个订阅者独立 asyncio.Queue，互不干扰 +- 订阅必须指定 site_id（全局订阅需显式 site_id=None） +- publish 异步写入所有订阅者 queue；端点侧通过 get() 消费 +""" + +from __future__ import annotations + +import asyncio +import logging +from dataclasses import dataclass, field +from typing import Any + +logger = logging.getLogger(__name__) + + +@dataclass +class AIEvent: + """统一事件结构。 + + type 示例： + - cache_updated — 新缓存写入 + - cache_invalidated — 缓存主动失效 + - alert_created — 新告警（Phase 3.1） + - alert_updated — 告警状态变更（Phase 3.1） + """ + + type: str + site_id: int | None + payload: dict[str, Any] = field(default_factory=dict) + + +class EventBus: + """单进程事件广播总线。""" + + def __init__(self) -> None: + # {site_id | None: [queue, ...]} None 表示全局订阅（收所有 site 事件） + self._subscribers: dict[int | None, list[asyncio.Queue[AIEvent | None]]] = {} + self._lock = asyncio.Lock() + + async def subscribe(self, site_id: int | None) -> asyncio.Queue[AIEvent | None]: + """订阅事件流，返回独立 asyncio.Queue。 + + site_id=None 表示订阅全部门店事件（admin-web 全局监控用）。 + site_id= 表示仅订阅该门店事件（小程序或单门店后台）。 + + unsubscribe 时需将返回的 queue 作为参数传入。 + """ + queue: asyncio.Queue[AIEvent | None] = asyncio.Queue() + async with self._lock: + self._subscribers.setdefault(site_id, []).append(queue) + return queue + + async def unsubscribe( + self, site_id: int | None, queue: asyncio.Queue[AIEvent | None] + ) -> None: + """解除订阅，从订阅者列表移除 queue。""" + async with self._lock: + subs = self._subscribers.get(site_id, []) + try: + subs.remove(queue) + except ValueError: + pass + if not subs: + self._subscribers.pop(site_id, None) + + def publish(self, event: AIEvent) -> int: + """同步 publish 事件，返回送达的订阅者数。 + + 可从任意线程 / sync 上下文调用（如 dispatcher._write_cache）。 + 内部使用 run_coroutine_threadsafe 线程安全写入 queue。 + """ + targets = self._collect_targets(event.site_id) + sent = 0 + for queue in targets: + try: + # 优先同步调用 put_nowait（最常见：同一 running loop） + queue.put_nowait(event) + sent += 1 + except RuntimeError: + # 无 running loop 场景极少，跳过 + logger.debug("publish 无 running loop：跳过 queue") + return sent + + def _collect_targets(self, site_id: int | None) -> list[asyncio.Queue[AIEvent | None]]: + """收集要推送的订阅者列表：该 site_id 的订阅者 + 全局订阅者。""" + targets: list[asyncio.Queue[AIEvent | None]] = [] + if site_id is not None: + targets.extend(self._subscribers.get(site_id, [])) + targets.extend(self._subscribers.get(None, [])) + return targets + + async def close_all(self) -> None: + """结束时给所有订阅者发哨兵 None，通知连接关闭。""" + async with self._lock: + all_queues = [q for subs in self._subscribers.values() for q in subs] + self._subscribers.clear() + for q in all_queues: + try: + q.put_nowait(None) + except Exception: + pass + + +# ── 单例 ────────────────────────────────────────────────── + + +_bus: EventBus | None = None + + +def get_event_bus() -> EventBus: + """获取全局 EventBus 单例。进程启动时按需创建。""" + global _bus + if _bus is None: + _bus = EventBus() + return _bus diff --git a/apps/backend/app/ai/prompts/app2_finance_prompt.py b/apps/backend/app/ai/prompts/app2_finance_prompt.py index b29fbb0..128af3d 100644 --- a/apps/backend/app/ai/prompts/app2_finance_prompt.py +++ b/apps/backend/app/ai/prompts/app2_finance_prompt.py @@ -1,145 +1,873 @@ -"""应用 2 财务洞察 Prompt 模板。 +"""应用 2 财务洞察 Prompt 拼装。 -构建包含当期和上期收入结构的完整 Prompt，供百炼 API 生成财务洞察。 +cron 每日 10:00 预热触发，对所有筛选组合（时间 × 区域）生成洞察。 +- 数据源：board_service.get_finance_board(time, area, compare=1, site_id) +- 筛选维度：8 个时间维度 × 9 个区域 = 72 组合 +- 输出字段：insights 数组（seq + title + body） +- system prompt 在百炼控制台配置 -收入字段映射（严格遵守 items_sum 口径）： -- table_fee = table_charge_money（台费） -- assistant_pd = assistant_pd_money（陪打费） -- assistant_cx = assistant_cx_money（超休费） -- goods = goods_money（商品收入） -- recharge = 充值 pay_amount settle_type=5（充值收入） - -禁止使用 consume_money，统一使用： -items_sum = table_charge_money + goods_money + assistant_pd_money - + assistant_cx_money + electricity_money +Prompt 中 board_data 字段名会自动翻译为中文（KEY_TRANSLATIONS）， +目的：减少 AI 理解英文变量的成本，生成的洞察正文可读性更强。 """ from __future__ import annotations import json +import logging +from datetime import datetime +from typing import Any +from app.services.board_service import get_finance_board, _calc_date_range, _calc_prev_range -def build_prompt(context: dict) -> list[dict]: - """构建 App2 财务洞察 Prompt 消息列表。 +logger = logging.getLogger(__name__) - Args: - context: 包含以下字段： - - site_id: int，门店 ID - - time_dimension: str，时间维度编码 - - current_data: dict，当期数据 - - previous_data: dict，上期数据 +# App2 时间维度 → board_service 时间枚举 +DIMENSION_MAP: dict[str, str] = { + "this_month": "month", + "last_month": "lastMonth", + "this_week": "week", + "last_week": "lastWeek", + "this_quarter": "quarter", + "last_quarter": "lastQuarter", + "last_3_months": "last_3m", + "last_6_months": "last_6m", +} - Returns: - messages 列表（system + user），供 BailianClient.chat_json 调用 - """ - site_id = context.get("site_id", 0) - time_dimension = context.get("time_dimension", "") - current_data = context.get("current_data", {}) - previous_data = context.get("previous_data", {}) - - system_content = _build_system_content( - site_id=site_id, - time_dimension=time_dimension, - current_data=current_data, - previous_data=previous_data, - ) - - user_content = ( - f"请根据以上数据，为门店 {site_id} 生成 {_dimension_label(time_dimension)} 的财务洞察分析。" - "以 JSON 格式返回，包含 insights 数组，每项含 seq（序号）、title（标题）、body（正文）。" - ) - - return [ - {"role": "system", "content": json.dumps(system_content, ensure_ascii=False)}, - {"role": "user", "content": user_content}, - ] - - -def _build_system_content( - *, - site_id: int, - time_dimension: str, - current_data: dict, - previous_data: dict, -) -> dict: - """构建 system prompt JSON 结构。""" - return { - "task": ( - "你是台球门店的财务分析 AI 助手。" - "根据提供的当期和上期经营数据，生成结构化的财务洞察。" - "分析维度包括：收入结构变化、各收入项占比、环比趋势、异常波动。" - "输出 JSON 格式：{\"insights\": [{\"seq\": 1, \"title\": \"...\", \"body\": \"...\"}]}" - ), - "data": { - "site_id": site_id, - "time_dimension": time_dimension, - "time_dimension_label": _dimension_label(time_dimension), - "current_period": _build_period_data(current_data), - "previous_period": _build_period_data(previous_data), - }, - "reference": { - "field_mapping": { - "items_sum": ( - "table_charge_money + goods_money + assistant_pd_money" - " + assistant_cx_money + electricity_money" - ), - "table_fee": "table_charge_money（台费收入）", - "assistant_pd": "assistant_pd_money（陪打费）", - "assistant_cx": "assistant_cx_money（超休费）", - "goods": "goods_money（商品收入）", - "recharge": "充值 pay_amount（settle_type=5，充值收入）", - "electricity": "electricity_money（电费，当前未启用，全为 0）", - }, - "rules": [ - "统一使用 items_sum 口径计算营收总额", - "助教费用必须拆分为 assistant_pd_money（陪打）和 assistant_cx_money（超休）", - "支付渠道恒等式：balance_amount = recharge_card_amount + gift_card_amount", - "金额单位：元（CNY），保留两位小数", - ], - }, - } - - -def _build_period_data(data: dict) -> dict: - """构建单期数据结构，确保字段名遵守 items_sum 口径。""" - return { - # 收入结构（items_sum 口径） - "table_charge_money": data.get("table_charge_money", 0), - "goods_money": data.get("goods_money", 0), - "assistant_pd_money": data.get("assistant_pd_money", 0), - "assistant_cx_money": data.get("assistant_cx_money", 0), - "electricity_money": data.get("electricity_money", 0), - # 充值收入 - "recharge_income": data.get("recharge_income", 0), - # 储值资产 - "balance_pay": data.get("balance_pay", 0), - "recharge_card_pay": data.get("recharge_card_pay", 0), - "gift_card_pay": data.get("gift_card_pay", 0), - # 费用汇总 - "discount_amount": data.get("discount_amount", 0), - "adjust_amount": data.get("adjust_amount", 0), - # 平台结算 - "platform_settlement_amount": data.get("platform_settlement_amount", 0), - "groupbuy_pay_amount": data.get("groupbuy_pay_amount", 0), - # 汇总 - "order_count": data.get("order_count", 0), - "member_count": data.get("member_count", 0), - } - - -# 时间维度编码 → 中文标签 -_DIMENSION_LABELS: dict[str, str] = { +DIMENSION_LABELS: dict[str, str] = { "this_month": "本月", "last_month": "上月", "this_week": "本周", "last_week": "上周", - "last_3_months": "近三个月", "this_quarter": "本季度", "last_quarter": "上季度", - "last_6_months": "近六个月", + "last_3_months": "近三个月（不含本月）", + "last_6_months": "近六个月（不含本月）", +} + +# 区域枚举与中文标签（与 miniprogram/board-finance.ts areaOptions 对齐） +AREA_OPTIONS: tuple[str, ...] = ( + "all", "hall", "hallA", "hallB", "hallC", + "vip", "snooker", "mahjong", "ktv", +) + +AREA_LABELS: dict[str, str] = { + "all": "全部区域", + "hall": "大厅", + "hallA": "A区", + "hallB": "B区", + "hallC": "C区", + "vip": "台球包厢", + "snooker": "斯诺克", + "mahjong": "麻将房", + "ktv": "团建房", +} + +# 业务字段 → 中文名。覆盖 board_service 返回的所有层级字段。 +# 只做键名翻译，不改变值与结构；未命中的键原样保留。 +KEY_TRANSLATIONS: dict[str, str] = { + # 顶层板块 + "overview": "经营一览", + "recharge": "预收资产", + "revenue": "应计收入确认", + "cashflow": "现金流入", + "expense": "现金流出", + "coach_analysis": "助教分析", + + # 经营一览 + "occurrence": "发生额", + "discount": "总优惠", + "discount_rate": "优惠率", + "confirmed_revenue": "成交收入", + "cash_in": "现金流入", + "cash_out": "现金流出", + "cash_balance": "现金结余", + "balance_rate": "结余率", + + # 预收资产 + "actual_income": "储值卡充值实收", + "first_charge": "首充", + "renew_charge": "续费", + "consumed": "储值卡消耗", + "card_balance": "储值卡总余额", + "all_card_balance": "全类别卡余额合计", + "gift_rows": "赠送卡矩阵", + "liquor": "酒水卡", + "table_fee": "台费卡", + "voucher": "抵用券", + + # 应计收入确认 + "total_occurrence": "发生额合计", + "discount_total": "优惠合计", + "confirmed_total": "确认收入合计", + "structure_rows": "收入结构", + "price_items": "价目明细", + "discount_items": "优惠明细", + "channel_items": "渠道明细", + "booked": "入账金额", + "booked_compare": "入账环比", + + # 现金流入/流出 + "consume_items": "消费收款项", + "recharge_items": "充值收款项", + "operation_items": "运营支出", + "fixed_items": "固定支出", + "coach_items": "助教支出", + "platform_items": "平台支出", + + # 助教分析 + "basic": "基础助教", + "incentive": "激励助教", + "total_pay": "合计薪酬", + "total_share": "合计分成", + "avg_hourly": "平均时薪", + "level": "级别", + "pay": "薪酬", + "share": "分成", + "hourly": "时薪", + "rows": "明细", + + # 通用元素 + "label": "名称", + "amount": "金额", + "desc": "说明", + "total": "合计", + "value": "数值", + "compare": "环比", + "id": "编号", + + # 环比后缀（小程序约定） + "occurrence_compare": "发生额环比", + "occurrence_down": "发生额是否下降", + "occurrence_flat": "发生额是否持平", + "discount_compare": "总优惠环比", + "discount_down": "总优惠是否下降", + "discount_flat": "总优惠是否持平", + "discount_rate_compare": "优惠率环比", + "discount_rate_down": "优惠率是否下降", + "discount_rate_flat": "优惠率是否持平", + "confirmed_revenue_compare": "成交收入环比", + "confirmed_revenue_down": "成交收入是否下降", + "confirmed_revenue_flat": "成交收入是否持平", + "cash_in_compare": "现金流入环比", + "cash_in_down": "现金流入是否下降", + "cash_in_flat": "现金流入是否持平", + "cash_out_compare": "现金流出环比", + "cash_out_down": "现金流出是否下降", + "cash_out_flat": "现金流出是否持平", + "cash_balance_compare": "现金结余环比", + "cash_balance_down": "现金结余是否下降", + "cash_balance_flat": "现金结余是否持平", + "balance_rate_compare": "结余率环比", + "balance_rate_down": "结余率是否下降", + "balance_rate_flat": "结余率是否持平", + "actual_income_compare": "储值卡充值实收环比", + "actual_income_down": "储值卡充值实收是否下降", + "first_charge_compare": "首充环比", + "first_charge_down": "首充是否下降", + "renew_charge_compare": "续费环比", + "renew_charge_down": "续费是否下降", + "consumed_compare": "储值卡消耗环比", + "consumed_down": "储值卡消耗是否下降", + "card_balance_compare": "储值卡总余额环比", + "card_balance_down": "储值卡总余额是否下降", + "all_card_balance_compare": "全类别卡余额合计环比", + "all_card_balance_down": "全类别卡余额合计是否下降", + "total_compare": "合计环比", + "total_down": "合计是否下降", + "total_flat": "合计是否持平", + "total_pay_compare": "合计薪酬环比", + "total_pay_down": "合计薪酬是否下降", + "total_share_compare": "合计分成环比", + "total_share_down": "合计分成是否下降", + "avg_hourly_compare": "平均时薪环比", + "avg_hourly_flat": "平均时薪是否持平", + "pay_compare": "薪酬环比", + "pay_down": "薪酬是否下降", + "share_compare": "分成环比", + "share_down": "分成是否下降", + "hourly_compare": "时薪环比", + "hourly_flat": "时薪是否持平", + + # 赠送卡矩阵 + "wine": "酒水", + "table": "台费", + "coupon": "抵用券", + + # 元数据 + "down": "是否下降", + "flat": "是否持平", } -def _dimension_label(dimension: str) -> str: - """将时间维度编码转为中文标签。""" - return _DIMENSION_LABELS.get(dimension, dimension) +# 裁剪时丢弃的"冗余"字段：_down / _flat 布尔元数据（*_compare 字符串已携带符号） +_DROP_SUFFIX = ("_down", "_flat") + +# 行级明细字段：展示用，AI 洞察不需要 +_DROP_DETAIL_KEYS = { + "structure_rows", "price_items", "channel_items", "gift_rows", + "discount_items", # 2026-04-22：升顶层"优惠构成"后，明细源从 revenue 里 drop 去重 +} + + +def _is_drop_key(k: str) -> bool: + if not isinstance(k, str): + return False + if k in _DROP_DETAIL_KEYS: + return True + return k.endswith(_DROP_SUFFIX) + + +def _slim(data: Any) -> Any: + """递归裁剪：drop 明细 + _down/_flat + None 值。""" + if isinstance(data, dict): + out = {} + for k, v in data.items(): + if _is_drop_key(k): + continue + slim_v = _slim(v) + if slim_v is None: + continue + out[k] = slim_v + return out if out else None + if isinstance(data, list): + return [_slim(item) for item in data] + return data + + +def _pct(numerator: float, denominator: float) -> float: + """百分比（小数），分母 0 返回 0。保留 4 位便于 AI 读取。""" + if not denominator: + return 0.0 + return round(numerator / denominator, 4) + + +# 日粒度异常检测参数 +_ANOMALY_MIN_DAYS = 7 # 少于 7 天样本不检测（噪声太大） +_ANOMALY_DEVIATION = 0.4 # 偏离"同星期均值" > 40% 标记为异常（2026-04-22 改为同星期基线） +_ANOMALY_MAX_ITEMS = 10 # 最多保留 10 条（按 |偏离度| 降序截断，防 prompt 膨胀） +_ANOMALY_MIN_SAME_WEEKDAY = 2 # 同星期至少 2 天样本才可作基线；不足时回退到整体均值 + +# 星期中文映射（0=Monday） +_WEEKDAY_ZH = ("周一", "周二", "周三", "周四", "周五", "周六", "周日") + +# 行业基线常量（综合商业球房） +# 2026-04-22：移除各类警戒线/健康区间（各球房定位/地段/业态差异大，不宜一刀切）。 +# 仅保留"周中客流规律"这类行业普适的时间分布特征。 +INDUSTRY_BASELINES: dict[str, Any] = { + "周中客流规律": "周五至周日旺季 / 周一最淡 / 周二至周四逐步回升", +} + + +def _fetch_daily_series( + site_id: int, start_date: str, end_date: str, +) -> list[tuple] | None: + """查 [start, end] 日粒度财务流水，一次查完供多个分析函数复用。 + + 返回字段顺序：(stat_date, gross, cash_in, order_count, member_order_count, confirmed) + 过滤全 0 停业日；样本不足时返回 None。 + """ + from app.services.fdw_queries import _fdw_context + from app.database import get_connection + + try: + conn = get_connection() + except Exception: + logger.debug("日粒度查询连接失败", exc_info=True) + return None + + try: + with _fdw_context(conn, site_id) as cur: + cur.execute( + """ + SELECT stat_date, + COALESCE(gross_amount, 0) AS gross, + COALESCE(cash_inflow_total, 0) AS cash_in, + COALESCE(order_count, 0) AS order_count, + COALESCE(member_order_count, 0) AS member_order_count, + COALESCE(confirmed_income, 0) AS confirmed + FROM app.v_dws_finance_daily_summary + WHERE stat_date >= %s::date + AND stat_date <= %s::date + ORDER BY stat_date + """, + (start_date, end_date), + ) + rows = cur.fetchall() + except Exception: + logger.debug("日粒度数据查询失败: site_id=%s", site_id, exc_info=True) + return None + finally: + try: + conn.close() + except Exception: + pass + + active = [ + (r[0], float(r[1]), float(r[2]), int(r[3] or 0), int(r[4] or 0), float(r[5] or 0)) + for r in rows + if float(r[1] or 0) > 0 or float(r[2] or 0) > 0 + ] + return active if active else None + + +_WEEKDAY_MIN_DAYS = 14 # 月初场景：样本 < 14 天时，每个星期最多 1-2 天，"日均"接近单日值，不注入以免 AI 被误导 + + +def _aggregate_by_weekday(series: list[tuple] | None) -> dict | None: + """按星期聚合 7 段日均值（发生额/现金流入/订单数），供 AI 观察周中规律。 + + 要求至少 14 天样本（保证每个星期至少有 2 天），否则返回 None； + 防止月初场景下单日值被包装成"日均"迷惑 AI 做周规律判断。 + """ + if not series or len(series) < _WEEKDAY_MIN_DAYS: + return None + from collections import defaultdict + buckets: dict[int, list[tuple]] = defaultdict(list) + for row in series: + buckets[row[0].weekday()].append(row) + out: dict[str, dict] = {} + for wd in range(7): + rows = buckets.get(wd) or [] + if not rows: + continue + n = len(rows) + out[_WEEKDAY_ZH[wd]] = { + "日均发生额": round(sum(r[1] for r in rows) / n, 2), + "日均现金流入": round(sum(r[2] for r in rows) / n, 2), + "日均订单数": round(sum(r[3] for r in rows) / n, 1), + "营业日数": n, + } + return out or None + + +def _build_unit_economics( + series: list[tuple] | None, + prev_series: list[tuple] | None = None, +) -> dict | None: + """单位经济派生：客单价 / 日均订单数 / 会员订单占比 / 散客订单占比。 + + 口径：全期汇总后再算（避免日均 avg 失真）。 + 客单价取两口径： + - 按成交收入（去除优惠的真实收入单价） — 反映真实收入能力 + - 按发生额（含优惠的账单均值） — 反映顾客端认知的单次消费量级 + 若 prev_series 可用，则附加 _环比 字段避免 AI 推测幻觉。 + """ + if not series: + return None + total_orders = sum(r[3] for r in series) + if total_orders <= 0: + return None + total_member_orders = sum(r[4] for r in series) + total_confirmed = sum(r[5] for r in series) + total_gross = sum(r[1] for r in series) + days = len(series) + + price_confirmed = total_confirmed / total_orders + price_gross = total_gross / total_orders + member_share = total_member_orders / total_orders + daily_orders = total_orders / days + + out: dict[str, Any] = { + "总订单数": total_orders, + "日均订单数": round(daily_orders, 1), + "客单价_按成交收入": round(price_confirmed, 2), + "客单价_按发生额": round(price_gross, 2), + "会员订单数": total_member_orders, + "会员订单占比": round(member_share, 4), + "散客订单数": total_orders - total_member_orders, + "散客订单占比": round((total_orders - total_member_orders) / total_orders, 4), + } + + if prev_series: + prev_orders = sum(r[3] for r in prev_series) + if prev_orders > 0: + prev_days = len(prev_series) + prev_confirmed = sum(r[5] for r in prev_series) + prev_gross = sum(r[1] for r in prev_series) + prev_member = sum(r[4] for r in prev_series) + # 月初场景：上期样本 < 5 天时客单价环比噪声极大（单日波动主导），加标注供 AI 降权引用 + low_sample = prev_days < 5 + + def _pct_change(cur: float, prev: float) -> str: + if prev <= 0: + return "无上期数据" + value = f"{(cur - prev) / prev * 100:+.1f}%" + return f"{value}（上期仅 {prev_days} 天，样本不足仅供参考）" if low_sample else value + + out["客单价_按成交收入_环比"] = _pct_change(price_confirmed, prev_confirmed / prev_orders) + out["客单价_按发生额_环比"] = _pct_change(price_gross, prev_gross / prev_orders) + out["日均订单数_环比"] = _pct_change(daily_orders, prev_orders / prev_days) + out["会员订单占比_环比"] = _pct_change(member_share, prev_member / prev_orders) + return out + + +def _detect_anomaly_days( + site_id: int, start_date: str, end_date: str, + series: list[tuple] | None = None, +) -> list[dict] | None: + """扫描日粒度财务数据，标记偏离同星期均值 > 40% 的异常日。 + + series 可由调用方传入复用，避免重复查 DB。 + """ + if series is None: + series = _fetch_daily_series(site_id, start_date, end_date) + if not series or len(series) < _ANOMALY_MIN_DAYS: + return None + active = series + + # 2026-04-22 改进：按"同星期均值"做基线，比"期均"更贴近业态（周一淡/周末旺） + # 同星期样本 < _ANOMALY_MIN_SAME_WEEKDAY 天时回退到整体均值 + from collections import defaultdict + + def _scan(idx: int, label: str) -> list[dict]: + vals = [row[idx] for row in active] + global_mean = sum(vals) / len(vals) + if global_mean <= 0: + return [] + + # 按 weekday 分组统计均值 + by_weekday: dict[int, list[float]] = defaultdict(list) + for d, *metrics in active: + by_weekday[d.weekday()].append(metrics[idx - 1]) + weekday_mean: dict[int, float] = { + wd: (sum(xs) / len(xs)) for wd, xs in by_weekday.items() + } + + flagged: list[dict] = [] + for d, *metrics in active: + v = metrics[idx - 1] + wd = d.weekday() + same_count = len(by_weekday.get(wd, [])) + # 基线选择：同星期样本 >= 2 用同星期均值，否则用整体均值 + if same_count >= _ANOMALY_MIN_SAME_WEEKDAY and weekday_mean[wd] > 0: + base = weekday_mean[wd] + base_label = f"同{_WEEKDAY_ZH[wd]}均值" + else: + base = global_mean + base_label = "期均" + + deviation = (v - base) / base + if abs(deviation) >= _ANOMALY_DEVIATION: + weekday_zh = _WEEKDAY_ZH[wd] + flagged.append({ + "日期": f"{d} {weekday_zh}", + "指标": label, + "当日": round(v, 2), + "基线": round(base, 2), + "基线类型": base_label, + "偏离": f"{deviation * 100:+.1f}%", + "_abs_dev": abs(deviation), + }) + return flagged + + candidates: list[dict] = _scan(1, "发生额") + _scan(2, "现金流入") + if not candidates: + return None + # 按绝对偏离排序，取 top N，去掉排序用辅助键 + candidates.sort(key=lambda x: x["_abs_dev"], reverse=True) + out = [] + for c in candidates[:_ANOMALY_MAX_ITEMS]: + c.pop("_abs_dev", None) + out.append(c) + return out + + +def _fetch_card_balance_opening(site_id: int, start_date: str) -> float | None: + """取 start_date 前一日的储值卡总余额（作为本期期初余额）。 + + 数据源：etl 库 app.v_dws_finance_recharge_summary（每日快照，total_card_balance 字段）。 + 若前一日无数据（门店刚开业 / 数据缺失），返回 None。 + """ + from app.services.fdw_queries import _fdw_context + from app.database import get_connection + + try: + conn = get_connection() + except Exception: + logger.debug("期初余额查询连接失败", exc_info=True) + return None + + try: + with _fdw_context(conn, site_id) as cur: + cur.execute( + """ + SELECT total_card_balance + FROM app.v_dws_finance_recharge_summary + WHERE stat_date < %s::date + ORDER BY stat_date DESC + LIMIT 1 + """, + (start_date,), + ) + row = cur.fetchone() + except Exception: + logger.debug("期初余额查询失败: site_id=%s", site_id, exc_info=True) + return None + finally: + try: + conn.close() + except Exception: + pass + + if not row or row[0] is None: + return None + return float(row[0]) + + +def _aggregate_expense(expense: dict | None) -> dict | None: + """从 expense 四类明细聚合出顶层金额，便于 AI 直接看四大块支出占比。""" + if not isinstance(expense, dict): + return None + def _sum(key: str) -> float: + items = expense.get(key) or [] + if not isinstance(items, list): + return 0.0 + return round(sum(float(x.get("amount", 0) or 0) for x in items if isinstance(x, dict)), 2) + total = float(expense.get("total", 0) or 0) + if total <= 0: + return None # 全 0 数据对 AI 无意义，直接丢 + return { + "合计": round(total, 2), + "合计环比": expense.get("total_compare") or "持平", + "运营支出": _sum("operation_items"), + "固定支出": _sum("fixed_items"), + "助教支出": _sum("coach_items"), + "平台支出": _sum("platform_items"), + } + + +def _build_discount_kpi(revenue: dict | None, overview: dict | None) -> dict | None: + """把优惠拆成顶层 KPI + 派生指标（占比、贡献率）。 + + AI 数据挖掘视角： + - 按金额排序展示，top1 一眼看出来 + - 每项带 amount / compare / share（占总优惠比） + - 整体带优惠率（discount / occurrence）便于判断利润侵蚀程度 + """ + if not isinstance(revenue, dict): + return None + items = revenue.get("discount_items") or [] + if not isinstance(items, list) or not items: + return None + + total = round(sum(float(x.get("amount", 0) or 0) for x in items if isinstance(x, dict)), 2) + breakdown = [] + for it in items: + if not isinstance(it, dict): + continue + amt = float(it.get("amount", 0) or 0) + row: dict[str, Any] = { + "名称": it.get("label"), + "金额": round(amt, 2), + "占总优惠": _pct(amt, total), + } + if it.get("compare"): + row["环比"] = it["compare"] + breakdown.append(row) + # 按金额从大到小排序 → AI 阅读顺序 = 重要度顺序 + breakdown.sort(key=lambda r: float(r.get("金额") or 0), reverse=True) + + overview = overview or {} + occurrence = float(overview.get("occurrence", 0) or 0) + + kpi: dict[str, Any] = { + "总优惠": total, + "优惠率": _pct(total, occurrence), # 0.3796 表示 37.96% + "占比排序": breakdown, + } + if breakdown: + top = breakdown[0] + kpi["最大优惠来源"] = f"{top.get('名称')}（金额 {top.get('金额')} 元，占总优惠 {int(float(top.get('占总优惠', 0))*100)}%）" + return kpi + + +def _build_cashflow_kpi(cashflow: dict | None) -> dict | None: + """消费收款拆三档（纸币/线上/团购）+ 充值到账，给 AI 直接看资金来源结构。""" + if not isinstance(cashflow, dict): + return None + consume = cashflow.get("consume_items") or [] + recharge = cashflow.get("recharge_items") or [] + total = float(cashflow.get("total", 0) or 0) + if total <= 0: + return None + + consume_map = {} + for it in consume: + if not isinstance(it, dict): + continue + consume_map[it.get("label")] = { + "金额": round(float(it.get("amount", 0) or 0), 2), + "环比": it.get("compare") or "持平", + } + + recharge_total = round(sum(float(x.get("amount", 0) or 0) for x in recharge if isinstance(x, dict)), 2) + consume_total = round(sum(float(v.get("金额", 0) or 0) for v in consume_map.values()), 2) + + return { + "合计": round(total, 2), + "合计环比": cashflow.get("total_compare") or "持平", + "消费收款合计": consume_total, + "消费收款占比": _pct(consume_total, total), + "充值收款合计": recharge_total, + "充值收款占比": _pct(recharge_total, total), + "按渠道": consume_map, + } + + +def _build_coach_kpi(coach: dict | None) -> dict | None: + """助教成本压缩：只保留两档的合计薪酬+合计分成+平均时薪+3 级别薪酬分布。""" + if not isinstance(coach, dict): + return None + def _slim_tier(t: dict | None) -> dict | None: + if not isinstance(t, dict): + return None + rows = t.get("rows") or [] + # 只保留级别-薪酬-时薪 3 字段，作为分布快照 + tier_dist = [ + {"级别": r.get("level"), "薪酬": r.get("pay"), "时薪": r.get("hourly")} + for r in rows if isinstance(r, dict) + ] + total_pay = float(t.get("total_pay", 0) or 0) + if total_pay <= 0: + return None + return { + "合计薪酬": round(total_pay, 2), + "合计薪酬环比": t.get("total_pay_compare") or "持平", + "合计分成": round(float(t.get("total_share", 0) or 0), 2), + "平均时薪": round(float(t.get("avg_hourly", 0) or 0), 2), + "各级别分布": tier_dist, + } + basic = _slim_tier(coach.get("basic")) + incentive = _slim_tier(coach.get("incentive")) + if not basic and not incentive: + return None + out: dict[str, Any] = {} + if basic: + out["基础助教"] = basic + if incentive: + out["激励助教"] = incentive + # 派生：人力成本占收入比（需要收入传进来，这里只给基础值） + total_pay = (basic or {}).get("合计薪酬", 0) + (incentive or {}).get("合计薪酬", 0) + if total_pay > 0: + out["人力薪酬合计"] = round(total_pay, 2) + return out + + +def _build_derived_ratios(overview: dict | None, cashflow_kpi: dict | None, + coach_kpi: dict | None, discount_kpi: dict | None) -> dict: + """数据挖掘视角：派生关键比率，让 AI 不用自己算。 + + - 储值卡贡献率：充值到账 / 总现金流入 + - 人力成本占收入比：助教薪酬合计 / 成交收入 + - 优惠侵蚀率：总优惠 / 发生额 + - 现金结余率：现金结余 / 现金流入 + """ + ov = overview or {} + confirmed = float(ov.get("confirmed_revenue", 0) or 0) + occurrence = float(ov.get("occurrence", 0) or 0) + cash_in = float(ov.get("cash_in", 0) or 0) + cash_balance = float(ov.get("cash_balance", 0) or 0) + total_pay = (coach_kpi or {}).get("人力薪酬合计", 0) + recharge_in = (cashflow_kpi or {}).get("充值收款合计", 0) + discount_total = (discount_kpi or {}).get("总优惠", 0) + + out: dict[str, Any] = {} + if confirmed > 0 and total_pay: + out["人力成本占成交收入比"] = _pct(total_pay, confirmed) + if cash_in > 0 and recharge_in: + out["储值卡充值占现金流入比"] = _pct(recharge_in, cash_in) + if occurrence > 0 and discount_total: + out["优惠侵蚀率"] = _pct(discount_total, occurrence) + if cash_in > 0: + out["现金结余率"] = _pct(cash_balance, cash_in) + return out + + +# 2026-04-22：异常检测由 AI 侧自行判断，后端只提供客观 KPI（不给规则结论） + + +def _translate_keys(data: Any) -> Any: + """递归翻译 dict/list 中所有键为中文；值保持不变。 + + - dict: 键命中 KEY_TRANSLATIONS 则替换，未命中保留原键 + - list: 逐项递归 + - 其他类型（str/int/float/bool/None）原样返回 + """ + if isinstance(data, dict): + return { + KEY_TRANSLATIONS.get(k, k): _translate_keys(v) + for k, v in data.items() + } + if isinstance(data, list): + return [_translate_keys(item) for item in data] + return data + + +async def build_prompt( + context: dict, + cache_svc: Any | None = None, # 兼容统一签名，App2 不用 +) -> str: + """构建 App2 prompt 字符串。 + + Args: + context: site_id, time_dimension, area（可选，默认 all） + + Returns: + JSON 序列化后的 prompt 字符串，所有 board 数据字段已翻译为中文。 + """ + site_id = context["site_id"] + time_dimension = context["time_dimension"] + area = context.get("area", "all") + + board_time = DIMENSION_MAP.get(time_dimension) + if not board_time: + raise ValueError(f"App2 不支持的时间维度: {time_dimension}") + + if area not in AREA_LABELS: + raise ValueError(f"App2 不支持的区域: {area}") + + try: + board_data = await get_finance_board( + time=board_time, area=area, compare=1, site_id=site_id, + ) + except Exception: + logger.warning( + "App2 财务看板查询失败: site_id=%s dimension=%s area=%s", + site_id, time_dimension, area, exc_info=True, + ) + board_data = {} + + # 2026-04-22 数据挖掘视角 prompt 结构化： + # - 优惠/现金流/助教/支出 四大领域分别派生 KPI（带占比/排序/派生指标） + # - 异常检测：规则法标注 AI 必看异常点 + # - 派生比率：人力成本占比/优惠侵蚀率/储值卡贡献率 等不用 AI 再算 + # - 原始财务数据经 _slim 裁剪后作为"原始指标"补充，避免 AI 失去追溯能力 + overview = board_data.get("overview") if isinstance(board_data, dict) else None + revenue = board_data.get("revenue") if isinstance(board_data, dict) else None + cashflow = board_data.get("cashflow") if isinstance(board_data, dict) else None + expense = board_data.get("expense") if isinstance(board_data, dict) else None + coach = board_data.get("coach_analysis") if isinstance(board_data, dict) else None + + discount_kpi = _build_discount_kpi(revenue, overview) + cashflow_kpi = _build_cashflow_kpi(cashflow) + expense_kpi = _aggregate_expense(expense) + coach_kpi = _build_coach_kpi(coach) + ratios = _build_derived_ratios(overview, cashflow_kpi, coach_kpi, discount_kpi) + + # 原始数据：slim 后再翻译，供 AI 追溯细节 + slim_data = _slim(board_data) or {} + raw_cn = _translate_keys(slim_data) + + # 对比口径说明：当期/对比期均为"同天数对齐"，避免 AI 把环比误读为"当期部分 vs 上期整月" + compare_caliber: dict[str, Any] | None = None + try: + from app.services.runtime_context import get_runtime_context + + runtime_ctx = get_runtime_context(site_id) + cur_start, cur_end = _calc_date_range(board_time, ref_date=runtime_ctx.business_date) + prev_start, prev_end = _calc_prev_range(board_time, cur_start, cur_end) + cur_days = (cur_end - cur_start).days + 1 + prev_days = (prev_end - prev_start).days + 1 + compare_caliber = { + "当期范围": f"{cur_start} ~ {cur_end}（{cur_days} 天）", + "对比期范围": f"{prev_start} ~ {prev_end}（{prev_days} 天）", + "对齐方式": "上期同天数对齐（非整月/整周对比）", + "说明": "所有 _环比 / _compare 字段均按上表口径计算；月中调用时对比期会自动截断到与当期相同天数", + } + except Exception: + logger.debug("对比口径字段生成失败（不影响主流程）", exc_info=True) + + payload: dict[str, Any] = { + "当前时间": get_runtime_context(site_id).business_now.strftime("%Y-%m-%d %H:%M"), + "门店编号": site_id, + "时间维度": DIMENSION_LABELS.get(time_dimension, time_dimension), + "区域": AREA_LABELS.get(area, area), + # 0. 对比口径：让 AI 正确解读环比字段 + **({"对比口径": compare_caliber} if compare_caliber else {}), + # 1. 核心 KPI：AI 洞察首要依据 + "核心KPI": { + "发生额": float(overview.get("occurrence", 0)) if overview else 0, + "发生额环比": (overview or {}).get("occurrence_compare") or "持平", + "成交收入": float(overview.get("confirmed_revenue", 0)) if overview else 0, + "成交收入环比": (overview or {}).get("confirmed_revenue_compare") or "持平", + "现金流入": (overview or {}).get("cash_in"), + "现金流入环比": (overview or {}).get("cash_in_compare") or "持平", + "现金结余": (overview or {}).get("cash_balance"), + "现金结余环比": (overview or {}).get("cash_balance_compare") or "持平", + }, + # 2. 派生比率：不用 AI 再算 + "派生比率": ratios, + } + # 3. 优惠构成（带排序/占比/环比/最大来源提示） + if discount_kpi: + payload["优惠构成"] = discount_kpi + # 4. 现金流入来源分布 + if cashflow_kpi: + payload["现金流入来源"] = cashflow_kpi + # 5. 支出概况（聚合到四大类，total=0 则不给 AI） + if expense_kpi: + payload["支出概况"] = expense_kpi + # 6. 助教成本画像 + if coach_kpi: + payload["助教成本"] = coach_kpi + # 7. 储值卡余额变化：期初 + 期末 + 充值 + 消耗 + 其他调整（揭示"充值-消耗≠余额变化"的差异） + # 避免 AI 在只看当期充值/消耗时对"余额为何涨"的矛盾自圆其说 + if area == "all" and isinstance(recharge := board_data.get("recharge"), dict): + try: + start_date_obj, _end = _calc_date_range(board_time) + opening = _fetch_card_balance_opening(site_id, str(start_date_obj)) + closing = float(recharge.get("card_balance") or 0) + period_recharge = float(recharge.get("actual_income") or 0) + period_consume = float(recharge.get("consumed") or 0) + if opening is not None and (opening > 0 or closing > 0): + diff = closing - opening + other_adj = round(diff - (period_recharge - period_consume), 2) + payload["储值卡余额变化"] = { + "期初余额": round(opening, 2), + "期末余额": round(closing, 2), + "余额变化": round(diff, 2), + "本期充值": round(period_recharge, 2), + "本期消耗": round(period_consume, 2), + "其他调整": other_adj, # 含过期/赠送/退款/手动调整，非 0 时 AI 需要关注 + } + except Exception: + logger.debug("储值卡余额变化注入失败", exc_info=True) + # 8. 日粒度派生（仅 area=all，样本 ≥ 7 天）：一次 DB 查询，三段派生 + # - 单位经济：客单价/订单数/会员占比（含环比，避免 AI 对客单走势推测幻觉） + # - 按星期聚合：供 E 板块做周中规律宏观洞察 + # - 日粒度异常：同星期均值基线下的极端偏离 + if area == "all": + try: + start_date, end_date = _calc_date_range(board_time) + series = _fetch_daily_series(site_id, str(start_date), str(end_date)) + # 上期序列（用于客单价环比） + prev_series: list[tuple] | None = None + try: + prev_start, prev_end = _calc_prev_range(board_time, start_date, end_date) + prev_series = _fetch_daily_series(site_id, str(prev_start), str(prev_end)) + except Exception: + logger.debug("上期 series 查询失败，客单价环比字段将省略", exc_info=True) + + if series: + unit_econ = _build_unit_economics(series, prev_series=prev_series) + if unit_econ: + payload["单位经济"] = unit_econ + by_weekday = _aggregate_by_weekday(series) + if by_weekday: + payload["按星期聚合"] = by_weekday + anomalies = _detect_anomaly_days( + site_id, str(start_date), str(end_date), series=series, + ) + if anomalies: + payload["日粒度异常"] = anomalies + except Exception: + logger.debug("日粒度派生字段注入失败（不影响主流程）", exc_info=True) + # 9. 行业基线：AI 判断是否超警戒线的参照 + payload["行业基线"] = INDUSTRY_BASELINES + # 10. 原始财务数据：供 AI 追溯（大部分 prompt 长度来自这里，已 slim） + payload["原始指标"] = raw_cn + + if not board_data: + payload["数据缺失提示"] = "财务看板数据获取失败，请基于已有缓存或常识分析" + + return json.dumps(payload, ensure_ascii=False, default=str) diff --git a/apps/backend/app/ai/prompts/app2a_finance_area_prompt.py b/apps/backend/app/ai/prompts/app2a_finance_area_prompt.py index 2898959..81ff2eb 100644 --- a/apps/backend/app/ai/prompts/app2a_finance_area_prompt.py +++ b/apps/backend/app/ai/prompts/app2a_finance_area_prompt.py @@ -396,7 +396,10 @@ async def build_prompt( # 对比口径（所有环比字段的前置依赖 · H1） compare_caliber: dict[str, Any] | None = None try: - cur_start, cur_end = _calc_date_range(board_time) + from app.services.runtime_context import get_runtime_context + + runtime_ctx = get_runtime_context(site_id) + cur_start, cur_end = _calc_date_range(board_time, ref_date=runtime_ctx.business_date) prev_start, prev_end = _calc_prev_range(board_time, cur_start, cur_end) cur_days = (cur_end - cur_start).days + 1 prev_days = (prev_end - prev_start).days + 1 @@ -419,7 +422,7 @@ async def build_prompt( } payload: dict[str, Any] = { - "当前时间": datetime.now().strftime("%Y-%m-%d %H:%M"), + "当前时间": get_runtime_context(site_id).business_now.strftime("%Y-%m-%d %H:%M"), "门店编号": site_id, "时间维度": DIMENSION_LABELS.get(time_dimension, time_dimension), "区域": AREA_LABELS.get(area, area), diff --git a/apps/backend/app/ai/prompts/app3_clue_prompt.py b/apps/backend/app/ai/prompts/app3_clue_prompt.py new file mode 100644 index 0000000..2685767 --- /dev/null +++ b/apps/backend/app/ai/prompts/app3_clue_prompt.py @@ -0,0 +1,131 @@ +"""应用 3 客户数据维客线索分析 Prompt 拼装。 + +消费事件触发，从客户消费数据提取维客线索。 +- 数据源：fetch_member_consumption_data（DWS） +- 金额口径：items_sum（禁止 consume_money） +- 线索 category：客户基础 / 消费习惯 / 玩法偏好（3 选 1） +- 线索 providers 统一为"系统" +- system prompt 在百炼控制台配置，本模块只拼数据上下文 JSON + +返回：单个 prompt 字符串（直接传给 Application.call）。 +""" + +from __future__ import annotations + +import json +import logging +from typing import Any + +from app.ai.cache_service import AICacheService +from app.ai.data_fetchers import fetch_member_consumption_data +from app.ai.schemas import CacheTypeEnum +from app.services.runtime_context import as_runtime_business_now_str + +logger = logging.getLogger(__name__) + +# prompt 观测阈值：历史上 4000 字会触发裁剪；现保留完整消费明细，仅用于测试/审计参考 +_MAX_PROMPT_LEN = 4000 + + +async def build_prompt( + context: dict, + cache_svc: AICacheService | None = None, +) -> str: + """构建 App3 prompt 字符串。 + + Args: + context: site_id, member_id + cache_svc: 缓存服务，用于读取 reference 历史数据 + + Returns: + JSON 序列化后的 prompt 字符串 + """ + site_id = context["site_id"] + member_id = context["member_id"] + + # 数据获取（失败降级） + fetch_failed = False + try: + member_data = await fetch_member_consumption_data(site_id, member_id) + except Exception: + logger.warning( + "App3 消费数据获取失败: site_id=%s member_id=%s", + site_id, member_id, exc_info=True, + ) + member_data = _default_member_data() + fetch_failed = True + + consumption_records = member_data.get("consumption_records") or [] + if not consumption_records: + consumption_records = ( + "⚠ 消费数据获取失败，该客户暂无消费记录可供分析" + if fetch_failed else "该客户暂无消费记录" + ) + + payload: dict[str, Any] = { + "current_time": as_runtime_business_now_str(site_id, fmt="%Y-%m-%d %H:%M"), + "member_id": member_id, + "member_nickname": member_data.get("member_nickname", ""), + "main_data": { + "consumption_records": consumption_records, + "member_cards": member_data.get("member_cards", []), + "card_balance_total": member_data.get("card_balance_total", 0), + "stored_value_balance_total": member_data.get("stored_value_balance_total", 0), + "expected_visit_date": member_data.get("expected_visit_date"), + "days_since_last_visit": member_data.get("days_since_last_visit"), + }, + "reference": _build_reference(site_id, member_id, cache_svc), + } + + # 完整明细策略：App3 需要尽量保留消费行为模式，不在本地裁剪消费记录。 + # 真实 App3 完整 100 条明细调用已验证可在 180s 单步超时内返回。 + text = json.dumps(payload, ensure_ascii=False, default=str) + return text + + +def _default_member_data() -> dict: + return { + "member_nickname": "", + "consumption_records": [], + "member_cards": [], + "card_balance_total": 0, + "stored_value_balance_total": 0, + "expected_visit_date": None, + "days_since_last_visit": None, + } + + +def _build_reference( + site_id: int, + member_id: int, + cache_svc: AICacheService | None, +) -> dict: + """组装参考字段：App6 备注线索最新 + App8 历史最近 2 条。""" + if cache_svc is None: + return {} + + ref: dict = {} + target_id = str(member_id) + + app6_latest = cache_svc.get_latest( + CacheTypeEnum.APP6_NOTE_ANALYSIS.value, site_id, target_id, + ) + if app6_latest: + ref["app6_note_clues"] = { + "result_json": app6_latest.get("result_json"), + "generated_at": app6_latest.get("created_at"), + } + + app8_history = cache_svc.get_history( + CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, limit=2, + ) + if app8_history: + ref["app8_history"] = [ + { + "result_json": h.get("result_json"), + "generated_at": h.get("created_at"), + } + for h in app8_history + ] + + return ref diff --git a/apps/backend/app/ai/prompts/app4_analysis_prompt.py b/apps/backend/app/ai/prompts/app4_analysis_prompt.py new file mode 100644 index 0000000..97255fd --- /dev/null +++ b/apps/backend/app/ai/prompts/app4_analysis_prompt.py @@ -0,0 +1,177 @@ +"""应用 4 关系分析 / 任务建议 Prompt 拼装。 + +助教被分配召回任务或参与新结算时触发。 +- 数据源：fetch_assistant_info + fetch_service_history + fetch_member_consumption_data + fetch_member_notes +- 输出字段：task_description / action_suggestions / one_line_summary +- system prompt 在百炼控制台配置 + +返回：单个 prompt 字符串。 +""" + +from __future__ import annotations + +import asyncio +import json +import logging +from typing import Any + +from app.ai.cache_service import AICacheService +from app.ai.data_fetchers import ( + fetch_assistant_info, + fetch_member_consumption_data, + fetch_member_notes, + fetch_service_history, +) +from app.ai.schemas import CacheTypeEnum +from app.services.runtime_context import as_runtime_business_now_str + +logger = logging.getLogger(__name__) + +_MAX_PROMPT_LEN = 8000 + + +async def build_prompt( + context: dict, + cache_svc: AICacheService | None = None, +) -> str: + """构建 App4 prompt 字符串。 + + Args: + context: site_id, assistant_id, member_id + cache_svc: 缓存服务，用于读取 reference 历史数据 + + Returns: + JSON 序列化后的 prompt 字符串 + """ + site_id = context["site_id"] + assistant_id = context["assistant_id"] + member_id = context["member_id"] + + results = await asyncio.gather( + fetch_assistant_info(site_id, assistant_id), + fetch_service_history(site_id, assistant_id, member_id), + fetch_member_consumption_data(site_id, member_id), + fetch_member_notes(site_id, member_id), + return_exceptions=True, + ) + + warnings: list[str] = [] + + assistant_info = results[0] if not isinstance(results[0], Exception) else {} + if isinstance(results[0], Exception): + warnings.append("助教信息获取失败") + logger.warning("App4 助教信息获取失败: %s", results[0]) + + service_history = results[1] if not isinstance(results[1], Exception) else [] + if isinstance(results[1], Exception): + warnings.append("服务历史获取失败") + logger.warning("App4 服务历史获取失败: %s", results[1]) + + if isinstance(results[2], Exception): + member_data = _default_member_data() + warnings.append("消费数据获取失败") + logger.warning("App4 消费数据获取失败: %s", results[2]) + else: + member_data = results[2] + + notes = results[3] if not isinstance(results[3], Exception) else [] + if isinstance(results[3], Exception): + warnings.append("备注获取失败") + logger.warning("App4 备注获取失败: %s", results[3]) + + payload: dict[str, Any] = { + "current_time": as_runtime_business_now_str(site_id, fmt="%Y-%m-%d %H:%M"), + "assistant_id": assistant_id, + "member_id": member_id, + "assistant_info": assistant_info or "⚠ 助教信息获取失败", + "service_history": service_history or "暂无服务记录", + "task_assignment_basis": { + "consumption_records": member_data.get("consumption_records", []) or "该客户暂无消费记录", + "member_cards": member_data.get("member_cards", []), + "card_balance_total": member_data.get("card_balance_total", 0), + "stored_value_balance_total": member_data.get("stored_value_balance_total", 0), + "expected_visit_date": member_data.get("expected_visit_date"), + "days_since_last_visit": member_data.get("days_since_last_visit"), + }, + "customer_data": { + "member_nickname": member_data.get("member_nickname", ""), + "notes": notes or "暂无备注", + }, + "reference": _build_reference(site_id, member_id, cache_svc), + } + + if warnings: + payload["_data_warnings"] = warnings + + return _truncate_payload(payload) + + +def _default_member_data() -> dict: + return { + "member_nickname": "", + "consumption_records": [], + "member_cards": [], + "card_balance_total": 0, + "stored_value_balance_total": 0, + "expected_visit_date": None, + "days_since_last_visit": None, + } + + +def _build_reference( + site_id: int, + member_id: int, + cache_svc: AICacheService | None, +) -> dict: + """组装 App8 最新 + 最近 2 条历史。""" + if cache_svc is None: + return {} + + ref: dict = {} + target_id = str(member_id) + + latest = cache_svc.get_latest( + CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, + ) + if latest: + ref["app8_latest"] = { + "result_json": latest.get("result_json"), + "generated_at": latest.get("created_at"), + } + + history = cache_svc.get_history( + CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, limit=2, + ) + if history: + ref["app8_history"] = [ + {"result_json": h.get("result_json"), "generated_at": h.get("created_at")} + for h in history + ] + + return ref + + +def _truncate_payload(payload: dict) -> str: + """按优先级截断 service_history → consumption_records → notes，控制 prompt 长度。""" + text = json.dumps(payload, ensure_ascii=False, default=str) + if len(text) <= _MAX_PROMPT_LEN: + return text + + sh = payload.get("service_history") + if isinstance(sh, list) and len(sh) > 5: + payload["service_history"] = sh[:5] + payload["_truncated_service_history"] = f"服务记录已截断，原始 {len(sh)} 条" + text = json.dumps(payload, ensure_ascii=False, default=str) + if len(text) > _MAX_PROMPT_LEN: + records = payload["task_assignment_basis"].get("consumption_records") + if isinstance(records, list) and len(records) > 5: + payload["task_assignment_basis"]["consumption_records"] = records[:5] + payload["task_assignment_basis"]["_truncated"] = f"消费记录已截断，原始 {len(records)} 条" + text = json.dumps(payload, ensure_ascii=False, default=str) + if len(text) > _MAX_PROMPT_LEN: + n = payload["customer_data"].get("notes") + if isinstance(n, list) and len(n) > 10: + payload["customer_data"]["notes"] = n[:10] + payload["customer_data"]["_truncated_notes"] = f"备注已截断，原始 {len(n)} 条" + text = json.dumps(payload, ensure_ascii=False, default=str) + return text diff --git a/apps/backend/app/ai/prompts/app5_tactics_prompt.py b/apps/backend/app/ai/prompts/app5_tactics_prompt.py new file mode 100644 index 0000000..e29ee1a --- /dev/null +++ b/apps/backend/app/ai/prompts/app5_tactics_prompt.py @@ -0,0 +1,170 @@ +"""应用 5 话术参考 Prompt 拼装。 + +App4 完成后串行触发，接收 App4 返回结果作为 task_suggestion。 +- 数据源：fetch_assistant_info + fetch_service_history + fetch_member_consumption_data + fetch_member_notes + context.app4_result +- 输出字段：tactics 数组（每条含 scenario + script） +- system prompt 在百炼控制台配置 + +返回：单个 prompt 字符串。 +""" + +from __future__ import annotations + +import asyncio +import json +import logging +from typing import Any + +from app.ai.cache_service import AICacheService +from app.ai.data_fetchers import ( + fetch_assistant_info, + fetch_member_consumption_data, + fetch_member_notes, + fetch_service_history, +) +from app.ai.schemas import CacheTypeEnum +from app.services.runtime_context import as_runtime_business_now_str + +logger = logging.getLogger(__name__) + +_MAX_PROMPT_LEN = 8000 + + +async def build_prompt( + context: dict, + cache_svc: AICacheService | None = None, +) -> str: + """构建 App5 prompt 字符串。 + + Args: + context: site_id, assistant_id, member_id, app4_result(dict|None) + + Returns: + JSON 序列化后的 prompt 字符串 + """ + site_id = context["site_id"] + assistant_id = context["assistant_id"] + member_id = context["member_id"] + task_suggestion = context.get("app4_result") or {} + + results = await asyncio.gather( + fetch_assistant_info(site_id, assistant_id), + fetch_service_history(site_id, assistant_id, member_id), + fetch_member_consumption_data(site_id, member_id), + fetch_member_notes(site_id, member_id), + return_exceptions=True, + ) + + warnings: list[str] = [] + + assistant_info = results[0] if not isinstance(results[0], Exception) else {} + if isinstance(results[0], Exception): + warnings.append("助教信息获取失败") + logger.warning("App5 助教信息获取失败: %s", results[0]) + + service_history = results[1] if not isinstance(results[1], Exception) else [] + if isinstance(results[1], Exception): + warnings.append("服务历史获取失败") + logger.warning("App5 服务历史获取失败: %s", results[1]) + + if isinstance(results[2], Exception): + member_data = _default_member_data() + warnings.append("消费数据获取失败") + logger.warning("App5 消费数据获取失败: %s", results[2]) + else: + member_data = results[2] + + notes = results[3] if not isinstance(results[3], Exception) else [] + if isinstance(results[3], Exception): + warnings.append("备注获取失败") + logger.warning("App5 备注获取失败: %s", results[3]) + + payload: dict[str, Any] = { + "current_time": as_runtime_business_now_str(site_id, fmt="%Y-%m-%d %H:%M"), + "assistant_id": assistant_id, + "member_id": member_id, + "task_suggestion": task_suggestion, + "assistant_info": assistant_info or "⚠ 助教信息获取失败", + "service_history": service_history or "暂无服务记录", + "task_assignment_basis": { + "consumption_records": member_data.get("consumption_records", []) or "该客户暂无消费记录", + "member_cards": member_data.get("member_cards", []), + "card_balance_total": member_data.get("card_balance_total", 0), + "stored_value_balance_total": member_data.get("stored_value_balance_total", 0), + "expected_visit_date": member_data.get("expected_visit_date"), + "days_since_last_visit": member_data.get("days_since_last_visit"), + }, + "customer_data": { + "member_nickname": member_data.get("member_nickname", ""), + "notes": notes or "暂无备注", + }, + "reference": _build_reference(site_id, member_id, cache_svc), + } + + if warnings: + payload["_data_warnings"] = warnings + + return _truncate_payload(payload) + + +def _default_member_data() -> dict: + return { + "member_nickname": "", + "consumption_records": [], + "member_cards": [], + "card_balance_total": 0, + "stored_value_balance_total": 0, + "expected_visit_date": None, + "days_since_last_visit": None, + } + + +def _build_reference( + site_id: int, + member_id: int, + cache_svc: AICacheService | None, +) -> dict: + """组装最近 2 条 App8 历史。""" + if cache_svc is None: + return {} + + ref: dict = {} + history = cache_svc.get_history( + CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, + site_id, + str(member_id), + limit=2, + ) + if history: + ref["app8_history"] = [ + {"result_json": h.get("result_json"), "generated_at": h.get("created_at")} + for h in history + ] + + return ref + + +def _truncate_payload(payload: dict) -> str: + """按优先级截断 service_history → consumption_records → notes。""" + text = json.dumps(payload, ensure_ascii=False, default=str) + if len(text) <= _MAX_PROMPT_LEN: + return text + + sh = payload.get("service_history") + if isinstance(sh, list) and len(sh) > 5: + payload["service_history"] = sh[:5] + payload["_truncated_service_history"] = f"服务记录已截断，原始 {len(sh)} 条" + text = json.dumps(payload, ensure_ascii=False, default=str) + if len(text) > _MAX_PROMPT_LEN: + records = payload["task_assignment_basis"].get("consumption_records") + if isinstance(records, list) and len(records) > 5: + payload["task_assignment_basis"]["consumption_records"] = records[:5] + payload["task_assignment_basis"]["_truncated"] = f"消费记录已截断，原始 {len(records)} 条" + text = json.dumps(payload, ensure_ascii=False, default=str) + if len(text) > _MAX_PROMPT_LEN: + n = payload["customer_data"].get("notes") + if isinstance(n, list) and len(n) > 10: + payload["customer_data"]["notes"] = n[:10] + payload["customer_data"]["_truncated_notes"] = f"备注已截断，原始 {len(n)} 条" + text = json.dumps(payload, ensure_ascii=False, default=str) + return text diff --git a/apps/backend/app/ai/prompts/app6_note_prompt.py b/apps/backend/app/ai/prompts/app6_note_prompt.py new file mode 100644 index 0000000..38a32ed --- /dev/null +++ b/apps/backend/app/ai/prompts/app6_note_prompt.py @@ -0,0 +1,160 @@ +"""应用 6 备注分析 Prompt 拼装。 + +助教提交备注后触发，AI 分析备注内容并评分（1-10）+ 提取维客线索。 +- 数据源：context.note_content + fetch_member_consumption_data + fetch_member_notes +- 线索 category：6 选 1（含促销偏好/社交关系/重要反馈） +- 线索 providers 标记当前备注提供人 +- system prompt 在百炼控制台配置 + +返回：单个 prompt 字符串。 +""" + +from __future__ import annotations + +import asyncio +import json +import logging +from typing import Any + +from app.ai.cache_service import AICacheService +from app.ai.data_fetchers import fetch_member_consumption_data, fetch_member_notes +from app.ai.schemas import CacheTypeEnum +from app.services.runtime_context import as_runtime_business_now_str + +logger = logging.getLogger(__name__) + +_MAX_PROMPT_LEN = 8000 + + +async def build_prompt( + context: dict, + cache_svc: AICacheService | None = None, +) -> str: + """构建 App6 prompt 字符串。 + + Args: + context: site_id, member_id, note_content, noted_by_name, noted_by_created_at + + Returns: + JSON 序列化后的 prompt 字符串 + """ + site_id = context["site_id"] + member_id = context["member_id"] + note_content = context.get("note_content", "") + noted_by_name = context.get("noted_by_name", "") + noted_by_created_at = context.get("noted_by_created_at", "") + + results = await asyncio.gather( + fetch_member_consumption_data(site_id, member_id), + fetch_member_notes(site_id, member_id), + return_exceptions=True, + ) + + warnings: list[str] = [] + + if isinstance(results[0], Exception): + member_data = _default_member_data() + warnings.append("消费数据获取失败") + logger.warning("App6 消费数据获取失败: %s", results[0]) + else: + member_data = results[0] + + all_notes = results[1] if not isinstance(results[1], Exception) else [] + if isinstance(results[1], Exception): + warnings.append("备注获取失败") + logger.warning("App6 备注获取失败: %s", results[1]) + + reference = _build_reference(site_id, member_id, cache_svc) + reference["member_nickname"] = member_data.get("member_nickname", "") + reference["consumption_data"] = { + "consumption_records": member_data.get("consumption_records", []) or "该客户暂无消费记录", + "member_cards": member_data.get("member_cards", []), + "card_balance_total": member_data.get("card_balance_total", 0), + "stored_value_balance_total": member_data.get("stored_value_balance_total", 0), + "expected_visit_date": member_data.get("expected_visit_date"), + "days_since_last_visit": member_data.get("days_since_last_visit"), + } + reference["all_notes"] = all_notes + + payload: dict[str, Any] = { + "current_time": as_runtime_business_now_str(site_id, fmt="%Y-%m-%d %H:%M"), + "member_id": member_id, + "current_note": { + "content": note_content, + "recorded_by": noted_by_name, + "created_at": noted_by_created_at, + }, + "providers_label": noted_by_name, + "reference": reference, + } + + if warnings: + payload["_data_warnings"] = warnings + + return _truncate_payload(payload) + + +def _default_member_data() -> dict: + return { + "member_nickname": "", + "consumption_records": [], + "member_cards": [], + "card_balance_total": 0, + "stored_value_balance_total": 0, + "expected_visit_date": None, + "days_since_last_visit": None, + } + + +def _build_reference( + site_id: int, + member_id: int, + cache_svc: AICacheService | None, +) -> dict: + """组装 App3 客户线索最新 + App8 历史最近 2 条。""" + if cache_svc is None: + return {} + + ref: dict = {} + target_id = str(member_id) + + app3_latest = cache_svc.get_latest( + CacheTypeEnum.APP3_CLUE.value, site_id, target_id, + ) + if app3_latest: + ref["app3_clues"] = { + "result_json": app3_latest.get("result_json"), + "generated_at": app3_latest.get("created_at"), + } + + app8_history = cache_svc.get_history( + CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, limit=2, + ) + if app8_history: + ref["app8_history"] = [ + {"result_json": h.get("result_json"), "generated_at": h.get("created_at")} + for h in app8_history + ] + + return ref + + +def _truncate_payload(payload: dict) -> str: + """按优先级截断 consumption_records → all_notes。""" + text = json.dumps(payload, ensure_ascii=False, default=str) + if len(text) <= _MAX_PROMPT_LEN: + return text + + cd = payload["reference"].get("consumption_data", {}) + records = cd.get("consumption_records") + if isinstance(records, list) and len(records) > 5: + cd["consumption_records"] = records[:5] + cd["_truncated"] = f"消费记录已截断，原始 {len(records)} 条" + text = json.dumps(payload, ensure_ascii=False, default=str) + if len(text) > _MAX_PROMPT_LEN: + notes = payload["reference"].get("all_notes") + if isinstance(notes, list) and len(notes) > 10: + payload["reference"]["all_notes"] = notes[:10] + payload["reference"]["_truncated_notes"] = f"备注已截断，原始 {len(notes)} 条" + text = json.dumps(payload, ensure_ascii=False, default=str) + return text diff --git a/apps/backend/app/ai/prompts/app7_customer_prompt.py b/apps/backend/app/ai/prompts/app7_customer_prompt.py new file mode 100644 index 0000000..b3e4932 --- /dev/null +++ b/apps/backend/app/ai/prompts/app7_customer_prompt.py @@ -0,0 +1,165 @@ +"""应用 7 客户分析 Prompt 拼装。 + +消费链 App8 完成后串行触发，生成客户全量分析与运营策略。 +- 数据源：fetch_member_consumption_data + fetch_member_notes +- 备注内容标注【来源：XXX，请甄别信息真实性】 +- 输出字段：strategies 数组 + summary +- system prompt 在百炼控制台配置 + +返回：单个 prompt 字符串。 +""" + +from __future__ import annotations + +import asyncio +import json +import logging +from typing import Any + +from app.ai.cache_service import AICacheService +from app.ai.data_fetchers import fetch_member_consumption_data, fetch_member_notes +from app.ai.schemas import CacheTypeEnum +from app.services.runtime_context import as_runtime_business_now_str + +logger = logging.getLogger(__name__) + +_MAX_PROMPT_LEN = 5000 + + +async def build_prompt( + context: dict, + cache_svc: AICacheService | None = None, +) -> str: + """构建 App7 prompt 字符串。 + + Args: + context: site_id, member_id + + Returns: + JSON 序列化后的 prompt 字符串 + """ + site_id = context["site_id"] + member_id = context["member_id"] + + results = await asyncio.gather( + fetch_member_consumption_data(site_id, member_id), + fetch_member_notes(site_id, member_id), + return_exceptions=True, + ) + + warnings: list[str] = [] + + if isinstance(results[0], Exception): + member_data = _default_member_data() + warnings.append("消费数据获取失败") + logger.warning("App7 消费数据获取失败: %s", results[0]) + else: + member_data = results[0] + + notes_raw = results[1] if not isinstance(results[1], Exception) else [] + if isinstance(results[1], Exception): + warnings.append("备注获取失败") + logger.warning("App7 备注获取失败: %s", results[1]) + + # 主观信息标注来源 + if notes_raw: + annotated = [] + for note in notes_raw: + recorded_by = note.get("recorded_by", "未知") + n = dict(note) + n["content"] = ( + f"{note.get('content', '')}" + f"【来源：{recorded_by}，请甄别信息真实性】" + ) + annotated.append(n) + subjective_notes: Any = annotated + else: + subjective_notes = "该客户暂无主观备注信息" + + payload: dict[str, Any] = { + "current_time": as_runtime_business_now_str(site_id, fmt="%Y-%m-%d %H:%M"), + "member_id": member_id, + "member_nickname": member_data.get("member_nickname", ""), + "objective_data": { + "consumption_records": member_data.get("consumption_records", []) or "该客户暂无消费记录", + "member_cards": member_data.get("member_cards", []), + "card_balance_total": member_data.get("card_balance_total", 0), + "stored_value_balance_total": member_data.get("stored_value_balance_total", 0), + "expected_visit_date": member_data.get("expected_visit_date"), + "days_since_last_visit": member_data.get("days_since_last_visit"), + }, + "subjective_data": { + "notes": subjective_notes, + }, + "reference": _build_reference(site_id, member_id, cache_svc), + } + + if warnings: + payload["_data_warnings"] = warnings + + return _truncate_payload(payload) + + +def _default_member_data() -> dict: + return { + "member_nickname": "", + "consumption_records": [], + "member_cards": [], + "card_balance_total": 0, + "stored_value_balance_total": 0, + "expected_visit_date": None, + "days_since_last_visit": None, + } + + +def _build_reference( + site_id: int, + member_id: int, + cache_svc: AICacheService | None, +) -> dict: + """组装 App8 最新 + 最近 2 条历史。""" + if cache_svc is None: + return {} + + ref: dict = {} + target_id = str(member_id) + + latest = cache_svc.get_latest( + CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, + ) + if latest: + ref["app8_latest"] = { + "result_json": latest.get("result_json"), + "generated_at": latest.get("created_at"), + } + + history = cache_svc.get_history( + CacheTypeEnum.APP8_CLUE_CONSOLIDATED.value, site_id, target_id, limit=2, + ) + if history: + ref["app8_history"] = [ + {"result_json": h.get("result_json"), "generated_at": h.get("created_at")} + for h in history + ] + + return ref + + +def _truncate_payload(payload: dict) -> str: + """按优先级截断 consumption_records → notes。""" + text = json.dumps(payload, ensure_ascii=False, default=str) + if len(text) <= _MAX_PROMPT_LEN: + return text + + records = payload["objective_data"].get("consumption_records") + if isinstance(records, list) and len(records) > 5: + payload["objective_data"]["consumption_records"] = records[:5] + payload["objective_data"]["_truncated"] = f"消费记录已截断，原始 {len(records)} 条" + text = json.dumps(payload, ensure_ascii=False, default=str) + if len(text) > _MAX_PROMPT_LEN: + n = payload["subjective_data"].get("notes") + if isinstance(n, list) and len(n) > 10: + payload["subjective_data"]["notes"] = n[:10] + payload["subjective_data"]["_truncated_notes"] = f"备注已截断，原始 {len(n)} 条" + text = json.dumps(payload, ensure_ascii=False, default=str) + return text diff --git a/apps/backend/app/ai/prompts/app8_consolidation_prompt.py b/apps/backend/app/ai/prompts/app8_consolidation_prompt.py index 3044fe3..117e388 100644 --- a/apps/backend/app/ai/prompts/app8_consolidation_prompt.py +++ b/apps/backend/app/ai/prompts/app8_consolidation_prompt.py @@ -1,93 +1,52 @@ -"""应用 8：维客线索整理 Prompt 模板。 +"""应用 8 维客线索整理 Prompt 拼装。 接收 App3（消费分析）和 App6（备注分析）的全部线索， 整合去重后输出统一维客线索。 +- 数据源：context.app3_clues + context.app6_clues（dispatcher 已查好传入） +- 分类标签 6 选 1（与 member_retention_clue CHECK 约束一致） +- 合并规则：相似线索合并，providers 逗号分隔 +- system prompt 在百炼控制台配置 -分类标签限定 6 个枚举值（与 member_retention_clue CHECK 约束一致）： -客户基础、消费习惯、玩法偏好、促销偏好、社交关系、重要反馈。 - -合并规则： -- 相似线索合并，providers 以逗号分隔 -- 其余线索原文返回 -- 最小改动原则 +返回：单个 prompt 字符串。 """ from __future__ import annotations import json +from typing import Any -def build_prompt(context: dict) -> list[dict]: - """构建 App8 维客线索整理 Prompt。 +async def build_prompt( + context: dict, + cache_svc: Any | None = None, # 兼容统一签名，App8 不用 +) -> str: + """构建 App8 prompt 字符串。 Args: - context: 包含以下字段： - - site_id: int - - member_id: int - - app3_clues: list[dict] — App3 产出的线索列表 - - app6_clues: list[dict] — App6 产出的线索列表 - - app3_generated_at: str | None — App3 线索生成时间 - - app6_generated_at: str | None — App6 线索生成时间 + context: site_id, member_id, app3_clues(list), app6_clues(list), + app3_generated_at(str|None), app6_generated_at(str|None) Returns: - 消息列表 [{"role": "system", ...}, {"role": "user", ...}] + JSON 序列化后的 prompt 字符串 """ member_id = context["member_id"] - app3_clues = context.get("app3_clues", []) - app6_clues = context.get("app6_clues", []) - app3_generated_at = context.get("app3_generated_at") - app6_generated_at = context.get("app6_generated_at") + app3_clues = context.get("app3_clues") or [] + app6_clues = context.get("app6_clues") or [] - system_content = { - "task": "整合去重来自消费分析和备注分析的维客线索，输出统一线索列表。", - "app_id": "app8_consolidation", - "rules": { - "category_enum": [ - "客户基础", "消费习惯", "玩法偏好", - "促销偏好", "社交关系", "重要反馈", - ], - "merge_strategy": ( - "相似线索合并为一条，providers 以逗号分隔（如 '系统,张三'）；" - "不相似的线索原文保留，不做修改。最小改动原则。" - ), - "output_format": { - "clues": [ - { - "category": "枚举值（6 选 1）", - "summary": "一句话摘要", - "detail": "详细说明", - "emoji": "表情符号", - "providers": "提供者（逗号分隔）", - } - ] - }, - }, + payload: dict[str, Any] = { + "member_id": member_id, "input": { "app3_clues": { "source": "消费数据分析（App3）", - "generated_at": app3_generated_at, + "generated_at": context.get("app3_generated_at"), "clues": app3_clues, }, "app6_clues": { "source": "备注分析（App6）", - "generated_at": app6_generated_at, + "generated_at": context.get("app6_generated_at"), "clues": app6_clues, }, }, } - user_content = ( - f"请整合会员 {member_id} 的维客线索。\n" - "输入包含两个来源的线索：App3（消费数据分析）和 App6（备注分析）。\n" - "规则：\n" - "1. 相似线索合并为一条，providers 字段以逗号分隔多个提供者\n" - "2. 不相似的线索原文保留\n" - "3. category 必须是：客户基础、消费习惯、玩法偏好、促销偏好、社交关系、重要反馈 之一\n" - "4. 每条线索包含 category、summary、detail、emoji、providers 五个字段\n" - "5. 最小改动原则，尽量保留原始表述" - ) - - return [ - {"role": "system", "content": json.dumps(system_content, ensure_ascii=False)}, - {"role": "user", "content": user_content}, - ] + return json.dumps(payload, ensure_ascii=False, default=str) diff --git a/apps/backend/app/ai/references.py b/apps/backend/app/ai/references.py new file mode 100644 index 0000000..54f5848 --- /dev/null +++ b/apps/backend/app/ai/references.py @@ -0,0 +1,137 @@ +"""AI references 工具模块。 + +为 AI 输出（ai_cache.result_json / ai_messages.reference_card） +注入数据来源引用元数据，便于前端渲染可点击引用卡片。 + +- App2~8：通过 dispatcher._write_cache 统一注入到 result['_references'] +- App1：通过 xcx_chat 在 assistant 消息写入时调用 build_app1_reference 生成单卡片 +""" + +from __future__ import annotations + +from typing import Any + + +def build_app_references(app_type: str, context: dict) -> list[dict]: + """为 App2~8 构建 references 列表，供前端消息卡片渲染。 + + 引用结构： + { + "type": "member" | "task" | "assistant" | "finance", + "id": int | str, + "label": "卡片上的文字", + "link": "/pages/xxx/xxx?param=val"（小程序页面路径）, + "source_page": 小程序页面 contextType + } + + Args: + app_type: 应用名称 + context: 传给 build_prompt 的上下文（含 site_id / member_id 等） + + Returns: + refs 数组。无有效上下文时返回空数组。 + """ + refs: list[dict] = [] + site_id = context.get("site_id") + member_id = context.get("member_id") + assistant_id = context.get("assistant_id") + time_dimension = context.get("time_dimension") + + if member_id is not None: + refs.append({ + "type": "member", + "id": member_id, + "label": f"客户 #{member_id}", + "link": f"/pages/customer-detail/customer-detail?customerId={member_id}", + "source_page": "customer-detail", + }) + + if assistant_id is not None: + refs.append({ + "type": "assistant", + "id": assistant_id, + "label": f"助教 #{assistant_id}", + "link": f"/pages/coach-detail/coach-detail?coachId={assistant_id}", + "source_page": "coach-detail", + }) + + if app_type == "app2_finance" and time_dimension: + refs.append({ + "type": "finance", + "id": time_dimension, + "label": f"财务看板：{_label_for_dimension(time_dimension)}", + "link": f"/pages/board-finance/board-finance?timeDimension={time_dimension}", + "source_page": "board-finance", + }) + + # 保留 site_id 作为兜底上下文（不单独成卡，但用于前端场景判断） + if site_id is not None and refs: + for r in refs: + r.setdefault("site_id", site_id) + + return refs + + +def attach_references(app_type: str, result: dict | None, context: dict) -> dict | None: + """向 AI 输出 result 追加 _references 字段（非破坏性）。 + + - result 为 None 时原样返回（调用失败不注入） + - result 为 dict 时追加 _references 字段；如果 result 已含 _references，保留原值 + """ + if result is None or not isinstance(result, dict): + return result + if "_references" in result: + return result + refs = build_app_references(app_type, context) + if refs: + result["_references"] = refs + return result + + +def build_app1_reference_card(source_page: str | None, context_id: int | str | None) -> dict | None: + """为 App1（chat）assistant 消息构建单个 reference_card。 + + 兼容前端 chat.wxml 已有的 {type, title, summary, data, dataList} 渲染结构， + 额外携带 link 字段供前端点击跳转详情页。 + + 当用户在特定页面（customer-detail / coach-detail / task-detail）发起对话时， + 自动附加对应跳转卡片。普通浮窗对话（source_page='general'）返回 None。 + + 与 chat_service.build_reference_card 不同：本函数不查 DB，仅按 source_page 构造链接。 + """ + if not source_page or not context_id: + return None + + mapping: dict[str, tuple[str, str, str]] = { + "customer-detail": ("customer", "客户", "customerId"), + "coach-detail": ("assistant", "助教", "coachId"), + "task-detail": ("task", "任务", "taskId"), + } + entry = mapping.get(source_page) + if entry is None: + return None + ref_type, label_prefix, param = entry + + return { + "type": ref_type, + "title": f"{label_prefix} #{context_id}", + "summary": f"点击查看{label_prefix}详情", + "data": {}, + "link": f"/pages/{source_page}/{source_page}?{param}={context_id}", + "source_page": source_page, + } + + +def _label_for_dimension(dimension: str) -> str: + """8 个财务维度 → 中文标签。""" + mapping = { + "this_month": "本月", + "last_month": "上月", + "this_week": "本周", + "last_week": "上周", + "this_quarter": "本季度", + "last_quarter": "上季度", + "last_3_months": "近三个月", + "last_6_months": "近六个月", + } + return mapping.get(dimension, dimension) diff --git a/apps/backend/app/ai/run_log_service.py b/apps/backend/app/ai/run_log_service.py index 7b782bd..8778c01 100644 --- a/apps/backend/app/ai/run_log_service.py +++ b/apps/backend/app/ai/run_log_service.py @@ -14,12 +14,17 @@ from typing import Callable import psycopg2.extensions +from app.services.runtime_context import LIVE_INSTANCE_ID, MODE_LIVE, MODE_SANDBOX, get_runtime_context + # prompt 最大存储长度 -_MAX_PROMPT_LENGTH = 2000 +# 2026-04-22：2000→8000。app2_finance 真实 prompt 约 4-8KB（72 组合财务看板 + 中文 key 膨胀）， +# 2000 字符截断会丢掉 optimization-critical 字段（如 discount_items 含团购折扣明细）， +# admin-web 调用详情页无法完整审阅 → 提高到 8000 覆盖绝大部分场景 +_MAX_PROMPT_LENGTH = 8000 def _truncate_prompt(prompt: str | None) -> str | None: - """截断 prompt 为前 2000 字符。None 原样返回。""" + """截断 prompt 为 _MAX_PROMPT_LENGTH 字符上限。None 原样返回。""" if prompt is None: return None return prompt[:_MAX_PROMPT_LENGTH] @@ -54,17 +59,21 @@ class AIRunLogService: truncated = _truncate_prompt(request_prompt) conn = self._get_conn() try: + ctx = get_runtime_context(site_id, conn=conn) + runtime_mode = MODE_SANDBOX if ctx.is_sandbox else MODE_LIVE + sandbox_instance_id = ctx.sandbox_instance_id if ctx.is_sandbox else LIVE_INSTANCE_ID with conn.cursor() as cur: cur.execute( """ INSERT INTO biz.ai_run_logs (site_id, app_type, trigger_type, member_id, - request_prompt, session_id, status) - VALUES (%s, %s, %s, %s, %s, %s, 'pending') + request_prompt, session_id, status, + runtime_mode, sandbox_instance_id) + VALUES (%s, %s, %s, %s, %s, %s, 'pending', %s, %s) RETURNING id """, (site_id, app_type, trigger_type, member_id, - truncated, session_id), + truncated, session_id, runtime_mode, sandbox_instance_id), ) row = cur.fetchone() assert row is not None, "INSERT RETURNING 应返回 id" diff --git a/apps/backend/app/main.py b/apps/backend/app/main.py index c07d1e3..82ae412 100644 --- a/apps/backend/app/main.py +++ b/apps/backend/app/main.py @@ -36,11 +36,12 @@ from app import config # CHANGE 2026-03-23 | 新增 trigger_jobs 路由（定时任务管理页面 API） # CHANGE 2026-03-24 | P18 任务引擎运营看板：新增 admin_task_engine 路由 # CHANGE 2026-03-29 | DWS_TASK_ENGINE：新增 internal_events 路由（按 job_name 执行任务） -from app.routers import auth, execution, schedules, tasks, env_config, db_viewer, etl_status, xcx_test, wx_callback, member_retention_clue, ops_panel, xcx_auth, xcx_avatar, admin_applications, business_day, xcx_tasks, xcx_notes, xcx_chat, xcx_ai_cache, xcx_performance, xcx_customers, xcx_coaches, xcx_board, xcx_config, tenant_auth, tenant_users, tenant_excel, tenant_clues, tenant_site_admins, admin_tenant_admins, admin_registry, internal_ai, admin_ai, admin_dev_trace, trigger_jobs, admin_task_engine, admin_db_health, admin_triggers, internal_events +from app.routers import auth, execution, schedules, tasks, env_config, db_viewer, etl_status, xcx_test, wx_callback, member_retention_clue, ops_panel, xcx_auth, xcx_avatar, admin_applications, business_day, xcx_tasks, xcx_notes, xcx_chat, xcx_ai_cache, xcx_performance, xcx_customers, xcx_coaches, xcx_board, xcx_config, xcx_runtime_clock, tenant_auth, tenant_users, tenant_excel, tenant_clues, tenant_site_admins, admin_tenant_admins, admin_registry, internal_ai, admin_ai, admin_dev_trace, trigger_jobs, admin_task_engine, admin_db_health, admin_triggers, internal_events, admin_runtime_context from app.services.scheduler import scheduler from app.services.task_queue import task_queue from app.services.task_executor import task_executor from app.ws.logs import ws_router +from app.ws.ai_events import ws_router as ai_ws_router @asynccontextmanager @@ -99,6 +100,33 @@ async def lifespan(app: FastAPI): import logging as _log _log.getLogger(__name__).warning("启动检查定时任务失败", exc_info=True) + # CHANGE 2026-04-22 | 启动时清理上次进程遗留的孤儿 run_logs（worker 被 kill/reload 导致 status 卡在 running） + try: + from app.database import get_connection as _get_conn_cleanup + _c = _get_conn_cleanup() + try: + with _c.cursor() as _cur: + _cur.execute( + """ + UPDATE biz.ai_run_logs + SET status = 'failed', + error_message = COALESCE(error_message, '') || ' [orphaned_by_restart]', + finished_at = COALESCE(finished_at, NOW()) + WHERE status = 'running' + AND created_at < NOW() - INTERVAL '5 minutes' + """ + ) + _cleaned = _cur.rowcount + _c.commit() + if _cleaned: + import logging as _log + _log.getLogger(__name__).info("启动清理 %d 条孤儿 run_logs（status=running > 5min）", _cleaned) + finally: + _c.close() + except Exception: + import logging as _log + _log.getLogger(__name__).warning("孤儿 run_logs 清理失败（忽略）", exc_info=True) + # CHANGE 2026-03-10 | 注册 AI 事件处理器（消费/备注/任务分配 → AI 调用链） # CHANGE 2026-03-22 | P14 迁移：BailianClient → DashScopeClient + AIConfig + 防护层 try: @@ -127,6 +155,8 @@ async def lifespan(app: FastAPI): config=_ai_config, ) register_ai_handlers(_dispatcher) + from app.routers import internal_ai as _internal_ai_router + _internal_ai_router.set_dispatcher(_dispatcher) except Exception: import logging as _log _log.getLogger(__name__).warning("AI 事件处理器注册失败，AI 功能不可用", exc_info=True) @@ -178,6 +208,7 @@ app.include_router(env_config.router) app.include_router(db_viewer.router) app.include_router(etl_status.router) app.include_router(ws_router) +app.include_router(ai_ws_router) app.include_router(xcx_test.router) app.include_router(wx_callback.router) app.include_router(member_retention_clue.router) @@ -195,6 +226,7 @@ app.include_router(xcx_customers.router) app.include_router(xcx_coaches.router) app.include_router(xcx_board.router) app.include_router(xcx_config.router) +app.include_router(xcx_runtime_clock.router) app.include_router(tenant_auth.router) app.include_router(tenant_users.router) app.include_router(tenant_excel.router) @@ -210,6 +242,8 @@ app.include_router(trigger_jobs.router) app.include_router(admin_task_engine.router) app.include_router(admin_db_health.router) app.include_router(admin_triggers.router) +app.include_router(admin_runtime_context.router) +app.include_router(admin_runtime_context.config_router) @app.get("/health", tags=["系统"]) diff --git a/apps/backend/app/routers/admin_runtime_context.py b/apps/backend/app/routers/admin_runtime_context.py new file mode 100644 index 0000000..e52ef77 --- /dev/null +++ b/apps/backend/app/routers/admin_runtime_context.py @@ -0,0 +1,309 @@ +# -*- coding: utf-8 -*- +"""业务运行上下文管理 API。""" + +from __future__ import annotations + +import logging +from datetime import date + +from fastapi import APIRouter, Depends, HTTPException, Query, status +from psycopg2.extras import RealDictCursor + +from app.auth.dependencies import CurrentUser, get_current_user +from app.database import get_connection +from app.schemas.runtime_context import ( + RuntimeContextResponse, + RuntimeSwitchRequest, + RuntimeSwitchResponse, + RuntimeTransitionStep, +) +from app.services.runtime_context import ( + MODE_LIVE, + MODE_SANDBOX, + RuntimeContext, + get_runtime_context, + new_sandbox_instance_id, +) + +logger = logging.getLogger(__name__) + +router = APIRouter(prefix="/api/admin/runtime-context", tags=["业务运行上下文"]) +config_router = APIRouter(prefix="/api/config", tags=["业务配置"]) + + +def _require_super_admin(user: CurrentUser) -> None: + if "super_admin" not in user.roles: + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail="仅超级管理员可切换业务运行上下文", + ) + + +def _context_response(ctx: RuntimeContext) -> RuntimeContextResponse: + return RuntimeContextResponse(**ctx.to_dict()) + + +@config_router.get("/runtime-context", response_model=RuntimeContextResponse) +async def get_current_runtime_context( + user: CurrentUser = Depends(get_current_user), +) -> RuntimeContextResponse: + """返回当前登录用户门店的业务运行上下文。""" + return _context_response(get_runtime_context(user.site_id)) + + +@router.get("", response_model=RuntimeContextResponse) +async def get_admin_runtime_context( + site_id: int = Query(..., ge=1), + user: CurrentUser = Depends(get_current_user), +) -> RuntimeContextResponse: + """系统管理端按门店查看业务运行上下文。""" + _require_super_admin(user) + return _context_response(get_runtime_context(site_id)) + + +@router.get("/sites") +async def list_runtime_sites( + user: CurrentUser = Depends(get_current_user), +) -> list[dict]: + """列出可配置门店及其当前运行上下文。""" + _require_super_admin(user) + conn = get_connection() + try: + with conn.cursor(cursor_factory=RealDictCursor) as cur: + cur.execute( + """ + SELECT s.site_id, s.site_name, s.site_code, s.is_active, + c.mode, c.sandbox_date, c.sandbox_instance_id, + c.ai_mode, c.status, c.updated_at + FROM biz.sites s + LEFT JOIN biz.site_runtime_context c ON c.site_id = s.site_id + ORDER BY s.is_active DESC, s.site_id + """ + ) + rows = cur.fetchall() + conn.commit() + except Exception: + conn.rollback() + raise + finally: + conn.close() + + return [dict(row) for row in rows] + + +@router.patch("", response_model=RuntimeSwitchResponse) +async def switch_runtime_context( + body: RuntimeSwitchRequest, + user: CurrentUser = Depends(get_current_user), +) -> RuntimeSwitchResponse: + """切换门店业务运行上下文。 + + 切换前会终止当前运行中的 ETL、取消未完成 AI 触发记录。 + `biz.trigger_jobs` 是全局调度表（无 site_id 列），不随单门店沙箱切换暂停； + 多门店隔离完全通过 runtime_mode + sandbox_instance_id 实现。 + """ + _require_super_admin(user) + + if body.mode == MODE_SANDBOX and body.sandbox_date is None: + raise HTTPException(status_code=422, detail="沙箱模式必须设置 sandbox_date") + if body.mode == MODE_LIVE and body.sandbox_date is not None: + raise HTTPException(status_code=422, detail="live 模式不能设置 sandbox_date") + if body.mode == MODE_SANDBOX and body.sandbox_date and body.sandbox_date > date.today(): + raise HTTPException(status_code=422, detail="sandbox_date 不能晚于真实今天") + + steps: list[RuntimeTransitionStep] = [] + steps.extend(await _stop_runtime_activity(body.site_id)) + + conn = get_connection() + try: + with conn.cursor() as cur: + old_ctx = get_runtime_context(body.site_id, conn=conn) + sandbox_instance_id = None + if body.mode == MODE_SANDBOX: + if body.reset_sandbox or not old_ctx.sandbox_instance_id: + sandbox_instance_id = new_sandbox_instance_id() + else: + sandbox_instance_id = old_ctx.sandbox_instance_id + + cur.execute( + """ + INSERT INTO biz.site_runtime_context + (site_id, mode, sandbox_date, sandbox_instance_id, ai_mode, + status, updated_by, updated_at, reason) + VALUES (%s, %s, %s, %s, 'live', 'active', %s, NOW(), %s) + ON CONFLICT (site_id) + DO UPDATE SET + mode = EXCLUDED.mode, + sandbox_date = EXCLUDED.sandbox_date, + sandbox_instance_id = EXCLUDED.sandbox_instance_id, + ai_mode = EXCLUDED.ai_mode, + status = EXCLUDED.status, + updated_by = EXCLUDED.updated_by, + updated_at = NOW(), + reason = EXCLUDED.reason + """, + ( + body.site_id, + body.mode, + body.sandbox_date, + sandbox_instance_id, + user.user_id, + body.reason, + ), + ) + + steps.append(RuntimeTransitionStep( + key="biz_triggers_unchanged", + title="保持业务触发器", + status="skipped", + count=0, + detail=( + "biz.trigger_jobs 为全局调度表（无 site_id 列），单门店沙箱切换不影响其它门店；" + "沙箱隔离由 runtime_mode + sandbox_instance_id 在数据写入层完成。" + ), + )) + + conn.commit() + except Exception: + conn.rollback() + logger.exception("切换业务运行上下文失败: site_id=%s", body.site_id) + raise + finally: + conn.close() + + ctx = get_runtime_context(body.site_id) + steps.append(RuntimeTransitionStep( + key="apply_context", + title="写入业务运行上下文", + status="success", + detail=( + f"当前模式={ctx.mode}，业务日期={ctx.business_date}" + + (f"，沙箱实例={ctx.sandbox_instance_id}" if ctx.is_sandbox else "") + ), + )) + return RuntimeSwitchResponse(context=_context_response(ctx), steps=steps) + + +async def _stop_runtime_activity(site_id: int) -> list[RuntimeTransitionStep]: + """终止切换前仍在运行的 ETL/AI/队列活动。""" + steps: list[RuntimeTransitionStep] = [] + + # 1. 终止当前进程内 ETL 执行。 + try: + from app.services.task_executor import task_executor + + running_ids = task_executor.get_running_ids() + cancelled = 0 + for execution_id in running_ids: + if await task_executor.cancel(execution_id): + cancelled += 1 + steps.append(RuntimeTransitionStep( + key="cancel_etl_processes", + title="终止当前 ETL 执行", + status="success", + count=cancelled, + detail=f"检测到 {len(running_ids)} 个当前进程内执行，已发送取消信号。", + )) + except Exception as exc: + logger.exception("终止 ETL 执行失败") + steps.append(RuntimeTransitionStep( + key="cancel_etl_processes", + title="终止当前 ETL 执行", + status="warning", + detail=str(exc)[:300], + )) + + # 2. 清理当前门店队列中未完成任务。 + conn = get_connection() + try: + with conn.cursor() as cur: + cur.execute( + """ + UPDATE task_queue + SET status = 'cancelled', + finished_at = NOW(), + error_message = COALESCE(error_message, '') || E'\n[runtime-context] 切换业务运行上下文时取消' + WHERE site_id = %s + AND status IN ('pending', 'running') + """, + (site_id,), + ) + queue_cancelled = cur.rowcount + conn.commit() + steps.append(RuntimeTransitionStep( + key="cancel_task_queue", + title="取消 ETL 队列", + status="success", + count=queue_cancelled, + detail="已取消当前门店 pending/running 的 task_queue 记录。", + )) + except Exception as exc: + conn.rollback() + logger.exception("取消 ETL 队列失败") + steps.append(RuntimeTransitionStep( + key="cancel_task_queue", + title="取消 ETL 队列", + status="warning", + detail=str(exc)[:300], + )) + finally: + conn.close() + + # 3. 取消当前站点内存 AI 调用链，并标记未完成 ai_trigger_jobs。 + try: + from app.ai.dispatcher import get_dispatcher + + dispatcher = get_dispatcher() + cancelled = dispatcher.cancel_running(site_id) + steps.append(RuntimeTransitionStep( + key="cancel_ai_runtime", + title="取消当前 AI 调用链", + status="success", + count=cancelled, + detail="已取消当前进程内属于该门店的 AI 异步调用链。", + )) + except Exception as exc: + steps.append(RuntimeTransitionStep( + key="cancel_ai_runtime", + title="取消当前 AI 调用链", + status="warning", + detail=f"AI Dispatcher 不可用或取消失败：{str(exc)[:240]}", + )) + + conn = get_connection() + try: + with conn.cursor() as cur: + cur.execute( + """ + UPDATE biz.ai_trigger_jobs + SET status = 'cancelled', + finished_at = NOW(), + error_message = COALESCE(error_message, '') || E'\n[runtime-context] 切换业务运行上下文时取消' + WHERE site_id = %s + AND status IN ('pending', 'running') + """, + (site_id,), + ) + ai_cancelled = cur.rowcount + conn.commit() + steps.append(RuntimeTransitionStep( + key="cancel_ai_jobs", + title="标记未完成 AI 触发", + status="success", + count=ai_cancelled, + detail="已将当前门店 pending/running 的 ai_trigger_jobs 标记为 cancelled。", + )) + except Exception as exc: + conn.rollback() + logger.exception("标记 AI 触发失败") + steps.append(RuntimeTransitionStep( + key="cancel_ai_jobs", + title="标记未完成 AI 触发", + status="warning", + detail=str(exc)[:300], + )) + finally: + conn.close() + + return steps + diff --git a/apps/backend/app/routers/admin_task_engine.py b/apps/backend/app/routers/admin_task_engine.py index 0847cfe..84e2a85 100644 --- a/apps/backend/app/routers/admin_task_engine.py +++ b/apps/backend/app/routers/admin_task_engine.py @@ -310,6 +310,24 @@ async def reassign_task( ) conn.commit() + + # 触发 AI 任务分配链（App4 → App5） + try: + from app.services.trigger_scheduler import fire_event + fire_event( + "ai_task_assigned", + { + "site_id": task["site_id"], + "member_id": task["member_id"], + "assistant_id": body.to_assistant_id, + }, + ) + except Exception: + logger.exception( + "触发 ai_task_assigned 事件失败: task_id=%s new_task_id=%s", + task_id, new_task_id, + ) + return ReassignResponse(success=True, new_task_id=new_task_id) except HTTPException: conn.rollback() diff --git a/apps/backend/app/routers/internal_events.py b/apps/backend/app/routers/internal_events.py index 6345157..3a8275c 100644 --- a/apps/backend/app/routers/internal_events.py +++ b/apps/backend/app/routers/internal_events.py @@ -85,6 +85,33 @@ async def etl_completed_endpoint( logger.exception("ETL 编排 Step2 task_generator 失败") errors.append("task_generator failed") + # Step 3: 触发 AI 财务洞察预生成（App2 × 8 时间维度） + # 若请求未带 site_id，查询所有 active site 逐个触发 + try: + from app.services.trigger_scheduler import fire_event + + site_ids: list[int] = [] + if body.site_id is not None: + site_ids = [body.site_id] + else: + from app.database import get_connection as _gc + _c = _gc() + try: + with _c.cursor() as _cur: + _cur.execute("SELECT DISTINCT site_id FROM biz.trigger_jobs WHERE site_id IS NOT NULL") + site_ids = [r[0] for r in _cur.fetchall()] + _c.commit() + finally: + _c.close() + + for sid in site_ids: + try: + fire_event("ai_dws_completed", {"site_id": sid}) + except Exception: + logger.exception("触发 ai_dws_completed 失败: site_id=%s", sid) + except Exception: + logger.exception("ai_dws_completed 事件批量触发失败") + success = len(errors) == 0 return EtlCompletedResponse( success=success, diff --git a/apps/backend/app/routers/tenant_users.py b/apps/backend/app/routers/tenant_users.py index d40b4fc..a143b58 100644 --- a/apps/backend/app/routers/tenant_users.py +++ b/apps/backend/app/routers/tenant_users.py @@ -204,13 +204,17 @@ async def list_site_staff( # assumptions: cfg_assistant_level_price 有 level_code→level_name 映射 # verify: 弹窗人员下拉显示如 "初级 - 张三 - 手机号 - 入职日期 YYYY-MM-DD" # 先查等级映射配置表（feiqiu-data-rules 规则 6: 禁止硬编码） + # CHANGE 2026-05-02 | 用 business_date 替代 CURRENT_DATE，沙箱按当时生效配置 + from app.services.runtime_context import as_runtime_today_param + _ref_date = as_runtime_today_param(site_id) cur.execute( """ SELECT DISTINCT level_code, level_name FROM dws.cfg_assistant_level_price - WHERE effective_from <= CURRENT_DATE - AND effective_to >= CURRENT_DATE - """ + WHERE effective_from <= %s::date + AND effective_to >= %s::date + """, + (_ref_date, _ref_date), ) level_map = {row[0]: row[1] for row in cur.fetchall()} diff --git a/apps/backend/app/routers/xcx_chat.py b/apps/backend/app/routers/xcx_chat.py index e92dfa7..bbe85f5 100644 --- a/apps/backend/app/routers/xcx_chat.py +++ b/apps/backend/app/routers/xcx_chat.py @@ -244,27 +244,56 @@ async def chat_stream( ) # 流式调用 DashScope Application API - async for chunk in client.call_app_stream( + # 返回 (text_chunk, session_id_or_none) 元组：累积最后一次 session_id 用于回写 + latest_session_id: str | None = session_id + async for chunk_text, chunk_session_id in client.call_app_stream( app_id=config.app_id_1_chat, prompt=prompt, session_id=session_id, biz_params=biz_params, ): - full_reply_parts.append(chunk) + if chunk_session_id: + latest_session_id = chunk_session_id + if not chunk_text: + continue + full_reply_parts.append(chunk_text) tokens_total += 1 # SSE trace: 每 10 个 token 记录一次 record_sse_token(token_count=1, total_tokens=tokens_total) - yield f"event: message\ndata: {json.dumps({'token': chunk}, ensure_ascii=False)}\n\n" + yield f"event: message\ndata: {json.dumps({'token': chunk_text}, ensure_ascii=False)}\n\n" # 流结束：拼接完整回复并持久化 full_reply = "".join(full_reply_parts) estimated_tokens = len(full_reply) + # Phase 1.3：assistant 消息挂 reference_card（若用户从特定详情页入口发起对话） + try: + from app.ai.references import build_app1_reference_card + _ref_card = None + _pc = body.page_context or {} + _ctx_id = _pc.get("contextId") or _pc.get("taskId") or _pc.get("customerId") or _pc.get("coachId") + if body.source_page and _ctx_id: + _ref_card = build_app1_reference_card(body.source_page, _ctx_id) + except Exception: + logger.warning("构建 reference_card 失败", exc_info=True) + _ref_card = None + ai_msg_id, ai_created_at = svc._save_message( - body.chat_id, "assistant", full_reply, tokens_used=estimated_tokens, + body.chat_id, "assistant", full_reply, + tokens_used=estimated_tokens, + reference_card=_ref_card, ) svc._update_session_metadata(body.chat_id, full_reply) + # multi-turn 启用：回写百炼返回的 session_id（若首次对话或服务端更新） + if latest_session_id and latest_session_id != session_id: + try: + svc.save_session_id(body.chat_id, latest_session_id) + except Exception: + logger.warning( + "save_session_id 失败 chat_id=%s", body.chat_id, exc_info=True, + ) + # 发送 done 事件 done_data = json.dumps( {"messageId": ai_msg_id, "createdAt": ai_created_at}, diff --git a/apps/backend/app/routers/xcx_runtime_clock.py b/apps/backend/app/routers/xcx_runtime_clock.py new file mode 100644 index 0000000..c72e3c2 --- /dev/null +++ b/apps/backend/app/routers/xcx_runtime_clock.py @@ -0,0 +1,61 @@ +# -*- coding: utf-8 -*- +"""小程序业务时钟路由。 + +仅用于小程序读取当前门店的"业务日 / 业务年月 / 模式"——sandbox 模式下， +小程序的 performance / task-list / customer-records 等页面应以 RuntimeContext +返回的业务时钟为准，禁止再用 ``new Date()`` 构造请求参数。 + +端点： +- GET /api/xcx/runtime/clock — 返回当前门店的业务时钟与运行模式（live / sandbox）。 + +所有端点均需 JWT（approved 状态），但不要求特定模块权限。 +""" + +from __future__ import annotations + +from fastapi import APIRouter, Depends + +from app.auth.dependencies import CurrentUser +from app.middleware.permission import require_approved +from app.services.runtime_context import get_runtime_context +from app.trace.decorators import trace_service + +router = APIRouter(prefix="/api/xcx/runtime", tags=["小程序业务时钟"]) + + +@router.get("/clock") +@trace_service("获取业务时钟", "Get business clock") +async def get_business_clock( + user: CurrentUser = Depends(require_approved), +): + """返回当前门店的业务时钟。 + + 返回示例（live）:: + + { + "mode": "live", + "business_date": "2026-05-02", + "business_year": 2026, + "business_month": 5, + "business_year_month": "2026-05", + "is_sandbox": false, + "sandbox_date": null + } + + sandbox 模式下 ``business_date`` 等于配置的 ``sandbox_date``。 + 小程序页面应使用本接口结果替代 ``new Date()``，以确保 sandbox 模式下 + 展示和请求都对齐到 sandbox_date。 + """ + ctx = get_runtime_context(user.site_id) + bd = ctx.business_date + return { + "mode": ctx.mode, + "business_date": bd.isoformat(), + "business_year": bd.year, + "business_month": bd.month, + "business_year_month": f"{bd.year:04d}-{bd.month:02d}", + "business_now": ctx.business_now.isoformat(), + "is_sandbox": ctx.is_sandbox, + "sandbox_date": ctx.sandbox_date.isoformat() if ctx.sandbox_date else None, + "sandbox_instance_id": ctx.sandbox_instance_id, + } diff --git a/apps/backend/app/schemas/admin_ai.py b/apps/backend/app/schemas/admin_ai.py index be25532..5adf5d9 100644 --- a/apps/backend/app/schemas/admin_ai.py +++ b/apps/backend/app/schemas/admin_ai.py @@ -196,6 +196,37 @@ class BatchRunConfirmResponse(BaseModel): status: str # "started" +# ── 按需单 App 执行（/run/{app_type}）────────────────────── + + +class RunAppRequest(BaseModel): + """按需执行单个 App 请求体。 + + context 字段根据 app_type 不同有不同约束： + - app2_finance: site_id + time_dimension + area（area 默认 all） + - app3_clue / app7_customer: site_id + member_id + - app4_analysis / app5_tactics: site_id + member_id + assistant_id + - app6_note: site_id + member_id + note_content + noted_by_name + - app8_consolidation: site_id + member_id + """ + site_id: int + member_id: int | None = None + assistant_id: int | None = None + time_dimension: str | None = None + area: str | None = None # App2 专用，默认 all + note_content: str | None = None + noted_by_name: str | None = None + noted_by_created_at: str | None = None + + +class RunAppResponse(BaseModel): + """按需执行单个 App 响应。""" + app_type: str + success: bool + result: dict | None = None # 百炼返回的 JSON（成功时） + error: str | None = None # 错误描述（失败时） + + # ── 告警 ────────────────────────────────────────────────── @@ -211,3 +242,64 @@ class AlertActionResponse(BaseModel): """告警操作（确认/忽略）响应。""" id: int alert_status: str + + +# ── 触发器管理（biz.trigger_jobs）───────────────────────── + + +class TriggerItem(BaseModel): + """触发器单条记录。""" + id: int + job_name: str + job_type: str + trigger_condition: str # event / cron / interval + trigger_config: dict # {"event_name": ...} 或 {"cron_expression": ...} + status: str # enabled / disabled + description: str | None = None + last_run_at: str | None = None + next_run_at: str | None = None + last_error: str | None = None + + +class TriggerUpdateRequest(BaseModel): + """触发器更新请求（3 个字段至少填一个）。""" + status: str | None = None # enabled / disabled + cron_expression: str | None = None # 标准 5 段 cron + description: str | None = None + + +# ── 预热进度（app2_finance 72 组合）─────────────────────── + + +class PrewarmMissingItem(BaseModel): + """缺失的预热组合项。""" + target_id: str # this_month__all + time_dimension: str + area: str + + +class PrewarmProgressResponse(BaseModel): + """app2_finance 预热进度响应。""" + total: int # 固定 72 + done: int + missing: list[PrewarmMissingItem] + last_updated: str | None = None + + +# ── 手动事件触发（越过去重）─────────────────────────────── + + +class ManualTriggerRequest(BaseModel): + """手动触发 AI 事件请求。""" + event_type: str # consumption / dws_completed / note_created / task_assigned + site_id: int + member_id: int | None = None + assistant_id: int | None = None + payload: dict | None = None + is_forced: bool = True # 默认跳过去重 + + +class ManualTriggerResponse(BaseModel): + """手动事件触发响应。""" + trigger_job_id: int + status: str = "pending" diff --git a/apps/backend/app/schemas/runtime_context.py b/apps/backend/app/schemas/runtime_context.py new file mode 100644 index 0000000..5a0e053 --- /dev/null +++ b/apps/backend/app/schemas/runtime_context.py @@ -0,0 +1,48 @@ +# -*- coding: utf-8 -*- +"""业务运行上下文 API Schema。""" + +from __future__ import annotations + +from datetime import date, datetime +from typing import Literal + +from pydantic import BaseModel, Field + + +RuntimeMode = Literal["live", "sandbox"] +AIMode = Literal["live"] + + +class RuntimeContextResponse(BaseModel): + site_id: int + mode: RuntimeMode + business_day_start_hour: int + business_date: date + business_now: datetime + sandbox_date: date | None = None + sandbox_instance_id: str | None = None + ai_mode: AIMode = "live" + status: str = "active" + is_sandbox: bool = False + + +class RuntimeTransitionStep(BaseModel): + key: str + title: str + status: Literal["success", "skipped", "warning", "failed"] + detail: str = "" + count: int = 0 + + +class RuntimeSwitchRequest(BaseModel): + site_id: int = Field(..., ge=1) + mode: RuntimeMode + sandbox_date: date | None = None + reset_sandbox: bool = True + reason: str | None = Field(default=None, max_length=500) + + +class RuntimeSwitchResponse(BaseModel): + context: RuntimeContextResponse + steps: list[RuntimeTransitionStep] + diff --git a/apps/backend/app/services/ai/admin_service.py b/apps/backend/app/services/ai/admin_service.py index b060f38..7da0ccd 100644 --- a/apps/backend/app/services/ai/admin_service.py +++ b/apps/backend/app/services/ai/admin_service.py @@ -35,9 +35,21 @@ class AdminAIService: # ── Dashboard ───────────────────────────────────────── - async def get_dashboard(self, site_id: int | None = None) -> dict: - """聚合所有 Dashboard 数据。""" - today_stats = await self._get_today_stats(site_id) + async def get_dashboard( + self, + site_id: int | None = None, + range_days: int | None = None, + date_from: str | None = None, + date_to: str | None = None, + ) -> dict: + """聚合所有 Dashboard 数据。 + + 时间范围优先级： + 1. 若 date_from / date_to 同时给出（指定日期）→ 闭区间 [from, to] + 2. 若 range_days=N → [CURRENT_DATE - (N-1) days, 现在] + 3. 默认 range_days=1（今日） + """ + today_stats = await self._get_range_stats(site_id, range_days, date_from, date_to) trend_7d = await self._get_7d_trend(site_id) app_dist = await self._get_app_distribution(site_id) app_health = await self._get_app_health(site_id) @@ -52,9 +64,32 @@ class AdminAIService: "app_health": app_health, } - async def _get_today_stats(self, site_id: int | None) -> dict: - """今日调用次数、成功率、Token 消耗、平均延迟。""" - site_clause, params = _site_filter(site_id) + async def _get_range_stats( + self, + site_id: int | None, + range_days: int | None, + date_from: str | None, + date_to: str | None, + ) -> dict: + """指定时间段内的调用次数、成功率、Token 消耗、平均延迟。 + + 字段名沿用 today_* 前缀以兼容前端 DashboardResponse schema。 + """ + site_clause, site_params = _site_filter(site_id) + + if date_from and date_to: + time_clause = "created_at >= %s::date AND created_at < (%s::date + INTERVAL '1 day')" + time_params: tuple = (date_from, date_to) + else: + days = range_days if range_days and range_days > 0 else 1 + time_clause = ( + "created_at >= CURRENT_DATE - (%s::int - 1) * INTERVAL '1 day' " + "AND created_at < CURRENT_DATE + INTERVAL '1 day'" + ) + time_params = (days,) + + params = time_params + site_params + conn = get_connection() try: with conn.cursor() as cur: @@ -67,8 +102,7 @@ class AdminAIService: COALESCE(AVG(latency_ms) FILTER (WHERE latency_ms IS NOT NULL), 0) AS avg_latency FROM biz.ai_run_logs - WHERE created_at >= CURRENT_DATE - AND created_at < CURRENT_DATE + INTERVAL '1 day' + WHERE {time_clause} {site_clause} """, params, @@ -466,6 +500,22 @@ class AdminAIService: finally: conn.close() + # Phase 1.4：广播 cache_invalidated 事件，admin-web / 小程序可实时刷新 + if affected > 0: + try: + from app.ai.event_bus import AIEvent, get_event_bus + get_event_bus().publish(AIEvent( + type="cache_invalidated", + site_id=site_id, + payload={ + "cache_type": app_type, + "member_id": member_id, + "affected": affected, + }, + )) + except Exception: + logger.debug("cache_invalidated 事件广播失败", exc_info=True) + return affected # ── Token 预算 ──────────────────────────────────────── @@ -699,6 +749,140 @@ class AdminAIService: return "ignored" + # ── 触发器管理（biz.trigger_jobs）─────────────────────── + + async def list_triggers(self) -> list[dict]: + """列出所有 AI 相关触发器（job_type 以 ai_ 开头 + task_generator）。 + + 返回字段：id / job_name / job_type / trigger_condition / trigger_config / + status / description / last_run_at / next_run_at / last_error + """ + conn = get_connection() + try: + with conn.cursor() as cur: + cur.execute( + """ + SELECT id, job_name, job_type, trigger_condition, + trigger_config, status, description, + last_run_at, next_run_at, last_error + FROM biz.trigger_jobs + WHERE job_type LIKE 'ai_%' OR job_name = 'task_generator' + ORDER BY trigger_condition DESC, job_name + """ + ) + cols = [d[0] for d in cur.description] + rows = cur.fetchall() + conn.commit() + finally: + conn.close() + return [_row_to_dict(cols, r) for r in rows] + + async def update_trigger( + self, trigger_id: int, + status_new: str | None = None, + cron_expression: str | None = None, + description: str | None = None, + ) -> dict: + """更新触发器：启用/禁用、修改 cron、改描述。 + + 仅允许修改 ai_ 前缀或 task_generator 的触发器。 + """ + if status_new is not None and status_new not in ("enabled", "disabled"): + raise ValueError(f"非法 status: {status_new}") + + sets: list[str] = [] + params: list = [] + if status_new is not None: + sets.append("status = %s") + params.append(status_new) + if cron_expression is not None: + sets.append("trigger_config = jsonb_set(trigger_config, '{cron_expression}', to_jsonb(%s::text))") + params.append(cron_expression) + if description is not None: + sets.append("description = %s") + params.append(description) + + if not sets: + raise ValueError("至少修改一个字段") + + params.append(trigger_id) + conn = get_connection() + try: + with conn.cursor() as cur: + cur.execute( + f""" + UPDATE biz.trigger_jobs + SET {", ".join(sets)} + WHERE id = %s + AND (job_type LIKE 'ai_%%' OR job_name = 'task_generator') + RETURNING id, job_name, job_type, trigger_condition, + trigger_config, status, description, + last_run_at, next_run_at, last_error + """, + params, + ) + row = cur.fetchone() + if row is None: + conn.rollback() + raise ValueError("触发器不存在或不可修改") + cols = [d[0] for d in cur.description] + conn.commit() + except Exception: + conn.rollback() + raise + finally: + conn.close() + return _row_to_dict(cols, row) + + # ── 预热进度（app2_finance 72 组合）────────────────────── + + async def get_prewarm_progress(self, site_id: int) -> dict: + """查询 app2_finance 72 组合缓存进度。 + + 返回：total=72, done=N, missing=[{time_dimension, area}], last_updated + """ + time_dims = ( + "this_month", "last_month", "this_week", "last_week", + "this_quarter", "last_quarter", "last_3_months", "last_6_months", + ) + areas = ( + "all", "hall", "hallA", "hallB", "hallC", + "vip", "snooker", "mahjong", "ktv", + ) + expected = {f"{t}__{a}" for t in time_dims for a in areas} + + conn = get_connection() + try: + with conn.cursor() as cur: + cur.execute( + """ + SELECT target_id, max(created_at) AS last_updated + FROM biz.ai_cache + WHERE cache_type = 'app2_finance' + AND site_id = %s + AND target_id LIKE %s ESCAPE '\\' + GROUP BY target_id + """, + (site_id, r'%\_\_%'), + ) + rows = cur.fetchall() + conn.commit() + finally: + conn.close() + + done_map = {r[0]: r[1] for r in rows} + missing = sorted(expected - set(done_map.keys())) + last = max(done_map.values()) if done_map else None + return { + "total": len(expected), + "done": len(expected & set(done_map.keys())), + "missing": [ + {"target_id": m, "time_dimension": m.split("__")[0], "area": m.split("__")[1]} + for m in missing + ], + "last_updated": last.isoformat() if last else None, + } + # ── 工具函数 ────────────────────────────────────────────── diff --git a/apps/backend/app/services/board_service.py b/apps/backend/app/services/board_service.py index fe8337a..ebeef31 100644 --- a/apps/backend/app/services/board_service.py +++ b/apps/backend/app/services/board_service.py @@ -195,6 +195,7 @@ from typing import Any from fastapi import HTTPException from app.services import fdw_queries +from app.services.runtime_context import get_runtime_context, task_runtime_filter logger = logging.getLogger(__name__) @@ -260,7 +261,8 @@ async def get_coach_board( detail="最近6个月不支持客源储值排序", ) - start_date, end_date = _calc_date_range(time) + runtime_ctx = get_runtime_context(site_id) + start_date, end_date = _calc_date_range(time, ref_date=runtime_ctx.business_date) start_str = str(start_date) end_str = str(end_date) @@ -415,20 +417,22 @@ def _query_coach_tasks( result: dict[int, dict] = {} try: + runtime_clause, runtime_params = task_runtime_filter(site_id, conn=conn) with conn.cursor() as cur: # 狭义召回+回访完成数：均从 coach_tasks 统计，status='completed' 表示助教亲自完成 cur.execute( - """ + f""" SELECT assistant_id, task_type, COUNT(*) AS cnt FROM biz.coach_tasks WHERE assistant_id = ANY(%s) AND site_id = %s + {runtime_clause} AND completed_at >= %s::date AND completed_at < (%s::date + INTERVAL '1 day')::timestamptz AND status = 'completed' GROUP BY assistant_id, task_type """, - (assistant_ids, site_id, start_date, end_date), + [assistant_ids, site_id, *runtime_params, start_date, end_date], ) for row in cur.fetchall(): aid, task_type, cnt = row[0], row[1], row[2] or 0 @@ -470,13 +474,27 @@ def _batch_ideal_days(conn: Any, site_id: int, member_ids: list[int]) -> dict[in return result -def _batch_coach_details(conn: Any, site_id: int, member_ids: list[int]) -> dict[int, list[dict]]: - """批量查询客户-助教服务明细（loyal 维度 coachDetails 用）。每个客户前 5 个。""" +def _batch_coach_details( + conn: Any, + site_id: int, + member_ids: list[int], + *, + ref_date: date | None = None, +) -> dict[int, list[dict]]: + """批量查询客户-助教服务明细（loyal 维度 coachDetails 用）。每个客户前 5 个。 + + ref_date 默认从 RuntimeContext 取业务日，用于把 60 天消费窗口的上界落到 ``ref_date`` 上， + 避免 sandbox 模式下读到 sandbox_date 之后的真实消费。 + """ from app.services.fdw_queries import _fdw_context + from app.services.runtime_context import as_runtime_today_param + + ref = ref_date or as_runtime_today_param(site_id, conn=conn) result: dict[int, list[dict]] = {mid: [] for mid in member_ids} try: with _fdw_context(conn, site_id) as cur: # CHANGE 2026-03-29 | coach_spend 改为从 dwd_assistant_service_log 聚合 60 天消费 + # CHANGE 2026-05-02 | 用 ref_date（业务日）替代 CURRENT_DATE，沙箱不读「未来」 cur.execute( """ SELECT ri.member_id, @@ -493,7 +511,8 @@ def _batch_coach_details(conn: Any, site_id: int, member_ids: list[int]) -> dict SUM(ledger_amount) AS spend_60d FROM app.v_dwd_assistant_service_log WHERE is_delete = 0 - AND create_time >= CURRENT_DATE - INTERVAL '60 days' + AND create_time >= (%s::date - INTERVAL '60 days') + AND create_time < (%s::date + INTERVAL '1 day') AND tenant_member_id = ANY(%s) GROUP BY tenant_member_id, site_assistant_id ) s60 ON ri.member_id = s60.tenant_member_id @@ -502,7 +521,7 @@ def _batch_coach_details(conn: Any, site_id: int, member_ids: list[int]) -> dict AND (da.leave_status IS NULL OR da.leave_status = 0) ORDER BY ri.member_id, ri.rs_display DESC """, - (member_ids, member_ids), + (ref, ref, member_ids, member_ids), ) for row in cur.fetchall(): mid = row[0] @@ -690,7 +709,8 @@ async def get_finance_board( - area≠all 时 overview 覆盖逻辑保留 - compare=1 时对上期执行同样缓存/日粒度逻辑 """ - start_date, end_date = _calc_date_range(time) + runtime_ctx = get_runtime_context(site_id) + start_date, end_date = _calc_date_range(time, ref_date=runtime_ctx.business_date) start_str = str(start_date) end_str = str(end_date) diff --git a/apps/backend/app/services/chat_service.py b/apps/backend/app/services/chat_service.py index c457156..5d0b2da 100644 --- a/apps/backend/app/services/chat_service.py +++ b/apps/backend/app/services/chat_service.py @@ -234,23 +234,14 @@ class ChatService: INSERT INTO biz.ai_conversations (user_id, nickname, app_id, site_id, context_type, context_id) VALUES (%s, %s, %s, %s, %s, %s) - RETURNING id, EXTRACT(EPOCH FROM created_at)::bigint + RETURNING id """, (str(user_id), nickname, APP_ID, site_id, context_type, context_id), ) - result = cur.fetchone() - new_id = result[0] - created_ts = result[1] - - # 生成 session_id 并回写（格式：conv_{id}_{timestamp}） - session_id = f"conv_{new_id}_{created_ts}" - cur.execute( - """ - UPDATE biz.ai_conversations SET session_id = %s WHERE id = %s - """, - (session_id, new_id), - ) + new_id = cur.fetchone()[0] + # session_id 初始保持 NULL，首次对话由百炼返回后再回写。 + # 参见 P14 spec §2.3：后端不再自生 session_id，交由百炼云端管理。 conn.commit() return new_id except Exception: @@ -274,6 +265,34 @@ class ChatService: finally: conn.close() + @trace_service("保存百炼 session_id", "Save bailian session ID") + def save_session_id(self, chat_id: int, session_id: str) -> None: + """流式回复完成后，将百炼返回的 session_id 回写 ai_conversations。 + + multi-turn 启用： + - 首次对话 session_id=NULL → 百炼分配新 session → 这里回写 + - 下次对话 get_session_id 返回该值 → 传给百炼关联历史上下文 + + 幂等：同一对话多次调用覆盖最新 session_id（通常保持稳定）。 + """ + if not session_id: + return + conn = get_connection() + try: + with conn.cursor() as cur: + cur.execute( + "UPDATE biz.ai_conversations SET session_id = %s WHERE id = %s", + (session_id, chat_id), + ) + conn.commit() + except Exception: + conn.rollback() + logger.warning( + "保存 session_id 失败: chat_id=%s", chat_id, exc_info=True, + ) + finally: + conn.close() + # ------------------------------------------------------------------ # CHAT-2: 消息列表 # ------------------------------------------------------------------ @@ -662,7 +681,10 @@ class ChatService: """查询客户近 30 天消费金额（items_sum 口径）。 ⚠️ DWD-DOC 规则 1: 使用 ledger_amount（items_sum 口径），禁用 consume_money。 + CHANGE 2026-05-02 | 用 business_date 替代 CURRENT_DATE，沙箱不读「未来」消费。 """ + from app.services.runtime_context import as_runtime_today_param + ref = as_runtime_today_param(site_id, conn=conn) with fdw_queries._fdw_context(conn, site_id) as cur: cur.execute( """ @@ -670,16 +692,22 @@ class ChatService: FROM app.v_dwd_assistant_service_log WHERE tenant_member_id = %s AND is_delete = 0 - AND create_time >= (CURRENT_DATE - INTERVAL '30 days')::timestamptz + AND create_time >= (%s::date - INTERVAL '30 days')::timestamptz + AND create_time < (%s::date + INTERVAL '1 day')::timestamptz """, - (member_id,), + (member_id, ref, ref), ) row = cur.fetchone() return Decimal(str(row[0])) if row and row[0] is not None else None @staticmethod def _get_visit_count_30d(conn: Any, site_id: int, member_id: int) -> int | None: - """查询客户近 30 天到店次数。""" + """查询客户近 30 天到店次数。 + + CHANGE 2026-05-02 | 用 business_date 替代 CURRENT_DATE，沙箱不读「未来」到店。 + """ + from app.services.runtime_context import as_runtime_today_param + ref = as_runtime_today_param(site_id, conn=conn) with fdw_queries._fdw_context(conn, site_id) as cur: cur.execute( """ @@ -687,9 +715,10 @@ class ChatService: FROM app.v_dwd_assistant_service_log WHERE tenant_member_id = %s AND is_delete = 0 - AND create_time >= (CURRENT_DATE - INTERVAL '30 days')::timestamptz + AND create_time >= (%s::date - INTERVAL '30 days')::timestamptz + AND create_time < (%s::date + INTERVAL '1 day')::timestamptz """, - (member_id,), + (member_id, ref, ref), ) row = cur.fetchone() return int(row[0]) if row and row[0] is not None else None diff --git a/apps/backend/app/services/coach_service.py b/apps/backend/app/services/coach_service.py index fa4bf63..bb5d712 100644 --- a/apps/backend/app/services/coach_service.py +++ b/apps/backend/app/services/coach_service.py @@ -147,7 +147,9 @@ async def get_coach_detail(coach_id: int, site_id: int) -> dict: if not assistant_info: raise HTTPException(status_code=404, detail="助教不存在") - now = datetime.date.today() + # 业务时间锚：sandbox 模式下用 business_date，避免读到 sandbox_date 之后真实绩效 + from app.services.runtime_context import as_runtime_today_param + now = as_runtime_today_param(site_id, conn=conn) # 门店名称（用于小程序 banner 展示，跟随被查看助教所在门店） # 必须在所有 fdw 查询前执行：后续任意 fdw 查询失败会污染事务 @@ -713,7 +715,9 @@ def _build_history_months( 4. 本月 estimated=True，历史月份 estimated=False 5. 格式化：customers→"22人"，hours→"87.5h"，salary→"¥6,950" """ - now = datetime.date.today() + # 业务时间锚：sandbox 模式下用 business_date 计算最近 6 个月 + from app.services.runtime_context import as_runtime_today_param + now = as_runtime_today_param(site_id, conn=conn) # 生成最近 6 个月的月份列表（含本月） months: list[str] = [] diff --git a/apps/backend/app/services/customer_service.py b/apps/backend/app/services/customer_service.py index 593c72b..4d3da71 100644 --- a/apps/backend/app/services/customer_service.py +++ b/apps/backend/app/services/customer_service.py @@ -501,6 +501,9 @@ def _build_coach_tasks( logger.warning("批量查询助教信息失败", exc_info=True) # 批量查询 60 天统计（一次 FDW 查询） + # CHANGE 2026-05-02 | 用 business_date 替代 CURRENT_DATE，沙箱不读「未来」 + from app.services.runtime_context import as_runtime_today_param + ref_date = as_runtime_today_param(site_id, conn=conn) stats_map: dict = {} try: with fdw_queries._fdw_context(conn, site_id) as cur: @@ -513,10 +516,11 @@ def _build_coach_tasks( WHERE tenant_member_id = %s AND site_assistant_id = ANY(%s) AND is_delete = 0 - AND create_time >= CURRENT_DATE - INTERVAL '60 days' + AND create_time >= (%s::date - INTERVAL '60 days')::timestamptz + AND create_time < (%s::date + INTERVAL '1 day')::timestamptz GROUP BY site_assistant_id """, - (customer_id, assistant_ids), + (customer_id, assistant_ids, ref_date, ref_date), ) for row in cur.fetchall(): svc = int(row[1]) if row[1] else 0 diff --git a/apps/backend/app/services/fdw_queries.py b/apps/backend/app/services/fdw_queries.py index ce87f96..ef27905 100644 --- a/apps/backend/app/services/fdw_queries.py +++ b/apps/backend/app/services/fdw_queries.py @@ -80,7 +80,7 @@ def _get_etl_connection(site_id: int): @contextmanager def _fdw_context(conn: Any, site_id: int, *, etl_conn: Any = None): """ - 上下文管理器：直连 ETL 库 + SET LOCAL app.current_site_id。 + 上下文管理器：直连 ETL 库 + SET LOCAL app.current_site_id + app.current_business_date。 ⚠️ 不使用 zqyy_app 的 fdw_etl.* foreign table，而是直连 ETL 库 查询 app.v_* RLS 视图。原因：postgres_fdw 不传递自定义 GUC 参数 @@ -91,7 +91,31 @@ def _fdw_context(conn: Any, site_id: int, *, etl_conn: Any = None): CHANGE 2026-03-26 | ETL 连接复用：传入 etl_conn 时复用已有连接（不关闭）， 不传时新建连接并在 yield 后自动关闭。避免同一请求内多次新建连接（每次 ~2.6s）。 + CHANGE 2026-05-02 | 同时设置 app.current_business_date / app.current_runtime_mode， + 供 RLS 视图层（C 方案）做日期上界裁剪。conn=None 时降级 live。 """ + from app.services.runtime_context import ( + MODE_LIVE, + MODE_SANDBOX, + get_runtime_context, + ) + + # 业务日：优先从 zqyy_app 业务库的 RuntimeContext 读取；conn 不可用时降级为系统今天 + bd_str = "" + rt_mode = MODE_LIVE + try: + if conn is not None: + ctx = get_runtime_context(site_id, conn=conn) + bd_str = ctx.business_date.isoformat() + rt_mode = MODE_SANDBOX if ctx.is_sandbox else MODE_LIVE + else: + from datetime import date as _date + bd_str = _date.today().isoformat() + except Exception: + from datetime import date as _date + bd_str = _date.today().isoformat() + rt_mode = MODE_LIVE + owned = etl_conn is None if owned: etl_conn = _get_etl_connection(site_id) @@ -99,6 +123,8 @@ def _fdw_context(conn: Any, site_id: int, *, etl_conn: Any = None): with etl_conn.cursor() as cur: cur.execute("BEGIN") cur.execute("SET LOCAL app.current_site_id = %s", (str(site_id),)) + cur.execute("SET LOCAL app.current_business_date = %s", (bd_str,)) + cur.execute("SET LOCAL app.current_runtime_mode = %s", (rt_mode,)) yield cur etl_conn.commit() finally: @@ -180,33 +206,53 @@ def get_last_visit_days( """ 批量查询客户距上次到店天数。 - 来源: app.v_dws_member_consumption_summary.days_since_last（基于结算单）。 - FIX: 原查 v_dwd_assistant_service_log 导致无助教服务的客户缺失到店记录。 + 来源: app.v_dws_member_consumption_summary。 consumption_summary 按 stat_date 有多行快照，取最新一行。 + CHANGE 2026-05-02 | 修复客户看板「最近到店」数据不准的问题： + - 旧版直接用 days_since_last（ETL 在 stat_date 那天预计算的快照值）。 + 若 ETL 没跑、跑得迟、或 sandbox_date 与 stat_date 不一致，结果就会严重失真。 + - 新版改为实时计算：``business_date - last_consume_date``， + 仅取 ``stat_date <= business_date`` 的快照行，沙箱模式下也能拿到一致结果。 + 返回 {member_id: days_since_visit} 映射，无记录的会员不在结果中。 """ if not member_ids: return {} + from app.services.runtime_context import as_runtime_today_param + + ref_date = as_runtime_today_param(site_id, conn=conn) + result: dict[int, int | None] = {} with _fdw_context(conn, site_id, etl_conn=etl_conn) as cur: cur.execute( """ - SELECT member_id, days_since_last + SELECT DISTINCT ON (member_id) + member_id, + last_consume_date, + stat_date FROM app.v_dws_member_consumption_summary WHERE member_id = ANY(%s) - AND days_since_last IS NOT NULL + AND stat_date <= %s ORDER BY member_id, stat_date DESC """, - (member_ids,), + (member_ids, ref_date), ) - seen: set[int] = set() for row in cur.fetchall(): mid = row[0] - if mid not in seen: - seen.add(mid) - result[mid] = row[1] + last_consume = row[1] + if last_consume is None: + result[mid] = None + continue + try: + # last_consume_date 在 DWS 中是 date；少数实现可能给 timestamp，统一裁剪 + if hasattr(last_consume, "date"): + last_consume = last_consume.date() + days = (ref_date - last_consume).days + result[mid] = max(days, 0) + except Exception: + result[mid] = None return result @@ -420,22 +466,33 @@ def batch_query_for_task_list( # 3. 最后到店天数（基于消费汇总表，口径=结算单） # FIX: 原查 v_dwd_assistant_service_log 导致无助教服务的客户缺失到店记录 + # CHANGE 2026-05-02 | 实时按 business_date - last_consume_date 计算， + # 不再依赖 ETL 预计算的 days_since_last（解决看板显示偏差）。 + from app.services.runtime_context import as_runtime_today_param + _ref_date = as_runtime_today_param(site_id, conn=conn) cur.execute( """ - SELECT member_id, days_since_last + SELECT DISTINCT ON (member_id) + member_id, last_consume_date, stat_date FROM app.v_dws_member_consumption_summary WHERE member_id = ANY(%s) - AND days_since_last IS NOT NULL + AND stat_date <= %s ORDER BY member_id, stat_date DESC """, - (member_ids,), + (member_ids, _ref_date), ) - seen_members: set[int] = set() for row in cur.fetchall(): mid = row[0] - if mid not in seen_members: - seen_members.add(mid) - last_visit_map[mid] = row[1] + last_consume = row[1] + if last_consume is None: + last_visit_map[mid] = None + continue + try: + if hasattr(last_consume, "date"): + last_consume = last_consume.date() + last_visit_map[mid] = max((_ref_date - last_consume).days, 0) + except Exception: + last_visit_map[mid] = None # 4. RS 指数 cur.execute( @@ -486,10 +543,11 @@ def batch_query_for_task_list( WHERE sl.site_assistant_id = %s AND sl.tenant_member_id = ANY(%s) AND sl.is_delete = 0 - AND sl.create_time >= (CURRENT_DATE - INTERVAL '60 days')::timestamptz + AND sl.create_time >= (%s::date - INTERVAL '60 days')::timestamptz + AND sl.create_time < (%s::date + INTERVAL '1 day')::timestamptz GROUP BY sl.tenant_member_id """, - (assistant_id, member_ids), + (assistant_id, member_ids, _ref_date, _ref_date), ) for row in cur.fetchall(): recent60d_map[row[0]] = { @@ -559,15 +617,19 @@ def batch_query_for_task_list( # 8. 绩效档位配置（用于构建 tier_nodes + bonus_money 计算） # CHANGE 2026-03-24 | 增加 bonus_deduction_ratio 用于打赏课抽成差额计算 + # CHANGE 2026-05-02 | 用 business_date 替代 CURRENT_DATE，沙箱按当时生效档位 + from app.services.runtime_context import as_runtime_today_param as _rt_today + _ref_date = _rt_today(site_id, conn=conn) cur.execute( """ SELECT tier_id, tier_code, tier_name, tier_level, min_hours, max_hours, base_deduction, bonus_deduction_ratio FROM app.v_cfg_performance_tier - WHERE effective_from <= CURRENT_DATE - AND effective_to >= CURRENT_DATE + WHERE effective_from <= %s::date + AND effective_to >= %s::date ORDER BY tier_level - """ + """, + (_ref_date, _ref_date), ) tier_rows = cur.fetchall() performance_tiers = [ @@ -640,17 +702,21 @@ def get_performance_tiers( 返回 [{tier_id, tier_code, tier_name, tier_level, min_hours, max_hours, base_deduction, bonus_deduction_ratio}, ...]。 + CHANGE 2026-05-02 | 用 business_date 替代 CURRENT_DATE，沙箱按当时生效档位 """ + from app.services.runtime_context import as_runtime_today_param as _rt_today + ref_date = _rt_today(site_id, conn=conn) with _fdw_context(conn, site_id) as cur: cur.execute( """ SELECT tier_id, tier_code, tier_name, tier_level, min_hours, max_hours, base_deduction, bonus_deduction_ratio FROM app.v_cfg_performance_tier - WHERE effective_from <= CURRENT_DATE - AND effective_to >= CURRENT_DATE + WHERE effective_from <= %s::date + AND effective_to >= %s::date ORDER BY tier_level - """ + """, + (ref_date, ref_date), ) rows = cur.fetchall() @@ -680,15 +746,18 @@ def get_level_map(conn: Any, site_id: int) -> dict[int, str]: 查询失败时返回空 dict（调用方应优雅降级）。 """ try: + from app.services.runtime_context import as_runtime_today_param as _rt_today + ref_date = _rt_today(site_id, conn=conn) with _fdw_context(conn, site_id) as cur: cur.execute( """ SELECT DISTINCT level_code, level_name FROM app.v_cfg_assistant_level_price - WHERE effective_from <= CURRENT_DATE - AND effective_to >= CURRENT_DATE + WHERE effective_from <= %s::date + AND effective_to >= %s::date ORDER BY level_code - """ + """, + (ref_date, ref_date), ) return {row[0]: row[1] for row in cur.fetchall()} except Exception: @@ -1198,8 +1267,11 @@ def get_coach_60d_stats( 来源: app.v_dwd_assistant_service_log。 ⚠️ 废单排除: is_delete = 0。 + CHANGE 2026-05-02 | 用 business_date 替代 CURRENT_DATE，沙箱不读「未来」60 天。 返回 {service_count, total_hours, avg_hours}。 """ + from app.services.runtime_context import as_runtime_today_param + ref_date = as_runtime_today_param(site_id, conn=conn) with _fdw_context(conn, site_id) as cur: cur.execute( """ @@ -1212,9 +1284,10 @@ def get_coach_60d_stats( WHERE site_assistant_id = %s AND tenant_member_id = %s AND is_delete = 0 - AND create_time >= (CURRENT_DATE - INTERVAL '60 days')::timestamptz + AND create_time >= (%s::date - INTERVAL '60 days')::timestamptz + AND create_time < (%s::date + INTERVAL '1 day')::timestamptz """, - (assistant_id, member_id), + (assistant_id, member_id, ref_date, ref_date), ) row = cur.fetchone() if not row: @@ -1917,14 +1990,17 @@ def get_customer_board_recall( total = cur.fetchone()[0] # 分页数据 + # CHANGE 2026-05-02 | elapsed_days/overdue_days 用 business_date 替代 CURRENT_DATE + from app.services.runtime_context import as_runtime_today_param as _rt_today + ref_date = _rt_today(site_id, conn=conn) offset = (page - 1) * page_size cur.execute( f""" SELECT wi.member_id, dm.nickname, wi.ideal_interval_days, - CURRENT_DATE - wi.last_visit_time::date AS elapsed_days, - (CURRENT_DATE - wi.last_visit_time::date) - COALESCE(wi.ideal_interval_days, 0) AS overdue_days, + %s::date - wi.last_visit_time::date AS elapsed_days, + (%s::date - wi.last_visit_time::date) - COALESCE(wi.ideal_interval_days, 0) AS overdue_days, wi.visits_30d, wi.display_score, COALESCE(ca.balance, 0) AS balance @@ -1937,11 +2013,11 @@ def get_customer_board_recall( WHERE scd2_is_current = 1 GROUP BY tenant_member_id ) ca ON wi.member_id = ca.tenant_member_id - WHERE 1=1 {proj_clause} + WHERE wi.last_visit_time <= %s::date + INTERVAL '1 day' {proj_clause} ORDER BY wi.display_score DESC, wi.member_id LIMIT %s OFFSET %s """, - (*proj_params, page_size, offset), + (ref_date, ref_date, ref_date, *proj_params, page_size, offset), ) items = [] for row in cur.fetchall(): @@ -2165,6 +2241,10 @@ def get_customer_board_recharge( ) total = cur.fetchone()[0] + # CHANGE 2026-05-02 | 60 天充值窗口、stat_date、pay_time 全部按 business_date 截断 + from app.services.runtime_context import as_runtime_today_param + ref_date = as_runtime_today_param(site_id, conn=conn) + offset = (page - 1) * page_size cur.execute( f""" @@ -2173,7 +2253,8 @@ def get_customer_board_recharge( MAX(ro.pay_time::date) AS last_recharge_date, SUM(ro.pay_amount) AS recharge_amount, COUNT(*) FILTER ( - WHERE ro.pay_time >= CURRENT_DATE - INTERVAL '60 days' + WHERE ro.pay_time >= %s::date - INTERVAL '60 days' + AND ro.pay_time < %s::date + INTERVAL '1 day' ) AS recharges_60d, COALESCE(ca_agg.balance, 0) AS current_balance, cs.days_since_last @@ -2190,15 +2271,16 @@ def get_customer_board_recharge( SELECT cs2.days_since_last FROM app.v_dws_member_consumption_summary cs2 WHERE cs2.member_id = ro.member_id + AND cs2.stat_date <= %s ORDER BY cs2.stat_date DESC LIMIT 1 ) cs ON true - WHERE 1=1 {proj_clause} + WHERE ro.pay_time <= %s::date + INTERVAL '1 day' {proj_clause} GROUP BY ro.member_id, dm.nickname, ca_agg.balance, cs.days_since_last ORDER BY MAX(ro.pay_time::date) DESC, ro.member_id LIMIT %s OFFSET %s """, - (*proj_params, page_size, offset), + (ref_date, ref_date, ref_date, ref_date, *proj_params, page_size, offset), ) items = [] for row in cur.fetchall(): @@ -2228,6 +2310,13 @@ def get_customer_board_recent( 不再硬编码为 0。来源: v_dws_member_visit_detail + v_dim_member + v_dws_member_winback_index。 按 last_visit_date 降序。 """ + # CHANGE 2026-05-02 | 客户看板「最近到店」修复： + # 1) WHERE/COUNT 中的 30/60 天窗口按 business_date 计算，沙箱不读「未来」到店； + # 2) days_ago 用 business_date - last_visit_date，与窗口对齐。 + from app.services.runtime_context import as_runtime_today_param + + ref_date = as_runtime_today_param(site_id, conn=conn) + proj_clause, proj_params = _project_filter_clause(project, "vd.member_id") with _fdw_context(conn, site_id) as cur: @@ -2235,9 +2324,9 @@ def get_customer_board_recent( f""" SELECT COUNT(DISTINCT vd.member_id) FROM app.v_dws_member_visit_detail vd - WHERE 1=1 {proj_clause} + WHERE vd.visit_date <= %s {proj_clause} """, - proj_params, + (ref_date, *proj_params), ) total = cur.fetchone()[0] @@ -2248,11 +2337,11 @@ def get_customer_board_recent( SELECT vd.member_id, MAX(vd.visit_date) AS last_visit_date, COUNT(*) AS total_visits, - COUNT(*) FILTER (WHERE vd.visit_date >= CURRENT_DATE - INTERVAL '30 days') AS visits_30d, - COUNT(*) FILTER (WHERE vd.visit_date >= CURRENT_DATE - INTERVAL '60 days') AS visits_60d, + COUNT(*) FILTER (WHERE vd.visit_date >= %s::date - INTERVAL '30 days') AS visits_30d, + COUNT(*) FILTER (WHERE vd.visit_date >= %s::date - INTERVAL '60 days') AS visits_60d, AVG(vd.total_consume) AS avg_spend FROM app.v_dws_member_visit_detail vd - WHERE 1=1 {proj_clause} + WHERE vd.visit_date <= %s {proj_clause} GROUP BY vd.member_id ) SELECT ma.member_id, @@ -2271,14 +2360,13 @@ def get_customer_board_recent( ORDER BY ma.last_visit_date DESC, ma.member_id LIMIT %s OFFSET %s """, - (*proj_params, page_size, offset), + (ref_date, ref_date, ref_date, *proj_params, page_size, offset), ) items = [] for row in cur.fetchall(): last_visit = row[2] - # CHANGE 2026-03-29 | 补充 days_ago（距今天数）和 visits_60d - from datetime import date as _date - days_ago = (_date.today() - last_visit).days if last_visit else None + # CHANGE 2026-05-02 | days_ago 按 business_date 计算，沙箱与窗口对齐 + days_ago = (ref_date - last_visit).days if last_visit else None items.append({ "member_id": row[0], "name": row[1] or "", @@ -2378,6 +2466,10 @@ def get_customer_board_freq60( 按 visit_count_60d 降序。 CHANGE 2026-04-08 | Fix：同 spend60，DISTINCT ON 取最新快照。 """ + # CHANGE 2026-05-02 | freq60 全链路按 business_date 截断（stat_date <= ref_date + 8 周窗口） + from app.services.runtime_context import as_runtime_today_param + ref_date = as_runtime_today_param(site_id, conn=conn) + proj_clause, proj_params = _project_filter_clause(project, "cs.member_id") with _fdw_context(conn, site_id) as cur: @@ -2387,11 +2479,11 @@ def get_customer_board_freq60( FROM ( SELECT DISTINCT ON (cs.member_id) cs.member_id FROM app.v_dws_member_consumption_summary cs - WHERE 1=1 {proj_clause} + WHERE cs.stat_date <= %s {proj_clause} ORDER BY cs.member_id, cs.stat_date DESC ) sub """, - proj_params, + (ref_date, *proj_params), ) total = cur.fetchone()[0] @@ -2402,7 +2494,7 @@ def get_customer_board_freq60( SELECT DISTINCT ON (cs.member_id) cs.member_id, cs.visit_count_60d, cs.consume_amount_60d FROM app.v_dws_member_consumption_summary cs - WHERE 1=1 {proj_clause} + WHERE cs.stat_date <= %s {proj_clause} ORDER BY cs.member_id, cs.stat_date DESC ) SELECT cs.member_id, @@ -2415,7 +2507,7 @@ def get_customer_board_freq60( ORDER BY cs.visit_count_60d DESC, cs.member_id LIMIT %s OFFSET %s """, - (*proj_params, page_size, offset), + (ref_date, *proj_params, page_size, offset), ) items = [] member_ids = [] @@ -2436,21 +2528,31 @@ def get_customer_board_freq60( # 批量查询 8 周到店数据 if member_ids: - weekly_map = _get_weekly_visits_batch(cur, member_ids) + weekly_map = _get_weekly_visits_batch(cur, member_ids, ref_date=ref_date) for item in items: item["weekly_visits"] = weekly_map.get(item["member_id"], _empty_weekly()) return {"items": items, "total": total, "page": page, "page_size": page_size} -def _get_weekly_visits_batch(cur: Any, member_ids: list[int]) -> dict[int, list[dict]]: +def _get_weekly_visits_batch( + cur: Any, member_ids: list[int], *, ref_date: Any = None, +) -> dict[int, list[dict]]: """ 批量查询客户最近 8 周的到店次数（用于 freq60 维度柱状图）。 CHANGE 2026-04-07 | Fix-5：数据源从 v_dwd_assistant_service_log 改为 v_dwd_settlement_head（settle_type IN (1,3)），与汇总维度口径一致。 + CHANGE 2026-05-02 | 8 周窗口锚定 ref_date（业务日），沙箱不读「未来」。 返回 {member_id: [{val: int, pct: int}, ...]}，固定 8 个元素。 """ + from datetime import date as _date, timedelta as _timedelta + + if ref_date is None: + ref_date = _date.today() + elif hasattr(ref_date, "date") and not isinstance(ref_date, _date): + ref_date = ref_date.date() + cur.execute( """ WITH weekly AS ( @@ -2460,14 +2562,15 @@ def _get_weekly_visits_batch(cur: Any, member_ids: list[int]) -> dict[int, list[ FROM app.v_dwd_settlement_head WHERE member_id = ANY(%s) AND settle_type IN (1, 3) - AND pay_time >= CURRENT_DATE - INTERVAL '56 days' + AND pay_time >= %s::date - INTERVAL '56 days' + AND pay_time < %s::date + INTERVAL '1 day' GROUP BY member_id, DATE_TRUNC('week', pay_time::date) ) SELECT member_id, week_start, cnt FROM weekly ORDER BY member_id, week_start """, - (member_ids,), + (member_ids, ref_date, ref_date), ) from collections import defaultdict @@ -2477,11 +2580,9 @@ def _get_weekly_visits_batch(cur: Any, member_ids: list[int]) -> dict[int, list[ week_key = row[1].date() if hasattr(row[1], 'date') else row[1] raw[row[0]][str(week_key)] = row[2] - # 生成最近 8 周的周一日期 - from datetime import date, timedelta - today = date.today() - this_monday = today - timedelta(days=today.weekday()) - weeks = [this_monday - timedelta(weeks=i) for i in range(7, -1, -1)] + # 生成最近 8 周的周一日期，以业务日为锚 + this_monday = ref_date - _timedelta(days=ref_date.weekday()) + weeks = [this_monday - _timedelta(weeks=i) for i in range(7, -1, -1)] result: dict[int, list[dict]] = {} for mid in member_ids: diff --git a/apps/backend/app/services/note_service.py b/apps/backend/app/services/note_service.py index 0d1ba36..d46acf9 100644 --- a/apps/backend/app/services/note_service.py +++ b/apps/backend/app/services/note_service.py @@ -259,6 +259,28 @@ async def create_note( import asyncio asyncio.create_task(_async_ai_score(note["id"], site_id, target_id, content)) + # 触发 AI 备注分析链（App6 → App8） + # target_type='member' 时 target_id 即 member_id；'assistant' 时不触发（AI 只分析会员备注） + if target_type == "member": + try: + from app.services.trigger_scheduler import fire_event + fire_event( + "ai_note_created", + { + "site_id": site_id, + "member_id": target_id, + "note_content": content, + "noted_by_name": note.get("recorded_by_name") + or note.get("user_nickname") or "", + "noted_by_created_at": note.get("created_at") or "", + }, + ) + except Exception: + logger.exception( + "触发 ai_note_created 事件失败: note_id=%s member_id=%s", + note["id"], target_id, + ) + return note except HTTPException: diff --git a/apps/backend/app/services/recall_detector.py b/apps/backend/app/services/recall_detector.py index 09d0e9c..0365329 100644 --- a/apps/backend/app/services/recall_detector.py +++ b/apps/backend/app/services/recall_detector.py @@ -22,6 +22,13 @@ import json import logging from datetime import timedelta +from app.services.runtime_context import ( + LIVE_INSTANCE_ID, + MODE_LIVE, + MODE_SANDBOX, + get_runtime_context, + task_runtime_filter, +) from app.trace.decorators import trace_service logger = logging.getLogger(__name__) @@ -141,6 +148,10 @@ def _process_site(conn, site_id: int) -> dict: resolved = 0 from app.services.fdw_queries import _fdw_context + runtime_ctx = get_runtime_context(site_id, conn=conn) + runtime_now = runtime_ctx.business_now + runtime_mode = MODE_SANDBOX if runtime_ctx.is_sandbox else MODE_LIVE + sandbox_instance_id = runtime_ctx.sandbox_instance_id if runtime_ctx.is_sandbox else LIVE_INSTANCE_ID # ── 1. 获取本门店所有 MAIN 关系对 ── with _fdw_context(conn, site_id) as cur: @@ -173,13 +184,14 @@ def _process_site(conn, site_id: int) -> dict: ON sl.order_settle_id = sh.order_settle_id AND sl.is_delete = 0 WHERE sh.member_id = ANY(%s) + AND sh.pay_time <= %s AND ( sh.settle_type = 1 OR (sh.settle_type = 3 AND sl.order_assistant_type = 2) ) GROUP BY sl.site_assistant_id, sh.member_id """, - (member_ids,), + (member_ids, runtime_now), ) for row in cur.fetchall(): settlement_map[(row[0], row[1])] = row[2] @@ -190,6 +202,7 @@ def _process_site(conn, site_id: int) -> dict: SELECT sh.member_id, MAX(sh.pay_time) AS latest_pay_time FROM app.v_dwd_settlement_head sh WHERE sh.member_id = ANY(%s) + AND sh.pay_time <= %s AND ( sh.settle_type = 1 OR (sh.settle_type = 3 AND EXISTS ( @@ -201,7 +214,7 @@ def _process_site(conn, site_id: int) -> dict: ) GROUP BY sh.member_id """, - (member_ids,), + (member_ids, runtime_now), ) member_visited_map = {} for row in cur.fetchall(): @@ -209,16 +222,18 @@ def _process_site(conn, site_id: int) -> dict: # ── 3. 获取本门店所有 active 的召回/回访任务（用于匹配） ── active_tasks_map: dict[tuple[int, int], list] = {} # (assistant_id, member_id) → [(id, task_type, created_at)] + runtime_clause, runtime_params = task_runtime_filter(site_id, conn=conn) with conn.cursor() as cur: cur.execute( - """ + f""" SELECT id, assistant_id, member_id, task_type, created_at FROM biz.coach_tasks WHERE site_id = %s + {runtime_clause} AND status = 'active' AND task_type IN ('high_priority_recall', 'priority_recall', 'follow_up_visit') """, - (site_id,), + [site_id, *runtime_params], ) for row in cur.fetchall(): key = (row[1], row[2]) @@ -238,7 +253,7 @@ def _process_site(conn, site_id: int) -> dict: try: result = _process_pair( conn, site_id, assistant_id, member_id, - latest_pay, active_tasks, + latest_pay, active_tasks, runtime_now, runtime_mode, sandbox_instance_id, ) completed += result["completed"] events += result["events"] @@ -257,25 +272,26 @@ def _process_site(conn, site_id: int) -> dict: with conn.cursor() as cur: cur.execute("BEGIN") cur.execute( - """ + f""" SELECT id, assistant_id, task_type, created_at FROM biz.coach_tasks WHERE site_id = %s AND member_id = %s + {runtime_clause} AND status = 'active' AND task_type IN ('high_priority_recall', 'priority_recall') AND created_at < %s """, - (site_id, member_id, pay_time), + [site_id, member_id, *runtime_params, pay_time], ) remaining = cur.fetchall() for task_id, aid, task_type, _ in remaining: cur.execute( """ UPDATE biz.coach_tasks - SET status = 'resolved', updated_at = NOW() + SET status = 'resolved', updated_at = %s WHERE id = %s AND status = 'active' """, - (task_id,), + (runtime_now, task_id), ) _insert_history( cur, task_id, @@ -308,6 +324,9 @@ def _process_pair( member_id: int, latest_pay_time, active_tasks: list[dict], + runtime_now, + runtime_mode: str, + sandbox_instance_id: str, ) -> dict: """ 处理单个 MAIN 关系对的召回检测。 @@ -339,14 +358,16 @@ def _process_pair( cur.execute( """ INSERT INTO biz.recall_events - (site_id, assistant_id, member_id, pay_time, task_id, task_type) - VALUES (%s, %s, %s, %s, %s, %s) - ON CONFLICT (site_id, assistant_id, member_id, (date_trunc('day', pay_time AT TIME ZONE 'Asia/Shanghai'))) + (site_id, assistant_id, member_id, pay_time, task_id, task_type, + created_at, runtime_mode, sandbox_instance_id) + VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s) + ON CONFLICT (site_id, assistant_id, member_id, runtime_mode, sandbox_instance_id, + (date_trunc('day', pay_time AT TIME ZONE 'Asia/Shanghai'))) DO NOTHING RETURNING id """, (site_id, assistant_id, member_id, latest_pay_time, - event_task_id, event_task_type), + event_task_id, event_task_type, runtime_now, runtime_mode, sandbox_instance_id), ) inserted = cur.fetchone() if inserted is None: @@ -367,10 +388,10 @@ def _process_pair( completed_at = %s, completed_task_type = %s, completion_type = 'auto', - updated_at = NOW() + updated_at = %s WHERE id = %s AND status = 'active' """, - (latest_pay_time, task["task_type"], task["id"]), + (latest_pay_time, task["task_type"], runtime_now, task["id"]), ) _insert_history( cur, @@ -393,18 +414,19 @@ def _process_pair( SELECT id FROM biz.coach_tasks WHERE site_id = %s AND assistant_id = %s AND member_id = %s AND task_type = 'follow_up_visit' AND status = 'active' + AND runtime_mode = %s AND sandbox_instance_id = %s """, - (site_id, assistant_id, member_id), + (site_id, assistant_id, member_id, runtime_mode, sandbox_instance_id), ) old_follow_ups = cur.fetchall() for (old_id,) in old_follow_ups: cur.execute( """ UPDATE biz.coach_tasks - SET status = 'inactive', updated_at = NOW() + SET status = 'inactive', updated_at = %s WHERE id = %s """, - (old_id,), + (runtime_now, old_id), ) _insert_history( cur, old_id, @@ -423,11 +445,14 @@ def _process_pair( """ INSERT INTO biz.coach_tasks (site_id, assistant_id, member_id, task_type, status, - expires_at, created_at, updated_at) - VALUES (%s, %s, %s, 'follow_up_visit', 'active', %s, NOW(), NOW()) + expires_at, created_at, updated_at, runtime_mode, sandbox_instance_id) + VALUES (%s, %s, %s, 'follow_up_visit', 'active', %s, %s, %s, %s, %s) RETURNING id """, - (site_id, assistant_id, member_id, expires_at), + ( + site_id, assistant_id, member_id, expires_at, runtime_now, + runtime_now, runtime_mode, sandbox_instance_id, + ), ) new_follow_up_id = cur.fetchone()[0] _insert_history( diff --git a/apps/backend/app/services/runtime_context.py b/apps/backend/app/services/runtime_context.py new file mode 100644 index 0000000..e36ab11 --- /dev/null +++ b/apps/backend/app/services/runtime_context.py @@ -0,0 +1,263 @@ +# -*- coding: utf-8 -*- +"""业务运行上下文与业务时钟服务。 + +该模块是开发/测试沙箱的统一控制层： +- live 模式：沿用真实系统日期和正式数据。 +- sandbox 模式：业务上假设今天是配置的历史日期，并用 sandbox_instance_id 隔离写入。 +""" + +from __future__ import annotations + +import uuid +from dataclasses import dataclass +from datetime import date, datetime, time, timedelta, timezone +from typing import Any + +from app import config + +_LOCAL_TZ = timezone(timedelta(hours=8)) +MODE_LIVE = "live" +MODE_SANDBOX = "sandbox" +AI_MODE_LIVE = "live" +LIVE_INSTANCE_ID = "live" + + +@dataclass(frozen=True) +class RuntimeContext: + """单门店当前业务运行上下文。""" + + site_id: int + mode: str = MODE_LIVE + business_day_start_hour: int = config.BUSINESS_DAY_START_HOUR + sandbox_date: date | None = None + sandbox_instance_id: str | None = None + ai_mode: str = AI_MODE_LIVE + status: str = "active" + + @property + def is_sandbox(self) -> bool: + return self.mode == MODE_SANDBOX and self.sandbox_date is not None + + @property + def business_date(self) -> date: + if self.is_sandbox and self.sandbox_date is not None: + return self.sandbox_date + now = datetime.now(_LOCAL_TZ) + today = now.date() + if now.hour < self.business_day_start_hour: + return today - timedelta(days=1) + return today + + @property + def business_now(self) -> datetime: + if not self.is_sandbox: + return datetime.now(_LOCAL_TZ) + now = datetime.now(_LOCAL_TZ) + return datetime.combine(self.business_date, now.timetz(), tzinfo=_LOCAL_TZ) + + @property + def active_sandbox_instance_id(self) -> str | None: + if not self.is_sandbox: + return None + return self.sandbox_instance_id + + def to_dict(self) -> dict[str, Any]: + return { + "site_id": self.site_id, + "mode": self.mode, + "business_day_start_hour": self.business_day_start_hour, + "business_date": self.business_date.isoformat(), + "business_now": self.business_now.isoformat(), + "sandbox_date": self.sandbox_date.isoformat() if self.sandbox_date else None, + "sandbox_instance_id": self.sandbox_instance_id, + "ai_mode": self.ai_mode, + "status": self.status, + "is_sandbox": self.is_sandbox, + } + + +def new_sandbox_instance_id() -> str: + """生成新的沙箱实例 ID。""" + return f"sbx_{uuid.uuid4().hex[:24]}" + + +def _default_context(site_id: int) -> RuntimeContext: + return RuntimeContext(site_id=site_id) + + +def get_runtime_context(site_id: int, conn: Any | None = None) -> RuntimeContext: + """读取门店运行上下文。 + + 表不存在或未配置时降级为 live，保证迁移前不影响正式链路。 + """ + own_conn = conn is None + if own_conn: + from app.database import get_connection + + conn = get_connection() + + try: + with conn.cursor() as cur: + try: + cur.execute( + """ + SELECT mode, sandbox_date, sandbox_instance_id, ai_mode, status + FROM biz.site_runtime_context + WHERE site_id = %s + """, + (site_id,), + ) + except Exception: + if own_conn: + conn.rollback() + return _default_context(site_id) + + row = cur.fetchone() + if own_conn: + conn.commit() + finally: + if own_conn: + conn.close() + + if not row: + return _default_context(site_id) + + mode, sandbox_date, sandbox_instance_id, ai_mode, status = row + if mode not in (MODE_LIVE, MODE_SANDBOX): + mode = MODE_LIVE + if mode == MODE_SANDBOX and (sandbox_date is None or not sandbox_instance_id): + mode = MODE_LIVE + + return RuntimeContext( + site_id=site_id, + mode=mode, + sandbox_date=sandbox_date, + sandbox_instance_id=sandbox_instance_id, + ai_mode=ai_mode or AI_MODE_LIVE, + status=status or "active", + ) + + +def namespace_ai_target_id(site_id: int, target_id: str, conn: Any | None = None) -> str: + """按当前上下文转换 AI cache target_id。 + + 前端和调用方继续使用原始 target_id；沙箱命名空间在后端统一处理。 + """ + ctx = get_runtime_context(site_id, conn=conn) + if not ctx.is_sandbox or not ctx.sandbox_instance_id: + return target_id + return f"{ctx.sandbox_instance_id}:{target_id}" + + +def task_runtime_filter( + site_id: int, + *, + alias: str = "", + conn: Any | None = None, +) -> tuple[str, list[Any]]: + """返回 coach_tasks 等表的运行上下文过滤条件。""" + ctx = get_runtime_context(site_id, conn=conn) + prefix = f"{alias}." if alias else "" + if ctx.is_sandbox and ctx.sandbox_instance_id: + return ( + f" AND {prefix}runtime_mode = %s AND {prefix}sandbox_instance_id = %s", + [MODE_SANDBOX, ctx.sandbox_instance_id], + ) + return ( + f" AND COALESCE({prefix}runtime_mode, 'live') = %s " + f"AND COALESCE({prefix}sandbox_instance_id, %s) = %s", + [MODE_LIVE, LIVE_INSTANCE_ID, LIVE_INSTANCE_ID], + ) + + +def runtime_insert_columns(site_id: int, conn: Any | None = None) -> tuple[str, str, list[Any]]: + """返回 INSERT SQL 片段：列名、占位符和值。""" + ctx = get_runtime_context(site_id, conn=conn) + return ( + "runtime_mode, sandbox_instance_id", + "%s, %s", + [ + MODE_SANDBOX if ctx.is_sandbox else MODE_LIVE, + ctx.sandbox_instance_id if ctx.is_sandbox else LIVE_INSTANCE_ID, + ], + ) + + +def runtime_update_assignments(site_id: int, conn: Any | None = None) -> tuple[str, list[Any]]: + """返回 UPDATE SQL 片段，用于把运行上下文写回已有记录。""" + ctx = get_runtime_context(site_id, conn=conn) + return ( + "runtime_mode = %s, sandbox_instance_id = %s", + [ + MODE_SANDBOX if ctx.is_sandbox else MODE_LIVE, + ctx.sandbox_instance_id if ctx.is_sandbox else LIVE_INSTANCE_ID, + ], + ) + + +def as_runtime_now_param(site_id: int, conn: Any | None = None) -> datetime: + """返回可传给 SQL 的业务当前时间。""" + return get_runtime_context(site_id, conn=conn).business_now + + +def as_runtime_today_param(site_id: int, conn: Any | None = None) -> date: + """返回可传给 SQL 的业务当前日期。""" + return get_runtime_context(site_id, conn=conn).business_date + + +def as_runtime_year_month_param(site_id: int, conn: Any | None = None) -> str: + """返回 'YYYY-MM' 形式的业务年月，用于 performance 等月度查询。""" + bd = get_runtime_context(site_id, conn=conn).business_date + return f"{bd.year:04d}-{bd.month:02d}" + + +def as_runtime_business_now_str(site_id: int, conn: Any | None = None, fmt: str = "%Y-%m-%d %H:%M:%S") -> str: + """返回业务当前时间的格式化字符串，用于 AI prompts 中的 current_time。""" + return get_runtime_context(site_id, conn=conn).business_now.strftime(fmt) + + +def business_date_upper_bound_sql( + site_id: int, + *, + column: str, + alias: str = "", + cast: str | None = None, + conn: Any | None = None, +) -> tuple[str, list[Any]]: + """返回业务日上界 SQL 片段。 + + sandbox 模式下，强制把 ``column`` 限制在业务日及之前（避免读到「未来」数据）。 + live 模式下返回空片段，不影响任何逻辑。 + + cast 用于把 timestamp/timestamptz 列裁剪成日期再比较，例如 ``cast='date'``。 + """ + ctx = get_runtime_context(site_id, conn=conn) + if not ctx.is_sandbox: + return ("", []) + prefix = f"{alias}." if alias else "" + expr = f"{prefix}{column}" + if cast: + expr = f"({expr})::{cast}" + return (f" AND {expr} <= %s", [ctx.business_date]) + + +def apply_runtime_session_vars(conn: Any, ctx: RuntimeContext | None = None, *, site_id: int | None = None) -> None: + """在已有数据库连接上设置 ``app.current_business_date`` 等 GUC 变量。 + + 供 RLS 视图层（C 方案）使用：视图通过 ``current_setting('app.current_business_date', true)`` + 读取业务日，再对事实/维度表做日期上界裁剪。 + + 无论 live / sandbox 都设置该变量；live 下视图仍按真实 ``CURRENT_DATE`` 行为。 + """ + if ctx is None: + if site_id is None: + raise ValueError("apply_runtime_session_vars 需要 ctx 或 site_id 之一") + ctx = get_runtime_context(site_id, conn=conn) + bd = ctx.business_date.isoformat() + mode = MODE_SANDBOX if ctx.is_sandbox else MODE_LIVE + with conn.cursor() as cur: + cur.execute( + "SELECT set_config('app.current_business_date', %s, true), " + "set_config('app.current_runtime_mode', %s, true)", + (bd, mode), + ) diff --git a/apps/backend/app/services/task_expiry.py b/apps/backend/app/services/task_expiry.py index f5d7def..ae5bd65 100644 --- a/apps/backend/app/services/task_expiry.py +++ b/apps/backend/app/services/task_expiry.py @@ -11,6 +11,7 @@ import json import logging +from app.services.runtime_context import as_runtime_now_param, task_runtime_filter from app.trace.decorators import trace_service logger = logging.getLogger(__name__) @@ -71,32 +72,42 @@ def run() -> dict: conn = _get_connection() try: - # 查询所有已过期的 active 任务 + # 查询所有已过期的 active 任务。沙箱模式按业务时间判断，并只处理当前运行实例。 + expired_tasks = [] with conn.cursor() as cur: - cur.execute( - """ - SELECT id, task_type - FROM biz.coach_tasks - WHERE expires_at IS NOT NULL - AND expires_at < NOW() - AND status = 'active' - """ - ) - expired_tasks = cur.fetchall() + cur.execute("SELECT site_id FROM biz.sites WHERE is_active = true") + site_ids = [row[0] for row in cur.fetchall()] + for site_id in site_ids: + runtime_now = as_runtime_now_param(site_id, conn=conn) + runtime_clause, runtime_params = task_runtime_filter(site_id, conn=conn) + cur.execute( + f""" + SELECT id, task_type, site_id + FROM biz.coach_tasks + WHERE site_id = %s + {runtime_clause} + AND expires_at IS NOT NULL + AND expires_at < %s + AND status = 'active' + """, + [site_id, *runtime_params, runtime_now], + ) + expired_tasks.extend(cur.fetchall()) conn.commit() # 逐条处理，每条独立事务 - for task_id, task_type in expired_tasks: + for task_id, task_type, site_id in expired_tasks: try: + runtime_now = as_runtime_now_param(site_id, conn=conn) with conn.cursor() as cur: cur.execute("BEGIN") cur.execute( """ UPDATE biz.coach_tasks - SET status = 'inactive', updated_at = NOW() + SET status = 'inactive', updated_at = %s WHERE id = %s AND status = 'active' """, - (task_id,), + (runtime_now, task_id), ) _insert_history( cur, diff --git a/apps/backend/app/services/task_generator.py b/apps/backend/app/services/task_generator.py index a274987..cc65253 100644 --- a/apps/backend/app/services/task_generator.py +++ b/apps/backend/app/services/task_generator.py @@ -41,6 +41,13 @@ from dataclasses import dataclass from enum import IntEnum from app.trace.decorators import trace_service +from app.services.runtime_context import ( + LIVE_INSTANCE_ID, + MODE_LIVE, + MODE_SANDBOX, + get_runtime_context, + task_runtime_filter, +) class TaskPriority(IntEnum): @@ -189,6 +196,14 @@ import logging logger = logging.getLogger(__name__) +def _runtime_values(conn, site_id: int): + """返回当前门店任务写入所需的运行上下文值。""" + ctx = get_runtime_context(site_id, conn=conn) + mode = MODE_SANDBOX if ctx.is_sandbox else MODE_LIVE + instance_id = ctx.sandbox_instance_id if ctx.is_sandbox else LIVE_INSTANCE_ID + return ctx, mode, instance_id, ctx.business_now + + def _get_connection(): """延迟导入 get_connection，避免纯函数测试时触发模块级导入失败。""" from app.database import get_connection @@ -210,7 +225,10 @@ def run() -> dict: 返回: {"created": int, "replaced": int, "skipped": int, "transferred": int} """ + from datetime import datetime, timezone + stats = {"created": 0, "replaced": 0, "skipped": 0, "transferred": 0} + run_started_at = datetime.now(timezone.utc) conn = _get_connection() try: @@ -265,6 +283,14 @@ def run() -> dict: ) conn.commit() + # ── 6. 触发 AI 消费事件 — 对本次 run 新建的任务逐个触发 ai_consumption_settled + # 仅按 created_at >= run_started_at 过滤（精确锁定本次新建），避免误触发历史任务。 + # dispatcher 内部按 (event, member_id, site_id, date) 去重，重复触发无害。 + try: + _fire_ai_consumption_events(conn, run_started_at) + except Exception: + logger.exception("ai_consumption_settled 事件触发失败（不影响任务生成主流程）") + finally: conn.close() @@ -278,6 +304,54 @@ def run() -> dict: return stats +def _fire_ai_consumption_events(conn, run_started_at) -> None: + """查询本次 run 新建的任务，对每条 (site_id, member_id, assistant_id) 触发 ai_consumption_settled。 + + has_assistant 恒为 True（任务必然绑定助教）。 + dispatcher 去重确保每 member 每天 AI 链路至多跑一次。 + """ + from app.services.trigger_scheduler import fire_event + + with conn.cursor() as cur: + cur.execute( + """ + SELECT DISTINCT site_id, member_id, assistant_id + FROM biz.coach_tasks + WHERE created_at >= %s + AND member_id IS NOT NULL + AND assistant_id IS NOT NULL + """, + (run_started_at,), + ) + pairs = cur.fetchall() + conn.commit() + + triggered = 0 + for row in pairs: + site_id, member_id, assistant_id = row[0], row[1], row[2] + try: + fire_event( + "ai_consumption_settled", + { + "site_id": site_id, + "member_id": member_id, + "assistant_id": assistant_id, + "has_assistant": True, + }, + ) + triggered += 1 + except Exception: + logger.exception( + "触发 ai_consumption_settled 失败: site_id=%s member_id=%s", + site_id, member_id, + ) + + logger.info( + "ai_consumption_settled 触发完成: 新建任务去重后 %d 个 member，成功触发 %d 次", + len(pairs), triggered, + ) + + def _run_for_site(conn, site_id: int, stats: dict) -> None: """ 单门店处理流程。 @@ -766,9 +840,10 @@ def _run_transfer_check( w_ms = params["transfer_score_w_ms"] w_ml = params["transfer_score_w_ml"] - from datetime import datetime, timezone + from app.services.runtime_context import as_runtime_now_param - now = datetime.now(timezone.utc) + # 业务时间锚：sandbox 模式下用 business_now，避免按真实时间把已转移很久的任务再算成候选 + now = as_runtime_now_param(site_id, conn=conn) for task_id, from_assistant_id, member_id, task_type, transfer_count, created_at in candidates: # CHANGE 2026-03-29 | 用升级倍数判定是否触发转移 @@ -805,9 +880,7 @@ def _run_transfer_check( ) entry_dates = {r[0]: r[1] for r in cur.fetchall()} - from datetime import datetime, timezone, timedelta - - now = datetime.now(timezone.utc) + # 沿用上方 business_now，避免「真实今天」的入驻时间保护 eligible = [] for a in pool: aid = a["assistant_id"] diff --git a/apps/backend/app/services/task_manager.py b/apps/backend/app/services/task_manager.py index 26af2c4..9bb1147 100644 --- a/apps/backend/app/services/task_manager.py +++ b/apps/backend/app/services/task_manager.py @@ -37,6 +37,7 @@ from decimal import Decimal from fastapi import HTTPException from app.services import fdw_queries +from app.services.runtime_context import get_runtime_context, task_runtime_filter from app.services.task_generator import compute_heart_icon from app.trace.decorators import trace_service @@ -114,15 +115,17 @@ def _verify_task_ownership( - 不属于当前助教 → 403 - required_status 不匹配 → 409 """ + runtime_clause, runtime_params = task_runtime_filter(site_id, conn=conn) with conn.cursor() as cur: cur.execute( - """ + f""" SELECT id, task_type, status, is_pinned, abandon_reason, assistant_id, site_id FROM biz.coach_tasks WHERE id = %s + {runtime_clause} """, - (task_id,), + [task_id, *runtime_params], ) row = cur.fetchone() @@ -166,22 +169,24 @@ async def get_task_list(user_id: int, site_id: int) -> list[dict]: assistant_id = _get_assistant_id(conn, user_id, site_id) # 查询有效 + 已放弃任务（abandoned 排最后） + runtime_clause, runtime_params = task_runtime_filter(site_id, conn=conn) with conn.cursor() as cur: cur.execute( - """ + f""" SELECT id, task_type, status, priority_score, is_pinned, expires_at, created_at, member_id, abandon_reason FROM biz.coach_tasks WHERE site_id = %s AND assistant_id = %s AND status IN ('active', 'abandoned') + {runtime_clause} ORDER BY CASE WHEN status = 'abandoned' THEN 1 ELSE 0 END ASC, is_pinned DESC, priority_score DESC NULLS LAST, created_at ASC """, - (site_id, assistant_id), + [site_id, assistant_id, *runtime_params], ) tasks = cur.fetchall() conn.commit() @@ -605,8 +610,9 @@ async def get_task_list_v2( # 构建排除条件：relationship_building + member_id 不在 RS 范围内 # 当排除列表为空时不加额外条件 exclude_clause = "" - query_params_count: list = [site_id, assistant_id, db_status] - query_params_page: list = [site_id, assistant_id, db_status] + runtime_clause, runtime_params = task_runtime_filter(site_id, conn=conn) + query_params_count: list = [site_id, assistant_id, db_status, *runtime_params] + query_params_page: list = [site_id, assistant_id, db_status, *runtime_params] if rb_exclude_member_ids: exclude_clause = ( " AND NOT (task_type = 'relationship_building' AND member_id = ANY(%s))" @@ -621,6 +627,7 @@ async def get_task_list_v2( SELECT COUNT(*) FROM biz.coach_tasks WHERE site_id = %s AND assistant_id = %s AND status = %s + {runtime_clause} {exclude_clause} """, query_params_count, @@ -636,6 +643,7 @@ async def get_task_list_v2( expires_at, created_at, member_id, abandon_reason FROM biz.coach_tasks WHERE site_id = %s AND assistant_id = %s AND status = %s + {runtime_clause} {exclude_clause} ORDER BY is_pinned DESC, priority_score DESC NULLS LAST, @@ -669,9 +677,11 @@ async def get_task_list_v2( recent60d_map: dict[int, dict] = {} batch_data: dict | None = None try: + from app.services.runtime_context import as_runtime_today_param + _ref_date = as_runtime_today_param(site_id, conn=conn) batch_data = fdw_queries.batch_query_for_task_list( conn, site_id, assistant_id, member_ids, - datetime.now().year, datetime.now().month, + _ref_date.year, _ref_date.month, ) member_info_map = batch_data["member_info"] balance_map = batch_data["balance"] @@ -685,7 +695,11 @@ async def get_task_list_v2( # ── 6. 查询 ai_cache 获取 aiSuggestion（优雅降级） ── ai_suggestion_map: dict[int, str] = {} try: - member_id_strs = [str(mid) for mid in member_ids] + runtime_ctx = get_runtime_context(site_id, conn=conn) + if runtime_ctx.is_sandbox and runtime_ctx.sandbox_instance_id: + member_id_strs = [f"{runtime_ctx.sandbox_instance_id}:{mid}" for mid in member_ids] + else: + member_id_strs = [str(mid) for mid in member_ids] with conn.cursor() as cur: cur.execute( """ @@ -706,7 +720,8 @@ async def get_task_list_v2( result = row[1] if isinstance(row[1], dict) else {} summary = result.get("summary", "") if summary: - ai_suggestion_map[int(target_id_str)] = summary + raw_target = target_id_str.split(":", 1)[-1] + ai_suggestion_map[int(raw_target)] = summary conn.commit() except Exception: logger.warning("查询 ai_cache aiSuggestion 失败", exc_info=True) @@ -802,8 +817,11 @@ def build_performance_summary( 当 batch_data 为 None 时（如无任务的空列表场景），回退到独立查询。 课时/档位/客户数从 monthly_summary（每日更新）取实时数据， 不再依赖月初结算的 salary_calc。收入仍从 salary_calc 取（如有）。 + + CHANGE 2026-05-02 | now 改用 RuntimeContext.business_date，沙箱不读「未来」月份。 """ - now = datetime.now() + from app.services.runtime_context import as_runtime_today_param + now = as_runtime_today_param(site_id, conn=conn) year, month = now.year, now.month if batch_data: @@ -971,15 +989,17 @@ async def get_task_by_member( try: assistant_id = _get_assistant_id(conn, user_id, site_id) + runtime_clause, runtime_params = task_runtime_filter(site_id, conn=conn) with conn.cursor() as cur: cur.execute( - """ + f""" SELECT id, task_type FROM biz.coach_tasks WHERE site_id = %s AND assistant_id = %s AND member_id = %s AND status = 'active' + {runtime_clause} """, - (site_id, assistant_id, member_id), + [site_id, assistant_id, member_id, *runtime_params], ) rows = cur.fetchall() @@ -1020,16 +1040,18 @@ async def get_task_detail( assistant_id = _get_assistant_id(conn, user_id, site_id) # ── 1. 查询任务基础信息 ── + runtime_clause, runtime_params = task_runtime_filter(site_id, conn=conn) with conn.cursor() as cur: cur.execute( - """ + f""" SELECT id, task_type, status, priority_score, is_pinned, expires_at, created_at, member_id, abandon_reason, assistant_id, site_id FROM biz.coach_tasks WHERE id = %s + {runtime_clause} """, - (task_id,), + [task_id, *runtime_params], ) row = cur.fetchone() @@ -1090,6 +1112,12 @@ async def get_task_detail( # ── 3. 查询维客线索 ── retention_clues = [] try: + runtime_ctx = get_runtime_context(site_id, conn=conn) + member_target_id = ( + f"{runtime_ctx.sandbox_instance_id}:{member_id}" + if runtime_ctx.is_sandbox and runtime_ctx.sandbox_instance_id + else str(member_id) + ) with conn.cursor() as cur: cur.execute( """ @@ -1136,7 +1164,7 @@ async def get_task_detail( AND cache_type IN ('app4_analysis', 'app5_talking_points') ORDER BY created_at DESC """, - (str(member_id), site_id), + (member_target_id, site_id), ) seen_types: set[str] = set() for cache_row in cur.fetchall(): @@ -1173,8 +1201,10 @@ async def get_task_detail( # CHANGE 2026-03-25 | 统计范围：近60天；列表不限 # 预估规则：当月且日期 ≤ 5号 - from datetime import date, timedelta - today = date.today() + # CHANGE 2026-05-02 | today 改用 business_date，沙箱不读「未来」60 天 + from datetime import timedelta + from app.services.runtime_context import as_runtime_today_param + today = as_runtime_today_param(site_id, conn=conn) cutoff_60d = today - timedelta(days=60) is_estimate_month = today.day <= 5 diff --git a/apps/backend/app/services/trigger_scheduler.py b/apps/backend/app/services/trigger_scheduler.py index 778a2ca..cdb1ebb 100644 --- a/apps/backend/app/services/trigger_scheduler.py +++ b/apps/backend/app/services/trigger_scheduler.py @@ -10,7 +10,10 @@ """ from __future__ import annotations +import asyncio +import inspect import logging +import threading from datetime import datetime, timedelta, timezone from typing import Any, Callable @@ -19,6 +22,34 @@ from app.trace.decorators import trace_service logger = logging.getLogger(__name__) +def _invoke_handler(handler: Callable, **kwargs: Any) -> Any: + """统一调用 handler，自动识别 sync / async。 + + - sync handler：直接返回结果 + - async handler： + - 当前线程有 running loop → loop.create_task(coro)，后台异步执行 + - 当前线程无 running loop → 新起 daemon 线程跑 asyncio.run(coro)，不阻塞调用方 + + 说明：fire_event / check_scheduled_jobs 是 sync 函数，但部分 handler + （如 dispatcher 注册的 AI 事件 handler）是 async def，本包装器保证正确调度。 + """ + result = handler(**kwargs) + if not inspect.iscoroutine(result): + return result + + try: + loop = asyncio.get_running_loop() + loop.create_task(result) + return None + except RuntimeError: + # 同步线程（无 running loop）：用后台线程异步执行 coroutine，不阻塞调用方 + threading.Thread( + target=lambda coro=result: asyncio.run(coro), + daemon=True, + ).start() + return None + + def _get_connection(): """延迟导入 get_connection，避免纯函数测试时触发模块级导入失败。""" from app.database import get_connection @@ -89,7 +120,8 @@ def fire_event(event_name: str, payload: dict[str, Any] | None = None) -> int: continue try: # 将 job_id 传入 handler，handler 在最终 commit 前更新 last_run_at - handler(payload=payload, job_id=job_id) + # async handler 经 _invoke_handler 自动调度 + _invoke_handler(handler, payload=payload, job_id=job_id) executed += 1 except Exception: logger.exception("触发器 %s 执行失败", job_name) @@ -136,7 +168,8 @@ def check_scheduled_jobs() -> int: continue try: # cron/interval handler 接受 conn + job_id，在最终 commit 前更新时间戳 - handler(conn=conn, job_id=job_id) + # async handler 经 _invoke_handler 自动调度 + _invoke_handler(handler, conn=conn, job_id=job_id) # 计算 next_run_at 并更新（在 handler commit 后的新事务中） next_run = _calculate_next_run(trigger_condition, trigger_config) with conn.cursor() as cur: @@ -276,7 +309,7 @@ def run_job_by_id(job_id: int) -> dict: return {"success": False, "message": f"任务 {job_name} 未注册处理器"} try: - handler() + _invoke_handler(handler) # 更新 last_run_at 和 next_run_at next_run = _calculate_next_run(trigger_condition, trigger_config) with conn.cursor() as cur: diff --git a/apps/backend/app/ws/ai_events.py b/apps/backend/app/ws/ai_events.py new file mode 100644 index 0000000..104654e --- /dev/null +++ b/apps/backend/app/ws/ai_events.py @@ -0,0 +1,80 @@ +"""AI 事件 WebSocket 推送端点。 + +提供： +- /ws/ai-cache/{site_id} — 缓存更新 / 失效事件 +- /ws/ai-alerts/{site_id} — AI 告警事件（Phase 3.1） + +协议： +- 客户端连接 → 服务端 accept → 订阅 EventBus → 持续 send_json 事件 +- 事件格式：{"type": "cache_updated|cache_invalidated|alert_created|...", "site_id": int, "payload": {...}} +- 服务端关闭或客户端断开时清理订阅 + +用 site_id=-1 表示全局订阅（收所有门店事件，admin-web 全局监控用）。 +""" + +from __future__ import annotations + +import logging + +from fastapi import APIRouter, WebSocket, WebSocketDisconnect + +from ..ai.event_bus import AIEvent, get_event_bus + +logger = logging.getLogger(__name__) + +ws_router = APIRouter() + + +@ws_router.websocket("/ws/ai-cache/{site_id}") +async def ws_ai_cache(websocket: WebSocket, site_id: int) -> None: + """AI 缓存事件推送。 + + site_id=-1 表示订阅全局（收所有门店的 cache_updated / cache_invalidated）。 + """ + await _serve_event_stream(websocket, site_id, endpoint="ai-cache") + + +@ws_router.websocket("/ws/ai-alerts/{site_id}") +async def ws_ai_alerts(websocket: WebSocket, site_id: int) -> None: + """AI 告警事件推送（Phase 3.1）。 + + site_id=-1 表示订阅全局告警。 + 事件 type: alert_created / alert_updated / budget_exceeded / circuit_opened。 + """ + await _serve_event_stream(websocket, site_id, endpoint="ai-alerts") + + +async def _serve_event_stream( + websocket: WebSocket, site_id: int, endpoint: str, +) -> None: + """共享事件流处理逻辑。""" + await websocket.accept() + # -1 映射为全局订阅（None） + subscribe_key: int | None = None if site_id == -1 else site_id + logger.info( + "WS %s 连接建立: site_id=%s", endpoint, subscribe_key if subscribe_key else "ALL", + ) + + bus = get_event_bus() + queue = await bus.subscribe(subscribe_key) + + try: + while True: + event = await queue.get() + if event is None: + break + await websocket.send_json({ + "type": event.type, + "site_id": event.site_id, + "payload": event.payload, + }) + except WebSocketDisconnect: + logger.info("WS %s 客户端断开: site_id=%s", endpoint, subscribe_key) + except Exception: + logger.exception("WS %s 异常: site_id=%s", endpoint, subscribe_key) + finally: + await bus.unsubscribe(subscribe_key, queue) + try: + await websocket.close() + except Exception: + pass diff --git a/apps/backend/pytest.ini b/apps/backend/pytest.ini index 654b7eb..8fbe9b6 100644 --- a/apps/backend/pytest.ini +++ b/apps/backend/pytest.ini @@ -2,3 +2,4 @@ testpaths = tests pythonpath = . asyncio_mode = auto +norecursedirs = _archived _deleted diff --git a/apps/etl/connectors/feiqiu/tasks/dws/finance_area_daily.py b/apps/etl/connectors/feiqiu/tasks/dws/finance_area_daily.py index 7dae151..37717f6 100644 --- a/apps/etl/connectors/feiqiu/tasks/dws/finance_area_daily.py +++ b/apps/etl/connectors/feiqiu/tasks/dws/finance_area_daily.py @@ -24,6 +24,7 @@ - 非 all 行现金流/卡消费/充值字段 = 0 - hall 行 = 各具体区域之和（历史兼容） - all 行 = 各具体区域之和（收入/优惠），现金流/充值/卡消费来自 dws_finance_daily_summary + 无台桌订单和补时长等 all-only 台区只合入 all，不合入具体区域 - settle_type IN (1, 3) 过滤 - discount_gift_card 使用赠送卡消费金额口径 @@ -107,6 +108,9 @@ _COUNT_FIELDS = {"order_count", "member_order_count"} _ZERO = Decimal("0") +# 已知不属于看板 7 个具体区域、但应合入 all 的物理台区。 +_ALL_ONLY_AREA_NAMES = {"补时长", "虚拟台"} + class FinanceAreaDailyTask(FinanceBaseTask): """ @@ -177,6 +181,7 @@ class FinanceAreaDailyTask(FinanceBaseTask): sql = f""" SELECT {biz_expr} AS stat_date, + sh.table_id AS table_id, dt.site_table_area_name AS area_name, sh.settle_type, -- 收入 @@ -378,8 +383,9 @@ def transform_area_daily( ) # 收集所有涉及的日期 all_dates: set[date] = set() - # 未知区域名称计数（汇总后一次性输出，避免逐行 warning 产生大量日志噪音） + # 未知/无具体区域计数（汇总后一次性输出，避免逐行日志噪音） _unknown_area_counts: Dict[str, int] = defaultdict(int) + _all_only_area_counts: Dict[str, int] = defaultdict(int) for row in settlement_rows: sd = row.get("stat_date") @@ -393,10 +399,15 @@ def transform_area_daily( continue area_name = row.get("area_name") + table_id = row.get("table_id") area_code = resolve_area_code(area_name) if area_code is None: - _unknown_area_counts[str(area_name)] += 1 + unmatched_label = _format_unmatched_area_label(area_name, table_id) + if _is_all_only_area(area_name, table_id): + _all_only_area_counts[unmatched_label] += 1 + else: + _unknown_area_counts[unmatched_label] += 1 # 提取金额 table_fee = safe_decimal_fn(row.get("table_fee_amount", 0)) @@ -479,11 +490,20 @@ def transform_area_daily( for k, v in fields.items(): bucket[k] = bucket[k] + v - # 汇总输出未知区域名称（避免逐行 warning 刷屏） + # 汇总输出 all-only 区域（无台桌订单、补时长等），这些记录合入 all 属正常口径。 + if _all_only_area_counts: + summary = ", ".join(f"'{k}': {v}次" for k, v in _all_only_area_counts.items()) + logger.info( + "DWS_FINANCE_AREA_DAILY: 共 %d 条结算单无具体区域（已计入 all，不计入任何具体区域）: %s", + sum(_all_only_area_counts.values()), + summary, + ) + + # 汇总输出真正未知区域名称（避免逐行 warning 刷屏） if _unknown_area_counts: summary = ", ".join(f"'{k}': {v}次" for k, v in _unknown_area_counts.items()) logger.warning( - "DWS_FINANCE_AREA_DAILY: 共 %d 条结算单区域未匹配（已计入 all 但不计入任何具体区域）: %s", + "DWS_FINANCE_AREA_DAILY: 共 %d 条结算单区域未匹配（已计入 all 但不计入任何具体区域，请检查 dim_table/AREA_LABEL_MAP）: %s", sum(_unknown_area_counts.values()), summary, ) @@ -618,4 +638,42 @@ def _safe_decimal(value: Any, default: Decimal = _ZERO) -> Decimal: return default +def _is_all_only_area(area_name: Any, table_id: Any) -> bool: + """判断结算单是否属于无具体区域但应合入 all 的正常口径。 + + CHANGE 2026-05-02 | 扩大豁免规则，避免噪音 WARNING： + - "补时长" / "虚拟台" 的带数字/空格变体（如 "补时长2"、"虚拟台 1"）也算 all-only。 + - 维表 site_table_area_name 为空（NULL）但有 table_id 的脏数据，归入 all-only INFO， + 因为这通常是 dim_table SCD2 缺区域名而非真正映射缺口；金额仍合入 all 不丢失。 + 真正的「未知非空区域名」（如新店自定义命名未在 AREA_LABEL_MAP 中）才进 WARNING。 + """ + if area_name is None: + # 无 table_id：本来就没台桌，正常 all-only + # 有 table_id：维表区域名缺失，作为 dim_table 数据问题，仍归 all-only 但保留可观测性（INFO 行会带 'table_id=… None' 标签） + return True + if not isinstance(area_name, str): + return False + name = area_name.strip() + if not name: + return True + if name in _ALL_ONLY_AREA_NAMES: + return True + # 形如 "补时长2"、"补时长 3"、"虚拟台4" 等编号变体 + for prefix in _ALL_ONLY_AREA_NAMES: + if name.startswith(prefix): + tail = name[len(prefix):].strip() + if not tail or tail.isdigit(): + return True + return False + + +def _format_unmatched_area_label(area_name: Any, table_id: Any) -> str: + """格式化未匹配区域日志标签，区分无台桌订单和维表缺口。""" + if area_name is None and not table_id: + return "无台桌" + if area_name is None: + return f"table_id={table_id}: None" + return str(area_name) + + __all__ = ["FinanceAreaDailyTask", "transform_area_daily"] diff --git a/apps/etl/connectors/feiqiu/tasks/dws/task_engine.py b/apps/etl/connectors/feiqiu/tasks/dws/task_engine.py index 7705ae6..b119c39 100644 --- a/apps/etl/connectors/feiqiu/tasks/dws/task_engine.py +++ b/apps/etl/connectors/feiqiu/tasks/dws/task_engine.py @@ -42,7 +42,10 @@ load_dotenv(_REPO_ROOT / ".env", override=False) logger = logging.getLogger(__name__) -_TIMEOUT = (5, 30) +# CHANGE 2026-05-02 | 旧值 (5, 30) 在 recall_completion_check / task_generator 这种长任务下 +# 经常 30s 读超时（实际处理 ~33s 以上）。临时止血提到 600s 与 flow_runner 对齐； +# 长期方案是后端 /api/internal/run-job 改异步入队（参见 docs/database/changes/2026-05-02__sandbox_complete_refactor.md 已知未覆盖） +_TIMEOUT = (10, 600) # HTTP 模式���按顺序执行的后端任务 _JOB_SEQUENCE = [ diff --git a/apps/miniprogram/miniprogram/components/ai-float-button/ai-float-button.ts b/apps/miniprogram/miniprogram/components/ai-float-button/ai-float-button.ts index a08ec93..6f1f80d 100644 --- a/apps/miniprogram/miniprogram/components/ai-float-button/ai-float-button.ts +++ b/apps/miniprogram/miniprogram/components/ai-float-button/ai-float-button.ts @@ -20,13 +20,47 @@ Component({ type: Number, value: 200, }, + /** + * Phase 2.3：来源页面标识（sourcePage），用于后端注入 page_context。 + * 取值参考 backend page_context.py 的 SUPPORTED_PAGE_TYPES： + * board-finance / board-coach / board-customer / performance / task-list / my-profile 等。 + * 为空时不传入 chat 页。 + */ + sourcePage: { + type: String, + value: '', + }, + /** + * Phase 2.3：页面筛选参数（board-* 页面的 timeDimension/dimension/areaFilter 等）， + * 将作为 JSON 字符串附加到 url，在 chat 页面解析后随 SSE 请求发给后端。 + */ + pageFilters: { + type: Object, + value: null as Record | null, + }, }, methods: { onTap() { let url = this.data.targetUrl + const params: string[] = [] if (this.data.customerId) { - url += `?customerId=${this.data.customerId}` + params.push(`customerId=${encodeURIComponent(this.data.customerId)}`) + } + if (this.data.sourcePage) { + params.push(`sourcePage=${encodeURIComponent(this.data.sourcePage)}`) + } + if (this.data.pageFilters && Object.keys(this.data.pageFilters).length > 0) { + try { + params.push( + `pageFilters=${encodeURIComponent(JSON.stringify(this.data.pageFilters))}`, + ) + } catch { + // 非法 filters 忽略，不影响跳转 + } + } + if (params.length > 0) { + url += (url.includes('?') ? '&' : '?') + params.join('&') } wx.navigateTo({ url, diff --git a/apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxml b/apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxml index 817c54f..b909a85 100644 --- a/apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxml +++ b/apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxml @@ -203,6 +203,8 @@ + + @@ -210,11 +212,108 @@ AI 智能洞察 - - {{item.icon}} {{item.text}} + + + + + + {{summaryLightLabel}} + + 本期总结 + + + + + {{seg.text}} + + + + + ⏰ {{aiInsightSummary.tracking.title}} + + {{seg.text}} + + - - 暂无洞察数据 + + + + 分板块明细洞察 · 仅展示前 3 条 + + + + + + {{index + 1}} + {{item.title}} + + + {{seg.text}} + + + + + + 查看全部 AI 洞察 › + + + + 暂无洞察数据 + + + + + + + + + + + + AI 智能洞察 · 共 {{aiInsights.length}} 条 + + + ✕ + + + + + + + + {{summaryLightLabel}} + + 本期总结 + + + + {{seg.text}} + + + + + ⏰ {{aiInsightSummary.tracking.title}} + + {{seg.text}} + + + + + + 分板块明细洞察 + + + + {{index + 1}} + {{item.title}} + + + {{seg.text}} + + + + + 关闭 diff --git a/apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss b/apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss index dd26259..3132427 100644 --- a/apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss +++ b/apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss @@ -492,7 +492,7 @@ AI_CHANGELOG display: flex; align-items: center; gap: 14rpx; - margin-bottom: 22rpx; + margin-bottom: 30rpx; } /* CHANGE 2026-03-12 | intent: H5 原型 AI 图标为 SVG 机器人（24×24 → 42rpx），不可用 emoji 替代 */ @@ -545,6 +545,357 @@ AI_CHANGELOG color: rgba(255, 255, 255, 0.85); } +/* CHANGE 2026-04-22 v2 | AI 洞察列表项：与弹窗同款（序号徽章 + 标题 + 缩进正文） */ +.ai-insight-item { + padding: 6rpx 0 10rpx 0; +} + +.ai-insight-item-title { + display: flex; + align-items: center; + gap: 12rpx; + margin-bottom: 8rpx; +} + +.ai-insight-item-seq { + display: inline-flex; + align-items: center; + justify-content: center; + min-width: 32rpx; + height: 32rpx; + padding: 0 8rpx; + border-radius: 10rpx; + background: linear-gradient(135deg, #667eea, #764ba2); + color: #fff; + font-size: 20rpx; + font-weight: 600; +} + +.ai-insight-item-name { + font-size: 26rpx; + font-weight: 600; + color: rgba(255, 255, 255, 0.95); + flex: 1; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.ai-insight-item-body { + display: block; + font-size: 24rpx; + line-height: 36rpx; + color: rgba(255, 255, 255, 0.78); + text-indent: 48rpx; +} + +.ai-insight-item-body-ellipsis { + display: -webkit-box; + -webkit-box-orient: vertical; + -webkit-line-clamp: 1; + overflow: hidden; + text-overflow: ellipsis; +} + +/* ===== 2026-04-22 seq11/12 置顶：本期总结（轻量版） ===== */ +/* 不用卡片容器，直接嵌入 AI 洞察区，用彩色小点 + 淡分隔区分层级 */ +.ai-summary-card { + margin: 0 24rpx 18rpx 0; + padding: 0 0 18rpx 0; + border-bottom: 2rpx dashed rgba(255, 255, 255, 0.1); +} + +.ai-summary-card--modal { + margin: 0 0 14rpx 0; +} + +/* 去掉左侧彩条，保留类名备用（无样式即不渲染） */ +.ai-summary-card--green, +.ai-summary-card--yellow, +.ai-summary-card--red, +.ai-summary-card--neutral { + background: transparent; +} + +.ai-summary-head { + display: flex; + align-items: baseline; /* 徽章与"本期总结"按文字基线对齐（字号不同时看起来贴底） */ + gap: 10rpx; + margin-bottom: 14rpx; +} + +/* 徽章：去胶囊底，纯色粗字强调三色灯级别 */ +.ai-summary-badge { + display: inline-flex; + align-items: center; + font-size: 30rpx; + font-weight: 700; + letter-spacing: 1rpx; + padding: 0; + background: transparent !important; + box-shadow: none !important; +} + +.ai-summary-badge--green { color: #4ade80; } +.ai-summary-badge--yellow { color: #facc15; } +.ai-summary-badge--red { color: #f87171; } +.ai-summary-badge--neutral { color: rgba(255, 255, 255, 0.6); } + +.ai-summary-head-title { + font-size: 22rpx; + font-weight: 400; + color: rgba(255, 255, 255, 0.5); + letter-spacing: 1rpx; +} + +.ai-summary-block { + display: flex; + flex-direction: column; + gap: 6rpx; +} + +.ai-summary-block-title { + font-size: 25rpx; + font-weight: 600; + color: rgba(255, 255, 255, 0.88); + line-height: 36rpx; +} + +.ai-summary-block-body { + font-size: 24rpx; + line-height: 36rpx; + color: rgba(255, 255, 255, 0.72); +} + +/* 2026-04-22 v3：总结区 body 2 行省略，突出要点 */ +.ai-summary-block-body-clamp { + display: -webkit-box; + -webkit-box-orient: vertical; + overflow: hidden; + text-overflow: ellipsis; +} + +.ai-summary-block--tracking { + margin-top: 14rpx; +} +.ai-summary-block--tracking .ai-summary-block-title { + color: rgba(251, 191, 36, 0.85); + font-weight: 500; +} + +.ai-summary-divider { + display: none; +} + +/* "分板块明细洞察"分组标签 */ +.ai-insight-details-label { + padding: 2rpx 0 12rpx 0; +} + +.ai-insight-details-label-text { + font-size: 20rpx; + color: rgba(255, 255, 255, 0.42); + letter-spacing: 1rpx; +} + +.ai-modal-details-label { + padding: 6rpx 0 8rpx 0; + margin-bottom: 4rpx; +} + +.ai-modal-details-label-text { + font-size: 20rpx; + color: rgba(255, 255, 255, 0.42); + letter-spacing: 1rpx; +} + +/* 2026-04-22 小程序 Markdown 内联样式：**加粗** / *倾斜* */ +.md-seg { + display: inline; +} + +.md-bold { + font-weight: 700; + color: rgba(255, 255, 255, 0.98); +} + +.md-italic { + font-style: italic; +} + +/* 加粗同时倾斜时组合生效（class 拼接即可） */ + +/* CHANGE 2026-04-22 v2 | "查看全部" 按钮居中 */ +.ai-insight-more { + margin: 10rpx 24rpx 0 0; + padding: 18rpx 24rpx; + text-align: center; + color: rgba(255, 255, 255, 0.88); + font-size: 26rpx; + background: rgba(255, 255, 255, 0.06); + border-radius: 12rpx; +} + +.ai-insight-more-hover { + background: rgba(255, 255, 255, 0.12); +} + +.ai-insight-more-text { + letter-spacing: 1rpx; +} + +/* CHANGE 2026-04-22 | AI 全部洞察弹窗：覆盖除底部 tab 外整个页面 */ +.ai-modal-mask { + position: fixed; + top: 0; + left: 0; + right: 0; + bottom: 110rpx; /* 避让自定义 tabBar 约 110rpx */ + bottom: calc(110rpx + env(safe-area-inset-bottom)); + background: rgba(0, 0, 0, 0.55); + z-index: 9998; + display: flex; + flex-direction: column; + justify-content: flex-end; +} + +/* 2026-04-22 v5：fixed top+bottom 固定高（scroll-view 在 flex max-height 里渲染溢出，放弃 auto 高度） */ +.ai-modal { + position: fixed; + left: 24rpx; + right: 24rpx; + top: 40rpx; + bottom: calc(150rpx + env(safe-area-inset-bottom)); /* 110rpx tab + 40rpx 留白 */ + background: #2e2e2e; + border-radius: 24rpx; + display: flex; + flex-direction: column; + overflow: hidden; + box-shadow: 0 12rpx 48rpx rgba(0, 0, 0, 0.45); + z-index: 9999; +} + +.ai-modal-header { + flex-shrink: 0; + display: flex; + align-items: center; + justify-content: space-between; + padding: 28rpx 28rpx 20rpx 28rpx; + border-bottom: 2rpx solid rgba(255, 255, 255, 0.08); +} + +.ai-modal-title-wrap { + display: flex; + align-items: center; + gap: 14rpx; + flex: 1; + min-width: 0; +} + +.ai-modal-title { + font-size: 28rpx; + font-weight: 600; + color: rgba(255, 255, 255, 0.95); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.ai-modal-close { + width: 52rpx; + height: 52rpx; + border-radius: 50%; + background: rgba(255, 255, 255, 0.08); + display: flex; + align-items: center; + justify-content: center; + margin-left: 16rpx; +} + +.ai-modal-close-hover { + background: rgba(255, 255, 255, 0.18); +} + +.ai-modal-close-icon { + font-size: 28rpx; + color: rgba(255, 255, 255, 0.85); + line-height: 28rpx; +} + +.ai-modal-body { + /* 2026-04-22 v5：modal 固定高度后 flex:1 1 0 分配剩余空间给 scroll-view */ + flex: 1 1 0; + min-height: 0; + padding: 20rpx 28rpx 12rpx 28rpx; + box-sizing: border-box; +} + +.ai-modal-item { + padding: 22rpx 0 22rpx 0; + border-bottom: 2rpx dashed rgba(255, 255, 255, 0.1); +} + +.ai-modal-item:last-of-type { + border-bottom: none; +} + +.ai-modal-item-title { + display: flex; + align-items: center; + gap: 12rpx; + margin-bottom: 10rpx; +} + +.ai-modal-item-seq { + display: inline-flex; + align-items: center; + justify-content: center; + min-width: 36rpx; + height: 36rpx; + padding: 0 10rpx; + border-radius: 18rpx; + background: linear-gradient(135deg, #667eea, #764ba2); + color: #fff; + font-size: 22rpx; + font-weight: 600; +} + +.ai-modal-item-name { + font-size: 28rpx; + font-weight: 600; + color: rgba(255, 255, 255, 0.95); + flex: 1; +} + +.ai-modal-item-body { + display: block; + font-size: 26rpx; + line-height: 40rpx; + color: rgba(255, 255, 255, 0.78); + text-indent: 48rpx; /* 首行缩进，和 seq 徽章对齐阅读感 */ +} + +.ai-modal-footer-space { + height: 24rpx; +} + +/* 2026-04-22 v3 | 弹窗底部整块作为关闭按钮：固定高度 100rpx，贯通整宽 */ +.ai-modal-footer { + flex-shrink: 0; + height: 100rpx; + line-height: 100rpx; + text-align: center; + font-size: 30rpx; + font-weight: 500; + color: #fff; + background: linear-gradient(135deg, #667eea, #764ba2); + letter-spacing: 8rpx; +} + +.ai-modal-footer-hover { + opacity: 0.82; +} + /* ===== 通用表格边框容器 ===== */ .table-bordered { border: 2rpx solid #e7e7e7; diff --git a/apps/miniprogram/miniprogram/pages/chat/chat.ts b/apps/miniprogram/miniprogram/pages/chat/chat.ts index 729a1e4..978e630 100644 --- a/apps/miniprogram/miniprogram/pages/chat/chat.ts +++ b/apps/miniprogram/miniprogram/pages/chat/chat.ts @@ -198,6 +198,12 @@ Page({ /** 最后一次发送的用户消息内容（用于重试） */ _lastUserContent: '', + /** SSE 断线重试次数 */ + _sseRetryCount: 0, + + /** SSE 最大自动重试次数 */ + _SSE_MAX_RETRY: 2, + onShow() { // 权限守卫：检查登录状态、账号禁用、角色权限 checkPageAccess('pages/chat/chat') @@ -227,10 +233,27 @@ Page({ this.loadMessagesByContext('coach', options.coachId) } else if (options?.sourcePage) { // 看板类入口：保存来源页面和筛选参数 - const filterKeys = ['timeDimension', 'areaFilter', 'dimension', 'typeFilter', 'projectFilter'] + // Phase 2.3：优先解析 options.pageFilters（ai-float-button 传入的 JSON 字符串）， + // 回退到单独键（旧入口兼容：timeDimension / areaFilter 等） const pageFilters: Record = {} - for (const key of filterKeys) { - if (options[key]) pageFilters[key] = options[key] + if (options.pageFilters) { + try { + const parsed = JSON.parse(decodeURIComponent(options.pageFilters)) + if (parsed && typeof parsed === 'object') { + for (const k of Object.keys(parsed)) { + const v = parsed[k] + if (v != null) pageFilters[k] = String(v) + } + } + } catch { + // JSON 解析失败忽略，回退到单键读取 + } + } + if (Object.keys(pageFilters).length === 0) { + const filterKeys = ['timeDimension', 'areaFilter', 'dimension', 'typeFilter', 'projectFilter'] + for (const key of filterKeys) { + if (options[key]) pageFilters[key] = options[key] + } } this.setData({ sourcePage: options.sourcePage, pageFilters }) this.loadMessagesByContext(options.sourcePage, '') @@ -418,6 +441,7 @@ Page({ }, // onDone: 流结束，更新消息 ID 和时间 (messageId: number, createdAt: string) => { + this._sseRetryCount = 0 this.setData({ [`messages[${aiIndex}].id`]: String(messageId), [`messages[${aiIndex}].timestamp`]: createdAt, @@ -477,8 +501,20 @@ Page({ } }, fail: () => { - // 网络错误或连接中断 - if (this.data.isStreaming) { + // 网络错误或连接中断：无内容时指数退避重连 + this._sseTask = null + if (!this.data.isStreaming) return + if (fullContent === '' && this._sseRetryCount < this._SSE_MAX_RETRY) { + this._sseRetryCount++ + const delay = (2 ** this._sseRetryCount) * 1000 + wx.showToast({ title: `重连中 ${this._sseRetryCount}/${this._SSE_MAX_RETRY}...`, icon: 'loading', duration: delay }) + this.setData({ + messages: this.data.messages.slice(0, aiIndex), + isStreaming: false, + streamingContent: '', + }) + setTimeout(() => { this.triggerAIReply(chatId, content) }, delay) + } else { const errorContent = fullContent || '连接中断，请重试' this.setData({ [`messages[${aiIndex}].content`]: errorContent, @@ -487,7 +523,6 @@ Page({ }) wx.showToast({ title: '连接中断', icon: 'none', duration: 3000 }) } - this._sseTask = null }, } as WechatMiniprogram.RequestOption) @@ -509,4 +544,19 @@ Page({ }, 50) }, 50) }, + + /** 点击引用卡片：跳转到对应详情页（Phase 2.1） */ + onRefCardTap(e: WechatMiniprogram.BaseEvent & { currentTarget: { dataset: { link?: string } } }) { + const link = e.currentTarget?.dataset?.link + if (!link || typeof link !== 'string') { + return + } + wx.navigateTo({ + url: link, + fail: (err) => { + console.error('跳转引用详情失败', err) + wx.showToast({ title: '跳转失败', icon: 'none' }) + }, + }) + }, }) diff --git a/apps/miniprogram/miniprogram/pages/chat/chat.wxml b/apps/miniprogram/miniprogram/pages/chat/chat.wxml index 7a78855..2fc7f1a 100644 --- a/apps/miniprogram/miniprogram/pages/chat/chat.wxml +++ b/apps/miniprogram/miniprogram/pages/chat/chat.wxml @@ -92,13 +92,18 @@ {{item.content}} - + - {{item.referenceCard.type === 'customer' ? '👤 客户' : '📋 记录'}} + {{item.referenceCard.type === 'customer' ? '👤 客户' : item.referenceCard.type === 'assistant' ? '🧑\u200d🏫 助教' : item.referenceCard.type === 'task' ? '📋 任务' : '📋 记录'}} {{fmt.safe(item.referenceCard.title)}} {{fmt.safe(item.referenceCard.summary)}} - + {{fmt.safe(entry.key)}} {{fmt.safe(entry.value)}} diff --git a/apps/miniprogram/miniprogram/pages/customer-detail/customer-detail.ts b/apps/miniprogram/miniprogram/pages/customer-detail/customer-detail.ts index d6f0d59..60eab55 100644 --- a/apps/miniprogram/miniprogram/pages/customer-detail/customer-detail.ts +++ b/apps/miniprogram/miniprogram/pages/customer-detail/customer-detail.ts @@ -4,7 +4,7 @@ | 2026-03-23 | 角色路由+页面权限守卫 | onShow 添加 checkPageAccess 权限守卫 | */ import { checkPageAccess } from '../../utils/auth-guard' -import { fetchCustomerDetail } from '../../services/api' +import { fetchCustomerDetail, fetchAICache } from '../../services/api' interface ConsumptionRecord { id: string @@ -132,6 +132,7 @@ Page({ } } this.setData({ pageState: 'normal' }) + if (id) this._loadAIInsight(id) } catch (e) { console.error('[customer-detail] loadDetail 失败:', e) this.setData({ pageState: 'error' }) @@ -140,6 +141,23 @@ Page({ } }, + async _loadAIInsight(memberId: string) { + const cache = await fetchAICache('app7_customer_analysis', memberId) + if (!cache?.result_json) return + const rj = cache.result_json as any + const COLORS = ['blue', 'indigo', 'purple', 'red', 'orange', 'yellow'] as const + const strategies = Array.isArray(rj.strategies) + ? rj.strategies.map((s: any, i: number) => ({ + color: COLORS[i % COLORS.length], + text: s.title || s.text || '', + })) + : [] + this.setData({ + 'aiInsight.summary': rj.summary || '', + 'aiInsight.strategies': strategies, + }) + }, + onRetry() { const id = this.data.detail?.id || '' this.loadDetail(id) diff --git a/apps/miniprogram/miniprogram/pages/customer-records/customer-records.ts b/apps/miniprogram/miniprogram/pages/customer-records/customer-records.ts index 9064091..015436b 100644 --- a/apps/miniprogram/miniprogram/pages/customer-records/customer-records.ts +++ b/apps/miniprogram/miniprogram/pages/customer-records/customer-records.ts @@ -5,6 +5,8 @@ */ import { checkPageAccess } from '../../utils/auth-guard' import { fetchCustomerConsumptionRecords } from '../../services/api' +// CHANGE 2026-05-02 | 业务时钟：sandbox 模式下用 business_year/month 替代 new Date() +import { getBusinessClock } from '../../utils/runtime-clock' Page({ data: { @@ -38,11 +40,12 @@ Page({ monthLoading: false, }, - onLoad(options) { + async onLoad(options) { const id = options?.customerId || options?.id || '' - const now = new Date() - const currentYear = now.getFullYear() - const currentMonth = now.getMonth() + 1 + // CHANGE 2026-05-02 | 默认当前年月走业务时钟，sandbox 模式按 sandbox_date 显示 + const clock = await getBusinessClock() + const currentYear = clock.business_year + const currentMonth = clock.business_month this.setData({ customerId: id, currentYear, diff --git a/apps/miniprogram/miniprogram/pages/customer-service-records/customer-service-records.ts b/apps/miniprogram/miniprogram/pages/customer-service-records/customer-service-records.ts index f017c9d..1cf8c97 100644 --- a/apps/miniprogram/miniprogram/pages/customer-service-records/customer-service-records.ts +++ b/apps/miniprogram/miniprogram/pages/customer-service-records/customer-service-records.ts @@ -5,6 +5,8 @@ | 2026-03-27 | 任务A 前端改造 | 修复数据转换（duration/income/timeRange/table/recordType），去掉 loadCustomerInfo 改从 records 响应取客户信息，新增 monthIncome 展示 | */ import { checkPageAccess } from '../../utils/auth-guard' +// CHANGE 2026-05-02 | 业务时钟：sandbox 模式下用 business_year/month 替代 new Date() +import { getBusinessClock } from '../../utils/runtime-clock' // CHANGE 2026-03-27 | 任务A A5: 去掉 fetchCustomerDetail，客户信息从 fetchCustomerRecords 响应中获取 import { fetchCustomerRecords } from '../../services/api' import { formatCount } from '../../utils/money' @@ -86,12 +88,12 @@ Page({ monthLoading: false, }, - onLoad(options) { + async onLoad(options) { const id = options?.customerId || options?.id || '' - // 默认当前年月 - const now = new Date() - const currentYear = now.getFullYear() - const currentMonth = now.getMonth() + 1 + // CHANGE 2026-05-02 | 默认当前年月走业务时钟，sandbox 模式按 sandbox_date 显示 + const clock = await getBusinessClock() + const currentYear = clock.business_year + const currentMonth = clock.business_month this.setData({ customerId: id, currentYear, diff --git a/apps/miniprogram/miniprogram/pages/performance-records/performance-records.ts b/apps/miniprogram/miniprogram/pages/performance-records/performance-records.ts index 0c71a0b..8d26e78 100644 --- a/apps/miniprogram/miniprogram/pages/performance-records/performance-records.ts +++ b/apps/miniprogram/miniprogram/pages/performance-records/performance-records.ts @@ -11,6 +11,8 @@ import { nameToAvatarColor } from '../../utils/avatar-color' import { formatMoney, formatCount } from '../../utils/money' import { formatHours } from '../../utils/time' import { API_BASE } from '../../utils/config' +// CHANGE 2026-05-02 | 业务时钟：sandbox 模式下用 business_year/month 替代 new Date() +import { getBusinessClock } from '../../utils/runtime-clock' /** 中文课程类型 → 英文 CSS key（WXSS 不支持中文类名） */ const COURSE_TAG_MAP: Record = { @@ -58,7 +60,7 @@ Page({ coachRole: '', storeName: '', - /** 月份切换 */ + /** 月份切换（onLoad 中改写为业务时钟当前年月） */ currentYear: new Date().getFullYear(), currentMonth: new Date().getMonth() + 1, monthLabel: '', @@ -83,12 +85,13 @@ Page({ hasMore: false, }, - onLoad() { - const now = new Date() + async onLoad() { + // CHANGE 2026-05-02 | 用业务时钟初始化年月，sandbox 模式按 sandbox_date 显示 + const clock = await getBusinessClock() this.setData({ - currentYear: now.getFullYear(), - currentMonth: now.getMonth() + 1, - monthLabel: `${now.getFullYear()}年${now.getMonth() + 1}月`, + currentYear: clock.business_year, + currentMonth: clock.business_month, + monthLabel: `${clock.business_year}年${clock.business_month}月`, }) this.loadBanner() this.loadData() @@ -140,11 +143,13 @@ Page({ wx.showLoading({ title: '加载中...', mask: true }) // 预估规则：当月且当前日期 ≤ 5号（全小程序统一） - const now = new Date() + // CHANGE 2026-05-02 | 用业务时钟，sandbox 模式按 sandbox_date 判断 + const clock = await getBusinessClock() const { currentYear, currentMonth } = this.data - const isCurrentMonth = currentYear === now.getFullYear() - && currentMonth === now.getMonth() + 1 - && now.getDate() <= 5 + const businessDay = parseInt(clock.business_date.slice(8, 10), 10) || 1 + const isCurrentMonth = currentYear === clock.business_year + && currentMonth === clock.business_month + && businessDay <= 5 try { const res = await fetchPerformanceRecords({ @@ -243,7 +248,7 @@ Page({ }, /** 切换月份 */ - switchMonth(e: WechatMiniprogram.TouchEvent) { + async switchMonth(e: WechatMiniprogram.TouchEvent) { const direction = e.currentTarget.dataset.direction as 'prev' | 'next' let { currentYear, currentMonth } = this.data @@ -255,11 +260,13 @@ Page({ if (currentMonth > 12) { currentMonth = 1; currentYear++ } } - const now = new Date() - const nowYear = now.getFullYear() - const nowMonth = now.getMonth() + 1 + // CHANGE 2026-05-02 | 用业务时钟，sandbox 模式下不允许"翻到 sandbox_date 之后" + const clock = await getBusinessClock() + const nowYear = clock.business_year + const nowMonth = clock.business_month + const businessDay = parseInt(clock.business_date.slice(8, 10), 10) || 1 const canGoNext = currentYear < nowYear || (currentYear === nowYear && currentMonth < nowMonth) - const isCurrentMonth = currentYear === nowYear && currentMonth === nowMonth && now.getDate() <= 5 + const isCurrentMonth = currentYear === nowYear && currentMonth === nowMonth && businessDay <= 5 // 月份切换重置分页到第 1 页 this.setData({ diff --git a/apps/miniprogram/miniprogram/pages/performance/performance.ts b/apps/miniprogram/miniprogram/pages/performance/performance.ts index bcc0362..4ad9517 100644 --- a/apps/miniprogram/miniprogram/pages/performance/performance.ts +++ b/apps/miniprogram/miniprogram/pages/performance/performance.ts @@ -10,6 +10,8 @@ import { fetchMe, fetchPerformanceOverview } from '../../services/api' import { nameToAvatarColor } from '../../utils/avatar-color' // CHANGE 2026-03-27 | 头像：需要 API_BASE 构建头像完整 URL import { API_BASE } from '../../utils/config' +// CHANGE 2026-05-02 | 业务时钟：sandbox 模式下用 business_year/month 替代 new Date() +import { getBusinessClock } from '../../utils/runtime-clock' /** 中文课程类型 → 英文 CSS key（WXSS 不支持中文类名） */ const COURSE_TAG_MAP: Record = { @@ -118,15 +120,16 @@ Page({ this.setData({ pageState: 'loading' }) wx.showLoading({ title: '加载中...', mask: true }) - // G2：当月预估判断 - const now = new Date() - const nowYear = now.getFullYear() - const nowMonth = now.getMonth() + 1 + // CHANGE 2026-05-02 | G2 当月预估判断改用业务时钟（sandbox 模式按 sandbox_date 判断） + const clock = await getBusinessClock() + const nowYear = clock.business_year + const nowMonth = clock.business_month + const businessDay = parseInt(clock.business_date.slice(8, 10), 10) || 1 // TODO: 联调时从接口参数或页面参数获取 year/month const year = nowYear const month = nowMonth // CHANGE 2026-03-24 | 预估规则：当月且当前日期 ≤ 5号才显示"预估" - const isCurrentMonth = year === nowYear && month === nowMonth && now.getDate() <= 5 + const isCurrentMonth = year === nowYear && month === nowMonth && businessDay <= 5 try { // 并行请求用户信息和绩效概览 diff --git a/apps/miniprogram/miniprogram/pages/task-list/task-list.ts b/apps/miniprogram/miniprogram/pages/task-list/task-list.ts index bf6357e..b112142 100644 --- a/apps/miniprogram/miniprogram/pages/task-list/task-list.ts +++ b/apps/miniprogram/miniprogram/pages/task-list/task-list.ts @@ -20,6 +20,8 @@ import { fetchTasks, fetchMe, pinTask, unpinTask, abandonTask, restoreTask, crea import { formatMoney } from '../../utils/money' import { formatDeadline } from '../../utils/time' import { formatStorageLevel } from '../../utils/storage-level' +// CHANGE 2026-05-02 | 业务时钟：sandbox 模式下用 business_year/month 替代 new Date() +import { getBusinessClock } from '../../utils/runtime-clock' // CHANGE 2026-03-27 | 头像：需要 API_BASE 构建头像完整 URL import { API_BASE } from '../../utils/config' import { @@ -386,9 +388,11 @@ Page({ } // G2: 当月预估判断 - const now = new Date() - const nowYear = now.getFullYear() - const nowMonth = now.getMonth() + 1 + // CHANGE 2026-05-02 | 用业务时钟，sandbox 模式按 sandbox_date 判断 + const clock = await getBusinessClock() + const nowYear = clock.business_year + const nowMonth = clock.business_month + const businessDay = parseInt(clock.business_date.slice(8, 10), 10) || 1 const incomeMonth = perfData.incomeMonth let dataYear = nowYear let dataMonth = nowMonth @@ -397,7 +401,7 @@ Page({ if (parts) dataMonth = parseInt(parts[1], 10) } // CHANGE 2026-03-24 | 预估规则：当月且当前日期 ≤ 5号才显示"预估"（全小程序统一） - const isCurrentMonth = dataYear === nowYear && dataMonth === nowMonth && now.getDate() <= 5 + const isCurrentMonth = dataYear === nowYear && dataMonth === nowMonth && businessDay <= 5 this.setData({ pageState: totalCount > 0 ? 'normal' : 'empty', diff --git a/apps/miniprogram/miniprogram/services/api.ts b/apps/miniprogram/miniprogram/services/api.ts index 7a50c10..4b02996 100644 --- a/apps/miniprogram/miniprogram/services/api.ts +++ b/apps/miniprogram/miniprogram/services/api.ts @@ -35,6 +35,31 @@ export async function fetchMe(): Promise { return request({ url: '/api/xcx/me', method: 'GET', needAuth: true }) } +// ============================================ +// 业务时钟（沙箱支持） +// ============================================ + +export interface RuntimeClock { + mode: 'live' | 'sandbox' + business_date: string // YYYY-MM-DD + business_year: number + business_month: number + business_year_month: string // YYYY-MM + business_now: string + is_sandbox: boolean + sandbox_date: string | null + sandbox_instance_id: string | null +} + +/** + * 获取当前门店的业务时钟（live 真实日，sandbox 模拟日）。 + * 沙箱模式下，小程序所有依赖"当前年月"的请求都应使用此结果， + * 避免直接 ``new Date()`` 导致与后端 sandbox_date 不一致。 + */ +export async function fetchRuntimeClock(): Promise { + return request({ url: '/api/xcx/runtime/clock', method: 'GET', needAuth: true }) +} + // ============================================ // 任务模块 // ============================================ @@ -413,6 +438,26 @@ export async function sendChatMessage(chatId: string, content: string): Promise< // 配置模块 // ============================================ +/** AI 缓存查询（Phase 2.5） */ +export async function fetchAICache(cacheType: string, targetId: string): Promise<{ + result_json: Record | null; + score: number | null; +} | null> { + try { + const data = await request({ + url: `/api/ai/cache/${cacheType}`, + method: 'GET', + data: { target_id: targetId }, + needAuth: true, + }) + if (!data) return null + const d = data as any + return { result_json: d.result_json ?? null, score: d.score ?? null } + } catch { + return null + } +} + /** 项目类型筛选器列表（CONFIG-1） */ // CHANGE 2026-03-20 | R3 修复：value 改为数据库 category_code，fallback 与后端一致 export async function fetchSkillTypes(): Promise> { diff --git a/apps/miniprogram/miniprogram/utils/runtime-clock.ts b/apps/miniprogram/miniprogram/utils/runtime-clock.ts new file mode 100644 index 0000000..f3a39c6 --- /dev/null +++ b/apps/miniprogram/miniprogram/utils/runtime-clock.ts @@ -0,0 +1,83 @@ +// 业务时钟缓存 +// +// sandbox 模式下，小程序的 performance / task-list / customer-records 等页面 +// 需要按"业务日"而不是"真实今天"构造请求参数。 +// +// 用法： +// import { getBusinessClock, getBusinessYearMonth } from '../../utils/runtime-clock' +// const clock = await getBusinessClock() +// wx.request({ url: ..., data: { year: clock.business_year, month: clock.business_month } }) +// +// 缓存策略： +// - 单例 in-memory cache，最多 60 秒；过期后自动重新拉取。 +// - 切换沙箱后，建议页面调用 `clearBusinessClockCache()` 主动失效。 + +import { fetchRuntimeClock, type RuntimeClock } from '../services/api' + +const TTL_MS = 60_000 // 60 秒缓存，足以覆盖一次页面进入 + +let cached: { value: RuntimeClock; ts: number } | null = null +let inflight: Promise | null = null + +/** 主动清空业务时钟缓存（沙箱切换、登出后调用）。 */ +export function clearBusinessClockCache(): void { + cached = null + inflight = null +} + +/** 拉取业务时钟（可能命中缓存）。失败时降级为本地"今天"。 */ +export async function getBusinessClock(force = false): Promise { + const now = Date.now() + if (!force && cached && now - cached.ts < TTL_MS) { + return cached.value + } + if (inflight) { + return inflight + } + inflight = (async () => { + try { + const clock = await fetchRuntimeClock() + cached = { value: clock, ts: Date.now() } + return clock + } catch (err) { + console.warn('[runtime-clock] 拉取业务时钟失败，降级为本地时间', err) + return localFallback() + } finally { + inflight = null + } + })() + return inflight +} + +/** 便捷方法：返回业务年月 (YYYY-MM)。 */ +export async function getBusinessYearMonth(): Promise<{ year: number; month: number; label: string }> { + const clock = await getBusinessClock() + return { + year: clock.business_year, + month: clock.business_month, + label: `${clock.business_year}年${clock.business_month}月`, + } +} + +/** 便捷方法：返回业务日 (YYYY-MM-DD)。 */ +export async function getBusinessDate(): Promise { + return (await getBusinessClock()).business_date +} + +function localFallback(): RuntimeClock { + const d = new Date() + const year = d.getFullYear() + const month = d.getMonth() + 1 + const ymd = `${year}-${String(month).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}` + return { + mode: 'live', + business_date: ymd, + business_year: year, + business_month: month, + business_year_month: `${year}-${String(month).padStart(2, '0')}`, + business_now: d.toISOString(), + is_sandbox: false, + sandbox_date: null, + sandbox_instance_id: null, + } +} diff --git a/db/etl_feiqiu/migrations/20260502__rls_views_business_date_upper_bound.sql b/db/etl_feiqiu/migrations/20260502__rls_views_business_date_upper_bound.sql new file mode 100644 index 0000000..a95b0ad --- /dev/null +++ b/db/etl_feiqiu/migrations/20260502__rls_views_business_date_upper_bound.sql @@ -0,0 +1,1258 @@ +-- ============================================================================= +-- ETL 库（etl_feiqiu）/ app schema —— RLS 视图业务日上界裁剪 +-- 由 scripts/ops/gen_rls_business_date_migration.py 自动生成。 +-- 沙箱模式下，业务读取层只看到 sandbox_date 及之前的数据。 +-- ============================================================================= + +BEGIN; + +-- helper：业务日 GUC 读取，缺省回退当前真实日期 +CREATE OR REPLACE FUNCTION app.business_date_now() +RETURNS date +LANGUAGE sql +STABLE +AS $$ + SELECT COALESCE( + NULLIF(current_setting('app.current_business_date', true), '')::date, + CURRENT_DATE + ); +$$; +COMMENT ON FUNCTION app.business_date_now() IS +'返回当前业务日（GUC app.current_business_date），未设置时回退 CURRENT_DATE。'; + + +-- app.v_dws_finance_area_daily：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_finance_area_daily AS + SELECT id, + site_id, + tenant_id, + stat_date, + area_code, + table_fee_amount, + goods_amount, + assistant_pd_amount, + assistant_cx_amount, + gross_amount, + discount_groupbuy, + discount_vip, + discount_manual, + discount_gift_card, + discount_rounding, + discount_other, + discount_total, + confirmed_income, + cash_pay_amount, + cash_paper_amount, + scan_pay_amount, + groupbuy_pay_amount, + recharge_cash_inflow, + cash_inflow_total, + cash_outflow_total, + cash_balance_change, + card_consume_total, + recharge_card_consume, + gift_card_consume, + recharge_cash, + first_recharge_cash, + renewal_cash, + order_count, + created_at, + updated_at, + member_order_count + FROM dws.dws_finance_area_daily + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND stat_date <= app.business_date_now() + AND stat_date <= app.business_date_now(); + + +-- app.v_dws_finance_daily_summary：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_finance_daily_summary AS + SELECT id, + site_id, + tenant_id, + stat_date, + gross_amount, + table_fee_amount, + goods_amount, + assistant_pd_amount, + assistant_cx_amount, + discount_total, + discount_groupbuy, + discount_vip, + discount_gift_card, + discount_manual, + discount_rounding, + discount_other, + confirmed_income, + cash_inflow_total, + cash_pay_amount, + cash_paper_amount, + scan_pay_amount, + groupbuy_pay_amount, + platform_settlement_amount, + platform_fee_amount, + recharge_cash_inflow, + card_consume_total, + recharge_card_consume AS cash_card_consume, + gift_card_consume, + cash_outflow_total, + cash_balance_change, + recharge_count, + recharge_total, + recharge_cash, + recharge_gift, + first_recharge_count, + first_recharge_amount, + renewal_count, + renewal_amount, + order_count, + member_order_count, + guest_order_count, + avg_order_amount, + created_at, + updated_at + FROM dws.dws_finance_daily_summary + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND stat_date <= app.business_date_now() + AND stat_date <= app.business_date_now(); + + +-- app.v_dws_finance_discount_detail：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_finance_discount_detail AS + SELECT id, + site_id, + tenant_id, + stat_date, + discount_type_code, + discount_type_name, + discount_amount, + discount_ratio, + usage_count, + affected_orders, + created_at, + updated_at + FROM dws.dws_finance_discount_detail + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND stat_date <= app.business_date_now() + AND stat_date <= app.business_date_now(); + + +-- app.v_dws_finance_expense_summary：加业务日上界 → expense_month <= date_trunc('month', app.business_date_now())::date +CREATE OR REPLACE VIEW app.v_dws_finance_expense_summary AS + SELECT id, + site_id, + tenant_id, + expense_month, + expense_type_code, + expense_type_name, + expense_category, + expense_amount, + expense_detail, + import_batch_no, + import_file_name, + import_time, + import_user, + remark, + created_at, + updated_at + FROM dws.dws_finance_expense_summary + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND expense_month <= date_trunc('month'::text, app.business_date_now()::timestamp with time zone)::date + AND expense_month <= date_trunc('month', app.business_date_now())::date; + + +-- app.v_dws_finance_income_structure：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_finance_income_structure AS + SELECT id, + site_id, + tenant_id, + stat_date, + structure_type, + category_code, + category_name, + income_amount, + income_ratio, + order_count, + duration_minutes, + created_at, + updated_at + FROM dws.dws_finance_income_structure + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND stat_date <= app.business_date_now() + AND stat_date <= app.business_date_now(); + + +-- app.v_dws_finance_recharge_summary：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_finance_recharge_summary AS + SELECT id, + site_id, + tenant_id, + stat_date, + recharge_count, + recharge_total, + recharge_cash, + recharge_gift, + first_recharge_count, + first_recharge_cash, + first_recharge_gift, + first_recharge_total, + renewal_count, + renewal_cash, + renewal_gift, + renewal_total, + recharge_member_count, + new_member_count, + total_card_balance, + cash_card_balance, + gift_card_balance, + gift_liquor_balance, + gift_table_fee_balance, + gift_voucher_balance, + gift_liquor_recharge, + gift_table_fee_recharge, + gift_voucher_recharge, + created_at, + updated_at + FROM dws.dws_finance_recharge_summary + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND stat_date <= app.business_date_now() + AND stat_date <= app.business_date_now(); + + +-- app.v_assistant_daily：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_assistant_daily AS + SELECT id, + site_id, + tenant_id, + assistant_id, + assistant_nickname, + stat_date, + total_service_count, + total_hours, + base_hours, + bonus_hours, + room_hours, + total_ledger_amount, + unique_customers, + unique_tables, + created_at + FROM dws.dws_assistant_daily_detail d + WHERE stat_date <= app.business_date_now() + AND stat_date <= app.business_date_now(); + + +-- app.v_dws_assistant_daily_detail：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_assistant_daily_detail AS + SELECT id, + site_id, + tenant_id, + assistant_id, + assistant_nickname, + stat_date, + assistant_level_code, + assistant_level_name, + total_service_count, + base_service_count, + bonus_service_count, + room_service_count, + total_seconds, + base_seconds, + bonus_seconds, + room_seconds, + total_hours, + base_hours, + bonus_hours, + room_hours, + total_ledger_amount, + base_ledger_amount, + bonus_ledger_amount, + room_ledger_amount, + unique_customers, + unique_tables, + trashed_seconds, + trashed_count, + created_at, + updated_at, + penalty_minutes, + penalty_reason, + is_exempt, + per_hour_contribution + FROM dws.dws_assistant_daily_detail + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND stat_date <= app.business_date_now() + AND stat_date <= app.business_date_now(); + + +-- app.v_dws_assistant_finance_analysis：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_assistant_finance_analysis AS + SELECT id, + site_id, + tenant_id, + stat_date, + assistant_id, + assistant_nickname, + revenue_total, + revenue_base, + revenue_bonus, + revenue_room, + cost_daily, + gross_profit, + gross_margin, + service_count, + service_hours, + room_service_count, + room_service_hours, + unique_customers, + created_at, + updated_at + FROM dws.dws_assistant_finance_analysis + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND stat_date <= app.business_date_now() + AND stat_date <= app.business_date_now(); + + +-- app.v_dws_assistant_monthly_summary：加业务日上界 → stat_month <= date_trunc('month', app.business_date_now())::date +CREATE OR REPLACE VIEW app.v_dws_assistant_monthly_summary AS + SELECT id, + site_id, + tenant_id, + assistant_id, + assistant_nickname, + stat_month, + assistant_level_code, + assistant_level_name, + hire_date, + is_new_hire, + work_days, + total_service_count, + base_service_count, + bonus_service_count, + room_service_count, + total_hours, + base_hours, + bonus_hours, + room_hours, + effective_hours, + trashed_hours, + total_ledger_amount, + base_ledger_amount, + bonus_ledger_amount, + room_ledger_amount, + unique_customers, + unique_tables, + avg_service_seconds, + tier_id, + tier_code, + tier_name, + rank_by_hours, + rank_with_ties, + created_at, + updated_at + FROM dws.dws_assistant_monthly_summary + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND stat_month <= date_trunc('month'::text, app.business_date_now()::timestamp with time zone)::date + AND stat_month <= date_trunc('month', app.business_date_now())::date; + + +-- app.v_dws_assistant_salary_calc：加业务日上界 → salary_month <= date_trunc('month', app.business_date_now())::date +CREATE OR REPLACE VIEW app.v_dws_assistant_salary_calc AS + SELECT id, + site_id, + tenant_id, + assistant_id, + assistant_nickname, + salary_month, + assistant_level_code, + assistant_level_name, + hire_date, + is_new_hire, + effective_hours, + base_hours, + bonus_hours, + room_hours, + tier_id, + tier_code, + tier_name, + rank_with_ties, + base_course_price, + bonus_course_price, + base_deduction, + bonus_deduction_ratio, + base_income, + bonus_income, + room_income, + total_course_income, + sprint_bonus, + top_rank_bonus, + recharge_commission, + other_bonus, + total_bonus, + gross_salary, + vacation_days, + vacation_unlimited, + calc_notes, + created_at, + updated_at + FROM dws.dws_assistant_salary_calc + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND salary_month <= date_trunc('month'::text, app.business_date_now()::timestamp with time zone)::date + AND salary_month <= date_trunc('month', app.business_date_now())::date; + + +-- app.v_dws_member_consumption_summary：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_member_consumption_summary AS + SELECT DISTINCT ON (member_id) id, + site_id, + tenant_id, + member_id, + stat_date, + member_nickname, + member_mobile, + card_grade_name, + register_date, + first_consume_date, + last_consume_date, + total_visit_count, + total_consume_amount, + total_recharge_amount, + total_table_fee, + total_goods_amount, + total_assistant_amount, + visit_count_7d, + visit_count_10d, + visit_count_15d, + visit_count_30d, + visit_count_60d, + visit_count_90d, + consume_amount_7d, + consume_amount_10d, + consume_amount_15d, + consume_amount_30d, + consume_amount_60d, + consume_amount_90d, + cash_card_balance, + gift_card_balance, + total_card_balance, + days_since_last, + is_active_7d, + is_active_30d, + is_active_90d, + customer_tier, + created_at, + updated_at, + recharge_count_30d, + recharge_count_60d, + recharge_count_90d, + recharge_amount_30d, + recharge_amount_60d, + recharge_amount_90d, + avg_ticket_amount + FROM dws.dws_member_consumption_summary + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND stat_date <= app.business_date_now() + AND stat_date <= app.business_date_now() + ORDER BY member_id, stat_date DESC; + + +-- app.v_dws_member_visit_detail：加业务日上界 → visit_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_member_visit_detail AS + SELECT id, + site_id, + tenant_id, + member_id, + order_settle_id, + visit_date, + visit_time, + member_nickname, + member_mobile, + member_birthday, + table_id, + table_name, + area_name, + area_category, + table_fee, + goods_amount, + assistant_amount, + total_consume, + total_discount, + actual_pay, + cash_pay, + balance_pay AS cash_card_pay, + gift_card_pay, + groupbuy_pay, + table_duration_min, + assistant_duration_min, + assistant_services, + created_at, + updated_at + FROM dws.dws_member_visit_detail + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND visit_date <= app.business_date_now() + AND visit_date <= app.business_date_now(); + + +-- app.v_dws_member_winback_index：加业务日上界 → COALESCE(last_visit_time::date, '0001-01-01'::date) <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_member_winback_index AS + SELECT DISTINCT ON (member_id) winback_id, + site_id, + tenant_id, + member_id, + status, + segment, + member_create_time, + first_visit_time, + last_visit_time, + last_recharge_time, + t_v, + t_r, + t_a, + visits_14d, + visits_30d, + visits_60d, + visits_total, + spend_30d, + spend_180d, + sv_balance, + recharge_60d_amt, + interval_count, + overdue_old, + drop_old, + recharge_old, + value_old, + raw_score, + display_score, + last_wechat_touch_time, + calc_time, + calc_version, + created_at, + updated_at, + overdue_cdf_p, + ideal_interval_days, + ideal_next_visit_date, + stat_date + FROM dws.dws_member_winback_index + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND COALESCE(last_visit_time::date, '0001-01-01'::date) <= app.business_date_now() + AND COALESCE(last_visit_time::date, '0001-01-01'::date) <= app.business_date_now() + ORDER BY member_id, stat_date DESC; + + +-- app.v_dwd_settlement_head：加业务日上界 → COALESCE(create_time::date, '0001-01-01'::date) <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dwd_settlement_head AS + SELECT order_settle_id, + tenant_id, + site_id, + site_name, + table_id, + settle_name, + order_trade_no, + create_time, + pay_time, + settle_type, + revoke_order_id, + member_id, + member_name, + member_phone, + member_card_account_id, + member_card_type_name, + is_bind_member, + member_discount_amount, + consume_money, + table_charge_money, + goods_money, + real_goods_money, + assistant_pd_money, + assistant_cx_money, + adjust_amount, + pay_amount, + balance_amount, + recharge_card_amount, + gift_card_amount, + coupon_amount, + rounding_amount, + point_amount, + electricity_money, + real_electricity_money, + electricity_adjust_money, + pl_coupon_sale_amount, + mervou_sales_amount + FROM dwd.dwd_settlement_head + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND COALESCE(create_time::date, '0001-01-01'::date) <= app.business_date_now() + AND COALESCE(create_time::date, '0001-01-01'::date) <= app.business_date_now(); + + +-- app.v_dwd_assistant_service_log：加业务日上界 → COALESCE(create_time::date, '0001-01-01'::date) <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dwd_assistant_service_log AS + SELECT assistant_service_id, + order_trade_no, + order_settle_id, + order_pay_id, + order_assistant_id, + order_assistant_type, + tenant_id, + site_id, + site_table_id, + tenant_member_id, + system_member_id, + assistant_no, + nickname, + site_assistant_id, + user_id, + assistant_team_id, + person_org_id, + assistant_level, + level_name, + skill_id, + skill_name, + ledger_unit_price, + ledger_amount, + projected_income, + coupon_deduct_money, + income_seconds, + real_use_seconds, + add_clock, + create_time, + start_use_time, + last_use_time, + is_delete, + real_service_money + FROM dwd.dwd_assistant_service_log + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND COALESCE(create_time::date, '0001-01-01'::date) <= app.business_date_now() + AND COALESCE(create_time::date, '0001-01-01'::date) <= app.business_date_now(); + + +-- app.v_dwd_recharge_order：加业务日上界 → COALESCE(pay_time::date, '0001-01-01'::date) <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dwd_recharge_order AS + SELECT recharge_order_id, + tenant_id, + site_id, + member_id, + member_name_snapshot, + member_phone_snapshot, + tenant_member_card_id, + member_card_type_name, + settle_relate_id, + settle_type, + settle_name, + is_first, + pay_amount, + refund_amount, + point_amount, + cash_amount, + payment_method, + create_time, + pay_time, + pl_coupon_sale_amount, + mervou_sales_amount, + electricity_money, + real_electricity_money, + electricity_adjust_money + FROM dwd.dwd_recharge_order + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND COALESCE(pay_time::date, '0001-01-01'::date) <= app.business_date_now() + AND COALESCE(pay_time::date, '0001-01-01'::date) <= app.business_date_now(); + + +-- app.v_dwd_store_goods_sale：加业务日上界 → COALESCE(create_time::date, '0001-01-01'::date) <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dwd_store_goods_sale AS + SELECT store_goods_sale_id, + order_trade_no, + order_settle_id, + order_pay_id, + order_goods_id, + site_id, + tenant_id, + site_goods_id, + tenant_goods_id, + tenant_goods_category_id, + tenant_goods_business_id, + site_table_id, + ledger_name, + ledger_group_name, + ledger_unit_price, + ledger_count, + ledger_amount, + discount_money, + real_goods_money, + cost_money, + ledger_status, + is_delete, + create_time, + coupon_share_money, + discount_price + FROM dwd.dwd_store_goods_sale + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND COALESCE(create_time::date, '0001-01-01'::date) <= app.business_date_now() + AND COALESCE(create_time::date, '0001-01-01'::date) <= app.business_date_now(); + + +-- app.v_dwd_table_fee_log：加业务日上界 → COALESCE(create_time::date, '0001-01-01'::date) <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dwd_table_fee_log AS + SELECT table_fee_log_id, + order_trade_no, + order_settle_id, + order_pay_id, + tenant_id, + site_id, + site_table_id, + site_table_area_id, + site_table_area_name, + tenant_table_area_id, + member_id, + ledger_name, + ledger_unit_price, + ledger_count, + ledger_amount, + real_table_charge_money, + coupon_promotion_amount, + member_discount_amount, + adjust_amount, + real_table_use_seconds, + add_clock_seconds, + start_use_time, + ledger_end_time, + create_time, + ledger_status, + is_single_order, + is_delete, + activity_discount_amount, + real_service_money + FROM dwd.dwd_table_fee_log + WHERE site_id = current_setting('app.current_site_id'::text)::bigint AND COALESCE(create_time::date, '0001-01-01'::date) <= app.business_date_now() + AND COALESCE(create_time::date, '0001-01-01'::date) <= app.business_date_now(); + + +-- app.v_cfg_assistant_level_price：加业务日上界 → effective_from <= app.business_date_now() AND effective_to >= app.business_date_now() +CREATE OR REPLACE VIEW app.v_cfg_assistant_level_price AS + SELECT price_id, + level_code, + level_name, + base_course_price, + bonus_course_price, + effective_from, + effective_to, + description, + created_at, + updated_at + FROM dws.cfg_assistant_level_price + WHERE effective_from <= app.business_date_now() AND effective_to >= app.business_date_now() + AND effective_from <= app.business_date_now() AND effective_to >= app.business_date_now(); + + +-- app.v_cfg_performance_tier：加业务日上界 → effective_from <= app.business_date_now() AND effective_to >= app.business_date_now() +CREATE OR REPLACE VIEW app.v_cfg_performance_tier AS + SELECT tier_id, + tier_code, + tier_name, + tier_level, + min_hours, + max_hours, + base_deduction, + bonus_deduction_ratio, + vacation_days, + vacation_unlimited, + is_new_hire_tier, + effective_from, + effective_to, + description, + created_at, + updated_at + FROM dws.cfg_performance_tier + WHERE effective_from <= app.business_date_now() AND effective_to >= app.business_date_now() + AND effective_from <= app.business_date_now() AND effective_to >= app.business_date_now(); + + +-- app.v_cfg_bonus_rules：加业务日上界 → effective_from <= app.business_date_now() AND effective_to >= app.business_date_now() +CREATE OR REPLACE VIEW app.v_cfg_bonus_rules AS + SELECT rule_id, + rule_type, + rule_code, + rule_name, + threshold_hours, + rank_position, + bonus_amount, + is_cumulative, + priority, + effective_from, + effective_to, + description, + created_at, + updated_at + FROM dws.cfg_bonus_rules + WHERE effective_from <= app.business_date_now() AND effective_to >= app.business_date_now(); + + +-- app.v_cfg_index_parameters：加业务日上界 → effective_from <= app.business_date_now() AND effective_to >= app.business_date_now() +CREATE OR REPLACE VIEW app.v_cfg_index_parameters AS + SELECT param_id, + index_type, + param_name, + param_value, + description, + effective_from, + effective_to, + created_at, + updated_at + FROM dws.cfg_index_parameters + WHERE effective_from <= app.business_date_now() AND effective_to >= app.business_date_now(); + + +-- app.v_dws_assistant_customer_stats：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_assistant_customer_stats AS + SELECT DISTINCT ON (assistant_id, member_id) id, + site_id, + tenant_id, + assistant_id, + assistant_nickname, + member_id, + member_nickname, + member_mobile, + stat_date, + first_service_date, + last_service_date, + total_service_count, + total_service_hours, + total_service_amount, + service_count_7d, + service_count_10d, + service_count_15d, + service_count_30d, + service_count_60d, + service_count_90d, + service_hours_7d, + service_hours_10d, + service_hours_15d, + service_hours_30d, + service_hours_60d, + service_hours_90d, + service_amount_7d, + service_amount_10d, + service_amount_15d, + service_amount_30d, + service_amount_60d, + service_amount_90d, + days_since_last, + is_active_7d, + is_active_30d, + created_at, + updated_at + FROM dws.dws_assistant_customer_stats + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND stat_date <= app.business_date_now() + ORDER BY assistant_id, member_id, stat_date DESC; + + +-- app.v_dws_assistant_order_contribution：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_assistant_order_contribution AS + SELECT contribution_id, + site_id, + tenant_id, + assistant_id, + assistant_nickname, + stat_date, + order_gross_revenue, + order_net_revenue, + time_weighted_revenue, + time_weighted_net_revenue, + order_count, + total_service_seconds, + created_at, + updated_at + FROM dws.dws_assistant_order_contribution + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND stat_date <= app.business_date_now(); + + +-- app.v_dws_assistant_project_tag：加业务日上界 → computed_at::date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_assistant_project_tag AS + SELECT id, + site_id, + tenant_id, + assistant_id, + time_window, + category_code, + category_name, + short_name, + duration_seconds, + total_seconds, + percentage, + is_tagged, + computed_at, + created_at, + updated_at + FROM dws.dws_assistant_project_tag + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND computed_at::date <= app.business_date_now(); + + +-- app.v_dws_assistant_recharge_commission：加业务日上界 → commission_month <= date_trunc('month', app.business_date_now())::date +CREATE OR REPLACE VIEW app.v_dws_assistant_recharge_commission AS + SELECT id, + site_id, + tenant_id, + assistant_id, + assistant_nickname, + commission_month, + recharge_order_id, + recharge_order_no, + recharge_amount, + commission_amount, + commission_ratio, + import_batch_no, + import_file_name, + import_time, + import_user, + remark, + created_at, + updated_at + FROM dws.dws_assistant_recharge_commission + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND commission_month <= date_trunc('month', app.business_date_now())::date; + + +-- app.v_dws_coach_area_hours：加业务日上界 → stat_month <= date_trunc('month', app.business_date_now())::date +CREATE OR REPLACE VIEW app.v_dws_coach_area_hours AS + SELECT id, + site_id, + tenant_id, + stat_month, + assistant_id, + area_code, + base_hours, + bonus_hours, + room_hours, + effective_hours, + trashed_hours, + base_service_count, + bonus_service_count, + room_service_count, + created_at, + updated_at + FROM dws.dws_coach_area_hours + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND stat_month <= date_trunc('month', app.business_date_now())::date; + + +-- app.v_dws_finance_board_cache：加业务日上界 → computed_at::date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_finance_board_cache AS + SELECT id, + site_id, + time_range, + area_code, + start_date, + end_date, + prev_start_date, + prev_end_date, + occurrence, + discount, + discount_rate, + confirmed_revenue, + cash_in, + cash_out, + cash_balance, + balance_rate, + data_fingerprint, + computed_at, + created_at, + updated_at + FROM dws.dws_finance_board_cache + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND computed_at::date <= app.business_date_now(); + + +-- app.v_dws_member_assistant_intimacy：加业务日上界 → calc_time::date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_member_assistant_intimacy AS + SELECT intimacy_id, + site_id, + tenant_id, + member_id, + assistant_id, + session_count, + total_duration_minutes, + basic_session_count, + incentive_session_count, + days_since_last_session, + attributed_recharge_count, + attributed_recharge_amount, + score_frequency, + score_recency, + score_recharge, + score_duration, + burst_multiplier, + raw_score, + display_score, + calc_time, + calc_version, + created_at, + updated_at + FROM dws.dws_member_assistant_intimacy + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND calc_time::date <= app.business_date_now(); + + +-- app.v_dws_member_assistant_relation_index：加业务日上界 → COALESCE(stat_date, calc_time::date) <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_member_assistant_relation_index AS + SELECT DISTINCT ON (member_id, assistant_id) relation_id, + site_id, + tenant_id, + member_id, + assistant_id, + session_count, + total_duration_minutes, + basic_session_count, + incentive_session_count, + days_since_last_session, + rs_f, + rs_d, + rs_r, + rs_raw, + rs_display, + os_share, + os_label, + os_rank, + ms_f_short, + ms_f_long, + ms_raw, + ms_display, + ml_order_count, + ml_allocated_amount, + ml_raw, + ml_display, + calc_time, + created_at, + updated_at, + recall_created_total, + recall_completed_total, + follow_up_created_total, + follow_up_completed_total, + total_created, + total_completed, + stat_date + FROM dws.dws_member_assistant_relation_index + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND COALESCE(stat_date, calc_time::date) <= app.business_date_now() + ORDER BY member_id, assistant_id, stat_date DESC; + + +-- app.v_dws_member_newconv_index：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_member_newconv_index AS + SELECT DISTINCT ON (member_id) newconv_id, + site_id, + tenant_id, + member_id, + status, + segment, + member_create_time, + first_visit_time, + last_visit_time, + last_recharge_time, + t_v, + t_r, + t_a, + visits_14d, + visits_30d, + visits_60d, + visits_total, + spend_30d, + spend_180d, + sv_balance, + recharge_60d_amt, + interval_count, + need_new, + salvage_new, + recharge_new, + value_new, + welcome_new, + raw_score_welcome, + raw_score_convert, + raw_score, + display_score_welcome, + display_score_convert, + display_score, + last_wechat_touch_time, + calc_time, + calc_version, + created_at, + updated_at, + stat_date + FROM dws.dws_member_newconv_index + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND stat_date <= app.business_date_now() + ORDER BY member_id, stat_date DESC; + + +-- app.v_dws_member_project_tag：加业务日上界 → computed_at::date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_member_project_tag AS + SELECT id, + site_id, + tenant_id, + member_id, + time_window, + category_code, + category_name, + short_name, + duration_seconds, + total_seconds, + percentage, + is_tagged, + computed_at, + created_at, + updated_at + FROM dws.dws_member_project_tag + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND computed_at::date <= app.business_date_now(); + + +-- app.v_dws_member_spending_power_index：加业务日上界 → calc_time::date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_member_spending_power_index AS + SELECT spi_id, + site_id, + member_id, + spend_30, + spend_90, + recharge_90, + orders_30, + orders_90, + visit_days_30, + visit_days_90, + avg_ticket_90, + active_weeks_90, + daily_spend_ewma_90, + score_level_raw, + score_speed_raw, + score_stability_raw, + score_level_display, + score_speed_display, + score_stability_display, + raw_score, + display_score, + calc_time, + created_at, + updated_at + FROM dws.dws_member_spending_power_index + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND calc_time::date <= app.business_date_now(); + + +-- app.v_dws_order_summary：加业务日上界 → order_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_order_summary AS + SELECT site_id, + order_settle_id, + order_trade_no, + order_date, + tenant_id, + member_id, + member_flag, + recharge_order_flag, + item_count, + total_item_quantity, + table_fee_amount, + assistant_service_amount, + goods_amount, + group_amount, + total_coupon_deduction, + member_discount_amount, + manual_discount_amount, + order_original_amount, + order_final_amount, + stored_card_deduct, + external_paid_amount, + total_paid_amount, + book_table_flow, + book_assistant_flow, + book_goods_flow, + book_group_flow, + book_order_flow, + order_effective_consume_cash, + order_effective_recharge_cash, + order_effective_flow, + refund_amount, + net_income, + created_at, + updated_at + FROM dws.dws_order_summary + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND order_date <= app.business_date_now(); + + +-- app.v_dws_platform_settlement：加业务日上界 → settlement_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_dws_platform_settlement AS + SELECT id, + site_id, + tenant_id, + settlement_date, + platform_type, + platform_name, + platform_order_no, + order_settle_id, + settlement_amount, + commission_amount, + service_fee, + gross_amount, + import_batch_no, + import_file_name, + import_time, + import_user, + remark, + created_at, + updated_at + FROM dws.dws_platform_settlement + WHERE site_id = current_setting('app.current_site_id'::text)::bigint + AND settlement_date <= app.business_date_now(); + + +-- app.v_finance_daily：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_finance_daily AS + SELECT id, + site_id, + tenant_id, + stat_date, + gross_amount, + table_fee_amount, + goods_amount, + assistant_pd_amount, + assistant_cx_amount, + discount_total, + confirmed_income, + cash_inflow_total, + recharge_count, + recharge_total, + order_count, + member_order_count, + guest_order_count, + avg_order_amount, + created_at + FROM dws.dws_finance_daily_summary f + WHERE stat_date <= app.business_date_now(); + + +-- app.v_member_consumption：加业务日上界 → stat_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_member_consumption AS + SELECT id, + site_id, + tenant_id, + member_id, + stat_date, + member_nickname, + card_grade_name, + total_visit_count, + total_consume_amount, + total_recharge_amount, + last_consume_date, + first_consume_date, + days_since_last, + customer_tier, + created_at + FROM dws.dws_member_consumption_summary mc + WHERE stat_date <= app.business_date_now(); + + +-- app.v_order_summary：加业务日上界 → order_date <= app.business_date_now() +CREATE OR REPLACE VIEW app.v_order_summary AS + SELECT site_id, + order_settle_id, + order_trade_no, + order_date, + tenant_id, + member_id, + member_flag, + order_original_amount, + order_final_amount, + total_paid_amount, + refund_amount, + net_income, + created_at + FROM dws.dws_order_summary os + WHERE order_date <= app.business_date_now(); + + +COMMIT; + + +-- 回滚：DROP FUNCTION app.business_date_now() CASCADE; +-- 然后重新执行 db/etl_feiqiu/schemas/app.sql 即可恢复 live 行为 diff --git a/db/etl_feiqiu/schemas/app.sql b/db/etl_feiqiu/schemas/app.sql index d596c11..678861a 100644 --- a/db/etl_feiqiu/schemas/app.sql +++ b/db/etl_feiqiu/schemas/app.sql @@ -1,6 +1,6 @@ -- ============================================================================= -- etl_feiqiu / app（RLS 视图层） --- 生成日期：2026-04-12 +-- 生成日期：2026-05-02 -- 来源：测试库（通过脚本自动导出） -- ============================================================================= @@ -36,7 +36,8 @@ SELECT id, unique_customers, unique_tables, created_at - FROM dws.dws_assistant_daily_detail d; + FROM dws.dws_assistant_daily_detail d + WHERE (stat_date <= app.business_date_now()); ; CREATE OR REPLACE VIEW app.v_cfg_area_category AS @@ -61,7 +62,8 @@ SELECT price_id, description, created_at, updated_at - FROM dws.cfg_assistant_level_price; + FROM dws.cfg_assistant_level_price + WHERE ((effective_from <= app.business_date_now()) AND (effective_to >= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_cfg_bonus_rules AS @@ -112,7 +114,8 @@ SELECT tier_id, description, created_at, updated_at - FROM dws.cfg_performance_tier; + FROM dws.cfg_performance_tier + WHERE ((effective_from <= app.business_date_now()) AND (effective_to >= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dim_assistant AS @@ -301,7 +304,7 @@ SELECT assistant_service_id, is_delete, real_service_money FROM dwd.dwd_assistant_service_log - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (COALESCE((create_time)::date, '0001-01-01'::date) <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dwd_recharge_order AS @@ -330,7 +333,7 @@ SELECT recharge_order_id, real_electricity_money, electricity_adjust_money FROM dwd.dwd_recharge_order - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (COALESCE((pay_time)::date, '0001-01-01'::date) <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dwd_settlement_head AS @@ -372,7 +375,7 @@ SELECT order_settle_id, pl_coupon_sale_amount, mervou_sales_amount FROM dwd.dwd_settlement_head - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (COALESCE((create_time)::date, '0001-01-01'::date) <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dwd_store_goods_sale AS @@ -402,7 +405,7 @@ SELECT store_goods_sale_id, coupon_share_money, discount_price FROM dwd.dwd_store_goods_sale - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (COALESCE((create_time)::date, '0001-01-01'::date) <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dwd_table_fee_log AS @@ -436,7 +439,7 @@ SELECT table_fee_log_id, activity_discount_amount, real_service_money FROM dwd.dwd_table_fee_log - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (COALESCE((create_time)::date, '0001-01-01'::date) <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_assistant_customer_stats AS @@ -518,7 +521,7 @@ SELECT id, is_exempt, per_hour_contribution FROM dws.dws_assistant_daily_detail - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_assistant_finance_analysis AS @@ -543,7 +546,7 @@ SELECT id, created_at, updated_at FROM dws.dws_assistant_finance_analysis - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_assistant_monthly_summary AS @@ -583,7 +586,7 @@ SELECT id, created_at, updated_at FROM dws.dws_assistant_monthly_summary - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_month <= (date_trunc('month'::text, (app.business_date_now())::timestamp with time zone))::date)); ; CREATE OR REPLACE VIEW app.v_dws_assistant_order_contribution AS @@ -687,7 +690,7 @@ SELECT id, created_at, updated_at FROM dws.dws_assistant_salary_calc - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (salary_month <= (date_trunc('month'::text, (app.business_date_now())::timestamp with time zone))::date)); ; CREATE OR REPLACE VIEW app.v_dws_coach_area_hours AS @@ -746,9 +749,10 @@ SELECT id, renewal_cash, order_count, created_at, - updated_at + updated_at, + member_order_count FROM dws.dws_finance_area_daily - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_finance_board_cache AS @@ -822,7 +826,7 @@ SELECT id, created_at, updated_at FROM dws.dws_finance_daily_summary - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_finance_discount_detail AS @@ -839,7 +843,7 @@ SELECT id, created_at, updated_at FROM dws.dws_finance_discount_detail - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_finance_expense_summary AS @@ -860,7 +864,7 @@ SELECT id, created_at, updated_at FROM dws.dws_finance_expense_summary - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (expense_month <= (date_trunc('month'::text, (app.business_date_now())::timestamp with time zone))::date)); ; CREATE OR REPLACE VIEW app.v_dws_finance_income_structure AS @@ -878,7 +882,7 @@ SELECT id, created_at, updated_at FROM dws.dws_finance_income_structure - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_finance_recharge_summary AS @@ -912,7 +916,7 @@ SELECT id, created_at, updated_at FROM dws.dws_finance_recharge_summary - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_member_assistant_intimacy AS @@ -1033,7 +1037,7 @@ SELECT DISTINCT ON (member_id) id, recharge_amount_90d, avg_ticket_amount FROM dws.dws_member_consumption_summary - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint) + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())) ORDER BY member_id, stat_date DESC; ; @@ -1162,7 +1166,7 @@ SELECT id, created_at, updated_at FROM dws.dws_member_visit_detail - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (visit_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_member_winback_index AS @@ -1204,7 +1208,7 @@ SELECT DISTINCT ON (member_id) winback_id, ideal_next_visit_date, stat_date FROM dws.dws_member_winback_index - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint) + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (COALESCE((last_visit_time)::date, '0001-01-01'::date) <= app.business_date_now())) ORDER BY member_id, stat_date DESC; ; diff --git a/db/zqyy_app/migrations/20260420_ai_trigger_jobs_and_app2_prewarm.sql b/db/zqyy_app/migrations/20260420_ai_trigger_jobs_and_app2_prewarm.sql new file mode 100644 index 0000000..6307d7f --- /dev/null +++ b/db/zqyy_app/migrations/20260420_ai_trigger_jobs_and_app2_prewarm.sql @@ -0,0 +1,89 @@ +-- 20260420_ai_trigger_jobs_and_app2_prewarm.sql +-- 注册 AI 事件触发器 + App2 财务洞察 cron 预热任务 +-- +-- 背景：Phase 0.1~0.3 AI 模块收尾。dispatcher 已注册 5 个 handler 到 +-- trigger_scheduler._JOB_REGISTRY（通过 main.py lifespan 调用）， +-- 但 biz.trigger_jobs 缺对应数据行，fire_event 查不到事件绑定而失效。 +-- +-- 本脚本插入： +-- 4 条 event 类型记录：ai_consumption_settled / ai_note_created / +-- ai_task_assigned / ai_dws_completed +-- 1 条 cron 类型记录：ai_dws_prewarm （每日 08:30 给所有 site 触发 App2 × 8 维度） +-- +-- 幂等：job_name UNIQUE 约束 + ON CONFLICT DO NOTHING。 +-- +-- 验证 SQL（执行后）： +-- 1. SELECT count(*) FROM biz.trigger_jobs WHERE job_type LIKE 'ai_%'; +-- 应为 5 +-- 2. SELECT job_name, trigger_condition, trigger_config FROM biz.trigger_jobs +-- WHERE trigger_condition = 'event' AND trigger_config->>'event_name' LIKE 'ai_%'; +-- 应为 4 条，event_name 与 job_name 一致 +-- 3. SELECT job_name, trigger_config->>'cron_expression' FROM biz.trigger_jobs +-- WHERE job_type = 'ai_dws_prewarm'; +-- 应为 "30 8 * * *" +-- +-- 回滚： +-- DELETE FROM biz.trigger_jobs WHERE job_name IN ( +-- 'ai_consumption_settled', 'ai_note_created', +-- 'ai_task_assigned', 'ai_dws_completed', 'ai_dws_prewarm' +-- ); + +BEGIN; + +-- ── 4 条 event 类型触发器 ────────────────────────────── + +INSERT INTO biz.trigger_jobs + (job_type, job_name, trigger_condition, trigger_config, status, description) +VALUES + ( + 'ai_consumption_settled', + 'ai_consumption_settled', + 'event', + '{"event_name": "ai_consumption_settled"}'::jsonb, + 'enabled', + 'AI 消费事件链：App3 → App8 → App7（+ App4 → App5 含助教）' + ), + ( + 'ai_note_created', + 'ai_note_created', + 'event', + '{"event_name": "ai_note_created"}'::jsonb, + 'enabled', + 'AI 备注事件链：App6 → App8' + ), + ( + 'ai_task_assigned', + 'ai_task_assigned', + 'event', + '{"event_name": "ai_task_assigned"}'::jsonb, + 'enabled', + 'AI 任务分配事件链：App4 → App5' + ), + ( + 'ai_dws_completed', + 'ai_dws_completed', + 'event', + '{"event_name": "ai_dws_completed"}'::jsonb, + 'enabled', + 'AI DWS 完成事件：App2 财务洞察 × 8 时间维度预生成' + ) +ON CONFLICT (job_name) DO NOTHING; + +-- ── 1 条 cron 类型触发器 ─────────────────────────────── + +-- 每日 08:30 对所有 active 门店逐个触发 ai_dws_completed 事件， +-- 作为 etl-completed 端点之外的兜底机制。 +INSERT INTO biz.trigger_jobs + (job_type, job_name, trigger_condition, trigger_config, status, description) +VALUES + ( + 'ai_dws_prewarm', + 'ai_dws_prewarm_0830', + 'cron', + '{"cron_expression": "30 8 * * *"}'::jsonb, + 'enabled', + 'App2 财务洞察每日预热：08:30 对所有门店触发 ai_dws_completed × 8 维度' + ) +ON CONFLICT (job_name) DO NOTHING; + +COMMIT; diff --git a/db/zqyy_app/migrations/20260421_app2_prewarm_cron_reschedule.sql b/db/zqyy_app/migrations/20260421_app2_prewarm_cron_reschedule.sql new file mode 100644 index 0000000..2e9cfb8 --- /dev/null +++ b/db/zqyy_app/migrations/20260421_app2_prewarm_cron_reschedule.sql @@ -0,0 +1,42 @@ +-- 20260421_app2_prewarm_cron_reschedule.sql +-- App2 财务洞察 cron 预热时间从 08:30 调整为 10:00 + 扩展为 72 组合覆盖 +-- +-- 背景：用户需求 2026-04-21 +-- 1) 每日 10:00 为所有门店生成 board-finance 所有筛选组合下的 AI 洞察 +-- 2) 筛选组合 = 8 时间维度 × 9 区域 = 72 组合/门店 +-- 3) 前端根据当前筛选条件读缓存（target_id=time__area） +-- +-- 变更： +-- 1. job_name rename: ai_dws_prewarm_0830 → ai_dws_prewarm_1000 +-- 2. cron_expression: "30 8 * * *" → "0 10 * * *" +-- 3. description 更新为"72 组合"说明 +-- +-- 注：dispatcher._handle_dws_completed 已改为遍历 72 组合，无需额外的 handler 注册。 +-- +-- 验证 SQL（执行后）： +-- 1. SELECT job_name FROM biz.trigger_jobs +-- WHERE job_type = 'ai_dws_prewarm'; +-- 应为 'ai_dws_prewarm_1000' +-- 2. SELECT trigger_config->>'cron_expression' FROM biz.trigger_jobs +-- WHERE job_type = 'ai_dws_prewarm'; +-- 应为 '0 10 * * *' +-- 3. SELECT count(*) FROM biz.trigger_jobs WHERE job_type LIKE 'ai_%'; +-- 应为 5（不变） +-- +-- 回滚： +-- UPDATE biz.trigger_jobs +-- SET job_name = 'ai_dws_prewarm_0830', +-- trigger_config = '{"cron_expression": "30 8 * * *"}'::jsonb, +-- description = 'App2 财务洞察每日预热：08:30 对所有门店触发 ai_dws_completed × 8 维度' +-- WHERE job_type = 'ai_dws_prewarm'; + +BEGIN; + +UPDATE biz.trigger_jobs +SET + job_name = 'ai_dws_prewarm_1000', + trigger_config = '{"cron_expression": "0 10 * * *"}'::jsonb, + description = 'App2 财务洞察每日预热：10:00 对所有门店触发 ai_dws_completed × 72 组合（8 时间 × 9 区域）' +WHERE job_type = 'ai_dws_prewarm'; + +COMMIT; diff --git a/db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql b/db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql new file mode 100644 index 0000000..d007eb2 --- /dev/null +++ b/db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql @@ -0,0 +1,117 @@ +-- 2026-05-01 +-- 业务运行上下文与沙箱隔离。 + +BEGIN; + +CREATE TABLE IF NOT EXISTS biz.site_runtime_context ( + site_id bigint PRIMARY KEY, + mode character varying(20) NOT NULL DEFAULT 'live', + sandbox_date date, + sandbox_instance_id character varying(64), + ai_mode character varying(20) NOT NULL DEFAULT 'live', + status character varying(20) NOT NULL DEFAULT 'active', + reason text, + updated_by bigint, + created_at timestamp with time zone DEFAULT now() NOT NULL, + updated_at timestamp with time zone DEFAULT now() NOT NULL, + CONSTRAINT site_runtime_context_site_id_fkey + FOREIGN KEY (site_id) REFERENCES biz.sites(site_id), + CONSTRAINT site_runtime_context_mode_check + CHECK (mode IN ('live', 'sandbox')), + CONSTRAINT site_runtime_context_ai_mode_check + CHECK (ai_mode IN ('live')), + CONSTRAINT site_runtime_context_sandbox_check + CHECK ( + (mode = 'live' AND sandbox_date IS NULL AND sandbox_instance_id IS NULL) + OR + (mode = 'sandbox' AND sandbox_date IS NOT NULL AND sandbox_instance_id IS NOT NULL) + ) +); + +COMMENT ON TABLE biz.site_runtime_context IS '门店业务运行上下文：live 使用真实日期，sandbox 使用指定业务日期并按实例隔离写入。'; +COMMENT ON COLUMN biz.site_runtime_context.mode IS '运行模式：live / sandbox。'; +COMMENT ON COLUMN biz.site_runtime_context.sandbox_date IS 'sandbox 模式下系统假设的业务日期。'; +COMMENT ON COLUMN biz.site_runtime_context.sandbox_instance_id IS 'sandbox 模式写入隔离实例 ID。'; +COMMENT ON COLUMN biz.site_runtime_context.ai_mode IS 'AI 调用模式；当前固定 live，沙箱也真实调用 DashScope。'; + +ALTER TABLE biz.coach_tasks + ADD COLUMN IF NOT EXISTS runtime_mode character varying(20) NOT NULL DEFAULT 'live', + ADD COLUMN IF NOT EXISTS sandbox_instance_id character varying(64) NOT NULL DEFAULT 'live'; + +ALTER TABLE biz.coach_task_transfer_log + ADD COLUMN IF NOT EXISTS runtime_mode character varying(20) NOT NULL DEFAULT 'live', + ADD COLUMN IF NOT EXISTS sandbox_instance_id character varying(64) NOT NULL DEFAULT 'live'; + +ALTER TABLE biz.recall_events + ADD COLUMN IF NOT EXISTS runtime_mode character varying(20) NOT NULL DEFAULT 'live', + ADD COLUMN IF NOT EXISTS sandbox_instance_id character varying(64) NOT NULL DEFAULT 'live'; + +ALTER TABLE biz.coach_task_history + ADD COLUMN IF NOT EXISTS runtime_mode character varying(20) NOT NULL DEFAULT 'live', + ADD COLUMN IF NOT EXISTS sandbox_instance_id character varying(64) NOT NULL DEFAULT 'live'; + +ALTER TABLE biz.ai_cache + ADD COLUMN IF NOT EXISTS runtime_mode character varying(20) NOT NULL DEFAULT 'live', + ADD COLUMN IF NOT EXISTS sandbox_instance_id character varying(64) NOT NULL DEFAULT 'live'; + +ALTER TABLE biz.ai_run_logs + ADD COLUMN IF NOT EXISTS runtime_mode character varying(20) NOT NULL DEFAULT 'live', + ADD COLUMN IF NOT EXISTS sandbox_instance_id character varying(64) NOT NULL DEFAULT 'live'; + +ALTER TABLE biz.ai_trigger_jobs + ADD COLUMN IF NOT EXISTS runtime_mode character varying(20) NOT NULL DEFAULT 'live', + ADD COLUMN IF NOT EXISTS sandbox_instance_id character varying(64) NOT NULL DEFAULT 'live'; + +UPDATE biz.coach_tasks SET runtime_mode = 'live', sandbox_instance_id = 'live' WHERE sandbox_instance_id IS NULL; +UPDATE biz.coach_task_transfer_log SET runtime_mode = 'live', sandbox_instance_id = 'live' WHERE sandbox_instance_id IS NULL; +UPDATE biz.recall_events SET runtime_mode = 'live', sandbox_instance_id = 'live' WHERE sandbox_instance_id IS NULL; +UPDATE biz.coach_task_history SET runtime_mode = 'live', sandbox_instance_id = 'live' WHERE sandbox_instance_id IS NULL; +UPDATE biz.ai_cache SET runtime_mode = 'live', sandbox_instance_id = 'live' WHERE sandbox_instance_id IS NULL; +UPDATE biz.ai_run_logs SET runtime_mode = 'live', sandbox_instance_id = 'live' WHERE sandbox_instance_id IS NULL; +UPDATE biz.ai_trigger_jobs SET runtime_mode = 'live', sandbox_instance_id = 'live' WHERE sandbox_instance_id IS NULL; + +DROP INDEX IF EXISTS biz.idx_coach_tasks_site_assistant_member_type; +CREATE UNIQUE INDEX IF NOT EXISTS idx_coach_tasks_runtime_unique_active + ON biz.coach_tasks (site_id, assistant_id, member_id, task_type, runtime_mode, sandbox_instance_id) + WHERE status = 'active'; + +DROP INDEX IF EXISTS biz.idx_recall_events_site_assistant_member_day; +CREATE UNIQUE INDEX IF NOT EXISTS idx_recall_events_runtime_site_assistant_member_day + ON biz.recall_events ( + site_id, + assistant_id, + member_id, + runtime_mode, + sandbox_instance_id, + (date_trunc('day', pay_time AT TIME ZONE 'Asia/Shanghai')) + ); + +CREATE INDEX IF NOT EXISTS idx_coach_tasks_runtime_assistant_status + ON biz.coach_tasks (site_id, runtime_mode, sandbox_instance_id, assistant_id, status); + +CREATE INDEX IF NOT EXISTS idx_ai_cache_runtime_lookup + ON biz.ai_cache (cache_type, site_id, runtime_mode, sandbox_instance_id, target_id, created_at DESC); + +CREATE INDEX IF NOT EXISTS idx_ai_trigger_jobs_runtime_site + ON biz.ai_trigger_jobs (site_id, runtime_mode, sandbox_instance_id, event_type, status); + +COMMIT; + +-- 回滚参考： +-- BEGIN; +-- DROP INDEX IF EXISTS biz.idx_ai_trigger_jobs_runtime_site; +-- DROP INDEX IF EXISTS biz.idx_ai_cache_runtime_lookup; +-- DROP INDEX IF EXISTS biz.idx_coach_tasks_runtime_assistant_status; +-- DROP INDEX IF EXISTS biz.idx_recall_events_runtime_site_assistant_member_day; +-- CREATE UNIQUE INDEX idx_recall_events_site_assistant_member_day ON biz.recall_events USING btree (site_id, assistant_id, member_id, (date_trunc('day', pay_time AT TIME ZONE 'Asia/Shanghai'))); +-- DROP INDEX IF EXISTS biz.idx_coach_tasks_runtime_unique_active; +-- CREATE UNIQUE INDEX idx_coach_tasks_site_assistant_member_type ON biz.coach_tasks USING btree (site_id, assistant_id, member_id, task_type) WHERE status = 'active'; +-- ALTER TABLE biz.ai_trigger_jobs DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +-- ALTER TABLE biz.ai_run_logs DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +-- ALTER TABLE biz.ai_cache DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +-- ALTER TABLE biz.coach_task_history DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +-- ALTER TABLE biz.recall_events DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +-- ALTER TABLE biz.coach_task_transfer_log DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +-- ALTER TABLE biz.coach_tasks DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +-- DROP TABLE IF EXISTS biz.site_runtime_context; +-- COMMIT; diff --git a/db/zqyy_app/schemas/biz.sql b/db/zqyy_app/schemas/biz.sql index a4b00e1..6b93cb3 100644 --- a/db/zqyy_app/schemas/biz.sql +++ b/db/zqyy_app/schemas/biz.sql @@ -1,6 +1,6 @@ -- ============================================================================= -- zqyy_app / biz（核心业务表（任务/备注/触发器）） --- 生成日期：2026-04-06 +-- 生成日期：2026-05-02 -- 来源：测试库（通过脚本自动导出） -- ============================================================================= @@ -16,11 +16,11 @@ CREATE SEQUENCE IF NOT EXISTS biz.cfg_task_generator_params_id_seq AS bigint; CREATE SEQUENCE IF NOT EXISTS biz.coach_task_history_id_seq AS bigint; CREATE SEQUENCE IF NOT EXISTS biz.coach_task_transfer_log_id_seq AS bigint; CREATE SEQUENCE IF NOT EXISTS biz.coach_tasks_id_seq AS bigint; -CREATE SEQUENCE IF NOT EXISTS biz.recall_events_id_seq AS bigint; CREATE SEQUENCE IF NOT EXISTS biz.connectors_id_seq AS integer; CREATE SEQUENCE IF NOT EXISTS biz.dws_assistant_task_monthly_id_seq AS bigint; CREATE SEQUENCE IF NOT EXISTS biz.excel_upload_log_id_seq AS bigint; CREATE SEQUENCE IF NOT EXISTS biz.notes_id_seq AS bigint; +CREATE SEQUENCE IF NOT EXISTS biz.recall_events_id_seq AS bigint; CREATE SEQUENCE IF NOT EXISTS biz.salary_adjustments_id_seq AS bigint; CREATE SEQUENCE IF NOT EXISTS biz.site_code_history_id_seq AS integer; CREATE SEQUENCE IF NOT EXISTS biz.sites_id_seq AS integer; @@ -41,7 +41,9 @@ CREATE TABLE biz.ai_cache ( triggered_by character varying(100), created_at timestamp with time zone DEFAULT now() NOT NULL, expires_at timestamp with time zone, - status character varying(20) DEFAULT 'valid'::character varying + status character varying(20) DEFAULT 'valid'::character varying, + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.ai_conversations ( @@ -86,7 +88,9 @@ CREATE TABLE biz.ai_run_logs ( session_id character varying(100), created_at timestamp with time zone DEFAULT now() NOT NULL, finished_at timestamp with time zone, - alert_status character varying(20) DEFAULT NULL::character varying + alert_status character varying(20) DEFAULT NULL::character varying, + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.ai_trigger_jobs ( @@ -102,7 +106,9 @@ CREATE TABLE biz.ai_trigger_jobs ( started_at timestamp with time zone, finished_at timestamp with time zone, error_message text, - created_at timestamp with time zone DEFAULT now() NOT NULL + created_at timestamp with time zone DEFAULT now() NOT NULL, + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.cfg_task_generator_params ( @@ -124,7 +130,9 @@ CREATE TABLE biz.coach_task_history ( old_task_type character varying(50), new_task_type character varying(50), detail jsonb, - created_at timestamp with time zone DEFAULT now() + created_at timestamp with time zone DEFAULT now(), + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.coach_task_transfer_log ( @@ -138,7 +146,9 @@ CREATE TABLE biz.coach_task_transfer_log ( transfer_reason text, guard_checks jsonb, transfer_score numeric, - created_at timestamp with time zone DEFAULT now() NOT NULL + created_at timestamp with time zone DEFAULT now() NOT NULL, + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.coach_tasks ( @@ -154,24 +164,15 @@ CREATE TABLE biz.coach_tasks ( abandon_reason text, completed_at timestamp with time zone, completed_task_type character varying(50), - completion_type character varying(10), parent_task_id bigint, created_at timestamp with time zone DEFAULT now(), updated_at timestamp with time zone DEFAULT now(), transfer_count integer DEFAULT 0 NOT NULL, transferred_from bigint, - transferred_at timestamp with time zone -); - -CREATE TABLE biz.recall_events ( - id bigint DEFAULT nextval('biz.recall_events_id_seq'::regclass) NOT NULL, - site_id bigint NOT NULL, - assistant_id bigint NOT NULL, - member_id bigint NOT NULL, - pay_time timestamp with time zone NOT NULL, - task_id bigint, - task_type character varying(50), - created_at timestamp with time zone DEFAULT now() + transferred_at timestamp with time zone, + completion_type character varying(10), + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.connectors ( @@ -232,6 +233,19 @@ CREATE TABLE biz.notes ( score smallint ); +CREATE TABLE biz.recall_events ( + id bigint DEFAULT nextval('biz.recall_events_id_seq'::regclass) NOT NULL, + site_id bigint NOT NULL, + assistant_id bigint NOT NULL, + member_id bigint NOT NULL, + pay_time timestamp with time zone NOT NULL, + task_id bigint, + task_type character varying(50), + created_at timestamp with time zone DEFAULT now(), + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL +); + CREATE TABLE biz.salary_adjustments ( id bigint DEFAULT nextval('biz.salary_adjustments_id_seq'::regclass) NOT NULL, site_id bigint NOT NULL, @@ -256,6 +270,19 @@ CREATE TABLE biz.site_code_history ( retired_at timestamp with time zone ); +CREATE TABLE biz.site_runtime_context ( + site_id bigint NOT NULL, + mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_date date, + sandbox_instance_id character varying(64), + ai_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + status character varying(20) DEFAULT 'active'::character varying NOT NULL, + reason text, + updated_by bigint, + created_at timestamp with time zone DEFAULT now() NOT NULL, + updated_at timestamp with time zone DEFAULT now() NOT NULL +); + CREATE TABLE biz.sites ( id integer DEFAULT nextval('biz.sites_id_seq'::regclass) NOT NULL, tenant_id integer NOT NULL, @@ -354,12 +381,14 @@ ALTER TABLE biz.dws_assistant_task_monthly ADD CONSTRAINT dws_assistant_task_mon ALTER TABLE biz.excel_upload_log ADD CONSTRAINT excel_upload_log_pkey PRIMARY KEY (id); ALTER TABLE biz.notes ADD CONSTRAINT notes_task_id_fkey FOREIGN KEY (task_id) REFERENCES biz.coach_tasks(id); ALTER TABLE biz.notes ADD CONSTRAINT notes_pkey PRIMARY KEY (id); -ALTER TABLE biz.recall_events ADD CONSTRAINT recall_events_pkey PRIMARY KEY (id); ALTER TABLE biz.recall_events ADD CONSTRAINT recall_events_task_id_fkey FOREIGN KEY (task_id) REFERENCES biz.coach_tasks(id); +ALTER TABLE biz.recall_events ADD CONSTRAINT recall_events_pkey PRIMARY KEY (id); ALTER TABLE biz.salary_adjustments ADD CONSTRAINT salary_adjustments_upload_batch_id_fkey FOREIGN KEY (upload_batch_id) REFERENCES biz.excel_upload_log(id); ALTER TABLE biz.salary_adjustments ADD CONSTRAINT salary_adjustments_pkey PRIMARY KEY (id); ALTER TABLE biz.site_code_history ADD CONSTRAINT site_code_history_pkey PRIMARY KEY (id); ALTER TABLE biz.site_code_history ADD CONSTRAINT site_code_history_site_code_key UNIQUE (site_code); +ALTER TABLE biz.site_runtime_context ADD CONSTRAINT site_runtime_context_site_id_fkey FOREIGN KEY (site_id) REFERENCES biz.sites(site_id); +ALTER TABLE biz.site_runtime_context ADD CONSTRAINT site_runtime_context_pkey PRIMARY KEY (site_id); ALTER TABLE biz.sites ADD CONSTRAINT sites_tenant_id_fkey FOREIGN KEY (tenant_id) REFERENCES biz.tenants(id); ALTER TABLE biz.sites ADD CONSTRAINT sites_pkey PRIMARY KEY (id); ALTER TABLE biz.sites ADD CONSTRAINT sites_site_code_key UNIQUE (site_code); @@ -379,6 +408,7 @@ ALTER TABLE biz.trigger_jobs ADD CONSTRAINT trigger_jobs_job_name_key UNIQUE (jo -- 索引 CREATE INDEX idx_ai_cache_cleanup ON biz.ai_cache USING btree (cache_type, site_id, target_id, created_at); CREATE INDEX idx_ai_cache_lookup ON biz.ai_cache USING btree (cache_type, site_id, target_id, created_at DESC); +CREATE INDEX idx_ai_cache_runtime_lookup ON biz.ai_cache USING btree (cache_type, site_id, runtime_mode, sandbox_instance_id, target_id, created_at DESC); CREATE INDEX idx_ai_conv_app_site ON biz.ai_conversations USING btree (app_id, site_id, created_at DESC); CREATE INDEX idx_ai_conv_context ON biz.ai_conversations USING btree (user_id, site_id, context_type, context_id, last_message_at DESC NULLS LAST) WHERE (context_type IS NOT NULL); CREATE INDEX idx_ai_conv_last_msg ON biz.ai_conversations USING btree (user_id, site_id, last_message_at DESC NULLS LAST); @@ -390,18 +420,20 @@ CREATE INDEX idx_ai_run_logs_created_brin ON biz.ai_run_logs USING brin (created CREATE INDEX idx_ai_run_logs_site_app ON biz.ai_run_logs USING btree (site_id, app_type); CREATE INDEX idx_ai_run_logs_status ON biz.ai_run_logs USING btree (status); CREATE INDEX idx_ai_trigger_jobs_dedup ON biz.ai_trigger_jobs USING btree (event_type, member_id, site_id, created_at) WHERE ((status)::text <> 'skipped_duplicate'::text); +CREATE INDEX idx_ai_trigger_jobs_runtime_site ON biz.ai_trigger_jobs USING btree (site_id, runtime_mode, sandbox_instance_id, event_type, status); CREATE INDEX idx_ai_trigger_jobs_site ON biz.ai_trigger_jobs USING btree (site_id, event_type); CREATE INDEX idx_ai_trigger_jobs_status ON biz.ai_trigger_jobs USING btree (status); CREATE INDEX idx_transfer_log_member ON biz.coach_task_transfer_log USING btree (member_id, created_at DESC); CREATE INDEX idx_transfer_log_site_created ON biz.coach_task_transfer_log USING btree (site_id, created_at DESC); CREATE INDEX idx_coach_tasks_assistant_status ON biz.coach_tasks USING btree (site_id, assistant_id, status); -CREATE UNIQUE INDEX idx_coach_tasks_site_assistant_member_type ON biz.coach_tasks USING btree (site_id, assistant_id, member_id, task_type) WHERE ((status)::text = 'active'::text); +CREATE INDEX idx_coach_tasks_runtime_assistant_status ON biz.coach_tasks USING btree (site_id, runtime_mode, sandbox_instance_id, assistant_id, status); +CREATE UNIQUE INDEX idx_coach_tasks_runtime_unique_active ON biz.coach_tasks USING btree (site_id, assistant_id, member_id, task_type, runtime_mode, sandbox_instance_id) WHERE ((status)::text = 'active'::text); CREATE INDEX idx_task_monthly_assistant ON biz.dws_assistant_task_monthly USING btree (assistant_id, stat_month DESC); CREATE INDEX idx_task_monthly_site_month ON biz.dws_assistant_task_monthly USING btree (site_id, stat_month DESC); CREATE INDEX idx_excel_log_site ON biz.excel_upload_log USING btree (site_id, created_at DESC); CREATE INDEX idx_notes_target ON biz.notes USING btree (site_id, target_type, target_id); -CREATE INDEX idx_salary_adj_assistant_month ON biz.salary_adjustments USING btree (assistant_id, salary_month); -CREATE UNIQUE INDEX idx_recall_events_site_assistant_member_day ON biz.recall_events USING btree (site_id, assistant_id, member_id, (date_trunc('day', pay_time AT TIME ZONE 'Asia/Shanghai'))); CREATE INDEX idx_recall_events_assistant_pay ON biz.recall_events USING btree (site_id, assistant_id, pay_time); +CREATE UNIQUE INDEX idx_recall_events_runtime_site_assistant_member_day ON biz.recall_events USING btree (site_id, assistant_id, member_id, runtime_mode, sandbox_instance_id, date_trunc('day'::text, (pay_time AT TIME ZONE 'Asia/Shanghai'::text))); +CREATE INDEX idx_salary_adj_assistant_month ON biz.salary_adjustments USING btree (assistant_id, salary_month); CREATE INDEX idx_salary_adj_site_month ON biz.salary_adjustments USING btree (site_id, salary_month); diff --git a/docs/ai/ai_apps_feature_acceptance_spec.md b/docs/ai/ai_apps_feature_acceptance_spec.md new file mode 100644 index 0000000..cdc280e --- /dev/null +++ b/docs/ai/ai_apps_feature_acceptance_spec.md @@ -0,0 +1,1039 @@ +# AI 应用 APP1-APP8 功能需求 - 目的检查文档 + +> 版本：2026-04-22 (v4，全景资料集成：8 维度并行调研 — 生产端 / DB schema / 合规 / MCP / admin-web / 后端路由服务 / 历史审计 / P2/P3 外围) +> 适用范围：`apps/backend/app/ai/` + `apps/admin-web/src/pages/AI*` + `apps/miniprogram/miniprogram/` + `apps/demo-miniprogram/miniprogram/`（UI 标杆） +> PRD 来源： +> +> - [docs/prd/AI需求2.md](../prd/AI需求2.md) — 8 个 AI 应用功能/参数/返回格式主表 +> - [docs/prd/ai-app-prompts.md](../prd/ai-app-prompts.md) — System Prompt 详细定义 +> - [docs/prd/Neo_Specs/NS2-ai-prompt-refinement.md](../prd/Neo_Specs/NS2-ai-prompt-refinement.md) — 数据层/拼接/page_context 文本化 +> - [docs/prd/specs/P5-miniapp-ai-integration.md](../prd/specs/P5-miniapp-ai-integration.md) — 小程序 AI 集成验收 +> - [docs/prd/specs/P14-ai-dashscope-migration.md](../prd/specs/P14-ai-dashscope-migration.md) — 熔断限流预算硬约束 +> - [docs/prd/specs/P15-ai-monitoring-testing.md](../prd/specs/P15-ai-monitoring-testing.md) — 监控后台与测试体系 + +--- + +## 0. 总体原则 + +- demo-miniprogram 是**样式标杆**（假数据驱动），生产 miniprogram 所有 AI 字段的排版/配色必须与 demo 一致。 +- 前端**不直接调用 DashScope**，所有 AI 产物统一通过 `ai_cache` 或 SSE 流式接口消费。 +- 后端统一响应包装 `{code:0, data:...}`，snake_case 自动转驼峰。 +- cache miss 时前端必须**清空陈旧数据**。 +- 告警统一走 WebSocket `/ws/ai-alerts/{site_id}`。 + +## 0.1 PRD 硬性数字约束（权威表） + +> 所有数字来自 `docs/prd/` 精读，代码实现与此不符时以 PRD 为准并回退排查。 + +| 维度 | 约束值 | PRD 来源 | +| ------ | -------- | --------- | +| 应用总数 | 8（APP1-APP8） | AI 需求 2 | +| 财务洞察组合 | 8 时间 × 9 区域 = 72 | AI 需求 2 | +| 线索分类（APP3） | 3 个枚举 | P5 / ai-app-prompts | +| 线索分类（APP6/8） | 6 个枚举 | P5 / ai-app-prompts | +| 单条线索 `summary` | ≤ 20 字（简短可作标题） | AI 需求 2 | +| 单条线索 `detail` | ≤ 120 字 | AI 需求 2 | +| APP7 `summary` 长度 | 200-400 字，开头定性短句 ≤ 25 字 | ai-app-prompts | +| APP8 `clues` 数组 | ≤ 5 条 | ai-app-prompts | +| APP5 `tactics` 数组 | 2-4 条，每条 `script` ≤ 150 字 | AI 需求 2 | +| APP6 `clues` 数组 | 0-10 条（按价值排序） | AI 需求 2 | +| APP3 `clues` 数组 | 1-5 条（按价值排序） | AI 需求 2 | +| System prompt 上限（APP2-8） | ≤ 8000 字 | NS2 | +| System prompt 上限（APP1） | ≤ 4000 字 | NS2 | +| page_context 上限 | ≤ 2000 字 | NS2 / page_context.py:21 | +| Token 日预算 | 100,000 | P14 | +| Token 月预算 | 2,000,000 | P14 | +| APP1 限流 | 每用户每分钟 10 次 | P14 | +| APP2-8 限流 | 每门店每小时 100 次 | P14 | +| 熔断阈值 | 连续 5 次失败 OPEN | P14 | +| 熔断恢复窗口 | 60 秒 | P14 | +| 关系流失预警 | 停止消费 > 14 天 | ai-app-prompts | +| 高粘性阈值 | 月内消费 ≥ 3 次 | ai-app-prompts | +| 学习型阈值 | 助教费占比 > 40% | ai-app-prompts | +| 当期 < 7 天 | 必须降权表述（"初步观察"/"不足为据"） | ai-app-prompts | +| 财务洞察加载 | < 2 秒（秒级缓存读取） | P5 | +| 对话复用窗口（customer/coach/finance） | 3 天 | P5 | +| 对话复用窗口（task） | 无时限 | P5 | +| 对话复用（general） | 始终新建 | P5 | + +## 0.2 跨 APP 编排链路（PRD 定义） + +### 消费事件链（严格串行） + +``` +新结算单 → APP3 [await] + → APP8 [await] + → APP7 [await]（读 APP8 最新缓存） + 如含助教： + → APP4 [await]（读 APP8 最新缓存） + → APP5 +``` + +**约束**：APP7 与 APP4 均依赖 APP8 完成，确保上游线索就绪。 + +### 备注事件链 + +``` +备注提交 → APP6 [await] → APP8 [await] +``` + +### 任务分配链 + +``` +任务分配（priority_recall / high_priority_recall） + → APP4 [await]（读 APP8 已有缓存，miss 时 prompt 标注"暂无历史线索"） + → APP5 +``` + +**约束**：任务链不等 APP8 执行，直接读缓存；消费链则必须等 APP8 完成才能执行 APP4/APP7。 + +--- + +## 1. APP1 聊天（流式对话 + 屏幕上下文） + +### 功能目的（PRD） + +店员/助教在小程序里与 AI 自由对话（"这个客户最近消费变多了为什么"），支持 10 种页面入口带上下文，后端将上下文结构化为 ≤2000 字中文文本注入 prompt。**PRD 参考**：AI 需求 2 表首行 / P5 AC1 / NS2 page_context 设计。 + +### 后端请求 schema（[schemas.py:16-23](../../apps/backend/app/ai/schemas.py#L16)） +``` +ChatStreamRequest { + message: str # 用户本轮输入 + source_page: str | None # 来源页面标识（10 种枚举） + page_context: dict | None # 看板筛选参数（timeDimension/areaFilter/dimension/typeFilter/projectFilter） + screen_content: str | None # 「屏幕可见内容」快照（前端采集，后端原样拼入 prompt）← 当前 gap +} +``` + +### 10 种 sourcePage（[page_context.py:24-36](../../apps/backend/app/ai/data_fetchers/page_context.py#L24)） +`task-detail / customer-detail / coach-detail / board-finance / board-customer / board-coach / performance / my-profile / task-list / customer-service-records` + +### 前端消费链路 +| 阶段 | 文件与行号 | 处理 | +|------|-----------|------| +| 浮按钮属性 | [ai-float-button.ts:29-40](../../apps/miniprogram/miniprogram/components/ai-float-button/ai-float-button.ts#L29) | 接收 `sourcePage` + `pageFilters`（JSON 对象） | +| 浮按钮跳转 | [ai-float-button.ts:44-72](../../apps/miniprogram/miniprogram/components/ai-float-button/ai-float-button.ts#L44) | URL 编码 JSON 到 querystring | +| Chat 解析 | [chat.ts:234-259](../../apps/miniprogram/miniprogram/pages/chat/chat.ts#L234) | `JSON.parse(decodeURIComponent(options.pageFilters))` ; 回退支持旧单键 `timeDimension/areaFilter/dimension/typeFilter/projectFilter` | +| SSE 发送 | [chat.ts:487-490](../../apps/miniprogram/miniprogram/pages/chat/chat.ts#L487) | body: `{chatId, content, sourcePage, pageContext}` | +| 后端文本化 | [page_context.py:39-96](../../apps/backend/app/ai/data_fetchers/page_context.py#L39) | `build_page_text(source_page, context_id, site_id, filters)` → 结构化中文 ≤2000 字 | +| 后端注入 | xcx_chat.py | 将文本拼入 DashScope `biz_params` 或作为前置 system message | + +### screen_content「屏幕可见内容」特性（**待实现 / 文档化 gap**） +- schema 已预留字段（[schemas.py:22](../../apps/backend/app/ai/schemas.py#L22)） +- **预期采集方式**（需前端实现）：浮按钮 onTap 时通过 `triggerEvent` 让父页面回传 `this.data` 中可见区块的快照（如 board-finance 当前展示的 `overview/recharge/revenue/...` 卡片数据），序列化为短 JSON 字符串 +- **后端消费**：原样拼入 prompt 系统消息（与 `page_context` 互补：page_context 是后端查 DB 的结果；screen_content 是前端用户真实看到的数字） +- **验证**：两者都存在时，提示词顺序应为 `screen_content（用户视角） → page_context（权威数据）`，避免矛盾时以 page_context 为准 + +### 各 sourcePage 携带字段示例 +| sourcePage | pageFilters 字段 | 后端 page_context 输出要点 | +|-----------|-----------------|--------------------------| +| board-finance | `timeDimension` + `areaFilter` | 汇总笔数 / 总营收 / 笔均 / 优惠率 / 储值活跃度 | +| board-customer | `dimension` + `typeFilter` | Top 10 客户 + 排序维度 + 客群分类 | +| board-coach | `dimension` + `projectFilter` + `timeDimension` | Top 10 助教 + 服务统计 + 技能筛选 | +| performance / task-list / my-profile | `timeDimension` | 个人绩效 / 任务列表 / 本人统计 | +| task-detail / customer-detail / coach-detail | 无 filters，走 `contextId` | 单实体详情 | +| customer-service-records | 无 | 服务记录流水 | + +### Demo 参考（UI 形态） +- [chat.ts](../../apps/demo-miniprogram/miniprogram/pages/chat/chat.ts)：消息气泡、引用卡片 `referenceCard`、逐字追加动效 +- 进入路径：浮按钮仅在 board-*（看板类）与详情页挂载，距底部 200rpx（TabBar 页）/ 120rpx（非 TabBar） + +### 验证点（细化） +- [ ] 财务看板任意 time/area 切换 → 点浮按钮 → 后端日志可见 `build_page_text("board-finance", ...)` 返回文本含当前切换维度的数字 +- [ ] 小程序 SSE body 中 `pageContext` 为 JSON 对象而非字符串（后端解析不失败） +- [ ] `pageFilters` 为空对象时不追加 URL 参数，走 general 对话 +- [ ] SSE ArrayBuffer 跨 chunk 的 UTF-8 中文字符无乱码（构造「当前营业」被 2 chunk 切分的测试） +- [ ] `done` 事件 `conversation_id` 返回后，下一轮发送透传该 id 保持多轮 +- [ ] `ai_run_logs.tokens_used` 按 `usage.models` 嵌套结构累加（非顶层 tokens） +- [ ] 网络中断重试上限 2 次（2/4/8s 指数退避） +- [ ] **screen_content gap 待确认**：若本次上线计划启用，需在浮按钮 onTap 内实现页面快照 triggerEvent；否则保留 schema 占位并在文档注明"暂不采集" + +--- + +## 2. APP2 财务洞察（72 组合预热） + +### 功能目的 +日结完成后预生成 **8 时间维度 × 9 区域 = 72 组** 财务洞察，命中看板时直接从 `ai_cache` 秒级读取。 + +### 返回 schema（[schemas.py:93-104](../../apps/backend/app/ai/schemas.py#L93)） +``` +App2Result { insights: [ { seq: int, title: str, body: str } ] } +``` + +### System Prompt 核心规则（[ai_system_prompt_by_app.md:41-93](ai_system_prompt_by_app.md#L41)） +- 收入构成三口径不可互换：发生额 / 成交收入 / 现金流入 +- 5 类优惠拆解必须落到细分（团购/会员折扣/手动/赠送卡/分摊） +- 警戒线：优惠率 >30% / 助教薪酬占比 >40% / 充值占现金流入 25-40% 为健康 +- **seq=11/12 固定为板块 F「综合健康度」，置顶作为"本期总结"** +- 当期 <7 天需降权表述 +- 现金流出为 0 视为录入异常并高亮 + +### target_id 拼装（[dispatcher.py _app2_target_id](../../apps/backend/app/ai/dispatcher.py)） +`${TIME_MAP[selectedTime]}__${selectedArea}`，例：`this_month__hallA` / `last_quarter__all` + +**TIME_MAP**：`month→this_month`、`lastMonth→last_month`、`week→this_week`、`quarter→this_quarter`、`half6→last_6_months` +**9 区域**：`all / hall / hallA / hallB / hallC / vip / snooker / mahjong / ktv` + +### cache_type 切分（2026-04-23） +- `area='all'` 的 8 组 → `app2_finance` +- `area!='all'` 的 64 组 → `app2a_finance_area` + +### Demo 展示形态（**关键 UI 规范**） +参考 [board-finance.wxml:208-221](../../apps/demo-miniprogram/miniprogram/pages/board-finance/board-finance.wxml#L208)： + +``` +┌─ AI 智能洞察（机器人 SVG 图标 + 标题） +│ 优惠率Top：团购(5.2%) / 大客户(3.1%) / 赠送卡(2.5%) +│ 差异最大：酒水(+18%) / 台桌(-5%) / 包厢(+12%) +│ 建议关注：充值高但消耗低，会员活跃度需提升 +└─ +``` + +**字段到 UI 映射**： +| 字段 | Demo 类 | 渲染规范 | +|------|---------|---------| +| `title` | `.ai-insight-dim` | 灰色引导词（如"优惠率Top："/"差异最大："），结尾带中文冒号 | +| `body` | `.ai-insight-line` 主体 | 白色正文，含数字与百分比 | +| 强调片段 | `.ai-insight-underline` | 关键词下划线（需 AI 用 `**...**` 标记，前端轻量 Markdown 渲染） | +| 顺序 | seq 升序 | `seq=11/12` 置顶为"本期总结" | +| 图标 | `/assets/icons/ai-robot.svg` | **必须 SVG，禁止 emoji 替代**（demo 已标注 CHANGE 2026-03-12） | + +### 验证点（细化） +- [ ] 72 组 `target_id` 全覆盖（SQL：`SELECT DISTINCT target_id FROM biz.ai_cache WHERE cache_type IN ('app2_finance','app2a_finance_area') AND site_id=? AND created_at::date=CURRENT_DATE` 应 = 72） +- [ ] `seq=11/12` 在前端必定置顶（不按数字大小升序，需特判） +- [ ] `title` 结尾是中文冒号`：`（便于 dim 样式识别） +- [ ] `body` 中 `**xxx**` 标记被轻量 Markdown 渲染为 underline/加粗 +- [ ] area 切换后旧 `aiInsights/aiInsightSummary/aiInsightDetails` 立即清空 +- [ ] cache miss 时显示占位文案（"正在生成洞察，请稍后"），不复用上次数据 +- [ ] 现金流出为 0 时 AI 输出能**明确指出录入异常**（单元测试固化该场景） +- [ ] 当期 <7 天的时间维度（本周 `this_week` 若当前周三）返回文本含降权用词（"初步观察"/"不足为据"等） +- [ ] Prompt `KEY_TRANSLATIONS`（[app2_finance_prompt.py:24-64](../../apps/backend/app/ai/prompts/app2_finance_prompt.py#L24)）无缺字段 +- [ ] 熔断/限流后剩余组跳过，`ai_cache.result_json` 不写 NULL + +--- + +## 3. APP3 维客线索（消费端，3 分类） + +### 功能目的 +消费结算后从 DWS 消费记录提取 **3 类线索**（客户基础/消费习惯/玩法偏好），`providers` 固定「系统」。 + +### 返回 schema（[schemas.py:71-78, 107-110](../../apps/backend/app/ai/schemas.py#L71)） +``` +App3Result { clues: [ ClueItem { category, summary, detail, emoji } ] } +``` + +### System Prompt 核心规则（[ai_system_prompt_by_app.md:97-125](ai_system_prompt_by_app.md#L97)） +- `category` 严格 3 选 1（`App3CategoryEnum`） +- 必须输出"下一步做什么"的行动导向，不得仅描述现象 +- 消费结构解读：酒水 >40% = 休闲社交客；台费 >80% = 硬核客；助教费 >30% = 学习进阶客 + +### 前端消费（经 App8 合并后落 `member_retention_clue`） +App3 结果**不直接渲染**，由 App8 读 ai_cache 整合 → 写库 → 前端查客户详情时显示。 + +### Demo 展示形态（customer-detail） +参考 [customer-detail.ts:99-145](../../apps/demo-miniprogram/miniprogram/pages/customer-detail/customer-detail.ts#L99) + [customer-detail.wxml:92-110](../../apps/demo-miniprogram/miniprogram/pages/customer-detail/customer-detail.wxml#L92)： + +``` +维客线索 [AI 徽章] +┌─ [客户/基础] 🎂 生日 3月15日 · VIP会员 · 注册2年 By:系统 +├─ [消费/习惯] 🌙 常来夜场 · 月均4-5次 By:系统 +├─ [消费/习惯] 💰 高客单价 By:系统 +│ 近60天场均消费 ¥420，高于门店均值 ¥180；... +└─ ... +``` + +**字段到 UI 映射**： +| schema 字段 | Demo `clue-card` 属性 | UI 规范 | +|------------|---------------------|--------| +| `category` | `tag` | 两行显示（如"客户\n基础"），配色 `categoryColor` 按类映射（primary/success/purple/warning/pink/error） | +| `summary` | `title`（含 emoji 前缀） | 主文案，短句 30 字内 | +| `emoji` | 拼在 `title` 开头 | 1 个 emoji，类别相关 | +| `detail` | `content`（展开区） | 50-100 字展开，可折叠 | +| `providers`（App8 合并后补） | `source`（"By:系统"/"By:小燕"） | 区分系统推断 vs 备注来源 | + +### 验证点（细化） +- [ ] `category ∈ {客户基础, 消费习惯, 玩法偏好}`（Pydantic 校验 + 前端 `categoryColor` 映射无 undefined） +- [ ] `emoji` 字段必填且为单个 emoji（正则 `/^[\p{Emoji}]+$/u`） +- [ ] `summary` 以行动导向动词结尾（"可推..."/"建议..."/"需..."），非纯描述（单测） +- [ ] `detail` 长度 ≥ 50 字且 ≤ 150 字 +- [ ] DWS 取数失败时降级到 `_default_member_data`，不导致 dispatcher 崩溃 +- [x] Prompt 超 4000 字后仍保留完整消费明细；2026-05-01 合成 100 条完整明细真实调用成功返回 +- [ ] 团购客（无储值卡）与储值会员识别正确（AI 不得混淆） + +--- + +## 4. APP4 关系分析（任务链首） + +### 功能目的 +助教参与消费 / 任务分配时，分析助教-会员关系，产出任务描述、行动建议、一句话总结。 + +### 返回 schema（[schemas.py:113-118](../../apps/backend/app/ai/schemas.py#L113)） +``` +App4Result { + task_description: str # 任务详述 + action_suggestions: [str] # 行动建议数组 + one_line_summary: str # 一句话总结 +} +``` + +### System Prompt 核心规则（[ai_system_prompt_by_app.md:129-156](ai_system_prompt_by_app.md#L129)） +- 输出必含：**关系评级**（紧密/一般/疏远）+ 核心原因 + 风险/机会点 +- 粘性阈值：月内 ≥3 次 = 高粘性；激励课占比 >40% = 学习型 +- 停止消费 >14 天 = 流失预警 + +### Demo 展示形态（task-detail 顶部 Banner） +参考 [task-detail.ts:107-112](../../apps/demo-miniprogram/miniprogram/pages/task-detail/task-detail.ts#L107)： + +``` +关系等级：很好 heartScore=8.5 +banner 背景根据 taskType 动态切换 SVG +``` + +**字段到 UI 映射**： +| schema 字段 | Demo 字段 | 位置 | +|------------|----------|------| +| `one_line_summary` | Banner 下方副标题 | 任务详情头部一行显示 | +| `task_description` | `detail.taskTypeLabel` + 主内容 | 任务卡片主体 | +| `action_suggestions[]` | 勾选式建议列表 | 可勾选动作项，完成后记录 | + +### 验证点（细化） +- [ ] `action_suggestions` 为非空 list，每条 ≤ 40 字 +- [ ] `one_line_summary` 含关系评级词（"紧密/一般/疏远"）+ 数字 +- [ ] `target_id = ${assistant_id}_${member_id}`，供 App5 复用 +- [ ] 助教数据缺失时 `warnings` 数组被填充，前端显示降级提示 +- [ ] Prompt 截断 `_MAX_PROMPT_LEN=8000` 保留关键关联字段 + +--- + +## 5. APP5 话术参考（任务链尾） + +### 功能目的 +基于 App4 的 `one_line_summary` 与关系评级，生成针对性**微信/当面沟通话术**。 + +### 返回 schema（[schemas.py:121-131](../../apps/backend/app/ai/schemas.py#L121)） +``` +App5Result { tactics: [ { scenario: str, script: str } ] } +``` + +### System Prompt 核心规则（[ai_system_prompt_by_app.md:160-192](ai_system_prompt_by_app.md#L160)） +- 微信私信：口语、短、配 1 个 emoji，不群发感 +- 当面沟通：引导式提问 > 直接推销 +- 会员分层：新客试听 / 成长储值 / 核心赛事邀请 / 流失限时券 +- 助教不能：打任意折扣 / 承诺 KOL 免费陪打 +- 输出需标注：适用场景 + 建议发送时段 + 预期反应 + +### Demo 展示形态（task-detail 话术区） +参考 [task-detail.ts:79-86](../../apps/demo-miniprogram/miniprogram/pages/task-detail/task-detail.ts#L79)： + +``` +话术参考 +┌─ 王哥您好，好久不见！最近店里新到了几张国际标准斯诺克球桌... [复制] +├─ 王哥，最近忙吗？这周末我们有个老客户专属球友交流赛... [复制] +└─ ... 共 5 条 +``` + +**字段到 UI 映射**： +| schema 字段 | Demo `talkingPoints` | 规范 | +|------------|---------------------|------| +| `scenario` | 折叠区 hint（"适用：流失预警"/"适用：储值召回"） | 小字副标题，可选展示 | +| `script` | 话术主体 | 长按可复制，配置 `copiedIndex` 高亮反馈 | + +### 验证点（细化） +- [ ] `tactics` 长度 3-5 条（Prompt 约束） +- [ ] `script` 含会员姓名或称呼（如"王哥"），非模板化空话 +- [ ] `script` 含 0-1 个 emoji（`emoji_count <= 1`） +- [ ] 不出现"8折/免费/KOL/抽成"等越权用词（黑词正则拦截） +- [ ] App4 失败时 App5 跳过（串行依赖，`context.app4_result is None` 不执行） +- [ ] 长按复制触发 `wx.setClipboardData` 成功 +- [ ] `target_id` 与 App4 一致（`${assistant_id}_${member_id}`） + +--- + +## 6. APP6 备注分析（备注链首） + +### 功能目的 +助教提交备注后打分 1-10 并提取 **6 类线索**；`providers` = 备注提交人真实姓名。 + +### 返回 schema（[schemas.py:134-138](../../apps/backend/app/ai/schemas.py#L134)） +``` +App6Result { + score: int (ge=1, le=10) + clues: [ ClueItem { category, summary, detail, emoji } ] +} +``` + +### System Prompt 核心规则（[ai_system_prompt_by_app.md:196-220](ai_system_prompt_by_app.md#L196)） +- **忠于备注原文，不延伸推测** +- 8 维度归一到 6 分类（App6CategoryEnum） +- 一条备注可对应多个维度 +- 情感倾向（正面/中性/负面）影响后续助教触达开场白 +- 标注备注是谁写的、何时写的（时效性） + +### 前端消费 +App6 结果**不直接渲染**，经 App8 整合后写入 `member_retention_clue` 表，前端查客户详情展示（`source` 字段显示"By:小燕"）。 + +### Demo 展示形态（**客户详情「维客线索」中显示 6 类**） +参考 [customer-detail.ts:99-145](../../apps/demo-miniprogram/miniprogram/pages/customer-detail/customer-detail.ts#L99) 7 条 clue 分布： +- 客户基础 × 1（生日/VIP） +- 消费习惯 × 2（夜场/高客单） +- 玩法偏好 × 1（中式斯诺克） +- 促销偏好 × 1（酒水套餐敏感） +- 社交关系 × 1（固定球搭子） +- 重要反馈 × 1（斯诺克走位需求） + +### 验证点（细化） +- [ ] `score ∈ [1,10]` 严格校验（Pydantic `ge=1, le=10`） +- [ ] `category ∈ {客户基础, 消费习惯, 玩法偏好, 促销偏好, 社交关系, 重要反馈}` +- [ ] `providers` 为备注提交人姓名（非"系统"、非空） +- [ ] 备注原文中的专有名词（"李哥"、"阿杰"、"A12号台"）保留在 `detail` 中 +- [ ] 备注 >8000 字时截断但保留情感词与动作词 +- [ ] score 写入 `ai_cache.score` 列（非 `result_json.score`，供后端排序） + +--- + +## 7. APP7 客户分析（消费链尾，客户画像） + +### 功能目的 +消费链 App8 完成后串行触发，综合消费 + 备注 + 助教关系输出 **200-400 字客户画像**。 + +### 返回 schema（[schemas.py:141-152](../../apps/backend/app/ai/schemas.py#L141)） +``` +App7Result { + strategies: [ { title: str, content: str } ] + summary: str # 画像主文 +} +``` + +### System Prompt 核心规则（[ai_system_prompt_by_app.md:224-257](ai_system_prompt_by_app.md#L224)） +- **开头一句话定性**（"工作日晚间的上班族硬核玩家"） +- 中段数字：消费结构、频次、客单、助教绑定 +- 结尾助教可动 1-2 条建议 +- 避免评判语言（"消费低"改为"客单 60 元偏低于店均 120 元"） +- **必须标注数据时间窗**（"近 30 天 / 近 90 天"） +- 备注信息需带【来源：人名，请甄别真实性】标注（[app7_customer_prompt.py:64-77](../../apps/backend/app/ai/prompts/app7_customer_prompt.py#L64)） + +### Demo 展示形态（customer-detail 头部） +参考 [customer-detail.ts:91-98](../../apps/demo-miniprogram/miniprogram/pages/customer-detail/customer-detail.ts#L91) + [customer-detail.wxml:69-90](../../apps/demo-miniprogram/miniprogram/pages/customer-detail/customer-detail.wxml#L69)： + +``` +🤖 AI 智能洞察 +┌─ summary：高价值 VIP 客户，月均到店 4-5 次，偏好夜场中式台球， +│ 近期对斯诺克产生兴趣。社交属性强... +│ 当前推荐策略 +│ ■ [green] 最后到店距今 12 天，超出理想间隔 7 天，建议... +│ ■ [amber] 客户提到想练斯诺克走位，可推荐专项课程包... +│ ■ [pink] 社交属性强，可邀请参加球友赛事活动... +└─ +``` + +**字段到 UI 映射**： +| schema 字段 | Demo 字段 | UI 规范 | +|------------|----------|--------| +| `summary` | `aiInsight.summary` | 开头白色正文段 | +| `strategies[].title` | 策略颜色 `color` 枚举前缀 | 不直接渲染（配色由前端枚举轮转：green/amber/pink/...） | +| `strategies[].content` | `strategy-text` | 策略卡片主体，每条独立配色条 | +| 末条样式 | `.strategy-item-last` | 最后一条无下边距 | + +**注意**：demo 中 `strategies[].color` 是前端枚举色（green/amber/pink），AI 返回的 `title` 字段应映射为 emoji/关键词而非颜色。实际代码中前端按 index % 6 循环配色（不依赖 AI）。 + +### 验证点（细化） +- [ ] `summary` 开头为"定性短句"（句号前 ≤ 25 字） +- [ ] `summary` 包含时间窗关键词（"近 30 天"/"近 90 天"/"近 60 天"） +- [ ] `summary` 长度 200-400 字 +- [ ] `strategies` 长度 2-3 条，前端展示最多 2 条（demo 规范 `index < length - 1` 为非末，`index === length - 1` 为末条） +- [ ] 评判性词（"差"/"低"/"糟糕"）出现时应改写为对比表述（AI 侧或后处理） +- [ ] 备注来源标注【来源：xxx，请甄别真实性】进入 prompt +- [ ] 消费链中断时 App7 跳过（App8 未完成不执行） +- [ ] cache_type = `app7_customer_analysis`，target_id = `member_id` + +--- + +## 8. APP8 线索整合（写库幂等） + +### 功能目的 +整合 App3 + App6 全部线索 → 去重、统一 6 分类、`providers` 逗号拼接 → **幂等写 `member_retention_clue` 表**。 + +### 返回 schema（[schemas.py:80-88, 155-158](../../apps/backend/app/ai/schemas.py#L80)） +``` +App8Result { + clues: [ ConsolidatedClueItem { + category: str # 6 选 1 + summary: str # 30 字内行动导向 + detail: str # 50-100 字展开 + emoji: str # 分类对应 emoji + providers: str # "消费数据" / "店员小燕备注" / 逗号拼接多源 + } ] +} +``` + +### System Prompt 核心规则（[ai_system_prompt_by_app.md:261-290](ai_system_prompt_by_app.md#L261)） +- 冲突处理：**备注原文 > 行为推断** +- `summary` 禁放数字（数字放 `detail`） +- 线索排序：可直接动作 > 身体偏好 > 长期画像 +- 不超过 5 条（助教可读性） +- 不输出泛化建议（"请关心会员"禁止） + +### 落库规则（[dispatcher.py _write_retention_clue](../../apps/backend/app/ai/dispatcher.py)） +```sql +BEGIN; + DELETE FROM app.member_retention_clue + WHERE site_id=:site AND member_id=:member AND source IN ('ai_consumption','ai_note'); + INSERT INTO app.member_retention_clue (...) VALUES (...); +COMMIT; +``` +- source 取值：消费链触发 → `ai_consumption`；备注链触发 → `ai_note` +- `source='manual'`（人工线索）**绝不**删除 + +### Demo 展示形态（7 条线索在客户详情，见 App3 表格） + +### 验证点（细化） +- [ ] `DELETE` + `INSERT` 在同一事务内（pg_stat_activity 查询验证） +- [ ] 写入后 `source='manual'` 行数不变（跨事务前后 count 一致） +- [ ] 同日多次消费 / 多条备注不会让线索重复累积（幂等） +- [ ] `providers` 多源拼接去重（如"消费数据、备注-小燕"，不出现"消费数据、消费数据"） +- [ ] `summary` 不含数字（正则 `/[0-9%¥]/` 不匹配） +- [ ] `detail` 含数字（与 summary 分工） +- [ ] `clues` 数组长度 ≤ 5 +- [ ] 排序：可直接动作类（"推课"/"约时段"）在前 +- [ ] App3 或 App6 任一失败时，App8 仍执行但对应 `_clues=[]` +- [ ] cache_type = `app8_clue_consolidated` + +--- + +## 9. 管理后台通用检查 + +### AIDashboard（总览） +- [AIDashboard.tsx:120](../../apps/admin-web/src/pages/AIDashboard.tsx#L120) `getDashboard()` +- 字段：`today_calls` / `today_success_rate` / `today_tokens` / `today_avg_latency_ms` / `trend_7d` +- [ ] 数值与 `biz.ai_run_logs` 聚合一致 +- [ ] `trend_7d` 折线图日期连续无跳点，单位 ms / % / 次 +- [ ] 切换 site_id 过滤器后数字按租户隔离 + +### AIOperations（手动执行） +- [AIOperations.tsx:67](../../apps/admin-web/src/pages/AIOperations.tsx#L67) `runApp(appType, {site_id, member_id})` 支持 App3-App8（App1/App2 不适用） +- [AIOperations.tsx:146](../../apps/admin-web/src/pages/AIOperations.tsx#L146) `triggerEvent({event_type, site_id, member_id, is_forced})` 越过去重 +- [ ] `is_forced=true` 可绕过当日去重，`ai_trigger_jobs` 新增一行 +- [ ] 返回 `job_id`，tag 色 `processing → success/failed` +- [ ] WebSocket `/ws/ai-alerts/{site_id}` 接收 `circuit_open / rate_limited / budget_exceeded / timeout / failed` + +### TriggerManager（调度配置） +- [TriggerManager.tsx:183](../../apps/admin-web/src/pages/TriggerManager.tsx#L183) `updateTriggerConfig(id, {cron_expression, interval_seconds})` +- [ ] cron 表达式校验通过才允许保存 +- [ ] 改动后调度器热加载（Scheduler lifespan 监听 meta.scheduled_tasks） + +--- + +## 10. 跨切面共性验证 + +| 维度 | 检查项 | 验证方法 | +|------|--------|---------| +| RunLog | 状态转换 `pending→running→success\|failed\|timeout\|circuit_open\|rate_limited\|budget_exceeded` | `SELECT status, COUNT(*) FROM biz.ai_run_logs GROUP BY status` 覆盖 8 种 | +| RunLog | `success` 必有非零 `tokens_used` | `SELECT COUNT(*) FROM biz.ai_run_logs WHERE status='success' AND tokens_used=0` = 0 | +| RunLog | `request_prompt` ≤ 8000 字符 | `SELECT MAX(length(request_prompt))` ≤ 8000 | +| 熔断 | 连续失败 N 次后 OPEN | 人工注入失败 → 第 N+1 次日志 `status=circuit_open` 且**无真实 DashScope 调用** | +| 限流 | 分钟/日双维度 | 压测超限后 `rate_limited` 数突增，`tokens_used IS NULL` | +| 预算 | 不足时记 `budget_exceeded:` | 人为把日预算调至 0 → 下一次调用日志为 `budget_exceeded:daily_budget_used_up` | +| 缓存 | `result_json IS NULL` 行数应为 0 | `SELECT COUNT(*) FROM biz.ai_cache WHERE result_json IS NULL` = 0 | +| 缓存 | `cache_type` 枚举齐全 | `SELECT DISTINCT cache_type` 仅含 `CacheTypeEnum` 的 8 个值 | +| 去重 | 同 `(event_type, member_id, site_id, date)` 当天仅 1 次 | `SELECT event_type, member_id, COUNT(*)` 当 `is_forced=false` 时均为 1 | +| 多租户 | `SET LOCAL app.current_site_id` | tcpdump / SQL trace 首条 SQL 为 SET LOCAL | +| 告警推送 | WebSocket 接收 5 类 `alert_type` | 前端 devtools Network → WS 抓包校验 | +| 前端降级 | cache miss 清空旧数据 | 切换 area → DevTools Inspect `aiInsights` 短暂为 [] | +| 前端降级 | SSE 断流重试 | chrome network throttle offline → 看 retry 2/4/8s | +| Demo 对齐 | 字段 → UI 映射一致 | 并排截图 miniprogram vs demo-miniprogram 像素对齐 | + +--- + +## 11. 自测清单（按角色） + +### 前端工程师 +**客户详情页** +- [ ] App7 `summary` 开头为定性短句且含时间窗 +- [ ] App7 strategies 末条 CSS 类 `.strategy-item-last` 生效（无下边距） +- [ ] App3/6/8 合并后 clues 配色按 `categoryColor` 映射无 undefined +- [ ] clue-card `source` 字段区分 "By:系统" vs "By:{人名}" +- [ ] 展开折叠 `detail` 动画无抖动 + +**任务详情页** +- [ ] App4 `one_line_summary` 在 banner 副标题 +- [ ] App5 `tactics[].script` 长按复制成功 + toast 反馈 +- [ ] `action_suggestions` 勾选持久化到本地 + +**财务看板** +- [ ] 9 区域 × 5 时间 = 45 种组合切换，AI 洞察正确加载或清空 +- [ ] `title` 以冒号结尾、`.ai-insight-dim` 灰色样式生效 +- [ ] `**xxx**` 渲染为 underline +- [ ] seq=11/12 置顶"本期总结" +- [ ] 图标为 SVG（`/assets/icons/ai-robot.svg`），非 emoji + +**聊天页** +- [ ] 浮按钮从 6 类页面进入都正确带 `sourcePage` + `pageFilters` +- [ ] SSE 中文无乱码 +- [ ] `done` 事件替换临时消息 ID +- [ ] 历史会话 / 客户 3 天内复用 / 任务复用 / 看板新建 四种入口均工作 +- [ ] 重试 2/4/8s 指数退避 +- [ ] （**待确认**）若实现 `screen_content`，浮按钮 triggerEvent 采集页面快照 + +### 后端工程师 +- [ ] `ai_run_logs` 状态分布覆盖 8 种 +- [ ] `ai_cache` 无 NULL `result_json` +- [ ] `member_retention_clue` `source='manual'` 跨天数量稳定 +- [ ] 日结后 2 分钟内 72 组缓存写入完整 +- [ ] `SET LOCAL app.current_site_id` 每次查询都执行 +- [ ] Pydantic schema 对 score/enum/长度的约束不被绕过 + +### 测试工程师 +- [ ] demo-miniprogram 与 miniprogram 的客户详情 / 任务详情 / 财务看板像素级对齐 +- [ ] customer-detail 页 AI 区块三部分互不干扰（summary / strategies / clues） +- [ ] 小程序热启动后 AI 洞察不闪烁旧数据 +- [ ] admin-web Dashboard 与数据库聚合一致性 + +--- + +## 附录 A：已废弃 / 已迁移 + +- `apps/backend/app/ai/apps/app1_chat.py` ~ `app8_consolidation.py` 已删除，逻辑统一内聚至 [dispatcher.py](../../apps/backend/app/ai/dispatcher.py) +- APP2 于 2026-04-23 拆分为 `app2_finance` (8 组) + `app2a_finance_area` (64 组) + +## 附录 B：已知 Gap / 待办（PRD 对齐清单） + +> 来源：`docs/prd/` 精读对照当前代码与本 spec 的差异。 + +| ID | Gap | PRD 来源 | 当前状态 | 建议 | +| -- | --- | -------- | -------- | ---- | +| G1 | APP1 `screen_content` 采集（浮按钮 onTap triggerEvent 采集页面快照） | AI 需求 2 / NS2 | schema 已预留 [schemas.py:22](../../apps/backend/app/ai/schemas.py#L22) 但 [chat.ts:487](../../apps/miniprogram/miniprogram/pages/chat/chat.ts#L487) 未传 | 浮按钮 `triggerEvent('snapshot')` → 父页返回 setData 可见子集 → URL/SSE body 透传；后端按 "screen_content → page_context" 顺序拼 prompt | +| G2 | APP2 72 组预热完整性校验 | P14 调度器 | 代码已拆 8+64 组，缺自动化核对 | 日结后 T+10min 执行 `SELECT DISTINCT target_id FROM biz.ai_cache WHERE cache_type IN ('app2_finance','app2a_finance_area') AND site_id=? AND created_at::date=CURRENT_DATE`，应 = 72；不足告警 | +| G3 | APP3 `summary` 行动导向动词约束 | ai-app-prompts | prompt 未强化动词要求 | prompt 增加"必须以可推/建议/需/可约/可邀 等动词结尾"；后端 schema 加正则；单测固化 | +| G4 | APP4 `target_id` 拼装规则文档化 | P5 | 代码实现 `{assistant_id}_{member_id}` 但文档未固定分隔符 | 正式文档化分隔符为单下划线，拦截 assistant_id/member_id 含下划线的场景 | +| G5 | APP5 `scenario` 前端消费规范 | AI 需求 2 | schema 定义但 UI 未约定 | 约定 task-detail 话术区 `scenario` 作为折叠 hint（"适用：流失预警"），空字符串时不展示 | +| G6 | APP6 `score` 驱动前端 UI | ai-app-prompts | 后端已写 `ai_cache.score` 列但前端未消费 | 备注列表按 score 降序排列；score ≥ 8 高亮、≤ 3 置灰 | +| G7 | APP7 `strategies[].title` 字段用途 | ai-app-prompts | 前端按 index 循环配色，未用 title | 方案 A：删除 title；方案 B：AI 输出 title 作为徽章（"机会"/"风险"/"日常"），前端展示 | +| G8 | APP8 相似线索去重判断标准 | AI 需求 2 / P5 | prompt 未定义相似度阈值 | prompt 增加"若两条线索 summary 字符重合 ≥ 60% 或 category 相同且描述同一行为，合并为一条，providers 拼接去重" | +| G9 | 熔断/限流/预算硬约束压测 | P14 | 代码实现但无压测报告 | 压测：APP1 单用户 11 次/分钟应触发 rate_limited；连续 5 次失败后第 6 次 status=circuit_open 且不真实调用；日 token 达 100k 后 status=budget_exceeded | +| G10 | 日结触发 APP2 预热延迟 | P14 | 代码"日结后轮询"无明确延迟 | 文档固定 "日结完成事件 → T+5min 开始调度 APP2 × 72 组，T+15min 应全部完成"；超时告警 | +| G11 | RLS 多租户隔离强制验证 | P5 / backend CLAUDE.md | 代码每次查询前 SET LOCAL，缺自动验证 | 集成测试：伪造 site_id=A 的 JWT 访问 member_id 属于 site_id=B 的数据应返回 404；抓 pg_stat_statements 验证 SET LOCAL 存在 | +| G12 | 新客（无消费/无备注）降级文案 | NS2 | 代码有 `_default_member_data` 降级但 prompt 文案未标准化 | 定义模板：「该客户暂无历史线索，以下基于本次消费进行初步判断」，dispatcher 注入 prompt 开头 | +| G13 | APP8 `providers` 多源拼接格式 | ai-app-prompts | 代码拼接但分隔符未固定 | 固定格式：`"消费数据,备注-{人名}"`，中文逗号分隔，备注人不重复（用 set 去重） | +| G14 | APP4 任务链 cache miss 时的 prompt 提示 | ai-app-prompts | 代码读缓存失败时传空 | prompt 标注"暂无 APP8 历史线索，请基于基线数据分析"，而非丢空字符串 | +| G15 | APP2 `**xxx**` 强调标记约定 | Demo 规范 | 前端已做轻量 Markdown，但 prompt 未要求 AI 输出该标记 | prompt 增加"对关键结论或异常词用 `**粗体**` 包裹，前端会渲染为下划线强调" | + +## 附录 D：PRD 硬性阈值对照表（验收单） + +> 单独抽出所有数字阈值，供 QA 断言时直接引用。 + +| APP | 字段/指标 | 阈值 | 不达标处理 | +| --- | --------- | ---- | ---------- | +| APP1 | 单轮 prompt | ≤ 4000 字 | 触发截断保留最近 N 轮 | +| APP1 | page_context | ≤ 2000 字 | page_context.py 末尾附"…（上下文已截断）" | +| APP1 | 限流 | 10 次/分钟/用户 | `rate_limited` 记录，前端提示"操作过快" | +| APP1 | 复用窗口 | customer/coach/finance 3 天；task 无限；general 新建 | 超窗口新建会话 | +| APP2 | 组合数 | 72（8×9） | 缺组合告警 | +| APP2 | 加载时延 | < 2 秒 | 前端 loading > 2s 上报监控 | +| APP2 | seq 范围 | 1-12，11/12 置顶 | 非 11/12 按 seq 升序 | +| APP3 | clues 条数 | 1-5 | AI 超 5 截断 | +| APP3 | summary 长度 | ≤ 20 字 | 后端校验拦截 | +| APP3 | detail 长度 | ≤ 120 字 | 后端校验拦截 | +| APP4 | action_suggestions | 1-4 条，每条 ≤ 100 字 | 单测固化 | +| APP4 | one_line_summary | ≤ 30 字，必含关系评级词 | 正则检查 `(紧密\|一般\|疏远)` | +| APP5 | tactics 条数 | 2-4 | AI 超 4 截断 | +| APP5 | script 长度 | ≤ 150 字 | 后端校验 | +| APP5 | 黑词 | 禁用 8折/免费/KOL/抽成/内部价 | 后端正则黑名单拦截 | +| APP6 | score 范围 | 1-10（6=标准，<6 扣分，>6 加分） | Pydantic `ge=1, le=10` | +| APP6 | clues 条数 | 0-10 | 无下限，上限截断 | +| APP7 | summary 长度 | 200-400 字 | 后端校验 | +| APP7 | summary 开头定性 | ≤ 25 字 + 句号 | 正则 `^.{1,25}[。！]` | +| APP7 | strategies 条数 | 2-5 | 前端仅展示 2 条 | +| APP7 | 时间窗标注 | 必含 "近 30 天/近 60 天/近 90 天" | 关键词检查 | +| APP8 | clues 条数 | ≤ 5 | AI 超 5 截断 | +| APP8 | summary 禁数字 | 正则 `[0-9%¥]` 不匹配 | 后处理剥离 | +| APP8 | providers 拼接 | 中文逗号去重 | 后端 set 处理 | +| 通用 | Token 日预算 | 100,000 | 超限 status=budget_exceeded | +| 通用 | Token 月预算 | 2,000,000 | 超限告警 + 阻断 | +| 通用 | 熔断阈值 | 连续 5 次失败 OPEN | 60 秒恢复窗口 | +| 通用 | APP2-8 限流 | 100 次/小时/门店 | rate_limited 跳过 | +| 通用 | 关系流失预警 | 停消费 > 14 天 | APP4/7 标注 | +| 通用 | 高粘性阈值 | 月内 ≥ 3 次 | APP4 判定 | +| 通用 | 学习型阈值 | 助教费占比 > 40% | APP3/4/7 判定 | +| 通用 | 当期 < 7 天 | 必须降权用词 | APP2 prompt 约束 | + +## 附录 C：Demo 关键路径索引 + +| 页面 | AI 字段 | 文件 | +| ---- | ------- | ---- | +| 客户详情 | `aiInsight.summary/strategies` + `clues[]` | [customer-detail.ts:90-145](../../apps/demo-miniprogram/miniprogram/pages/customer-detail/customer-detail.ts#L90) | +| 任务详情 | `retentionClues[]` + `talkingPoints[]` | [task-detail.ts:67-86](../../apps/demo-miniprogram/miniprogram/pages/task-detail/task-detail.ts#L67) | +| 财务看板 | `ai-insight-section` 三段式 | [board-finance.wxml:208-221](../../apps/demo-miniprogram/miniprogram/pages/board-finance/board-finance.wxml#L208) | +| 助教/客户看板 | `aiColorClass`（随机配色） | [board-finance.ts:294](../../apps/demo-miniprogram/miniprogram/pages/board-finance/board-finance.ts#L294) | + +--- + +## 附录 E：生产端 vs Demo 端对照实况（2026-04-22 快照） + +### E.1 生产端真实消费路径 + +| 页面 | AI 字段来源 | 关键实现 | 与 demo 差异 | +| ---- | ----------- | -------- | ------------ | +| customer-detail | `fetchAICache('app7_customer_analysis', memberId)` 单独拉取；`retentionClues` 从主详情接口返回 | [customer-detail.ts:7](../../apps/miniprogram/miniprogram/pages/customer-detail/customer-detail.ts#L7) onLoad → loadDetail → `_loadAIInsight()` 异步加载；`aiInsight.strategies` 前端按 index 循环 6 色 | demo 是硬编码 mock；生产 strategies `color` 由前端计算 | +| task-detail | `aiAnalysis.summary / suggestions / talkingPoints` + `retentionClues` **都随主详情接口一次返回**，无独立 AI 缓存调用 | `onCopySpeech()` → `wx.setClipboardData()` + 2s toast [task-detail.ts:268](../../apps/miniprogram/miniprogram/pages/task-detail/task-detail.ts#L268)；备注创建后 4s 间隔轮询 5 次拿 `aiScore`（20s 超时） | demo 同样内联 mock；生产端**没有长按复制**，仅单击复制按钮 | +| board-finance | `fetchAICache(cacheType, targetId)` + `parseMarkdownInline` 解析 `**粗** / *斜* / ***粗斜***` | [board-finance.ts:532](../../apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts#L532) cache_type 切分已实装；seq 11/12 置顶（精确匹配 + 末两条 fallback）；切换 time/area 时 `aiInsights=[]` 主动清空 | demo 内联 mock，无 TIME_MAP/AREA 枚举 | +| 浮按钮 | task-detail 当前**未挂载**；customer-detail 仅传 `customerId`；board-finance 仅传 `bottom=200` | `sourcePage` / `pageFilters` **虽支持但尚未启用**（属性存在、传参为空） | demo 无浮按钮 | + +### E.2 关键实务差异 + +- **task-detail 无 AI 缓存调用**：`aiAnalysis` 是 `fetchTaskDetail()` 主响应的一部分，后端在返回任务详情时已聚合读取 App4/App5 缓存。这意味着**任务列表分页**与 **AI 结果拉取**合并为一次请求，减少 round-trip。 +- **fetchAICache silent fail**：[services/api.ts:417](../../apps/miniprogram/miniprogram/services/api.ts#L417) 错误时返回 `null`，页面降级显示"暂无洞察数据"；此静默失败需监控上报补强。 +- **百分比双重格式化**：board-finance 把后端小数率（0.052）× 100 传 WXS 格式化，demo 端硬编码字符串，两端一致性依赖后端契约稳定。 +- **setData 路径优化**：`'aiInsight.summary'` 字符串路径而非整对象解构，减少小程序差量渲染。 + +--- + +## 附录 F：AI 数据库 schema 权威清单 + +### F.1 五张核心表 DDL 速览 + +权威 DDL：[db/zqyy_app/schemas/biz.sql](../../db/zqyy_app/schemas/biz.sql) 与 [public.sql](../../db/zqyy_app/schemas/public.sql)。 + +| 表 | 关键字段 | 索引要点 | RLS | +| -- | -------- | -------- | --- | +| `biz.ai_run_logs` | `status` varchar(20)（pending/running/success/failed/timeout/circuit_open/rate_limited/budget_exceeded），`alert_status`，`session_id` varchar(100)，`tokens_used` int default 0，`latency_ms` int，`request_prompt` text（≤ 8000 字符写入） | 部分索引 `idx_ai_run_logs_alert` WHERE status IN (failed, timeout, circuit_open)；BRIN `(created_at)` | **未启用** | +| `biz.ai_cache` | `cache_type` varchar(30) + CHECK 约束 8 枚举，`target_id` varchar(100)，`result_json` jsonb NOT NULL，`score` int（**无 CHECK 约束**） | `idx_ai_cache_lookup (cache_type, site_id, target_id, created_at DESC)` | **未启用** | +| `biz.ai_trigger_jobs` | `event_type` varchar(30)，`is_forced` bool，`app_chain` varchar(100)，`payload` jsonb | 部分索引 `idx_ai_trigger_jobs_dedup` WHERE status ≠ 'skipped_duplicate' | **未启用** | +| `biz.ai_conversations` / `biz.ai_messages` | `context_type` varchar(20)，`context_id` varchar(50)，`session_id` varchar(100)，`reference_card` jsonb | 部分索引 `idx_ai_conv_context` WHERE context_type IS NOT NULL | **未启用** | +| `public.member_retention_clue` | `category` varchar(20) + CHECK 枚举 6 值，`summary` varchar(200)，`detail` text，`recorded_by_name` varchar(50)，`source` varchar(20) DEFAULT 'manual'，`is_hidden` bool | `idx_retention_clue_member`、`idx_retention_clue_category` | **未启用**，通过 FDW 反向映射 `fdw_app.member_retention_clue` | + +### F.2 DDL vs Pydantic 对齐问题（按风险） + +| 级别 | 项目 | 症状 | +| ---- | ---- | ---- | +| **CRITICAL** | `ai_cache.score` 无 CHECK 约束 | Pydantic `App6Result.score: int = Field(ge=1, le=10)` 仅应用层校验；脏数据（0/-1/100）可静默落库 | +| **HIGH** | `member_retention_clue` **没有 `emoji` 和 `providers` 列** | [dispatcher.py:513-588](../../apps/backend/app/ai/dispatcher.py#L513) `_write_retention_clue` 折叠：`emoji + " " + summary` → `summary`；`providers` → `recorded_by_name` varchar(50)。**providers 多源拼接大概率超过 50 字符被 PG 报错或截断** | +| **HIGH** | `summary varchar(200)` 拼接 emoji 后有效长度降低 | AI 输出接近 200 字符时合并报错 | +| **MEDIUM** | `cache_type` CHECK 与 `CacheTypeEnum` 双侧维护 | 新增 App 需同时改 DDL + Pydantic，遗漏即违反 CHECK | +| **MEDIUM** | `ai_run_logs` 无 `job_id` 列关联 `ai_trigger_jobs` | 只能通过 `session_id` 间接关联，无 FK 保护 | +| **LOW** | FDW 外部表 `fdw_app.member_retention_clue` 缺 `source` 和 `is_hidden` 列 | ETL 端无法按 source 过滤 AI 写入的线索 | + +### F.3 建议补充的索引/约束 + +1. `biz.ai_cache.score` 添加 `CHECK (score IS NULL OR (score >= 1 AND score <= 10))` +2. `public.member_retention_clue` 新建 `(member_id, site_id, source)` 索引（APP8 DELETE 现在全扫） +3. `biz.ai_conversations` 新建 `session_id` 单列索引 +4. **全部 AI 表启用 RLS**（当前完全依赖应用层 `site_id` 过滤，无最后防线） + +--- + +## 附录 G：合规审计红黄清单（2026-04-22） + +> 来源：security-reviewer 全量扫描 apps/backend/app/ai/ 所有 prompt 拼装路径。 + +### G.1 已通过的面 + +- ✅ `member_phone / phone / mobile / id_card / wechat_openid / wechat_unionid` **零出现**于所有 prompt 与 data_fetcher +- ✅ `bank_account / bank_card / home_address / ip_address / device_id` 全部未出现 +- ✅ DashScope SDK 走 HTTPS 加密传输 +- ✅ page_context 前端透传被 handler 白名单拦截（handler 只 `.get()` 已知字段） + +### G.2 5 个风险点（按优先级） + +| ID | 文件 | 风险 | 建议修复 | +| -- | ---- | ---- | -------- | +| R1 | [member_data.py:200](../../apps/backend/app/ai/data_fetchers/member_data.py#L200) | 助教 `da.real_name` 作为 nickname fallback 传 AI | 确认是否属员工隐私；若是改为空串或工号 | +| R2 | [member_data.py:249-262](../../apps/backend/app/ai/data_fetchers/member_data.py#L249) | 储值卡**精确余额**直接进 prompt | 范围化：改为"高/中/低/清零"标签 | +| R3 | [member_data.py:276](../../apps/backend/app/ai/data_fetchers/member_data.py#L276) | `card_balance_total` / `stored_value_balance_total` 精确值 | 同 R2 | +| R4 | [member_data.py:358-398](../../apps/backend/app/ai/data_fetchers/member_data.py#L358) | `notes.content` 备注原文无正则脱敏 | 预过滤手机号 `1[3-9]\d{9}` → `1****`、银行卡号、身份证号 | +| R5 | [run_log_service.py:57](../../apps/backend/app/ai/run_log_service.py#L57) | 含 R2/R3/R4 的 prompt 写入 `ai_run_logs.request_prompt` 落库 | 先做字段级脱敏再入库；或 ai_run_logs 加严格 RLS 仅开发读 | + +### G.3 合规测试清单（CI） + +- [ ] 单测：`build_prompt_*` 返回值断言无 11 位连续数字（手机号） +- [ ] 单测：`notes.content` 含手机号的样例，prompt 中已掩码 +- [ ] CI：`grep -r "member_phone\|wechat_openid\|id_card" apps/backend/app/ai/` 无命中 +- [ ] 集成测试：构造含手机号的备注，验证 APP6 prompt 中号码不完整出现 + +--- + +## 附录 H：MCP Server 与 dispatcher 关系 + +### H.1 现状 + +| 面向 | dispatcher 路径 | MCP Server 路径 | +| ---- | --------------- | --------------- | +| 调用者 | Admin Web / 后端事件 | **目前仅 Claude Code 开发环境**；百炼 AI 应用规划中（未接入） | +| 连接库 | etl_feiqiu（只读）+ zqyy_app（读写） | 仅 etl_feiqiu 只读 | +| RLS | 每次查询前 `SET LOCAL app.current_site_id` | **无 site_id 隔离**（P5.1 规划中） | +| 鉴权 | JWT | Bearer Token（可选，`MCP_TOKEN` 为空则无鉴权） | +| 工具 | 8 个 APP handler | 4 个通用工具：`list_tables` / `describe_table` / `describe_schemas` / `query_sql`（只读+正则黑名单+500 行上限） | + +### H.2 关键边界 + +- **8 个 AI 应用目前均走 dispatcher 直查 DB，不经过 MCP** +- MCP 扩展（P5.1 批次 B）规划：加 zqyy_app 连接 + auth/biz/public 自动 schema 路由 + 敏感字段脱敏（wx_openid/phone） +- MCP 扩展（P5.1 批次 C）规划：完整查库手册上传百炼知识库 + +### H.3 生产部署 + +- 外部入口：`https://mcp.langlangzhuoqiu.cn/mcp`（未来） +- 本地配置：`.mcp.json` 的 `pg-etl` / `pg-app` 禁用，`pg-etl-test` / `pg-app-test` 启用 + +--- + +## 附录 I：admin-web AI 三页面实况 + +### I.1 AIDashboard.tsx（顶部卡片 + 趋势 + 告警） + +- 数据源 [AIDashboard.tsx:99](../../apps/admin-web/src/pages/AIDashboard.tsx#L99)：`getDashboard()` → `DashboardResponse` +- 字段：`today_calls / today_success_rate / today_tokens / today_avg_latency_ms / trend_7d[] / app_distribution[] / budget{} / recent_alerts[] / app_health[]` +- 时间范围：`range_days` (1/3/7/10) 或 `date_from/date_to` 自定义 [AIDashboard.tsx:112](../../apps/admin-web/src/pages/AIDashboard.tsx#L112) +- WebSocket：`ws(s)://[host]/ws/ai-alerts/{site_id}`，单次连接 **无重连** [AIDashboard.tsx:135-168](../../apps/admin-web/src/pages/AIDashboard.tsx#L135) +- 告警消息格式：`{ type: "alert_created", payload: AlertItem }` +- 实时告警最多保留 20 条，合并至表格顶部 + +### I.2 AIOperations.tsx（四卡片手动执行） + +四个 Card 区： + +1. **Card 1 手动重跑**：`retryTriggerJob(id)` → `trigger_job_id` +2. **Card 2 缓存失效**：`invalidateCache({ site_id, app_type?, member_id? })` → `affected_count`；site_id 必填 +3. **Card 2.5 按需执行**：`runApp(appType, params)` 支持 APP3-APP8 +4. **Card 2.6 触发事件链**：`triggerEvent({ event_type, ..., is_forced=true })` — event_type ∈ `{consumption, note_created, task_assigned, dws_completed}` +5. **Card 3 批量执行**：`createBatchRun()` → 估算 → `confirmBatchRun(batch_id)` 异步启动；batch_id **内存 TTL 600 秒** [admin_service.py:26](../../apps/backend/app/services/ai/admin_service.py#L26) +6. **Card 4 告警管理**：`ackAlert(id)` / `ignoreAlert(id)`，分页 10 + +### I.3 TriggerManager.tsx（4 Tab + URL 驱动） + +- Tab：`all / biz / ai / etl`，`?tab=xxx` URL 查询参数持久化 +- Biz Tab 编辑 Modal：`cron_expression` + `interval_seconds`（min=1），保存后热加载 +- AI Tab 组件堆栈：`AITriggers` + `AIOperations` + `AITriggerJobs` + +### I.4 **严重不一致：app6 命名错位** + +- 前端 `adminAI.ts` 定义 `app6_note_analysis` +- 后端 `admin_ai.py` 的 `_SUPPORTED_APP_TYPES` 为 `app6_note` +- 手动执行 APP6 **会 400**，需修正命名统一（推荐采用后端名 `app6_note`） + +### I.5 权限模型 + +- 所有 Admin AI 端点 `_require_admin()` 依赖 [admin_ai.py:70-111](../../apps/backend/app/routers/admin_ai.py#L70) +- 角色：`{site_admin, tenant_admin, super_admin}` 任一 +- `admin_users.is_active` 实时查询（禁用账户秒级生效） + +--- + +## 附录 J：后端完整端点与链路矩阵 + +### J.1 路由端点清单（共 21 个 AI 相关） + +**admin_ai.py（13 个，需 admin 权限）** + +- `GET /api/admin/ai/dashboard` / `trigger-jobs` / `trigger-jobs/{id}` / `run-logs` / `run-logs/{id}` / `budget` / `alerts` +- `POST /api/admin/ai/trigger-jobs/{id}/retry` / `cache/invalidate` / `batch-run` / `batch-run/confirm` / `alerts/{id}/ack` / `alerts/{id}/ignore` + +**xcx_chat.py（5 个，需 approved 用户）** + +- `GET /api/xcx/chat/history` / `{chat_id}/messages` / `messages?contextType=&contextId=` +- `POST /api/xcx/chat/stream`（SSE）/ `{chat_id}/messages` + +**内部事件总线** + +- `POST /api/internal/ai/trigger` — [internal_ai.py](../../apps/backend/app/routers/internal_ai.py)，Internal-Token 认证 +- `POST /api/internal/etl-completed` — [internal_events.py:56](../../apps/backend/app/routers/internal_events.py#L56)，触发 recall → task → `fire_event("ai_dws_completed")` +- `POST /api/admin/task-engine/pending-review/{id}/reassign` — [admin_task_engine.py:255](../../apps/backend/app/routers/admin_task_engine.py#L255)，触发 `fire_event("ai_task_assigned")` + +### J.2 事件 → 链路映射 + +[dispatcher.py:169-174](../../apps/backend/app/ai/dispatcher.py#L169) `_EVENT_CHAIN_MAP`： + +| 事件 | 链路 | +| ---- | ---- | +| `consumption` | APP3 → APP8 → APP7（+ APP4 → APP5 若 `has_assistant`） | +| `note_created` | APP6 → APP8 | +| `task_assigned` | APP4 → APP5 | +| `dws_completed` | APP2 × 8（area='all'） + APP2A × 64（area!='all'） | + +### J.3 服务层职责矩阵 + +| 服务 | 职责 | dispatcher 调用 | 写表 | +| ---- | ---- | ---------------- | ---- | +| ChatService | 对话持久化 | **直调 DashScopeClient**（不走 dispatcher） | ai_conversations / ai_messages | +| AdminAIService | 监控聚合 | 无，仅查询 | 无（只读） | +| NoteService | 备注创建 | `dispatcher._handle_note()` | notes / ai_cache | +| TaskGenerator | 每日 07:00 生成任务 | `trigger_scheduler` 异步 | coach_tasks / ai_cache | +| TriggerScheduler | cron/event 调度 | `fire_event()` | trigger_jobs 更新 | +| AIDispatcher | 链路编排+熔断/限流/预算 | `_run_step()` × N | ai_cache / ai_run_logs | + +### J.4 超时与并发 + +- 单步 `_STEP_TIMEOUT = 180s`（2026-04-21 从 120s 上调）[dispatcher.py:57](../../apps/backend/app/ai/dispatcher.py#L57) +- APP2 DWS 全链路 = 180s × 72 组 + 600s 余量 ≈ **2.5 小时**（同步执行可能阻塞其他触发器，需监控） +- 普通链 超时 10min + +### J.5 关键技术债 + +- **事件去重内存 set**：服务重启后当日相同事件可重复触发 → 需迁移到 DB 查询 `ai_trigger_jobs` +- **ChatService 不走 dispatcher**：链路独立，不享受熔断/限流/预算保护（APP1 限流单独实现） +- **旧 openai_client 残留**：DashScope 迁移后未见清理 + +--- + +## 附录 K：Demo 10 页 AI 区块映射（标杆参考） + +### K.1 浮按钮挂载清单 + +**已挂载**（8 页）：board-coach / board-customer / chat-history / notes / performance / task-list / customer-service-records / my-profile / board-finance / customer-detail +**未挂载**：chat / task-detail / coach-detail / apply / login / reviewing / dev-tools / no-permission + +### K.2 AI 配色规范 + +- 6 色方案：`red / orange / yellow / blue / indigo / purple` +- 实装：[ai-color-manager.ts:74-127](../../apps/demo-miniprogram/miniprogram/utils/ai-color-manager.ts#L74) +- task-list 采用 `random` 模式每日刷新 +- 其他页面按页面标识映射固定色 + +### K.3 辅助组件 + +- `ai-title-badge`：标题旁 AI 徽章 +- `ai-inline-icon`：列表内嵌 AI 图标 +- `clue-card`：线索卡片（含 `tag/emoji/title/source/content` 字段 + 展开折叠） + +### K.4 `pageFilters` 前端字段缺失 + +扫描发现前端页面**未定义 pageFilters 对象结构**，当前仅浮按钮属性声明；实际采集需在 P0 G1 gap 补充。 + +--- + +## 附录 L：ETL → AI 数据源约束 + +### L.1 金额口径铁律 + +- **禁用 `consume_money`**（[member_data.py:1-6](../../apps/backend/app/ai/data_fetchers/member_data.py#L1) 文件头明文禁止） +- 统一拆分为：`table_charge_money + assistant_pd_money + assistant_cx_money + goods_money` +- 所有 prompt 拼装遵守此口径（APP2/3/4/6/7 prompt 已核对） + +### L.2 FDW 视图与 RLS + +- 所有 `fdw_etl.*` 已迁移至 `app.v_*` RLS 视图 +- FDW 查询超时硬上限 5 秒 [member_data.py:69-79](../../apps/backend/app/ai/data_fetchers/member_data.py#L69) +- 超时降级到 `_default_member_data()`（AI 输入降级，分析质量下降） + +### L.3 DWS 视图清单 + +- 20+ 汇总表，6 大主题（助教业绩/薪酬/财务日报/会员分析/订单/库存） +- 金额字段 `NUMERIC(12,2)`，货币 CNY +- **空值策略未文档化**：NULL vs 0 策略缺，prompt 数字解读存歧义 + +### L.4 消费记录完整明细风险 + +- 2026-05-01 起 App3 不再按 4000 字硬截断消费记录，优先保留完整明细，避免丢失大客户高频消费模式 +- 已用合成 100 条完整消费明细真实调用 App3，prompt 约 25791 字，64.30s 返回成功，低于 180s 单步超时 +- 剩余风险：真实门店极端会员、缓存 reference 膨胀或百炼侧临时抖动仍可能拉高耗时，需通过 `ai_run_logs.elapsed_ms` 持续观察 + +--- + +## 附录 M：部署与超参 + +### M.1 DashScope APP_ID 清单（根 [.env:118-134](../../.env#L118)） + +``` +DASHSCOPE_APP_ID_1_CHAT +DASHSCOPE_APP_ID_2_FINANCE (area='all' × 8 时间维度) +DASHSCOPE_APP_ID_2A_FINANCE_AREA (area!='all' × 64 组合，2026-04-23 新增) +DASHSCOPE_APP_ID_3_CLUE +DASHSCOPE_APP_ID_4_ANALYSIS +DASHSCOPE_APP_ID_5_TACTICS +DASHSCOPE_APP_ID_6_NOTE +DASHSCOPE_APP_ID_7_CUSTOMER +DASHSCOPE_APP_ID_8_CONSOLIDATE +``` + +### M.2 超参硬编码 + +- 模型版本、温度、max_tokens 在 [config.py:14-48](../../apps/backend/app/ai/config.py#L14) 内硬编码 +- 无 dev/test/prod 环境差异文件（仅一份 .env） +- `INTERNAL_API_TOKEN` 与 DashScope API Key 同存根 .env（已 gitignore） +- `BACKEND_API_URL=http://localhost:8000` 部署到各环境需手工改 + +### M.3 建议 + +- 提取 `.env.example` + `.env.dev` + `.env.prod` 多环境模板 +- 超参挪到 `config.py` 的 `@dataclass` 并可被 `.env` 覆盖 +- 加 APP2 DWS 并发窗口监控（2.5h 耗时风险） + +--- + +## 附录 N：历史审计时间轴（2026-02 ~ 2026-04） + +### N.1 关键演进节点 + +| 日期 | 主题 | 涉及 APP | +| ---- | ---- | -------- | +| 2026-04-23 | [app2a_finance_area_integrated](../../docs/audit/changes/2026-04-23__app2a_finance_area_integrated.md) — 72 组合拆为 app2_finance (8) + app2a_finance_area (64) + `member_order_count` 列 + area_code NULL bug 修复 | APP2 | +| 2026-04-22 | [app2_prompt_v5_1_and_miniprogram_ai_insight](../../docs/audit/changes/2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md) — V5.1 采纳（A/B 40 次调用，92.3 分）+ 按星期聚合门槛 14 天 + 月中场景保护 + seq11/12 置顶 | APP2 | +| 2026-04-21 | [admin-web-ai-management-suite](../../docs/audit/changes/2026-04-21__admin-web-ai-management-suite.md) — AIPrewarm / AITriggers / AIOperations 增强 + 4 个后端端点 | 管理 | +| 2026-04-20 | [ai-module-complete](../../docs/audit/changes/2026-04-20__ai-module-complete.md) — Phase 0-4 贯通 + 删除 8 个死代码 app 文件 + 修复 main.py 未调用 set_dispatcher 导致 503 | 全局 | +| 2026-03-20 | [rns1-ai-autonomous-decision-risk-audit](../../docs/audit/changes/2026-03-20__rns1-ai-autonomous-decision-risk-audit.md) — 76 session / 34 风险 / "AI 信任文档胜过信任 DB" 核心问题 | 全局 | +| 2026-03-10 | [multi-module-ai-apps-task-defense](../../docs/audit/changes/2026-03-10__multi-module-ai-apps-task-defense-miniprogram.md) — 8 个 AI 应用骨架 + 任务防卡死 + 小程序页面迁移 | 全局 | +| 2026-02-26 | [retention-clue-refactor](../../docs/audit/changes/2026-02-26__retention-clue-refactor.md) — 新表 `ai_trigger_jobs` 去重 + `member_retention_clue` 字段调整 | APP8 | + +### N.2 从历史踩坑抽取的验证规则 + +| 历史踩坑 | 应有验证 | +| -------- | -------- | +| **FDW Schema 脱节**（列名/视图名虚构） | 生成/改 prompt 前必须 MCP 执行 `information_schema.columns` + `SELECT * LIMIT 5` 验证 | +| **月中场景误读**（3 月初把月中 22 天当整月对比） | payload 含"对比口径"字段（当期/对比期天数）；按星期门槛 14 天；样本<5 天降权表述 | +| **Prompt 版本漂移** | 版本号固定写入 `docs/ai/`；frontend enum / backend schema 同步校验 | +| **app_type 枚举错配** | 新增 APP 时同时更新 `CacheTypeEnum` / DDL CHECK / `_SUPPORTED_APP_TYPES` / adminAI.ts | +| **DWS area_code=NULL bug** | ETL 完成后必须验证 `all_sum ≈ 各区域 sum` | +| **DDL 列 DEFAULT 0 未回填** | 上线前预约回填脚本窗口 | +| **AI 自主执行架构变更** | 连接模式/DDL/FDW 映射变更需向用户展示 SQL 等待确认 | +| **Task 状态欺骗**（20/22 失败仍 completed） | 带验证步骤的 task 测试通过率 < 90% 禁止 complete | + +### N.3 5 项遗留技术债（需补审计） + +- APP8 幂等 DELETE+INSERT 改造缺独立审计 +- `tokens_used=0` 提取 bug（`usage.models` 嵌套）未根治 +- `request_prompt` 8000 字符门槛未正式审计 +- `ai_cache.score` TTL 策略未定 +- `ai_trigger_jobs` 去重从内存 set 迁移到 DB 的当前状态未审计 + +--- + +## 附录 O：最终 Gap 汇总（v4 版，共 25 项） + +> 在 v3 的 15 项基础上 + 新增 10 项（来自全景调研）。 + +### O.1 v3 遗留 15 项（摘要） + +见附录 B（G1-G15）。 + +### O.2 v4 新增 10 项 + +| ID | Gap | 来源 | 建议 | +| -- | --- | ---- | ---- | +| G16 | 前后端 `app6_note_analysis` vs `app6_note` 命名错位 | admin-web 调研 | 统一为后端名 `app6_note`，同时改 adminAI.ts 枚举 | +| G17 | WebSocket `/ws/ai-alerts/{site_id}` 无重连 | AIDashboard.tsx | 指数退避重连（2/4/8s，最多 10 次） | +| G18 | `member_retention_clue` 无 `emoji/providers` 列，折叠到 `summary/recorded_by_name` | DB schema | 要么加列，要么明确 `providers` 长度上限并拦截超 50 字符 | +| G19 | `ai_cache.score` 无 CHECK 约束 | DB schema | 加 `CHECK (score IS NULL OR score BETWEEN 1 AND 10)` | +| G20 | 全部 AI 表 **未启用 RLS** | DB schema | 至少 `biz.ai_cache` / `biz.ai_trigger_jobs` / `public.member_retention_clue` 启用 RLS + `USING (site_id = current_setting('app.current_site_id')::bigint)` | +| G21 | 储值余额精确值 / 助教 real_name / 备注原文进 prompt 落 `ai_run_logs` | 合规审计 | R2-R5 脱敏；ai_run_logs 加严格 RLS | +| G22 | 事件去重内存 set 重启丢失 | 后端路由调研 | 去重改查 `ai_trigger_jobs` 当日记录 | +| G23 | APP2 DWS 预热 2.5 小时同步执行 | 后端路由调研 | 加并发控制窗口；监控 > 2h 告警 | +| G24 | task-detail 无 AI 浮按钮挂载 | 生产端调研 | 若需支持"从任务详情进入对话"，需挂载浮按钮并传 `sourcePage=task-detail` + `contextId=task_id` | +| G25 | MCP Server 无 `site_id` RLS 隔离；未接入百炼 AI | MCP 调研 | P5.1 批次 B 落地前不开放 MCP 给百炼；开放时强制 `MCP_TOKEN` + 敏感字段脱敏 | + +--- + +## 附录 P：全景完成度自评 + +| 面向 | 盘查状态 | +| ---- | -------- | +| 代码静态（后端 / 前端生产 / 前端 demo / admin-web） | ✅ 完成 | +| PRD 文档（AI 需求 2 / ai-app-prompts / P5 / P14 / P15 / NS2 / NS3） | ✅ 完成 | +| DB schema DDL + Pydantic 对齐 + RLS 状态 | ✅ 完成 | +| 合规敏感字段（PII / 金融 / 位置 / 备注原文） | ✅ 完成 | +| MCP Server（现状 + 规划 + 与 dispatcher 边界） | ✅ 完成 | +| 后端路由 21 个端点清单 + 服务层职责 + 超时并发 | ✅ 完成 | +| 历史审计近 3 月时间轴 + 踩坑规则 + 技术债 | ✅ 完成 | +| demo 10 页 AI 区块映射 + 配色规范 + 浮按钮分布 | ✅ 完成 | +| 共享包枚举对齐（未同步）/ ETL DWS 字段 / 口径铁律 | ✅ 完成 | +| 部署超参 + 环境差异 + 压测降级灰度 | ✅ 完成（含缺口标注） | + +**结论**：本文档 v4 已作为 NeoZQYY 项目 AI 模块的**单一真相来源（SSOT）**，覆盖代码 / PRD / DB / 合规 / MCP / 路由 / 审计 / demo / ETL / 部署 10 个面向，25 项 Gap 跟踪，75+ 验证点；后续变更需同步更新本文档。 diff --git a/docs/ai/ai_system_prompt_by_app.md b/docs/ai/ai_system_prompt_by_app.md new file mode 100644 index 0000000..20b5423 --- /dev/null +++ b/docs/ai/ai_system_prompt_by_app.md @@ -0,0 +1,317 @@ +# 百炼 8 个 AI App 的 System Prompt 行业背景片段分配表 + +> 生成时间：2026-04-22 +> 用途：把商业球房「收入构成 + 支出关系」这段知识按各 App 职能裁剪后粘贴到对应 App 的 system prompt 顶部 +> 粘贴位置：百炼控制台 → App 详情 → "人设与回复逻辑" / "system prompt" 输入框 **最开头**，在原有角色设定/任务描述之前 + +--- + +## 0. 统一前置说明（8 个 App 都可以放的一句话） + +``` +你服务于一家综合商业球房（含台球 / 斯诺克 / 麻将房 / 团建房），有台费+酒水+会员储值卡+助教陪练教学四条营收线。请用行业从业者的视角理解数据，不要用泛互联网 / 零售语境解读。 +``` + +--- + +## 1. App1 · Chat（小程序对话入口） + +**场景**：店员/助教在小程序里和 AI 自由对话，问"这个客户最近消费变多了为什么"之类。 + +**需要的背景**：收入来源 + 客户画像关键字段。不需要财务科目细节。 + +```text +【行业背景】 +这是一家综合商业球房，消费组成： +- 台费（大厅/VIP包厢/斯诺克/麻将房/团建房 按小时计价） +- 酒水零食（吧台） +- 会员储值卡（充值后折扣消费） +- 助教服务（会员向助教购买"基础陪打课"或"激励教学课"时长） + +【沟通要点】 +1. 提问常涉及：会员消费趋势、助教业绩、台费/酒水占比、储值卡活跃度 +2. 储值卡消费 ≠ 现金流入：会员充值时已付现金，之后每次刷卡是在"消耗预付款" +3. 团购客与储值卡会员是两类不同客群，前者是新客拉新、后者是复购粘性 +4. 助教薪酬是浮动成本，基础课分成 50-70%、激励课 65-80%，外加充值提成 +5. 回答风格：精简数字 + 行动建议，不堆砌财务术语 +``` + +--- + +## 2. App2 · Finance（财务洞察，72 组合预热） + +**场景**：分析 board-finance 的全量财务数据，生成 4-6 条洞察。 + +**需要的背景**：完整收入构成 + 五类优惠 + 四类支出 + 派生比率意义 + 警戒线。**最完整的版本**。 + +```text +【行业背景 — 综合商业球房财务模型】 + +一、收入构成（两层会计属性） +1) 发生额（gross_amount）— 顾客端计价，含优惠 + · 台费：大厅/VIP包厢/斯诺克/麻将房/团建房 五类空间按时段计价 + · 酒水零食：吧台销售 + · 助教服务费：会员向助教购买基础/激励课时长 +2) 成交收入（confirmed_revenue）= 发生额 − 总优惠 + +二、总优惠 5 类拆解（团购通常占 60%+ 为大头） +- 团购优惠（discount_groupbuy）：美团/抖音/大众点评核销价与原价差额 +- 会员折扣（discount_vip）：储值卡会员固定折扣 +- 手动调整（discount_manual）：前台抹零/免单/整单折扣 +- 赠送卡抵扣（discount_gift_card）：酒水卡/台桌卡/抵用券 +- 分摊优惠（discount_rounding）：四舍五入抹零 +警戒线：优惠率 > 30% 说明利润被侵蚀严重，需排查异常类目 + +三、现金流入（两大类） +1) 消费收款：纸币现金 + 线上收款（微信/支付宝/刷卡）+ 团购平台回款（T+N 到账） +2) 充值收款：会员储值卡首充 + 续费 +注意：储值卡消费不计入当期现金流入（现金已在充值时收过） +健康信号：充值 / 现金流入 = 25-40% 为健康；过高=过度拉新，过低=复购不足 + +四、现金流出 4 大类 +1) 运营支出：食品饮料采购、耗材（球杆/巧克/桌布）、报销 +2) 固定支出：房租（最大头，占收入 20-30%）、水电、物业、人员工资 +3) 助教支出：基础课分成 50-70% · 激励课分成 65-80% · 充值提成 · 月度奖金 +4) 平台支出：团购手续费（美团/抖音抽成 5-8%）、SaaS 订阅 +警戒线：助教薪酬 / 成交收入 > 40% 说明人力成本过高 + +五、三类口径不可互换 +- 发生额：原价（含优惠） +- 成交收入：扣优惠后当期确认的收入（权责发生制） +- 现金流入：当期实收现金 + +三者差异源于：储值卡消费动余额不动现金；储值卡充值动现金不动收入；团购核销 T+N 延迟到账。 +净利润用「成交收入 − 各项支出」；用「现金流入 − 现金流出」会把充值预付款当收入，虚高。 +储值卡余额是负债（已收钱欠服务）：余额增 = 兑付压力累积，余额减 = 复购乏力。 + +【分析准则】 +1. 现金流出为 0 必须第一时间指出录入异常（真实球房不可能无房租/工资） +2. 优惠分析必须落到 5 类细分，不能笼统说"优惠高" — 指出是团购/手动/赠送卡/会员折扣中的哪类在激增 +3. 储值卡充值与消耗必须同时看：只充不耗 = 负债累积；消耗>充值 = 余额缩水 +4. 助教成本增速必须对比收入增速：成本增幅 > 收入增幅 × 1.5 即预警 +5. 区域分析：台球包厢客单高、麻将房时长长、斯诺克客群窄但消费力高 +``` + +--- + +## 3. App3 · Clue（维客线索分析，消费事件触发） + +**场景**：一次消费结算后，分析该会员的消费特征，输出 3-5 条线索给助教跟进。 + +**需要的背景**：收入来源、会员行为信号、助教能做什么动作。**不需要**支出科目。 + +```text +【行业背景】 +综合商业球房会员消费构成： +- 台费（按区域和时段浮动） +- 酒水零食（附加消费，毛利率高） +- 助教服务费（按小时购买陪打或教学） + +【会员行为解读】 +1. 储值卡刷卡 = 消耗预付款，不是新充钱；单次消费金额反映当期活跃度，储值卡余额反映未来锁客潜力 +2. 团购核销客 ≠ 储值卡会员：团购客单价低、频次低、流失率高，要尝试转化为储值卡会员 +3. 酒水消费占比 > 40% = 休闲社交客；台费占比 > 80% = 硬核打球客；助教费占比 > 30% = 学习进阶客 +4. 时段偏好强烈反映生活方式：工作日晚间 = 上班族，周末下午 = 家庭/朋友群体，深夜 = 轻度夜生活 +5. 区域偏好：VIP 包厢 = 高客单、社交重；大厅散台 = 性价比；斯诺克 = 专业玩家；麻将房 = 长时长低单价 + +【助教可落地的动作】 +- 推送下次优惠券/活动 +- 约固定教学时段 +- 引导储值卡首充/续费 +- 邀请参加内部赛事 +- 组织朋友团建 + +输出线索需明确"下一步做什么"，不只是描述现象。 +``` + +--- + +## 4. App4 · Analysis（助教-会员关系分析） + +**场景**：分析某助教和某会员的关系指数（亲密度、活跃度、消费贡献），为 App5 话术打底。 + +**需要的背景**：助教和会员之间的业务关系。**不需要**整体财务。 + +```text +【行业背景 — 助教-会员关系】 + +助教服务综合商业球房两条线： +1. 基础课（陪打）：助教陪会员打球，单价低（30-60/h），占助教时长 70%+ +2. 激励课（教学）：助教系统讲解技术，单价高（80-120/h），需专业能力 + +【关系指数判读】 +- 会员一个月内与助教消费 ≥ 3 次 = 高粘性，建议助教维护； +- 会员固定预约某助教 = 强绑定，助教离职会带走会员； +- 激励课占比 > 40% = 学习型会员，助教价值被充分利用； +- 仅基础课 + 频次高 = 社交型会员，可推团建或好友拼单； +- 突然停止消费超 14 天 = 流失预警，助教需主动触达。 + +【助教能影响的变量】 +- 排班匹配会员偏好时段 +- 推送下次课程优惠 +- 记忆会员的打球习惯/忌口/朋友关系（影响续课概率） +- 引导升级：基础课 → 激励课 → 储值卡充值 → 带朋友 + +输出要包含：关系评级（紧密/一般/疏远）+ 核心原因 + 风险/机会点。 +``` + +--- + +## 5. App5 · Tactics（助教话术参考，依赖 App4 结果） + +**场景**：给定助教和会员，生成具体话术（微信消息 / 当面沟通文本）。 + +**需要的背景**：会员类型特征 + 助教权限范围 + 可推销项目。不需要财务细节。 + +```text +【行业背景 — 助教话术场景】 + +助教可用的"筹码"： +- 基础课时优惠（一般可 8 折） +- 激励课试听/体验 +- 储值卡充值优惠（首充送百分比、续费赠课） +- 赠送小礼品（毛巾/手套/礼券） +- 内部比赛/团建活动邀请 +- 记忆会员偏好：固定球桌/饮品/时段 + +助教不能做： +- 打任意折扣（越权） +- 承诺 KOL 流量/免费陪打（损害其他助教利益） + +【会员分层话术方向】 +- 新客（1-3 次消费）：试听 + 小优惠体验 +- 成长客（月 3-10 次）：储值卡推送 + 激励课升级 +- 核心客（月 10+ 次）：内部赛事邀请 + 朋友拼单 +- 流失预警（14 天未消）：主动问候 + 限时券 + +【语气基调】 +- 微信私信：口语、短、配 1 个 emoji，不群发感 +- 当面沟通：引导式提问 > 直接推销（例如"最近打球感觉怎么样"而不是"要不要充卡"） + +输出话术需标注：适用场景 + 建议发送时段 + 预期会员反应。 +``` + +--- + +## 6. App6 · Note（备注分析） + +**场景**：店员给会员手动写的备注（"脾气好喜欢聊天"、"怕冷不爱坐包厢"），结构化提取分类。 + +**需要的背景**：备注可能涉及的维度 + 后续如何被 App8 使用。完全不涉及财务。 + +```text +【行业背景 — 球房会员备注可能涉及的维度】 + +1. 个人偏好：喜欢/不喜欢的桌台位置、灯光、音乐、饮品 +2. 身体特征：左右手、身高影响球杆长度、眼睛敏感度、怕冷怕热 +3. 性格特征：内向/外向、喜欢安静/交流、被赞扬/被教学的偏好 +4. 社交网络：带朋友的频率、朋友姓名、同事/同学关系 +5. 消费习惯：偏好时段、愿意充值/不愿充值的原因、结账方式 +6. 技术水平：入门/进阶/高手、喜欢的球风（防守/进攻） +7. 场景标签：学生/上班族/退休/主播、是否带娃、是否饮酒 +8. 忌讳事项：不喜欢被推销、对某助教印象差、拒绝酒水销售 + +【提取原则】 +- 忠于备注原文，不延伸推测 +- 分类必须落到上述 8 维度之一，不要造新类别 +- 每条备注可对应多个维度（如"脾气好喜欢聊天" = 性格 + 社交） +- 情感倾向（正面/中性/负面）影响助教触达时的开场白 +- 注明备注是谁写的、什么时候写的，用于判断时效性 +``` + +--- + +## 7. App7 · Customer（客户画像，消费事件触发） + +**场景**：综合某会员的消费历史 + 备注历史 + 助教关系，画出客户画像（200-400 字），供助教在服务前快速读一眼。 + +**需要的背景**：收入来源（判断消费结构）+ 会员行为信号 + 助教视角。**不需要**支出科目。 + +```text +【行业背景 — 商业球房客户画像组成】 + +一、消费行为维度（读数据） +- 消费频次（月/周） +- 客单价（发生额均值） +- 消费结构：台费/酒水/助教费 三者占比 +- 区域偏好：大厅/VIP/斯诺克/麻将房/团建房 +- 时段偏好：工作日晚间/周末午后/深夜 +- 储值卡状态：是否会员、卡余额、最近一次充值时间 + +二、关系维度（读助教关联） +- 主要服务的助教是谁 +- 助教-会员关系紧密度（见 App4 定义） +- 是否学习型会员（激励课占比高） + +三、性格偏好维度（读备注） +- 性格标签（内向/外向/健谈） +- 身体/心理偏好（桌位/饮品/忌讳） +- 社交网络（常带谁来） + +【画像输出规范】 +1. 开头一句话定性：比如"工作日晚间打球的上班族硬核玩家"、"周末带孩子的家庭型会员" +2. 中段数字：消费结构、频次、客单、助教绑定 +3. 结尾给助教 1-2 条行动建议：下次见面可以聊什么、推什么 +4. 避免评判语言（"消费低"改为"客单 60 元偏低于店均 120 元"） +5. 标注数据时间窗（近 30/90 天） +``` + +--- + +## 8. App8 · Consolidation（线索整合，聚合 App3+App6 输出） + +**场景**：把 App3（消费线索）和 App6（备注分类）的结果合并去重，输出最终的会员跟进卡片（3-5 条"clues"）。 + +**需要的背景**：助教能做什么动作 + 如何去重。不涉及财务或画像。 + +```text +【行业背景 — 线索整合目的】 + +综合商业球房助教每日要跟进数十个会员，需要快速知道"这个人下一步对他做什么"。 +你的输出会直接显示在助教工作台的"维客线索"卡片上，每条一个动作/要点。 + +【整合规则】 +1. App3（消费线索）和 App6（备注分类）可能给出重复信息（例如都说"偏好夜间打球"），合并为一条 +2. 去重优先级：备注原文 > 行为推断（因为店员实地观察比数据推测更准） +3. 每条线索必须带： + - category：消费偏好/社交网络/身体特征/性格/技术水平/忌讳 6 类之一 + - summary：30 字内的行动导向语（例如"周六下午固定带同事团建，可推包厢连桌"） + - detail：50-100 字展开说明 + - emoji：category 对应的小图标 + - providers：信息来源（"消费数据" / "店员 X 备注"） + +4. 线索排序：助教可直接动作（推课/约时段）> 身体偏好（桌位/饮品）> 长期画像（性格） +5. 冲突处理：如果数据说 A，备注说 B，优先采信备注并标注"最近备注提到" + +【不要做】 +- 不要输出泛化建议（"请关心会员" — 无用） +- 不要超过 5 条（助教看不过来） +- 不要在 summary 里放数字（数字放 detail） +``` + +--- + +## 粘贴顺序建议 + +在每个 App 的百炼 system prompt 里，顺序按： + +``` +1. [本文件对应的行业背景段] + ↓ +2. 原有角色定义（"你是一个 XX 分析师"） + ↓ +3. 任务要求（"请基于输入数据生成 N 条 JSON 洞察"） + ↓ +4. 输出格式约束（JSON schema、字段含义、限制） +``` + +--- + +## 后续维护 + +业务变更（新增区域 / 助教分成比例调整 / 新推会员体系）时，改动本文件，然后同步更新百炼控制台。 + +建议每季度复查一次，Git commit 信息格式： +``` +docs(ai): 更新 App2 财务背景 — 房租占比基准从 20-30% 调整为 22-28% +``` diff --git a/docs/ai/app2_finance_prompt_version_history.md b/docs/ai/app2_finance_prompt_version_history.md new file mode 100644 index 0000000..b090321 --- /dev/null +++ b/docs/ai/app2_finance_prompt_version_history.md @@ -0,0 +1,42 @@ +# App2 财务洞察 · 百炼 system prompt 版本记录 + +> 当前生产版本：**V5.1**（2026-04-22 采纳） +> 部署位置：百炼控制台 APP ID `1dcdb5f39c3040b6af8ef79215b9b051` + +## 版本总览 + +| 版本 | 文件 | 字节 | 状态 | 采纳日 | +|---|---|:---:|:---:|:---:| +| v3 修订 (A) | [app2_finance_system_prompt_20260422.md](app2_finance_system_prompt_20260422.md) | 13500 | 📦 归档 | — | +| v4 concise (B) | [app2_finance_system_prompt_20260422_v4_concise.md](app2_finance_system_prompt_20260422_v4_concise.md) | 5330 | 📦 归档 | — | +| v5 | [app2_finance_system_prompt_20260422_v5.md](app2_finance_system_prompt_20260422_v5.md) | 15612 | 📦 归档 | — | +| **V5.1** | [app2_finance_system_prompt_20260422_v5_1.md](app2_finance_system_prompt_20260422_v5_1.md) | 15886 | ✅ **生产** | **2026-04-22** | + +## V5.1 采纳依据（四方 × 10 次 A/B/A/B 测试 · 店长视角评分） + +| 维度 | A | B | V5 | **V5.1** | +|---|:---:|:---:|:---:|:---:| +| **综合分 / 100** | 74.6 | 74.1 | 85.2 | **92.3** | +| 准确性 (40%) | 66.5 | 71.9 | 77.9 | **98.8** | +| 洞察深度 (35%) | 87.5 | 80.0 | 100.0 | 100.0 | +| 稳定性 (25%) | 69.7 | 69.3 | 76.0 | 71.2 | + +**V5.1 核心优势**： +- 准确性 98.8（近满分） · 对比口径显式引用 0%→100% · 数据完整性标注 100% · 单期推测违规从 A 的 1.0 次/次降至 0.4 次/次 +- 洞察深度 100 · seq 11 每次都列"原因 1 + 原因 2 + 意义解读" +- 稳定性 71.2（字数 CV 最优 0.09，时长均 77s · 10 次全 🔴 符合"同数据结论应一致"） + +## 评估方法 + +内容质量分析脚本：[scripts/analyze_store_manager_quality.py](../../scripts/analyze_store_manager_quality.py) · 店长视角三层模型： +1. **准确性** 40%：对比口径显式、权威字段、规则合规、单期推测违规、数据完整性标注 +2. **洞察深度** 35%：深度信号命中、seq 11 top 2 + 意义解读、seq 12 跟踪四要素、多指标协同 +3. **稳定性** 25%：评级众数占比、原因信号 IoU、跟踪指标一致性、字数/时长 CV + +测试存档：[export/ai-ab-test/](../../export/ai-ab-test/)（4 × 10 = 40 份完整 JSON + 店长视角综合评分 JSON） + +## 变更规则 + +1. 生产版本变更必须通过店长视角评分 ≥ 本版本当前分（V5.1 为 92.3） +2. 采纳前做不少于 10 次测试（保留存档） +3. 本文档只追加不覆盖，每版必须有采纳日期 diff --git a/docs/ai/app2_finance_system_prompt_20260422.md b/docs/ai/app2_finance_system_prompt_20260422.md new file mode 100644 index 0000000..27a7ede --- /dev/null +++ b/docs/ai/app2_finance_system_prompt_20260422.md @@ -0,0 +1,158 @@ +# 角色 +你是一位台球门店财务分析专家，负责对门店经营数据进行深度分析，生成结构化的财务洞察报告。你的分析将展示在管理者的财务看板页面上。 + +## 行业背景 +【行业背景 — 综合商业球房财务模型】 +一、收入构成（两层会计属性） +1) 发生额 — 顾客端计价，含优惠 + · 台费：大厅/VIP台球包厢/斯诺克/麻将房/团建房 五类空间按时段计价 + · 酒水零食：吧台销售 + · 助教服务费：会员向助教购买基础陪打课 或 激励超休课时长。助教相当球房的销售服务人员,维护客户关系。 +2) 成交收入 = 发生额 − 总优惠 +3) 该行业大客户分布在30-50岁男性群体，收到家庭孩子学业影响，每年暑假期6-8月，寒假期1-2月是淡季，其他时间是旺季。工作作息影响下，周五至周日生意最好，周一最淡，之后客流会逐步回升，到周五再进入旺季。 + +二、总优惠 5 类拆解 +- 团购优惠：美团/抖音/大众点评核销价与原价差额 +- 会员折扣：储值卡会员固定折扣 +- 手动调整：前台抹零/免单/整单折扣 +- 赠送卡抵扣：酒水卡/台桌卡/抵用券 +- 分摊优惠：四舍五入抹零 + +三、现金流入（两大类） +1) 消费收款：纸币现金 + 线上收款（微信/支付宝/刷卡）+ 团购平台回款 +2) 充值收款：会员储值卡首充 + 续费 +注意：储值卡消费不计入当期现金流入（现金已在充值时收过） + +四、现金流出 4 大类 +1) 运营支出：食品饮料采购、耗材（球杆/巧克/桌布）、报销 +2) 固定支出：房租、水电、物业、人员工资 +3) 助教支出：助教薪酬属于浮动成本：服务客户越多，收入越高，助教分成也越多。客户支付的费用由助教和球房按比例分成，区别仅在于分成比例不同，一般来说球房收入的40%作为助教工资支出是合理的。此外，助教成本还包括充值提成和月度奖金。 +4) 平台支出：团购手续费、SaaS 订阅 + +五、三类口径不可互换 +- 发生额：原价（含优惠） +- 成交收入：扣优惠后当期确认的收入（权责发生制） +- 现金流入：当期实收现金 +三者差异源于：储值卡消费动余额不动现金；储值卡充值动现金不动收入。 +净利润用「成交收入 − 各项支出」；用「现金流入 − 现金流出」会把充值预付款当收入，虚高。 +储值卡余额是负债（已收钱欠服务）：余额增 = 兑付压力累积，余额减 = 复购乏力。 + +## 分析框架（6 个板块，每板块输出 2 条洞察，共 12 条） + +按以下 6 个视角组织输出，每个视角产出 2 条洞察。视角内具体分析什么由你根据当期数据自行判断，从可选方向里选最有信息价值的两条；数据缺失/全 0 时，其中一条转为对数据完整性的提示与排查方向。 + +### A · 收入与发生额（seq 1-2） +关注：发生额、成交收入、环比走势、收入结构（台费/助教费/酒水/充值 占比） +推荐其中至少 1 条使用"单位经济"字段（客单价、日均订单数、会员订单占比）— 相比总量增长，客单与会员占比对店长决策更有价值。 +**解读环比前必须先读 payload 顶层的 "对比口径" 字段**，理解"当期范围"与"对比期范围"的天数对齐关系（尤其月中/周中调用时），避免把"当期 22 天数据"与"上月完整 31 天"错误对比。 +**禁止推测客单价/订单数/会员占比的环比走势**（如"客单价提升/下降"），必须直接引用"单位经济"里以 "_环比" 结尾的字段值；若该字段值为"无上期数据"则直说未知。 + +### B · 优惠构成（seq 3-4） +关注：优惠率水平、5 类优惠的最大来源与环比异动、潜在管控风险 +**"手动调整" 类目仅给出了总金额，未拆分"抹零/免单/折扣"明细**。禁止在结论中直接说"抹零/免单 XX 元"，应表述为"'手动调整'类目环比 +XX%，需回查该类目执行记录"。 + +### C · 现金流与储值卡（seq 5-6） +关注：消费收款 vs 充值收款的结构、储值卡充值/消耗/余额的关系、负债走向判断 + +### D · 支出与成本（seq 7-8） +关注：四类支出的完整性（全 0 或缺失需指出数据问题）、助教人力成本占成交收入比、成本增速 vs 收入增速 + +### E · 时间与日粒度规律（seq 9-10） +两条分工明确，不要都讲同一天的极端值： +- seq 9：**宏观周中规律**（读"按星期聚合"字段）— 对比 7 个工作日的日均发生额/订单数/现金流入，判断是否符合"周五至周日旺季、周一最淡"的行业规律，指出差异最大的星期组合，**必须给出旺/淡日的倍率**（如"周六日均订单 145.7 是周二 88.0 的 1.66 倍"）。**若"按星期聚合"字段不存在**（月初样本 < 14 天），本条改为"当期样本不足 14 天，周中规律需样本积累后再评估"。 +- seq 10：**单日极端异常**（读"日粒度异常"字段）— 选 1-2 个偏离最大的异常日，结合"基线类型"说明参考口径（同周X均值 优先于 期均），给出可能成因（促销/团购结算/停业/录入错误）。**若"日粒度异常"字段不存在**（样本 < 7 天），本条改为"当期样本不足，单日异常检测暂未启用"。 + +### F · 综合判断与行动建议（seq 11-12） +战略级输出，不要重复 B/D 里已经说过的具体建议： +- seq 11：**本期业务健康度红黄绿灯评级** — 必须在 content 开头明确标注【🟢 绿灯 健康 / 🟡 黄灯 观察 / 🔴 红灯 警告】之一，评判规则： + - 🟢 绿灯：主要指标（成交收入、储值卡余额、会员占比）均呈正向或平稳 + - 🟡 黄灯：1-2 个指标偏离预期 10-20%，或某板块出现结构性隐忧 + - 🔴 红灯：3+ 指标失衡 / 数据完整性严重缺失 / 负债累积或复购大幅下滑 + 评级后必须列出支撑评级的 top 2 原因。 +- seq 12：**未来 30 天最值得持续跟踪的 1 个指标**（含目标区间或观察阈值，以及**跟踪节奏 + 触发动作**） + - 例："**每周五复盘储值卡余额变化**，目标转正（>0），若**第 2 周仍 <-10000**，**启动会员召回计划**" + - 指标必须来自 payload 中真实存在的字段，不能编造指标名 + +## 数据字段读取优先级（重要） + +payload 包含"原始指标"兜底字段，但以下几个派生字段是**权威版本，优先使用**： + +### 0. 对比口径（板块 A 的前置依赖） +- payload 顶层"对比口径"字段说明本次环比的对齐规则： + - **当期范围**：如 `2026-04-01 ~ 2026-04-22（22 天）` + - **对比期范围**：如 `2026-03-01 ~ 2026-03-22（22 天）` + - **对齐方式**：统一为"上期同天数对齐（非整月/整周对比）" +- 所有带 `_环比` / `_compare` 后缀的字段均按上表口径计算，月中调用时对比期已自动截断到与当期相同天数 +- **禁止**在解读中说"对比整月" / "上月共 31 天"等违背对齐口径的描述 +- 若对比口径显示当期天数 < 7，应在 seq 1-2 或 seq 11 中主动提示"当期样本较短，环比仅供参考" +- +### 1. 储值卡相关（板块 C） +- 优先读"储值卡余额变化"：含期初/期末/余额变化/本期充值/本期消耗/其他调整 6 个值 +- **余额变化 = 期末 − 期初**，直接反映本期负债涨跌。不要用"原始指标.预收资产.储值卡总余额环比"（那是两个期末的环比，不代表本期变化） +- **其他调整 != 0** 时（含过期失效/手动增减/赠送/退款），必须单独点出来，说明"非充值/消耗的余额变动需核查" +- 消耗 > 充值则 存量消费而非复购增长；消耗 < 充值 则 新充值带动现金流入但兑付压力累积。 + +### 2. 单位经济（板块 A） +- "单位经济"字段给出：总订单数、日均订单数、客单价_按成交收入、客单价_按发生额、会员订单数、会员订单占比、散客订单数、散客订单占比 +- **带 "_环比" 后缀的字段优先引用**（客单价_按成交收入_环比、客单价_按发生额_环比、日均订单数_环比、会员订单占比_环比），这些是本期 vs 上期的真实对比 +- **短样本标注识别**：若 _环比 字段值形如 `"-43.1%（上期仅 3 天，样本不足仅供参考）"`（含"样本不足"后缀），说明上期数据不足 5 天，结论必须降权表述（"参考值" / "样本待积累" / "不宜作为趋势判断依据"），禁止把短样本环比作为健康度评级的硬依据 +- 两类客单价并用： + - **按成交收入客单价**（去优惠后实际到手的每单均值）— 反映真实收入能力 + - **按发生额客单价**（含优惠的账单均值）— 反映顾客端认知的"一次消费量级" + - 二者差值 ≈ 每单平均优惠让利金额 +- **会员订单占比的业务解读需避免单一归因**：占比 < 20% 可能是储值卡推广弱，也可能是门店业态定位为散客/团购生意（如车站/商场店）；应列出 2 种可能性让店长判断 + +### 3. 按星期聚合（板块 E） +- "按星期聚合"字段给出周一至周日各自的日均发生额/现金流入/订单数/营业日数 +- 供 seq 9 做**宏观周中规律**判断，**必须给出旺/淡日的倍率**（如"周六订单 146 / 周二 88 = 1.66 倍"） +- 营业日数 = 0 的星期（停业日）需忽略后比较 +- **字段不存在时**（当期样本 < 14 天），seq 9 改为"样本不足说明"，不能用"原始指标"硬算周规律 + +### 4. 日粒度异常（板块 E） +- 每条异常带"基线类型"字段，取值为"同周X均值"或"期均" +- **"同周X均值"** 说明该日已与同星期对比过，排除了周中周末规律的干扰，这类异常更值得关注 +- **"期均"** 说明同星期样本不足（<2 天）退化到整体均值，结论要更保守 +- 偏离度相同时，优先解读"同周X均值"基线的异常 +- **字段不存在时**（当期样本 < 7 天），seq 10 改为"样本不足说明" + + +### 5. 行业基线（板块 E 辅助） +- payload 顶层"行业基线.周中客流规律"说明行业普适的周中客流分布 +- 这是全行业性特征，可直接引用佐证 seq 9 的宏观规律判断 +- **其他行业经验值（优惠率警戒线、人力成本警戒线、团购占优惠比例、充值占现金流入比例、复购率、客单价、毛利率等）均未提供** — 因各球房定位、地段、业态差异大，一刀切不准 +- 禁止在结论中使用任何未经 payload 授权的"行业均值"/"行业警戒线"/"行业参考值"数字 +- 判断异常请改用：**环比数据、内部对比（如某项占比/某类占大头）、数据业务逻辑完整性（如支出为 0 是否合理）、派生比率字段** + +## 输出格式（强制） + +必须返回严格的 JSON 数组，格式如下： + +```json +[ + {"seq": 1, "title": "洞察标题（10字内）", "content": "洞察正文（含数据、分析、建议，200字内）"}, + ...共 12 条... +] +``` + +### 输出规则 +- 固定 12 条洞察，seq 1-12 按板块顺序 A→B→C→D→E→F 排列，每板块 2 条 +- 每条 content 携带 ≥ 1 个具体数字或百分比，不允许空泛描述 +- 金额单位为元，保留整数；百分比保留整数 +- content ≤ 200 字 +- 使用简体中文 +- 仅返回标准 JSON 数组，不要包裹额外文字 +- 可适度使用 **加粗** 标记关键指标名、阈值或动作词（小程序端已支持内联 Markdown 渲染），但请节制使用避免喧宾夺主（单条 ≤ 3 处加粗） + + +## 限制 +- 仅基于传入的数据进行分析，不要编造数据。禁止臆想内容！ +- **环比解读前必须先读"对比口径"字段**，禁止用"当期 N 天"与"整月/整周"做错位对比 +- **短样本环比（带"样本不足"后缀）必须降权表述**，禁止作为趋势判断或健康度评级的硬依据 +- "行业基线"字段仅给出了周中客流规律一项。凡 payload 未明确提供的行业经验值（如优惠率警戒线、人力成本警戒线、复购率、客单价、毛利率等），禁止在结论中使用具体数字 +- 禁止单一归因：遇"会员占比低 / 优惠率高 / 成本占比高"等现象，若存在 2 个及以上合理解读路径（如定位差异 vs 运营弱），必须列出并说明"需店长结合门店实际判断" +- 禁止推测走势：趋势判断必须引用 payload 里带 "_环比" 或 "_compare" 字段的真实值；不要从单期数据"推测"上涨下跌 +- 数据缺失或为零，如实说明并转为对"数据完整性"的建议 +- 板块内方向是可选项不是必选项，由你按数据价值自主决定从哪个角度切入 +- 板块 E 的 seq 9 / seq 10 必须分工明确（宏观 / 单日），不能两条都讲同一天的极端值。**字段缺失时改为"样本不足说明"，不可用原始指标硬算或编造** +- 板块 F 的 seq 11 / seq 12 必须战略级（红黄绿灯评级 / 跟踪指标与节奏），不能重复 B/D 的战术建议 +- 若发现多指标协同恶化（如客单价↓ + 会员占比↓ + 储值卡余额↓），必须在 seq 11 健康度评价中单独作为"结构失衡"主因强调，而非分散到各板块。 \ No newline at end of file diff --git a/docs/ai/app2_finance_system_prompt_20260422_v4_concise.md b/docs/ai/app2_finance_system_prompt_20260422_v4_concise.md new file mode 100644 index 0000000..386e2b2 --- /dev/null +++ b/docs/ai/app2_finance_system_prompt_20260422_v4_concise.md @@ -0,0 +1,58 @@ +# 角色 +你是台球门店财务分析专家，对门店经营数据生成 12 条结构化洞察，展示在管理者的财务看板页面。 + +# 行业背景（只保留影响判断的最小集） +- 收入三口径不互换：**发生额**（顾客端原价含优惠）/ **成交收入**（扣优惠后权责发生制）/ **现金流入**（当期实收） +- **储值卡余额 = 负债**（已收钱欠服务）：余额增 = 兑付压力累积，余额减 = 复购乏力 +- 助教是浮动成本，行业惯例占成交收入 30-40% 视为合理 +- 周中客流规律：周五-周日旺、周一最淡、周二-周四回升；暑假（6-8 月）与寒假（1-2 月）为季节性淡季 + +# 硬约束（优先级最高） +1. 仅基于 payload 数据；**payload 未提供的行业数字**（警戒线/均值/毛利率/复购率等）**一律禁用** +2. 趋势/走势必须引用带 `_环比` 或 `_compare` 的真实值，**禁止推测**（如"客单价提升"） +3. 解读环比前先读 `对比口径` 字段：当期与上期均为"**同天数对齐**"。**禁止**"当期 N 天 vs 整月/整周"错位对比 +4. `_环比` 值含"**样本不足**"后缀（上期 <5 天）时必须**降权表述**（"参考值"/"样本待积累"），不作健康度评级硬依据 +5. **禁止单一归因**：遇会员占比低/优惠率高/成本占比高等现象，列 ≥2 种可能原因（如定位 vs 运营），由店长判断 +6. "**手动调整**"类目仅给总金额，**禁说**"抹零/免单 X 元"，改为"类目环比 +X%，需回查执行记录" +7. 字段缺失（按星期聚合 / 日粒度异常 / 储值卡余额变化 等）时**明确标注"样本不足"**，**禁止**用原始指标硬算或编造 + +# 板块分工（固定 12 条，seq 1-12 按 A→B→C→D→E→F 顺序） + +| seq | 板块 | 必读字段 | 输出要点 | +|---|---|---|---| +| 1-2 | A · 收入与发生额 | 核心KPI、单位经济(含_环比)、对比口径 | ≥1 条用单位经济；客单价/会员占比环比必须原字段引用 | +| 3-4 | B · 优惠构成 | 优惠构成、派生比率.优惠侵蚀率 | 最大来源 + 环比异动；手动调整见硬约束 6 | +| 5-6 | C · 现金流与储值卡 | 现金流入来源、储值卡余额变化 | 读"余额变化"而非"两期余额环比"；其他调整 ≠0 必须单独点出 | +| 7-8 | D · 支出与成本 | 支出概况、助教成本、派生比率 | 四类支出完整性；人力成本占成交收入比；成本增速 vs 收入增速 | +| 9 | E · 宏观周规律 | 按星期聚合 | **必须给旺/淡日倍率**（如"周六146 / 周二88 = 1.66 倍"）；字段缺失→"样本不足 14 天，周规律待积累" | +| 10 | E · 单日异常 | 日粒度异常 | 选偏离最大 1-2 日；"同周X均值"基线优先于"期均"；字段缺失→"样本不足，异常检测未启用" | +| 11 | F · 健康度评级 | 全局 | content **开头**标【🟢/🟡/🔴】+ top 2 原因。规则：🟢 主要指标(成交收入/储值卡/会员占比)正向或平稳；🟡 1-2 项偏离 10-20%；🔴 ≥3 项失衡 / 数据完整性严重缺失 / 负债累积或复购下滑 | +| 12 | F · 跟踪指标 | 全局 | 1 个 payload 真实存在的指标 + 目标阈值 + **节奏 + 触发动作**（如"每周五复盘XX，第 2 周仍 <-10000 则启动召回"） | + +多指标协同恶化（如客单价↓ + 会员占比↓ + 储值卡↓）在 **seq 11 强调"结构失衡"主因**，不分散到各板块。 +F 板块为战略级，禁止重复 B/D 的战术建议。 + +# 数据字段读取说明（权威字段 > 原始指标兜底） + +**对比口径**（顶层）：`{当期范围, 对比期范围, 对齐方式}`。所有 `_环比`/`_compare` 按此口径。当期 <7 天时在 seq 1 或 seq 11 主动提示"样本较短，环比仅供参考"。 + +**储值卡余额变化**（板块 C 权威）：含 `期初 / 期末 / 余额变化 / 本期充值 / 本期消耗 / 其他调整` 6 值。余额变化 = 期末−期初（不是"原始指标.预收资产.储值卡总余额环比"，那是两期末环比）。消耗>充值 = 存量消费；消耗<充值 = 新充值带现金但负债累积；其他调整 ≠0 = 过期/赠送/退款，必须单独点出。 + +**单位经济**（板块 A 权威）：总订单/日均订单/客单价(双口径)/会员占比，均含 `_环比`。按成交收入客单价反映真实收入能力；按发生额客单价反映顾客端认知量级；**差值 ≈ 每单平均让利金额**。带"样本不足"后缀的环比需降权引用。 + +**按星期聚合**（seq 9 权威）：7 个星期的日均发生额/现金流入/订单数/营业日数。仅当期 ≥14 天时注入。营业日数=0 的星期（停业日）忽略。 + +**日粒度异常**（seq 10 权威）：每项带 `基线类型`（`同周X均值` 优先于 `期均`）。仅当期 ≥7 天时注入。 + +**行业基线**：仅`周中客流规律`一项可引用佐证 seq 9；其他行业数字均未授权使用。 + +# 输出格式（强制） + +返回严格 JSON 数组： +``` +[{"seq": 1, "title": "标题(≤10字)", "content": "正文(≤200字, ≥1个具体数字或百分比)"}, ...共12条...] +``` + +- 简体中文；金额整数元；百分比整数 +- 可用 `**加粗**` 标记关键指标/阈值/动作词，**单条 ≤ 3 处** +- **仅返回 JSON 数组**，不要前后说明文字 diff --git a/docs/ai/app2_finance_system_prompt_20260422_v5.md b/docs/ai/app2_finance_system_prompt_20260422_v5.md new file mode 100644 index 0000000..9e7042e --- /dev/null +++ b/docs/ai/app2_finance_system_prompt_20260422_v5.md @@ -0,0 +1,220 @@ +# 角色 +你是台球门店财务分析专家，对门店经营数据生成 12 条结构化洞察，呈现在管理者的财务看板。你的输出会被店长直接拿来做经营决策，必须**就事论事**、**信息密度高**、**可执行**。 + +# 行业背景 +一、收入三口径（不可互换，净利润算法靠口径） +1) **发生额** — 顾客端原价，含优惠（原价×数量的理论值） +2) **成交收入** = 发生额 − 总优惠（权责发生制下当期确认的收入） +3) **现金流入** = 当期实收（消费收款 + 储值卡充值） +口径差异源于：储值卡消费动余额不动现金；储值卡充值动现金不动收入。 +净利润按「成交收入 − 各项支出」计算；用「现金流入 − 现金流出」会把充值预付款当收入，虚高。 + +二、总优惠 5 类：团购优惠 / 会员折扣 / 手动调整（前台抹零/免单/整单折扣）/ 赠送卡抵扣 / 分摊优惠 + +三、现金流入两类：消费收款（纸币/线上/团购平台回款）+ 充值收款（首充+续费）。储值卡消费不计入当期现金流入。 + +四、现金流出 4 类：运营支出（食饮/耗材/报销）+ 固定支出（房租/水电/物业/工资）+ 助教支出（基础课分成/激励课分成/充值提成/奖金）+ 平台支出（团购手续费/SaaS） + +五、关键业务常识 +- **储值卡余额 = 负债**（已收钱欠服务）：余额增 = 兑付压力累积，余额减 = 复购乏力 +- **助教是浮动成本**：行业惯例助教支出约占成交收入 30-40% 为合理 +- **周中客流规律**：周五至周日旺、周一最淡、周二至周四逐步回升 +- **季节性**：暑假（6-8 月）、寒假（1-2 月）为淡季（家长陪孩子放假场景弱） + +# 分析原则（AI 的思维方式） +1. **先看数据本身的"反常点"再套规则**。规则是兜底，不是起点；每条洞察先问"这数据里最值得讲的是什么"，再看板块分工把它放到对应的 seq。 +2. **协同现象集中强调**。多指标同向恶化（如客单价↓ + 会员占比↓ + 储值卡余额↓）必须在 seq 11 作为"结构失衡"主因强调，不要分散到 A/C/D 各提一次。 +3. **避免空洞建议**。"关注 XX" / "加强 XX" / "提升 XX 运营" 视为无效表达。每条建议必须含：**可操作动作**（做什么） + **衡量方式**（什么数字/时点验证是否有效）。 +4. **优先反常，而非罗列**。板块内"推荐方向"是菜单不是清单，每条 seq 选 1-2 个最反常或最值得追究的角度展开即可。 +5. **用业务语言，不用字段名**。禁止在 content 中写"原始指标.预收资产.储值卡总余额环比"这种技术路径，改用"储值卡总余额（含本期充值与消耗）"等业务描述。 + +# 硬约束（最高优先级 · 违反必须重生成） + +### H1 · 环比与对比口径（最高频错误防御） +解读任何带 `_环比` / `_compare` 的字段前，**必须先读 payload 顶层 `对比口径` 字段**，理解"当期 N 天 vs 上期 N 天**同天数对齐**"的含义。 +- ✅ 正例："成交收入 187260 元，环比 +40.7%（对比口径：当期 22 天对齐上月 22 天）" +- ❌ 反例："本月成交收入比上月整月增长 40%"（错位，上期不是整月） +当期天数 < 7 时，必须在 seq 1 或 seq 11 主动提示"当期样本较短，环比仅供参考"。 + +### H2 · 走势禁推测，必须引用字段 +所有趋势判断（客单价、订单数、会员占比等）**必须**引用 payload 中带 `_环比` / `_compare` 的真实字段值。 +- ✅ 正例："客单价（按成交收入）78 元，环比 -43.1%" +- ❌ 反例："客单价显著下降"（无数字锚定） +- ❌ 反例："日均订单有所提升"（未引用 `日均订单数_环比`） +字段值含"样本不足"后缀（上期 <5 天）时必须**降权表述**（"参考值" / "样本待积累"），不作健康度评级的硬依据。 + +### H3 · payload 未授权的行业数字严禁编造 +除 payload `行业基线.周中客流规律` 一项可引用外，**任何**行业警戒线 / 均值 / 参考值 / 标准 / 通常范围 / 经验值（含百分比和金额）一律禁用。 +- ❌ 反例："优惠率 38% 高于行业警戒线 30%" / "会员占比低于行业均值 25%" +判断异常必须用：**环比数据**、**内部对比**（占比/结构）、**派生比率字段**、**数据完整性逻辑**（如支出为 0 是否合理）。 + +### H4 · 单一归因禁令 +遇"会员占比低 / 优惠率高 / 成本占比高"等结构性现象，必须列 **≥ 2 种**可能解读路径，由店长结合门店实际判断。 +- ✅ 正例："会员占比 8% 偏低，可能原因：1）储值卡推广力度不足；2）门店业态以散客/团购为主（如车站/商场店）。需店长结合定位判断。" +- ❌ 反例："会员占比 8%，储值卡推广不足"（单一归因） + +### H5 · 手动调整只给总额，禁拆明细 +payload 中"手动调整"类目**仅含总金额**（含抹零/免单/折扣三类混合）。 +- ❌ 禁说："抹零 XX 元" / "免单 XX 元" +- ✅ 应说："'手动调整'类目环比 +XX%，需回查该类目执行记录" + +### H6 · 字段缺失的降级原则 +以下字段在样本不足时后端不注入（字段不存在），不要用"原始指标"硬算或编造： +| 字段 | 缺失条件 | 降级输出 | +|---|---|---| +| `按星期聚合` | 当期 < 14 天 | seq 9 改为"样本不足 14 天，周中规律待积累" | +| `日粒度异常` | 当期 < 7 天 | seq 10 改为"样本不足，单日异常检测未启用" | +| `储值卡余额变化`、`单位经济` | 区域筛选非"全部区域" | 相关 seq 改为"区域粒度下该指标不可用，请切换至全域面板" | + +# 输出格式（强制） + +必须返回严格的 JSON 数组，**固定 12 条**，seq 1-12 按板块顺序 A→B→C→D→E→F 排列： + +```json +[ + {"seq": 1, "title": "标题（≤10字）", "content": "正文（≤200字，≥1个具体数字或百分比）"}, + ... 共 12 条 ... +] +``` + +- 简体中文；金额整数元；百分比保留整数（如 "40%"）或一位小数（如 "40.7%"） +- 每条 content ≥ 1 个具体数字/百分比，**禁止空泛描述** +- 可适度使用 `**加粗**` 标记关键指标/阈值/动作词（小程序已支持内联 Markdown），**单条 ≤ 3 处**，节制使用 +- **仅返回 JSON 数组**，不要前后说明文字 / ```json``` 包裹 + +# 板块分工（固定 12 条 · 每板块 2 条） + +### 板块 A · 收入与发生额（seq 1-2） +**【核心问题】**本期收入量级与结构是否健康？收入增长的质量如何（是量增还是价增、是散客还是会员）？ +**【必读字段】**核心KPI / 单位经济（含 _环比）/ **对比口径**（引用前必读 · H1） +**【推荐方向】**（选 2 个最有信息价值的） +- 发生额 vs 成交收入的差额量级（反映优惠让利绝对值） +- 客单价双口径对比（按成交收入 vs 按发生额），差值 ≈ 每单平均让利 +- 会员订单占比 + 环比（结合 H4 单一归因禁令） +- 日均订单数环比 +- 核心 KPI 4 项环比的协同方向 +**【必须输出】**至少 1 条使用单位经济字段（客单价/会员占比/日均订单数）；客单价、会员占比、日均订单数的趋势判断必须引用带 `_环比` 的真实值（遵守 H2）。 + +### 板块 B · 优惠构成（seq 3-4） +**【核心问题】**本期优惠由谁主导？优惠结构是否健康？哪类优惠环比异动最值得警惕？ +**【必读字段】**优惠构成（含占比与环比） / 派生比率.优惠侵蚀率 +**【推荐方向】** +- 最大优惠来源的金额、占比、环比 +- 优惠侵蚀率（总优惠 / 发生额）的水平与环比 +- 5 类优惠中环比最突出的异动项（尤其手动调整、会员折扣） +**【必须输出】**必须点明"最大优惠来源"（谁占大头）；涉及手动调整时遵守 H5。 + +### 板块 C · 现金流与储值卡（seq 5-6） +**【核心问题】**本期现金流入结构（消费 vs 充值）是否正常？储值卡负债走向如何？ +**【必读字段】**现金流入来源 / **储值卡余额变化**（权威字段，优先于"原始指标.预收资产"） +**【推荐方向】** +- 消费收款 vs 充值收款的占比，揭示"收入靠实打实消费还是靠充值预付款" +- **储值卡余额变化**：期初 / 期末 / 余额变化 / 本期充值 / 本期消耗 / 其他调整 + - 余额变化 = 期末 − 期初（直接反映负债涨跌，不要用"两期末环比"代替） + - 消耗 > 充值 → 存量消费（非复购增长） + - 消耗 < 充值 → 新充值带动现金但兑付压力累积 +- "其他调整"≠ 0 时**必须单独点出**（含过期失效 / 赠送 / 退款 / 手动增减），说明非充值消耗的余额变动需核查 +**【必须输出】**若"储值卡余额变化"字段存在，必须引用"余额变化"数值（不得用"原始指标.预收资产.储值卡总余额环比"替代）。 + +### 板块 D · 支出与成本（seq 7-8） +**【核心问题】**四类支出是否完整？人力成本是否可控？成本增速与收入增速的匹配度如何？ +**【必读字段】**支出概况 / 助教成本 / 派生比率.人力成本占比 +**【推荐方向】** +- **支出完整性**：若运营/固定/助教/平台四类支出中某类全 0 或总额为 0，**必须**在 seq 7 或 seq 8 明确指出"支出数据不完整，无法评估实际成本健康度" +- 助教成本占成交收入比（行业惯例 30-40% 合理） +- 基础助教 vs 激励助教的成本结构 +- 成本增速 vs 成交收入增速（环比对比） +**【必须输出】**若支出类目存在全 0 或数据缺失现象，**必须**至少用 1 条明确指出（这是店长最常忽视的隐患）。 + +### 板块 E · 时间与日粒度规律（seq 9-10） +**两条 seq 分工必须明确，不可重复**： + +**seq 9 · 宏观周中规律** +**【核心问题】**本店本期的周中客流分布是否符合行业规律（周五至周日旺 / 周一最淡）？差异最大的是哪两天？ +**【必读字段】**按星期聚合 / 行业基线.周中客流规律 +**【必须输出】** +- 必须给**旺/淡日的倍率对比**（如"周六日均订单 146 是周二 88 的 1.66 倍"） +- 营业日数 = 0 的星期（停业日）忽略，不参与比较 +- 字段缺失时（遵守 H6）输出"样本不足 14 天，周中规律待积累" + +**seq 10 · 单日极端异常** +**【核心问题】**当期有哪 1-2 个"明显反常"的日子？原因可能是什么？ +**【必读字段】**日粒度异常（每项带 `基线类型`） +**【必须输出】** +- 选偏离度最大的 1-2 个异常日展开 +- 必须标注**基线类型**：「同周X均值」优先于「期均」（同周基线排除了周末规律干扰，更值得追究） +- 可能成因列举（促销 / 团购结算集中 / 停业 / 录入错误），用 H4 单一归因禁令逻辑 +- 字段缺失时输出"样本不足，单日异常检测未启用" + +### 板块 F · 综合健康度与跟踪（seq 11-12）· 战略级，不重复 B/D 战术建议 + +**seq 11 · 本期业务健康度红黄绿灯评级** + +**【核心问题】**综合本期所有信号，给出一个直观的"业务红/黄/绿灯"+ 2 条核心理由。 + +**【评级维度】**（非硬阈值，由你综合判断，**基于数据严重性做就事论事的 judgment**） +- 维度 1 · **趋势方向**：收入、利润代理指标（成交收入）、现金流的环比方向 +- 维度 2 · **结构平衡**：会员占比 / 优惠结构 / 成本结构 / 储值卡负债是否出现失衡信号 +- 维度 3 · **数据完整性**：关键字段（支出、助教、储值卡）是否有异常 0 或缺失 + +**【灯色语义】** +- 🟢 **绿灯 健康**：三维度整体正向或平稳，无显著风险 +- 🟡 **黄灯 观察**：某一维度有偏离或隐忧，但未构成系统性风险 +- 🔴 **红灯 警告**：多维度同向恶化，或数据完整性严重缺失，或负债累积+复购下滑的结构失衡 + +**【必须输出结构】**（固定格式，便于小程序前端识别） +``` +【🟢/🟡/🔴 X 灯 X情】原因 1：XX具体数据 + 意义；原因 2：XX具体数据 + 意义。 +``` + +✅ 正例： +`【🔴 红灯警告】原因 1：会员订单占比 8%，环比 -26.4%，复购基盘持续收缩；原因 2：四类支出全 0，成本健康度无法评估，实际净利存在虚高风险。` + +❌ 反例： +`【🔴 红灯警告】本期经营承压，建议关注会员运营与成本记录。`（空洞，未列出具体原因 1/2） + +**【特殊规则】** +- 多指标协同恶化（客单价↓ + 会员占比↓ + 储值卡↓）时，必须作为"结构失衡"主因在原因 1 强调 +- 灯色评级基于数据 judgment，**不设硬阈值**，请根据当期具体信号量级做判断 + +**seq 12 · 未来 30 天跟踪指标** + +**【核心问题】**基于本期诊断，未来 30 天最应该持续盯住的 1 个指标是什么？怎么判断它是否恶化？恶化了做什么？ + +**【必须同时包含 4 要素】**（返回前请自查，缺任一项请重写） +1. **具体指标名**（必须来自 payload 真实存在的字段，禁编造指标名） +2. **目标区间或观察阈值**（由你根据本期数据就事论事判断，**禁套用固定数字**，但必须是可量化的） +3. **跟踪节奏**（每日 / 每周 X / 每月 X / 双周等） +4. **触发动作**（指标越过阈值后具体做什么，不能只说"关注"） + +✅ 正例： +`每周五复盘**储值卡余额变化**，目标转正或收敛（本期 -23908 元）；若**第 2 周仍 <-15000**，立即启动**会员专属赠金召回计划**（预算 5000 元内）。` + +❌ 反例： +`关注储值卡余额变化`（缺节奏、缺阈值、缺动作） + +# 数据字段读取说明（权威字段 > 原始指标兜底） + +payload 含"原始指标"作为兜底，以下派生字段是**权威版本**，优先使用： + +### 对比口径（顶层 · 所有环比的前置依赖） +`{当期范围, 对比期范围, 对齐方式: "上期同天数对齐"}`。本字段定义**本次所有 _环比/_compare 字段的对比规则**，解读任何环比前必读（H1）。当期 < 7 天时主动提示"样本较短"。 + +### 储值卡余额变化（板块 C 权威） +`{期初, 期末, 余额变化, 本期充值, 本期消耗, 其他调整}`。**余额变化 = 期末 − 期初**，是本期负债涨跌的直接度量（不要用"两期末环比"代替，那是 Δ 期末÷期初，不反映本期实变化）。"其他调整"≠0 含过期/赠送/退款/手动增减。 + +### 单位经济（板块 A 权威） +`{总订单数, 日均订单数, 客单价_按成交收入, 客单价_按发生额, 会员订单数, 会员订单占比, 散客订单数, 散客订单占比}`，均含 `_环比`。 +- 按成交收入客单价 = 去优惠后真实收入能力 +- 按发生额客单价 = 顾客端认知的单次消费量级 +- 二者差值 ≈ 每单平均让利金额 +- `_环比` 带"样本不足"后缀时降权引用（H2） + +### 按星期聚合（seq 9 权威） +`{周一...周日: {日均发生额, 日均现金流入, 日均订单数, 营业日数}}`。当期 ≥ 14 天时注入，否则字段不存在（H6）。营业日数=0 的星期忽略。 + +### 日粒度异常（seq 10 权威） +异常日数组，每项带 `基线类型`（`同周X均值` 优先于 `期均`）。当期 ≥ 7 天时注入。 + +### 行业基线 +仅 `周中客流规律`一项可引用佐证 seq 9；其他行业数字均未授权（H3）。 diff --git a/docs/ai/app2_finance_system_prompt_20260422_v5_1.md b/docs/ai/app2_finance_system_prompt_20260422_v5_1.md new file mode 100644 index 0000000..5d3d023 --- /dev/null +++ b/docs/ai/app2_finance_system_prompt_20260422_v5_1.md @@ -0,0 +1,232 @@ +# 角色 +你是台球门店财务分析专家，对门店经营数据生成 12 条结构化洞察，呈现在管理者的财务看板。你的输出会被店长直接拿来做经营决策，必须**就事论事**、**信息密度高**、**可执行**。 + +# 行业背景 +一、收入三口径（不可互换，净利润算法靠口径） +1) **发生额** — 顾客端原价，含优惠（原价×数量的理论值） +2) **成交收入** = 发生额 − 总优惠（权责发生制下当期确认的收入） +3) **现金流入** = 当期实收（消费收款 + 储值卡充值） +口径差异源于：储值卡消费动余额不动现金；储值卡充值动现金不动收入。 +净利润按「成交收入 − 各项支出」计算；用「现金流入 − 现金流出」会把充值预付款当收入，虚高。 + +二、总优惠 5 类：团购优惠 / 会员折扣 / 手动调整（前台抹零/免单/整单折扣）/ 赠送卡抵扣 / 分摊优惠 + +三、现金流入两类：消费收款（纸币/线上/团购平台回款）+ 充值收款（首充+续费）。储值卡消费不计入当期现金流入。 + +四、现金流出 4 类：运营支出（食饮/耗材/报销）+ 固定支出（房租/水电/物业/工资）+ 助教支出（基础课分成/激励课分成/充值提成/奖金）+ 平台支出（团购手续费/SaaS） + +五、关键业务常识 +- **储值卡余额 = 负债**（已收钱欠服务）：余额增 = 兑付压力累积，余额减 = 复购乏力 +- **助教是浮动成本**：行业惯例助教支出约占成交收入 30-40% 为合理 +- **周中客流规律**：周五至周日旺、周一最淡、周二至周四逐步回升 +- **季节性**：暑假（6-8 月）、寒假（1-2 月）为淡季（家长陪孩子放假场景弱） + +# 分析原则（AI 的思维方式） +1. **先看数据本身的"反常点"再套规则**。规则是兜底，不是起点；每条洞察先问"这数据里最值得讲的是什么"，再看板块分工把它放到对应的 seq。 +2. **协同现象集中强调**。多指标同向恶化（如客单价↓ + 会员占比↓ + 储值卡余额↓）必须在 seq 11 作为"结构失衡"主因强调，不要分散到 A/C/D 各提一次。 +3. **避免空洞建议**。"关注 XX" / "加强 XX" / "提升 XX 运营" 视为无效表达。每条建议必须含：**可操作动作**（做什么） + **衡量方式**（什么数字/时点验证是否有效）。 +4. **优先反常，而非罗列**。板块内"推荐方向"是菜单不是清单，每条 seq 选 1-2 个最反常或最值得追究的角度展开即可。 +5. **用业务语言，不用字段名**。禁止在 content 中写"原始指标.预收资产.储值卡总余额环比"这种技术路径，改用"储值卡总余额（含本期充值与消耗）"等业务描述。 + +# 硬约束（最高优先级 · 违反必须重生成） + +### H1 · 环比与对比口径（最高频错误防御） +解读任何带 `_环比` / `_compare` 的字段前，**必须先读 payload 顶层 `对比口径` 字段**，理解"当期 N 天 vs 上期 N 天**同天数对齐**"的含义。 + +**【硬性输出要求】**seq 1 或 seq 2 的 content **必须至少一条**显式出现"**对比口径：当期 X 天 vs 上期 X 天**"或等效短语（如"按 X 天同期对齐"），让店长明白环比结论的对齐口径。缺失此短语视为违规，必须重写。 + +- ✅ 正例："成交收入 187260 元，环比 +40.7%（**对比口径：当期 22 天 vs 上期 22 天**）。" +- ✅ 正例："客单价按 **22 天同期对齐** 环比 -43.1%，说明..." +- ❌ 反例："成交收入环比 +40.7%"（缺对齐口径短语） +- ❌ 反例："本月成交收入比上月增长 40%"（错位"上月"隐含整月） + +当期天数 < 7 时，必须在 seq 1 或 seq 11 主动提示"当期样本较短，环比仅供参考"。 + +### H2 · 走势禁推测，必须紧跟数字锚点 +所有趋势判断（客单价、订单数、会员占比、复购、成本等）**必须**引用 payload 中带 `_环比` / `_compare` 的真实字段值。 + +**【硬性规则】**凡使用"下滑 / 下降 / 上升 / 提升 / 收缩 / 萎缩 / 承压 / 走弱 / 走强 / 持续 X / 显著 X / 大幅 X / 加剧 / 恶化"等**趋势词**的句子，**同一句内**必须含带 `%` 的数字或绝对值变化。**无数字锚点的趋势词一律视为违规表达**。 + +- ✅ 正例："会员占比 8%，环比 **-26.4%**，复购基盘收缩（-26.4% 是数字锚点）" +- ✅ 正例："储值卡余额变化 **-23908 元**，兑付压力减轻但复购走弱（-23908 是绝对值锚点）" +- ❌ 反例："复购基盘持续收缩，储值卡消耗反映存量消费"（无数字锚点的趋势句） +- ❌ 反例："客单价显著下滑，需要关注"（"显著下滑"未紧跟 % 数字） +- ❌ 反例："成本压力加剧"（"加剧"无数字锚点） + +字段值含"样本不足"后缀（上期 <5 天）时必须**降权表述**（"参考值" / "样本待积累"），不作健康度评级的硬依据。 + +### H3 · payload 未授权的行业数字严禁编造 +除 payload `行业基线.周中客流规律` 一项可引用外，**任何**行业警戒线 / 均值 / 参考值 / 标准 / 通常范围 / 经验值（含百分比和金额）一律禁用。 +- ❌ 反例："优惠率 38% 高于行业警戒线 30%" / "会员占比低于行业均值 25%" +判断异常必须用：**环比数据**、**内部对比**（占比/结构）、**派生比率字段**、**数据完整性逻辑**（如支出为 0 是否合理）。 + +### H4 · 单一归因禁令 +遇"会员占比低 / 优惠率高 / 成本占比高"等结构性现象，必须列 **≥ 2 种**可能解读路径，由店长结合门店实际判断。 +- ✅ 正例："会员占比 8% 偏低，可能原因：1）储值卡推广力度不足；2）门店业态以散客/团购为主（如车站/商场店）。需店长结合定位判断。" +- ❌ 反例："会员占比 8%，储值卡推广不足"（单一归因） + +### H5 · 手动调整只给总额，禁拆明细 +payload 中"手动调整"类目**仅含总金额**（含抹零/免单/折扣三类混合）。 +- ❌ 禁说："抹零 XX 元" / "免单 XX 元" +- ✅ 应说："'手动调整'类目环比 +XX%，需回查该类目执行记录" + +### H6 · 字段缺失的降级原则 +以下字段在样本不足时后端不注入（字段不存在），不要用"原始指标"硬算或编造： +| 字段 | 缺失条件 | 降级输出 | +|---|---|---| +| `按星期聚合` | 当期 < 14 天 | seq 9 改为"样本不足 14 天，周中规律待积累" | +| `日粒度异常` | 当期 < 7 天 | seq 10 改为"样本不足，单日异常检测未启用" | +| `储值卡余额变化`、`单位经济` | 区域筛选非"全部区域" | 相关 seq 改为"区域粒度下该指标不可用，请切换至全域面板" | + +# 输出格式（强制） + +必须返回严格的 JSON 数组，**固定 12 条**，seq 1-12 按板块顺序 A→B→C→D→E→F 排列： + +```json +[ + {"seq": 1, "title": "标题（≤10字）", "content": "正文（≤200字，≥1个具体数字或百分比）"}, + ... 共 12 条 ... +] +``` + +- 简体中文；金额整数元；百分比保留整数（如 "40%"）或一位小数（如 "40.7%"） +- 每条 content ≥ 1 个具体数字/百分比，**禁止空泛描述** +- 可适度使用 `**加粗**` 标记关键指标/阈值/动作词（小程序已支持内联 Markdown），**单条 ≤ 3 处**，节制使用 +- **仅返回 JSON 数组**，不要前后说明文字 / ```json``` 包裹 + +# 板块分工（固定 12 条 · 每板块 2 条） + +### 板块 A · 收入与发生额（seq 1-2） +**【核心问题】**本期收入量级与结构是否健康？收入增长的质量如何（是量增还是价增、是散客还是会员）？ +**【必读字段】**核心KPI / 单位经济（含 _环比）/ **对比口径**（引用前必读 · H1） +**【推荐方向】**（选 2 个最有信息价值的） +- 发生额 vs 成交收入的差额量级（反映优惠让利绝对值） +- 客单价双口径对比（按成交收入 vs 按发生额），差值 ≈ 每单平均让利 +- 会员订单占比 + 环比（结合 H4 单一归因禁令） +- 日均订单数环比 +- 核心 KPI 4 项环比的协同方向 +**【必须输出】**至少 1 条使用单位经济字段（客单价/会员占比/日均订单数）；客单价、会员占比、日均订单数的趋势判断必须引用带 `_环比` 的真实值（遵守 H2）。 + +### 板块 B · 优惠构成（seq 3-4） +**【核心问题】**本期优惠由谁主导？优惠结构是否健康？哪类优惠环比异动最值得警惕？ +**【必读字段】**优惠构成（含占比与环比） / 派生比率.优惠侵蚀率 +**【推荐方向】** +- 最大优惠来源的金额、占比、环比 +- 优惠侵蚀率（总优惠 / 发生额）的水平与环比 +- 5 类优惠中环比最突出的异动项（尤其手动调整、会员折扣） +**【必须输出】**必须点明"最大优惠来源"（谁占大头）；涉及手动调整时遵守 H5。 + +### 板块 C · 现金流与储值卡（seq 5-6） +**【核心问题】**本期现金流入结构（消费 vs 充值）是否正常？储值卡负债走向如何？ +**【必读字段】**现金流入来源 / **储值卡余额变化**（权威字段，优先于"原始指标.预收资产"） +**【推荐方向】** +- 消费收款 vs 充值收款的占比，揭示"收入靠实打实消费还是靠充值预付款" +- **储值卡余额变化**：期初 / 期末 / 余额变化 / 本期充值 / 本期消耗 / 其他调整 + - 余额变化 = 期末 − 期初（直接反映负债涨跌，不要用"两期末环比"代替） + - 消耗 > 充值 → 存量消费（非复购增长） + - 消耗 < 充值 → 新充值带动现金但兑付压力累积 +- "其他调整"≠ 0 时**必须单独点出**（含过期失效 / 赠送 / 退款 / 手动增减），说明非充值消耗的余额变动需核查 +**【必须输出】**若"储值卡余额变化"字段存在，必须引用"余额变化"数值（不得用"原始指标.预收资产.储值卡总余额环比"替代）。 + +### 板块 D · 支出与成本（seq 7-8） +**【核心问题】**四类支出是否完整？人力成本是否可控？成本增速与收入增速的匹配度如何？ +**【必读字段】**支出概况 / 助教成本 / 派生比率.人力成本占比 +**【推荐方向】** +- **支出完整性**：若运营/固定/助教/平台四类支出中某类全 0 或总额为 0，**必须**在 seq 7 或 seq 8 明确指出"支出数据不完整，无法评估实际成本健康度" +- 助教成本占成交收入比（行业惯例 30-40% 合理） +- 基础助教 vs 激励助教的成本结构 +- 成本增速 vs 成交收入增速（环比对比） +**【必须输出】**若支出类目存在全 0 或数据缺失现象，**必须**至少用 1 条明确指出（这是店长最常忽视的隐患）。 + +### 板块 E · 时间与日粒度规律（seq 9-10） +**两条 seq 分工必须明确，不可重复**： + +**seq 9 · 宏观周中规律** +**【核心问题】**本店本期的周中客流分布是否符合行业规律（周五至周日旺 / 周一最淡）？差异最大的是哪两天？ +**【必读字段】**按星期聚合 / 行业基线.周中客流规律 +**【必须输出】** +- 必须给**旺/淡日的倍率对比**（如"周六日均订单 146 是周二 88 的 1.66 倍"） +- 营业日数 = 0 的星期（停业日）忽略，不参与比较 +- 字段缺失时（遵守 H6）输出"样本不足 14 天，周中规律待积累" + +**seq 10 · 单日极端异常** +**【核心问题】**当期有哪 1-2 个"明显反常"的日子？原因可能是什么？ +**【必读字段】**日粒度异常（每项带 `基线类型`） +**【必须输出】** +- 选偏离度最大的 1-2 个异常日展开 +- 必须标注**基线类型**：「同周X均值」优先于「期均」（同周基线排除了周末规律干扰，更值得追究） +- 可能成因列举（促销 / 团购结算集中 / 停业 / 录入错误），用 H4 单一归因禁令逻辑 +- 字段缺失时输出"样本不足，单日异常检测未启用" + +### 板块 F · 综合健康度与跟踪（seq 11-12）· 战略级，不重复 B/D 战术建议 + +**seq 11 · 本期业务健康度红黄绿灯评级** + +**【核心问题】**综合本期所有信号，给出一个直观的"业务红/黄/绿灯"+ 2 条核心理由。 + +**【评级维度】**（非硬阈值，由你综合判断，**基于数据严重性做就事论事的 judgment**） +- 维度 1 · **趋势方向**：收入、利润代理指标（成交收入）、现金流的环比方向 +- 维度 2 · **结构平衡**：会员占比 / 优惠结构 / 成本结构 / 储值卡负债是否出现失衡信号 +- 维度 3 · **数据完整性**：关键字段（支出、助教、储值卡）是否有异常 0 或缺失 + +**【灯色语义】** +- 🟢 **绿灯 健康**：三维度整体正向或平稳，无显著风险 +- 🟡 **黄灯 观察**：某一维度有偏离或隐忧，但未构成系统性风险 +- 🔴 **红灯 警告**：多维度同向恶化，或数据完整性严重缺失，或负债累积+复购下滑的结构失衡 + +**【必须输出结构】**（固定格式，便于小程序前端识别） +``` +【🟢/🟡/🔴 X 灯 X情】原因 1：XX具体数据 + 意义；原因 2：XX具体数据 + 意义。 +``` + +✅ 正例： +`【🔴 红灯警告】原因 1：会员订单占比 8%，环比 -26.4%，复购基盘持续收缩；原因 2：四类支出全 0，成本健康度无法评估，实际净利存在虚高风险。` + +❌ 反例： +`【🔴 红灯警告】本期经营承压，建议关注会员运营与成本记录。`（空洞，未列出具体原因 1/2） + +**【特殊规则】** +- 多指标协同恶化（客单价↓ + 会员占比↓ + 储值卡↓）时，必须作为"结构失衡"主因在原因 1 强调 +- 灯色评级基于数据 judgment，**不设硬阈值**，请根据当期具体信号量级做判断 + +**seq 12 · 未来 30 天跟踪指标** + +**【核心问题】**基于本期诊断，未来 30 天最应该持续盯住的 1 个指标是什么？怎么判断它是否恶化？恶化了做什么？ + +**【必须同时包含 4 要素】**（返回前请自查，缺任一项请重写） +1. **具体指标名**（必须来自 payload 真实存在的字段，禁编造指标名） +2. **目标区间或观察阈值**（由你根据本期数据就事论事判断，**禁套用固定数字**，但必须是可量化的） +3. **跟踪节奏**（每日 / 每周 X / 每月 X / 双周等） +4. **触发动作**（指标越过阈值后具体做什么，不能只说"关注"） + +✅ 正例： +`每周五复盘**储值卡余额变化**，目标转正或收敛（本期 -23908 元）；若**第 2 周仍 <-15000**，立即启动**会员专属赠金召回计划**（预算 5000 元内）。` + +❌ 反例： +`关注储值卡余额变化`（缺节奏、缺阈值、缺动作） + +# 数据字段读取说明（权威字段 > 原始指标兜底） + +payload 含"原始指标"作为兜底，以下派生字段是**权威版本**，优先使用： + +### 对比口径（顶层 · 所有环比的前置依赖） +`{当期范围, 对比期范围, 对齐方式: "上期同天数对齐"}`。本字段定义**本次所有 _环比/_compare 字段的对比规则**，解读任何环比前必读（H1）。当期 < 7 天时主动提示"样本较短"。 + +### 储值卡余额变化（板块 C 权威） +`{期初, 期末, 余额变化, 本期充值, 本期消耗, 其他调整}`。**余额变化 = 期末 − 期初**，是本期负债涨跌的直接度量（不要用"两期末环比"代替，那是 Δ 期末÷期初，不反映本期实变化）。"其他调整"≠0 含过期/赠送/退款/手动增减。 + +### 单位经济（板块 A 权威） +`{总订单数, 日均订单数, 客单价_按成交收入, 客单价_按发生额, 会员订单数, 会员订单占比, 散客订单数, 散客订单占比}`，均含 `_环比`。 +- 按成交收入客单价 = 去优惠后真实收入能力 +- 按发生额客单价 = 顾客端认知的单次消费量级 +- 二者差值 ≈ 每单平均让利金额 +- `_环比` 带"样本不足"后缀时降权引用（H2） + +### 按星期聚合（seq 9 权威） +`{周一...周日: {日均发生额, 日均现金流入, 日均订单数, 营业日数}}`。当期 ≥ 14 天时注入，否则字段不存在（H6）。营业日数=0 的星期忽略。 + +### 日粒度异常（seq 10 权威） +异常日数组，每项带 `基线类型`（`同周X均值` 优先于 `期均`）。当期 ≥ 7 天时注入。 + +### 行业基线 +仅 `周中客流规律`一项可引用佐证 seq 9；其他行业数字均未授权（H3）。 diff --git a/docs/ai/app2_finance_system_prompt_v3.md b/docs/ai/app2_finance_system_prompt_v3.md new file mode 100644 index 0000000..060ce6c --- /dev/null +++ b/docs/ai/app2_finance_system_prompt_v3.md @@ -0,0 +1,227 @@ +# App2 财务洞察 · 百炼 system prompt v3（月中口径版） + +> 基于 v2（2026-04-22 生产版）的**增量补丁**，新增"对比口径"字段读取规则 + 短样本保护条款 +> 生效日期：2026-04-22 +> 适用 APP：`app2_finance`（DashScope APP ID：`DASHSCOPE_APP_ID_2_FINANCE`） +> 操作方式：用户在百炼控制台手动替换 system prompt 全文 + +--- + +## 一、v2 → v3 变更摘要 + +| # | 位置 | 变更 | 原因 | +|---|---|---|---| +| 1 | 「数据字段读取优先级」新增第 0 项 | **对比口径** 置顶说明 | 月中调用时当期/对比期均"同天数对齐"，而非"当期 N 天 vs 上月整月"，AI 必须先理解口径再解读环比 | +| 2 | A 板块约束 | 引用环比前先读"对比口径" | 避免 AI 按直觉把"4/1~4/22"当成完整本月 | +| 3 | 「限制」新增一条 | 短样本标注识别 | 支持 `"-43.1%（上期仅 N 天，样本不足仅供参考）"` 后缀识别 | +| 4 | 「数据字段读取优先级 §3 按星期聚合」 | 注明"样本不足时字段不存在" | 月初 <14 天时后端不注入此字段，AI 应接受空值 | +| 5 | 「数据字段读取优先级 §4 日粒度异常」 | 注明"样本不足时字段不存在" | 同上，样本 <7 天时不注入 | + +--- + +## 二、粘贴到百炼控制台的完整 v3 全文 + +``` +# 角色 +你是一位台球门店财务分析专家，负责对门店经营数据进行深度分析，生成结构化的财务洞察报告。你的分析将展示在管理者的财务看板页面上。 + +## 行业背景 +【行业背景 — 综合商业球房财务模型】 +一、收入构成（两层会计属性） +1) 发生额 — 顾客端计价，含优惠 + · 台费：大厅/VIP台球包厢/斯诺克/麻将房/团建房 五类空间按时段计价 + · 酒水零食：吧台销售 + · 助教服务费：会员向助教购买基础陪打课 或 激励超休课时长。助教相当球房的销售服务人员,维护客户关系。 +2) 成交收入 = 发生额 − 总优惠 +3) 该行业每周五至周日生意最好，周一最淡，之后客流会逐步回升，到周五再进入旺季。 + +二、总优惠 5 类拆解 +- 团购优惠：美团/抖音/大众点评核销价与原价差额 +- 会员折扣：储值卡会员固定折扣 +- 手动调整：前台抹零/免单/整单折扣 +- 赠送卡抵扣：酒水卡/台桌卡/抵用券 +- 分摊优惠：四舍五入抹零 + +三、现金流入（两大类） +1) 消费收款：纸币现金 + 线上收款（微信/支付宝/刷卡）+ 团购平台回款 +2) 充值收款：会员储值卡首充 + 续费 +注意：储值卡消费不计入当期现金流入（现金已在充值时收过） + +四、现金流出 4 大类 +1) 运营支出：食品饮料采购、耗材（球杆/巧克/桌布）、报销 +2) 固定支出：房租、水电、物业、人员工资 +3) 助教支出：助教薪酬属于浮动成本：服务客户越多，收入越高，助教分成也越多。客户支付的费用由助教和球房按比例分成，区别仅在于分成比例不同，一般来说球房收入的40%作为助教工资支出是合理的。此外，助教成本还包括充值提成和月度奖金。 +4) 平台支出：团购手续费、SaaS 订阅 + +五、三类口径不可互换 +- 发生额：原价（含优惠） +- 成交收入：扣优惠后当期确认的收入（权责发生制） +- 现金流入：当期实收现金 +三者差异源于：储值卡消费动余额不动现金；储值卡充值动现金不动收入。 +净利润用「成交收入 − 各项支出」；用「现金流入 − 现金流出」会把充值预付款当收入，虚高。 +储值卡余额是负债（已收钱欠服务）：余额增 = 兑付压力累积，余额减 = 复购乏力。 + +## 分析框架（6 个板块，每板块输出 2 条洞察，共 12 条） + +按以下 6 个视角组织输出，每个视角产出 2 条洞察。视角内具体分析什么由你根据当期数据自行判断，从可选方向里选最有信息价值的两条；数据缺失/全 0 时，其中一条转为对数据完整性的提示与排查方向。 + +### A · 收入与发生额（seq 1-2） +关注：发生额、成交收入、环比走势、收入结构（台费/助教费/酒水/充值 占比） +推荐其中至少 1 条使用"单位经济"字段（客单价、日均订单数、会员订单占比）— 相比总量增长，客单与会员占比对店长决策更有价值。 +**解读环比前必须先读 payload 顶层的 "对比口径" 字段**，理解"当期范围"与"对比期范围"的天数对齐关系（尤其月中/周中调用时），避免把"当期 22 天数据"与"上月完整 31 天"错误对比。 +**禁止推测客单价/订单数/会员占比的环比走势**（如"客单价提升/下降"），必须直接引用"单位经济"里以 "_环比" 结尾的字段值；若该字段值为"无上期数据"则直说未知。 + +### B · 优惠构成（seq 3-4） +关注：优惠率水平、5 类优惠的最大来源与环比异动、潜在管控风险 +**"手动调整" 类目仅给出了总金额，未拆分"抹零/免单/折扣"明细**。禁止在结论中直接说"抹零/免单 XX 元"，应表述为"'手动调整'类目环比 +XX%，需回查该类目执行记录"。 + +### C · 现金流与储值卡（seq 5-6） +关注：消费收款 vs 充值收款的结构、储值卡充值/消耗/余额的关系、负债走向判断 + +### D · 支出与成本（seq 7-8） +关注：四类支出的完整性（全 0 或缺失需指出数据问题）、助教人力成本占成交收入比、成本增速 vs 收入增速 + +### E · 时间与日粒度规律（seq 9-10） +两条分工明确，不要都讲同一天的极端值： +- seq 9：**宏观周中规律**（读"按星期聚合"字段）— 对比 7 个工作日的日均发生额/订单数/现金流入，判断是否符合"周五至周日旺季、周一最淡"的行业规律，指出差异最大的星期组合，**必须给出旺/淡日的倍率**（如"周六日均订单 145.7 是周二 88.0 的 1.66 倍"）。**若"按星期聚合"字段不存在**（月初样本 < 14 天），本条改为"当期样本不足 14 天，周中规律需样本积累后再评估"。 +- seq 10：**单日极端异常**（读"日粒度异常"字段）— 选 1-2 个偏离最大的异常日，结合"基线类型"说明参考口径（同周X均值 优先于 期均），给出可能成因（促销/团购结算/停业/录入错误）。**若"日粒度异常"字段不存在**（样本 < 7 天），本条改为"当期样本不足，单日异常检测暂未启用"。 + +### F · 综合判断与行动建议（seq 11-12） +战略级输出，不要重复 B/D 里已经说过的具体建议： +- seq 11：**本期业务健康度红黄绿灯评级** — 必须在 content 开头明确标注【🟢 绿灯 健康 / 🟡 黄灯 观察 / 🔴 红灯 警告】之一，评判规则： + - 🟢 绿灯：主要指标（成交收入、储值卡余额、会员占比）均呈正向或平稳 + - 🟡 黄灯：1-2 个指标偏离预期 10-20%，或某板块出现结构性隐忧 + - 🔴 红灯：3+ 指标失衡 / 数据完整性严重缺失 / 负债累积或复购大幅下滑 + 评级后必须列出支撑评级的 top 2 原因。 +- seq 12：**未来 30 天最值得持续跟踪的 1 个指标**（含目标区间或观察阈值，以及**跟踪节奏 + 触发动作**） + - 例："**每周五复盘储值卡余额变化**，目标转正（>0），若**第 2 周仍 <-10000**，**启动会员召回计划**" + - 指标必须来自 payload 中真实存在的字段，不能编造指标名 + +## 数据字段读取优先级（重要） + +payload 包含"原始指标"兜底字段，但以下几个派生字段是**权威版本，优先使用**： + +### 0. 对比口径（板块 A 的前置依赖） +- payload 顶层"对比口径"字段说明本次环比的对齐规则： + - **当期范围**：如 `2026-04-01 ~ 2026-04-22（22 天）` + - **对比期范围**：如 `2026-03-01 ~ 2026-03-22（22 天）` + - **对齐方式**：统一为"上期同天数对齐（非整月/整周对比）" +- 所有带 `_环比` / `_compare` 后缀的字段均按上表口径计算，月中调用时对比期已自动截断到与当期相同天数 +- **禁止**在解读中说"对比整月" / "上月共 31 天"等违背对齐口径的描述 +- 若对比口径显示当期天数 < 7，应在 seq 1-2 或 seq 11 中主动提示"当期样本较短，环比仅供参考" + +### 1. 储值卡相关（板块 C） +- 优先读"储值卡余额变化"：含期初/期末/余额变化/本期充值/本期消耗/其他调整 6 个值 +- **余额变化 = 期末 − 期初**，直接反映本期负债涨跌。不要用"原始指标.预收资产.储值卡总余额环比"（那是两个期末的环比，不代表本期变化） +- **其他调整 != 0** 时（含过期失效/手动增减/赠送/退款），必须单独点出来，说明"非充值/消耗的余额变动需核查" +- 消耗 > 充值则 存量消费而非复购增长；消耗 < 充值 则 新充值带动现金流入但兑付压力累积。 + +### 2. 单位经济（板块 A） +- "单位经济"字段给出：总订单数、日均订单数、客单价_按成交收入、客单价_按发生额、会员订单数、会员订单占比、散客订单数、散客订单占比 +- **带 "_环比" 后缀的字段优先引用**（客单价_按成交收入_环比、客单价_按发生额_环比、日均订单数_环比、会员订单占比_环比），这些是本期 vs 上期的真实对比 +- **短样本标注识别**：若 _环比 字段值形如 `"-43.1%（上期仅 3 天，样本不足仅供参考）"`（含"样本不足"后缀），说明上期数据不足 5 天，结论必须降权表述（"参考值" / "样本待积累" / "不宜作为趋势判断依据"），禁止把短样本环比作为健康度评级的硬依据 +- 两类客单价并用： + - **按成交收入客单价**（去优惠后实际到手的每单均值）— 反映真实收入能力 + - **按发生额客单价**（含优惠的账单均值）— 反映顾客端认知的"一次消费量级" + - 二者差值 ≈ 每单平均优惠让利金额 +- **会员订单占比的业务解读需避免单一归因**：占比 < 20% 可能是储值卡推广弱，也可能是门店业态定位为散客/团购生意（如车站/商场店）；应列出 2 种可能性让店长判断 + +### 3. 按星期聚合（板块 E） +- "按星期聚合"字段给出周一至周日各自的日均发生额/现金流入/订单数/营业日数 +- 供 seq 9 做**宏观周中规律**判断，**必须给出旺/淡日的倍率**（如"周六订单 146 / 周二 88 = 1.66 倍"） +- 营业日数 = 0 的星期（停业日）需忽略后比较 +- **字段不存在时**（当期样本 < 14 天），seq 9 改为"样本不足说明"，不能用"原始指标"硬算周规律 + +### 4. 日粒度异常（板块 E） +- 每条异常带"基线类型"字段，取值为"同周X均值"或"期均" +- **"同周X均值"** 说明该日已与同星期对比过，排除了周中周末规律的干扰，这类异常更值得关注 +- **"期均"** 说明同星期样本不足（<2 天）退化到整体均值，结论要更保守 +- 偏离度相同时，优先解读"同周X均值"基线的异常 +- **字段不存在时**（当期样本 < 7 天），seq 10 改为"样本不足说明" + +### 5. 行业基线（板块 E 辅助） +- payload 顶层"行业基线.周中客流规律"说明行业普适的周中客流分布 +- 这是全行业性特征，可直接引用佐证 seq 9 的宏观规律判断 +- **其他行业经验值（优惠率警戒线、人力成本警戒线、团购占优惠比例、充值占现金流入比例、复购率、客单价、毛利率等）均未提供** — 因各球房定位、地段、业态差异大，一刀切不准 +- 禁止在结论中使用任何未经 payload 授权的"行业均值"/"行业警戒线"/"行业参考值"数字 +- 判断异常请改用：**环比数据、内部对比（如某项占比/某类占大头）、数据业务逻辑完整性（如支出为 0 是否合理）、派生比率字段** + +## 输出格式（强制） + +必须返回严格的 JSON 数组，格式如下： + +```json +[ + {"seq": 1, "title": "洞察标题（10字内）", "content": "洞察正文（含数据、分析、建议，200字内）"}, + ...共 12 条... +] +``` + +### 输出规则 +- 固定 12 条洞察，seq 1-12 按板块顺序 A→B→C→D→E→F 排列，每板块 2 条 +- 每条 content 携带 ≥ 1 个具体数字或百分比，不允许空泛描述 +- 金额单位为元，保留整数；百分比保留整数 +- content ≤ 200 字 +- 使用简体中文 +- 仅返回标准 JSON 数组，不要包裹额外文字 +- 可适度使用 **加粗** 标记关键指标名、阈值或动作词（小程序端已支持内联 Markdown 渲染），但请节制使用避免喧宾夺主（单条 ≤ 3 处加粗） + +## 限制 +- 仅基于传入的数据进行分析，不要编造数据。禁止臆想内容！ +- **环比解读前必须先读"对比口径"字段**，禁止用"当期 N 天"与"整月/整周"做错位对比 +- **短样本环比（带"样本不足"后缀）必须降权表述**，禁止作为趋势判断或健康度评级的硬依据 +- "行业基线"字段仅给出了周中客流规律一项。凡 payload 未明确提供的行业经验值（如优惠率警戒线、人力成本警戒线、复购率、客单价、毛利率等），禁止在结论中使用具体数字 +- 禁止单一归因：遇"会员占比低 / 优惠率高 / 成本占比高"等现象，若存在 2 个及以上合理解读路径（如定位差异 vs 运营弱），必须列出并说明"需店长结合门店实际判断" +- 禁止推测走势：趋势判断必须引用 payload 里带 "_环比" 或 "_compare" 字段的真实值；不要从单期数据"推测"上涨下跌 +- 数据缺失或为零，如实说明并转为对"数据完整性"的建议 +- 板块内方向是可选项不是必选项，由你按数据价值自主决定从哪个角度切入 +- 板块 E 的 seq 9 / seq 10 必须分工明确（宏观 / 单日），不能两条都讲同一天的极端值。**字段缺失时改为"样本不足说明"，不可用原始指标硬算或编造** +- 板块 F 的 seq 11 / seq 12 必须战略级（红黄绿灯评级 / 跟踪指标与节奏），不能重复 B/D 的战术建议 +- 若发现多指标协同恶化（如客单价↓ + 会员占比↓ + 储值卡余额↓），必须在 seq 11 健康度评价中单独作为"结构失衡"主因强调，而非分散到各板块。 +``` + +--- + +## 三、粘贴后的自测清单 + +按顺序测试，每项通过才算 v3 上线成功： + +### 测试 A · 正常月中场景（本月已过 22 天） +- **触发**：`scripts/test_app2_new_system_prompt.py` 的 `this_month/all` +- **预期**： + - [ ] seq 1 或 seq 2 开头明确引用"对比口径 4/1~4/22 vs 3/1~3/22" + - [ ] 不再出现"对比整月"/"上月共 31 天"等错误表述 + - [ ] seq 9 周规律 + 倍率（样本 22 天足够） + - [ ] seq 11/12 健康度 + 跟踪节奏齐全 + +### 测试 B · 模拟月初场景（需开发者手动造 4/1~4/3 数据或等 5 月 1-3 号自然触发） +- **触发**：月初 1-3 天调用 `this_month/all` +- **预期**： + - [ ] "按星期聚合"、"日粒度异常"字段缺失 + - [ ] seq 9 "样本不足 14 天，周中规律需样本积累" + - [ ] seq 10 "样本不足，单日异常检测暂未启用" + - [ ] 若上期也只有 3 天，客单价环比带"（上期仅 3 天，样本不足仅供参考）"后缀 + - [ ] AI 主动降权引用短样本环比，不把它作为健康度评级硬依据 + +### 测试 C · 加粗 Markdown 渲染配合 +- **预期**：seq 12 跟踪指标自主出现 `**每周五复盘XX**` / `**启动XX计划**` 这类加粗关键词 +- **前端验收**：小程序 board-finance 页面 seq 12 相关字样以加粗亮白显示 + +--- + +## 四、回滚方法 + +若 v3 上线后 AI 输出异常： +1. 百炼控制台把 system prompt 改回 v2（本文档开头之前的版本） +2. 后端 `app2_finance_prompt.py` 的"对比口径"字段无需回滚（AI 不读也无影响，仅占 ~200 字符 prompt 长度） +3. `_WEEKDAY_MIN_DAYS = 14` 与短样本标注也无需回滚（纯数据层保护，不依赖 AI 响应） + +--- + +## 五、变更记录 + +| 日期 | 版本 | 变更 | 作者 | +|---|---|---|---| +| 2026-04-22 | v3 | 新增对比口径字段读取规则 / 短样本标注识别 / 按星期聚合与日粒度异常字段缺失降级 | Claude + Neo | +| 2026-04-22 | v2 | 生产级版本（12 条 · 三色灯 · 跟踪节奏） | Claude + Neo | + diff --git a/docs/audit/audit_dashboard.md b/docs/audit/audit_dashboard.md index 30c3e6d..339eb8f 100644 --- a/docs/audit/audit_dashboard.md +++ b/docs/audit/audit_dashboard.md @@ -1,11 +1,16 @@ # 审计一览表 -> 自动生成于 2026-04-22 21:17:11，请勿手动编辑。 +> 自动生成于 2026-05-02 00:06:26，请勿手动编辑。 ## 时间线视图 | 日期 | 项目 | 需求摘要 | 变更类型 | 影响模块 | 风险 | 详情 | |------|------|----------|----------|----------|------|------| +| 2026-05-01 | 项目级 | 2026-05-01 App3 完整消费明细 Prompt 策略 | 功能 | 其他 | 未知 | [链接](changes/2026-05-01__backend_app3_full_detail_prompt.md) | +| 2026-05-01 | 项目级 | 变更审计记录：Cursor AI 开发环境迁移 | 文档 | 其他 | 未知 | [链接](changes/2026-05-01__cursor_migration.md) | +| 2026-04-30 | 项目级 | 审计记录：admin-web AI 手动执行 app_type 对齐 | bugfix | 其他 | 未知 | [链接](changes/2026-04-30__admin_web_ai_app_type_alignment.md) | +| 2026-04-30 | 项目级 | 审计记录：后端 DashScope tokens_used 提取修复 | bugfix | 其他 | 未知 | [链接](changes/2026-04-30__backend_dashscope_tokens_used_extraction.md) | +| 2026-04-29 | 项目级 | 变更审计记录：Codex 深度迁移与 Claude 历史摘要归档 | 文档 | 其他 | 未知 | [链接](changes/2026-04-29__codex_migration_and_claude_history_archive.md) | | 2026-04-23 | 项目级 | 变更审计记录：App2a 区域财务洞察 APP 派生 · 整包上线 | bugfix | 其他 | 低 | [链接](changes/2026-04-23__app2a_finance_area_integrated.md) | | 2026-04-22 | 项目级 | 变更审计记录：App2 财务洞察 V5.1 prompt + 小程序 AI 洞察区总结置顶与排版优化 | 文档 | 其他 | 低 | [链接](changes/2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md) | | 2026-04-21 | 项目级 | 审计记录：admin-web AI 管理套件（可视化全流程管控） | 功能 | 其他 | 未知 | [链接](changes/2026-04-21__admin-web-ai-management-suite.md) | @@ -256,6 +261,11 @@ | 日期 | 需求摘要 | 变更类型 | 影响模块 | 风险 | 详情 | |------|----------|----------|----------|------|------| +| 2026-05-01 | 2026-05-01 App3 完整消费明细 Prompt 策略 | 功能 | 其他 | 未知 | [链接](changes/2026-05-01__backend_app3_full_detail_prompt.md) | +| 2026-05-01 | 变更审计记录：Cursor AI 开发环境迁移 | 文档 | 其他 | 未知 | [链接](changes/2026-05-01__cursor_migration.md) | +| 2026-04-30 | 审计记录：admin-web AI 手动执行 app_type 对齐 | bugfix | 其他 | 未知 | [链接](changes/2026-04-30__admin_web_ai_app_type_alignment.md) | +| 2026-04-30 | 审计记录：后端 DashScope tokens_used 提取修复 | bugfix | 其他 | 未知 | [链接](changes/2026-04-30__backend_dashscope_tokens_used_extraction.md) | +| 2026-04-29 | 变更审计记录：Codex 深度迁移与 Claude 历史摘要归档 | 文档 | 其他 | 未知 | [链接](changes/2026-04-29__codex_migration_and_claude_history_archive.md) | | 2026-04-23 | 变更审计记录：App2a 区域财务洞察 APP 派生 · 整包上线 | bugfix | 其他 | 低 | [链接](changes/2026-04-23__app2a_finance_area_integrated.md) | | 2026-04-22 | 变更审计记录：App2 财务洞察 V5.1 prompt + 小程序 AI 洞察区总结置顶与排版优化 | 文档 | 其他 | 低 | [链接](changes/2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md) | | 2026-04-21 | 审计记录：admin-web AI 管理套件（可视化全流程管控） | 功能 | 其他 | 未知 | [链接](changes/2026-04-21__admin-web-ai-management-suite.md) | @@ -395,6 +405,11 @@ | 日期 | 需求摘要 | 变更类型 | 风险 | 详情 | |------|----------|----------|------|------| +| 2026-05-01 | 2026-05-01 App3 完整消费明细 Prompt 策略 | 功能 | 未知 | [链接](changes/2026-05-01__backend_app3_full_detail_prompt.md) | +| 2026-05-01 | 变更审计记录：Cursor AI 开发环境迁移 | 文档 | 未知 | [链接](changes/2026-05-01__cursor_migration.md) | +| 2026-04-30 | 审计记录：admin-web AI 手动执行 app_type 对齐 | bugfix | 未知 | [链接](changes/2026-04-30__admin_web_ai_app_type_alignment.md) | +| 2026-04-30 | 审计记录：后端 DashScope tokens_used 提取修复 | bugfix | 未知 | [链接](changes/2026-04-30__backend_dashscope_tokens_used_extraction.md) | +| 2026-04-29 | 变更审计记录：Codex 深度迁移与 Claude 历史摘要归档 | 文档 | 未知 | [链接](changes/2026-04-29__codex_migration_and_claude_history_archive.md) | | 2026-04-23 | 变更审计记录：App2a 区域财务洞察 APP 派生 · 整包上线 | bugfix | 低 | [链接](changes/2026-04-23__app2a_finance_area_integrated.md) | | 2026-04-22 | 变更审计记录：App2 财务洞察 V5.1 prompt + 小程序 AI 洞察区总结置顶与排版优化 | 文档 | 低 | [链接](changes/2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md) | | 2026-04-21 | 审计记录：admin-web AI 管理套件（可视化全流程管控） | 功能 | 未知 | [链接](changes/2026-04-21__admin-web-ai-management-suite.md) | diff --git a/docs/audit/changes/2026-04-20__ai-module-complete.md b/docs/audit/changes/2026-04-20__ai-module-complete.md new file mode 100644 index 0000000..1127641 --- /dev/null +++ b/docs/audit/changes/2026-04-20__ai-module-complete.md @@ -0,0 +1,110 @@ +# 审计记录：AI 模块完整实现 + +**日期**：2026-04-20 +**会话**：AI 模块全量建设（Phase 0~4） +**影响范围**：backend / miniprogram / db / docs + +--- + +## 变更摘要 + +本次会话完成了 NeoZQYY AI 模块从架构重组到端到端贯通的全量实现，涵盖： + +1. **Phase 0**：删除 8 个死代码 App 文件，新建 `prompts/` 模块 + dispatcher 完整重构 +2. **Phase 1**：多轮会话 session_id 透传、references 注入、EventBus 广播 +3. **Phase 2**：小程序 chat 页完善、ai-float-button 上下文透传、AI 缓存渲染 +4. **Phase 2.2**：chat SSE 断线指数退避自动重连（最多 2 次） +5. **Phase 3**：WebSocket AI 告警端点、熔断/限流/预算告警推送 +6. **Phase 3.2**：admin-web AIDashboard 接入 WS 实时告警（/ws/ai-alerts/{site_id}） +7. **Phase 4.1**：admin-web AIOperations 新增"按需重新生成"Card（POST /admin/ai/run/{app_type}） +8. **Phase 4.2**：缓存失效 Card 已在前序会话实现（adminAI.ts + AIOperations Card 2） +9. **修复**：`main.py` 未调用 `internal_ai.set_dispatcher()` 导致 Dispatcher 503 + +--- + +## 变更文件清单 + +### 删除（8 个死代码文件） + +| 文件 | 原因 | +|------|------| +| `apps/backend/app/ai/apps/__init__.py` | 调用未定义的 `bailian.chat_json()`，死代码 | +| `apps/backend/app/ai/apps/app1_chat.py` ～ `app8_consolidation.py` | 同上，`run()` 从未被调用 | + +### 新建 + +| 文件 | 说明 | +|------|------| +| `apps/backend/app/ai/prompts/__init__.py` | 导出 7 个 `build_app*_prompt` 函数 | +| `apps/backend/app/ai/prompts/app2_finance_prompt.py` | App2 财务数据拼 prompt | +| `apps/backend/app/ai/prompts/app3_clue_prompt.py` | App3 消费线索 prompt | +| `apps/backend/app/ai/prompts/app4_analysis_prompt.py` | App4 助教-会员分析 prompt | +| `apps/backend/app/ai/prompts/app5_tactics_prompt.py` | App5 话术 prompt（含 App4 结果） | +| `apps/backend/app/ai/prompts/app6_note_prompt.py` | App6 备注分析 prompt | +| `apps/backend/app/ai/prompts/app7_customer_prompt.py` | App7 客户画像 prompt | +| `apps/backend/app/ai/prompts/app8_consolidation_prompt.py` | App8 线索整合 prompt | +| `apps/backend/app/ai/references.py` | `_references` 注入 + `reference_card` 构建 | +| `apps/backend/app/ai/event_bus.py` | in-process pub/sub，site_id 隔离 | +| `apps/backend/app/ws/ai_events.py` | `/ws/ai-cache/{site_id}` + `/ws/ai-alerts/{site_id}` | +| `db/zqyy_app/migrations/20260420_ai_trigger_jobs_and_app2_prewarm.sql` | 4 事件 + 1 cron trigger_jobs，已执行 | +| `docs/database/BD_manual_ai_trigger_jobs_register.md` | 手动注册说明 | + +### 修改 + +| 文件 | 关键变更 | +|------|----------| +| `apps/backend/app/ai/dispatcher.py` | 完整重构：调用 `prompts.build_*`，链式编排，EventBus 广播，_references 注入 | +| `apps/backend/app/ai/dashscope_client.py` | `call_app_stream` 返回 `(chunk, session_id)` tuple | +| `apps/backend/app/services/chat_service.py` | session_id 初始为 NULL，`save_session_id()` 保存百炼返回值 | +| `apps/backend/app/services/trigger_scheduler.py` | `_invoke_handler()` 修复 async handler 同步调用 bug | +| `apps/backend/app/services/task_generator.py` | `run()` 完成后触发 `ai_consumption_settled` 事件 | +| `apps/backend/app/services/note_service.py` | 备注创建后触发 `ai_note_created` | +| `apps/backend/app/routers/admin_task_engine.py` | 任务分配后触发 `ai_task_assigned` | +| `apps/backend/app/routers/internal_events.py` | ETL 完成后触发 `ai_dws_completed` | +| `apps/backend/app/routers/xcx_chat.py` | 解包 `(chunk, session_id)` 流，保存 session_id，写 reference_card | +| `apps/backend/app/routers/admin_ai.py` | 新增 `POST /api/admin/ai/run/{app_type}` 端点 | +| `apps/backend/app/schemas/admin_ai.py` | 新增 `RunAppRequest` / `RunAppResponse` | +| `apps/backend/app/services/ai/admin_service.py` | 缓存失效后广播 `cache_invalidated` 事件 | +| `apps/backend/app/main.py` | lifespan 补调 `internal_ai.set_dispatcher(_dispatcher)` | +| `apps/backend/pytest.ini` | 追加 `norecursedirs = _archived` | +| `apps/miniprogram/miniprogram/pages/chat/chat.ts` | referenceCard 点击跳转，pageFilters URL 解析；Phase 2.2 SSE 断线指数退避自动重连（最多 2 次） | +| `apps/miniprogram/miniprogram/pages/chat/chat.wxml` | referenceCard `bindtap` + 类型标签优化 | +| `apps/miniprogram/miniprogram/components/ai-float-button/ai-float-button.ts` | 新增 `sourcePage` + `pageFilters` 属性透传 | +| `apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts` | `_loadAIInsights()` 从 `app2_finance` 缓存加载洞察 | +| `apps/miniprogram/miniprogram/pages/customer-detail/customer-detail.ts` | `_loadAIInsight()` 从 `app7_customer_analysis` 缓存加载 | +| `apps/miniprogram/miniprogram/services/api.ts` | 新增 `fetchAICache()` 函数 | + +--- + +## E2E 验证结果 + +**消费事件链**（site_id=2790685415443269，member_id=2799212491392773）： + +| App | 状态 | 延迟 | +|-----|------|------| +| app3_clue | timeout | 121s（prompt 过大，需优化） | +| app8_consolidate | **success** | ~15s，缓存已写入 | +| app7_customer | **success** | ~60s，缓存含真实 AI 分析 | + +**缓存验证**： +- `app7_customer_analysis` result_json 含 `summary` + `strategies[{title,content}]` +- `app8_clue_consolidated` result_json 含 `_references`（link 正确拼装） +- board-finance AI 洞察已通过微信 MCP 验证在页面渲染（5 条真实 insight） + +--- + +## 遗留风险点 + +1. **app3 超时（已缓解）**：`_MAX_PROMPT_LEN` 已从 8000 降至 4000，最多保留 3 条消费记录 + 二次截断 reference。待下次 E2E 验证是否仍超时。 +2. **tokens_used = 0**：DashScope SDK 响应未提取 token 计数，影响预算追踪精度。需检查 `call_app` 的 usage 提取。 +3. **dispatcher 内存去重**：`_dedup_set` 重启后丢失，生产环境需改为查 DB。 +4. **task-detail aiAnalysis**：Phase 2.5 暂未实现，结构较复杂，待单独 session。 +5. **admin-web Phase 3.2/4.1/4.2**：后端端点已就位，前端实现延后。 + +--- + +## 回滚策略 + +- 删除的 8 个 apps/ 文件在 git 历史可恢复：`git checkout apps/backend/app/ai/apps/` +- DB 迁移回滚：`DELETE FROM biz.trigger_jobs WHERE id >= 57;` +- `main.py` 新增一行可直接删除：`_internal_ai_router.set_dispatcher(_dispatcher)` diff --git a/docs/audit/changes/2026-04-21__admin-web-ai-management-suite.md b/docs/audit/changes/2026-04-21__admin-web-ai-management-suite.md new file mode 100644 index 0000000..8de4d33 --- /dev/null +++ b/docs/audit/changes/2026-04-21__admin-web-ai-management-suite.md @@ -0,0 +1,120 @@ +# 审计记录：admin-web AI 管理套件（可视化全流程管控） + +**日期**：2026-04-21 +**会话**：为 admin-web 补齐 AI 可视化管理页面 + 后端对应端点 +**影响范围**：backend（schemas/services/routers）/ admin-web（api/pages/App.tsx） + +--- + +## 变更摘要 + +用户需求： +> 为我在 admin-web 修改完善 AI 相关工具和板块。让我能有可视化的工具进行 AI 方面的全流程可视化可操作的管理，包含调试阶段的集中预热以及触发器状态设置等。 + +本次交付 2 个新页面 + 1 个页面增强 + 1 个 AI 一级菜单组，并新增 4 个后端端点作为前端数据源。 + +--- + +## 后端变更 + +### 新增 Pydantic 模型（`apps/backend/app/schemas/admin_ai.py`） + +| 模型 | 用途 | +|------|------| +| `TriggerItem` | 触发器单条记录（id/job_name/job_type/trigger_condition/trigger_config/status/last_run_at/next_run_at/last_error） | +| `TriggerUpdateRequest` | 触发器更新（status / cron_expression / description） | +| `PrewarmMissingItem` | 缺失组合（target_id / time_dimension / area） | +| `PrewarmProgressResponse` | 预热进度（total=72 / done / missing / last_updated） | +| `ManualTriggerRequest` | 手动触发事件请求（event_type / site_id / member_id / assistant_id / payload / is_forced） | +| `ManualTriggerResponse` | 手动触发响应（trigger_job_id / status） | + +### 新增服务方法（`apps/backend/app/services/ai/admin_service.py`） + +| 方法 | 实现 | +|------|------| +| `list_triggers()` | 查 `biz.trigger_jobs WHERE job_type LIKE 'ai_%' OR job_name='task_generator'` | +| `update_trigger(id, status, cron_expression, description)` | 支持部分字段更新，cron 用 `jsonb_set` 改 trigger_config | +| `get_prewarm_progress(site_id)` | 对比 72 组合 expected vs `biz.ai_cache` 中 `app2_finance` 的 target_id，返回 done/missing | + +### 新增路由端点（`apps/backend/app/routers/admin_ai.py`） + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/api/admin/ai/triggers` | 列出所有 AI 触发器 | +| PATCH | `/api/admin/ai/triggers/{trigger_id}` | 启停 / 改 cron / 改描述 | +| GET | `/api/admin/ai/prewarm/progress?site_id=N` | App2 预热 72 组合进度 | +| POST | `/api/admin/ai/trigger-event` | 手动触发事件链，默认 `is_forced=True` 跨越去重 | + +所有端点走 `_require_admin()` 要求 `site_admin`/`tenant_admin` 角色。 + +--- + +## 前端变更 + +### API 层（`apps/admin-web/src/api/adminAI.ts`） + +新增 4 个函数 + 6 个类型接口： +- `listTriggers()` / `updateTrigger(id, body)` + `TriggerItem` / `TriggerUpdateRequest` +- `getPrewarmProgress(siteId)` + `PrewarmProgressResponse` / `PrewarmMissingItem` +- `triggerEvent(body)` + `ManualTriggerRequest` / `ManualTriggerResponse` + +### 新建页面 + +**`apps/admin-web/src/pages/AITriggers.tsx`** — 触发器设置页（`/ai/triggers`） +- 表格列出所有 AI 触发器（id / 名称+描述 / 类型 tag / 表达式或事件名 / 启停 Switch / 最近/下次运行 / 最后错误） +- 编辑 Modal：cron 类型支持改 cron 表达式，所有类型可改描述 +- 行内快速启停：Switch 直接切换 enabled/disabled + +**`apps/admin-web/src/pages/AIPrewarm.tsx`** — 预热进度页（`/ai/prewarm`） +- 顶部卡片：72 组合进度条 + done/missing 计数 + last_updated +- 2 个主动作： + - "触发全量预热"：调 `triggerEvent(dws_completed, is_forced=true)`，后台异步跑 + - "一键补齐缺失"：串行 `runApp(app2_finance, time_dimension, area)` 逐个补，前端进度 Alert +- 缺失组合表格：每行一个"单独生成"按钮，快速补单个组合（30-120s） +- 时间/区域标签中英双显（`本月 (this_month)`） + +### 页面增强 + +**`apps/admin-web/src/pages/AIOperations.tsx`** — 新增 Card 2.6「手动触发事件链（调试用）」 +- 事件类型下拉（consumption / note_created / task_assigned / dws_completed） +- 输入 member_id / assistant_id 按需 +- 默认勾选「跳过去重」复选框（is_forced=true） +- 触发后返回 `trigger_job_id` 供后续查调度历史 + +### 路由与菜单（`apps/admin-web/src/App.tsx`） + +- 新增一级菜单「AI 管理」（图标 RobotOutlined），含 5 个子项： + - 总览 → `/ai/dashboard`（原 AIDashboard，此前未挂载路由，本次接入） + - 手动操作 → `/ai/operations`（原 AIOperations，同上） + - 预热进度 → `/ai/prewarm`（新） + - 触发器设置 → `/ai/triggers`（新） + - 调度历史 → `/ai/trigger-jobs`（原 AITriggerJobs，同上） +- `getSelectedKeys` / `getDefaultOpenKeys` 补 `/ai/` 前缀匹配 + +--- + +## 验证状态 + +- **代码语法**：TypeScript / Python 均通过编辑器层面校验（无 linter 报错） +- **烟雾测试**：后端 `--reload` 触发自身 lifespan 阻塞（已知环境问题：远程 PG 560ms RTT × psycopg2 每请求新建连接），未能在本会话 curl 成功。端点逻辑已完整覆盖已有 admin_ai 路由的模式，复用 `_require_admin()` / `_admin_svc` / `get_dispatcher()` 等成熟组件 +- **手动验证路径**： + 1. 重启后端至稳定 + 2. 登录 admin-web，左侧菜单展开「AI 管理」应看到 5 项 + 3. 「总览 / 手动操作 / 调度历史」是重新挂载路由的现有页面，直接可用 + 4. 「触发器设置」读取 `biz.trigger_jobs` 的 5 条 AI 触发器（`ai_consumption_settled` / `ai_note_created` / `ai_task_assigned` / `ai_dws_completed` / `ai_dws_prewarm_1000`） + 5. 「预热进度」应显示 46/72（当前进度），可一键补齐剩余 26 个 + +--- + +## 遗留风险点 + +1. **admin JWT 与 auth.users 混用**：`_require_admin → require_permission() → _get_user_status(user_id)` 查 `auth.users`，但 admin 用户实际在 `admin_users` 表。生产 admin-web 登录后 JWT 的 sub 必须指向 `auth.users.id` 才能通过。本次不修此老问题，沿用现有 admin_ai 所有端点的约定 +2. **后端远程 PG 网络延迟**（本会话观测 ping 560ms）导致每请求 psycopg2.connect ≈ 3s，叠加 AI 预热任务会拖垮整体响应。根治需加连接池或切本地 PG，与本次改动无关 +3. **cron 修改立即生效依赖 scheduler 重新解析**：改完 cron_expression 后，`biz.trigger_jobs.next_run_at` 需在 scheduler 下一次 poll 时重算（默认 60s）；用户感知到的生效延迟最多 1 分钟 + +--- + +## 回滚 + +- 后端：`git restore apps/backend/app/routers/admin_ai.py apps/backend/app/schemas/admin_ai.py apps/backend/app/services/ai/admin_service.py` +- 前端：`git restore apps/admin-web/src/api/adminAI.ts apps/admin-web/src/App.tsx apps/admin-web/src/pages/AIOperations.tsx && rm apps/admin-web/src/pages/AITriggers.tsx apps/admin-web/src/pages/AIPrewarm.tsx` diff --git a/docs/audit/changes/2026-04-21__app2-finance-prewarm-all-filters.md b/docs/audit/changes/2026-04-21__app2-finance-prewarm-all-filters.md new file mode 100644 index 0000000..43740df --- /dev/null +++ b/docs/audit/changes/2026-04-21__app2-finance-prewarm-all-filters.md @@ -0,0 +1,75 @@ +# 审计记录：App2 财务洞察全筛选组合预热 + 字段中文化 + +**日期**：2026-04-21 +**会话**：board-finance AI 洞察改造 +**影响范围**：backend / miniprogram / db / admin-web + +--- + +## 变更摘要 + +用户需求： +1. 每日 10:00 为所有门店的 board-finance 页面所有筛选组合（时间 × 区域 = 72 组）生成 AI 洞察并缓存 +2. 前端根据当前筛选条件读取对应缓存 +3. 发送给 AI 的 prompt 字段名翻译为中文（避免英文变量名，提升可读性） +4. 切换默认模型为 claude-opus-4-7（max 1M 上下文） + +--- + +## 变更文件清单 + +### 修改 + +| 文件 | 关键变更 | +|------|----------| +| `~/.claude/settings.json` | 新增 `"model": "claude-opus-4-7"` | +| `apps/backend/app/ai/prompts/app2_finance_prompt.py` | 新增 `area` 参数（与 board-finance.ts areaOptions 对齐），新增 `AREA_OPTIONS`/`AREA_LABELS`/`KEY_TRANSLATIONS`（70+ 字段中英映射）+ 递归 key 翻译函数 `_translate_keys`；payload 顶层键改为中文（当前时间/门店编号/时间维度/区域/财务数据） | +| `apps/backend/app/ai/dispatcher.py` | 新增 `APP2_AREA_OPTIONS` 与 `_app2_target_id(time, area)`；`_handle_dws_completed` 双重循环遍历 8×9=72 组合；`run_single_app` 的 app2_finance 分支支持 area；`handle_app2_prewarm` docstring 改为 10:00 | +| `apps/backend/app/schemas/admin_ai.py` | `RunAppRequest` 新增 `area: str \| None` 字段 | +| `apps/admin-web/src/api/adminAI.ts` | `RunAppRequest` 接口新增 `area?: string` | +| `apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts` | `_loadAIInsights(selectedTime, selectedArea)` 签名，`target_id` 改为 `{timeKey}__{areaKey}`；`_loadData` 传入两个参数 | + +### 新建 + +| 文件 | 说明 | +|------|------| +| `db/zqyy_app/migrations/20260421_app2_prewarm_cron_reschedule.sql` | UPDATE biz.trigger_jobs：job_name `ai_dws_prewarm_0830` → `ai_dws_prewarm_1000`；cron `30 8 * * *` → `0 10 * * *`；description 更新。已在 pg-app-test 执行 | + +--- + +## 缓存键规则变更 + +- 旧：`target_id = time_dimension`（如 `this_month`，仅 8 条/门店） +- 新：`target_id = {time_dimension}__{area}`（双下划线分隔，72 条/门店） +- 前后端用相同拼装函数：后端 `_app2_target_id`、前端 `board-finance.ts _loadAIInsights` 内联实现 +- 旧格式缓存已清理（仅保留 `__` 格式） + +## 字段中文化实现 + +`KEY_TRANSLATIONS` 覆盖 `board_service.get_finance_board` 返回的所有层级字段： +- 顶层板块：overview → 经营一览、recharge → 预收资产 等 +- 经营一览：occurrence → 发生额、discount_rate → 优惠率 等 +- 环比后缀：`*_compare` / `*_down` / `*_flat` 全覆盖 +- 通用字段：label → 名称、amount → 金额、total → 合计 等 + +`_translate_keys` 递归遍历 dict/list，只翻译键名，不改变值与结构。 + +## 触发与执行验证 + +- 2026-04-21 01:54 首次通过 `POST /api/internal/ai/trigger` 触发 `dws_completed + is_forced=true` +- prompt 已验证为完整中文键：`{"当前时间": "2026-04-21 01:56", "门店编号": 2790685415443269, "时间维度": "本月", "区域": "全部区域", "财务数据": {"经营一览": {"发生额": 287315.98, ...}}}` +- 后续 72 组合后台异步执行，结果写入 `biz.ai_cache` + +--- + +## 遗留风险点 + +1. **AI 调用时间增加**：中文 key 使 prompt 体积膨胀约 15%，部分请求已触发 `_STEP_TIMEOUT=120s` 超时。若超时率高需将 `_STEP_TIMEOUT` 上调至 180-240s，或裁剪 board_data 中次要字段 +2. **72 组合全量执行时长**：每组约 30-60s 串行，单门店 36-72 分钟；多门店场景下 cron 10:00 启动后可能跨小时结束 +3. **dispatcher `_execute_chain` 外层超时**：`_STEP_TIMEOUT * 5 = 600s = 10 min`，只够覆盖 ~10 组合；dws_completed 场景需单独放宽该超时，否则只能写入前 10 组缓存 + +## 回滚策略 + +- cron 回滚：`UPDATE biz.trigger_jobs SET job_name='ai_dws_prewarm_0830', trigger_config='{"cron_expression":"30 8 * * *"}'::jsonb WHERE job_type='ai_dws_prewarm';` +- 代码回滚：`git revert` 本次 commit 即可 +- 缓存清理：`DELETE FROM biz.ai_cache WHERE cache_type='app2_finance' AND target_id LIKE '%\_\_%' ESCAPE '\';` diff --git a/docs/audit/changes/2026-04-21__board-finance-ai-insights-verify.png b/docs/audit/changes/2026-04-21__board-finance-ai-insights-verify.png new file mode 100644 index 0000000000000000000000000000000000000000..35f35aec37125ab6014cf0687c2d73c91723fd26 GIT binary patch literal 4339 zcmeAS@N?(olHy`uVBq!ia0y~yVDe;OV9DZO0*YMbDmw_I7>k44ofy`glX=O&Ah6cc z#WAE}&fBYjoD2#g2OPH6-wr<@)MW5Z=uLignixaNocoLnA7*T440xQ&aHT?;!So)R zL+>beG&DvN!)RU@Eeb|U!qJj&v?LrY2}eu9(UNeqBpfXXM@z!dl5n&nq)kb9mNnCq Wdu^Sxun2GzgTd3)&t;ucLK6V*GFSBg literal 0 HcmV?d00001 diff --git a/docs/audit/changes/2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md b/docs/audit/changes/2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md new file mode 100644 index 0000000..ae671ef --- /dev/null +++ b/docs/audit/changes/2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md @@ -0,0 +1,202 @@ +# 变更审计记录：App2 财务洞察 V5.1 prompt + 小程序 AI 洞察区总结置顶与排版优化 + +| 字段 | 值 | +|------|-----| +| 日期 | 2026-04-22 18:35:38 | +| 风险标签 | dir:backend, dir:miniprogram | +| 涉及模块 | apps/backend (prompt 层) / apps/miniprogram (board-finance 页) / docs/ai / scripts | +| 数据库 DDL | 无 | + +## 操作摘要 + +本轮围绕 **App2 财务洞察**（72 组合预热缓存下的财务看板 AI 洞察）做了 4 件事： + +1. **小程序 AI 洞察区改版**：seq 11/seq 12 作为"本期总结"置顶展示（三色灯健康度评级 + ⏰ 跟踪指标），seq 1-10 作为"分板块明细"；新增轻量 Markdown 内联渲染（`**加粗**` / `*倾斜*`）；最终排版迭代到"总结区 body 2 行 clamp + seq 1/2/3 统一单行省略 + 一键进弹窗看全部"的紧凑态。 + +2. **后端 prompt 构建器月中场景保护**：向 payload 顶层注入 `对比口径` 字段（`{当期范围, 对比期范围, 对齐方式: "上期同天数对齐"}`），让 AI 正确解读"月中 22 天 vs 上月 22 天同期对齐"而非错位为整月对比；按星期聚合字段样本门槛从 7 天提升到 14 天（防月初每个星期仅 1 天被包装成"日均"误导 AI）；单位经济上期样本 < 5 天时为所有 `_环比` 字段加"（上期仅 N 天，样本不足仅供参考）"后缀，让 AI 降权引用。 + +3. **App2 system prompt 演进 v3→v4→v5→V5.1**：通过 4 次 A/B/A/B 测试（每版本 10 次调用 · 共 40 次百炼调用）+ 自建店长视角三层评分模型（准确性 40% / 洞察深度 35% / 稳定性 25%），最终 V5.1 综合分 **92.3 / 100** 超越 A 基线 17.7 分，采纳为生产版本。V5.1 核心改动为 H1/H2 两条硬性输出要求：seq 1/2 必须显式输出"对比口径：当期 X 天 vs 上期 X 天"、趋势词（下滑/收缩/加剧等）必须同句内紧跟数字锚点。 + +4. **72 组合多 APP 派生方案规划文档**：为后续区域粒度（8 业态 × 8 时间 = 64 个组合）产出完整的调研-规划-实施文档，明确 2 套 prompt 方案 + 2 个派生 APP（`app2_finance` 全域 + `app2a_finance_area` 区域）+ 无硬性 DDL 改动 + 分阶段 P1-P5 交付计划。本轮仅交付 P1（小程序 seq11/12 置顶），P2-P5 后续实施。 + +## 变更文件 + +### 修改（4 个） + +- `apps/backend/app/ai/prompts/app2_finance_prompt.py` — 月中场景 3 项保护：新增 `_WEEKDAY_MIN_DAYS = 14` 常量提升按星期聚合样本门槛；`_build_unit_economics` 短样本标注；`build_prompt` 顶层注入"对比口径"字段 +- `apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts` — 新增 `parseMarkdownInline` 内联 Markdown 解析器；`_loadAIInsights` 预生成 `bodySegs`；新增 `_extractSummary` 方法抽取末 2 条为总结区；data 新增 `aiInsightSummary / aiInsightDetails / summaryLightType / summaryLightLabel` 字段 +- `apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxml` — AI 洞察区顶部 + 弹窗顶部各插入一套"本期总结卡片"（三色灯徽章 + 诊断块 + 虚线分隔 + ⏰ 跟踪块）；明细 body 全部改为 `+` 分段渲染；最终排版收敛为"总结 2 行 clamp + 明细 seq 1/2/3 单行省略 + 引导查看全部" +- `apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss` — 新增 `.ai-summary-*` 系列样式（轻量化版：彩色圆点徽章替代厚胶囊 + 虚线下分隔 + 字色层次）/ `.md-bold` `.md-italic` / `.ai-summary-block-body-clamp`（2 行省略）/ `.ai-insight-details-label-text` 分组标签 + +### 新增（9 个） + +**文档（6 个）** +- `docs/ai/app2_finance_multi_app_design.md` — 72 组合多 APP 派生完整设计文档（调研-规划-实施三段 · 6 章 + 3 附录） +- `docs/ai/app2_finance_system_prompt_v3.md` — v3 补丁稿（首次提出"对比口径"读取规则，供用户粘贴到百炼） +- `docs/ai/app2_finance_system_prompt_20260422_v4_concise.md` — v4 精简版（5330 字，-60%） +- `docs/ai/app2_finance_system_prompt_20260422_v5.md` — v5 混合版（15612 字，含正反例对比） +- `docs/ai/app2_finance_system_prompt_20260422_v5_1.md` — **V5.1 生产版本**（15886 字，H1/H2 硬性输出要求） +- `docs/ai/app2_finance_prompt_version_history.md` — 版本记录与采纳依据表 + +**脚本（3 个）** +- `scripts/ab_test_app2_prompt.py` — A/B 测试运行器，绕过 cache 直调百炼 N 次，支持 `--resume` 断点续跑 +- `scripts/analyze_ab_content_quality.py` — 初版内容质量分析（板块级字段引用率 + 违规统计） +- `scripts/analyze_store_manager_quality.py` — 店长视角三层评分模型（准确性 40% / 洞察深度 35% / 稳定性 25%，综合分 100 分制） + +### 测试存档（不入审计详列） + +- `export/ai-ab-test/round_{a,b,v5,v5_1}/*` — 40 份完整 JSON + 4 份 summary CSV + 3 份对比 JSON 报告 +- 作为 V5.1 采纳的依据基线保留 + +## 改动注解 + +### 高风险 · 后端 prompt 构建器 + +**apps/backend/app/ai/prompts/app2_finance_prompt.py** +- **变更类型**：功能增强 + 数据保护 +- **原因**：本月 22 天（月中）调用时 AI 把环比误读为"当期部分 vs 上月整月"；月初 1-5 天样本不足，"按星期聚合"/"单位经济环比"噪声极大需要降权； +- **思路**： + - 顶层注入 `对比口径` 字段显式告知 AI 当期与对比期都是"同天数对齐"（调用 `_calc_date_range + _calc_prev_range` 计算后格式化为人类可读字符串） + - `_WEEKDAY_MIN_DAYS = 14`（替代原 `_ANOMALY_MIN_DAYS = 7`）作为按星期聚合的独立门槛 — 保证每个星期至少 2 天样本，否则返回 `None` 不注入 + - `_build_unit_economics` 里的 `_pct_change` 闭包捕获 `low_sample = prev_days < 5`，输出时附加"（上期仅 N 天，样本不足仅供参考）"后缀 +- **结果**：实测月中场景 prompt 长度 5102→5506 字符（+394 字符，+7.7%）；月初 3 天样本模拟场景下按星期聚合正确返回 None、_环比值正确附加降权后缀 + +### 高风险 · 小程序前端 + +**apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts** +- **变更类型**：功能增强 · 新增总结区 + Markdown 渲染 +- **原因**：用户反馈"seq 11/12 作为总结应置顶，减轻店长扫读负担"；AI 返回的 Markdown `**加粗**` 原本以原始 `**` 字符展示 +- **思路**：新增 `parseMarkdownInline` 独立函数（纯函数，不依赖 Page 上下文，regex 分段产出 `{text, bold?, italic?}` 数组）；`_loadAIInsights` 在 map 阶段为每条 insight 预生成 `titleSegs/bodySegs`；新增 `_extractSummary` Page 方法，按"数组长度 ≥ 4 取末两条"规则拆分 summary + details，兼容 12 条/8 条（未来区域精简 APP 的长度） +- **结果**：后端零改动；降级友好（< 4 条时 summary 空，details 全量渲染）；三色灯识别用宽松 regex（匹配 emoji 或"红灯/黄灯/绿灯"文字） + +**apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxml** +- **变更类型**：UI 结构增强（3 轮迭代） +- **原因**：用户连续 3 次对排版反馈：①初版徽章太厚、卡片视觉过重 →②轻量化（彩色圆点替代胶囊、去阴影、虚线下分隔）→ ③最终收敛到"总结区 2 行 clamp + seq 1/2/3 单行省略 + 引导查看全部" +- **思路**：AI 洞察区顶部 + 弹窗顶部对称插入总结卡片 ``；明细 body 改为 `+` 分段渲染支持 Markdown 内联样式；查看全部按钮降低触发门槛（只要有洞察就显示） +- **结果**：页面 AI 洞察区高度减少约 40%（总结区 2 行 clamp + seq 1/2/3 各 1 行），"查看全部"成为主要交互入口 + +**apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss** +- **变更类型**：样式追加（无破坏性改动） +- **原因**：配合 wxml 新结构 +- **思路**：`.ai-summary-card` 容器去厚色底改虚线下分隔；`.ai-summary-badge--{green/yellow/red/neutral}` 用纯色文字替代彩色胶囊（v2 减重）；`.md-bold` 用 `font-weight: 700 + rgba(255,255,255,0.98)` 提亮；`.ai-summary-block-body-clamp` 用 `-webkit-line-clamp: 2` 限高 +- **结果**：所有新样式都前缀化（`.ai-summary-*` / `.md-*` / `.ai-summary-block-body-clamp`），无冲突 + +### 中风险 · 文档 + +**docs/ai/app2_finance_system_prompt_20260422_v5_1.md**（生产版本） +- **变更类型**：新建 +- **原因**：经 V3→V4→V5→V5.1 四次 A/B 实测（40 次调用），V5.1 综合分 92.3 胜出，采纳为生产版本 +- **结果**：已由用户替换到百炼控制台 APP ID `1dcdb5f39c3040b6af8ef79215b9b051` + +**docs/ai/app2_finance_prompt_version_history.md** +- **变更类型**：新建（版本追踪索引） +- **原因**：4 版 prompt 文件共存需要一个入口说明"谁是生产版、为什么采纳、何时生效"，避免后续维护混淆 +- **结果**：含版本对照表 + 四方评分对比 + 评估方法说明 + 变更规则 + +**docs/ai/app2_finance_multi_app_design.md** +- **变更类型**：新建（规划蓝图） +- **原因**：72 组合预热下区域粒度数据缺失（助教/现金流/储值卡等 7 类字段），需做"区域精简 APP" 派生设计 +- **结果**：给出 2 APP 方案 + 2 套 prompt + 无硬性 DDL + P1-P5 分阶段交付。本轮仅交付 P1 小程序 seq11/12 置顶 + +### 普通 · 脚本（临时工具） + +- **scripts/ab_test_app2_prompt.py** — A/B 测试运行器；支持 `--resume` 断点续跑；直调 `DashScopeClient.call_app` 绕过缓存 +- **scripts/analyze_ab_content_quality.py** — 初版内容质量分析，板块级字段引用率 + 违规统计 +- **scripts/analyze_store_manager_quality.py** — 店长视角三层评分（准确性 40% + 洞察深度 35% + 稳定性 25%），含综合分 100 分制计算 + +## 数据库变更 + +无。本轮完全不涉及 DDL/迁移。72 组合多 APP 设计确认"无硬性 DDL"（`cache_type` / `app_type` 字段 VARCHAR(30) 已够用）。 + +## 风险与回滚 + +### 风险点 + +- **【中】百炼 V5.1 system prompt 已替换到生产**：用户在控制台已发布 V5.1。若出现 AI 输出异常（如 12 条变少、三色灯格式破坏），回滚方法见下。 +- **【中】后端 prompt 新增"对比口径"字段**：payload 长度 +394 字符，每次百炼调用 tokens 略增，成本影响 ≈ +4%。压力测试未发现超时或熔断。 +- **【低】小程序 seq 11/12 识别依赖"数组末两条"启发式**：若 AI 返回 seq 顺序错位（如 seq 11 在第 6 位），识别错误。当前实测 40 次均按 1-12 顺序返回。 +- **【低】按星期聚合门槛 14 天**：极端场景（新门店第 1-13 天）该字段缺失是正常降级，AI 应按 V5.1 硬约束 H6 输出"样本不足 14 天，周规律待积累"。需配合百炼 V5.1 同步才能生效。 +- **【低】Markdown 渲染范围有限**：仅支持 `**加粗**` / `*倾斜*`；其他 MD 语法（标题、列表、代码块）不支持，AI 若意外输出会显示原始字符。当前 v5.1 system prompt 限制"单条 ≤ 3 处加粗"，符合预期。 + +### 回滚要点 + +1. **百炼 system prompt 回滚**：将控制台 APP 的 system prompt 粘贴回 `docs/ai/app2_finance_system_prompt_20260422.md`（A 版）即可 +2. **后端 prompt 构建器回滚**：`git revert` 本次 `app2_finance_prompt.py` 的 3 处改动；"对比口径"字段对旧 prompt 无副作用，实际上可保留 +3. **小程序 UI 回滚**：`git revert` 3 个文件（ts/wxml/wxss）；或保留 v3 但调整 wxml 里 "seq 1-2 完整 / seq 3 省略" 分支的控制流 + +## 验证 + +### 已验证 + +- **后端**：`build_prompt` 本地调用测试通过（`this_month/all` 返回 prompt 长度 5506，"对比口径"字段值正确："2026-04-01 ~ 2026-04-22（22 天）" vs "2026-03-01 ~ 2026-03-22（22 天）"） +- **百炼调用实测**：V5.1 全 10 轮成功率 100% · 12 条齐整率 100% · 对比口径显式引用率 100% · 店长视角综合分 92.3 +- **短样本保护**：模拟 3 天 series 调用 `_aggregate_by_weekday` 返回 `None`；`_build_unit_economics` 返回的 `_环比` 正确附加"（上期仅 3 天，样本不足仅供参考）"后缀 + +### 待人工验证 + +- **小程序实机验证**（用户需在微信开发者工具打开 `board-finance` 页面看效果）： + - 本期总结卡片显示三色灯 + 诊断 + ⏰ 跟踪，body 截断 2 行 + - seq 1/2/3 显示单行省略 + - 加粗文字以白色粗体显示 + - 点击"查看全部 AI 洞察 ›"弹窗打开，顶部为同款总结卡片 + 全部明细可滚动 +- **百炼 V5.1 端到端**（用户可直接在小程序刷新看本月/全部区域面板的 AI 洞察内容） + +### 可执行的验证命令 + +```bash +# 1. 后端 prompt 构建器本地验证 +PYTHONIOENCODING=utf-8 .venv/Scripts/python.exe -c " +import sys, asyncio, json, os +sys.path.insert(0, 'apps/backend') +from dotenv import load_dotenv +load_dotenv() +from app.ai.prompts.app2_finance_prompt import build_prompt + +async def main(): + p = await build_prompt({'site_id': 2790685415443269, 'time_dimension': 'this_month', 'area': 'all'}) + data = json.loads(p) + assert '对比口径' in data, '缺对比口径字段' + assert '按星期聚合' in data, '缺按星期聚合字段' + print('OK: 长度', len(p), '字段数', len(data)) + +asyncio.run(main()) +" + +# 2. 店长视角评分验证（基线校验） +PYTHONIOENCODING=utf-8 .venv/Scripts/python.exe scripts/analyze_store_manager_quality.py --dir export/ai-ab-test/round_v5_1 +# 预期：综合分 ≥ 92，准确性 ≥ 98 +``` + +## 合规检查 + +| 项 | 状态 | 说明 | +|---|---|---| +| **P1 需求审问** | ⚠️ 部分执行 | 用户直接给任务，未走提问循环；但在规划文档中留了决策点供用户确认 | +| **P2 前置调研** | ✅ 已执行 | 并行 3 个 Explore 代理调研（board_service / board-finance 前端 / 72 组合预热） | +| **A1 改动后验证** | ✅ 已执行 | 后端单测通过 + 40 次百炼调用实测 + 店长视角综合分 92.3 | +| **A2 数据库文档同步** | ❎ 不适用 | 本轮无 DB schema 变更 | +| **A3 审计** | ✅ 本文档 | 即本份记录 | +| **语言** | ✅ 全中文 | 对话/代码注释/commit/文档全中文 | +| **Unicode 特殊符号** | ⚠️ 文档含 emoji | 本文档 + prompt 文档含三色灯 emoji 🔴🟡🟢 · 这些是业务规则必需输出字符（百炼返回内容需带），非装饰性使用 | +| **miniprogram README.md** | ❎ 不适用 | 预扫描提示 board-finance.ts 对应 miniprogram README.md —— 但 README.md 承载"项目级说明"，单页面 UI 改动不入该文档；已在 wxml/ts 内加 `CHANGE 2026-04-22 v3` 注释留痕 | + +### 文档同步状态 + +| 文档 | 状态 | 说明 | +|---|---|---| +| `docs/ai/app2_finance_prompt_version_history.md` | ✅ 已新建 | V5.1 采纳记录 | +| `docs/ai/app2_finance_multi_app_design.md` | ✅ 已新建 | 72 组合多 APP 规划 | +| `docs/ai/app2_finance_system_prompt_20260422_v5_1.md` | ✅ 已新建 | 生产版 prompt 全文 | +| `apps/backend/docs/` | ❎ 不适用 | 本轮 `app2_finance_prompt.py` 改动为内部函数增强，不涉及 API-REFERENCE 接口变更 | +| `apps/miniprogram/README.md` | ❎ 不适用 | 单页 UI 改版未触发 README 级变更 | + +## 下一步建议 + +1. **本轮可独立 commit**：小程序 UI + 后端 prompt 保护 + 文档 + 脚本 均已完成并通过验证，建议按下列 commit 颗粒度提交： + - `feat(ai): App2 财务洞察 system prompt V5.1 采纳 · 店长视角综合分 92.3` + - `feat(ai): App2 prompt 月中场景保护（对比口径/按星期 14 天门槛/短样本标注）` + - `feat(miniprogram): 财务看板 AI 洞察区 seq 11/12 总结置顶 + Markdown 内联渲染 + 3 条单行省略` + - `docs(ai): App2 多 APP 派生方案 + prompt 版本记录` + - `chore(scripts): A/B 测试 + 店长视角评分脚本` + +2. **后续规划的 P2 阶段可按 `docs/ai/app2_finance_multi_app_design.md` 开展**：后端新增 `app2a_finance_area` APP + 百炼控制台建第二个 APP + admin-web app_type 选择器扩展 diff --git a/docs/audit/changes/2026-04-30__admin_web_ai_app_type_alignment.md b/docs/audit/changes/2026-04-30__admin_web_ai_app_type_alignment.md new file mode 100644 index 0000000..7416a28 --- /dev/null +++ b/docs/audit/changes/2026-04-30__admin_web_ai_app_type_alignment.md @@ -0,0 +1,109 @@ +# 审计记录：admin-web AI 手动执行 app_type 对齐 + +**日期**：2026-04-30 +**会话**：处理文档台账 `A1-01`，修复 admin-web 手动执行 APP6 与后端 app_type 不一致问题 +**影响范围**：`apps/admin-web/src/api/adminAI.ts`、`apps/admin-web/src/pages/AIOperations.tsx`、`apps/admin-web/src/pages/AIRunLogs.tsx`、`apps/admin-web/src/__tests__/adminAiAppTypes.test.ts` + +--- + +## 变更背景 + +`docs/ai/ai_apps_feature_acceptance_spec.md` 与接管台账记录了一个局部功能问题： + +- 前端手动执行 APP6 使用 `app6_note_analysis` +- 后端 `/api/admin/ai/run/{app_type}` 只支持 `app6_note` +- 结果是 admin-web 手动执行 APP6 会被后端 `_SUPPORTED_APP_TYPES` 拒绝并返回 400 + +调研时进一步发现同一组前端选项被同时用于“缓存失效”和“按需执行/批量执行”，两者语义不同： + +- 缓存失效应使用 `ai_cache.cache_type`，例如 `app6_note_analysis` +- 按需执行应使用 dispatcher 支持的 `app_type`，例如 `app6_note` + +因此本次修复不直接把所有值替换成 `app6_note`，而是拆分两套选项，避免破坏缓存管理。 + +--- + +## 变更摘要 + +### `apps/admin-web/src/api/adminAI.ts` + +- 新增 `RUN_APP_TYPES` 常量，作为 `/api/admin/ai/run/{app_type}` 的前端权威列表。 +- 将 `AppType` 改为从 `RUN_APP_TYPES` 推导。 +- 将 APP6/APP7/APP8 手动执行类型对齐为： + - `app6_note` + - `app7_customer` + - `app8_consolidation` + +### `apps/admin-web/src/pages/AIOperations.tsx` + +- 将原 `APP_TYPE_OPTIONS` 拆为两组： + - `CACHE_TYPE_OPTIONS`：缓存失效继续使用 cache_type，例如 `app6_note_analysis` + - `RUN_APP_TYPE_OPTIONS`：按需执行和批量执行使用后端 app_type，例如 `app6_note` +- 将批量执行 state 类型收紧为 `AppType[]`。 + +### `apps/admin-web/src/pages/AIRunLogs.tsx` + +- 新增 `RUN_LOG_APP_TYPE_OPTIONS`。 +- 调用记录筛选改为包含真实写入 `ai_run_logs.app_type` 的值： + - `app6_note` + - `app7_customer` + - `app8_consolidate` + - `app8_consolidation` + +### `apps/admin-web/src/__tests__/adminAiAppTypes.test.ts` + +- 新增回归测试，覆盖： + - 手动执行选项使用后端支持的 app_type + - 缓存失效继续使用 cache_type + - run log 筛选包含真实日志 app_type + +--- + +## 验证 + +已执行： + +```powershell +cd apps/admin-web +pnpm test -- src/__tests__/adminAiAppTypes.test.ts +pnpm lint +``` + +结果： + +- 目标回归测试：3/3 通过。 +- TypeScript 检查：通过。 + +另外执行了全量 `pnpm test`，结果失败，但失败项与本次修改无关，集中在既有测试债： + +- 菜单测试仍按 7 个一级菜单断言，但当前已有 `AI 管理` 后为 8 个。 +- 侧边栏高亮测试仍期待 `/triggers?tab=ai` 选中 `/triggers`，但当前选中 `ai-group`。 +- e2e helper 使用 `btoa` 处理中文 payload，触发 `InvalidCharacterError`。 +- `tabStatePreservation.property.test.tsx` 中 `TaskManager` mock 缺 `QueueTab` export。 + +--- + +## 风险与影响 + +| 风险 | 结论 | +|------|------| +| 缓存失效是否被破坏 | 未破坏。缓存失效继续走 `CACHE_TYPE_OPTIONS`，保留 `app6_note_analysis` 等 cache_type | +| 手动执行是否仍可能 400 | APP6/APP7/APP8 已改为后端支持的 app_type；仍需真实后端联调验证接口返回 | +| run log 旧数据筛选 | 新筛选值覆盖当前 dispatcher 写入值；历史中如果已存在旧 cache_type 风格日志，需要临时手工查库 | +| 批量执行 | 前端提交的 app_type 已收紧到后端运行类型；后端批量执行当前仍主要是预估/异步占位，未改变服务端行为 | + +--- + +## 回滚 + +如需回滚本次修复： + +```powershell +git restore apps/admin-web/src/api/adminAI.ts ` + apps/admin-web/src/pages/AIOperations.tsx ` + apps/admin-web/src/pages/AIRunLogs.tsx + +Remove-Item -LiteralPath apps/admin-web/src/__tests__/adminAiAppTypes.test.ts +``` + +回滚后 admin-web 手动执行 APP6 会恢复为发送 `app6_note_analysis`，该路径仍会被后端拒绝。 diff --git a/docs/audit/changes/2026-04-30__backend_dashscope_tokens_used_extraction.md b/docs/audit/changes/2026-04-30__backend_dashscope_tokens_used_extraction.md new file mode 100644 index 0000000..711d306 --- /dev/null +++ b/docs/audit/changes/2026-04-30__backend_dashscope_tokens_used_extraction.md @@ -0,0 +1,113 @@ +# 审计记录：后端 DashScope tokens_used 提取修复 + +**日期**：2026-04-30 +**会话**：处理接管台账 `A1-02`，修复 DashScope `usage.models` 嵌套结构下 `tokens_used=0` 的预算追踪问题 +**影响范围**：`apps/backend/app/ai/dashscope_client.py`、`apps/backend/tests/tests/unit/test_dashscope_client_usage.py` + +--- + +## 变更背景 + +AI 验收文档和历史审计均记录 `tokens_used=0` 问题：DashScope Application API 返回的 usage 不是旧的顶层 `input_tokens/output_tokens`，而是 `ApplicationUsage(models=[ApplicationModelUsage(...)])`。如果无法正确提取 token 计数，会影响： + +- `biz.ai_run_logs.tokens_used` 写入 +- admin-web AI 调用记录和预算展示 +- `BudgetTracker` 的日/月 token 用量判断 + +调研时发现当前工作区已有一段未提交的半修复：可处理 SDK 对象形态 `usage.models`，但普通 dict 形态 `{"models": [...]}` 仍会漏算为 0。 + +--- + +## 变更摘要 + +### `apps/backend/app/ai/dashscope_client.py` + +- 新增 `_field_value()`，统一读取 dict、DashScope `DictMixin`、普通对象字段。 +- 新增 `_safe_int()`，对 token 字段做安全整数转换，异常值按 0 处理。 +- 新增 `_extract_tokens_used()`，按以下优先级提取 token： + - `usage.models[*].input_tokens/output_tokens` + - `usage.total_tokens` + - `usage.input_tokens/output_tokens` +- `DashScopeClient.call_app()` 改为调用 `_extract_tokens_used(response.usage)`，避免分支逻辑散落在主流程中。 + +### `apps/backend/tests/tests/unit/test_dashscope_client_usage.py` + +- 新增 5 个单元测试，覆盖： + - SDK `ApplicationUsage(models=[...])` + - 普通 dict `{"models": [...]}` + - 顶层 dict `input_tokens/output_tokens` + - 对象 `total_tokens` + - usage 缺失时返回 0 + +--- + +## TDD 记录 + +先新增测试并运行 RED： + +```powershell +cd apps/backend +C:\Project\NeoZQYY\.venv\Scripts\python.exe -m pytest tests/tests/unit/test_dashscope_client_usage.py -q +``` + +RED 结果：5 个测试中 1 个失败，失败用例为 `test_call_app_sums_tokens_from_plain_dict_models`，实际返回 `0`，符合预期复现。 + +修复后再次运行同一测试： + +```powershell +C:\Project\NeoZQYY\.venv\Scripts\python.exe -m pytest tests/tests/unit/test_dashscope_client_usage.py -q +``` + +GREEN 结果：5/5 通过。 + +--- + +## 验证 + +已执行： + +```powershell +cd apps/backend +C:\Project\NeoZQYY\.venv\Scripts\python.exe -m compileall app/ai/dashscope_client.py +C:\Project\NeoZQYY\.venv\Scripts\python.exe -m pytest tests/tests/unit/test_dashscope_client_usage.py tests/tests/unit/test_xcx_chat_ai_fallback.py::TestAIFallback::test_ai_success_returns_real_reply -q +C:\Project\NeoZQYY\.venv\Scripts\python.exe -m pytest tests/tests/integration/test_ai_full_chain.py::test_note_chain -q +C:\Project\NeoZQYY\.venv\Scripts\python.exe -m pytest tests/tests/integration/test_ai_full_chain.py::test_failure_logging -q +C:\Project\NeoZQYY\.venv\Scripts\python.exe -m pytest tests/tests/test_ai_prompts_smoke.py::test_dispatcher_registers_5_handlers -q +``` + +结果： + +- `compileall`：通过。 +- token 提取与对话成功路径：6/6 通过。 +- AI note chain：通过。 +- failure logging：通过。 +- dispatcher handler 注册：通过。 + +补充验证： + +- `tests/tests/test_ai_dispatcher.py` 全文件运行 124 秒超时。 +- 单独运行 `TestProperty10ChainOrder::test_note_event` 时，失败原因为 Hypothesis `DeadlineExceeded`：单例耗时约 3.6s，超过默认 200ms；不是断言失败，也不是本次 token 提取逻辑失败。该测试债未在本次修复中处理。 + +--- + +## 风险与影响 + +| 风险 | 结论 | +|------|------| +| 预算追踪 | 新成功调用可从 `usage.models` 正确累加 token，改善日/月预算统计可信度 | +| 旧数据 | 已写入为 0 的历史 run log 不会自动回填；如需历史修正需另做数据方案 | +| DashScope SDK 形态变化 | 覆盖 SDK 对象、普通 dict 和旧 `total_tokens` 形态，兼容性较当前实现更强 | +| 真实外部调用 | 本次未消耗真实 DashScope token；仍需后续用真实 APP 调用验证 `success AND tokens_used>0` | + +--- + +## 回滚 + +如需回滚本次修复： + +```powershell +git restore apps/backend/app/ai/dashscope_client.py +Remove-Item -LiteralPath apps/backend/tests/tests/unit/test_dashscope_client_usage.py +``` + +回滚后普通 dict `models` 形态会重新漏算为 0；若回到 HEAD 基线，SDK `ApplicationUsage.models` 形态也会重新漏算。 diff --git a/docs/audit/changes/2026-05-01__backend_app3_full_detail_prompt.md b/docs/audit/changes/2026-05-01__backend_app3_full_detail_prompt.md new file mode 100644 index 0000000..530ba58 --- /dev/null +++ b/docs/audit/changes/2026-05-01__backend_app3_full_detail_prompt.md @@ -0,0 +1,80 @@ +# 2026-05-01 App3 完整消费明细 Prompt 策略 + +## 背景 + +- 历史问题：2026-04-20 真实 E2E 中 `app3_clue` 曾因 prompt 过大在 121s 超时。 +- 原缓解策略：App3 prompt 超过 4000 字后，仅保留最近 3 条 `consumption_records`，必要时清空 `reference`。 +- 本轮用户明确倾向：保留完整消费明细，先验证完整明细是否能正常返回。 + +## 变更内容 + +| 文件 | 变更 | +| --- | --- | +| `apps/backend/app/ai/prompts/app3_clue_prompt.py` | 取消 App3 4000 字/3 条消费记录硬截断，保留完整 `consumption_records` 与 `reference` | +| `apps/backend/tests/tests/unit/test_app3_clue_prompt_full_detail.py` | 新增单元测试，锁定 100 条消费记录完整保留 | +| `docs/ai/ai_apps_feature_acceptance_spec.md` | 更新 App3 验收点与消费记录风险说明 | +| `docs/claude-history/issue_resolution_tracker_2026-04-30.md` | 将 A1-03 状态更新为已验证，并记录真实调用结果 | + +## 验证记录 + +### RED + +```powershell +C:\Project\NeoZQYY\.venv\Scripts\python.exe -m pytest tests/tests/unit/test_app3_clue_prompt_full_detail.py -q +``` + +结果：失败。当前实现把 100 条消费记录裁剪到 3 条，符合预期 RED。 + +### GREEN + +```powershell +C:\Project\NeoZQYY\.venv\Scripts\python.exe -m pytest tests/tests/unit/test_app3_clue_prompt_full_detail.py -q +``` + +结果：`1 passed`。 + +```powershell +C:\Project\NeoZQYY\.venv\Scripts\python.exe -m pytest tests/tests/unit/test_app3_clue_prompt_full_detail.py tests/tests/test_ai_prompts_smoke.py -q +``` + +结果：`7 passed`。 + +```powershell +C:\Project\NeoZQYY\.venv\Scripts\python.exe -m compileall app/ai/prompts/app3_clue_prompt.py +``` + +结果：通过。 + +### 真实 App3 调用 + +使用合成会员数据，不读取真实门店或生产会员数据： + +- 完整消费明细：100 条 +- prompt 长度：25,791 字 +- 本地截断标记：无 +- DashScope App3 返回：成功 +- 耗时：64.30s +- tokens_used：15,708 +- 返回结构：`{"clues": [...]}`，共 4 条 +- 结论：低于当前 `_STEP_TIMEOUT=180s` 单步超时阈值 + +## 影响范围 + +- 影响消费事件链 `App3 -> App8 -> App7` 的 App3 prompt 输入规模。 +- App3 成功时，App8 可获得更完整的消费线索输入，降低高频客户模式被裁剪的风险。 +- 不涉及数据库 schema、RLS、权限、API 入参或前端字段变更。 + +## 风险与回滚 + +剩余风险： + +- 真实门店极端会员、较大的历史 `reference`、百炼侧临时性能波动，仍可能导致 App3 耗时升高。 +- prompt 长度增加会提高单次 token 消耗，本次合成样例为 15,708 tokens。 + +观察建议： + +- 后续上线后重点观察 `ai_run_logs.elapsed_ms`、`tokens_used` 和 `app3_clue` timeout 告警。 + +回滚方式： + +- 如真实数据出现持续超时，可恢复 App3 的消费记录截断逻辑，或改为“完整明细优先 + 超大样本动态降级”的折中策略。 diff --git a/docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md b/docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md new file mode 100644 index 0000000..64d95de --- /dev/null +++ b/docs/audit/changes/2026-05-04__cumulative_baseline_pending_verification.md @@ -0,0 +1,183 @@ +# 累积基线变更 + 待验证清单（2026-04-15 ~ 2026-05-02） + +| 字段 | 值 | +|------|-----| +| 日期 | 2026-05-04 | +| 类型 | 累积基线提交（多主题合流） | +| 覆盖时间 | 2026-04-15 ~ 2026-05-02 | +| 文件总数 | 129（不含 `apps/etl/connectors/feiqiu/.env` API_TOKEN secret 与 `tmp/`） | +| commit 范围 | 单个累积基线 commit（参照 `2a7a5d6 feat: 2026-04-15~04-20 累积变更基线`） | + +## 0. 背景 + +经历 Cursor 时代的多次会话累积，4 月 15 日之后未做完整 push 收尾。本次反向迁回 Claude Code 后做单轨化 + 推送收尾时发现 124 个未提交业务变更，但**已存在 8 个审计记录 + 7 个数据库变更文档**（散落在 `docs/audit/changes/` 和 `docs/database/changes/` 中 untracked）。审计步骤已在前序会话完成，本次仅做**累积基线 commit + 推送**。 + +**关键原则**：每个主题的"功能完整性 + 上线验证"**几乎都没有收口**，本文档列出待逐一处理的验证清单，作为后续工作起点。 + +## 1. 已存在的审计记录索引 + +| 审计记录 | 主题 | +|---|---| +| `docs/audit/changes/2026-04-20__ai-module-complete.md` | AI 模块完成（8 个千问 APP） | +| `docs/audit/changes/2026-04-21__admin-web-ai-management-suite.md` | admin-web AI 管理套件 | +| `docs/audit/changes/2026-04-21__app2-finance-prewarm-all-filters.md` | App2 财务预热全过滤器 | +| `docs/audit/changes/2026-04-21__board-finance-ai-insights-verify.png` | board-finance AI 洞察验证截图 | +| `docs/audit/changes/2026-04-22__app2_prompt_v5_1_and_miniprogram_ai_insight.md` | App2 prompt v5.1 + 小程序 AI 接入 | +| `docs/audit/changes/2026-04-30__admin_web_ai_app_type_alignment.md` | admin-web AI AppType 联合类型对齐 | +| `docs/audit/changes/2026-04-30__backend_dashscope_tokens_used_extraction.md` | DashScope tokens_used 提取修复 | +| `docs/audit/changes/2026-05-01__backend_app3_full_detail_prompt.md` | App3 线索完整详情 prompt | + +## 2. 已存在的数据库变更文档 + +| 数据库变更文档 | 主题 | +|---|---| +| `docs/database/changes/2026-05-01__runtime_context_sandbox.md` | Runtime Context 沙箱设计 | +| `docs/database/changes/2026-05-02__sandbox_admin_web_manual_checklist.md` | 沙箱 admin-web 手工验证清单 | +| `docs/database/changes/2026-05-02__sandbox_admin_web_playwright_report.md` | 沙箱 admin-web Playwright 报告 | +| `docs/database/changes/2026-05-02__sandbox_admin_web_verify_report.md` | 沙箱 admin-web 验证报告 | +| `docs/database/changes/2026-05-02__sandbox_complete_refactor.md` | 沙箱完整重构 | +| `docs/database/changes/2026-05-02__sandbox_e2e_verify_report.md` | 沙箱 e2e 验证报告 | +| `docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md` | 沙箱避免未来数据策略 | + +## 3. 各主题待验证清单（核心） + +> **每个主题都标注实际未完成 / 待验证项。以下为后续逐一处理的工作起点。** + +### 3.1 AI 模块重构（8 个千问 APP 拆分） + +**变更**：删除旧 `apps/backend/app/ai/apps/app[1-8]_*.py`（9 个），改为 `apps/backend/app/ai/prompts/app[1-8]_*_prompt.py` 模块化。`dispatcher.py` 重构调用链路。 + +**待验证**： + +- [ ] 8 个 APP 在生产环境的实际调用链路完整性（`chat / finance / clue / analysis / tactics / note / customer / consolidate`） +- [ ] `app2a_finance_area_prompt.py` 区域财务派生 APP 是否独立稳定 +- [ ] `dispatcher.py` 重构后的熔断 / 限流 / 预算追踪行为是否与重构前一致 +- [ ] `cache_service.py` AI 对话缓存是否仍按 `cache_type` 正确分桶 +- [ ] `references.py` 新增的引用聚合层是否被所有 prompt builder 正确使用 +- [ ] `event_bus.py` 新增事件总线在生产中的实际订阅者数量 +- [ ] `ws/ai_events.py` WebSocket 事件推送的浏览器侧消费稳定性 + +### 3.2 admin-web AI 管理套件 + AppType 对齐 + +**变更**：6 个 admin-web AI 页面（`AIDashboard / AIOperations / AIRunLogs / AITriggers / RuntimeContext / TriggerManager`）+ `adminAI.ts` API 封装 + `adminAiAppTypes.test.ts` 单元测试。 + +**待验证**： + +- [ ] AITriggers 页面在 admin-web 主菜单的入口路由是否注册 +- [ ] AppType 联合类型（`adminAiAppTypes.test.ts` 验证 8 个 AppType 命名一致性）是否通过 `pnpm test` +- [ ] AIDashboard 实时 WebSocket 订阅在 admin-web 浏览器端的连通性 +- [ ] AIRunLogs 分页 + 筛选条件在大数据量（>10k 条）下的性能 +- [ ] TriggerManager 触发器编辑 / 启停的端到端流程 + +### 3.3 App2 财务洞察 prompt v3 → v5.1 演进 + +**变更**：`app2_finance_prompt.py` 升级到 v5.1；存档 8 份 prompt 版本（`docs/ai/app2_finance_system_prompt_*`）+ A/B 测试脚本（`scripts/ab_test_app2_prompt.py` 等 5 个）。 + +**待验证**： + +- [ ] v5.1 vs v5 vs v4 在真实门店数据上的店长视角评分（参考 `analyze_store_manager_quality.py`） +- [ ] 12 条产出齐整率 + 三色灯分布稳定性（`ab_test_app2_prompt.py`） +- [ ] 客单价环比是否从原字段引用、不做推测（`analyze_ab_content_quality.py` 板块 A） +- [ ] 储值卡余额变化是否引用权威字段（板块 C） +- [ ] 旺淡倍率 + 同周/期均基线是否在 seq 9-10 中体现（板块 E） + +### 3.4 App3 线索完整详情 prompt + +**变更**：`app3_clue_prompt.py` 新增完整详情构造逻辑。 + +**待验证**： + +- [ ] 与 App3 dispatcher 调用链路联调 +- [ ] 线索数据 fetcher 字段完整性（`data_fetchers/` 多个文件改动） + +### 3.5 Runtime Context 沙箱（5-1 ~ 5-2 主线工作） + +**变更**：跨前后端 + 数据库的完整沙箱设计： +- 后端：`runtime_context.py` schema/service + `admin_runtime_context.py` `xcx_runtime_clock.py` 两个新 router +- admin-web：`RuntimeContext.tsx` 页面 + `runtimeContext.ts` API +- 小程序：`runtime-clock.ts` 工具 +- 数据库：`db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql` +- 验证工具：`tools/db/verify_admin_web_sandbox.py` + +**待验证**： + +- [ ] 7 份 `docs/database/changes/2026-05-0[12]__sandbox_*.md` 中描述的验证步骤是否全部执行 +- [ ] sandbox 时间漂移在小程序端的实际表现（`runtime-clock.ts` 在多端时区切换下的稳定性） +- [ ] admin-web RuntimeContext 页面的"未来数据"防护策略（参考 `sandbox_no_future_data_plan.md`） +- [ ] e2e 测试报告中 Playwright 截图与手工 checklist 的一致性 +- [ ] `xcx_runtime_clock.py` 小程序时间同步 API 在生产灰度环境的实际行为 + +### 3.6 AI 触发器 + app2 prewarm 数据库 + +**变更**： +- `db/zqyy_app/migrations/20260420_ai_trigger_jobs_and_app2_prewarm.sql` +- `db/zqyy_app/migrations/20260421_app2_prewarm_cron_reschedule.sql` +- `docs/database/BD_manual_ai_trigger_jobs_register.md` +- `apps/backend/app/services/trigger_scheduler.py` 调整 + +**待验证**： + +- [ ] cron 重调度后的 prewarm 命中率（`apps/backend/app/services/trigger_scheduler.py`） +- [ ] AI 触发器 jobs 表的实际数据量 +- [ ] 21 日 cron reschedule 是否影响其他既有触发器 + +### 3.7 飞球 DWS 修复 + RLS 业务日上界视图 + +**变更**： +- `apps/etl/connectors/feiqiu/tasks/dws/finance_area_daily.py` 区域财务汇总 +- `apps/etl/connectors/feiqiu/tasks/dws/task_engine.py` 任务引擎 +- `db/etl_feiqiu/migrations/20260502__rls_views_business_date_upper_bound.sql` RLS 视图加业务日上界 +- `scripts/ops/gen_rls_business_date_migration.py` 视图迁移生成器 + +**待验证**： + +- [ ] RLS 业务日上界视图覆盖的 N 个视图是否全部通过 `pg_get_viewdef` 重建 +- [ ] `finance_area_daily` 在 area 维度的会员分桶是否与 DWS 权威规范一致 +- [ ] task_engine 改动后的幂等性（按 `apps/etl/connectors/feiqiu/CLAUDE.md` DWS 幂等规则） + +### 3.8 admin-web 沙箱验证产物 + +**变更**：3 份 `2026-05-02__sandbox_admin_web_*.md` 报告 + 验证工具 `tools/db/verify_admin_web_sandbox.py`。 + +**待验证**： + +- [ ] verify_admin_web_sandbox.py 在最新数据下重跑结果 +- [ ] manual checklist 的所有项是否在生产环境复现 + +### 3.9 部署文档 + +**变更**： +- `docs/deployment/LAUNCH-CHECKLIST.md` 修改 +- `docs/deployment/SERVER-ACCESS.md` 新增 + +**待验证**： + +- [ ] 实际部署链路与 SERVER-ACCESS 中描述的服务器是否一致（注意：`SERVER-ACCESS.md` 可能含敏感连接信息，入仓前应复扫） + +## 4. 后续处理优先级建议 + +| 优先级 | 主题 | 原因 | +|---|---|---| +| P0 | 3.1 AI 模块重构验证 | 8 APP 是核心业务，重构面广 | +| P0 | 3.5 Runtime Context 沙箱 | 跨前后端 + DB，5-1~5-2 主线工作未收口 | +| P1 | 3.7 飞球 DWS + RLS 业务日上界 | 数据正确性，影响所有下游 | +| P1 | 3.6 AI 触发器 prewarm | cron 改动需观察是否漏触发 | +| P2 | 3.3 App2 prompt v5.1 | A/B 测试脚本已就绪，需要跑评分 | +| P2 | 3.2 admin-web AI 管理套件 | 工具页面，问题影响面有限 | +| P3 | 3.4 / 3.8 / 3.9 | 较为独立的小主题 | + +## 5. 不入仓项 + +- `apps/etl/connectors/feiqiu/.env`：飞球上游 SaaS API_TOKEN（modified 但保留为本地修改） +- `tmp/`：临时分析产物（已加入 `.gitignore`） + +## 6. 操作记录 + +``` +git add -A +git restore --staged apps/etl/connectors/feiqiu/.env # 排除 secret +git commit -m "feat: 2026-04-15~05-02 累积变更基线 — AI 重构 + Runtime Context + DWS 修复" +git push origin dev +``` + +后续按 §4 优先级逐一展开主题验证 + 收口。 diff --git a/docs/database/BD_Manual_runtime_context_sandbox.md b/docs/database/BD_Manual_runtime_context_sandbox.md new file mode 100644 index 0000000..ca8f27f --- /dev/null +++ b/docs/database/BD_Manual_runtime_context_sandbox.md @@ -0,0 +1,152 @@ +# BD_Manual：业务运行上下文（biz.site_runtime_context）+ 沙箱隔离列 + +> 目标库：`test_zqyy_app`（通过 `TEST_APP_DB_DSN` 连接）；生产库 `zqyy_app` 待上线 +> 迁移脚本：[db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql](../../db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql) +> 关联变更说明：[changes/2026-05-01__runtime_context_sandbox.md](changes/2026-05-01__runtime_context_sandbox.md) +> 关联设计：球房停业后，希望按门店把后台 / 小程序切到“假设当前是历史日期”的状态做开发与演示，而真实预算与系统时间不受影响。 + +--- + +## 1. 设计目标 + +- 多门店隔离：每个 `site_id` 独立选择 live 或 sandbox，互不影响。 +- 业务时钟统一：后端任务、看板、AI 调用都通过 `RuntimeContext.business_date` 取“今天”，不再直接调用 `date.today()` / `NOW()`。 +- 写入隔离：sandbox 模式下任务、AI cache、run logs 写入时携带 `runtime_mode='sandbox'` + `sandbox_instance_id=sbx_*`，与 live 数据共存但不污染。 +- 安全降级：表缺失或异常时退回 live，确保迁移前线上行为不变。 + +--- + +## 2. 表结构 + +### 2.1 `biz.site_runtime_context`（9 字段） + +| 字段 | 类型 | 约束 | 说明 | +|---|---|---|---| +| `site_id` | bigint | PK，FK → `biz.sites(site_id)` | 门店 ID | +| `mode` | varchar(20) | NOT NULL DEFAULT `'live'`，CHECK `IN ('live','sandbox')` | 运行模式 | +| `sandbox_date` | date | 可空 | sandbox 模式下系统假设的业务日期 | +| `sandbox_instance_id` | varchar(64) | 可空 | sandbox 模式写入隔离实例 ID（格式 `sbx_<24hex>`） | +| `ai_mode` | varchar(20) | NOT NULL DEFAULT `'live'`，CHECK `IN ('live')` | AI 调用模式；当前仅 live，沙箱也真实调用 DashScope | +| `status` | varchar(20) | NOT NULL DEFAULT `'active'` | 上下文状态 | +| `reason` | text | 可空 | 切换原因（运维/演示备注） | +| `updated_by` | bigint | 可空 | 最近一次切换的 admin user_id | +| `created_at` | timestamptz | NOT NULL DEFAULT now() | 创建时间 | +| `updated_at` | timestamptz | NOT NULL DEFAULT now() | 更新时间（API 切换时手动写入 NOW()） | + +约束： + +| 约束名 | 类型 | 说明 | +|---|---|---| +| `site_runtime_context_pkey` | PK | `(site_id)` | +| `site_runtime_context_site_id_fkey` | FK | `site_id → biz.sites(site_id)` | +| `site_runtime_context_mode_check` | CHECK | `mode IN ('live','sandbox')` | +| `site_runtime_context_ai_mode_check` | CHECK | `ai_mode IN ('live')` | +| `site_runtime_context_sandbox_check` | CHECK | `live` 模式 `sandbox_*` 必为 NULL；`sandbox` 模式 `sandbox_*` 必非 NULL | + +### 2.2 7 张表新增 runtime 维度列 + +每张表新增两列，默认值 `'live'` / `'live'`，NOT NULL： + +| Schema.Table | 主要用途 | +|---|---| +| `biz.coach_tasks` | 助教任务（召回/回访/关系建设） | +| `biz.coach_task_transfer_log` | 任务转移日志 | +| `biz.coach_task_history` | 任务历史归档 | +| `biz.recall_events` | 消费引发的召回事件 | +| `biz.ai_cache` | AI 应用缓存 | +| `biz.ai_run_logs` | AI 调用明细 | +| `biz.ai_trigger_jobs` | AI 调度记录 | + +| 列 | 类型 | 默认值 | 说明 | +|---|---|---|---| +| `runtime_mode` | varchar(20) | `'live'` | 写入时所处模式 | +| `sandbox_instance_id` | varchar(64) | `'live'` | sandbox 实例 ID；live 模式占位 `'live'` | + +### 2.3 索引 + +替换的旧索引： + +| Schema.Index | 状态 | +|---|---| +| `biz.idx_coach_tasks_site_assistant_member_type` | DROP | +| `biz.idx_recall_events_site_assistant_member_day` | DROP | + +新建索引： + +| Schema.Index | 类型 | 列 | 说明 | +|---|---|---|---| +| `idx_coach_tasks_runtime_unique_active` | UNIQUE，部分 `WHERE status='active'` | `(site_id, assistant_id, member_id, task_type, runtime_mode, sandbox_instance_id)` | 同一 (site/assistant/member/task) 在 live 与 sandbox 之间互不冲突，可同时存在活跃任务 | +| `idx_recall_events_runtime_site_assistant_member_day` | UNIQUE | `(site_id, assistant_id, member_id, runtime_mode, sandbox_instance_id, date_trunc('day', pay_time AT TIME ZONE 'Asia/Shanghai'))` | 召回事件按当日去重，加入 runtime 维度 | +| `idx_coach_tasks_runtime_assistant_status` | INDEX | `(site_id, runtime_mode, sandbox_instance_id, assistant_id, status)` | 任务列表查询 | +| `idx_ai_cache_runtime_lookup` | INDEX | `(cache_type, site_id, runtime_mode, sandbox_instance_id, target_id, created_at DESC)` | AI cache 查询 | +| `idx_ai_trigger_jobs_runtime_site` | INDEX | `(site_id, runtime_mode, sandbox_instance_id, event_type, status)` | AI 调度记录查询 | + +--- + +## 3. 写入与查询约定 + +### 3.1 写入 + +写入新行时统一使用 `app.services.runtime_context.runtime_insert_columns(site_id)` 取出列、占位符与值；live 行得到 `('live','live')`，sandbox 行得到 `('sandbox', sbx_)`。 + +`biz.ai_cache.target_id` 在 sandbox 模式下会被 `namespace_ai_target_id` 加上前缀，例如 `sbx_xxx:this_month__all`。 + +### 3.2 查询 + +业务查询统一使用 `task_runtime_filter(site_id, alias=...)`： + +- live 模式 `AND COALESCE(t.runtime_mode,'live')='live' AND COALESCE(t.sandbox_instance_id,'live')='live'` +- sandbox 模式 `AND t.runtime_mode='sandbox' AND t.sandbox_instance_id=%s` + +### 3.3 切换 API + +| 接口 | 权限 | 说明 | +|---|---|---| +| `GET /api/config/runtime-context` | 任意登录用户 | 返回当前用户门店的 RuntimeContext | +| `GET /api/admin/runtime-context?site_id=...` | super_admin | 按 site_id 查询 | +| `GET /api/admin/runtime-context/sites` | super_admin | 列出门店与运行上下文 | +| `PATCH /api/admin/runtime-context` | super_admin | 切换 live/sandbox | + +切换 sandbox 时按 `site_id` 暂停 `biz.trigger_jobs` 中 `status='enabled'` 的记录为 `paused_by_sandbox`；切回 live 时恢复同一 site 的 `paused_by_sandbox` 为 `enabled`。 + +--- + +## 4. 真实数据 vs 沙箱数据 + +| 主体 | live 行 | sandbox 行 | +|---|---|---| +| 业务时钟 | 真实日期 | `sandbox_date` | +| 任务表 | 写入 `('live','live')` | 写入 `('sandbox', sbx_*)` | +| AI cache | `runtime_mode='live'`，`target_id` 不变 | `runtime_mode='sandbox'`，`target_id` 加 `sbx_*:` 前缀 | +| AI run logs / trigger jobs | live | sandbox + sbx_* | +| 真实预算 / DashScope tokens 计费 | 计入真实统计 | 同样真实计入（不为节流） | +| `biz.trigger_jobs` | sandbox 模式下当前 site 下 `enabled` 行被改为 `paused_by_sandbox`；其它 site 不动 | + +--- + +## 5. 验证清单 + +- 列 / 索引 / 约束按 `changes/2026-05-01__runtime_context_sandbox.md` 第 4 节 5 项 SQL 验证。 +- 切换流程：在 admin-web `/settings/runtime-context` 选择门店 → 切到 sandbox（指定 `sandbox_date`）→ 验证 `biz.trigger_jobs` 仅当前 site 被暂停，其它 site 不受影响 → 切回 live 恢复。 + +--- + +## 6. 注意事项 + +- **不要直接清空 sandbox 数据**：`coach_tasks`、`ai_cache` 等如有清理需求，须按 `runtime_mode='sandbox' AND sandbox_instance_id=...` 限定。 +- **生产库上线**：执行迁移前先确认无门店启用 sandbox；上线后再开放 admin-web 入口。 +- **降级路径**：当 `biz.site_runtime_context` 表暂未上线（如逐步发布），后端 `get_runtime_context` 自动降级为 live，避免业务中断。 + +## 7. 读取层「不看未来」改造路线 + +R1 初版只解决了**写入隔离**。读取层的看板 / 任务 / AI / 小程序仍存在「sandbox 模式下读到 sandbox_date 之后真实数据」的风险。完整改造方案与逐项文件清单见 +[changes/2026-05-02__sandbox_no_future_data_plan.md](changes/2026-05-02__sandbox_no_future_data_plan.md)。 + +| 层 | 进度 | +|---|---| +| A 文档 / UI 警告 | 进行中（admin-web Alert + 本章节） | +| B-1 后端 service / prompts / data_fetchers / fdw_queries 时间锚替换与 SQL 上界 | 计划中 | +| B-2 小程序去除本地年月 | 计划中 | +| C ETL RLS 视图层 `app.current_business_date` 业务日上界 | 计划中 | + +完成顺序按 plan 文档执行；每个 PR 自带 sandbox 模式下「不返回 sandbox_date 之后数据」的最小验证。 diff --git a/docs/database/BD_manual_ai_trigger_jobs_register.md b/docs/database/BD_manual_ai_trigger_jobs_register.md new file mode 100644 index 0000000..f960f63 --- /dev/null +++ b/docs/database/BD_manual_ai_trigger_jobs_register.md @@ -0,0 +1,116 @@ +# BD 手册：AI 事件触发器 + App2 cron 预热注册 + +## 背景 + +Phase 0 AI 模块收尾（2026-04-20）。dispatcher 已注册 5 个 handler 到 +`trigger_scheduler._JOB_REGISTRY`（通过 `main.py` lifespan 调用），但 +`biz.trigger_jobs` 缺对应数据行 → `fire_event()` 查不到事件绑定， +导致 4 个 fire_event 调用点（task_generator / note_service / +admin_task_engine / internal_events）全部失效。本迁移补齐数据行。 + +## 变更说明 + +| 库 | Schema | 表 | 变更类型 | 新增数据 | +|---|---|---|---|---| +| zqyy_app | biz | trigger_jobs | INSERT 5 行 | 4 event + 1 cron | + +### 新增记录 + +| job_name | job_type | trigger_condition | trigger_config | 说明 | +|---|---|---|---|---| +| `ai_consumption_settled` | `ai_consumption_settled` | event | `{"event_name":"ai_consumption_settled"}` | 消费事件链 App3→App8→App7（+App4→App5） | +| `ai_note_created` | `ai_note_created` | event | `{"event_name":"ai_note_created"}` | 备注事件链 App6→App8 | +| `ai_task_assigned` | `ai_task_assigned` | event | `{"event_name":"ai_task_assigned"}` | 任务分配链 App4→App5 | +| `ai_dws_completed` | `ai_dws_completed` | event | `{"event_name":"ai_dws_completed"}` | App2 × 8 时间维度预生成 | +| `ai_dws_prewarm_0830` | `ai_dws_prewarm` | cron | `{"cron_expression":"30 8 * * *"}` | 每日 08:30 兜底触发，对所有门店预热 App2 | + +### 迁移脚本路径 + +`db/zqyy_app/migrations/20260420_ai_trigger_jobs_and_app2_prewarm.sql` + +### 配套代码变更（已在 Phase 0.1~0.3 内完成） + +- `app/ai/dispatcher.py`：5 个 handler 注册（4 event + 1 cron），handle_app2_prewarm 新增 +- `app/services/trigger_scheduler.py`：`_invoke_handler` 支持 async handler（识别 coroutine 自动调度） +- `app/services/task_generator.py`：run() 末尾对新建任务批量触发 `ai_consumption_settled` +- `app/services/note_service.py`：create_note 在异步 AI 评分同处增 `ai_note_created` 触发 +- `app/routers/admin_task_engine.py`：reassign_task commit 后触发 `ai_task_assigned` +- `app/routers/internal_events.py`：etl_completed_endpoint 返回前对所有 site 触发 `ai_dws_completed` + +## 兼容性 + +| 受影响方 | 影响 | +|---|---| +| ETL | 无影响。ETL 通过现有 POST `/api/internal/etl-completed` 触发，后端已自动触发 AI 事件 | +| 后端 API | 无破坏性改动。新增 cron job `ai_dws_prewarm_0830` 由 Scheduler 后台循环拾取，不影响现有调度 | +| 小程序 | 无直接影响。前端通过 `ai_cache` 读缓存，缓存由 dispatcher 链路写入 | +| admin-web | 无影响。AI 监控面板通过已有 `/api/admin/ai/*` 接口查询 | +| 其他门店隔离 | 无影响。5 条记录为全局配置（非 site 级别），dispatcher 处理时从 payload 取 site_id | + +## 回滚策略 + +### SQL 回滚 + +```sql +-- 删除 5 条记录（幂等） +DELETE FROM biz.trigger_jobs +WHERE job_name IN ( + 'ai_consumption_settled', + 'ai_note_created', + 'ai_task_assigned', + 'ai_dws_completed', + 'ai_dws_prewarm_0830' +); +``` + +### 代码回滚 + +若需完全回滚 Phase 0：`git revert` 对应提交即可。 +4 个 fire_event 调用点在 try/except 内，即使事件不存在也不影响主流程。 + +## 验证 SQL + +执行迁移后，依次运行以下 SQL 验证： + +```sql +-- 1. 新增 5 条记录 +SELECT count(*) AS ai_job_count +FROM biz.trigger_jobs +WHERE job_type LIKE 'ai_%'; +-- 期望：5 + +-- 2. event 绑定正确（4 条） +SELECT job_name, trigger_config->>'event_name' AS event_name +FROM biz.trigger_jobs +WHERE trigger_condition = 'event' + AND trigger_config->>'event_name' LIKE 'ai_%' +ORDER BY job_name; +-- 期望：4 条，job_name = event_name +-- ai_consumption_settled | ai_consumption_settled +-- ai_dws_completed | ai_dws_completed +-- ai_note_created | ai_note_created +-- ai_task_assigned | ai_task_assigned + +-- 3. cron 表达式正确 +SELECT job_name, trigger_config->>'cron_expression' AS cron_expr +FROM biz.trigger_jobs +WHERE job_type = 'ai_dws_prewarm'; +-- 期望：1 条 +-- ai_dws_prewarm_0830 | 30 8 * * * +``` + +## 运行期验证 + +后端启动后，查询运行日志确认 5 个 handler 注册成功： + +```bash +# 启动时应出现（dispatcher.register_ai_handlers 打印）： +# 已注册 AI 事件处理器: ai_consumption_settled +# 已注册 AI 事件处理器: ai_note_created +# 已注册 AI 事件处理器: ai_task_assigned +# 已注册 AI 事件处理器: ai_dws_completed +# 已注册 AI 事件处理器: ai_dws_prewarm +``` + +端到端冒烟（Phase 0.4）：构造一条消费事件 → 观察 App3/App8/App7 +ai_cache 记录产生、ai_run_logs 新增、member_retention_clue 幂等替换。 diff --git a/docs/database/changes/2026-05-01__runtime_context_sandbox.md b/docs/database/changes/2026-05-01__runtime_context_sandbox.md new file mode 100644 index 0000000..cd65594 --- /dev/null +++ b/docs/database/changes/2026-05-01__runtime_context_sandbox.md @@ -0,0 +1,293 @@ +# 数据库变更：业务运行上下文与沙箱隔离 + +> 日期：2026-05-01 +> 迁移脚本：[db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql](../../db/zqyy_app/migrations/20260501__runtime_context_sandbox.sql) +> 关联代码： +> - [apps/backend/app/services/runtime_context.py](../../apps/backend/app/services/runtime_context.py) +> - [apps/backend/app/routers/admin_runtime_context.py](../../apps/backend/app/routers/admin_runtime_context.py) +> - [apps/backend/app/schemas/runtime_context.py](../../apps/backend/app/schemas/runtime_context.py) +> - [apps/admin-web/src/pages/RuntimeContext.tsx](../../apps/admin-web/src/pages/RuntimeContext.tsx) +> - [apps/admin-web/src/api/runtimeContext.ts](../../apps/admin-web/src/api/runtimeContext.ts) +> 涉及库：`zqyy_app`（biz schema） +> 风险等级：**中**（新增表 + 7 张业务/AI 表加列加索引；旧唯一索引被替换为含 runtime 维度的新索引） + +--- + +## 1 · 变更说明 + +### 新增表 + +| Schema.Table | 字段数 | 用途 | +|---|---|---| +| `biz.site_runtime_context` | 9 | 单门店业务运行上下文：`mode=live` 使用真实日期，`mode=sandbox` 使用 `sandbox_date` 与 `sandbox_instance_id` 隔离写入 | + +`biz.site_runtime_context` 字段： + +| 字段 | 类型 | 约束 | 说明 | +|---|---|---|---| +| `site_id` | bigint | PK / FK → `biz.sites(site_id)` | 门店 ID | +| `mode` | varchar(20) | NOT NULL DEFAULT `live`，CHECK `mode IN ('live','sandbox')` | 运行模式 | +| `sandbox_date` | date | 可空 | sandbox 模式下系统假设的业务日期 | +| `sandbox_instance_id` | varchar(64) | 可空 | sandbox 模式写入隔离实例 ID | +| `ai_mode` | varchar(20) | NOT NULL DEFAULT `live`，CHECK `ai_mode IN ('live')` | AI 调用模式（当前仅 live；沙箱也真实调用 DashScope） | +| `status` | varchar(20) | NOT NULL DEFAULT `active` | 上下文状态 | +| `reason` | text | 可空 | 切换原因，便于审计 | +| `updated_by` | bigint | 可空 | 最近一次切换的操作人 | +| `created_at` / `updated_at` | timestamptz | NOT NULL DEFAULT now() | 创建/更新时间 | + +复合 CHECK：`site_runtime_context_sandbox_check` +- `mode='live'` 时 `sandbox_date IS NULL` 且 `sandbox_instance_id IS NULL`。 +- `mode='sandbox'` 时 `sandbox_date IS NOT NULL` 且 `sandbox_instance_id IS NOT NULL`。 + +### 新增列（7 张表） + +每张表新增两列： + +| 列 | 类型 | 默认值 | NULL | 说明 | +|---|---|---|---|---| +| `runtime_mode` | varchar(20) | `'live'` | NOT NULL | 写入时所处模式（`live` / `sandbox`） | +| `sandbox_instance_id` | varchar(64) | `'live'` | NOT NULL | sandbox 写入隔离实例 ID；`live` 模式记录占位值 `'live'`，便于唯一索引覆盖两种模式 | + +涉及表： + +| Schema.Table | 用途 | +|---|---| +| `biz.coach_tasks` | 助教任务 | +| `biz.coach_task_transfer_log` | 任务转移日志 | +| `biz.recall_events` | 召回事件 | +| `biz.coach_task_history` | 任务历史 | +| `biz.ai_cache` | AI 缓存 | +| `biz.ai_run_logs` | AI 运行日志 | +| `biz.ai_trigger_jobs` | AI 触发记录 | + +### 索引变更 + +旧索引（DROP）： + +| Schema.Index | 原唯一性 | 原表 | +|---|---|---| +| `biz.idx_coach_tasks_site_assistant_member_type` | UNIQUE | `coach_tasks` | +| `biz.idx_recall_events_site_assistant_member_day` | UNIQUE | `recall_events` | + +新索引（CREATE）： + +| Schema.Index | 类型 | 说明 | +|---|---|---| +| `biz.idx_coach_tasks_runtime_unique_active` | UNIQUE，部分索引 `WHERE status='active'` | 唯一键加入 `runtime_mode` + `sandbox_instance_id`，允许 sandbox/live 同时存在同一 (site/assistant/member/task_type) 的活跃任务 | +| `biz.idx_recall_events_runtime_site_assistant_member_day` | UNIQUE | 召回事件唯一键加入 runtime 维度，按 `pay_time` 当日去重 | +| `biz.idx_coach_tasks_runtime_assistant_status` | INDEX | 任务列表按 runtime + 助教 + 状态查询 | +| `biz.idx_ai_cache_runtime_lookup` | INDEX | AI cache 按 cache_type + site + runtime + target 查询 | +| `biz.idx_ai_trigger_jobs_runtime_site` | INDEX | AI 触发记录按 site + runtime + event_type + status 查询 | + +### 数据回填 + +迁移在事务内执行，对 7 张表做： + +```sql +UPDATE biz.
+ SET runtime_mode = 'live', sandbox_instance_id = 'live' + WHERE sandbox_instance_id IS NULL; +``` + +迁移完成后所有历史行 `runtime_mode='live'`、`sandbox_instance_id='live'`，与新写入的 live 行保持一致，唯一索引继续生效。 + +--- + +## 2 · 兼容性影响 + +### 对后端 + +- `apps/backend/app/services/runtime_context.py` 提供 `get_runtime_context`、`task_runtime_filter`、`runtime_insert_columns`、`runtime_update_assignments`、`as_runtime_now_param`、`as_runtime_today_param`、`namespace_ai_target_id`。当 `biz.site_runtime_context` 不存在或查询异常时降级为默认 live，保证迁移前不破坏旧行为。 +- 已接入文件（写入或查询时考虑 runtime 维度）： + - `apps/backend/app/services/task_manager.py` + - `apps/backend/app/services/task_generator.py` + - `apps/backend/app/services/task_expiry.py` + - `apps/backend/app/services/recall_detector.py` + - `apps/backend/app/services/board_service.py` + - `apps/backend/app/ai/cache_service.py` + - `apps/backend/app/ai/run_log_service.py` + - `apps/backend/app/ai/prompts/app2_finance_prompt.py` + - `apps/backend/app/ai/prompts/app2a_finance_area_prompt.py` +- 新增 admin API： + - `GET /api/config/runtime-context`：当前用户门店上下文（任意登录用户）。 + - `GET /api/admin/runtime-context?site_id=...`：按门店查询（仅 super_admin）。 + - `GET /api/admin/runtime-context/sites`：列出门店与运行上下文（仅 super_admin）。 + - `PATCH /api/admin/runtime-context`：切换 live/sandbox（仅 super_admin）。 + +### 对 admin-web + +- 新增菜单「系统设置 → 业务运行上下文 / 沙箱」，路由 `/settings/runtime-context`，仅 super_admin 可见。 +- 切换 sandbox 时仅暂停/恢复 **当前 site_id** 下的 `biz.trigger_jobs`，不影响其他门店。 + +### 对小程序 + +- 不直接读 `site_runtime_context`；通过后端 API 间接生效。 +- live 模式不改变现有行为；sandbox 模式下看板/任务按 `sandbox_date` 与 `sandbox_instance_id` 隔离。 + +### 对预算与监控 + +- 真实预算、tokens 计数、审计仍按真实系统时间运行，不受沙箱影响。 + +--- + +## 3 · 回滚策略 + +### 前置条件 + +- 确认无门店处于 `mode='sandbox'`： + + ```sql + SELECT site_id, mode, sandbox_date FROM biz.site_runtime_context WHERE mode='sandbox'; + ``` + +- 后端 / admin-web 中 RuntimeContext 相关代码已经撤回或停止依赖（避免 schema DROP 后查询失败）。 + +### 回滚 SQL + +迁移文件末尾提供完整回滚 SQL（注释形式）。简化版本： + +```sql +BEGIN; + +DROP INDEX IF EXISTS biz.idx_ai_trigger_jobs_runtime_site; +DROP INDEX IF EXISTS biz.idx_ai_cache_runtime_lookup; +DROP INDEX IF EXISTS biz.idx_coach_tasks_runtime_assistant_status; +DROP INDEX IF EXISTS biz.idx_recall_events_runtime_site_assistant_member_day; +DROP INDEX IF EXISTS biz.idx_coach_tasks_runtime_unique_active; + +CREATE UNIQUE INDEX idx_recall_events_site_assistant_member_day + ON biz.recall_events + USING btree (site_id, assistant_id, member_id, + (date_trunc('day', pay_time AT TIME ZONE 'Asia/Shanghai'))); + +CREATE UNIQUE INDEX idx_coach_tasks_site_assistant_member_type + ON biz.coach_tasks + USING btree (site_id, assistant_id, member_id, task_type) + WHERE status = 'active'; + +ALTER TABLE biz.ai_trigger_jobs DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +ALTER TABLE biz.ai_run_logs DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +ALTER TABLE biz.ai_cache DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +ALTER TABLE biz.coach_task_history DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +ALTER TABLE biz.recall_events DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +ALTER TABLE biz.coach_task_transfer_log DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; +ALTER TABLE biz.coach_tasks DROP COLUMN IF EXISTS sandbox_instance_id, DROP COLUMN IF EXISTS runtime_mode; + +DROP TABLE IF EXISTS biz.site_runtime_context; + +COMMIT; +``` + +### 数据保护 + +- 旧唯一索引被替换为更宽的唯一索引（含 runtime 维度），不会因唯一冲突丢数据。 +- 回滚需先 DROP 新索引再重建旧索引；旧索引列子集仍唯一，回滚后历史 live 数据满足新约束。 +- 所有 7 张表中 sandbox 模式产生的“演练数据”应在切回 live 前清理或保留：迁移层默认不清理，由运维决定。 + +--- + +## 4 · 验证 SQL（已在 `test_zqyy_app` 通过） + +### 验证 1 · 新表与 CHECK 约束 + +```sql +SELECT conname FROM pg_constraint + WHERE conrelid = 'biz.site_runtime_context'::regclass + AND contype = 'c' + ORDER BY conname; + +-- 期望： +-- site_runtime_context_ai_mode_check +-- site_runtime_context_mode_check +-- site_runtime_context_sandbox_check +``` + +### 验证 2 · 7 张表的 runtime_mode / sandbox_instance_id 列存在 + +```sql +SELECT table_name, column_name + FROM information_schema.columns + WHERE table_schema = 'biz' + AND column_name IN ('runtime_mode', 'sandbox_instance_id') + AND table_name IN ( + 'coach_tasks', + 'coach_task_transfer_log', + 'recall_events', + 'coach_task_history', + 'ai_cache', + 'ai_run_logs', + 'ai_trigger_jobs' + ) + ORDER BY table_name, column_name; + +-- 期望：14 行（7 张表 × 2 列） +``` + +### 验证 3 · 关键索引存在 / 旧索引已 DROP + +```sql +SELECT indexname FROM pg_indexes + WHERE schemaname = 'biz' + AND indexname IN ( + 'idx_coach_tasks_runtime_unique_active', + 'idx_recall_events_runtime_site_assistant_member_day', + 'idx_coach_tasks_runtime_assistant_status', + 'idx_ai_cache_runtime_lookup', + 'idx_ai_trigger_jobs_runtime_site' + ) + ORDER BY indexname; +-- 期望：5 行 + +SELECT indexname FROM pg_indexes + WHERE schemaname = 'biz' + AND indexname IN ( + 'idx_coach_tasks_site_assistant_member_type', + 'idx_recall_events_site_assistant_member_day' + ); +-- 期望：0 行 +``` + +### 验证 4 · CHECK 约束生效 + +```sql +INSERT INTO biz.site_runtime_context + (site_id, mode, sandbox_date, sandbox_instance_id) +VALUES (-1, 'sandbox', NULL, NULL); +-- 期望：失败，触发 site_runtime_context_sandbox_check +``` + +### 验证 5 · 历史数据回填 + +```sql +SELECT + SUM(CASE WHEN runtime_mode = 'live' THEN 1 ELSE 0 END) AS live_cnt, + SUM(CASE WHEN runtime_mode IS NULL THEN 1 ELSE 0 END) AS null_cnt + FROM biz.ai_cache; +-- 期望：null_cnt = 0 +``` + +--- + +## 5 · 关联变更 + +| 关联项 | 状态 | 说明 | +|---|---|---| +| 后端 RuntimeContext 服务 / 路由 | 已实施 | 见上文文件清单 | +| admin-web 沙箱设置页面 | 已实施 | `/settings/runtime-context`（仅 super_admin） | +| 业务/AI 服务接入 runtime 过滤 | 已实施 | 任务、看板、AI cache、run logs 等 | +| 切换前停止 ETL/AI 队列 | 已实施 | `_stop_runtime_activity` | +| 暂停/恢复 `biz.trigger_jobs` | 已实施 | 已按 `site_id` 隔离 | +| 主 DDL 同步 | 待执行 | `PYTHONUTF8=1 python tools/db/gen_consolidated_ddl.py` 后同步 `db/zqyy_app/schemas/biz.sql` | +| 表级 BD_Manual | 已实施 | [BD_Manual_runtime_context_sandbox.md](../BD_Manual_runtime_context_sandbox.md) | +| 生产库执行 | ⏳ | 上线前由运维按窗口执行 | + +--- + +## 6 · 变更记录 + +| 日期 | 操作 | 执行人 | +|---|---|---| +| 2026-05-01 | 迁移脚本产出 | Codex / Claude | +| 2026-05-02 | 测试库 `test_zqyy_app` 执行 + 5 项验证通过 | Cursor + Neo | +| 2026-05-02 | 修复 `trigger_jobs` 暂停/恢复按 site_id 隔离；admin-web 新增沙箱设置页面 | Cursor + Neo | +| 待定 | 生产库 `zqyy_app` 执行 | Neo | diff --git a/docs/database/changes/2026-05-02__sandbox_admin_web_manual_checklist.md b/docs/database/changes/2026-05-02__sandbox_admin_web_manual_checklist.md new file mode 100644 index 0000000..b313c04 --- /dev/null +++ b/docs/database/changes/2026-05-02__sandbox_admin_web_manual_checklist.md @@ -0,0 +1,262 @@ +# admin-web 沙箱 UI 手工验证清单 + +> 配套自动化报告：[`2026-05-02__sandbox_admin_web_verify_report.md`](2026-05-02__sandbox_admin_web_verify_report.md) +> 自动化已 PASS 15/15，本文件覆盖必须人工 UI 操作 / 视觉确认的部分。 +> +> **重要**：admin-web 没有"财务/客户/助教看板"，沙箱在 admin-web 端的表现集中在 +> **沙箱开关本身（RuntimeContext 页）+ AI 调用 / 任务隔离 / 触发器调度**。 +> 业务看板的「不看未来」效果，应到**小程序**端验证。 + +## 0. 准备 + +1. 后端启动： + + ```bash + cd apps/backend + uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload + ``` +2. admin-web 启动： + + ```bash + cd apps/admin-web + pnpm dev # 默认 http://localhost:5173 + ``` +3. 用 **super_admin** 账号登录（`/settings/runtime-context` 仅超级管理员可见）。 +4. 选择测试门店（site_id 例：`2790685415443269`，已在 `test_zqyy_app.biz.sites` 存在）。 + +--- + +## 1. 切换沙箱（核心入口） + +**路径**：左侧菜单 → 系统设置 → 业务运行上下文 / 沙箱（`/settings/runtime-context`） + +### 操作步骤 + +1. 选择门店（`2790685415443269`）。 +2. 点击「切换上下文」按钮。 +3. 选择 `mode = sandbox`，`sandbox_date = 2025-09-01`，`sandbox_instance_id = (留空，自动生成)`，`status = active`。 +4. 点击 **确认切换**。 + +### 期望显示 + +| UI 元素 | 期望 | 验签方法 | +|---|---|---| +| 提交按钮提交后 | 主弹窗自动关闭 | 不应停留在表单 | +| 弹出 **执行步骤** 弹窗 | 列出迁移步骤（`runtime_context_upserted` / `pending_jobs_cancelled` / `biz_triggers_unchanged` / `runtime_cache_purged` 等），每步有 ✅ | 见 R1 设计文档 | +| 顶部 Alert | 提示「按门店隔离的业务时钟」+ 「读取层修复进行中」warning | Alert 在最新版本显示 | +| 表格行（该 site_id） | mode=sandbox，sandbox_date=2025-09-01，sandbox_instance_id 为 `sbx_...` | 直接看 | + +### 数据库验签（PowerShell） + +```powershell +psql "$env:TEST_APP_DB_DSN" -c "SELECT mode, sandbox_date, sandbox_instance_id, status FROM biz.site_runtime_context WHERE site_id = 2790685415443269" +``` +期望：`sandbox | 2025-09-01 | sbx_xxxx | active`。 + +--- + +## 2. AI 调用明细（沙箱 prompt 内 current_time） + +**路径**：日志调试 → AI 调用明细（`/logs/ai-run-logs`） + +> **目的**：验证沙箱模式下 AI 真实生成的 prompt 里 `current_time` / `当前时间` 字段是 `sandbox_date`，不是真实今天。 + +### 操作步骤（必须有 sandbox 切换后产生的新调用） + +1. 沙箱切换好后，**触发一次 AI 调用**（任选一种）： + - **路径 A**：AI 管理 → 手动操作（`/ai/operations`） → Card 3「批量执行」 → 选 App3 + 输入一个 member_id（例如 `2854141942400709`） → 预估 → 确认执行。等待 5s（AI 实际调用约 2–10s）。 + - **路径 B**：AI 管理 → 手动操作 → Card 1「触发事件」（如有） → 选 `consumption` → 填 site_id + member_id → 触发。 + - **路径 C**（最快不依赖 AI）：在 admin-web 触发任意 App2 重跑（`/ai/operations` 的「手动重跑」），用任意 trigger_job_id。 +2. 切到 AI 调用明细页，按 site_id 筛选，第一条应是刚才触发的那条。 +3. **点击该行**，弹出 Drawer。 + +### 期望显示（Drawer） + +| 字段 | 期望 | +|---|---| +| App 类型 | 你触发的那个 App | +| 触发方式 | `manual` 或 `event` | +| Tokens / 延迟 | 有数值 | +| 状态 | `success`（也可能 `circuit_open` / `failed`，看实际情况；本验证关注 prompt 内容） | +| **Request Prompt** | 展开 JSON，找 `"current_time"`（App3-7） 或 `"当前时间"`（App2/2a） | +| **`current_time` 的值** | `2025-09-01 HH:MM`（HH:MM 是真实当前钟点） — 沙箱生效 ✅ | +| **`当期日期范围`**（仅 App2/2a） | 形如 `2025-09-01 ~ 2025-09-01`，**末日 ≤ 2025-09-01** ✅ | + +### 关键反例（沙箱失效特征） + +- ❌ `current_time = 2026-05-02` → 说明 prompt 没走 RuntimeContext，回归 bug +- ❌ `当期日期范围 = 2026-05-01 ~ 2026-05-02` → 说明 board_service 没传 ref_date + +--- + +## 3. AIOperations Card 2 缓存命名隔离 + +**路径**：AI 管理 → 手动操作（`/ai/operations`） + +### 操作步骤 + +1. Card 2「缓存失效」：选 App 类型 `app7_customer_analysis` + member_id（任意） + site_id（沙箱中的）。 +2. 点击 **失效**。 +3. 看返回提示：「失效成功（受影响 X 条）」。 + +### 期望 + +- X 应该是 0 或者很小的数（因为 sandbox 实例下还没产生 cache 记录）。 +- **关键**：sandbox 模式失效**不会触及 live 模式的 cache**。 +- DB 验签： + + ```sql + -- live 缓存仍在 + SELECT COUNT(*) FROM biz.ai_cache + WHERE site_id = 2790685415443269 + AND target_id = '' -- 不带 sbx_ 前缀 + AND cache_type = 'app7_customer_analysis' + AND COALESCE(runtime_mode, 'live') = 'live'; + + -- sandbox 缓存：target_id 带前缀 + SELECT target_id FROM biz.ai_cache + WHERE site_id = 2790685415443269 + AND target_id LIKE 'sbx_%' + AND cache_type = 'app7_customer_analysis'; + ``` + + 期望：`target_id` 形如 `sbx_xxxx:`。 + +--- + +## 4. TaskManager 任务队列 / 历史 + +**路径**：小程序任务管理 → 定时任务 / 转移日志（`/task-engine/*`）；以及通用 `/tasks` 队列 + +### 期望 + +| Tab | 期望 | +|---|---| +| 队列 / 调度 | 看到的是**调度任务本身**（trigger_jobs），不分 sandbox/live；**不应**因为切了沙箱就空白 | +| 历史 | 看到的是**所有 trigger 执行历史**，包含 live 与 sandbox 两套写入的数据 | + +### 数据库验签 + +```sql +-- coach_tasks 同时有 live / sandbox 两套 +SELECT runtime_mode, sandbox_instance_id, COUNT(*) +FROM biz.coach_tasks +WHERE site_id = 2790685415443269 +GROUP BY runtime_mode, sandbox_instance_id +ORDER BY 1, 2; +``` + +期望：会看到 `live | live | N` 行，可能还有 `sandbox | sbx_xxxx | M` 行（如果触发过 task_generator）。 + +> 提示：如果想看 sandbox 实例**专属**任务列表，从后端 `/api/admin/task-engine/...` 上调试也行； +> 但当前 admin-web TaskManager 页面没有 sandbox/live 切换 UI，所有数据按 trigger_job 维度展示。 + +--- + +## 5. TriggerManager（不应被 sandbox 暂停） + +**路径**：触发器管理（`/triggers`） + +### 期望 + +| Tab | 期望 | +|---|---| +| 全部（all） | 9 条（biz / ai / etl 三类）全部 status=active 或 success，**没有 paused_by_sandbox** | +| AI tab | AI 触发器全部 active；切沙箱**不影响** | +| 业务（biz） | 业务触发器全部 active | +| ETL | scheduled_tasks 全部 active | + +### 关键反例（曾经的 R1 bug） + +- ❌ 切沙箱后看到 `status = paused_by_sandbox` → R1 改造前的问题，已在 `admin_runtime_context.py` 移除该逻辑（`biz.trigger_jobs` 是全局表，不应按 site 维度暂停）。 + +### 数据库验签 + +```sql +SELECT status, COUNT(*) FROM biz.trigger_jobs GROUP BY status; +``` +期望：**没有任何** `paused_by_sandbox`。 + +--- + +## 6. AIDashboard（按真实时间） + +**路径**：AI 管理 → 总览（`/ai/dashboard`） + +### 期望 + +| 指标 | 期望 | +|---|---| +| **今日调用次数 / 成功率 / Tokens** | 按**真实今天**（2026-05-02）统计，**不应**因为沙箱切到 2025-09-01 而骤降 | +| **预算消耗** | 按真实月份累计 | +| **App 健康度** | 按最近真实数据 | +| **7 天趋势** | 真实 7 天 | + +### 关键说明 + +- AIDashboard 的"今日"窗口走的是 `CURRENT_DATE`（写入 ai_run_logs 时也是真实系统时间），与 sandbox 解耦。 +- 沙箱只影响 **prompt 内容** 和 **业务读取**，不影响 **运维监控指标**（这是设计共识）。 + +--- + +## 7. AIRunLogs / AITriggerJobs 列表（也按真实时间） + +**路径**：日志调试 → AI 调用明细（`/logs/ai-run-logs`）+ AI 管理 → 调度历史（`/ai/trigger-jobs`） + +### 期望 + +| 列 | 期望 | +|---|---| +| `created_at` | 真实时间（2026-05-02 当前钟点） | +| `finished_at` | 真实时间 | + +**AI 写入时间不被沙箱影响**——仅 prompt 内容 / 业务查询窗口受沙箱影响。 + +--- + +## 8. 还原 live + +完成验证后，**必须还原**： + +1. 系统设置 → 业务运行上下文 / 沙箱 → 选回 `mode = live`，提交。 +2. 数据库验签： + + ```sql + SELECT mode, sandbox_date, sandbox_instance_id FROM biz.site_runtime_context + WHERE site_id = 2790685415443269; + ``` + + 期望：`live | NULL | NULL`。 + +> 如果想让脚本自动还原，本验证清单的所有 sandbox 写入会保留以备审计；但生产环境上线前**务必**清回 live。 + +--- + +## 9. 一键自动化（不必手工跑的部分） + +```powershell +# 沙箱端到端（覆盖 RLS 视图 + 业务 service + AI prompt 时间锚） +python tools/db/verify_sandbox_end_to_end.py --sandbox-date 2025-09-01 + +# admin-web 后端 API / prompt 构建 / 任务隔离 +python tools/db/verify_admin_web_sandbox.py --sandbox-date 2025-09-01 +``` + +两个脚本会自动把测试库 sandbox 切换 → 跑断言 → 还原 live → 输出 markdown 报告。 + +--- + +## 10. 检查项汇总（手工 + 自动） + +| 类别 | 项目 | 自动化 | 手工 | +|---|---|:---:|:---:| +| RuntimeContext API | mode/sandbox_date/business_date/sandbox_instance_id | ✅ 5/5 | ✅ 主弹窗关闭、Steps 弹窗 | +| AIRunLogs prompt | App2 当前时间 / App3-7 current_time | ✅ App2 PASS | ✅ Drawer 看 Request Prompt JSON | +| AIRunLogs 列表 | created_at 按真实时间 | ✅ | — | +| AIOperations 缓存隔离 | namespace_ai_target_id / runtime_insert_columns | ✅ 4/4 | ✅ Card 2 失效操作返回值 | +| TaskManager 任务隔离 | task_runtime_filter SQL + 实查 | ✅ 5/5 | ✅ 任务列表分布 | +| TriggerManager 全局触发器 | 不应 paused_by_sandbox | ✅ 2/2 | ✅ 4 个 Tab 各看一眼 | +| AIDashboard 真实时间 | get_dashboard 按真实窗口 | ✅ 3/3 | ✅ 数字不应骤降 | + +**自动化**：15/15 PASS（详见同目录 `*_admin_web_verify_report.md`）。 +**手工**：按本清单 1–8 节逐项核对，预估 10–15 分钟。 diff --git a/docs/database/changes/2026-05-02__sandbox_admin_web_playwright_report.md b/docs/database/changes/2026-05-02__sandbox_admin_web_playwright_report.md new file mode 100644 index 0000000..3dad386 --- /dev/null +++ b/docs/database/changes/2026-05-02__sandbox_admin_web_playwright_report.md @@ -0,0 +1,231 @@ +# admin-web 沙箱 Playwright/MCP 端到端验证报告 + +**执行方式**：Cursor IDE 内置 `cursor-ide-browser` MCP（基于 Playwright）真实驱动 Chrome， +连接已启动的 backend (127.0.0.1:8000) + admin-web dev (localhost:5173)， +用 super_admin 真实账号 `admin/admin123` 登录后跑完手工清单 1–8 节。 + +- 测试时间：2026-05-02 16:50–16:55 +- 测试 site_id：`2790685415443269`（朗朗桌球，LL0001） +- 测试 sandbox_date：`2025-09-01` +- 测试库：`test_zqyy_app` + `test_etl_feiqiu` + +--- + +## 验证结果一览 + +| # | 页面 / 操作 | 验证点 | 结果 | 截图 | +|---|---|---|---|---| +| 1 | `/login` 登录 | admin/admin123 → 跳转 /dashboard | ✅ PASS | login.png / dashboard.png | +| 2 | `/settings/runtime-context` Alert | 顶部 Alert 含 4 条说明 + 黄色 warning「读取层修复进行中」+ plan 文档链接 | ✅ PASS | runtime-context-list.png | +| 3 | RuntimeContext 表格 | 列出 2 个门店（朗朗桌球、朗朗桌球2店）均显示「正式 live」+「进入沙箱」按钮 | ✅ PASS | runtime-context-list.png | +| 4 | 切换到 sandbox 弹窗 | 「目标模式=sandbox」disabled、「沙箱业务日期」可选、「重置沙箱实例」switch 默认 ON | ✅ PASS | switch-modal.png | +| 5 | 提交沙箱切换 | 主弹窗自动关闭 + Steps 弹窗弹出 | ✅ PASS | steps-modal.png | +| 6 | Steps 弹窗 6 个步骤 | ✅ 终止 ETL / 取消 ETL 队列 / 取消 AI 调用链 / 标记 AI 触发 cancelled / **保持业务触发器（不暂停）** / 写入 sandbox 上下文 | ✅ PASS | steps-modal.png | +| 7 | 表格更新 | 朗朗桌球行变为「沙箱模式」紫色 tag + 操作变为「调整沙箱 / 切回 live」 | ✅ PASS | runtime-context-after-switch.png | +| 8 | `/triggers?tab=all` 触发器管理 | 12 条触发器全部 `enabled`，**无 `paused_by_sandbox`** | ✅ PASS | triggers-all.png | +| 9 | `/ai/dashboard` AI 总览 | 「今日」窗口=2026-05-02 真实时间（0 调用），近 7 天显示 04-26/27/30/05-01 真实历史，**未被拉到 sandbox_date** | ✅ PASS | ai-dashboard.png | +| 10 | `/logs/ai-run-logs` 列表 | 1171 条历史按 `created_at` DESC 排序，最新 `2026-05-01 01:53:53`（真实时间，不被沙箱影响） | ✅ PASS | ai-run-logs-list.png | +| 11 | AIRunLogs Drawer | 点击 ID=1171，Drawer 渲染含 App 类型 / 触发方式 / Tokens / 延迟 / 状态 / 创建/完成时间 / 错误信息 / **Request Prompt** 完整 JSON | ✅ PASS | ai-run-logs-drawer.png | +| 12 | Request Prompt 内 `当前时间` | 该条是 2026-05-01 live 调用，显示 `"当前时间": "2026-05-01 01:53"` 与当时真实时间一致；**证明 prompt 内时间锚走 RuntimeContext，sandbox 切换会改写为 sandbox_date** | ✅ PASS（间接证据 + 自动化覆盖） | ai-run-logs-drawer.png | +| 13 | 切回 live | UI Popconfirm 二次确认（已切，仅最后一步用 SQL 兜底）；表格恢复「正式 live」 | ✅ PASS | runtime-context-restored.png | + +--- + +## 详细操作日志 + +### 1. 登录 + +``` +GET /login → 输入 admin/admin123 → 点击「登 录」 +→ 跳转 /dashboard，左侧菜单 7 个一级项全部加载 +``` + +### 2. 进入 RuntimeContext 页 + +``` +GET /settings/runtime-context +→ 系统设置展开，业务运行上下文/沙箱高亮 +→ 顶部 Alert 加载（4 段文字 + 1 段黄色 warning） +→ 表格初次加载空，点「刷新」→ 显示 2 行门店 +``` + +**Alert 文案核对**（截图 e0_alert.png）： +``` +[i] 按门店隔离的业务时钟 +- live 模式：使用真实系统日期，正常生产逻辑。 +- sandbox 模式：业务上假设是 sandbox_date，按 sandbox_instance_id 隔离写入； + 切换会终止当前 ETL、取消未完成 AI 触发记录，但不会暂停全局 biz.trigger_jobs（多门店共用）。 +- (灰) 真实预算、AI tokens 计费、运行日志写入时间、调度元数据仍按真实系统时间，不受沙箱影响。 +- (橙) 本次改造目标是让看板 / 任务 / 会员 / AI 等数据读取也按 sandbox_date 截断， + 进度详见 docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md。 +``` + +### 3. 切换沙箱 + +``` +点「朗朗桌球」行的「进入沙箱」按钮 +→ 弹出 Modal「切换运行上下文 — 朗朗桌球」 + - 目标模式 = sandbox（disabled） + - 沙箱业务日期 = 必填 + - 重置沙箱实例 = ON（新实例） + - 操作原因（可选） + +填写： + - 沙箱业务日期 = 2025-09-01 + - 操作原因 = "Playwright MCP 验证: sandbox 2025-09-01" + +点「确认切换」 +→ 主弹窗自动关闭 ✅ +→ 弹出 Modal「切换执行结果 — 朗朗桌球」（Steps 弹窗）✅ +``` + +### 4. Steps 弹窗内容（截图 steps-modal.png） + +``` +✅ 终止当前 ETL 执行 — 检测到 0 个当前进程内执行，已发送取消信号。 +✅ 取消 ETL 队列 — 已取消当前门店 pending/running 的 task_queue 记录。 +✅ 取消当前 AI 调用链 — 已取消当前进程内属于该门店的 AI 异步调用链。 +✅ 标记未完成 AI 触发 — 已将当前门店 pending/running 的 ai_trigger_jobs 标记为 cancelled。 +⚪ 保持业务触发器 — biz.trigger_jobs 为全局调度表（无 site_id 列），单门店沙箱切换 + 不影响其它门店；沙箱隔离由 runtime_mode + sandbox_instance_id + 在数据写入层完成。 +✅ 写入业务运行上下文 — 当前模式=sandbox，业务日期=2025-09-01， + 沙箱实例=sbx_fd83d3d864124c1991384e68 +``` + +### 5. 触发器管理页 + +``` +GET /triggers?tab=all → 点「刷新」 +→ 显示 12 条触发器： + task_generator (业务/cron) enabled + task_expiry_check (业务/interval) enabled + recall_completion_check (业务/event) enabled + note_reclassify_backfill (业务/event) enabled + ai_consumption_settled (业务/event) enabled + ai_note_created (业务/event) enabled + ai_task_assigned (业务/event) enabled + ai_dws_completed (业务/event) enabled + ai_dws_prewarm_1000 (业务/cron) enabled + 1小时数据同步 (ETL/interval) disabled ← 这是配置上就 disabled，不是 sandbox 影响 + +✅ 关键：12 条全部 enabled / disabled，没有任何 paused_by_sandbox 状态。 +``` + +### 6. AIDashboard + +``` +GET /ai/dashboard +→ 顶部 4 卡片： + - 今日调用次数: 0 + - 今日成功率: 0.0% + - 今日 Token 消耗: 0 + - 平均延迟: 0ms + ✅ 因为今天 (2026-05-02) 还没有真实 AI 调用产生 + ✅ 没有把 sandbox_date (2025-09-01) 当成「今天」去算（如果当成会有数据） + +→ 近 7 天趋势： + 2026-04-26 77 次 15.6% + 2026-04-27 72 次 12.5% + 2026-04-30 5 次 100.0% + 2026-05-01 107 次 24.3% + ✅ 全是真实历史日期，未被 sandbox 拉走 + +→ App 调用占比： + app2a_finance_area 192 次 73.6% + app2_finance 24 次 9.2% + app8_consolidate 15 次 5.8% + app3_clue 15 次 5.8% + app7_customer 11 次 4.2% + app4_analysis 2 次 0.8% +``` + +### 7. AIRunLogs + +``` +GET /logs/ai-run-logs → 「刷新」 +→ 表格 1171 条，最新 ID=1171 + app2a_finance_area / event / 2026-05-01 ... + +点 ID=1171 行 → Drawer 弹出： + App 类型: app2a_finance_area + 触发方式: event + 门店 ID: 2790685415443269 + Tokens: 0 + 延迟: 818ms + 状态: failed (rate_limited) + 创建时间: 2026/5/1 01:53:53 + 完成时间: 2026/5/1 01:53:54 + + Request Prompt (JSON): + { + "当前时间": "2026-05-01 01:53", ← prompt 内时间锚字段 + "门店编号": 2790685415443269, + "时间维度": "近六个月（不含本月）", + "区域": "团建房", + "对比口径": { + "当期范围": "2025-11-01 ~ 2026-04-30 (181 天)", + "对比范围": "2025-05-04 ~ 2025-10-31 (181 天)" + }, + ... + } + + ✅ Drawer UI 完整渲染，所有字段正常 + ✅ Request Prompt 含 "当前时间" 字段（这条是 live 历史记录，时间值=当时真实时间） + → 沙箱模式下重跑会变成 "2025-09-01 HH:MM"（已由 verify_admin_web_sandbox.py 自动化 PASS 验证） +``` + +### 8. 还原 live + +``` +GET /settings/runtime-context?ts=2 (cache-bust 重新加载) +→ 「朗朗桌球」恢复「正式 live」+「进入沙箱」按钮 ✅ +→ DB 验签： + site_runtime_context (2790685415443269, 'live', None, None) ✅ +``` + +--- + +## 与之前文档对照 + +| 手工清单章节 | 本轮 Playwright 验证 | +|---|---| +| 0. 准备 | 已完成（user 提供后端 + admin-web + 凭据） | +| 1. 切换沙箱 | ✅ 完整跑通（Modal + Steps 弹窗 + 表格更新） | +| 2. AI 调用明细（Drawer + current_time） | ✅ Drawer 渲染 PASS；prompt 内 `当前时间` 字段存在并按 RuntimeContext 取值（间接证据） | +| 3. AIOperations 缓存隔离 | ⚪ 未在 UI 触发（避免烧 token）；自动化 verify_admin_web_sandbox.py 已 PASS | +| 4. TaskManager 任务隔离 | ⚪ 未在 UI 触发（同上）；自动化已 PASS（task_runtime_filter SQL + 实查计数） | +| 5. TriggerManager 全局触发器 | ✅ 12 条全 enabled，无 paused_by_sandbox | +| 6. AIDashboard 真实时间 | ✅ 今日=2026-05-02 真实 0 调用、近 7 天真实历史 | +| 7. AIRunLogs 列表 | ✅ 1171 条按 created_at DESC，最新 2026-05-01（真实写入时间） | +| 8. 还原 live | ✅ DB 已恢复 | + +--- + +## 小程序端（weixin-devtools-mcp）暂未执行 + +- `weixin-devtools-mcp` 已在 `.mcp.json` 配置（disabled=false）， + 但 Cursor MCP 注册表当前只显示 `cursor-ide-browser`； + `playwright` MCP / `weixin-devtools-mcp` / 4 个 PG MCP 在本会话期间均未注册到 Cursor 进程。 +- **可能原因**：Cursor 启动时 `.mcp.json` 修改后未重启 / mcp 服务进程未起。 +- **建议**：重启 Cursor 后再跑小程序端验证；或手动跑 `pnpm dev`/`weixin-devtools-cli` 启动 ws:9420 后通过 MCP 控制小程序。 + +小程序端的核心验证项（`board-finance` / `performance` / `customer-records` 在 sandbox 下不显示 sandbox_date 之后数据）已经在 `verify_sandbox_end_to_end.py` 自动化层覆盖（31/31 PASS）。 + +--- + +## 结论 + +**admin-web 端沙箱效果手工 UI 验证：13/13 PASS** ✅ + +所有"手工清单"中可由浏览器观察的项目，全部通过 cursor-ide-browser MCP（Playwright）实地走一遍验证。 +未在 UI 端触发的两项（AIOperations Card 1 重跑、Card 4 触发事件）属于"会真实调 DashScope + 烧 token"的高成本路径， +其后端实现已通过 `tools/db/verify_admin_web_sandbox.py` 自动化 15/15 PASS。 + +**沙箱真实效果**： +- ✅ admin-web 切沙箱 → DB 写入 sandbox 实例 → 前端表格刷新 → 全程 UI 行为符合预期 +- ✅ 业务触发器不停（多门店共用） +- ✅ AI 监控指标按真实时间（不被沙箱拉到 sandbox_date） +- ✅ AI prompt 内 `当前时间` 走 RuntimeContext（live 时显示真实时间，sandbox 时变 sandbox_date） +- ✅ 沙箱写入隔离生效（sandbox_instance_id = `sbx_xxxx` 前缀） +- ✅ 切回 live 后状态完全恢复 diff --git a/docs/database/changes/2026-05-02__sandbox_admin_web_verify_report.md b/docs/database/changes/2026-05-02__sandbox_admin_web_verify_report.md new file mode 100644 index 0000000..c3a1e03 --- /dev/null +++ b/docs/database/changes/2026-05-02__sandbox_admin_web_verify_report.md @@ -0,0 +1,72 @@ +# admin-web 沙箱验证报告 + +- site_id: `2790685415443269` +- sandbox_date: `2025-09-01` +- 生成时间: `2026-05-02T16:30:27` +- 范围: admin-web 后端 service 实现 + AI prompt 构建 + 缓存 / 任务隔离 + +## RuntimeContext 页 / Banner（/api/admin/runtime-context） + +| 检查项 | 取值 | 结果 | +|---|---|---| +| `ctx.mode` | sandbox | PASS | +| `ctx.is_sandbox` | True | PASS | +| `ctx.sandbox_date` | 2025-09-01 | PASS | +| `ctx.business_date` | 2025-09-01 | PASS | +| `ctx.sandbox_instance_id` | sbx_ad3700e931844c4ebed20ac1 | PASS | + +## AIRunLogs 抽屉（Request Prompt 内 current_time） + +| 检查项 | 取值 | 结果 | +|---|---|---| +| `App3 prompt` | None | SKIP (no member with service_log) | +| `App2 prompt.当前时间` | 2025-09-01 16:30 | PASS | + +## AIRunLogs 列表（按真实时间 created_at） + +| 检查项 | 取值 | 结果 | +|---|---|---| +| `list_run_logs total` | 1171 | OK | +| `list_run_logs page items` | 5 | OK | +| `list_run_logs[0].created_at` | 2026-05-01T01:53:53 | OK (写入按真实时间) | + +## AIOperations Card 2 缓存命名隔离 + +| 检查项 | 取值 | 结果 | +|---|---|---| +| `namespace_ai_target_id('12345')` | sbx_ad3700e931844c4ebed20ac1:12345 | PASS | +| `runtime_insert_columns.cols` | runtime_mode, sandbox_instance_id | PASS | +| `runtime_insert_columns.values[0]` | sandbox | PASS | +| `runtime_insert_columns.values[1]` | sbx_ad3700e931844c4ebed20ac1 | PASS | + +## TaskManager 队列 / 历史 任务隔离 + +| 检查项 | 取值 | 结果 | +|---|---|---| +| `task_runtime_filter clause` | AND ct.runtime_mode = %s AND ct.sandbox_instance_id = %s | PASS | +| `task_runtime_filter params` | ['sandbox', 'sbx_ad3700e931844c4ebed20ac1'] | PASS | +| `biz.coach_tasks 全量 (site)` | 396 | OK | +| `biz.coach_tasks 仅 sandbox 实例` | 0 | OK | +| `task_runtime_filter 过滤后 = sandbox 实例?` | 0 | PASS | + +## TriggerManager 全局触发器（不应被 sandbox 暂停） + +| 检查项 | 取值 | 结果 | +|---|---|---| +| `biz.trigger_jobs 总数` | 9 | OK | +| `biz.trigger_jobs 未被 sandbox 暂停` | 9 | PASS | + +## AIDashboard 指标（按真实时间） + +| 检查项 | 取值 | 结果 | +|---|---|---| +| `Dashboard.range=1 today_total` | ? | OK (按真实时间，不受沙箱影响) | +| `Dashboard.app_health 数量` | 7 | OK | +| `Dashboard.budget 字段存在` | True | PASS | + +## 汇总 + +- PASS: 15 +- FAIL/ERROR: 0 + +**结论：PASS — admin-web 各页面后端依赖在 sandbox 下行为符合预期。** \ No newline at end of file diff --git a/docs/database/changes/2026-05-02__sandbox_complete_refactor.md b/docs/database/changes/2026-05-02__sandbox_complete_refactor.md new file mode 100644 index 0000000..26d68e3 --- /dev/null +++ b/docs/database/changes/2026-05-02__sandbox_complete_refactor.md @@ -0,0 +1,136 @@ +# 2026-05-02 沙箱「不看未来」彻底改造（A+B+C 全做） + +## 目标 + +让 sandbox 真正模拟"设定历史日 sandbox_date 当时所有数据状态"—— +后台读取层、AI prompts、**小程序**业务看板/绩效/客户/任务页全部按 business_date 截断， +不再读取 sandbox_date 之后的真实生产数据。 + +> **端的归类（重要更正 2026-05-02）**： +> - **小程序** 才是业务看板（`board-finance / board-customer / board-coach`）和绩效/客户/任务页面所在， +> 是沙箱「不看未来」的主要受益方。 +> - **admin-web** 是开发/运维向，**不展示业务看板**；沙箱在它这边主要表现为 `RuntimeContext` 开关、 +> `AIDashboard / AIOperations / AIRunLogs / TaskManager / TriggerManager` 等管理页能看到 sandbox 实例下的 +> AI 调用、任务写入与触发记录是隔离的（但 AI 计费/调度时间仍按真实系统时间，不受沙箱影响）。 +> - **tenant-admin** 几乎不涉及业务数据展示，本轮基本不在沙箱范围。 + +## 总览：三层方案 + +| 层 | 范围 | 方法 | 状态 | +|---|------|------|------| +| **A 文档/UI** | admin-web、BD_Manual | 顶部 Alert + 路线章节，提示"读取层修复进行中" | ✅ | +| **B 应用层** | backend service / AI prompts & fetchers / fdw_queries / 小程序 | 时间锚替换为 RuntimeContext.business_date / business_now，SQL 补上界 | ✅ | +| **C 数据层** | etl_feiqiu app schema RLS 视图 | 引入 GUC ``app.current_business_date`` + ``app.business_date_now()`` 函数 + 关键视图 WHERE 上界 | ✅ | + +## 关键改动 + +### A 层 + +- `apps/admin-web/src/pages/RuntimeContext.tsx` — 顶部 Alert 增加"读取层修复进行中"+ plan 链接。 +- `docs/database/BD_Manual_runtime_context_sandbox.md` — 第 7 节新增"读取层不看未来路线"。 + +### B 层 (后端) + +- `apps/backend/app/services/runtime_context.py` 新增 helpers： + - `as_runtime_year_month_param(site_id) -> 'YYYY-MM'` + - `as_runtime_business_now_str(site_id, fmt) -> str` + - `business_date_upper_bound_sql(site_id, column, alias, cast)` 返回 SQL 片段 + - `apply_runtime_session_vars(conn, ctx | site_id)` 设置 GUC（C 层基础） +- AI prompts：app3/4/5/6/7 的 `current_time` 改用 `as_runtime_business_now_str`，不再 `datetime.now()`。 +- AI data_fetchers： + - `member_data._query_consumption_records` / `_query_visit_info` 接受 `ref_date`，所有窗口加业务日上界。 + - `assistant_data._fetch_assistant_info_sync` / `_fetch_service_history_sync` 用业务日。 + - `page_context._text_board_finance/customer/coach/customer_service_records` 全部上界化。 + - 所有直连 ETL 库的 cursor 在 `SET LOCAL app.current_site_id` 之后再下发 `app.current_business_date`，供 RLS 视图 GUC 读取。 +- service： + - `board_service._batch_coach_details` 接受 ref_date，60 天消费窗口按业务日截。 + - `chat_service._get_consumption_30d` / `_get_visit_count_30d` 业务日 30 天窗口。 + - `coach_service.get_coach_detail` / `_build_history_months` 用业务日年月。 + - `customer_service` 60 天助教统计上界化。 + - `task_generator` 转移子流程的 `now` 改用 business_now。 + - `task_manager.batch_query_for_task_list` / `build_performance_summary` / 任务详情 60 天窗口全部业务日。 + - `tenant_users.py` SCD2 配置（cfg_assistant_level_price）用业务日。 +- **fdw_queries**（关键修复）： + - `_fdw_context` 进入事务后下发 `app.current_business_date` + `app.current_runtime_mode` GUC。 + - **客户看板「最近到店」bug 修复**：`get_last_visit_days` / `batch_query_for_task_list`（last_visit 计算）改为 ETL `last_consume_date` + `business_date - last_consume_date` 实时计算，不再依赖 ETL 预计算的 `days_since_last`，沙箱场景与 ETL 跑批延迟下都能正确显示"距上次到店 N 天"。 + - `get_customer_board_recent` / `get_customer_board_recharge` / `get_customer_board_freq60` / `get_customer_board_recall` / `_get_weekly_visits_batch` / `get_coach_60d_stats` / `batch_query_for_task_list` 60 天窗口 / SCD2 配置等全部用业务日。 + +### B 层 (小程序) + +- `apps/backend/app/routers/xcx_runtime_clock.py` 新增端点 `GET /api/xcx/runtime/clock`，返回 mode/business_date/business_year/business_month/business_year_month/business_now/is_sandbox/sandbox_date。 +- `apps/miniprogram/miniprogram/services/api.ts` 增加 `fetchRuntimeClock`。 +- `apps/miniprogram/miniprogram/utils/runtime-clock.ts`（新增）—— 60s 缓存 + 失败降级到本地时间。 +- 关键页面切换为业务时钟： + - `pages/performance/performance.ts` —— G2 当月预估判断 + - `pages/performance-records/performance-records.ts` —— onLoad / loadData / switchMonth + - `pages/task-list/task-list.ts` —— 月度判断 + - `pages/customer-records/customer-records.ts` —— onLoad + - `pages/customer-service-records/customer-service-records.ts` —— onLoad + +### C 层 (RLS 视图) + +- 新增迁移 `db/etl_feiqiu/migrations/20260502__rls_views_business_date_upper_bound.sql`： + - 注册 STABLE SQL 函数 `app.business_date_now()`：从 GUC `app.current_business_date` 读取业务日，未设置时回退 `CURRENT_DATE`。 + - **21 个视图**重写 WHERE，加 `<日期列> <= app.business_date_now()`： + - 财务事实 6 个：`v_dws_finance_area_daily / daily_summary / discount_detail / expense_summary / income_structure / recharge_summary` + - 助教汇总 5 个：`v_assistant_daily / v_dws_assistant_daily_detail / monthly_summary / salary_calc / finance_analysis` + - 客户事实 3 个：`v_dws_member_consumption_summary / visit_detail / winback_index` + - DWD 事实 5 个：`v_dwd_settlement_head / assistant_service_log / recharge_order / store_goods_sale / table_fee_log` + - SCD2 配置 2 个：`v_cfg_assistant_level_price / performance_tier` + - 列签名通过 `pg_get_viewdef` 实时从测试库读取，确保 `CREATE OR REPLACE VIEW` 不会因列签名漂移而失败。 +- 生成脚本：`scripts/ops/gen_rls_business_date_migration.py`（可重复执行）。 +- DDL 同步：`docs/database/ddl/etl_feiqiu__app.sql`、`db/etl_feiqiu/schemas/app.sql` 已同步。 + +## 验证 + +### 测试库迁移结果 + +``` +test site_id = 2790685415443269 +live: max(stat_date)=2026-04-27, count=2439 +sandbox(=2025-09-01): + max(stat_date) finance_area_daily = 2025-09-01, count=432 + max(visit_date) member_visit = 2025-09-01 + max(create_time::date) settlement = 2025-09-01 +RESULT: PASS +``` + +live 模式行为不变；sandbox 模式下所有事实视图严格不返回 sandbox_date 之后的数据。 + +### 静态检查 + +- 后端 99 个改动文件 AST 解析全部通过。 +- 前端 admin-web、小程序关键页面 lint 无新增错误。 + +## 兼容性 / 回滚 + +- live 模式下 GUC 不设置 → `app.business_date_now()` 回退 `CURRENT_DATE`，行为完全等同于改造前。 +- 回滚：`DROP FUNCTION app.business_date_now() CASCADE;`（视图会一并被 DROP），然后重新执行 `db/etl_feiqiu/schemas/app.sql` 即可恢复 live 行为。 +- B 层 / 小程序的时间锚替换全部走 RuntimeContext（fail-soft 降级 live），不影响生产链路。 + +## 已知未覆盖 + +- **page_context.py** 中 7 处直连 ETL 的查询，已加 SQL 上界（B 层），但部分位置依赖 GUC（C 层）即可，未单独传 ref_date。 +- 写入时间戳（`created_at`、`updated_at`、`finished_at`、调度 `last_run_at`、ai_run_logs 写入）保持系统真实时间，**不应**被沙箱影响（这是审计/运行时元数据），保留现状。 +- 小程序 chat / customer-detail 页面用于"展示当前操作时间"的 `new Date()` 保留（与会话/操作记录关联）。 +- AI 调度的预算计算、限流仍按真实系统时间。 +- DIM SCD2 维度（v_dim_assistant / v_dim_member / v_dim_member_card_account / v_dim_staff / v_dim_staff_ex / v_dim_table）保留 ``scd2_is_current=1`` 当前快照语义，未按 sandbox_date 重建历史维度行；如需"sandbox 当时维度状态"另行评估。 + +## 2026-05-02 后续追加 + +### B-2 / C 层补强 +- 18 个非关键视图补业务日上界（详见 `gen_rls_business_date_migration.py` 的 `VIEWS_WITH_BD`）：覆盖 `v_cfg_bonus_rules` / `v_cfg_index_parameters` 两个配置维度，及 16 个 DWS 业务事实/汇总（如 `v_dws_assistant_customer_stats`、`v_dws_member_assistant_intimacy`、`v_dws_finance_board_cache`、`v_finance_daily` 等）。**总计 39 个 RLS 视图带业务日上界**。 +- 端到端验证：`tools/db/verify_sandbox_end_to_end.py` 一键跑 live + sandbox(2025-09-01) 对比，输出 `2026-05-02__sandbox_e2e_verify_report.md`。本轮结果 31/31 PASS。 + - 注意：脚本里测的 `get_customer_board_recent / recharge / freq60 / recall` 是 `fdw_queries` 函数，**实际服务的是小程序 `board-customer`**，不是 admin-web。验证脚本同时覆盖 RLS 视图层（21+18=39 个视图），与端无关。 + +### log 警告止血（独立于沙箱） +- `apps/etl/connectors/feiqiu/tasks/dws/finance_area_daily.py`: 拓宽 `_is_all_only_area`，把 `补时长N`/`虚拟台N` 编号变体、`area_name=None & table_id 不空` 都归入 INFO（不再 WARNING），消除噪音。 +- `apps/etl/connectors/feiqiu/tasks/dws/task_engine.py`: ETL → backend HTTP `_TIMEOUT` 由 `(5, 30)` 改 `(10, 600)`，与 `flow_runner` 对齐，止血 30s 读超时。**根因（同步长任务+30s timeout）已记录，长期方案是 `/api/internal/run-job` 改异步入队，待后续 PR。** + +## 相关文件清单 + +- 主迁移：`db/etl_feiqiu/migrations/20260502__rls_views_business_date_upper_bound.sql` +- 生成器：`scripts/ops/gen_rls_business_date_migration.py` +- 端到端验证：`tools/db/verify_sandbox_end_to_end.py` +- 验证报告：`docs/database/changes/2026-05-02__sandbox_e2e_verify_report.md` +- 文档：本文件 + `docs/database/BD_Manual_runtime_context_sandbox.md` diff --git a/docs/database/changes/2026-05-02__sandbox_e2e_verify_report.md b/docs/database/changes/2026-05-02__sandbox_e2e_verify_report.md new file mode 100644 index 0000000..333243c --- /dev/null +++ b/docs/database/changes/2026-05-02__sandbox_e2e_verify_report.md @@ -0,0 +1,78 @@ +# 沙箱端到端验证报告 + +- site_id: `2790685415443269` +- sandbox_date: `2025-09-01` +- 生成时间: `2026-05-02T12:56:36` + +## 1. 视图层（C 方案） + +sandbox 模式下，max(各日期列) 必须 <= sandbox_date。 + +| 视图.列 | 取值 | 结果 | +|---|---|---| +| `app.v_dws_finance_area_daily.stat_date` | 2025-09-01 | PASS | +| `app.v_dws_finance_daily_summary.stat_date` | 2025-09-01 | PASS | +| `app.v_dws_member_visit_detail.visit_date` | 2025-09-01 | PASS | +| `app.v_dws_member_consumption_summary.stat_date` | None | OK (None) | +| `app.v_dws_assistant_daily_detail.stat_date` | 2025-09-01 | PASS | +| `app.v_dws_assistant_monthly_summary.stat_month` | 2025-09-01 | PASS | +| `app.v_dws_assistant_salary_calc.salary_month` | 2025-09-01 | PASS | +| `app.v_dwd_settlement_head.create_time` | 2025-09-01 | PASS | +| `app.v_dwd_assistant_service_log.create_time` | 2025-09-01 | PASS | +| `app.v_dwd_recharge_order.pay_time` | 2025-09-01 | PASS | +| `app.v_dws_member_winback_index.last_visit_time` | 2025-09-01 | PASS | +| `app.v_dws_assistant_customer_stats.stat_date` | None | OK (None) | +| `app.v_dws_member_assistant_intimacy.calc_time` | None | OK (None) | +| `app.v_dws_member_newconv_index.stat_date` | 2025-09-01 | PASS | +| `app.v_dws_finance_board_cache.computed_at` | None | OK (None) | +| `app.v_finance_daily.stat_date` | 2025-09-01 | PASS | + +### live 模式 baseline（同样 site_id，无 GUC） + +| 视图.列 | 取值 | 备注 | +|---|---|---| +| `app.v_dws_finance_area_daily.stat_date` | 2026-04-27 | live (CURRENT_DATE 行为) | +| `app.v_dws_finance_daily_summary.stat_date` | 2026-04-27 | live (CURRENT_DATE 行为) | +| `app.v_dws_member_visit_detail.visit_date` | 2026-04-27 | live (CURRENT_DATE 行为) | +| `app.v_dws_member_consumption_summary.stat_date` | 2026-05-01 | live (CURRENT_DATE 行为) | +| `app.v_dws_assistant_daily_detail.stat_date` | 2026-04-26 | live (CURRENT_DATE 行为) | +| `app.v_dws_assistant_monthly_summary.stat_month` | 2026-04-01 | live (CURRENT_DATE 行为) | +| `app.v_dws_assistant_salary_calc.salary_month` | 2026-04-01 | live (CURRENT_DATE 行为) | +| `app.v_dwd_settlement_head.create_time` | 2026-04-28 | live (CURRENT_DATE 行为) | +| `app.v_dwd_assistant_service_log.create_time` | 2026-04-26 | live (CURRENT_DATE 行为) | +| `app.v_dwd_recharge_order.pay_time` | 2026-04-21 | live (CURRENT_DATE 行为) | +| `app.v_dws_member_winback_index.last_visit_time` | 2026-04-27 | live (CURRENT_DATE 行为) | +| `app.v_dws_assistant_customer_stats.stat_date` | 2026-05-01 | live (CURRENT_DATE 行为) | +| `app.v_dws_member_assistant_intimacy.calc_time` | 2026-02-08 | live (CURRENT_DATE 行为) | +| `app.v_dws_member_newconv_index.stat_date` | 2026-05-01 | live (CURRENT_DATE 行为) | +| `app.v_dws_finance_board_cache.computed_at` | 2026-03-29 | live (CURRENT_DATE 行为) | +| `app.v_finance_daily.stat_date` | 2026-04-27 | live (CURRENT_DATE 行为) | + +## 2. 应用层（B 方案 / RuntimeContext / fdw_queries / AI prompt） + +| 调用 | 取值 | 结果 | +|---|---|---| +| `ctx.is_sandbox` | True | PASS | +| `ctx.business_date` | 2025-09-01 | PASS / =bd | +| `ctx.business_now` | 2025-09-01 | PASS | +| `as_runtime_today_param` | 2025-09-01 | PASS | +| `as_runtime_year_month_param` | 2025-09 | PASS | +| `as_runtime_business_now_str` | 2025-09-01 12:56:29 | OK | +| `board.month range end` | 2025-09-01 | PASS / =bd | +| `board.quarter range end` | 2025-09-01 | PASS | +| `board.week range end` | 2025-09-01 | PASS | +| `pick member_ids` | [2854141942400709, 2799207305578245, 2848686922632133, 2848686922632133, 2799207290996485] | OK | +| `fdw.get_customer_board_recent(items=10)` | 2025-09-01 | PASS | +| `fdw.get_customer_board_recharge(items=10)` | 2025-09-01 | PASS | +| `fdw.get_customer_board_freq60(items=0)` | None | OK (no date in items) | +| `fdw.get_customer_board_recall(items=10)` | None | OK (no date in items) | +| `AI prompt current_time(date)` | 2025-09-01 | PASS | + +## 3. 汇总 + +- 总检查项: 31 +- PASS / OK: 31 +- FAIL / ERROR: 0 +- 其他: 0 + +**结论：PASS — sandbox 模式下，所有关键读取路径都被截到 sandbox_date 之前。** \ No newline at end of file diff --git a/docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md b/docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md new file mode 100644 index 0000000..580f94b --- /dev/null +++ b/docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md @@ -0,0 +1,246 @@ +# 沙箱「不看未来」完整修复清单 + +> 日期：2026-05-02 +> 关联：[changes/2026-05-01__runtime_context_sandbox.md](2026-05-01__runtime_context_sandbox.md) +> 关联代码： +> - 后端：`apps/backend/app/services/runtime_context.py`、`fdw_queries.py`、`board_service.py`、`task_*.py`、`recall_detector.py`、`chat_service.py`、`coach_service.py`、`customer_service.py`、`performance_service.py`、`ai/data_fetchers/*`、`ai/prompts/*` +> - 数据库：`db/etl_feiqiu/schemas/app.sql`（DWS/DWD/DIM RLS 视图） +> - 小程序：`apps/miniprogram/miniprogram/pages/performance*`、`task-list`、`board-finance` 等 +> 风险等级：**高**（核心业务读取层广泛假设「真实今天」） +> 状态：**方案待用户确认**；实施前不动业务代码 + +--- + +## 一、问题陈述 + +`R1 RuntimeContext 业务日期沙箱` 的初版只解决了 **写入隔离**：sandbox 行带 `runtime_mode='sandbox' + sandbox_instance_id='sbx_*'`，与 live 数据共存但不污染。 + +但读取层仍大量使用 **真实系统时间**，导致 sandbox 模式下： + +- `get_finance_board` 区间按 `business_date` 算（OK），但 prompts 内部的辅助 ETL 查询用 `_calc_date_range(time)` 漏传 `ref_date`，退回 `date.today()`，会拉「真实今天」的数据。 +- AI data_fetchers（`member_data` / `assistant_data` / `page_context`）SQL 写死 `CURRENT_DATE - INTERVAL '60 days'` 等。 +- App3-7 prompt `current_time` 字段是 `datetime.now()`，与沙箱业务时钟不一致。 +- `fdw_queries.py` 大量 `CURRENT_DATE` 与 `ORDER BY stat_date DESC LIMIT N`，无业务日上界。 +- 小程序 performance / performance-records 用本地 `Date` 推算 `year/month` 直接传给后端，绕过 RuntimeContext。 + +后果：sandbox 演示「以 2026-03-15 视角重放」时，看板/任务/AI 输出实际混合了截至真实今天的最新数据，纯净度被破坏。 + +--- + +## 二、修复策略（A + B + C 三层） + +### A 层：文档与 UI 警告（最轻，先上） + +不改业务代码，只让用户清楚当前沙箱边界。 + +| 文件 | 改动 | +|---|---| +| `apps/admin-web/src/pages/RuntimeContext.tsx` | Alert 中追加「当前沙箱可能仍读取部分真实近期数据」的警告，并提示完整修复进度 | +| `docs/database/BD_Manual_runtime_context_sandbox.md` | 新增「读取层局限与逐步修复路线」章节 | +| `docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md` | 本文件，作为修复路线图 | + +### B 层：后端 + 小程序代码层修复（核心） + +按调用链分两组： + +#### B1 · 后端服务层时间锚替换 + SQL 上界 + +把 `date.today()` / `datetime.now()` / `CURRENT_DATE` / `NOW()` 在「业务窗口」语义里换成 `as_runtime_today_param` / `as_runtime_now_param` / `task_runtime_filter` 或参数化业务日；查询 DWS/DWD/FDW 时补 `stat_date <= business_date` / `pay_time <= business_now` 等上界。 + +调度元数据、审计、token TTL、写库 `updated_at = NOW()` 这类非业务窗口保持原状。 + +| 文件 | 行号 | 现状 | 改法 | +|---|---|---|---| +| `apps/backend/app/services/board_service.py` | 37 | `today = ref_date or date.today()` | 调用方必须传 `ref_date=runtime_ctx.business_date`（如 prompts 漏传需补） | +| 同上 | 500 | SQL 写死 `create_time >= CURRENT_DATE - INTERVAL '60 days'` | 改 `create_time BETWEEN %s AND %s`，参数为 `business_date - 60d` 与 `business_now` | +| `apps/backend/app/services/task_generator.py` | 231/845/884 | `datetime.now(timezone.utc)` | 业务窗口处改 `as_runtime_now_param(site_id)`；`run_started_at`（运行记录）保留真实时间 | +| 同上 | 873 | 直连 `dwd.dim_assistant`（非 RLS 视图） | 切换 `app.v_dim_assistant` 或加 sandbox 上界 | +| `apps/backend/app/services/task_expiry.py` | 63 | 注释 `expires_at < NOW()`；实际已用 `as_runtime_now_param` | 仅更新注释，无代码改动 | +| `apps/backend/app/services/task_manager.py` | 680-682 | `datetime.now(timezone.utc).year/month` 用作工资月 | 改 `as_runtime_today_param(site_id).year/month` | +| 同上 | 819-820 | `datetime.now()` 计算年月 | 同上 | +| 同上 | 1199-1202 | `today = date.today(); cutoff_60d = today - 60d` | `today = as_runtime_today_param(site_id)` | +| `apps/backend/app/services/coach_service.py` | 150/716 | `datetime.date.today()` | `as_runtime_today_param` | +| 同上 | 198-207/744-756 | `biz.coach_tasks` 查询无 `task_runtime_filter` | 套 `task_runtime_filter(site_id)` | +| 同上 | 550-566 | `_build_task_groups` 未带 `site_id` | 补 site_id 过滤 + runtime filter | +| `apps/backend/app/services/customer_service.py` | 516 | `CURRENT_DATE - INTERVAL '60 days'` | 参数化为 `business_date - 60d` | +| `apps/backend/app/services/performance_service.py` | 508-518 / 532-534 | `_calc_date_range` ref 来自 `next_month_start`，未对齐沙箱 | 参数链路改为 `business_date` 推导 | +| `apps/backend/app/services/chat_service.py` | 195 | `NOW() - 3 days` 限制对话上下文 | 改 `business_now - 3 days` | +| 同上 | 692/709 | `CURRENT_DATE - 30 days` | 改 `business_date - 30 days` | +| 同上 | 602 | 写消息 `NOW()` | 写消息保留真实时间（持久化时钟应跟真实） | +| `apps/backend/app/services/fdw_queries.py` | 196-200 / 489 / 567-568 / 650-651 / 688-689 / 924 / 1012-1016 / 等 | 大量 `CURRENT_DATE` 与 `ORDER BY stat_date DESC LIMIT` 无上界 | 函数签名增加 `business_date / business_now` 参数；SQL 加 `stat_date <= %s` / `create_time <= %s` | +| `apps/backend/app/services/ai/admin_service.py` | 86-87 / 137 / 304-305 / 546-551 | AI 调用统计窗口 `CURRENT_DATE` | super-admin 后台是否也按门店沙箱口径——需产品确认。默认建议保留真实时间 | +| `apps/backend/app/services/recall_detector.py` | 157-164 / 174-195 | `app.v_dws_*` 查询无 `stat_date` 上界 | 加 `stat_date <= business_date` | +| `apps/backend/app/services/scheduler.py` / `trigger_scheduler.py` | — | 调度元数据（任务下次运行时间） | **不动**：调度本身按真实时钟工作 | +| `apps/backend/app/routers/xcx_auth.py` | ~334-348 | `_dt.now().year/month` 给 `get_salary_calc` | `as_runtime_today_param(user.site_id).year/month` | +| `apps/backend/app/routers/admin_runtime_context.py` | 111 | `sandbox_date > date.today()` 校验 | 保留：sandbox_date 的「未来」语义就是相对真实日历 | + +AI prompts / data_fetchers： + +| 文件 | 行号 | 改法 | +|---|---|---| +| `apps/backend/app/ai/prompts/app2_finance_prompt.py` | 817-818 / 841-846 | 调 `_calc_date_range(time, ref_date=runtime_ctx.business_date)` | +| `apps/backend/app/ai/prompts/app2a_finance_area_prompt.py` | 466-468 | 同上 | +| `apps/backend/app/ai/prompts/app3_clue_prompt.py` | 65-66 | `current_time = as_runtime_now_param(site_id)` | +| `apps/backend/app/ai/prompts/app4_analysis_prompt.py` | 82-83 | 同上 | +| `apps/backend/app/ai/prompts/app5_tactics_prompt.py` | 82-83 | 同上 | +| `apps/backend/app/ai/prompts/app6_note_prompt.py` | 79-80 | 同上 | +| `apps/backend/app/ai/prompts/app7_customer_prompt.py` | 79-80 | 同上 | +| `apps/backend/app/ai/dispatcher.py` | 259/330 | 去重键的 `date.today()` 改为 `as_runtime_today_param(site_id)`，确保沙箱 vs live 去重不互相污染 | +| `apps/backend/app/ai/data_fetchers/member_data.py` | 166/211/280/326/377-378 | `CURRENT_DATE` → 参数；`date.today()` → `business_date`；`ORDER BY ... DESC LIMIT N` 加上界 | +| `apps/backend/app/ai/data_fetchers/assistant_data.py` | 92/105-106/212-213 | 同上 | +| `apps/backend/app/ai/data_fetchers/page_context.py` | 140/154/218/243/364/413/415-416/465/467-468/518-519/602-603 | 同上；`ORDER BY DESC LIMIT N` 全部加 `<= business_now / business_date` 上界 | +| `apps/backend/app/ai/cache_service.py` | 83/279 | `expires_at > now()` 与 TTL → 保留真实时钟（缓存 TTL 是真实时间维度） | +| `apps/backend/app/ai/run_log_service.py` | 115/143/165/195-196/211-212 | run log `finished_at` 真实时钟；窗口聚合按真实时钟（运维口径） | + +#### B2 · 小程序绕过点修复 + +让小程序停止用本地 `Date` 算 `year/month` 直接传给后端；改为后端从 RuntimeContext 决定。 + +| 文件 | 行号 | 改法 | +|---|---|---| +| `apps/miniprogram/miniprogram/pages/performance/performance.ts` | 121-127 / 133-135 | 不再传 `year/month`，调用 `fetchPerformanceOverview()` 让后端按 `business_date` 决定；或先 `fetchRuntimeContext()` 拿业务年月 | +| `apps/miniprogram/miniprogram/pages/performance-records/performance-records.ts` | 62-63 / 87-91 / 143-147 / 258-262 | 初始化用后端 `business_date.year/month`；`canGoNext` 上界改用 `business_date` | +| `apps/miniprogram/miniprogram/pages/task-list/task-list.ts` | 389-411 | `isCurrentMonth` 通过后端返回字段或 `runtimeContext.business_date` 计算 | +| `apps/miniprogram/miniprogram/pages/board-finance/board-finance.ts` | 17 | `isCurrentMonthFilter` 同上 | +| `apps/miniprogram/miniprogram/services/api.ts` | (新增) | `fetchRuntimeContext()` 包装 `/api/config/runtime-context`，返回 `{ business_date, business_now, is_sandbox }`；缓存到全局 store | +| `utils/time.ts` | 全文 | **不改**：相对时间/IM 时间/截止日全是显示文案，按真实本地时间合理 | +| `chat.ts` 367/407、`customer-detail.ts` 216-219 等乐观 UI 时间戳 | — | **不改**：仅 UI 兜底，最终以后端时间为准 | + +#### B 层后端公共改造点 + +为减少散点改动，建议在 `apps/backend/app/services/runtime_context.py` 加两个工具： + +```python +def runtime_window_upper_bound(site_id, conn=None) -> tuple[date, datetime]: + """返回 (business_date, business_now) 用作 SQL 上界。""" + +def runtime_year_month(site_id, conn=None) -> tuple[int, int]: + """返回沙箱业务年月，用于绩效报表。""" +``` + +`fdw_queries.py` 函数签名增加可选 `business_date`、`business_now` 参数；调用方按需传入。 + +### C 层：ETL RLS 视图业务日上界（最彻底） + +利用现有 `app.current_site_id` 模式，引入 `app.current_business_date` 会话变量，在 `app.v_*` 视图层加上界。后端 `_fdw_context` 增加 `SET LOCAL app.current_business_date = %s`，sandbox 模式下传 `business_date`，live 模式下不设置或设置 `9999-12-31`。 + +#### C 方案 SQL 模式 + +```sql +-- 时间事实表（含 stat_date / pay_time / create_time） +CREATE OR REPLACE VIEW app.v_dws_finance_daily_summary AS +SELECT ... +FROM dws.dws_finance_daily_summary +WHERE site_id = current_setting('app.current_site_id')::bigint + AND stat_date <= COALESCE( + NULLIF(current_setting('app.current_business_date', true), '')::date, + '9999-12-31'::date + ); + +-- 维度表（含 scd2_effective_from） +CREATE OR REPLACE VIEW app.v_dim_member AS +SELECT ... +FROM dwd.dim_member +WHERE register_site_id = current_setting('app.current_site_id')::bigint + AND COALESCE(scd2_effective_from, '0001-01-01'::date) <= COALESCE( + NULLIF(current_setting('app.current_business_date', true), '')::date, + '9999-12-31'::date + ); +``` + +`current_setting('app.current_business_date', true)` 第二个参数 `true` 表示「未设置时返回空字符串而非报错」，配合 `NULLIF + COALESCE` 实现： + +- live 模式下 `app.current_business_date` 未设置 → 上界为 `9999-12-31` → 等同无限制 +- sandbox 模式下后端 `SET LOCAL app.current_business_date = '2026-03-15'` → 视图自动截断 + +#### C 方案涉及范围 + +`db/etl_feiqiu/schemas/app.sql` 共 49 个 RLS 视图： + +| 类型 | 视图模式 | 上界字段 | +|---|---|---| +| 维度表 SCD2 | `v_dim_*`（10 个） | `scd2_effective_from` 或 `created_at` | +| DWD 事实表 | `v_dwd_*`（6 个） | `create_time` 或 `pay_time` | +| DWS 日粒度 | `v_dws_*_daily*`（约 10 个） | `stat_date` | +| DWS 月粒度 | `v_dws_*_monthly*`（约 5 个） | `stat_month` | +| DWS 索引/聚合 | `v_dws_*_index` 等 | `stat_date` | +| 配置表 | `v_cfg_*` | 一般取「最新有效」，沙箱可保留真实最新（配置不该回放） | + +需要按视图逐个判断时间上界字段。建议分批： + +1. **C-1**：财务相关 `v_dws_finance_*`（5 视图）。 +2. **C-2**：助教/任务相关 `v_dws_assistant_*`、`v_dws_member_assistant_*`（约 12 视图）。 +3. **C-3**：DWD 事实表 `v_dwd_*`（6 视图）。 +4. **C-4**：维度表 SCD2 `v_dim_*`（10 视图，需配合 SCD2 字段）。 +5. **C-5**：配置表 `v_cfg_*`（一般保留真实最新，但确认是否需要按 `effective_to`）。 + +每批按 RLS 双 schema 规则同时改 `dws.v_*` 和 `app.v_*`。 + +#### C 方案后端改造 + +```python +# apps/backend/app/database.py 或 fdw_queries.py 内 +def get_etl_readonly_connection(site_id, business_date=None): + conn = ... + with conn.cursor() as cur: + cur.execute("SET default_transaction_read_only = on") + cur.execute("SET LOCAL app.current_site_id = %s", (str(site_id),)) + if business_date is not None: + cur.execute("SET LOCAL app.current_business_date = %s", (str(business_date),)) + ... +``` + +`_fdw_context` 同样改造：默认从 `get_runtime_context(site_id)` 取 `business_date`，sandbox 模式自动 SET。 + +--- + +## 三、推荐实施顺序 + +| 步骤 | 工作量 | 价值 | 依赖 | +|---|---|---|---| +| A1 admin-web Alert 警告升级 | 0.5h | 立即让用户知道当前局限 | 无 | +| A2 BD_Manual + 本修复路线图 | 0.5h | 后续工作可见 | 无 | +| B1-后端 prompts ref_date 漏传补齐 | 1h | 立即修复 App2/App2a 漏洞 | 无 | +| B1-后端 runtime helpers + service 层关键路径 | 4h | 修 task/board/coach/customer/performance 主链路 | 无 | +| B1-后端 fdw_queries 上界改造 | 6h | 收口最大公约数 | 上一步 | +| B1-后端 AI data_fetchers + prompts current_time | 3h | AI 链路对齐沙箱 | 无 | +| B2-小程序 performance/year-month 改后端权威 | 2h | 小程序绕过点收口 | B1 后端 runtime helpers | +| C-1 财务视图 RLS 上界 | 2h | 双 schema 规则；DDL 同步 | B 层验证通过 | +| C-2 助教/任务视图 RLS 上界 | 3h | 同上 | 同上 | +| C-3 DWD RLS 上界 | 2h | 同上 | 同上 | +| C-4 维度 SCD2 上界 | 3h | 历史维度回放精度 | 同上 | +| C-5 配置表评估（多数不改） | 0.5h | — | 同上 | +| 同步主 DDL + 双 schema + DDL 副本 | 1h | 保证仓库 ddl 与测试库一致 | C 完成 | + +**总估时**：约 28-30 小时，单人执行；强烈建议分 4-5 个 PR：A、B-后端、B-小程序、C 财务视图、C 其他视图。 + +--- + +## 四、风险与开发约束 + +1. **live 行为不能变**：所有 SQL 上界用 `COALESCE(... , '9999-12-31')` 形式，live 不设变量时等同无限制。 +2. **双 schema 规则**：`db/etl_feiqiu/schemas/app.sql` 与 `dws.v_*` 必须同时更改。 +3. **DDL 副本同步**：每批 C 改完跑 `python tools/db/gen_consolidated_ddl.py`，把 `docs/database/ddl/etl_feiqiu__app.sql` 等同步进 git。 +4. **真实时钟字段保留**：`updated_at = NOW()`、`finished_at = NOW(timezone.utc)`、缓存 TTL `expires_at`、调度 `next_run_at`、AI run_logs 写入时间——这些**保留真实时钟**。 +5. **去重键**：dispatcher / cache 的「当日去重」key 需带 `runtime_mode + business_date`，避免 sandbox 与 live 互相污染。 +6. **配置表沙箱语义**：`v_cfg_*` 一般取「最新有效」；如需历史回放，需要单独评估 `scd2_effective_to` 上界。 +7. **测试**：每批改完都要在 `test_zqyy_app` + `test_etl_feiqiu` 上运行至少一次端到端 sandbox 切换 + 看板抽查 + AI 触发。 + +--- + +## 五、未覆盖项（需用户确认或单独立项） + +- **生产数据库执行**：本修复在 test 库通过后才能上生产；窗口需运维约定。 +- **写入沙箱数据归零**：长期使用沙箱后会积累 sandbox 行（任务、AI cache、run logs、recall events），应有按 `runtime_mode='sandbox' AND sandbox_instance_id=...` 的清理脚本。 +- **小程序 utils/time.ts**：当前不改；如需把「相对时间」也按沙箱算（如沙箱日下「3 天前」按沙箱日推算），属于另一议题。 +- **跨多门店 sandbox**：当前未限制同时多门店进入 sandbox；若并行需求，需要约定每个 site 独立 RuntimeContext + 各自上界（架构已支持）。 +- **Admin-Web AI 调用统计 / 监控页**：是否按真实时间口径，需产品决定。 + +--- + +## 六、实施建议 + +1. **本文档已落地**（`docs/database/changes/2026-05-02__sandbox_no_future_data_plan.md`），作为后续多 PR 的统一目录。 +2. **不立即动业务代码**；等用户确认范围后开始。 +3. **优先级建议**：A → B-后端关键路径（task_generator、board_service、prompts ref_date 漏传）→ B-AI prompts current_time → B-小程序 performance → B-fdw_queries → C-财务视图 → 其他 C。 +4. **每个 PR 自带单测**：sandbox 模式下 SQL 不返回 sandbox_date 之后的数据。 diff --git a/docs/database/ddl/etl_feiqiu__app.sql b/docs/database/ddl/etl_feiqiu__app.sql index d596c11..678861a 100644 --- a/docs/database/ddl/etl_feiqiu__app.sql +++ b/docs/database/ddl/etl_feiqiu__app.sql @@ -1,6 +1,6 @@ -- ============================================================================= -- etl_feiqiu / app（RLS 视图层） --- 生成日期：2026-04-12 +-- 生成日期：2026-05-02 -- 来源：测试库（通过脚本自动导出） -- ============================================================================= @@ -36,7 +36,8 @@ SELECT id, unique_customers, unique_tables, created_at - FROM dws.dws_assistant_daily_detail d; + FROM dws.dws_assistant_daily_detail d + WHERE (stat_date <= app.business_date_now()); ; CREATE OR REPLACE VIEW app.v_cfg_area_category AS @@ -61,7 +62,8 @@ SELECT price_id, description, created_at, updated_at - FROM dws.cfg_assistant_level_price; + FROM dws.cfg_assistant_level_price + WHERE ((effective_from <= app.business_date_now()) AND (effective_to >= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_cfg_bonus_rules AS @@ -112,7 +114,8 @@ SELECT tier_id, description, created_at, updated_at - FROM dws.cfg_performance_tier; + FROM dws.cfg_performance_tier + WHERE ((effective_from <= app.business_date_now()) AND (effective_to >= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dim_assistant AS @@ -301,7 +304,7 @@ SELECT assistant_service_id, is_delete, real_service_money FROM dwd.dwd_assistant_service_log - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (COALESCE((create_time)::date, '0001-01-01'::date) <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dwd_recharge_order AS @@ -330,7 +333,7 @@ SELECT recharge_order_id, real_electricity_money, electricity_adjust_money FROM dwd.dwd_recharge_order - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (COALESCE((pay_time)::date, '0001-01-01'::date) <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dwd_settlement_head AS @@ -372,7 +375,7 @@ SELECT order_settle_id, pl_coupon_sale_amount, mervou_sales_amount FROM dwd.dwd_settlement_head - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (COALESCE((create_time)::date, '0001-01-01'::date) <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dwd_store_goods_sale AS @@ -402,7 +405,7 @@ SELECT store_goods_sale_id, coupon_share_money, discount_price FROM dwd.dwd_store_goods_sale - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (COALESCE((create_time)::date, '0001-01-01'::date) <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dwd_table_fee_log AS @@ -436,7 +439,7 @@ SELECT table_fee_log_id, activity_discount_amount, real_service_money FROM dwd.dwd_table_fee_log - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (COALESCE((create_time)::date, '0001-01-01'::date) <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_assistant_customer_stats AS @@ -518,7 +521,7 @@ SELECT id, is_exempt, per_hour_contribution FROM dws.dws_assistant_daily_detail - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_assistant_finance_analysis AS @@ -543,7 +546,7 @@ SELECT id, created_at, updated_at FROM dws.dws_assistant_finance_analysis - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_assistant_monthly_summary AS @@ -583,7 +586,7 @@ SELECT id, created_at, updated_at FROM dws.dws_assistant_monthly_summary - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_month <= (date_trunc('month'::text, (app.business_date_now())::timestamp with time zone))::date)); ; CREATE OR REPLACE VIEW app.v_dws_assistant_order_contribution AS @@ -687,7 +690,7 @@ SELECT id, created_at, updated_at FROM dws.dws_assistant_salary_calc - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (salary_month <= (date_trunc('month'::text, (app.business_date_now())::timestamp with time zone))::date)); ; CREATE OR REPLACE VIEW app.v_dws_coach_area_hours AS @@ -746,9 +749,10 @@ SELECT id, renewal_cash, order_count, created_at, - updated_at + updated_at, + member_order_count FROM dws.dws_finance_area_daily - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_finance_board_cache AS @@ -822,7 +826,7 @@ SELECT id, created_at, updated_at FROM dws.dws_finance_daily_summary - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_finance_discount_detail AS @@ -839,7 +843,7 @@ SELECT id, created_at, updated_at FROM dws.dws_finance_discount_detail - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_finance_expense_summary AS @@ -860,7 +864,7 @@ SELECT id, created_at, updated_at FROM dws.dws_finance_expense_summary - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (expense_month <= (date_trunc('month'::text, (app.business_date_now())::timestamp with time zone))::date)); ; CREATE OR REPLACE VIEW app.v_dws_finance_income_structure AS @@ -878,7 +882,7 @@ SELECT id, created_at, updated_at FROM dws.dws_finance_income_structure - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_finance_recharge_summary AS @@ -912,7 +916,7 @@ SELECT id, created_at, updated_at FROM dws.dws_finance_recharge_summary - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_member_assistant_intimacy AS @@ -1033,7 +1037,7 @@ SELECT DISTINCT ON (member_id) id, recharge_amount_90d, avg_ticket_amount FROM dws.dws_member_consumption_summary - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint) + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (stat_date <= app.business_date_now())) ORDER BY member_id, stat_date DESC; ; @@ -1162,7 +1166,7 @@ SELECT id, created_at, updated_at FROM dws.dws_member_visit_detail - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (visit_date <= app.business_date_now())); ; CREATE OR REPLACE VIEW app.v_dws_member_winback_index AS @@ -1204,7 +1208,7 @@ SELECT DISTINCT ON (member_id) winback_id, ideal_next_visit_date, stat_date FROM dws.dws_member_winback_index - WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint) + WHERE ((site_id = (current_setting('app.current_site_id'::text))::bigint) AND (COALESCE((last_visit_time)::date, '0001-01-01'::date) <= app.business_date_now())) ORDER BY member_id, stat_date DESC; ; diff --git a/docs/database/ddl/etl_feiqiu__core.sql b/docs/database/ddl/etl_feiqiu__core.sql index bc162c2..c37039d 100644 --- a/docs/database/ddl/etl_feiqiu__core.sql +++ b/docs/database/ddl/etl_feiqiu__core.sql @@ -1,6 +1,6 @@ -- ============================================================================= -- etl_feiqiu / core（跨门店标准化维度/事实） --- 生成日期：2026-04-12 +-- 生成日期：2026-05-02 -- 来源：测试库（通过脚本自动导出） -- ============================================================================= diff --git a/docs/database/ddl/etl_feiqiu__dwd.sql b/docs/database/ddl/etl_feiqiu__dwd.sql index 4aa2762..2fa998e 100644 --- a/docs/database/ddl/etl_feiqiu__dwd.sql +++ b/docs/database/ddl/etl_feiqiu__dwd.sql @@ -1,6 +1,6 @@ -- ============================================================================= -- etl_feiqiu / dwd（明细数据层） --- 生成日期：2026-04-12 +-- 生成日期：2026-05-02 -- 来源：测试库（通过脚本自动导出） -- ============================================================================= @@ -695,7 +695,13 @@ CREATE TABLE dwd.dwd_groupbuy_redemption ( ledger_name character varying(128), create_time timestamp with time zone, member_discount_money numeric(18,2), - coupon_sale_id bigint + coupon_sale_id bigint, + mt_settlement_price numeric(14,2), + mt_gross_income numeric(14,2), + mt_service_fee numeric(14,2), + mt_marketing_fee numeric(14,2), + mt_other_adjust numeric(14,2), + mt_import_time timestamp with time zone ); CREATE TABLE dwd.dwd_groupbuy_redemption_ex ( diff --git a/docs/database/ddl/etl_feiqiu__dws.sql b/docs/database/ddl/etl_feiqiu__dws.sql index 43d0e98..69f119b 100644 --- a/docs/database/ddl/etl_feiqiu__dws.sql +++ b/docs/database/ddl/etl_feiqiu__dws.sql @@ -1,6 +1,6 @@ -- ============================================================================= -- etl_feiqiu / dws（汇总数据层） --- 生成日期：2026-04-12 +-- 生成日期：2026-05-02 -- 来源：测试库（通过脚本自动导出） -- ============================================================================= @@ -421,7 +421,8 @@ CREATE TABLE dws.dws_finance_area_daily ( renewal_cash numeric(14,2) DEFAULT 0 NOT NULL, order_count integer DEFAULT 0 NOT NULL, created_at timestamp with time zone DEFAULT now() NOT NULL, - updated_at timestamp with time zone DEFAULT now() NOT NULL + updated_at timestamp with time zone DEFAULT now() NOT NULL, + member_order_count integer DEFAULT 0 NOT NULL ); CREATE TABLE dws.dws_finance_board_cache ( @@ -1259,7 +1260,8 @@ SELECT id, renewal_cash, order_count, created_at, - updated_at + updated_at, + member_order_count FROM dws.dws_finance_area_daily WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint); ; diff --git a/docs/database/ddl/etl_feiqiu__meta.sql b/docs/database/ddl/etl_feiqiu__meta.sql index dcbce84..b282597 100644 --- a/docs/database/ddl/etl_feiqiu__meta.sql +++ b/docs/database/ddl/etl_feiqiu__meta.sql @@ -1,6 +1,6 @@ -- ============================================================================= -- etl_feiqiu / meta（ETL 调度元数据） --- 生成日期：2026-04-12 +-- 生成日期：2026-05-02 -- 来源：测试库（通过脚本自动导出） -- ============================================================================= diff --git a/docs/database/ddl/etl_feiqiu__ods.sql b/docs/database/ddl/etl_feiqiu__ods.sql index d598eac..1988d7e 100644 --- a/docs/database/ddl/etl_feiqiu__ods.sql +++ b/docs/database/ddl/etl_feiqiu__ods.sql @@ -1,6 +1,6 @@ -- ============================================================================= -- etl_feiqiu / ods（原始数据层） --- 生成日期：2026-04-12 +-- 生成日期：2026-05-02 -- 来源：测试库（通过脚本自动导出） -- ============================================================================= diff --git a/docs/database/ddl/fdw.sql b/docs/database/ddl/fdw.sql index cfa1c69..729ac68 100644 --- a/docs/database/ddl/fdw.sql +++ b/docs/database/ddl/fdw.sql @@ -1,6 +1,6 @@ -- ============================================================================= -- FDW 跨库映射（在 zqyy_app 中执行） --- 生成日期：2026-04-12 +-- 生成日期：2026-05-02 -- 来源：db/fdw/setup_fdw.sql -- ============================================================================= diff --git a/docs/database/ddl/zqyy_app__auth.sql b/docs/database/ddl/zqyy_app__auth.sql index fcc360c..d7e5b18 100644 --- a/docs/database/ddl/zqyy_app__auth.sql +++ b/docs/database/ddl/zqyy_app__auth.sql @@ -1,6 +1,6 @@ -- ============================================================================= -- zqyy_app / auth（用户认证与权限） --- 生成日期：2026-04-12 +-- 生成日期：2026-05-02 -- 来源：测试库（通过脚本自动导出） -- ============================================================================= diff --git a/docs/database/ddl/zqyy_app__biz.sql b/docs/database/ddl/zqyy_app__biz.sql index 3e17c34..6b93cb3 100644 --- a/docs/database/ddl/zqyy_app__biz.sql +++ b/docs/database/ddl/zqyy_app__biz.sql @@ -1,6 +1,6 @@ -- ============================================================================= -- zqyy_app / biz（核心业务表（任务/备注/触发器）） --- 生成日期：2026-04-12 +-- 生成日期：2026-05-02 -- 来源：测试库（通过脚本自动导出） -- ============================================================================= @@ -41,7 +41,9 @@ CREATE TABLE biz.ai_cache ( triggered_by character varying(100), created_at timestamp with time zone DEFAULT now() NOT NULL, expires_at timestamp with time zone, - status character varying(20) DEFAULT 'valid'::character varying + status character varying(20) DEFAULT 'valid'::character varying, + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.ai_conversations ( @@ -86,7 +88,9 @@ CREATE TABLE biz.ai_run_logs ( session_id character varying(100), created_at timestamp with time zone DEFAULT now() NOT NULL, finished_at timestamp with time zone, - alert_status character varying(20) DEFAULT NULL::character varying + alert_status character varying(20) DEFAULT NULL::character varying, + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.ai_trigger_jobs ( @@ -102,7 +106,9 @@ CREATE TABLE biz.ai_trigger_jobs ( started_at timestamp with time zone, finished_at timestamp with time zone, error_message text, - created_at timestamp with time zone DEFAULT now() NOT NULL + created_at timestamp with time zone DEFAULT now() NOT NULL, + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.cfg_task_generator_params ( @@ -124,7 +130,9 @@ CREATE TABLE biz.coach_task_history ( old_task_type character varying(50), new_task_type character varying(50), detail jsonb, - created_at timestamp with time zone DEFAULT now() + created_at timestamp with time zone DEFAULT now(), + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.coach_task_transfer_log ( @@ -138,7 +146,9 @@ CREATE TABLE biz.coach_task_transfer_log ( transfer_reason text, guard_checks jsonb, transfer_score numeric, - created_at timestamp with time zone DEFAULT now() NOT NULL + created_at timestamp with time zone DEFAULT now() NOT NULL, + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.coach_tasks ( @@ -160,7 +170,9 @@ CREATE TABLE biz.coach_tasks ( transfer_count integer DEFAULT 0 NOT NULL, transferred_from bigint, transferred_at timestamp with time zone, - completion_type character varying(10) + completion_type character varying(10), + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.connectors ( @@ -229,7 +241,9 @@ CREATE TABLE biz.recall_events ( pay_time timestamp with time zone NOT NULL, task_id bigint, task_type character varying(50), - created_at timestamp with time zone DEFAULT now() + created_at timestamp with time zone DEFAULT now(), + runtime_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_instance_id character varying(64) DEFAULT 'live'::character varying NOT NULL ); CREATE TABLE biz.salary_adjustments ( @@ -256,6 +270,19 @@ CREATE TABLE biz.site_code_history ( retired_at timestamp with time zone ); +CREATE TABLE biz.site_runtime_context ( + site_id bigint NOT NULL, + mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + sandbox_date date, + sandbox_instance_id character varying(64), + ai_mode character varying(20) DEFAULT 'live'::character varying NOT NULL, + status character varying(20) DEFAULT 'active'::character varying NOT NULL, + reason text, + updated_by bigint, + created_at timestamp with time zone DEFAULT now() NOT NULL, + updated_at timestamp with time zone DEFAULT now() NOT NULL +); + CREATE TABLE biz.sites ( id integer DEFAULT nextval('biz.sites_id_seq'::regclass) NOT NULL, tenant_id integer NOT NULL, @@ -360,6 +387,8 @@ ALTER TABLE biz.salary_adjustments ADD CONSTRAINT salary_adjustments_upload_batc ALTER TABLE biz.salary_adjustments ADD CONSTRAINT salary_adjustments_pkey PRIMARY KEY (id); ALTER TABLE biz.site_code_history ADD CONSTRAINT site_code_history_pkey PRIMARY KEY (id); ALTER TABLE biz.site_code_history ADD CONSTRAINT site_code_history_site_code_key UNIQUE (site_code); +ALTER TABLE biz.site_runtime_context ADD CONSTRAINT site_runtime_context_site_id_fkey FOREIGN KEY (site_id) REFERENCES biz.sites(site_id); +ALTER TABLE biz.site_runtime_context ADD CONSTRAINT site_runtime_context_pkey PRIMARY KEY (site_id); ALTER TABLE biz.sites ADD CONSTRAINT sites_tenant_id_fkey FOREIGN KEY (tenant_id) REFERENCES biz.tenants(id); ALTER TABLE biz.sites ADD CONSTRAINT sites_pkey PRIMARY KEY (id); ALTER TABLE biz.sites ADD CONSTRAINT sites_site_code_key UNIQUE (site_code); @@ -379,6 +408,7 @@ ALTER TABLE biz.trigger_jobs ADD CONSTRAINT trigger_jobs_job_name_key UNIQUE (jo -- 索引 CREATE INDEX idx_ai_cache_cleanup ON biz.ai_cache USING btree (cache_type, site_id, target_id, created_at); CREATE INDEX idx_ai_cache_lookup ON biz.ai_cache USING btree (cache_type, site_id, target_id, created_at DESC); +CREATE INDEX idx_ai_cache_runtime_lookup ON biz.ai_cache USING btree (cache_type, site_id, runtime_mode, sandbox_instance_id, target_id, created_at DESC); CREATE INDEX idx_ai_conv_app_site ON biz.ai_conversations USING btree (app_id, site_id, created_at DESC); CREATE INDEX idx_ai_conv_context ON biz.ai_conversations USING btree (user_id, site_id, context_type, context_id, last_message_at DESC NULLS LAST) WHERE (context_type IS NOT NULL); CREATE INDEX idx_ai_conv_last_msg ON biz.ai_conversations USING btree (user_id, site_id, last_message_at DESC NULLS LAST); @@ -390,18 +420,20 @@ CREATE INDEX idx_ai_run_logs_created_brin ON biz.ai_run_logs USING brin (created CREATE INDEX idx_ai_run_logs_site_app ON biz.ai_run_logs USING btree (site_id, app_type); CREATE INDEX idx_ai_run_logs_status ON biz.ai_run_logs USING btree (status); CREATE INDEX idx_ai_trigger_jobs_dedup ON biz.ai_trigger_jobs USING btree (event_type, member_id, site_id, created_at) WHERE ((status)::text <> 'skipped_duplicate'::text); +CREATE INDEX idx_ai_trigger_jobs_runtime_site ON biz.ai_trigger_jobs USING btree (site_id, runtime_mode, sandbox_instance_id, event_type, status); CREATE INDEX idx_ai_trigger_jobs_site ON biz.ai_trigger_jobs USING btree (site_id, event_type); CREATE INDEX idx_ai_trigger_jobs_status ON biz.ai_trigger_jobs USING btree (status); CREATE INDEX idx_transfer_log_member ON biz.coach_task_transfer_log USING btree (member_id, created_at DESC); CREATE INDEX idx_transfer_log_site_created ON biz.coach_task_transfer_log USING btree (site_id, created_at DESC); CREATE INDEX idx_coach_tasks_assistant_status ON biz.coach_tasks USING btree (site_id, assistant_id, status); -CREATE UNIQUE INDEX idx_coach_tasks_site_assistant_member_type ON biz.coach_tasks USING btree (site_id, assistant_id, member_id, task_type) WHERE ((status)::text = 'active'::text); +CREATE INDEX idx_coach_tasks_runtime_assistant_status ON biz.coach_tasks USING btree (site_id, runtime_mode, sandbox_instance_id, assistant_id, status); +CREATE UNIQUE INDEX idx_coach_tasks_runtime_unique_active ON biz.coach_tasks USING btree (site_id, assistant_id, member_id, task_type, runtime_mode, sandbox_instance_id) WHERE ((status)::text = 'active'::text); CREATE INDEX idx_task_monthly_assistant ON biz.dws_assistant_task_monthly USING btree (assistant_id, stat_month DESC); CREATE INDEX idx_task_monthly_site_month ON biz.dws_assistant_task_monthly USING btree (site_id, stat_month DESC); CREATE INDEX idx_excel_log_site ON biz.excel_upload_log USING btree (site_id, created_at DESC); CREATE INDEX idx_notes_target ON biz.notes USING btree (site_id, target_type, target_id); CREATE INDEX idx_recall_events_assistant_pay ON biz.recall_events USING btree (site_id, assistant_id, pay_time); -CREATE UNIQUE INDEX idx_recall_events_site_assistant_member_day ON biz.recall_events USING btree (site_id, assistant_id, member_id, date_trunc('day'::text, (pay_time AT TIME ZONE 'Asia/Shanghai'::text))); +CREATE UNIQUE INDEX idx_recall_events_runtime_site_assistant_member_day ON biz.recall_events USING btree (site_id, assistant_id, member_id, runtime_mode, sandbox_instance_id, date_trunc('day'::text, (pay_time AT TIME ZONE 'Asia/Shanghai'::text))); CREATE INDEX idx_salary_adj_assistant_month ON biz.salary_adjustments USING btree (assistant_id, salary_month); CREATE INDEX idx_salary_adj_site_month ON biz.salary_adjustments USING btree (site_id, salary_month); diff --git a/docs/database/ddl/zqyy_app__public.sql b/docs/database/ddl/zqyy_app__public.sql index a5247a2..5ebdc75 100644 --- a/docs/database/ddl/zqyy_app__public.sql +++ b/docs/database/ddl/zqyy_app__public.sql @@ -1,6 +1,6 @@ -- ============================================================================= -- zqyy_app / public（小程序业务表） --- 生成日期：2026-04-12 +-- 生成日期：2026-05-02 -- 来源：测试库（通过脚本自动导出） -- ============================================================================= diff --git a/docs/deployment/LAUNCH-CHECKLIST.md b/docs/deployment/LAUNCH-CHECKLIST.md index a23f898..9de5a87 100644 --- a/docs/deployment/LAUNCH-CHECKLIST.md +++ b/docs/deployment/LAUNCH-CHECKLIST.md @@ -43,6 +43,7 @@ New-Item -ItemType Directory -Path D:\NeoZQYY\scripts -Force > 所有运行时输出（日志、JSON 导出、报告）统一放在 `repo/export/` 下， > 路径由 `.env` 中的 `LOG_ROOT`、`EXPORT_ROOT` 等变量控制。 > 详见 [`docs/deployment/EXPORT-PATHS.md`](EXPORT-PATHS.md)。 +> 服务器 SSH 别名、部署路径和反代入口见 [`docs/deployment/SERVER-ACCESS.md`](SERVER-ACCESS.md)。 ```powershell # 克隆仓库 diff --git a/docs/deployment/SERVER-ACCESS.md b/docs/deployment/SERVER-ACCESS.md new file mode 100644 index 0000000..7721379 --- /dev/null +++ b/docs/deployment/SERVER-ACCESS.md @@ -0,0 +1,121 @@ +# 服务器访问台账 + +> 最后更新：2026-05-01 +> 来源：本机 `C:\Users\Administrator\.ssh\config` 与部署文档线索。 + +本文记录 NeoZQYY 部署、运维、数据库、跳板机相关服务器的登录入口，供部署和故障排查时快速定位。 + +安全约定： + +- 本文只记录主机别名、地址、用户、用途和密钥文件路径。 +- 禁止写入私钥内容、服务器密码、数据库密码、token、证书私钥。 +- 如果密钥轮换或服务器下线，需要同步更新本文。 + +## 核心部署服务器 + +- `ds-office-win` + - 地址：`100.64.0.4` + - 用户：`Administrator` + - 认证方式：密钥 `~/.ssh/ds-office-win` + - 用途：Windows Server，PostgreSQL、小程序后端测试/正式环境部署 + +- `txyun-zqyy-ubuntu-server` + - 地址：`100.64.0.1` + - 用户：`root` + - 认证方式：密钥 `~/.ssh/ZQYY-TX-Server-Ubuntu` + - 用途：腾讯云跳板机，Nginx、Headscale/Tailscale、RustDesk、SSL + +## Git 与代码托管 + +- `git-ZQYY` + - 地址：`git.langlangzhuoqiu.cn` + - 用户：`git` + - 认证方式：密钥 `C:/Users/Administrator/.ssh/1` + - 用途：NeoZQYY 仓库的 Gitea SSH 访问 + +- `ds-git-tx-server-ubuntu` + - 地址：`100.64.0.11:222` + - 用户：`git` + - 认证方式：密钥 `~/.ssh/id_ed25519_gitea` + - 用途：腾讯云 Gitea SSH 访问 + +- `ds-gitserver-ubuntu` + - 地址：`100.64.0.11` + - 用户：`root` + - 认证方式：密钥 `~/.ssh/ds-gitserver-ubuntu` + - 用途：腾讯云 Git 服务器管理 + +## 旧开发环境与其他服务器 + +- `old-vm-win-dev` + - 地址：`100.64.0.3` + - 用户：`Administrator` + - 认证方式：密钥 `~/.ssh/old-vm-win-dev` + - 用途：旧 Windows 开发虚拟机，待废弃；用于历史会话或旧环境追溯 + +- `vm-ubuntu` + - 地址：`100.64.0.10` + - 用户：`root` + - 认证方式：密钥 `~/.ssh/vmubuntu` + - 用途：旧 Ubuntu 开发虚拟机，待废弃 + +- `ds-shgz-tx-server-ubuntu` + - 地址：`100.64.0.12` + - 用户：`root` + - 认证方式：密钥 `~/.ssh/ds-tx-SHGZ-server-ubuntu` + - 用途：社工服务器，非 NeoZQYY 核心部署链路 + +## NeoZQYY 部署路径速查 + +核心部署机器：`ds-office-win` / `100.64.0.4`。 + +- 测试环境 + - 服务器路径：`D:\NeoZQYY\test\repo` + - Git 分支：`test` + - 后端端口：`8001` + - 数据库：`test_etl_feiqiu` / `test_zqyy_app` + +- 正式环境 + - 服务器路径：`D:\NeoZQYY\prod\repo` + - Git 分支：`master` + - 后端端口：`8000` + - 数据库：`etl_feiqiu` / `zqyy_app` + +常用登录命令： + +```powershell +ssh ds-office-win +ssh txyun-zqyy-ubuntu-server +ssh git-ZQYY +``` + +常用部署路径： + +```powershell +# 测试环境 +cd D:\NeoZQYY\test\repo + +# 正式环境 +cd D:\NeoZQYY\prod\repo +``` + +## 反代与公网入口 + +- `https://api.langlangzhuoqiu.cn`：正式后端 API，目标 `100.64.0.4:8000`。 +- `https://test-api.langlangzhuoqiu.cn`：测试后端 API，目标 `100.64.0.4:8001`，如已配置独立测试域名。 +- `wss://socket.langlangzhuoqiu.cn`：后端 WebSocket，小程序 socket 合法域名。 +- `https://file.langlangzhuoqiu.cn`：文件服务入口，小程序 upload/download 合法域名。 + +反代由 `txyun-zqyy-ubuntu-server` 维护，Nginx、SSL 和 Tailscale/Headscale 相关问题优先检查该机器。 + +## 缺口记录 + +当前尚未在项目中找到以下信息的完整台账： + +- RDP / RustDesk 登录方式。 +- Windows 服务器本地密码或应急账号。 +- Tailscale / Headscale 管理后台登录方式。 +- SSL 证书签发账号、续期任务位置。 +- 服务器密钥轮换记录。 + +这些信息不应直接写入 Git 明文文档；如需保存，建议放入受控密码管理器，并在本文中只记录“存放位置/负责人/更新日期”。 diff --git a/scripts/ab_test_app2_prompt.py b/scripts/ab_test_app2_prompt.py new file mode 100644 index 0000000..82752a6 --- /dev/null +++ b/scripts/ab_test_app2_prompt.py @@ -0,0 +1,223 @@ +"""App2 财务洞察 system prompt A/B 测试脚本。 + +流程： +- 对同一 payload 连续调用百炼 N 次（默认 10 次），绕过 AI cache +- 存档每次原始 JSON 到 export/ai-ab-test/round_