diff --git a/.claude/hooks/post_edit_db_doc_sync.py b/.claude/hooks/post_edit_db_doc_sync.py
new file mode 100644
index 0000000..9fb2008
--- /dev/null
+++ b/.claude/hooks/post_edit_db_doc_sync.py
@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""PostToolUse hook: 编辑 db/ 下 SQL 文件后提醒同步 docs/database/"""
+import json, re, sys
+
+try:
+ data = json.load(sys.stdin)
+except Exception:
+ sys.exit(0)
+
+fp = (data.get("tool_input") or {}).get("file_path", "")
+if not fp:
+ sys.exit(0)
+
+rel = re.sub(r"^.*?NeoZQYY[/\\]", "", fp.replace("\\", "/"))
+
+# 匹配 db/ 下的 SQL 文件（schemas、migrations、脚本等）
+if re.search(r"^db/.*\.sql$", rel):
+ print(json.dumps({
+ "hookSpecificOutput": {
+ "hookEventName": "PostToolUse",
+ "additionalContext": (
+ f"[db-doc-sync] 已编辑数据库文件: {rel} — "
+ "根据 Schema 变更规则，完成后须同步更新 docs/database/（变更说明、兼容性、回滚策略、验证 SQL）"
+ )
+ }
+ }))
diff --git a/.claude/hooks/post_edit_rls_dual_schema.py b/.claude/hooks/post_edit_rls_dual_schema.py
new file mode 100644
index 0000000..1c40e26
--- /dev/null
+++ b/.claude/hooks/post_edit_rls_dual_schema.py
@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""PostToolUse hook: 编辑含 CREATE VIEW 的 SQL 文件时提醒双 Schema 规则"""
+import json, re, sys
+
+try:
+ data = json.load(sys.stdin)
+except Exception:
+ sys.exit(0)
+
+fp = (data.get("tool_input") or {}).get("file_path", "")
+if not fp:
+ sys.exit(0)
+
+rel = re.sub(r"^.*?NeoZQYY[/\\]", "", fp.replace("\\", "/"))
+
+# 仅检查 db/ 下的 SQL 文件
+if not re.search(r"^db/.*\.sql$", rel):
+ sys.exit(0)
+
+# 读取文件内容检查是否包含 CREATE VIEW
+try:
+ with open(fp, "r", encoding="utf-8") as f:
+ content = f.read()
+except Exception:
+ sys.exit(0)
+
+# 检测 CREATE [OR REPLACE] VIEW 语句
+if re.search(r"CREATE\s+(OR\s+REPLACE\s+)?VIEW\s+(dws|dwd|core)\.", content, re.IGNORECASE):
+ print(json.dumps({
+ "hookSpecificOutput": {
+ "hookEventName": "PostToolUse",
+ "additionalContext": (
+ f"[rls-dual-schema] 检测到 {rel} 中包含 dws/dwd/core schema 的 VIEW 定义 — "
+ "根据 RLS 视图双 Schema 规则，必须同时在原 schema 和 app schema 创建对应视图，否则后端查询会失败。"
+ )
+ }
+ }))
diff --git a/.claude/hooks/pre_demo_protect.py b/.claude/hooks/pre_demo_protect.py
new file mode 100644
index 0000000..18b8f2b
--- /dev/null
+++ b/.claude/hooks/pre_demo_protect.py
@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: 保护 demo-miniprogram 目录不被删除或移入 _DEL/"""
+import json, re, sys
+
+try:
+ data = json.load(sys.stdin)
+except Exception:
+ sys.exit(0)
+
+tool = data.get("tool_name", "")
+tool_input = data.get("tool_input") or {}
+
+DEMO_DIR = "demo-miniprogram"
+
+if tool == "Bash":
+ cmd = tool_input.get("command", "")
+ # 检查命令是否在对 demo-miniprogram 执行删除/移动操作
+ if DEMO_DIR in cmd and re.search(r"\b(rm|rmdir|del|move|mv)\b", cmd, re.IGNORECASE):
+ # 允许 mv 到非 _DEL 目录（如正常重命名），但阻止移入 _DEL
+ if re.search(r"\brm\b|\brmdir\b|\bdel\b", cmd, re.IGNORECASE) or "_DEL" in cmd:
+ print(json.dumps({
+ "decision": "block",
+ "reason": f"[demo-protect] apps/{DEMO_DIR}/ 禁止删除或移入 _DEL/。该目录是 UI 样式标杆校对基准。"
+ }))
diff --git a/.claude/hooks/pre_read_archived_block.py b/.claude/hooks/pre_read_archived_block.py
new file mode 100644
index 0000000..8877287
--- /dev/null
+++ b/.claude/hooks/pre_read_archived_block.py
@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: 阻止读取 _archived/ 目录下的文件"""
+import json, re, sys
+
+try:
+ data = json.load(sys.stdin)
+except Exception:
+ sys.exit(0)
+
+tool = data.get("tool_name", "")
+tool_input = data.get("tool_input") or {}
+
+# 从不同工具中提取路径
+path = ""
+if tool in ("Read", "Edit", "Write"):
+ path = tool_input.get("file_path", "")
+elif tool == "Glob":
+ path = tool_input.get("path", "")
+
+path = path.replace("\\", "/")
+
+if re.search(r"/_archived/|/_archived$|^_archived/", path) or re.search(
+ r"[/\\]_archived[/\\]", tool_input.get("file_path", "")
+):
+ print(json.dumps({
+ "decision": "block",
+ "reason": "[archived-block] _archived/ 目录内容已废弃，禁止读取或参考。请使用当前版本的文件。"
+ }))
diff --git a/.claude/hooks/stop_audit_check.py b/.claude/hooks/stop_audit_check.py
index 93451b2..5dca45d 100644
--- a/.claude/hooks/stop_audit_check.py
+++ b/.claude/hooks/stop_audit_check.py
@@ -22,8 +22,5 @@ except Exception:
high_risk = result.get("high_risk_files", [])
if result.get("audit_required", False) and len(high_risk) > 0:
print(json.dumps({
- "hookSpecificOutput": {
- "hookEventName": "Stop",
- "additionalContext": f"[audit-check] 当前有 {len(high_risk)} 个高风险文件变更未审计。建议执行 /audit。"
- }
+ "systemMessage": f"[audit-check] 当前有 {len(high_risk)} 个高风险文件变更未审计。建议执行 /audit。"
}))
diff --git a/.claude/hooks/stop_verify_check.py b/.claude/hooks/stop_verify_check.py
new file mode 100644
index 0000000..0e0978c
--- /dev/null
+++ b/.claude/hooks/stop_verify_check.py
@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Stop hook: 检查是否有逻辑改动未验证（未跑测试）、DDL 变更未建迁移"""
+import json, re, subprocess, sys, os
+
+project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+
+try:
+ r = subprocess.run(
+ ["git", "diff", "--name-only"],
+ capture_output=True, text=True, timeout=10, cwd=project_dir,
+ )
+ staged = subprocess.run(
+ ["git", "diff", "--name-only", "--cached"],
+ capture_output=True, text=True, timeout=10, cwd=project_dir,
+ )
+ changed = set((r.stdout + "\n" + staged.stdout).strip().splitlines())
+except Exception:
+ sys.exit(0)
+
+if not changed:
+ sys.exit(0)
+
+warnings = []
+
+# --- 1. 逻辑改动未验证检查 ---
+LOGIC_PATTERNS = [
+ r"^apps/etl/connectors/feiqiu/(tasks|loaders|scd|orchestration|config|database|models|quality)/",
+ r"^apps/backend/app/(routers|services|auth|schemas)/",
+ r"^packages/shared/",
+]
+
+logic_files = [
+ f for f in changed
+ if any(re.search(p, f) for p in LOGIC_PATTERNS)
+]
+
+if logic_files:
+ # 检查是否有测试结果文件被修改（间接判断是否跑了测试）
+ # 更可靠的方式：检查变更中是否包含测试文件
+ test_files = [f for f in changed if re.search(r"tests?/", f)]
+ if not test_files:
+ count = len(logic_files)
+ warnings.append(
+ f"本次会话修改了 {count} 个逻辑文件但未发现测试文件变更，"
+ "建议运行相关测试验证（单元/集成/lint）"
+ )
+
+# --- 2. DDL 变更未建迁移检查 ---
+schema_files = [f for f in changed if re.search(r"^db/[^/]+/schemas/.*\.sql$", f)]
+migration_files = [f for f in changed if re.search(r"^db/[^/]+/migrations/.*\.sql$", f)]
+
+if schema_files and not migration_files:
+ # 也检查 untracked 的迁移文件
+ try:
+ untracked = subprocess.run(
+ ["git", "ls-files", "--others", "--exclude-standard", "db/"],
+ capture_output=True, text=True, timeout=10, cwd=project_dir,
+ )
+ new_migrations = [
+ f for f in untracked.stdout.strip().splitlines()
+ if re.search(r"^db/[^/]+/migrations/.*\.sql$", f)
+ ]
+ except Exception:
+ new_migrations = []
+
+ if not new_migrations:
+ dbs = set()
+ for f in schema_files:
+ m = re.match(r"^db/([^/]+)/", f)
+ if m:
+ dbs.add(m.group(1))
+ db_list = ", ".join(sorted(dbs))
+ warnings.append(
+ f"检测到 {db_list} 的 schemas/ DDL 已变更但无对应迁移脚本，"
+ "建议在 db/*/migrations/ 创建增量迁移文件"
+ )
+
+# --- 输出 ---
+if warnings:
+ msg = "[verify-check] " + " | ".join(warnings)
+ print(json.dumps({"systemMessage": msg}))
diff --git a/.claude/settings.json b/.claude/settings.json
index 92a7e27..31134bd 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -32,7 +32,10 @@
"Bash(cp -r tmp _DEL/tmp_backup)",
"Bash(*)",
"Bash(touch tmp/.gitkeep)",
- "Bash(ls -la c:/NeoZQYY/docs/audit/session_logs/_session_index*.json)"
+ "Bash(ls -la c:/NeoZQYY/docs/audit/session_logs/_session_index*.json)",
+ "mcp__pg-etl-test__execute_sql",
+ "mcp__pg-app-test__execute_sql",
+ "mcp__pg-app-test__list_schemas"
],
"additionalDirectories": [
"C:\\Users\\Administrator\\.claude",
@@ -52,6 +55,28 @@
]
}
],
+ "PreToolUse": [
+ {
+ "matcher": "Read|Edit|Write|Glob",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre_read_archived_block.py\"",
+ "timeout": 5
+ }
+ ]
+ },
+ {
+ "matcher": "Bash|Edit|Write",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre_demo_protect.py\"",
+ "timeout": 5
+ }
+ ]
+ }
+ ],
"PostToolUse": [
{
"matcher": "Edit|Write",
@@ -62,6 +87,26 @@
"timeout": 5
}
]
+ },
+ {
+ "matcher": "Edit|Write",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/post_edit_db_doc_sync.py\"",
+ "timeout": 5
+ }
+ ]
+ },
+ {
+ "matcher": "Edit|Write",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/post_edit_rls_dual_schema.py\"",
+ "timeout": 10
+ }
+ ]
}
],
"Stop": [
@@ -73,6 +118,15 @@
"timeout": 15
}
]
+ },
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/stop_verify_check.py\"",
+ "timeout": 15
+ }
+ ]
}
]
}
diff --git a/.env b/.env
index 6f5a9d4..d1d0dcf 100644
--- a/.env
+++ b/.env
@@ -104,25 +104,37 @@ SYSTEM_LOG_ROOT=C:/NeoZQYY/export/SYSTEM/LOGS
# ------------------------------------------------------------------------------
# 后端结构化日志目录
BACKEND_LOG_ROOT=C:/NeoZQYY/export/BACKEND/LOGS
+# 用户头像存储目录
+AVATAR_EXPORT_PATH=C:/NeoZQYY/export/BACKEND/avatars
# ------------------------------------------------------------------------------
-# 阿里云百炼 AI 配置
+# DashScope AI 配置（百炼 Application API）
# CHANGE 2026-02-23 | 从 PRD 文档迁移至 .env，禁止在文档中明文存放
+# CHANGE P14 | BAILIAN_* → DASHSCOPE_*；移除 BASE_URL/MODEL（Application API 不需要）
# ------------------------------------------------------------------------------
-BAILIAN_API_KEY=sk-6def29cab3474cc797e52b82a46a5dba
-BAILIAN_MODEL=qwen-plus
-BAILIAN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
-BAILIAN_TEST_APP_ID=541edb3d5fcd4c18b13cbad81bb5fb9d
+DASHSCOPE_API_KEY=sk-6def29cab3474cc797e52b82a46a5dba
+DASHSCOPE_WORKSPACE_ID=
-# CHANGE 2026-03-05 | 8 个百炼 AI 应用 ID（从百炼平台获取，2026-03-05 更新）
-BAILIAN_APP_ID_1_CHAT=979dabe6f22a43989632b8c662cac97c
-BAILIAN_APP_ID_2_FINANCE=1dcdb5f39c3040b6af8ef79215b9b051
-BAILIAN_APP_ID_3_CLUE=708bf45439cd48c7ab9a514d03482890
-BAILIAN_APP_ID_4_ANALYSIS=ea7b1c374f574b9a925a2fb5789a9b90
-BAILIAN_APP_ID_5_TACTICS=46f54e6053df4bb0b83be29366025cf6
-BAILIAN_APP_ID_6_NOTE=025bb344146b4e4e8be30c444adab3b4
-BAILIAN_APP_ID_7_CUSTOMER=df35e06991b24d49971c03c6428a9c87
-BAILIAN_APP_ID_8_CONSOLIDATE=407dfb89283b4196934eec5fefe3ebc2
+# 8 个百炼 AI 应用 ID（从百炼平台获取，通过 app_id 指定应用）
+# 应用 1：通用对话 | 应用 2：财务洞察 | 应用 3：客户数据维客线索分析
+# 应用 4：关系分析/任务建议 | 应用 5：话术参考 | 应用 6：备注分析
+# 应用 7：客户分析 | 应用 8：维客线索整理
+DASHSCOPE_APP_ID_1_CHAT=979dabe6f22a43989632b8c662cac97c
+DASHSCOPE_APP_ID_2_FINANCE=1dcdb5f39c3040b6af8ef79215b9b051
+DASHSCOPE_APP_ID_3_CLUE=708bf45439cd48c7ab9a514d03482890
+DASHSCOPE_APP_ID_4_ANALYSIS=ea7b1c374f574b9a925a2fb5789a9b90
+DASHSCOPE_APP_ID_5_TACTICS=46f54e6053df4bb0b83be29366025cf6
+DASHSCOPE_APP_ID_6_NOTE=025bb344146b4e4e8be30c444adab3b4
+DASHSCOPE_APP_ID_7_CUSTOMER=df35e06991b24d49971c03c6428a9c87
+DASHSCOPE_APP_ID_8_CONSOLIDATE=407dfb89283b4196934eec5fefe3ebc2
+# 应用 9：Session 日志摘要生成（Kiro agent_on_stop + batch_generate_summaries 使用）
+DASHSCOPE_APP_ID_SUMMARY=e0cf8913b1ee4a4eb9464cc1ee0bf300
+
+# 内部 API 认证 token（ETL 等内部服务调用 /api/internal/* 端点时使用）
+INTERNAL_API_TOKEN=C4Rs45fEoMC3u2PR4-jvakl8SBYpU9kV7JFiTj-TJAc
+
+# 后端 API 地址（ETL 触发 AI 事件时使用，如 http://localhost:8000）
+BACKEND_API_URL=http://localhost:8000
# ------------------------------------------------------------------------------
# 微信小程序
@@ -147,3 +159,18 @@ PIPELINE_RATE_MAX=2.0
OPS_SERVER_BASE=C:/NeoZQYY
ETL_PROJECT_PATH=C:/NeoZQYY/apps/etl/connectors/feiqiu
ETL_PYTHON_EXECUTABLE=C:/NeoZQYY/.venv/Scripts/python.exe
+
+# === Dev Trace Log ===
+# 全链路请求追踪日志（仅开发/测试环境使用，生产环境关闭）
+DEV_TRACE_ENABLED=true
+DEV_TRACE_LOG_DIR=export/dev-trace-logs
+DEV_TRACE_LOG_RETENTION_DAYS=7
+DEV_TRACE_LOG_SQL=true
+DEV_TRACE_LOG_PARAMS=true
+
+# ------------------------------------------------------------------------------
+# DWS 工资计算配置
+# CHANGE 2026-03-27 | 允许非月初结算期运行工资计算任务（临时开关）
+# 正常调度只在月初 1-5 号跑上月工资，此开关允许月中手动跑当月工资
+# ------------------------------------------------------------------------------
+DWS_SALARY_ALLOW_OUT_OF_CYCLE=true
diff --git a/.mcp.json b/.mcp.json
index 356f2a3..126aef8 100644
--- a/.mcp.json
+++ b/.mcp.json
@@ -33,18 +33,18 @@
"disabled": false
},
"weixin-devtools-mcp": {
- "command": "npx",
- "args": ["-y", "weixin-devtools-mcp", "--tools-profile=full", "--ws-endpoint=ws://127.0.0.1:9420"],
+ "command": "cmd",
+ "args": ["/c", "npx", "-y", "weixin-devtools-mcp", "--tools-profile=full", "--ws-endpoint=ws://127.0.0.1:9420"],
"env": {
"WECHAT_DEVTOOLS_CLI": "C:\\dev\\WechatDevtools\\cli.bat",
"WECHAT_DEVTOOLS_PROJECT": "C:\\NeoZQYY\\apps\\miniprogram"
},
- "disabled": true
+ "disabled": false
},
"playwright": {
- "command": "npx",
- "args": ["@playwright/mcp@latest"],
- "disabled": true
+ "command": "cmd",
+ "args": ["/c", "npx", "@playwright/mcp@latest"],
+ "disabled": false
},
"openapi": {
"command": "uv",
@@ -61,7 +61,7 @@
"env": {
"PYTHONUTF8": "1"
},
- "disabled": true
+ "disabled": false
}
}
}
diff --git a/CLAUDE.md b/CLAUDE.md
index e02f04e..bac9402 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -156,6 +156,15 @@ cd apps/miniprogram && npm test # 小程序 Jest
例外：纯格式调整、注释/文档纯文字修改、用户说"直接改/跳过调研"、新建文件且不涉及已有逻辑
+## 改动后验证（强制）
+
+逻辑改动完成后，必须执行以下验证步骤：
+1. 运行相关测试（单元/集成/lint），如无法运行需说明原因
+2. 输出 diff 摘要（改了哪些文件、每个文件改动要点）
+3. 列出未覆盖的风险点（未测试的路径、可能的副作用、需要人工验证的场景）
+
+例外：纯格式/文档/注释调整、用户说"跳过验证"
+
## 数据库 Schema 变更规则
修改任何影响 PostgreSQL schema 的内容（迁移/DDL/表定义/ORM 模型）时，必须同步更新 `docs/database/`：
diff --git a/apps/backend/app/database.py b/apps/backend/app/database.py
index 2739979..559c1bb 100644
--- a/apps/backend/app/database.py
+++ b/apps/backend/app/database.py
@@ -31,6 +31,31 @@ from app.config import (
ETL_DB_USER,
)
+# TCP keepalive 参数：防止长期运行的后台服务连接被网络设备/PostgreSQL 回收
+_KEEPALIVE_KWARGS = {
+ "keepalives": 1,
+ "keepalives_idle": 60, # 空闲 60 秒后开始探测
+ "keepalives_interval": 10, # 每 10 秒探测一次
+ "keepalives_count": 3, # 连续 3 次失败判定断开
+}
+
+# 连接重试参数：应对 PostgreSQL 瞬时不可用（Tailscale 网络抖动等）
+_CONNECT_MAX_RETRIES = 3
+_CONNECT_RETRY_DELAY = 1.0 # 秒
+
+
+def _connect_with_retry(connect_fn, max_retries=_CONNECT_MAX_RETRIES):
+ """带重试的数据库连接，应对服务端瞬时拒绝连接。"""
+ last_exc = None
+ for attempt in range(max_retries):
+ try:
+ return connect_fn()
+ except psycopg2.OperationalError as e:
+ last_exc = e
+ if attempt < max_retries - 1:
+ time.sleep(_CONNECT_RETRY_DELAY * (attempt + 1))
+ raise last_exc
+
def get_connection() -> PgConnection:
"""
@@ -49,13 +74,14 @@ def get_connection() -> PgConnection:
start = time.perf_counter() if should_trace else 0.0
- conn = psycopg2.connect(
+ conn = _connect_with_retry(lambda: psycopg2.connect(
host=DB_HOST,
port=DB_PORT,
user=DB_USER,
password=DB_PASSWORD,
dbname=APP_DB_NAME,
- )
+ **_KEEPALIVE_KWARGS,
+ ))
if should_trace:
from datetime import datetime
@@ -86,13 +112,14 @@ def get_etl_global_readonly_connection() -> PgConnection:
用于系统管理后台等不需要门店隔离的场景（如 ETL 状态监控）。
"""
- conn = psycopg2.connect(
+ conn = _connect_with_retry(lambda: psycopg2.connect(
host=ETL_DB_HOST,
port=ETL_DB_PORT,
user=ETL_DB_USER,
password=ETL_DB_PASSWORD,
dbname=ETL_DB_NAME,
- )
+ **_KEEPALIVE_KWARGS,
+ ))
try:
conn.autocommit = False
with conn.cursor() as cur:
@@ -121,13 +148,14 @@ def get_etl_readonly_connection(site_id: int | str) -> PgConnection:
finally:
conn.close()
"""
- conn = psycopg2.connect(
+ conn = _connect_with_retry(lambda: psycopg2.connect(
host=ETL_DB_HOST,
port=ETL_DB_PORT,
user=ETL_DB_USER,
password=ETL_DB_PASSWORD,
dbname=ETL_DB_NAME,
- )
+ **_KEEPALIVE_KWARGS,
+ ))
try:
conn.autocommit = False
with conn.cursor() as cur:
@@ -142,3 +170,23 @@ def get_etl_readonly_connection(site_id: int | str) -> PgConnection:
conn.close()
raise
return conn
+
+
+def get_etl_write_connection() -> PgConnection:
+ """
+ 获取 ETL 数据库（etl_feiqiu）的可写连接。
+
+ 仅用于后端需要回写 ETL 汇总表的场景（如 task_generator 回写关系指数统计）。
+ 不设置 RLS 隔离，调用方需在 SQL 中显式指定 site_id。
+ 调用方负责关闭连接。
+ """
+ conn = _connect_with_retry(lambda: psycopg2.connect(
+ host=ETL_DB_HOST,
+ port=ETL_DB_PORT,
+ user=ETL_DB_USER,
+ password=ETL_DB_PASSWORD,
+ dbname=ETL_DB_NAME,
+ **_KEEPALIVE_KWARGS,
+ ))
+ conn.autocommit = False
+ return conn
diff --git a/apps/backend/app/routers/internal_events.py b/apps/backend/app/routers/internal_events.py
index 6ba671c..6345157 100644
--- a/apps/backend/app/routers/internal_events.py
+++ b/apps/backend/app/routers/internal_events.py
@@ -39,6 +39,61 @@ class RunJobByNameResponse(BaseModel):
job_name: str
+class EtlCompletedRequest(BaseModel):
+ """ETL 完成通知请求体。"""
+ pipeline: str = Field(default="api_full", description="完成的 pipeline 名称")
+ site_id: int | None = Field(default=None, description="门店 ID（可选）")
+
+
+class EtlCompletedResponse(BaseModel):
+ """ETL 完成编排结果。"""
+ success: bool
+ recall_result: dict | None = None
+ task_gen_result: dict | None = None
+ message: str = ""
+
+
+@router.post("/etl-completed", response_model=EtlCompletedResponse)
+async def etl_completed_endpoint(
+ body: EtlCompletedRequest,
+ _token: str = Depends(verify_internal_token),
+) -> EtlCompletedResponse:
+ """ETL pipeline 完成后的统一编排入口。
+
+ CHANGE 2026-04-07 | Fix-12：ETL 完成后自动触发。
+ 编排顺序：recall_detector.run() → task_generator.run()
+ """
+ from app.services import recall_detector, task_generator
+
+ recall_result = None
+ task_gen_result = None
+ errors = []
+
+ # Step 1: 先检查召回完成（含回溯）
+ try:
+ recall_result = recall_detector.run()
+ logger.info("ETL 编排 Step1 recall_detector 完成: %s", recall_result)
+ except Exception:
+ logger.exception("ETL 编排 Step1 recall_detector 失败")
+ errors.append("recall_detector failed")
+
+ # Step 2: 再生成新任务
+ try:
+ task_gen_result = task_generator.run()
+ logger.info("ETL 编排 Step2 task_generator 完成: %s", task_gen_result)
+ except Exception:
+ logger.exception("ETL 编排 Step2 task_generator 失败")
+ errors.append("task_generator failed")
+
+ success = len(errors) == 0
+ return EtlCompletedResponse(
+ success=success,
+ recall_result=recall_result,
+ task_gen_result=task_gen_result,
+ message="; ".join(errors) if errors else "ok",
+ )
+
+
@router.post("/run-job", response_model=RunJobByNameResponse)
async def run_job_by_name_endpoint(
body: RunJobByNameRequest,
diff --git a/apps/backend/app/routers/xcx_tasks.py b/apps/backend/app/routers/xcx_tasks.py
index 2248805..5f9d5eb 100644
--- a/apps/backend/app/routers/xcx_tasks.py
+++ b/apps/backend/app/routers/xcx_tasks.py
@@ -12,6 +12,7 @@
- POST /api/xcx/tasks/{id}/restore — 恢复任务
所有端点均需 JWT（approved 状态）。
+回访任务通过提交备注自动完成（note_service），不提供手动完成接口。
"""
from __future__ import annotations
@@ -20,6 +21,7 @@ from fastapi import APIRouter, Depends, Query
from app.auth.dependencies import CurrentUser
from app.middleware.permission import require_approved, require_permission
+
from app.schemas.xcx_tasks import (
AbandonRequest,
TaskDetailResponse,
diff --git a/apps/backend/app/services/board_service.py b/apps/backend/app/services/board_service.py
index d224388..1ab31a3 100644
--- a/apps/backend/app/services/board_service.py
+++ b/apps/backend/app/services/board_service.py
@@ -375,9 +375,9 @@ async def get_coach_board(
"task_total": task_recall + task_callback,
})
- # 7. 排序
+ # 7. 排序（id 作 tiebreaker 保证分页稳定）
sort_key, sort_desc = _SORT_KEY_MAP.get(sort, ("perf_hours", True))
- items.sort(key=lambda x: x.get(sort_key, 0), reverse=sort_desc)
+ items.sort(key=lambda x: (x.get(sort_key, 0), x.get("id", 0)), reverse=sort_desc)
# 移除内部排序字段
for item in items:
@@ -406,7 +406,9 @@ def _query_coach_tasks(
"""
查询助教任务完成数（BOARD-1 task 维度）。
- 来源: biz.coach_tasks，按 task_type 分类统计 recall/callback。
+ CHANGE 2026-04-08 | Fix-13 改造：
+ - recall: 广义召回数（从 biz.recall_events 统计，按天去重，不重复叠加）
+ - callback: 回访完成数（从 biz.coach_tasks 统计，status='completed'）
"""
if not assistant_ids:
return {}
@@ -414,26 +416,42 @@ def _query_coach_tasks(
result: dict[int, dict] = {}
try:
with conn.cursor() as cur:
+ # 广义召回数：从 recall_events 统计（天然去重）
cur.execute(
"""
- SELECT assistant_id,
- COUNT(*) FILTER (WHERE task_type IN ('high_priority_recall', 'priority_recall')) AS recall_count,
- COUNT(*) FILTER (WHERE task_type = 'relationship_building') AS callback_count
- FROM biz.coach_tasks
+ SELECT assistant_id, COUNT(*) AS recall_count
+ FROM biz.recall_events
WHERE assistant_id = ANY(%s)
AND site_id = %s
- AND completed_at >= %s::date
- AND completed_at <= %s::date
- AND status = 'completed'
+ AND pay_time >= %s::date
+ AND pay_time < (%s::date + INTERVAL '1 day')
GROUP BY assistant_id
""",
(assistant_ids, site_id, start_date, end_date),
)
for row in cur.fetchall():
- result[row[0]] = {
- "recall": row[1] or 0,
- "callback": row[2] or 0,
- }
+ result.setdefault(row[0], {"recall": 0, "callback": 0})
+ result[row[0]]["recall"] = row[1] or 0
+
+ # 回访完成数：从 coach_tasks 统计
+ cur.execute(
+ """
+ SELECT assistant_id, COUNT(*) AS callback_count
+ FROM biz.coach_tasks
+ WHERE assistant_id = ANY(%s)
+ AND site_id = %s
+ AND completed_at >= %s::date
+ AND completed_at < (%s::date + INTERVAL '1 day')::timestamptz
+ AND status = 'completed'
+ AND task_type = 'follow_up_visit'
+ GROUP BY assistant_id
+ """,
+ (assistant_ids, site_id, start_date, end_date),
+ )
+ for row in cur.fetchall():
+ result.setdefault(row[0], {"recall": 0, "callback": 0})
+ result[row[0]]["callback"] = row[1] or 0
+
conn.commit()
except Exception:
logger.warning("BOARD-1 任务查询失败，降级为空", exc_info=True)
@@ -762,11 +780,16 @@ def _build_overview(
) -> dict:
"""经营一览板块。
- CHANGE 2026-04-01 | board-finance-dws-area-refactor 9.1 |
- 改为从 dws_finance_area_daily 按 area_code 查询（通过 get_finance_overview_area）。
+ CHANGE 2026-04-08 | P0 修复发生额失真 |
+ area=all 时回退到 dws_finance_daily_summary（get_finance_overview），
+ 仅 area≠all 时走 dws_finance_area_daily（get_finance_overview_area）。
+ 原因：area_daily 的 all 行只聚合有桌台映射的结算单，漏算无桌台单据约 12%。
"""
try:
- data = fdw_queries.get_finance_overview_area(conn, site_id, start, end, area)
+ if area == "all":
+ data = fdw_queries.get_finance_overview(conn, site_id, start, end)
+ else:
+ data = fdw_queries.get_finance_overview_area(conn, site_id, start, end, area)
except Exception:
logger.warning("overview 查询失败，降级为空", exc_info=True)
return _empty_overview()
@@ -775,7 +798,10 @@ def _build_overview(
if compare == 1 and prev_start and prev_end:
try:
- prev = fdw_queries.get_finance_overview_area(conn, site_id, prev_start, prev_end, area)
+ if area == "all":
+ prev = fdw_queries.get_finance_overview(conn, site_id, prev_start, prev_end)
+ else:
+ prev = fdw_queries.get_finance_overview_area(conn, site_id, prev_start, prev_end, area)
_attach_compare(result, data, prev, [
"occurrence", "discount", "discount_rate", "confirmed_revenue",
"cash_in", "cash_out", "cash_balance", "balance_rate",
diff --git a/apps/backend/app/services/fdw_queries.py b/apps/backend/app/services/fdw_queries.py
index dc69871..2e8fe1d 100644
--- a/apps/backend/app/services/fdw_queries.py
+++ b/apps/backend/app/services/fdw_queries.py
@@ -937,18 +937,18 @@ def get_consumption_60d(
"""
查询客户近 60 天消费金额。
- 来源: app.v_dwd_assistant_service_log。
- ⚠️ DWD-DOC 规则 1: 使用 ledger_amount（items_sum 口径）。
- ⚠️ 废单排除: is_delete = 0。
+ 来源: app.v_dws_member_consumption_summary（DWS 预聚合表）。
+ 与 board-customer spend60 维度统一口径：items_sum，60天窗口，日粒度。
+ 取最新 stat_date 的快照行。
"""
with _fdw_context(conn, site_id, etl_conn=etl_conn) as cur:
cur.execute(
"""
- SELECT COALESCE(SUM(ledger_amount), 0)
- FROM app.v_dwd_assistant_service_log
- WHERE tenant_member_id = %s
- AND is_delete = 0
- AND create_time >= (CURRENT_DATE - INTERVAL '60 days')::timestamptz
+ SELECT consume_amount_60d
+ FROM app.v_dws_member_consumption_summary
+ WHERE member_id = %s
+ ORDER BY stat_date DESC
+ LIMIT 1
""",
(member_id,),
)
@@ -1729,6 +1729,8 @@ def get_coach_sv_data(
result: dict[int, dict] = {}
with _fdw_context(conn, site_id) as cur:
+ # CHANGE 2026-04-07 | Fix-6：sv_consume 改为从结算表按 start_date/end_date 过滤，
+ # 使其随时间筛选联动，而非固定 60 天窗口。
cur.execute(
"""
WITH coach_members AS (
@@ -1737,11 +1739,21 @@ def get_coach_sv_data(
FROM app.v_dws_member_assistant_relation_index ri
WHERE ri.assistant_id = ANY(%s)
AND ri.session_count > 0
+ ),
+ period_consume AS (
+ SELECT sh.member_id,
+ COALESCE(SUM(sh.items_sum), 0) AS consume_amount
+ FROM app.v_dwd_settlement_head sh
+ WHERE sh.member_id = ANY(SELECT member_id FROM coach_members)
+ AND sh.settle_type IN (1, 3)
+ AND sh.pay_time::date >= %s::date
+ AND sh.pay_time::date <= %s::date
+ GROUP BY sh.member_id
)
SELECT cm.assistant_id,
COALESCE(SUM(ca_agg.balance), 0) AS sv_amount,
COUNT(DISTINCT CASE WHEN ca_agg.balance > 0 THEN cm.member_id END) AS sv_customer_count,
- COALESCE(SUM(cs.consume_amount_60d), 0) AS sv_consume
+ COALESCE(SUM(pc.consume_amount), 0) AS sv_consume
FROM coach_members cm
LEFT JOIN (
SELECT tenant_member_id, SUM(balance) AS balance
@@ -1749,11 +1761,11 @@ def get_coach_sv_data(
WHERE scd2_is_current = 1
GROUP BY tenant_member_id
) ca_agg ON cm.member_id = ca_agg.tenant_member_id
- LEFT JOIN app.v_dws_member_consumption_summary cs
- ON cm.member_id = cs.member_id
+ LEFT JOIN period_consume pc
+ ON cm.member_id = pc.member_id
GROUP BY cm.assistant_id
""",
- (assistant_ids,),
+ (assistant_ids, start_date, end_date),
)
for row in cur.fetchall():
result[row[0]] = {
@@ -1769,19 +1781,20 @@ def get_coach_sv_data(
# ---------------------------------------------------------------------------
-def _project_filter_clause(project: str) -> tuple[str, tuple]:
+def _project_filter_clause(project: str, member_col: str = "member_id") -> tuple[str, tuple]:
"""
生成项目筛选 SQL 片段（用于 BOARD-2 会员维度查询）。
CHANGE 2026-03-20 | R3 修复：project 参数直接接收 category_code
（BILLIARD/SNOOKER/MAHJONG/KTV/ALL），去掉 chinese→BILLIARD 映射层。
+ CHANGE 2026-04-07 | Fix-1：member_col 参数化，修复 6 个维度别名不匹配导致 SQL 500。
返回 (sql_fragment, params)，sql_fragment 以 AND 开头，可直接拼入 WHERE 子句。
"""
_valid_categories = {"BILLIARD", "SNOOKER", "MAHJONG", "KTV"}
if project == "ALL" or project not in _valid_categories:
return "", ()
- clause = """
- AND vd.member_id IN (
+ clause = f"""
+ AND {member_col} IN (
SELECT mpt.member_id
FROM app.v_dws_member_project_tag mpt
WHERE mpt.category_code = %s AND mpt.is_tagged = true
@@ -1802,13 +1815,13 @@ def get_customer_board_recall(
ideal_days → ideal_interval_days, wbi_score → display_score,
elapsed_days → CURRENT_DATE - last_visit_time::date (计算列),
overdue_days → elapsed_days - ideal_interval_days (计算列),
- visits_30d 不存在（有 visits_14d/visits_60d），用 visits_14d 近似,
+ CHANGE 2026-04-07 | Fix-3：visits_30d 新增字段，替代 visits_14d 近似,
balance_amount → balance (v_dim_member_card_account)
⚠️ DQ-6: 客户姓名通过 member_id JOIN v_dim_member。
⚠️ DQ-7: 余额通过 JOIN v_dim_member_card_account。
按 display_score 降序，LIMIT/OFFSET 分页。
"""
- proj_clause, proj_params = _project_filter_clause(project)
+ proj_clause, proj_params = _project_filter_clause(project, "wi.member_id")
with _fdw_context(conn, site_id) as cur:
# 总数
@@ -1817,6 +1830,7 @@ def get_customer_board_recall(
SELECT COUNT(*)
FROM app.v_dws_member_winback_index wi
WHERE 1=1 {proj_clause}
+
""",
proj_params,
)
@@ -1831,7 +1845,7 @@ def get_customer_board_recall(
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,
- wi.visits_14d,
+ wi.visits_30d,
wi.display_score,
COALESCE(ca.balance, 0) AS balance
FROM app.v_dws_member_winback_index wi
@@ -1844,7 +1858,7 @@ def get_customer_board_recall(
GROUP BY tenant_member_id
) ca ON wi.member_id = ca.tenant_member_id
WHERE 1=1 {proj_clause}
- ORDER BY wi.display_score DESC
+ ORDER BY wi.display_score DESC, wi.member_id
LIMIT %s OFFSET %s
""",
(*proj_params, page_size, offset),
@@ -1870,16 +1884,18 @@ def _derive_potential_tags(
level_score: float | None,
speed_score: float | None,
stability_score: float | None,
-) -> list[str]:
- """从三维分数派生潜力标签（display_score 均为 0-100 区间）。"""
- tags = []
- threshold = 60.0
+) -> list[dict]:
+ """从三维分数派生潜力标签（display_score 为 0-10 区间）。
+ 返回 [{text, theme}] 格式，与前端 potentialTags 类型一致。
+ """
+ tags: list[dict] = []
+ threshold = 6.0
if level_score is not None and float(level_score) >= threshold:
- tags.append("high_level")
+ tags.append({"text": "高消费力", "theme": "success"})
if speed_score is not None and float(speed_score) >= threshold:
- tags.append("fast_growth")
+ tags.append({"text": "快增长", "theme": "warning"})
if stability_score is not None and float(stability_score) >= threshold:
- tags.append("stable")
+ tags.append({"text": "稳定", "theme": "primary"})
return tags
@@ -1934,7 +1950,7 @@ def get_customer_board_potential(
) ca_agg ON spi.member_id = ca_agg.tenant_member_id
WHERE 1=1
{f"AND spi.member_id IN (SELECT member_id FROM app.v_dws_member_project_tag WHERE category_code = %s AND is_tagged = true)" if proj_params else ""}
- ORDER BY spi.display_score DESC NULLS LAST, COALESCE(ca_agg.balance, 0) DESC
+ ORDER BY spi.display_score DESC NULLS LAST, COALESCE(ca_agg.balance, 0) DESC, spi.member_id
LIMIT %s OFFSET %s
""",
(*proj_params, page_size, offset),
@@ -1969,7 +1985,7 @@ def get_customer_board_balance(
⚠️ DQ-7: 余额通过 tenant_member_id JOIN，取 scd2_is_current=1。
按 balance 降序。
"""
- proj_clause, proj_params = _project_filter_clause(project)
+ proj_clause, proj_params = _project_filter_clause(project, "ca.tenant_member_id")
with _fdw_context(conn, site_id) as cur:
# CHANGE 2026-03-28 | 修复客户重复：dim_member_card_account 同一 member 有多条记录，
@@ -2009,9 +2025,14 @@ def get_customer_board_balance(
) ca_agg
LEFT JOIN app.v_dim_member dm
ON ca_agg.member_id = dm.member_id AND dm.scd2_is_current = 1
- LEFT JOIN app.v_dws_member_consumption_summary vd
- ON ca_agg.member_id = vd.member_id
- ORDER BY ca_agg.balance DESC
+ LEFT JOIN LATERAL (
+ SELECT cs.days_since_last, cs.consume_amount_60d
+ FROM app.v_dws_member_consumption_summary cs
+ WHERE cs.member_id = ca_agg.member_id
+ ORDER BY cs.stat_date DESC
+ LIMIT 1
+ ) vd ON true
+ ORDER BY ca_agg.balance DESC, ca_agg.member_id
LIMIT %s OFFSET %s
""",
(*proj_params, page_size, offset),
@@ -2026,9 +2047,10 @@ def get_customer_board_balance(
"last_visit": f"{row[3]}天前" if row[3] is not None else "--",
"last_visit_date": row[3],
"ideal_days": None, # balance 维度无 ideal_days，由 board_service 补充
- "monthly_consume": float(row[4]) if row[4] is not None else 0.0,
+ # CHANGE 2026-04-07 | Fix-4：consume_amount_60d 是 60 天总额，月均 = /2
+ "monthly_consume": float(row[4]) / 2 if row[4] is not None else 0.0,
"available_months": (
- f"{float(row[2]) / float(row[4]):.1f}个月"
+ f"{2 * float(row[2]) / float(row[4]):.1f}个月"
if row[2] and row[4] and float(row[4]) > 0
else "--"
),
@@ -2050,7 +2072,7 @@ def get_customer_board_recharge(
balance_amount → balance (v_dim_member_card_account)
按 last_recharge_date (MAX(pay_time::date)) 降序。
"""
- proj_clause, proj_params = _project_filter_clause(project)
+ proj_clause, proj_params = _project_filter_clause(project, "ro.member_id")
with _fdw_context(conn, site_id) as cur:
cur.execute(
@@ -2084,11 +2106,16 @@ def get_customer_board_recharge(
WHERE scd2_is_current = 1
GROUP BY tenant_member_id
) ca_agg ON ro.member_id = ca_agg.tenant_member_id
- LEFT JOIN app.v_dws_member_consumption_summary cs
- ON ro.member_id = cs.member_id
+ LEFT JOIN LATERAL (
+ SELECT cs2.days_since_last
+ FROM app.v_dws_member_consumption_summary cs2
+ WHERE cs2.member_id = ro.member_id
+ ORDER BY cs2.stat_date DESC
+ LIMIT 1
+ ) cs ON true
WHERE 1=1 {proj_clause}
GROUP BY ro.member_id, dm.nickname, ca_agg.balance, cs.days_since_last
- ORDER BY MAX(ro.pay_time::date) DESC
+ ORDER BY MAX(ro.pay_time::date) DESC, ro.member_id
LIMIT %s OFFSET %s
""",
(*proj_params, page_size, offset),
@@ -2121,7 +2148,7 @@ def get_customer_board_recent(
不再硬编码为 0。来源: v_dws_member_visit_detail + v_dim_member + v_dws_member_winback_index。
按 last_visit_date 降序。
"""
- proj_clause, proj_params = _project_filter_clause(project)
+ proj_clause, proj_params = _project_filter_clause(project, "vd.member_id")
with _fdw_context(conn, site_id) as cur:
cur.execute(
@@ -2161,7 +2188,7 @@ def get_customer_board_recent(
ON ma.member_id = dm.member_id AND dm.scd2_is_current = 1
LEFT JOIN app.v_dws_member_winback_index wi
ON ma.member_id = wi.member_id
- ORDER BY ma.last_visit_date DESC
+ ORDER BY ma.last_visit_date DESC, ma.member_id
LIMIT %s OFFSET %s
""",
(*proj_params, page_size, offset),
@@ -2199,15 +2226,21 @@ def get_customer_board_spend60(
high_spend_tag/avg_spend 不存在，用 avg_ticket_amount 替代 avg_spend，
high_spend_tag 通过阈值计算。
按 consume_amount_60d 降序。
+ CHANGE 2026-04-08 | Fix：consumption_summary 按 stat_date 有多行快照，
+ 用 DISTINCT ON 取最新快照避免同一客户出现多次。
"""
- proj_clause, proj_params = _project_filter_clause(project)
+ proj_clause, proj_params = _project_filter_clause(project, "cs.member_id")
with _fdw_context(conn, site_id) as cur:
cur.execute(
f"""
SELECT COUNT(*)
- FROM app.v_dws_member_consumption_summary cs
- WHERE 1=1 {proj_clause}
+ FROM (
+ SELECT DISTINCT ON (cs.member_id) cs.member_id
+ FROM app.v_dws_member_consumption_summary cs
+ WHERE 1=1 {proj_clause}
+ ORDER BY cs.member_id, cs.stat_date DESC
+ ) sub
""",
proj_params,
)
@@ -2216,16 +2249,23 @@ def get_customer_board_spend60(
offset = (page - 1) * page_size
cur.execute(
f"""
+ WITH latest_cs AS (
+ SELECT DISTINCT ON (cs.member_id)
+ cs.member_id, cs.consume_amount_60d,
+ cs.visit_count_60d, cs.avg_ticket_amount
+ FROM app.v_dws_member_consumption_summary cs
+ WHERE 1=1 {proj_clause}
+ ORDER BY cs.member_id, cs.stat_date DESC
+ )
SELECT cs.member_id,
dm.nickname,
cs.consume_amount_60d,
cs.visit_count_60d,
cs.avg_ticket_amount
- FROM app.v_dws_member_consumption_summary cs
+ FROM latest_cs cs
LEFT JOIN app.v_dim_member dm
ON cs.member_id = dm.member_id AND dm.scd2_is_current = 1
- WHERE 1=1 {proj_clause}
- ORDER BY cs.consume_amount_60d DESC
+ ORDER BY cs.consume_amount_60d DESC, cs.member_id
LIMIT %s OFFSET %s
""",
(*proj_params, page_size, offset),
@@ -2256,15 +2296,20 @@ def get_customer_board_freq60(
CHANGE 2026-03-20 | 修正列名：items_sum_60d → consume_amount_60d,
avg_interval_days 不存在，用 60/visit_count_60d 近似计算。
按 visit_count_60d 降序。
+ CHANGE 2026-04-08 | Fix：同 spend60，DISTINCT ON 取最新快照。
"""
- proj_clause, proj_params = _project_filter_clause(project)
+ proj_clause, proj_params = _project_filter_clause(project, "cs.member_id")
with _fdw_context(conn, site_id) as cur:
cur.execute(
f"""
SELECT COUNT(*)
- FROM app.v_dws_member_consumption_summary cs
- WHERE 1=1 {proj_clause}
+ FROM (
+ SELECT DISTINCT ON (cs.member_id) cs.member_id
+ FROM app.v_dws_member_consumption_summary cs
+ WHERE 1=1 {proj_clause}
+ ORDER BY cs.member_id, cs.stat_date DESC
+ ) sub
""",
proj_params,
)
@@ -2273,15 +2318,21 @@ def get_customer_board_freq60(
offset = (page - 1) * page_size
cur.execute(
f"""
+ WITH latest_cs AS (
+ 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}
+ ORDER BY cs.member_id, cs.stat_date DESC
+ )
SELECT cs.member_id,
dm.nickname,
cs.visit_count_60d,
cs.consume_amount_60d
- FROM app.v_dws_member_consumption_summary cs
+ FROM latest_cs cs
LEFT JOIN app.v_dim_member dm
ON cs.member_id = dm.member_id AND dm.scd2_is_current = 1
- WHERE 1=1 {proj_clause}
- ORDER BY cs.visit_count_60d DESC
+ ORDER BY cs.visit_count_60d DESC, cs.member_id
LIMIT %s OFFSET %s
""",
(*proj_params, page_size, offset),
@@ -2316,20 +2367,21 @@ def _get_weekly_visits_batch(cur: Any, member_ids: list[int]) -> dict[int, list[
"""
批量查询客户最近 8 周的到店次数（用于 freq60 维度柱状图）。
- 来源: app.v_dwd_assistant_service_log，按 ISO 周分组。
+ CHANGE 2026-04-07 | Fix-5：数据源从 v_dwd_assistant_service_log 改为
+ v_dwd_settlement_head（settle_type IN (1,3)），与汇总维度口径一致。
返回 {member_id: [{val: int, pct: int}, ...]}，固定 8 个元素。
"""
cur.execute(
"""
WITH weekly AS (
- SELECT tenant_member_id AS member_id,
- DATE_TRUNC('week', create_time::date) AS week_start,
- COUNT(*) AS cnt
- FROM app.v_dwd_assistant_service_log
- WHERE tenant_member_id = ANY(%s)
- AND is_delete = 0
- AND create_time >= CURRENT_DATE - INTERVAL '56 days'
- GROUP BY tenant_member_id, DATE_TRUNC('week', create_time::date)
+ SELECT member_id,
+ DATE_TRUNC('week', pay_time::date) AS week_start,
+ COUNT(DISTINCT pay_time::date) AS cnt
+ 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'
+ GROUP BY member_id, DATE_TRUNC('week', pay_time::date)
)
SELECT member_id, week_start, cnt
FROM weekly
@@ -2379,7 +2431,7 @@ def get_customer_board_loyal(
来源: app.v_dws_member_assistant_relation_index。
按 max_rs（最高亲密度）降序。
"""
- proj_clause, proj_params = _project_filter_clause(project)
+ proj_clause, proj_params = _project_filter_clause(project, "ri.member_id")
with _fdw_context(conn, site_id) as cur:
cur.execute(
@@ -2403,7 +2455,7 @@ def get_customer_board_loyal(
FROM app.v_dws_member_assistant_relation_index ri
WHERE 1=1 {proj_clause}
GROUP BY ri.member_id
- ORDER BY MAX(ri.rs_display) DESC
+ ORDER BY MAX(ri.rs_display) DESC, ri.member_id
LIMIT %s OFFSET %s
)
SELECT mt.member_id,
@@ -2417,7 +2469,7 @@ def get_customer_board_loyal(
ON mt.member_id = dm.member_id AND dm.scd2_is_current = 1
LEFT JOIN app.v_dim_assistant da
ON mt.top_assistant_id = da.assistant_id AND da.scd2_is_current = 1
- ORDER BY mt.max_rs DESC
+ ORDER BY mt.max_rs DESC, mt.member_id
""",
(*proj_params, page_size, offset),
)
diff --git a/apps/backend/app/services/recall_detector.py b/apps/backend/app/services/recall_detector.py
index 6eae069..7141def 100644
--- a/apps/backend/app/services/recall_detector.py
+++ b/apps/backend/app/services/recall_detector.py
@@ -1,20 +1,22 @@
-# AI_CHANGELOG
-# - 2026-03-20 | Prompt: H2 FDW→直连ETL统一改造 | _process_site() 中 fdw_etl.v_dwd_assistant_service_log
-# 改为直连 ETL 库查询 app.v_dwd_assistant_service_log。使用 fdw_queries._fdw_context()。
-
# -*- coding: utf-8 -*-
"""
召回完成检测器（Recall Completion Detector）
-ETL 数据更新后，直连 ETL 库读取助教服务记录，
-匹配活跃任务标记为 completed，记录 completed_at 和 completed_task_type 快照，
-触发 recall_completed 事件通知备注回溯重分类器。
+ETL 数据更新后，扫描所有 MAIN 关系对的结算记录，
+记录广义召回事件（recall_events），匹配活跃任务标记 completed，
+对所有到店的 MAIN 关联客户生成回访任务（follow_up_visit）。
由 trigger_jobs 中的 recall_completion_check 配置驱动（event: etl_data_updated）。
+
+CHANGE 2026-04-08 | Fix-13 改造：
+- 扫描范围从"有 active 任务的客户"扩大为"所有 os_label='MAIN' 的关联客户"
+- 新增 recall_events 事件表记录广义召回（按天去重）
+- 无 active 任务的客户到店也生成 follow_up_visit
"""
import json
import logging
+from datetime import timedelta
from app.trace.decorators import trace_service
@@ -63,69 +65,37 @@ def run(payload: dict | None = None, job_id: int | None = None) -> dict:
"""
召回完成检测主流程。
- 1. 从 trigger_jobs 读取 last_run_at 作为增量过滤基准
- 2. 获取所有 distinct site_id（从 active 任务中）
- 3. 对每个 site_id，SET LOCAL app.current_site_id 后
- 通过 FDW 读取 v_dwd_assistant_service_log 中 service_time > last_run_at 的新增服务记录
- 4. 对每条服务记录，查找 biz.coach_tasks 中匹配的
- (site_id, assistant_id, member_id) 且 status='active' 的任务
- 5. 将匹配任务标记为 completed：
- - status = 'completed'
- - completed_at = 服务时间
- - completed_task_type = 当前 task_type（快照）
- 6. 记录 coach_task_history
- 7. 触发 fire_event('recall_completed', {site_id, assistant_id, member_id, service_time})
-
- 参数:
- payload: 事件载荷（event 触发时由 trigger_scheduler 传入）
- job_id: 触发器 job ID（由 trigger_scheduler 传入），用于在最终事务中
- 更新 last_run_at，保证 handler 数据变更与 last_run_at 原子提交
-
- 返回: {"completed_count": int}
+ CHANGE 2026-04-08 | Fix-13 改造：扫描所有 MAIN 关系对。
+ 1. 从 biz.sites 获取所有活跃门店
+ 2. 对每个 site_id，通过 _fdw_context 扫描 MAIN 关系对的结算记录
+ 3. 有结算 → 写 recall_events + 完成任务（如有）+ 生成回访
"""
completed_count = 0
+ event_count = 0
conn = _get_connection()
try:
- # ── 1. 读取 last_run_at ──
+ # ── 1. 从业务库获取所有活跃门店 ──
with conn.cursor() as cur:
cur.execute(
- """
- SELECT last_run_at
- FROM biz.trigger_jobs
- WHERE job_name = 'recall_completion_check'
- """
- )
- row = cur.fetchone()
- last_run_at = row[0] if row else None
- conn.commit()
-
- # ── 2. 获取所有有 active 任务的 distinct site_id ──
- with conn.cursor() as cur:
- cur.execute(
- """
- SELECT DISTINCT site_id
- FROM biz.coach_tasks
- WHERE status = 'active'
- """
+ "SELECT site_id FROM biz.sites WHERE is_active = true"
)
site_ids = [r[0] for r in cur.fetchall()]
conn.commit()
- # ── 3. 逐 site_id 读取新增服务记录 ──
+ # ── 2. 逐 site_id 处理 ──
for site_id in site_ids:
try:
- count = _process_site(conn, site_id, last_run_at)
- completed_count += count
+ result = _process_site(conn, site_id)
+ completed_count += result["completed"]
+ event_count += result["events"]
except Exception:
logger.exception(
"处理门店召回检测失败: site_id=%s", site_id
)
conn.rollback()
- # ── 事务安全（T5）：handler 成功后更新 last_run_at ──
- # job_id 由 trigger_scheduler 传入，在 handler 最终事务中更新
- # handler 异常时此处不会执行（异常向上传播），last_run_at 不变
+ # ── 更新 last_run_at（兼容 trigger_scheduler 调度记录） ──
if job_id is not None:
from app.services.trigger_scheduler import update_job_last_run_at
@@ -137,145 +107,196 @@ def run(payload: dict | None = None, job_id: int | None = None) -> dict:
finally:
conn.close()
- logger.info("召回完成检测完成: completed_count=%d", completed_count)
- return {"completed_count": completed_count}
+ logger.info(
+ "召回完成检测完成: completed_count=%d, event_count=%d",
+ completed_count, event_count,
+ )
+ return {"completed_count": completed_count, "event_count": event_count}
-def _process_site(conn, site_id: int, last_run_at) -> int:
+def _process_site(conn, site_id: int) -> dict:
"""
- 处理单个门店的召回完成检测。
+ 处理单个门店的广义召回检测。
- 直连 ETL 库读取新增服务记录，匹配 active 任务并标记 completed。
- 返回本门店完成的任务数。
+ CHANGE 2026-04-08 | Fix-13 改造：
+ 1. 从 ETL 查询所有 os_label='MAIN' 的 (assistant_id, member_id) 对
+ 2. 批量查询这些客户的最新结算记录
+ 3. 对每个有新结算的关系对：写 recall_events + 完成任务 + 生成回访
"""
completed = 0
+ events = 0
- # CHANGE 2026-03-20 | H2 FDW→直连ETL | fdw_etl.v_dwd_assistant_service_log → app.v_dwd_assistant_service_log
- # intent: 修复 RLS 门店隔离失效（postgres_fdw 不传递 GUC 参数）
- # assumptions: _fdw_context 内部管理 ETL 连接，conn 仅用于后续业务库操作
from app.services.fdw_queries import _fdw_context
+ # ── 1. 获取本门店所有 MAIN 关系对 ──
with _fdw_context(conn, site_id) as cur:
- if last_run_at is not None:
- # 列名映射: FDW 外部表 assistant_id/member_id/service_time
- # → RLS 视图 site_assistant_id/tenant_member_id/create_time
- cur.execute(
- """
- SELECT DISTINCT site_assistant_id, tenant_member_id, create_time
- FROM app.v_dwd_assistant_service_log
- WHERE create_time > %s
- ORDER BY create_time ASC
- """,
- (last_run_at,),
- )
- else:
- # 首次运行，读取所有服务记录
- cur.execute(
- """
- SELECT DISTINCT site_assistant_id, tenant_member_id, create_time
- FROM app.v_dwd_assistant_service_log
- ORDER BY create_time ASC
- """
- )
- service_records = cur.fetchall()
+ cur.execute(
+ """
+ SELECT assistant_id, member_id
+ FROM app.v_dws_member_assistant_relation_index
+ WHERE os_label = 'MAIN'
+ """
+ )
+ main_pairs = [(r[0], r[1]) for r in cur.fetchall()]
- # ── 4-7. 逐条服务记录匹配并处理 ──
- for assistant_id, member_id, service_time in service_records:
- # 散客过滤（member_id ≤ 0 不参与任务系统）
- if member_id is None or member_id <= 0:
- continue
- try:
- count = _process_service_record(
- conn, site_id, assistant_id, member_id, service_time
+ if not main_pairs:
+ return {"completed": 0, "events": 0}
+
+ # ── 2. 批量查询这些客户的最新结算时间 ──
+ member_ids = list({mid for _, mid in main_pairs})
+ settlement_map: dict[tuple[int, int], object] = {} # (assistant_id, member_id) → latest_pay_time
+
+ with _fdw_context(conn, site_id) as cur:
+ cur.execute(
+ """
+ SELECT sl.site_assistant_id AS assistant_id,
+ sh.member_id,
+ MAX(sh.pay_time) AS latest_pay_time
+ FROM app.v_dwd_settlement_head sh
+ JOIN app.v_dwd_assistant_service_log sl
+ ON sl.order_settle_id = sh.order_settle_id
+ AND sl.is_delete = 0
+ WHERE sh.member_id = ANY(%s)
+ AND sh.settle_type IN (1, 3)
+ GROUP BY sl.site_assistant_id, sh.member_id
+ """,
+ (member_ids,),
+ )
+ for row in cur.fetchall():
+ settlement_map[(row[0], row[1])] = row[2]
+
+ # ── 3. 获取本门店所有 active 的召回/回访任务（用于匹配） ──
+ active_tasks_map: dict[tuple[int, int], list] = {} # (assistant_id, member_id) → [(id, task_type, created_at)]
+ with conn.cursor() as cur:
+ cur.execute(
+ """
+ SELECT id, assistant_id, member_id, task_type, created_at
+ FROM biz.coach_tasks
+ WHERE site_id = %s
+ AND status = 'active'
+ AND task_type IN ('high_priority_recall', 'priority_recall', 'follow_up_visit')
+ """,
+ (site_id,),
+ )
+ for row in cur.fetchall():
+ key = (row[1], row[2])
+ active_tasks_map.setdefault(key, []).append(
+ {"id": row[0], "task_type": row[3], "created_at": row[4]}
)
- completed += count
+ conn.commit()
+
+ # ── 4. 逐关系对处理 ──
+ for assistant_id, member_id in main_pairs:
+ latest_pay = settlement_map.get((assistant_id, member_id))
+ if latest_pay is None:
+ continue
+
+ active_tasks = active_tasks_map.get((assistant_id, member_id), [])
+
+ try:
+ result = _process_pair(
+ conn, site_id, assistant_id, member_id,
+ latest_pay, active_tasks,
+ )
+ completed += result["completed"]
+ events += result["events"]
except Exception:
logger.exception(
- "处理服务记录失败: site_id=%s, assistant_id=%s, member_id=%s",
- site_id,
- assistant_id,
- member_id,
+ "处理关系对失败: site_id=%s, assistant_id=%s, member_id=%s",
+ site_id, assistant_id, member_id,
)
conn.rollback()
- return completed
+ return {"completed": completed, "events": events}
-def _process_service_record(
+def _process_pair(
conn,
site_id: int,
assistant_id: int,
member_id: int,
- service_time,
-) -> int:
+ latest_pay_time,
+ active_tasks: list[dict],
+) -> dict:
"""
- 处理单条服务记录：匹配 active 任务并标记 completed + 生成回访任务。
+ 处理单个 MAIN 关系对的召回检测。
- CHANGE 2026-03-30 | 回访任务直接在此生成（不再依赖 note_reclassifier 事件链）。
- 规则：
- - 有 active 召回任务 → 标记 completed，然后生成回访任务
- - 有 active 回访任务 → 关闭旧回访，生成新回访（重置 48h 倒计时）
- - 无任何 active 召回/回访 → 直接生成回访任务
+ CHANGE 2026-04-08 | Fix-13 改造：
+ - 写 recall_events（ON CONFLICT DO NOTHING 按天去重）
+ - 有 active 召回任务且 pay_time > created_at → 完成任务
+ - 关闭旧回访 → 新建回访（48h）
+ - 无 active 任务也生成回访
- 每条服务记录独立事务，失败不影响其他。
- 返回本次完成的任务数。
+ 返回: {"completed": int, "events": int}
"""
completed = 0
+ events = 0
with conn.cursor() as cur:
cur.execute("BEGIN")
- # ── 1. 查找匹配的 active 召回类任务 ──
+ # ── 1. 写 recall_events（按天去重） ──
+ # 先查是否有匹配的召回任务（用于填充 task_id/task_type）
+ recall_tasks = [
+ t for t in active_tasks
+ if t["task_type"] in ("high_priority_recall", "priority_recall")
+ and latest_pay_time > t["created_at"]
+ ]
+ event_task_id = recall_tasks[0]["id"] if recall_tasks else None
+ event_task_type = recall_tasks[0]["task_type"] if recall_tasks else None
+
cur.execute(
"""
- SELECT id, task_type
- FROM biz.coach_tasks
- WHERE site_id = %s
- AND assistant_id = %s
- AND member_id = %s
- AND status = 'active'
- AND task_type IN ('high_priority_recall', 'priority_recall')
+ 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')))
+ DO NOTHING
+ RETURNING id
""",
- (site_id, assistant_id, member_id),
+ (site_id, assistant_id, member_id, latest_pay_time,
+ event_task_id, event_task_type),
)
- active_recall_tasks = cur.fetchall()
+ inserted = cur.fetchone()
+ if inserted is None:
+ # 今天已记录过，跳过后续处理（避免重复生成回访）
+ conn.commit()
+ return {"completed": 0, "events": 0}
- has_active_recall = len(active_recall_tasks) > 0
+ events = 1
- # 将所有匹配的 active 召回任务标记为 completed
- for task_id, task_type in active_recall_tasks:
+ # ── 2. 完成匹配的召回任务 ──
+ has_active_recall = len(recall_tasks) > 0
+
+ for task in recall_tasks:
cur.execute(
"""
UPDATE biz.coach_tasks
SET status = 'completed',
completed_at = %s,
completed_task_type = %s,
+ completion_type = 'auto',
updated_at = NOW()
WHERE id = %s AND status = 'active'
""",
- (service_time, task_type, task_id),
+ (latest_pay_time, task["task_type"], task["id"]),
)
_insert_history(
cur,
- task_id,
+ task["id"],
action="completed",
old_status="active",
new_status="completed",
- old_task_type=task_type,
- new_task_type=task_type,
+ old_task_type=task["task_type"],
+ new_task_type=task["task_type"],
detail={
- "service_time": str(service_time),
- "completed_task_type": task_type,
+ "service_time": str(latest_pay_time),
+ "completed_task_type": task["task_type"],
},
)
completed += 1
- # ── 2. 生成回访任务（CHANGE 2026-03-30） ──
- # 如果还有 active 召回任务（其他助教的），不生成回访
- # 注意：上面已经把当前助教的召回任务标记为 completed 了
- # 这里检查的是当前助教-客户对是否还有未完成的召回任务（不应该有了）
-
- # 关闭已有的 active 回访任务
+ # ── 3. 关闭已有的 active 回访任务 ──
cur.execute(
"""
SELECT id FROM biz.coach_tasks
@@ -299,16 +320,19 @@ def _process_service_record(
action="superseded_by_new_visit",
old_status="active", new_status="inactive",
old_task_type="follow_up_visit", new_task_type="follow_up_visit",
- detail={"reason": "new_service_record", "service_time": str(service_time)},
+ detail={"reason": "new_service_record", "service_time": str(latest_pay_time)},
)
- # 创建新的回访任务（48h 过期）
- from datetime import timedelta
- expires_at = service_time + timedelta(hours=48) if hasattr(service_time, '__add__') else None
+ # ── 4. 创建新的回访任务（48h 过期） ──
+ expires_at = (
+ latest_pay_time + timedelta(hours=48)
+ if hasattr(latest_pay_time, '__add__') else None
+ )
cur.execute(
"""
INSERT INTO biz.coach_tasks
- (site_id, assistant_id, member_id, task_type, status, expires_at, created_at, updated_at)
+ (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())
RETURNING id
""",
@@ -322,14 +346,14 @@ def _process_service_record(
new_task_type="follow_up_visit",
detail={
"reason": "service_record_detected",
- "service_time": str(service_time),
+ "service_time": str(latest_pay_time),
"had_recall": has_active_recall,
},
)
conn.commit()
- # ── 3. 触发 recall_completed 事件（仅当有召回任务被完成时） ──
+ # ── 5. 触发 recall_completed 事件（仅当有召回任务被完成时） ──
if has_active_recall:
try:
from app.services.trigger_scheduler import fire_event
@@ -339,7 +363,7 @@ def _process_service_record(
"site_id": site_id,
"assistant_id": assistant_id,
"member_id": member_id,
- "service_time": str(service_time),
+ "service_time": str(latest_pay_time),
},
)
except Exception:
@@ -348,4 +372,4 @@ def _process_service_record(
site_id, assistant_id, member_id,
)
- return completed
+ return {"completed": completed, "events": events}
diff --git a/apps/backend/app/services/task_generator.py b/apps/backend/app/services/task_generator.py
index a843b97..e6479e4 100644
--- a/apps/backend/app/services/task_generator.py
+++ b/apps/backend/app/services/task_generator.py
@@ -998,8 +998,8 @@ def _update_task_stats(conn, site_id: int) -> None:
# ── C: 历史总计（写入 ETL 关系指数表） ──
try:
- from app.database import get_etl_readonly_connection
- etl_conn = get_etl_readonly_connection(site_id)
+ from app.database import get_etl_write_connection
+ etl_conn = get_etl_write_connection()
try:
# 先从业务库聚合历史总计
with conn.cursor() as cur:
diff --git a/apps/backend/app/services/task_registry.py b/apps/backend/app/services/task_registry.py
index c1f5212..9cdd650 100644
--- a/apps/backend/app/services/task_registry.py
+++ b/apps/backend/app/services/task_registry.py
@@ -95,6 +95,7 @@ DWS_TASKS: list[TaskDefinition] = [
TaskDefinition("DWS_FINANCE_RECHARGE", "充值汇总", "汇总充值数据", "财务", "DWS"),
TaskDefinition("DWS_FINANCE_INCOME_STRUCTURE", "收入结构", "分析收入结构", "财务", "DWS"),
TaskDefinition("DWS_FINANCE_DISCOUNT_DETAIL", "折扣明细", "汇总折扣明细", "财务", "DWS"),
+ TaskDefinition("DWS_FINANCE_AREA_DAILY", "区域财务日报", "按区域汇总每日财务数据", "财务", "DWS"),
# CHANGE [2026-02-19] intent: 同步 ETL 侧合并——原 DWS_RETENTION_CLEANUP / DWS_MV_REFRESH_* 已合并为 DWS_MAINTENANCE
TaskDefinition("DWS_MAINTENANCE", "DWS 维护", "刷新物化视图 + 清理过期留存数据", "通用", "DWS", requires_window=False, is_common=False),
# CHANGE [2026-03-27] intent: 注册 DWS 库存汇总任务（日/周/月）（需求 12.9）
diff --git a/apps/etl/connectors/feiqiu/.env b/apps/etl/connectors/feiqiu/.env
index 1e3557c..4536f13 100644
--- a/apps/etl/connectors/feiqiu/.env
+++ b/apps/etl/connectors/feiqiu/.env
@@ -26,7 +26,7 @@ SCHEMA_ETL=meta
# API 配置（上游 SaaS API）
# ------------------------------------------------------------------------------
API_BASE=https://pc.ficoo.vip/apiprod/admin/v1/
-API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnQtdHlwZSI6IjQiLCJ1c2VyLXR5cGUiOiIxIiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjoiMTIiLCJyb2xlLWlkIjoiMTIiLCJ0ZW5hbnQtaWQiOiIyNzkwNjgzMTYwNzA5OTU3Iiwibmlja25hbWUiOiLnp5_miLfnrqHnkIblkZjvvJrmganmgakxIiwic2l0ZS1pZCI6IjAiLCJtb2JpbGUiOiIxMzgxMDUwMjMwNCIsInNpZCI6IjI5NTA0ODk2NTgzOTU4NDUiLCJzdGFmZi1pZCI6IjMwMDk5MTg2OTE1NTkwNDUiLCJvcmctaWQiOiIwIiwicm9sZS10eXBlIjoiMyIsInJlZnJlc2hUb2tlbiI6IkZJUUxIWWJLSFl5QktJQlVuLzZuQVdINitqOEpLbGNHN1NScDFFaFNuMEE9IiwicmVmcmVzaEV4cGlyeVRpbWUiOiIyMDI2LzQvNyDkuIrljYg0OjU2OjA4IiwibmVlZENoZWNrVG9rZW4iOiJmYWxzZSIsImV4cCI6MTc3NTUwODk2OCwiaXNzIjoidGVzdCIsImF1ZCI6IlVzZXIifQ.fc92FpZrLBkV9tD9sNPCvMvgNePh5Y7T6g5FLx8N16A
+API_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnQtdHlwZSI6IjQiLCJ1c2VyLXR5cGUiOiIxIiwiaHR0cDovL3NjaGVtYXMubWljcm9zb2Z0LmNvbS93cy8yMDA4LzA2L2lkZW50aXR5L2NsYWltcy9yb2xlIjoiMTIiLCJyb2xlLWlkIjoiMTIiLCJ0ZW5hbnQtaWQiOiIyNzkwNjgzMTYwNzA5OTU3Iiwibmlja25hbWUiOiLnp5_miLfnrqHnkIblkZjvvJrmganmgakxIiwic2l0ZS1pZCI6IjAiLCJtb2JpbGUiOiIxMzgxMDUwMjMwNCIsInNpZCI6IjI5NTA0ODk2NTgzOTU4NDUiLCJzdGFmZi1pZCI6IjMwMDk5MTg2OTE1NTkwNDUiLCJvcmctaWQiOiIwIiwicm9sZS10eXBlIjoiMyIsInJlZnJlc2hUb2tlbiI6Ik9OUTkreFhSWjFPVFhzQWhieTJVa3RyVXR6UzdldVE5Q1VVQ3QzQ1ArMlE9IiwicmVmcmVzaEV4cGlyeVRpbWUiOiIyMDI2LzQvMTQg5LiL5Y2INTo0MToyNSIsIm5lZWRDaGVja1Rva2VuIjoiZmFsc2UiLCJleHAiOjE3NzYxNTk2ODUsImlzcyI6InRlc3QiLCJhdWQiOiJVc2VyIn0.KyULo2a6dirmiAkka5Ocu_ieoZY5VsVWVqMj5smwvmE
API_TIMEOUT=20
API_PAGE_SIZE=200
API_RETRY_MAX=3
diff --git a/apps/etl/connectors/feiqiu/database/connection.py b/apps/etl/connectors/feiqiu/database/connection.py
index 54786be..fa0a97f 100644
--- a/apps/etl/connectors/feiqiu/database/connection.py
+++ b/apps/etl/connectors/feiqiu/database/connection.py
@@ -1,9 +1,15 @@
# -*- coding: utf-8 -*-
"""数据库连接管理器（限制最大连接超时时间）。"""
+import time
+
import psycopg2
import psycopg2.extras
+# 连接重试参数：应对 PostgreSQL 瞬时不可用
+_CONNECT_MAX_RETRIES = 3
+_CONNECT_RETRY_DELAY = 1.0
+
class DatabaseConnection:
"""封装 psycopg2 连接，支持会话参数和超时保护。"""
@@ -24,11 +30,25 @@ class DatabaseConnection:
# assumptions: libpq 默认使用系统 locale 的 client_encoding，Windows 中文系统为 GBK/CP936
# 边界: 显式指定 client_encoding=utf8 确保连接层始终使用 UTF-8，与数据库 server_encoding 一致
# 验证: web-admin 手动触发 ETL 全量 flow，不再出现 0xd6 解码错误
- conn = psycopg2.connect(
- self._dsn,
- connect_timeout=timeout_val,
- options="-c client_encoding=utf8",
- )
+ last_exc = None
+ for attempt in range(_CONNECT_MAX_RETRIES):
+ try:
+ conn = psycopg2.connect(
+ self._dsn,
+ connect_timeout=timeout_val,
+ options="-c client_encoding=utf8",
+ keepalives=1,
+ keepalives_idle=60,
+ keepalives_interval=10,
+ keepalives_count=3,
+ )
+ break
+ except psycopg2.OperationalError as e:
+ last_exc = e
+ if attempt < _CONNECT_MAX_RETRIES - 1:
+ time.sleep(_CONNECT_RETRY_DELAY * (attempt + 1))
+ else:
+ raise last_exc
conn.autocommit = False
# 会话参数（时区、语句超时等）
diff --git a/apps/etl/connectors/feiqiu/database/operations.py b/apps/etl/connectors/feiqiu/database/operations.py
index 62b7bd9..a2756b4 100644
--- a/apps/etl/connectors/feiqiu/database/operations.py
+++ b/apps/etl/connectors/feiqiu/database/operations.py
@@ -30,6 +30,16 @@ class DatabaseOperations:
@property
def _connect_timeout(self):
return self._connection._connect_timeout
+
+ def ensure_open(self) -> bool:
+ """透传 DatabaseConnection.ensure_open()，重连后同步 self.conn 引用。"""
+ result = self._connection.ensure_open()
+ self.conn = self._connection.conn
+ return result
+
+ def rollback(self):
+ """透传 DatabaseConnection.rollback()。"""
+ self._connection.rollback()
def batch_execute(self, sql: str, rows: list, page_size: int = 1000):
"""批量执行SQL"""
diff --git a/apps/etl/connectors/feiqiu/orchestration/flow_runner.py b/apps/etl/connectors/feiqiu/orchestration/flow_runner.py
index db8eb64..3bf7a89 100644
--- a/apps/etl/connectors/feiqiu/orchestration/flow_runner.py
+++ b/apps/etl/connectors/feiqiu/orchestration/flow_runner.py
@@ -224,6 +224,9 @@ class FlowRunner:
summary_text = flow_logger.end(status="成功")
self.logger.info("\n%s", summary_text)
+ # CHANGE 2026-04-07 | Fix-12：ETL 完成后通知后端触发任务编排
+ self._notify_backend_etl_completed(run_label)
+
return {
"status": "SUCCESS",
"flow": run_label,
@@ -243,6 +246,33 @@ class FlowRunner:
self.logger.error("\n%s", summary_text)
raise
+ def _notify_backend_etl_completed(self, pipeline: str) -> None:
+ """ETL 完成后通知后端触发任务编排（recall_detector → task_generator）。
+
+ CHANGE 2026-04-07 | Fix-12：失败不阻断主流程，仅记录警告。
+ """
+ import os
+ backend_url = os.getenv("BACKEND_API_URL", "http://127.0.0.1:8000")
+ internal_token = os.getenv("INTERNAL_API_TOKEN", "")
+ if not internal_token:
+ self.logger.warning("ETL 完成回调跳过：INTERNAL_API_TOKEN 未配置")
+ return
+
+ try:
+ import httpx
+ resp = httpx.post(
+ f"{backend_url}/api/internal/etl-completed",
+ json={"pipeline": pipeline},
+ headers={"Authorization": f"Internal-Token {internal_token}"},
+ timeout=300,
+ )
+ if resp.status_code == 200:
+ self.logger.info("ETL 完成回调成功: %s", resp.json())
+ else:
+ self.logger.warning("ETL 完成回调失败: status=%d, body=%s", resp.status_code, resp.text)
+ except Exception:
+ self.logger.warning("ETL 完成回调异常（不阻断主流程）", exc_info=True)
+
def _run_post_consistency_check(self, timer: EtlTimer) -> str | None:
"""ETL 完成后运行数据一致性检查，输出黑盒测试报告。
diff --git a/apps/etl/connectors/feiqiu/orchestration/task_executor.py b/apps/etl/connectors/feiqiu/orchestration/task_executor.py
index 515c9d8..f6afb4f 100644
--- a/apps/etl/connectors/feiqiu/orchestration/task_executor.py
+++ b/apps/etl/connectors/feiqiu/orchestration/task_executor.py
@@ -21,6 +21,8 @@ from pathlib import Path
from typing import Any, Dict, List
from zoneinfo import ZoneInfo
+import psycopg2
+
from api.recording_client import RecordingAPIClient
from api.local_json_client import LocalJsonClient
from orchestration.cursor_manager import CursorManager
@@ -91,6 +93,17 @@ class TaskExecutor:
self.logger.info("开始运行任务: %s, run_uuid=%s", task_codes, run_uuid)
for task_code in task_codes:
+ # 每个任务前检测连接状态，断线自动重连
+ if not self.db_ops.ensure_open():
+ self.logger.error("数据库连接不可用且重连失败，跳过任务 %s", task_code)
+ results.append({
+ "task_code": task_code,
+ "status": "失败",
+ "error": "数据库连接不可用",
+ "counts": {},
+ })
+ continue
+
# 为每个任务创建独立的日志缓冲区，避免多任务日志交叉
task_log_buf = TaskLogBuffer(task_code, self.logger)
try:
@@ -113,9 +126,13 @@ class TaskExecutor:
task_log_buf.error("任务失败: %s", exc)
# CHANGE 2026-02-24 | 任务失败后 rollback，防止 InFailedSqlTransaction 级联
try:
- self.db.rollback()
+ self.db_ops.rollback()
except Exception:
pass
+ # 连接级异常：尝试重连，避免后续任务全部级联失败
+ if isinstance(exc, (psycopg2.OperationalError, psycopg2.InterfaceError)):
+ self.logger.warning("检测到连接异常，尝试重连...")
+ self.db_ops.ensure_open()
results.append({
"task_code": task_code,
"status": "失败",
diff --git a/apps/etl/connectors/feiqiu/orchestration/task_registry.py b/apps/etl/connectors/feiqiu/orchestration/task_registry.py
index f746b25..c9f476f 100644
--- a/apps/etl/connectors/feiqiu/orchestration/task_registry.py
+++ b/apps/etl/connectors/feiqiu/orchestration/task_registry.py
@@ -43,6 +43,7 @@ from tasks.dws import (
FinanceRechargeTask,
FinanceIncomeStructureTask,
FinanceDiscountDetailTask,
+ FinanceAreaDailyTask,
# 库存汇总任务
GoodsStockDailyTask,
GoodsStockWeeklyTask,
@@ -167,6 +168,7 @@ default_registry.register("DWS_FINANCE_DAILY", FinanceDailyTask, layer="DWS")
default_registry.register("DWS_FINANCE_RECHARGE", FinanceRechargeTask, layer="DWS")
default_registry.register("DWS_FINANCE_INCOME_STRUCTURE", FinanceIncomeStructureTask, layer="DWS")
default_registry.register("DWS_FINANCE_DISCOUNT_DETAIL", FinanceDiscountDetailTask, layer="DWS")
+default_registry.register("DWS_FINANCE_AREA_DAILY", FinanceAreaDailyTask, layer="DWS", depends_on=["DWS_FINANCE_DAILY"])
# CHANGE [2026-03-27] intent: 移除对 DWD_LOAD_FROM_ODS 的显式依赖，dwd_dws Flow 下该依赖不在批次内只产生无意义 warning
default_registry.register("DWS_GOODS_STOCK_DAILY", GoodsStockDailyTask, layer="DWS")
default_registry.register("DWS_GOODS_STOCK_WEEKLY", GoodsStockWeeklyTask, layer="DWS")
@@ -182,6 +184,7 @@ default_registry.register("DWS_MAINTENANCE", DwsMaintenanceTask, layer="DWS", de
"DWS_ASSISTANT_PROJECT_TAG", "DWS_MEMBER_PROJECT_TAG",
"DWS_FINANCE_DAILY", "DWS_FINANCE_RECHARGE",
"DWS_FINANCE_INCOME_STRUCTURE", "DWS_FINANCE_DISCOUNT_DETAIL",
+ "DWS_FINANCE_AREA_DAILY",
"DWS_BUILD_ORDER_SUMMARY",
"DWS_GOODS_STOCK_DAILY", "DWS_GOODS_STOCK_WEEKLY", "DWS_GOODS_STOCK_MONTHLY",
])
diff --git a/apps/etl/connectors/feiqiu/pyproject.toml b/apps/etl/connectors/feiqiu/pyproject.toml
index 95041f4..3482b0b 100644
--- a/apps/etl/connectors/feiqiu/pyproject.toml
+++ b/apps/etl/connectors/feiqiu/pyproject.toml
@@ -9,6 +9,7 @@ dependencies = [
"tzdata>=2023.0",
"python-dotenv",
"openpyxl>=3.1.0",
+ "httpx>=0.24.0",
"neozqyy-shared",
]
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 e7c2ced..027a811 100644
--- a/apps/etl/connectors/feiqiu/tasks/dws/finance_area_daily.py
+++ b/apps/etl/connectors/feiqiu/tasks/dws/finance_area_daily.py
@@ -373,6 +373,8 @@ def transform_area_daily(
)
# 收集所有涉及的日期
all_dates: set[date] = set()
+ # 未知区域名称计数（汇总后一次性输出，避免逐行 warning 产生大量日志噪音）
+ _unknown_area_counts: Dict[str, int] = defaultdict(int)
for row in settlement_rows:
sd = row.get("stat_date")
@@ -389,11 +391,7 @@ def transform_area_daily(
area_code = resolve_area_code(area_name)
if area_code is None:
- # 未知区域：记录警告，不计入具体区域行，但仍计入 all 行
- logger.warning(
- "DWS_FINANCE_AREA_DAILY: 未知区域名称 '%s'，不计入具体区域",
- area_name,
- )
+ _unknown_area_counts[str(area_name)] += 1
# 提取金额
table_fee = safe_decimal_fn(row.get("table_fee_amount", 0))
@@ -464,6 +462,15 @@ def transform_area_daily(
for k, v in fields.items():
bucket[k] = bucket[k] + v
+ # 汇总输出未知区域名称（避免逐行 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",
+ sum(_unknown_area_counts.values()),
+ summary,
+ )
+
# 也收集 global_summary 中的日期
for sd in global_index:
all_dates.add(sd)
diff --git a/apps/etl/connectors/feiqiu/tasks/dws/finance_base_task.py b/apps/etl/connectors/feiqiu/tasks/dws/finance_base_task.py
index 85640a6..7111c28 100644
--- a/apps/etl/connectors/feiqiu/tasks/dws/finance_base_task.py
+++ b/apps/etl/connectors/feiqiu/tasks/dws/finance_base_task.py
@@ -104,10 +104,10 @@ class FinanceBaseTask(BaseDwsTask):
SUM(CASE WHEN is_first = 1 THEN pay_amount + point_amount ELSE 0 END) AS first_recharge_total,
SUM(CASE WHEN is_first = 1 THEN pay_amount ELSE 0 END) AS first_recharge_cash,
SUM(CASE WHEN is_first = 1 THEN point_amount ELSE 0 END) AS first_recharge_gift,
- COUNT(CASE WHEN is_first = 0 OR is_first IS NULL THEN 1 END) AS renewal_count,
- SUM(CASE WHEN is_first = 0 OR is_first IS NULL THEN pay_amount + point_amount ELSE 0 END) AS renewal_total,
- SUM(CASE WHEN is_first = 0 OR is_first IS NULL THEN pay_amount ELSE 0 END) AS renewal_cash,
- SUM(CASE WHEN is_first = 0 OR is_first IS NULL THEN point_amount ELSE 0 END) AS renewal_gift,
+ COUNT(CASE WHEN is_first = 2 THEN 1 END) AS renewal_count,
+ SUM(CASE WHEN is_first = 2 THEN pay_amount + point_amount ELSE 0 END) AS renewal_total,
+ SUM(CASE WHEN is_first = 2 THEN pay_amount ELSE 0 END) AS renewal_cash,
+ SUM(CASE WHEN is_first = 2 THEN point_amount ELSE 0 END) AS renewal_gift,
COUNT(DISTINCT member_id) AS recharge_member_count
FROM dwd.dwd_recharge_order
WHERE site_id = %s
diff --git a/apps/etl/connectors/feiqiu/tasks/dws/finance_recharge_task.py b/apps/etl/connectors/feiqiu/tasks/dws/finance_recharge_task.py
index 7978308..0291e29 100644
--- a/apps/etl/connectors/feiqiu/tasks/dws/finance_recharge_task.py
+++ b/apps/etl/connectors/feiqiu/tasks/dws/finance_recharge_task.py
@@ -139,10 +139,10 @@ class FinanceRechargeTask(FinanceBaseTask):
SUM(CASE WHEN is_first = 1 THEN pay_amount ELSE 0 END) AS first_recharge_cash,
SUM(CASE WHEN is_first = 1 THEN point_amount ELSE 0 END) AS first_recharge_gift,
SUM(CASE WHEN is_first = 1 THEN pay_amount + point_amount ELSE 0 END) AS first_recharge_total,
- COUNT(CASE WHEN is_first != 1 OR is_first IS NULL THEN 1 END) AS renewal_count,
- SUM(CASE WHEN is_first != 1 OR is_first IS NULL THEN pay_amount ELSE 0 END) AS renewal_cash,
- SUM(CASE WHEN is_first != 1 OR is_first IS NULL THEN point_amount ELSE 0 END) AS renewal_gift,
- SUM(CASE WHEN is_first != 1 OR is_first IS NULL THEN pay_amount + point_amount ELSE 0 END) AS renewal_total,
+ COUNT(CASE WHEN is_first = 2 THEN 1 END) AS renewal_count,
+ SUM(CASE WHEN is_first = 2 THEN pay_amount ELSE 0 END) AS renewal_cash,
+ SUM(CASE WHEN is_first = 2 THEN point_amount ELSE 0 END) AS renewal_gift,
+ SUM(CASE WHEN is_first = 2 THEN pay_amount + point_amount ELSE 0 END) AS renewal_total,
COUNT(DISTINCT member_id) AS recharge_member_count,
COUNT(DISTINCT CASE WHEN is_first = 1 THEN member_id END) AS new_member_count
FROM dwd.dwd_recharge_order
@@ -198,20 +198,19 @@ class FinanceRechargeTask(FinanceBaseTask):
CASH_CARD_TYPE_ID = 2793249295533893
GIFT_CARD_TYPE_IDS = [2791990152417157, 2793266846533445, 2794699703437125]
- # CHANGE 2026-02-21 | dim_member_card_account 无 site_id 字段，改用 register_site_id
- # CHANGE 2026-02-22 | 需求 B：通过事实表反查，支持跨店消费会员
+ # CHANGE 2026-04-08 | 修复卡余额快照失真：改为门店全量会员
+ # 原逻辑通过 dwd_recharge_order 反查，遗漏"有卡无充值"会员（赠卡、活动等）
+ # 余额代表门店预收负债，应覆盖所有持卡会员
sql = """
- SELECT card_type_id, SUM(balance) AS total_balance
- FROM dwd.dim_member_card_account
- WHERE tenant_member_id IN (
- SELECT DISTINCT member_id
- FROM dwd.dwd_recharge_order
- WHERE site_id = %s
- AND member_id IS NOT NULL
- AND member_id != 0
- ) AND scd2_is_current = 1
- AND COALESCE(is_delete, 0) = 0
- GROUP BY card_type_id
+ SELECT dca.card_type_id, SUM(dca.balance) AS total_balance
+ FROM dwd.dim_member_card_account dca
+ JOIN dwd.dim_member m
+ ON dca.tenant_member_id = m.member_id
+ AND m.scd2_is_current = 1
+ WHERE m.register_site_id = %s
+ AND dca.scd2_is_current = 1
+ AND COALESCE(dca.is_delete, 0) = 0
+ GROUP BY dca.card_type_id
"""
rows = self.db.query(sql, (site_id,))
diff --git a/apps/etl/connectors/feiqiu/tasks/dws/index/member_index_base.py b/apps/etl/connectors/feiqiu/tasks/dws/index/member_index_base.py
index 8df0e68..337894d 100644
--- a/apps/etl/connectors/feiqiu/tasks/dws/index/member_index_base.py
+++ b/apps/etl/connectors/feiqiu/tasks/dws/index/member_index_base.py
@@ -36,6 +36,7 @@ class MemberActivityData:
days_since_last_recharge: Optional[int] = None
visits_14d: int = 0
+ visits_30d: int = 0
visits_60d: int = 0
visits_total: int = 0
@@ -451,8 +452,9 @@ class MemberIndexBaseTask(BaseIndexTask):
last_visit_time = max(r.get('last_visit_time') for r in day_rows_sorted)
data.last_visit_time = last_visit_time
- # 近14/60天到店次数
+ # 近14/30/60天到店次数
days_14_ago = base_date - timedelta(days=14)
+ days_30_ago_visit = base_date - timedelta(days=30)
days_60_ago = base_date - timedelta(days=60)
for r in day_rows_sorted:
visit_date = r.get('visit_date')
@@ -460,6 +462,8 @@ class MemberIndexBaseTask(BaseIndexTask):
continue
if visit_date >= days_14_ago:
data.visits_14d += 1
+ if visit_date >= days_30_ago_visit:
+ data.visits_30d += 1
if visit_date >= days_60_ago:
data.visits_60d += 1
diff --git a/apps/etl/connectors/feiqiu/tasks/dws/index/newconv_index_task.py b/apps/etl/connectors/feiqiu/tasks/dws/index/newconv_index_task.py
index aebe180..8d9e267 100644
--- a/apps/etl/connectors/feiqiu/tasks/dws/index/newconv_index_task.py
+++ b/apps/etl/connectors/feiqiu/tasks/dws/index/newconv_index_task.py
@@ -317,7 +317,7 @@ class NewconvIndexTask(MemberIndexBaseTask):
status, segment,
member_create_time, first_visit_time, last_visit_time, last_recharge_time,
t_v, t_r, t_a,
- visits_14d, visits_60d, visits_total,
+ 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,
@@ -331,7 +331,7 @@ class NewconvIndexTask(MemberIndexBaseTask):
%s, %s,
%s, %s, %s, %s,
%s, %s, %s,
- %s, %s, %s,
+ %s, %s, %s, %s,
%s, %s, %s, %s,
%s,
%s, %s, %s, %s,
@@ -352,7 +352,7 @@ class NewconvIndexTask(MemberIndexBaseTask):
data.status, data.segment,
activity.member_create_time, activity.first_visit_time, activity.last_visit_time, activity.last_recharge_time,
activity.t_v, activity.t_r, activity.t_a,
- activity.visits_14d, activity.visits_60d, activity.visits_total,
+ activity.visits_14d, activity.visits_30d, activity.visits_60d, activity.visits_total,
activity.spend_30d, activity.spend_180d, activity.sv_balance, activity.recharge_60d_amt,
activity.interval_count,
data.need_new, data.salvage_new, data.recharge_new, data.value_new,
diff --git a/apps/etl/connectors/feiqiu/tasks/dws/index/spending_power_index_task.py b/apps/etl/connectors/feiqiu/tasks/dws/index/spending_power_index_task.py
index 2b5c586..4752ed3 100644
--- a/apps/etl/connectors/feiqiu/tasks/dws/index/spending_power_index_task.py
+++ b/apps/etl/connectors/feiqiu/tasks/dws/index/spending_power_index_task.py
@@ -353,7 +353,12 @@ class SpendingPowerIndexTask(BaseIndexTask):
COALESCE(NULLIF(s.member_id, 0), mca.tenant_member_id)
AS canonical_member_id,
s.pay_time,
- COALESCE(s.pay_amount, 0) AS pay_amount
+ -- DWD 规则 #1：禁止 consume_money/pay_amount，使用 items_sum
+ (COALESCE(s.table_charge_money, 0)
+ + COALESCE(s.goods_money, 0)
+ + COALESCE(s.assistant_pd_money, 0)
+ + COALESCE(s.assistant_cx_money, 0)
+ + COALESCE(s.electricity_money, 0)) AS items_sum
FROM dwd.dwd_settlement_head s
LEFT JOIN dwd.dim_member_card_account mca
ON s.member_card_account_id = mca.member_card_id
@@ -368,14 +373,14 @@ class SpendingPowerIndexTask(BaseIndexTask):
SELECT
canonical_member_id AS member_id,
-- 90 天窗口
- SUM(pay_amount) AS spend_90,
+ SUM(items_sum) AS spend_90,
COUNT(*) AS orders_90,
COUNT(DISTINCT {biz_expr}) AS visit_days_90,
COUNT(DISTINCT EXTRACT(ISOYEAR FROM pay_time)::int * 100
+ EXTRACT(WEEK FROM pay_time)::int) AS active_weeks_90,
-- 30 天窗口（子集过滤）
SUM(CASE WHEN pay_time >= %s - INTERVAL '{short_days} days'
- THEN pay_amount ELSE 0 END) AS spend_30,
+ THEN items_sum ELSE 0 END) AS spend_30,
SUM(CASE WHEN pay_time >= %s - INTERVAL '{short_days} days'
THEN 1 ELSE 0 END) AS orders_30,
COUNT(DISTINCT CASE WHEN pay_time >= %s - INTERVAL '{short_days} days'
@@ -491,7 +496,12 @@ class SpendingPowerIndexTask(BaseIndexTask):
COALESCE(NULLIF(s.member_id, 0), mca.tenant_member_id)
AS canonical_member_id,
{biz_expr_s} AS pay_date,
- COALESCE(s.pay_amount, 0) AS pay_amount
+ -- DWD 规则 #1：使用 items_sum
+ (COALESCE(s.table_charge_money, 0)
+ + COALESCE(s.goods_money, 0)
+ + COALESCE(s.assistant_pd_money, 0)
+ + COALESCE(s.assistant_cx_money, 0)
+ + COALESCE(s.electricity_money, 0)) AS items_sum
FROM dwd.dwd_settlement_head s
LEFT JOIN dwd.dim_member_card_account mca
ON s.member_card_account_id = mca.member_card_id
@@ -502,7 +512,7 @@ class SpendingPowerIndexTask(BaseIndexTask):
AND s.settle_type IN (1, 3)
AND s.pay_time >= NOW() - INTERVAL '{long_days} days'
)
- SELECT pay_date, SUM(pay_amount) AS daily_spend
+ SELECT pay_date, SUM(items_sum) AS daily_spend
FROM consume_source
WHERE canonical_member_id = %s
GROUP BY pay_date
@@ -544,7 +554,12 @@ class SpendingPowerIndexTask(BaseIndexTask):
COALESCE(NULLIF(s.member_id, 0), mca.tenant_member_id)
AS canonical_member_id,
{biz_expr_s} AS pay_date,
- COALESCE(s.pay_amount, 0) AS pay_amount
+ -- DWD 规则 #1：使用 items_sum
+ (COALESCE(s.table_charge_money, 0)
+ + COALESCE(s.goods_money, 0)
+ + COALESCE(s.assistant_pd_money, 0)
+ + COALESCE(s.assistant_cx_money, 0)
+ + COALESCE(s.electricity_money, 0)) AS items_sum
FROM dwd.dwd_settlement_head s
LEFT JOIN dwd.dim_member_card_account mca
ON s.member_card_account_id = mca.member_card_id
@@ -558,7 +573,7 @@ class SpendingPowerIndexTask(BaseIndexTask):
)
SELECT canonical_member_id AS member_id,
pay_date,
- SUM(pay_amount) AS daily_spend
+ SUM(items_sum) AS daily_spend
FROM consume_source
WHERE canonical_member_id > 0
GROUP BY canonical_member_id, pay_date
diff --git a/apps/etl/connectors/feiqiu/tasks/dws/index/winback_index_task.py b/apps/etl/connectors/feiqiu/tasks/dws/index/winback_index_task.py
index 811bafe..01551fa 100644
--- a/apps/etl/connectors/feiqiu/tasks/dws/index/winback_index_task.py
+++ b/apps/etl/connectors/feiqiu/tasks/dws/index/winback_index_task.py
@@ -369,7 +369,7 @@ class WinbackIndexTask(MemberIndexBaseTask):
status, segment,
member_create_time, first_visit_time, last_visit_time, last_recharge_time,
t_v, t_r, t_a,
- visits_14d, visits_60d, visits_total,
+ visits_14d, visits_30d, visits_60d, visits_total,
spend_30d, spend_180d, sv_balance, recharge_60d_amt,
interval_count,
overdue_old, overdue_cdf_p, drop_old, recharge_old, value_old,
@@ -382,7 +382,7 @@ class WinbackIndexTask(MemberIndexBaseTask):
%s, %s,
%s, %s, %s, %s,
%s, %s, %s,
- %s, %s, %s,
+ %s, %s, %s, %s,
%s, %s, %s, %s,
%s,
%s, %s, %s, %s, %s,
@@ -402,7 +402,7 @@ class WinbackIndexTask(MemberIndexBaseTask):
data.status, data.segment,
activity.member_create_time, activity.first_visit_time, activity.last_visit_time, activity.last_recharge_time,
activity.t_v, activity.t_r, activity.t_a,
- activity.visits_14d, activity.visits_60d, activity.visits_total,
+ activity.visits_14d, activity.visits_30d, activity.visits_60d, activity.visits_total,
activity.spend_30d, activity.spend_180d, activity.sv_balance, activity.recharge_60d_amt,
activity.interval_count,
data.overdue_old, data.overdue_cdf_p, data.drop_old, data.recharge_old, data.value_old,
diff --git a/apps/miniprogram/miniprogram/pages/board-coach/board-coach.ts b/apps/miniprogram/miniprogram/pages/board-coach/board-coach.ts
index 8ab79fe..0c8f3ae 100644
--- a/apps/miniprogram/miniprogram/pages/board-coach/board-coach.ts
+++ b/apps/miniprogram/miniprogram/pages/board-coach/board-coach.ts
@@ -162,6 +162,8 @@ Page({
_lastScrollTop: 0,
_scrollAcc: 0,
_scrollDir: null as 'up' | 'down' | null,
+ /** 请求代数计数器：切换筛选时递增，旧请求的响应到达后对比丢弃 */
+ _loadGeneration: 0,
onLoad() {
this.loadData()
@@ -181,6 +183,7 @@ Page({
},
onPullDownRefresh() {
+ this._loadGeneration++
this.setData({ currentPage: 1, hasMore: true, coaches: [], allCoaches: [] })
this.loadData()
setTimeout(() => wx.stopPullDownRefresh(), 500)
@@ -219,7 +222,9 @@ Page({
// CHANGE 2026-03-28 | P4 联调：替换 Mock 为真实 API 调用
// CHANGE 2026-03-29 | 懒加载：支持分页追加
+ // CHANGE 2026-04-08 | 竞态修复：用 _loadGeneration 丢弃过时响应
async loadData() {
+ const gen = this._loadGeneration
const page = this.data.currentPage
const isFirstPage = page === 1
@@ -239,6 +244,8 @@ Page({
page,
pageSize: this.data.pageSize,
})
+ // 竞态保护：响应到达时代数已变（用户切了筛选），丢弃本次结果
+ if (gen !== this._loadGeneration) return
const items = res.items
if (isFirstPage && (!items || items.length === 0)) {
this.setData({ pageState: 'empty', totalCount: 0, hasMore: false })
@@ -318,6 +325,7 @@ Page({
onSortChange(e: WechatMiniprogram.CustomEvent<{ value: string }>) {
const val = e.detail.value
+ this._loadGeneration++
this.setData({
selectedSort: val,
dimType: SORT_TO_DIM[val] || 'perf',
@@ -327,11 +335,13 @@ Page({
},
onSkillChange(e: WechatMiniprogram.CustomEvent<{ value: string }>) {
+ this._loadGeneration++
this.setData({ selectedSkill: e.detail.value, currentPage: 1, hasMore: true, coaches: [], allCoaches: [] })
this.loadData()
},
onTimeChange(e: WechatMiniprogram.CustomEvent<{ value: string }>) {
+ this._loadGeneration++
this.setData({ selectedTime: e.detail.value, currentPage: 1, hasMore: true, coaches: [], allCoaches: [] })
this.loadData()
},
diff --git a/apps/miniprogram/miniprogram/pages/board-customer/board-customer.ts b/apps/miniprogram/miniprogram/pages/board-customer/board-customer.ts
index 0bae58c..3819c96 100644
--- a/apps/miniprogram/miniprogram/pages/board-customer/board-customer.ts
+++ b/apps/miniprogram/miniprogram/pages/board-customer/board-customer.ts
@@ -33,7 +33,7 @@ const DIMENSION_OPTIONS = [
{ value: 'recent', text: '最近到店' },
{ value: 'spend60', text: '最高消费 近60天' },
{ value: 'freq60', text: '最频繁 近60天' },
- { value: 'loyal', text: '最专一 近60天' },
+ { value: 'loyal', text: '最专一 近90天' },
]
// CHANGE 2026-03-28 | P9 修复：value 改为数据库 category_code，与后端枚举一致。
@@ -200,6 +200,8 @@ Page({
_lastScrollTop: 0,
_scrollAcc: 0,
_scrollDir: null as 'up' | 'down' | null,
+ /** 请求代数计数器：切换维度/项目时递增，旧请求的响应到达后对比丢弃 */
+ _loadGeneration: 0,
onLoad() {
this.loadData()
@@ -219,6 +221,7 @@ Page({
},
onPullDownRefresh() {
+ this._loadGeneration++
this.setData({ currentPage: 1, hasMore: true, customers: [], allCustomers: [] })
this.loadData()
setTimeout(() => wx.stopPullDownRefresh(), 500)
@@ -257,7 +260,9 @@ Page({
// CHANGE 2026-03-28 | P5 联调：替换 Mock 为真实 API 调用
// CHANGE 2026-03-29 | 懒加载：支持分页追加
+ // CHANGE 2026-04-08 | 竞态修复：用 _loadGeneration 丢弃过时响应
async loadData() {
+ const gen = this._loadGeneration
const page = this.data.currentPage
const isFirstPage = page === 1
@@ -276,6 +281,8 @@ Page({
page,
pageSize: this.data.pageSize,
})
+ // 竞态保护：响应到达时代数已变（用户切了维度/项目），丢弃本次结果
+ if (gen !== this._loadGeneration) return
const items = res.items
if (isFirstPage && (!items || items.length === 0)) {
this.setData({ pageState: 'empty', totalCount: 0, hasMore: false })
@@ -348,6 +355,7 @@ Page({
onDimensionChange(e: WechatMiniprogram.CustomEvent<{ value: string }>) {
const val = e.detail.value
+ this._loadGeneration++
this.setData({
selectedDimension: val,
dimType: DIMENSION_TO_DIM[val] || 'recall',
@@ -357,6 +365,7 @@ Page({
},
onProjectChange(e: WechatMiniprogram.CustomEvent<{ value: string }>) {
+ this._loadGeneration++
this.setData({ selectedProject: e.detail.value, currentPage: 1, hasMore: true, customers: [], allCustomers: [] })
this.loadData()
},
diff --git a/apps/miniprogram/miniprogram/pages/board-customer/board-customer.wxml b/apps/miniprogram/miniprogram/pages/board-customer/board-customer.wxml
index 9adb17f..ecaa70a 100644
--- a/apps/miniprogram/miniprogram/pages/board-customer/board-customer.wxml
+++ b/apps/miniprogram/miniprogram/pages/board-customer/board-customer.wxml
@@ -165,7 +165,7 @@
{{fmt.money(item.spend30d)}}
- 月均到店
+ 近30天到店
{{fmt.count(item.avgVisits, '次')}}
@@ -201,7 +201,7 @@
{{fmt.safe(item.lastRecharge)}}
- 充值
+ 累计充值
{{fmt.money(item.rechargeAmount)}}
diff --git a/apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss b/apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss
index 8193152..dd26259 100644
--- a/apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss
+++ b/apps/miniprogram/miniprogram/pages/board-finance/board-finance.wxss
@@ -1248,7 +1248,7 @@ AI_CHANGELOG
/* CHANGE 2026-03-14 | intent: H5 gap-1=4px → spec p-1=8rpx */
.coach-fin-header {
display: grid;
- grid-template-columns: 1fr 1.2fr 1.2fr 1fr;
+ grid-template-columns: 1fr 1.5fr 1.5fr 1fr;
gap: 8rpx;
padding: 14rpx 30rpx;
background: #f0f0f0;
@@ -1276,7 +1276,7 @@ AI_CHANGELOG
/* CHANGE 2026-03-14 | intent: H5 gap-1=4px → spec p-1=8rpx；基础行 py-2=14rpx */
.coach-fin-row {
display: grid;
- grid-template-columns: 1fr 1.2fr 1.2fr 1fr;
+ grid-template-columns: 1fr 1.5fr 1.5fr 1fr;
gap: 8rpx;
padding: 14rpx 30rpx;
border-bottom: 2rpx solid #f3f3f3;
@@ -1306,7 +1306,7 @@ AI_CHANGELOG
/* CHANGE 2026-03-13 | intent: 校对 H5 coach-fin-bold fontSize:14px→24rpx(87.5%) */
.coach-fin-bold {
- font-size: 26rpx;
+ font-size: 30rpx;
line-height: 36rpx;
font-weight: 600;
color: #242424;
diff --git a/db/etl_feiqiu/migrations/20260407_add_visits_30d.sql b/db/etl_feiqiu/migrations/20260407_add_visits_30d.sql
new file mode 100644
index 0000000..04803b0
--- /dev/null
+++ b/db/etl_feiqiu/migrations/20260407_add_visits_30d.sql
@@ -0,0 +1,74 @@
+-- 迁移：为 dws_member_winback_index 和 dws_member_newconv_index 添加 visits_30d 字段
+-- Fix-3：recall 维度需要 30 天到店次数，原先用 visits_14d 近似
+-- 日期：2026-04-07
+-- 重要：加列后必须重建所有引用这两张表的视图，否则视图看不到新列
+
+-- 1. 加列
+ALTER TABLE dws.dws_member_winback_index
+ ADD COLUMN IF NOT EXISTS visits_30d integer DEFAULT 0 NOT NULL;
+
+ALTER TABLE dws.dws_member_newconv_index
+ ADD COLUMN IF NOT EXISTS visits_30d integer DEFAULT 0 NOT NULL;
+
+-- 2. 重建 app schema RLS 视图（DROP + CREATE，因为列顺序变化导致 CREATE OR REPLACE 报错）
+DROP VIEW IF EXISTS app.v_dws_member_winback_index;
+CREATE VIEW app.v_dws_member_winback_index AS
+SELECT 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
+FROM dws.dws_member_winback_index
+WHERE site_id = current_setting('app.current_site_id')::bigint;
+
+DROP VIEW IF EXISTS app.v_dws_member_newconv_index;
+CREATE VIEW app.v_dws_member_newconv_index AS
+SELECT 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
+FROM dws.dws_member_newconv_index
+WHERE site_id = current_setting('app.current_site_id')::bigint;
+
+-- 3. 重建 dws.v_member_recall_priority (UNION ALL 视图)
+DROP VIEW IF EXISTS dws.v_member_recall_priority;
+CREATE VIEW dws.v_member_recall_priority AS
+SELECT site_id, tenant_id, member_id, 'WBI'::varchar(10) AS index_type,
+ 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,
+ NULL::numeric(10,4) AS need_new, NULL::numeric(10,4) AS salvage_new,
+ NULL::numeric(10,4) AS recharge_new, NULL::numeric(10,4) AS value_new,
+ NULL::numeric(10,4) AS welcome_new,
+ NULL::numeric(14,6) AS raw_score_welcome, NULL::numeric(14,6) AS raw_score_convert,
+ raw_score,
+ NULL::numeric(4,2) AS display_score_welcome, NULL::numeric(4,2) AS display_score_convert,
+ display_score, last_wechat_touch_time, calc_time
+FROM dws.dws_member_winback_index
+UNION ALL
+SELECT site_id, tenant_id, member_id, 'NCI'::varchar(10) AS index_type,
+ 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,
+ 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
+FROM dws.dws_member_newconv_index;
+
+-- 4. 回滚脚本（如需回滚，按逆序执行）：
+-- DROP VIEW IF EXISTS dws.v_member_recall_priority;
+-- DROP VIEW IF EXISTS app.v_dws_member_newconv_index;
+-- DROP VIEW IF EXISTS app.v_dws_member_winback_index;
+-- ALTER TABLE dws.dws_member_winback_index DROP COLUMN IF EXISTS visits_30d;
+-- ALTER TABLE dws.dws_member_newconv_index DROP COLUMN IF EXISTS visits_30d;
+-- 然后重建原始视图（不含 visits_30d）
diff --git a/db/etl_feiqiu/migrations/20260408_fix_snapshot_view_dedup.sql b/db/etl_feiqiu/migrations/20260408_fix_snapshot_view_dedup.sql
new file mode 100644
index 0000000..dd48335
--- /dev/null
+++ b/db/etl_feiqiu/migrations/20260408_fix_snapshot_view_dedup.sql
@@ -0,0 +1,58 @@
+-- 迁移：修复 app schema 快照视图多行膨胀
+-- 背景：consumption_summary 和 assistant_customer_stats 按 stat_date 存储每日快照，
+-- 原视图返回全部行导致 JOIN 行膨胀和前端卡片重复。
+-- 修复：DISTINCT ON 只取每个唯一键的最新 stat_date 行。
+-- 日期：2026-04-08
+
+-- 1. v_dws_member_consumption_summary：每个 member_id 只取最新快照
+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)
+ORDER BY member_id, stat_date DESC;
+
+-- 2. v_dws_assistant_customer_stats：每对 (assistant_id, member_id) 只取最新快照
+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)
+ORDER BY assistant_id, member_id, stat_date DESC;
+
+-- 验证 SQL（执行后检查）:
+-- SET app.current_site_id = '';
+-- 1) SELECT COUNT(*), COUNT(DISTINCT member_id) FROM app.v_dws_member_consumption_summary; -- 两个值应该相等
+-- 2) SELECT COUNT(*), COUNT(DISTINCT (assistant_id, member_id)) FROM app.v_dws_assistant_customer_stats; -- 两个值应该相等
+-- 3) SELECT member_id, COUNT(*) FROM app.v_dws_member_consumption_summary GROUP BY member_id HAVING COUNT(*) > 1; -- 应返回 0 行
+
+-- 回滚：
+-- CREATE OR REPLACE VIEW app.v_dws_member_consumption_summary AS
+-- SELECT ... FROM dws.dws_member_consumption_summary WHERE (site_id = ...); -- 去掉 DISTINCT ON 和 ORDER BY
+-- CREATE OR REPLACE VIEW app.v_dws_assistant_customer_stats AS
+-- SELECT ... FROM dws.dws_assistant_customer_stats WHERE (site_id = ...); -- 同上
diff --git a/db/etl_feiqiu/schemas/app.sql b/db/etl_feiqiu/schemas/app.sql
index 01d402e..1af6a83 100644
--- a/db/etl_feiqiu/schemas/app.sql
+++ b/db/etl_feiqiu/schemas/app.sql
@@ -439,8 +439,10 @@ SELECT table_fee_log_id,
WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint);
;
+-- CHANGE 2026-04-08 | DISTINCT ON 只取每对 (assistant, member) 最新快照
CREATE OR REPLACE VIEW app.v_dws_assistant_customer_stats AS
-SELECT id,
+SELECT DISTINCT ON (assistant_id, member_id)
+ id,
site_id,
tenant_id,
assistant_id,
@@ -478,7 +480,8 @@ SELECT id,
created_at,
updated_at
FROM dws.dws_assistant_customer_stats
- WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint);
+ WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint)
+ ORDER BY assistant_id, member_id, stat_date DESC;
;
CREATE OR REPLACE VIEW app.v_dws_assistant_daily_detail AS
@@ -976,8 +979,10 @@ SELECT relation_id,
WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint);
;
+-- CHANGE 2026-04-08 | DISTINCT ON 只取每个会员最新快照，避免多 stat_date 行膨胀
CREATE OR REPLACE VIEW app.v_dws_member_consumption_summary AS
-SELECT id,
+SELECT DISTINCT ON (member_id)
+ id,
site_id,
tenant_id,
member_id,
@@ -1024,7 +1029,8 @@ SELECT 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)
+ ORDER BY member_id, stat_date DESC;
;
CREATE OR REPLACE VIEW app.v_dws_member_newconv_index AS
@@ -1042,6 +1048,7 @@ SELECT newconv_id,
t_r,
t_a,
visits_14d,
+ visits_30d,
visits_60d,
visits_total,
spend_30d,
@@ -1167,6 +1174,7 @@ SELECT winback_id,
t_r,
t_a,
visits_14d,
+ visits_30d,
visits_60d,
visits_total,
spend_30d,
diff --git a/db/etl_feiqiu/schemas/dws.sql b/db/etl_feiqiu/schemas/dws.sql
index 70eda57..9b7f3c6 100644
--- a/db/etl_feiqiu/schemas/dws.sql
+++ b/db/etl_feiqiu/schemas/dws.sql
@@ -789,6 +789,7 @@ CREATE TABLE dws.dws_member_newconv_index (
t_r numeric(6,2),
t_a numeric(6,2),
visits_14d integer DEFAULT 0 NOT NULL,
+ visits_30d integer DEFAULT 0 NOT NULL,
visits_60d integer DEFAULT 0 NOT NULL,
visits_total integer DEFAULT 0 NOT NULL,
spend_30d numeric(14,2) DEFAULT 0 NOT NULL,
@@ -907,6 +908,7 @@ CREATE TABLE dws.dws_member_winback_index (
t_r numeric(6,2),
t_a numeric(6,2),
visits_14d integer DEFAULT 0 NOT NULL,
+ visits_30d integer DEFAULT 0 NOT NULL,
visits_60d integer DEFAULT 0 NOT NULL,
visits_total integer DEFAULT 0 NOT NULL,
spend_30d numeric(14,2) DEFAULT 0 NOT NULL,
@@ -1297,6 +1299,7 @@ SELECT dws_member_winback_index.site_id,
dws_member_winback_index.t_r,
dws_member_winback_index.t_a,
dws_member_winback_index.visits_14d,
+ dws_member_winback_index.visits_30d,
dws_member_winback_index.visits_60d,
dws_member_winback_index.visits_total,
dws_member_winback_index.spend_30d,
@@ -1332,6 +1335,7 @@ UNION ALL
dws_member_newconv_index.t_r,
dws_member_newconv_index.t_a,
dws_member_newconv_index.visits_14d,
+ dws_member_newconv_index.visits_30d,
dws_member_newconv_index.visits_60d,
dws_member_newconv_index.visits_total,
dws_member_newconv_index.spend_30d,
diff --git a/db/zqyy_app/migrations/20260407_add_completion_type.sql b/db/zqyy_app/migrations/20260407_add_completion_type.sql
new file mode 100644
index 0000000..4a4edf4
--- /dev/null
+++ b/db/zqyy_app/migrations/20260407_add_completion_type.sql
@@ -0,0 +1,11 @@
+-- 迁移：coach_tasks 添加 completion_type 字段
+-- Fix-13：区分自动完成（auto）和手动完成（manual）
+-- 日期：2026-04-07
+
+ALTER TABLE biz.coach_tasks
+ ADD COLUMN IF NOT EXISTS completion_type character varying(10);
+
+COMMENT ON COLUMN biz.coach_tasks.completion_type IS '完成类型：auto=系统自动检测到店, manual=助教手动标记';
+
+-- 回滚：
+-- ALTER TABLE biz.coach_tasks DROP COLUMN IF EXISTS completion_type;
diff --git a/db/zqyy_app/schemas/biz.sql b/db/zqyy_app/schemas/biz.sql
index f05f085..a4b00e1 100644
--- a/db/zqyy_app/schemas/biz.sql
+++ b/db/zqyy_app/schemas/biz.sql
@@ -16,6 +16,7 @@ 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;
@@ -153,6 +154,7 @@ 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(),
@@ -161,6 +163,17 @@ CREATE TABLE biz.coach_tasks (
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()
+);
+
CREATE TABLE biz.connectors (
id integer DEFAULT nextval('biz.connectors_id_seq'::regclass) NOT NULL,
connector_key character varying(50) NOT NULL,
@@ -341,6 +354,8 @@ 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.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);
@@ -386,5 +401,7 @@ CREATE INDEX idx_task_monthly_site_month ON biz.dws_assistant_task_monthly USING
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 INDEX idx_salary_adj_site_month ON biz.salary_adjustments USING btree (site_id, salary_month);
diff --git a/docs/audit/audit_dashboard.md b/docs/audit/audit_dashboard.md
index f07279a..92fdfbe 100644
--- a/docs/audit/audit_dashboard.md
+++ b/docs/audit/audit_dashboard.md
@@ -1,11 +1,12 @@
# 审计一览表
-> 自动生成于 2026-04-06 01:04:43，请勿手动编辑。
+> 自动生成于 2026-04-08 15:09:30，请勿手动编辑。
## 时间线视图
| 日期 | 项目 | 需求摘要 | 变更类型 | 影响模块 | 风险 | 详情 |
|------|------|----------|----------|----------|------|------|
+| 2026-04-08 | 项目级 | 变更审计记录：Fix-13 回滚手动完成 + 广义召回完成机制 | bugfix | 其他 | 低 | [链接](changes/2026-04-08__fix13-recall-events-refactor.md) |
| 2026-04-06 | 项目级 | 变更审计记录：v1 历史清理与 DDL 合并归档 | 清理 | 其他 | 极低 | [链接](changes/2026-04-06__v1-cleanup-ddl-consolidation.md) |
| 2026-04-05 | 项目级 | 变更审计记录：Kiro → Claude Code 全量迁移 | 文档 | 其他 | 低 | [链接](changes/2026-04-05__kiro-to-claude-code-migration.md) |
| 2026-03-31 | 项目级 | 变更审计记录：任务引擎改造 — 参数调优 + 客户级升级/转移 + 任务统计写入 | 功能 | 其他 | 未知 | [链接](changes/2026-03-31__task-engine-overhaul.md) |
@@ -240,6 +241,7 @@
| 日期 | 需求摘要 | 变更类型 | 影响模块 | 风险 | 详情 |
|------|----------|----------|----------|------|------|
+| 2026-04-08 | 变更审计记录：Fix-13 回滚手动完成 + 广义召回完成机制 | bugfix | 其他 | 低 | [链接](changes/2026-04-08__fix13-recall-events-refactor.md) |
| 2026-04-06 | 变更审计记录：v1 历史清理与 DDL 合并归档 | 清理 | 其他 | 极低 | [链接](changes/2026-04-06__v1-cleanup-ddl-consolidation.md) |
| 2026-04-05 | 变更审计记录：Kiro → Claude Code 全量迁移 | 文档 | 其他 | 低 | [链接](changes/2026-04-05__kiro-to-claude-code-migration.md) |
| 2026-03-31 | 变更审计记录：任务引擎改造 — 参数调优 + 客户级升级/转移 + 任务统计写入 | 功能 | 其他 | 未知 | [链接](changes/2026-03-31__task-engine-overhaul.md) |
@@ -370,6 +372,7 @@
| 日期 | 需求摘要 | 变更类型 | 风险 | 详情 |
|------|----------|----------|------|------|
+| 2026-04-08 | 变更审计记录：Fix-13 回滚手动完成 + 广义召回完成机制 | bugfix | 低 | [链接](changes/2026-04-08__fix13-recall-events-refactor.md) |
| 2026-04-06 | 变更审计记录：v1 历史清理与 DDL 合并归档 | 清理 | 极低 | [链接](changes/2026-04-06__v1-cleanup-ddl-consolidation.md) |
| 2026-04-05 | 变更审计记录：Kiro → Claude Code 全量迁移 | 文档 | 低 | [链接](changes/2026-04-05__kiro-to-claude-code-migration.md) |
| 2026-03-31 | 变更审计记录：任务引擎改造 — 参数调优 + 客户级升级/转移 + 任务统计写入 | 功能 | 未知 | [链接](changes/2026-03-31__task-engine-overhaul.md) |
diff --git a/docs/database/ddl/etl_feiqiu__app.sql b/docs/database/ddl/etl_feiqiu__app.sql
index 01d402e..1af6a83 100644
--- a/docs/database/ddl/etl_feiqiu__app.sql
+++ b/docs/database/ddl/etl_feiqiu__app.sql
@@ -439,8 +439,10 @@ SELECT table_fee_log_id,
WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint);
;
+-- CHANGE 2026-04-08 | DISTINCT ON 只取每对 (assistant, member) 最新快照
CREATE OR REPLACE VIEW app.v_dws_assistant_customer_stats AS
-SELECT id,
+SELECT DISTINCT ON (assistant_id, member_id)
+ id,
site_id,
tenant_id,
assistant_id,
@@ -478,7 +480,8 @@ SELECT id,
created_at,
updated_at
FROM dws.dws_assistant_customer_stats
- WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint);
+ WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint)
+ ORDER BY assistant_id, member_id, stat_date DESC;
;
CREATE OR REPLACE VIEW app.v_dws_assistant_daily_detail AS
@@ -976,8 +979,10 @@ SELECT relation_id,
WHERE (site_id = (current_setting('app.current_site_id'::text))::bigint);
;
+-- CHANGE 2026-04-08 | DISTINCT ON 只取每个会员最新快照，避免多 stat_date 行膨胀
CREATE OR REPLACE VIEW app.v_dws_member_consumption_summary AS
-SELECT id,
+SELECT DISTINCT ON (member_id)
+ id,
site_id,
tenant_id,
member_id,
@@ -1024,7 +1029,8 @@ SELECT 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)
+ ORDER BY member_id, stat_date DESC;
;
CREATE OR REPLACE VIEW app.v_dws_member_newconv_index AS
@@ -1042,6 +1048,7 @@ SELECT newconv_id,
t_r,
t_a,
visits_14d,
+ visits_30d,
visits_60d,
visits_total,
spend_30d,
@@ -1167,6 +1174,7 @@ SELECT winback_id,
t_r,
t_a,
visits_14d,
+ visits_30d,
visits_60d,
visits_total,
spend_30d,
diff --git a/docs/database/ddl/etl_feiqiu__dws.sql b/docs/database/ddl/etl_feiqiu__dws.sql
index 70eda57..9b7f3c6 100644
--- a/docs/database/ddl/etl_feiqiu__dws.sql
+++ b/docs/database/ddl/etl_feiqiu__dws.sql
@@ -789,6 +789,7 @@ CREATE TABLE dws.dws_member_newconv_index (
t_r numeric(6,2),
t_a numeric(6,2),
visits_14d integer DEFAULT 0 NOT NULL,
+ visits_30d integer DEFAULT 0 NOT NULL,
visits_60d integer DEFAULT 0 NOT NULL,
visits_total integer DEFAULT 0 NOT NULL,
spend_30d numeric(14,2) DEFAULT 0 NOT NULL,
@@ -907,6 +908,7 @@ CREATE TABLE dws.dws_member_winback_index (
t_r numeric(6,2),
t_a numeric(6,2),
visits_14d integer DEFAULT 0 NOT NULL,
+ visits_30d integer DEFAULT 0 NOT NULL,
visits_60d integer DEFAULT 0 NOT NULL,
visits_total integer DEFAULT 0 NOT NULL,
spend_30d numeric(14,2) DEFAULT 0 NOT NULL,
@@ -1297,6 +1299,7 @@ SELECT dws_member_winback_index.site_id,
dws_member_winback_index.t_r,
dws_member_winback_index.t_a,
dws_member_winback_index.visits_14d,
+ dws_member_winback_index.visits_30d,
dws_member_winback_index.visits_60d,
dws_member_winback_index.visits_total,
dws_member_winback_index.spend_30d,
@@ -1332,6 +1335,7 @@ UNION ALL
dws_member_newconv_index.t_r,
dws_member_newconv_index.t_a,
dws_member_newconv_index.visits_14d,
+ dws_member_newconv_index.visits_30d,
dws_member_newconv_index.visits_60d,
dws_member_newconv_index.visits_total,
dws_member_newconv_index.spend_30d,
diff --git a/docs/database/ddl/zqyy_app__biz.sql b/docs/database/ddl/zqyy_app__biz.sql
index f05f085..a4b00e1 100644
--- a/docs/database/ddl/zqyy_app__biz.sql
+++ b/docs/database/ddl/zqyy_app__biz.sql
@@ -16,6 +16,7 @@ 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;
@@ -153,6 +154,7 @@ 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(),
@@ -161,6 +163,17 @@ CREATE TABLE biz.coach_tasks (
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()
+);
+
CREATE TABLE biz.connectors (
id integer DEFAULT nextval('biz.connectors_id_seq'::regclass) NOT NULL,
connector_key character varying(50) NOT NULL,
@@ -341,6 +354,8 @@ 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.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);
@@ -386,5 +401,7 @@ CREATE INDEX idx_task_monthly_site_month ON biz.dws_assistant_task_monthly USING
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 INDEX idx_salary_adj_site_month ON biz.salary_adjustments USING btree (site_id, salary_month);
diff --git a/docs/prd/2026-04-07__board-audit-fix-plan.md b/docs/prd/2026-04-07__board-audit-fix-plan.md
new file mode 100644
index 0000000..c49f056
--- /dev/null
+++ b/docs/prd/2026-04-07__board-audit-fix-plan.md
@@ -0,0 +1,242 @@
+# 看板全面排查修复计划
+
+> 排查日期：2026-04-07
+> 范围：客户看板（BOARD-2）8 维度 + 助教看板（BOARD-1）4 维度
+> 状态：待实施（新对话执行）
+
+---
+
+## 一、已完成的修复
+
+| # | 问题 | 修复内容 | 文件 |
+|---|------|----------|------|
+| ✅ | SPI 消费口径用 `pay_amount` 而非 `items_sum` | 3 处 settlement_head 查询改为 `items_sum`（DWD 规则 #1） | `apps/etl/connectors/feiqiu/tasks/dws/index/spending_power_index_task.py` |
+| ✅ | 潜力标签阈值 60 但数据范围 0-10 | 阈值 60→6，返回 `[{text, theme}]` 对象数组 | `apps/backend/app/services/fdw_queries.py` `_derive_potential_tags` |
+
+---
+
+## 二、待实施修复（共 10 项）
+
+### P1 — 功能性 Bug
+
+#### Fix-1：客户看板项目筛选崩溃（C-1）
+
+- **问题**：`_project_filter_clause()` 硬编码 `vd.member_id`，但 6/8 维度主表别名不是 `vd`，选择项目筛选时后端 SQL 500
+- **影响维度**：recall / balance / recharge / spend60 / freq60 / loyal
+- **不受影响**：recent（别名 `vd`）、potential（自写子查询）
+- **修复方案**：统一改为独立子查询模式 `member_id IN (SELECT member_id FROM app.v_dws_member_project_tag WHERE category_code = %s AND is_tagged = true)`，不依赖外层别名（参考 potential 维度已有写法）
+- **文件**：`apps/backend/app/services/fdw_queries.py` — `_project_filter_clause()` 函数及 6 个维度查询函数
+
+#### Fix-2：助教看板 task 维度 callback 映射错误（A-3）
+
+- **问题**：callback 统计映射到 `relationship_building`，但业务上"回访"应对应 `follow_up_visit`
+- **修复**：`board_service.py` `_query_coach_tasks()` 中 callback 的 task_type 从 `relationship_building` 改为 `follow_up_visit`
+- **文件**：`apps/backend/app/services/board_service.py`
+
+### P2 — 数据口径错误
+
+#### Fix-3：recall 维度 visits_30d 实为 14d（C-2）
+
+- **问题**：`dws_member_winback_index` 无 `visits_30d` 字段，后端用 `visits_14d` 近似，前端显示"30天到店"
+- **修复**：
+ 1. DDL：`dws.dws_member_winback_index` 加列 `visits_30d INTEGER DEFAULT 0`
+ 2. ETL：WBI 计算任务增加 30 天到店次数统计
+ 3. RLS 视图：`dws.v_dws_member_winback_index` 和 `app.v_dws_member_winback_index` 加新列
+ 4. 后端：查询改用新字段
+ 5. DDL 文档同步更新
+- **文件**：
+ - `db/etl_feiqiu/schemas/dws.sql`（DDL）
+ - `apps/etl/connectors/feiqiu/tasks/dws/index/winback_index_task.py`（ETL）
+ - `db/etl_feiqiu/schemas/app.sql`（RLS 视图）
+ - `apps/backend/app/services/fdw_queries.py`（查询）
+ - `docs/database/ddl/etl_feiqiu__dws.sql` / `etl_feiqiu__app.sql`（DDL 文档）
+
+#### Fix-4：balance 维度月均消耗和可用月数偏差 2 倍（C-3 + C-4）
+
+- **问题**：
+ - `monthlyConsume`：直接用 `consume_amount_60d`（60天总额），标签"月均消耗"应为 `consume_amount_60d / 2`
+ - `availableMonths`：`balance / consume_amount_60d`，应为 `balance / (consume_amount_60d / 2)` 即 `2 * balance / consume_amount_60d`
+- **示例**：余额 49780 / 60天消费 14521 → 当前显示 3.4 个月，实际应 6.9 个月
+- **文件**：`apps/backend/app/services/fdw_queries.py` — `get_customer_board_balance()`
+
+#### Fix-5：freq60 柱状图数据源不一致（C-7）
+
+- **问题**：汇总数据来自 `v_dws_member_consumption_summary`（消费维度），但 8 周柱状图来自 `v_dwd_assistant_service_log`（助教服务维度），口径不一致
+- **修复**：柱状图改为从消费汇总或结算维度获取周数据，与汇总口径一致
+- **文件**：`apps/backend/app/services/fdw_queries.py` — freq60 相关查询
+
+#### Fix-6：助教看板 sv 维度不响应时间筛选（A-4）
+
+- **问题**：函数接收 `start_date/end_date` 但 SQL 未使用，"消耗"始终是固定 60 天
+- **修复**：`sv_consume` 的查询加入 `start_date/end_date` 过滤，使其随时间筛选联动
+- **文件**：`apps/backend/app/services/fdw_queries.py` — `get_coach_sv_data()`
+
+### P3 — 标签/文案修正
+
+#### Fix-7：loyal 维度标签"近60天"→"近90天"
+
+- **问题**：ETL 关系指数实际使用 90 天窗口（`lookback_days: 90`），非 60 天
+- **修复**：下拉选项文本 `最专一 近60天` → `最专一 近90天`
+- **文件**：`apps/miniprogram/miniprogram/pages/board-customer/board-customer.ts` — `DIMENSION_OPTIONS`
+
+#### Fix-8：potential 维度"月均到店"→"近30天到店"
+
+- **问题**：实际是 30 天到店天数（同一天多次只算一天），非"月均到店次数"
+- **位置**：board-customer 页面 → 最大消费潜力 tab → 4 列网格第 2 格
+- **文件**：`apps/miniprogram/miniprogram/pages/board-customer/board-customer.wxml`
+
+#### Fix-9：recharge 维度"充值"→"累计充值"
+
+- **问题**：实际是 `SUM(pay_amount)` 历史累计充值总额，标签仅"充值"易误解为单次
+- **位置**：board-customer 页面 → 最近充值 tab → 4 列网格第 2 格
+- **文件**：`apps/miniprogram/miniprogram/pages/board-customer/board-customer.wxml`
+
+#### Fix-10：freq60 维度标签确认
+
+- 此维度标签"最频繁 近60天"与实际口径一致（`visit_count_60d`），无需修改
+
+---
+
+## 三、DWD 合规检查结果（通过）
+
+| 检查项 | 客户看板 | 助教看板 |
+|--------|----------|----------|
+| consume_money 禁止直接使用 | ✅ 全部走 DWS items_sum | ✅ |
+| settle_type IN (1,3) | ✅ 不直查结算表 | ✅ |
+| DQ-6 会员姓名通过 dim_member | ✅ | ✅ |
+| DQ-7 会员卡通过 dim_member_card_account | ✅ | ✅ |
+| 助教费用拆分 pd/cx | N/A | ✅ |
+
+---
+
+## 四、已知但不修的项
+
+| 项 | 原因 |
+|----|------|
+| A-2：sv 维度客户重复计算 | 业务定义确认：每个助教看"我的客户总余额"，允许跨助教重叠，作为催促消耗的参考值 |
+| A-5：后端 `dim_type` 冗余 | 功能无影响，两端映射一致 |
+
+---
+
+## 五、recall_detector 修复 + 任务统计需求（同期实施）
+
+> 需求确认日期：2026-04-07
+
+### 背景
+
+`biz.coach_tasks` 当前 255 条记录，completed = 0。排查确认：
+- 系统完成逻辑设计正确（`recall_detector.py` 匹配服务记录→标记 completed）
+- 但两个技术问题导致完成检测不可靠
+- 缺少"助教主动标记完成"能力
+- 任务完成统计需要三个维度
+
+### 当前架构（调研结果）
+
+| 服务 | 文件 | 职责 | 调度方式 |
+|------|------|------|----------|
+| `recall_detector` | `app/services/recall_detector.py` | 检测客户到店→标记召回任务完成→生成回访任务 | event: `etl_data_updated`（当前无人触发） |
+| `task_generator` | `app/services/task_generator.py` | 根据 WBI/NCI/RS 指数生成召回/关系维护任务 | cron: `0 4 * * *`（每日凌晨 4 点） |
+
+生成规则（四级漏斗）：
+- `max(WBI, NCI) > 7` → `high_priority_recall`
+- `max(WBI, NCI) > 5` → `priority_recall`
+- `1 < RS < 6` → `relationship_building`
+- 不满足 → 不生成；`session_count > 0` 无任务时保底补充 `relationship_building`
+
+回溯逻辑（已有）：`recall_detector` 检测到新服务记录时，如匹配到活跃的 `follow_up_visit`，关闭旧任务（`superseded_by_new_visit`）并创建新回访。
+
+### Fix-11：recall_detector 增量时序 Bug + 编排顺序
+
+**问题**：`recall_detector` 用 `create_time > last_run_at` 全局增量指针。任务创建与客户到店时序不一致时漏匹配。
+
+**示例时间线**：
+1. 4/5 08:00 — `recall_detector` 运行，`last_run_at = 08:00`
+2. 4/5 14:00 — 客户张三到店，服务记录 `create_time = 14:00`
+3. 4/6 02:00 — `task_generator` 为张三创建召回任务
+4. 4/6 08:00 — `recall_detector` 再次运行，但 `last_run_at` 已更新，张三 4/5 的记录在上轮已扫描过（当时无任务）→ 永远不会重新匹配
+
+**修复方案**：
+1. 废弃 `last_run_at` 增量指针，改为：对所有活跃任务，检查 `dwd_settlement_head` 中是否有 `pay_time > task.created_at` 的结算记录（`settle_type IN (1,3)`），匹配 `(site_id, assistant_id, member_id)`
+2. 合并运行顺序：ETL 完成后，统一编排器按顺序执行：
+ ```
+ ETL 完成 → HTTP callback → 后端编排器:
+ Step 1: recall_detector.run() # 先检查完成（含回溯）
+ Step 2: task_generator.run() # 再生成新任务
+ ```
+3. 保留 `task_generator` 的每日 cron（`0 4 * * *`）作为兜底
+4. 两个服务保持独立文件，仅在调度层串联
+
+**文件**：`apps/backend/app/services/recall_detector.py`、调度编排器
+
+### Fix-12：ETL 完成后自动触发（HTTP callback）
+
+**问题**：`etl_data_updated` 事件无调用方，recall_detector 仅靠手动触发。
+
+**业务影响**：ETL 每小时同步完新的飞球数据后，系统不会自动检查召回完成情况。客户回店后，助教看不到任务完成，必须有人手动在管理后台触发。
+
+**修复方案**：ETL `api_full` pipeline 完成后，通过 HTTP callback 通知后端。
+
+实现：
+1. 后端新增 API：`POST /api/internal/etl-completed`（内部接口，仅限本机调用）
+2. 该接口触发统一编排：`recall_detector.run()` → `task_generator.run()`
+3. ETL orchestrator 在 pipeline 完成后调用此接口
+4. 安全：校验来源 IP 或 shared secret
+
+**文件**：
+- `apps/backend/app/routers/internal.py`（新增）
+- `apps/etl/connectors/feiqiu/orchestration/` — pipeline 完成回调
+- `apps/backend/app/services/trigger_scheduler.py` — 编排逻辑
+
+### Fix-13：任务完成统计三维度
+
+**需求确认**：任务完成分三个统计维度：
+
+| 统计维度 | 触发条件 | 是否需已有任务 | 判定数据源 |
+|----------|----------|---------------|-----------|
+| 召回完成（广义） | 关联客户来店 + 有结算单 | 不需要，只要是 `dws_member_assistant_relation_index` 中的关联客户 | `dwd_settlement_head`（`settle_type IN (1,3)`） |
+| 优先/高优先召回完成 | 已有 `priority_recall` / `high_priority_recall` 任务 + 客户到店 | 需要 | 同上 + `coach_tasks.status = 'completed'` |
+| 回访完成 | 完成 `follow_up_visit` 任务（含回溯完成） | 需要 | `coach_tasks` + 回溯检测 |
+
+关键定义：
+- **"关联客户"**：`dws_member_assistant_relation_index` 中有关系记录的客户
+- **"来店"判定**：`dwd_settlement_head` 中有结算单（`settle_type IN (1,3)`）
+- **时间窗口**：不限间隔，只要来了就算一次
+- **统计时间范围**：全量（任务系统上线至今）
+
+完成类型标记（两种都要记录）：
+
+| 完成类型 | 触发方式 | 当前状态 |
+|----------|----------|----------|
+| 自动完成 | 客户到店，系统匹配结算记录 | 逻辑存在但有 Bug（Fix-11 + Fix-12） |
+| 手动完成 | 助教在小程序中主动标记 | 当前不存在，需新建 |
+
+手动完成需要：
+- 小程序端：任务卡片增加"标记完成"按钮
+- 后端 API：`POST /api/xcx/tasks/{task_id}/complete`，body: `{type: "manual", note?: string}`
+- 数据库：`coach_tasks` 增加 `completion_type` 字段（`auto` / `manual`）
+- `coach_task_history` 增加 `action='manual_completed'`
+
+### Fix-14：助教看板 task 维度展示
+
+**展示位置**：微信小程序 board-coach 页面 task_desc 排序维度
+
+**统计口径**（按助教/按月）：
+- 召回完成数：`coach_task_history` 中 `action='completed'` 的任务数（优先+高优先）
+- 回访完成数：`follow_up_visit` 类型的完成数（含自动+手动+回溯）
+- 广义召回（关联客户来店）：从 `dwd_settlement_head` + 关系表统计
+
+**数据来源**：`biz.coach_tasks` + `biz.coach_task_history` + ETL 关系/结算表
+**时间范围**：全量
+**后续**：更详细的趋势报表作为独立需求
+
+### 实施依赖关系
+
+```
+Fix-11（时序Bug+编排顺序）──┐
+ ├→ Fix-14（看板展示）
+Fix-12（ETL 自动触发）────────┤
+ │
+Fix-13（手动完成+三维度统计）─┘
+```
+
+建议实施顺序：Fix-11 → Fix-12 → Fix-13 → Fix-14
diff --git a/docs/prd/2026-04-08__board-finance-optimization.md b/docs/prd/2026-04-08__board-finance-optimization.md
new file mode 100644
index 0000000..4bf3104
--- /dev/null
+++ b/docs/prd/2026-04-08__board-finance-optimization.md
@@ -0,0 +1,171 @@
+# 财务看板优化 PRD
+
+> 日期：2026-04-08
+> 触发：财务看板数据评估，发现数据失真、展示缺陷、指标缺失
+
+---
+
+## 一、Bug 修复
+
+### 1.1 [P2] 会员卡余额快照不变动
+
+**问题**：`dws_finance_recharge_summary` 表中 `cash_card_balance`（62,674）和 `total_card_balance`（67,760）连续多日完全相同。当前实际余额约 118K，ETL 快照值 67K，数字严重失真。
+
+**根因**（已调研确认）：
+
+`finance_recharge_task.py` 中：
+1. `_extract_card_balances()` 只调用一次（传入 `end_date`），所有日期复用同一快照（第 64、89 行）
+2. SQL 查询只取 `scd2_is_current = 1`，`stat_date` 参数传入但未使用（第 197-216 行）
+3. 赠送卡余额同样受影响
+
+**DWD 维度表验证**（已确认可用）：
+- `dim_member_card_account` SCD2 版本充足（主卡类 55,526 个版本，覆盖 53 天）
+- 按日有明确余额变化（4/6: ¥3,745 → 4/7: ¥9,291 → 4/8: ¥1,587）
+- 可通过 `scd2_start_time <= stat_date AND scd2_end_time > stat_date` 做 as-of 查询
+
+**修复方案**：
+- `_extract_card_balances()` 改为按日遍历，每天查该日生效的 SCD2 版本
+- `transform()` 中按 `stat_date` 查表，不再共用同一快照
+
+**状态**：待实施
+
+### 1.2 [P2] 充值首充/续费笔数全为 0
+
+**问题**：`dws_finance_daily_summary` 中 `first_recharge_count` 和 `renewal_count` 全为 0，但 `recharge_count` 有值。
+
+**DWD 验证**（已确认源数据正确）：
+- `dwd_recharge_order.is_first` 字段完好
+- 3 月：首充 6 笔 ¥14,996 / 续费 43 笔 ¥204,998
+- ETL 聚合时未读取 `is_first` 字段进行分类统计
+
+**修复方案**：`finance_recharge_task.py` 中按 `is_first` 分组统计，写入 `first_recharge_count` / `renewal_count`
+
+**状态**：待实施
+
+---
+
+## 二、文案优化
+
+### 2.1 "储值卡结算冲销" → "储值卡消费抵扣"
+
+**位置**：
+- `board_service.py:984` — 空降级值
+- `board_service.py:1023` — 正常取值
+- `fdw_queries.py:2898` — 查询层
+
+**状态**：待实施
+
+---
+
+## 三、新增指标
+
+### 3.1 经营一览 — 补充效率指标
+
+在经营一览板块"实收流水"数据下方新增一行，3 个指标横向排列：
+
+```
+┌──────────┬──────────┬──────────┐
+│ 开台数 │ 客单价 │ 日均额 │
+│ 3,262 │ ¥128.7 │ ¥13,991 │
+└──────────┴──────────┴──────────┘
+```
+
+#### 计算方案
+
+> 注意：客单价和日均额的分子使用**确认收入**（发生额-优惠后的实际入账），与所在位置"实收流水"语境一致。
+
+| 指标 | 公式 | 数据来源 | 说明 |
+|---|---|---|---|
+| 开台数 | `SUM(order_count)` | `dws_finance_daily_summary.order_count` | 日期范围内结算单总数 |
+| 客单价 | `SUM(confirmed_income) / SUM(order_count)` | 同上 | 确认收入 / 开台数 |
+| 日均额 | `SUM(confirmed_income) / COUNT(DISTINCT stat_date)` | 同上 | 确认收入 / 营业天数 |
+
+3 月实测值：开台 3,262 | 客单价 ¥128.7 | 日均额 ¥13,991
+
+#### 展示方案
+
+- 位置：经营一览板块"实收流水"数据下方
+- 样式：3 列等宽卡片，灰色标签 + 黑色数值
+- 环比：支持（compare=1 时显示环比变化）
+- 区域过滤：area!=all 时，从 `dws_finance_area_daily` 对应 area_code 取 `order_count` + `confirmed_income`
+
+#### 实现影响
+
+- **后端**：`fdw_queries.get_finance_overview()` 追加返回 `order_count`；`board_service._build_overview()` 计算 `avg_per_order` 和 `avg_daily`
+- **前端**：`board-finance.wxml` 经营一览实收流水下方加一行三列
+
+### 3.2 预收资产 — 补充充值笔数
+
+在储值卡充值实收行追加笔数信息：
+
+```
+储值卡充值实收 ¥222,994 50笔
+```
+
+> 首充/续费区分待 Bug 1.2 修复后展开为 `50笔（首充6 / 续费44）`
+
+#### 计算方案
+
+| 指标 | 公式 | 数据来源 |
+|---|---|---|
+| 充值笔数 | `SUM(recharge_count)` | `dws_finance_recharge_summary.recharge_count` |
+
+#### 展示方案
+
+- 位置：储值卡充值实收金额右侧
+- 格式：`50笔`
+- 环比：暂不做
+
+### 3.3 应计收入 — 优惠扣减增加占比
+
+每个优惠项显示金额 + 占总优惠的百分比：
+
+```
+团购优惠 ¥48,231 23.6%
+会员折扣 ¥89,102 43.6%
+手动调整 ¥31,540 15.4%
+赠送卡抵扣 ¥28,230 13.8%
+其他优惠 ¥7,209 3.5%
+────────────────────────
+总优惠 ¥204,312 100%
+```
+
+#### 计算方案
+
+| 指标 | 公式 |
+|---|---|
+| 各项占比 | `该项金额 / discount_total * 100` |
+
+#### 展示方案
+
+- 位置：每个优惠项金额右侧
+- 格式：`23.6%`，灰色小字
+- 仅在总优惠 > 0 时显示占比
+
+### 3.4 团购展示优化
+
+#### 背景
+
+团购数据上传时已上传的是**结算金额**（扣除平台各种扣费后的实际回款），因此不需要额外展示手续费和面值拆分。
+
+#### 方案
+
+将现金流入板块中"团购平台"标签改为"团购结算"，明确表达该金额是平台结算后到账金额，避免与核销面值混淆。
+
+**位置**：后端 `board_service.py` / `fdw_queries.py` 中 cashflow 板块的团购项 label
+
+**状态**：待实施
+
+---
+
+## 四、实施优先级
+
+| 优先级 | 事项 | 工作量 |
+|---|---|---|
+| P1 | 文案优化（储值卡消费抵扣） | 小 |
+| P1 | 经营一览补充效率指标（开台数/客单价/日均额） | 中 |
+| P1 | 团购标签改为"团购结算" | 小 |
+| P2 | 优惠占比展示 | 小 |
+| P2 | 充值笔数展示 | 小 |
+| P2 | 卡余额快照修复（Bug 1.1） | 中 |
+| P2 | 充值首充/续费识别修复（Bug 1.2） | 小 |
diff --git a/start-admin.bat b/start-admin.bat
new file mode 100644
index 0000000..d7cdb71
--- /dev/null
+++ b/start-admin.bat
@@ -0,0 +1,12 @@
+@echo off
+chcp 65001 >nul 2>&1
+:: CHANGE 2026-03-07 | 注入 NEOZQYY_LAUNCH_DIR：%~dp0 不穿透 junction，
+:: ps1 脚本用它定位项目根目录，避免 PowerShell 路径解析到 D 盘
+set "NEOZQYY_LAUNCH_DIR=%~dp0"
+:: 拉起 ps1 脚本（优先 pwsh 7，回退 powershell 5.1）
+where pwsh >nul 2>&1
+if %errorlevel%==0 (
+ start "NeoZQYY Launcher" pwsh -ExecutionPolicy Bypass -File "%~dp0scripts\ops\start-admin.ps1"
+) else (
+ start "NeoZQYY Launcher" powershell -ExecutionPolicy Bypass -File "%~dp0scripts\ops\start-admin.ps1"
+)
diff --git a/uv.lock b/uv.lock
index 991f8eb..73683d8 100644
--- a/uv.lock
+++ b/uv.lock
@@ -584,6 +584,7 @@ name = "etl-feiqiu"
version = "0.1.0"
source = { virtual = "apps/etl/connectors/feiqiu" }
dependencies = [
+ { name = "httpx" },
{ name = "neozqyy-shared" },
{ name = "openpyxl" },
{ name = "psycopg2-binary" },
@@ -595,6 +596,7 @@ dependencies = [
[package.metadata]
requires-dist = [
+ { name = "httpx", specifier = ">=0.24.0" },
{ name = "neozqyy-shared", editable = "packages/shared" },
{ name = "openpyxl", specifier = ">=3.1.0" },
{ name = "psycopg2-binary", specifier = ">=2.9.0" },