| name | shengxintou-bi-rules |
| description | 省心投 BI 的 AI 知识与数据助手（双模式）。开发模式：对本项目改代码/修 Bug/加功能/理解架构/核验业务口径时加载，提供产品边界、业务口径、跨端契约、验证与发布红线；数据助手模式：业务人员或在非项目目录时，基于本地省心投软件原始库表做数据问答、查询、排查与临时图表时加载，规范只读红线、库表定位、口径与输出目录，避免破坏已安装软件。 |
| metadata | {"author":"省心投 BI","license":"MIT"} |
省心投 BI — 知识与数据助手 Skill
本 Skill 有两种用途：开发省心投 BI 项目（沿用仓库开发规则体系），以及充当省心投的业务数据助手（在已安装软件的电脑上，基于原始库表做查询、排查、问答和临时图表）。进入任务后第一步必须判定所处模式，再决定可写范围与约束。
第一步：判定模式
- 当前工作目录 / 上下文中存在 项目仓库 特征（有
AGENTS.md / CLAUDE.md、app.py、config.py、docs/rules/）→ 模式 A（开发模式）。
- 否则（尤其当用户想用本 Skill 分析已安装的省心投桌面软件、排查小问题或做数据问答时）→ 模式 B（数据助手模式）。
模式判定决定了「能不能改软件文件夹下的代码」。数据助手模式一律只能读，不能动软件目录代码。
模式 A：开发模式（在项目仓库内）
这是原「开发规则文档体系」用法。references/ 是这个模式的内嵌规则快照（复制自仓库，属快照）；若同时在仓库内工作，docs/rules/ 与根级规则才是实时权威源，优先读仓库原文件。
触发条件（何时作为开发模式）
- 任何要对 省心投 BI 项目进行的开发 / 改动：改代码、修 Bug、加功能、重构、理解架构、核对数据口径、跑验证脚本。
- 使用 不支持
AGENTS.md / CLAUDE.md 的 AI Agent（如 Workbuddy、豆包）开发本项目时：将它们作为规则加载入口，进入项目上下文后即应在改动前加载本 Skill。
- 对 支持
AGENTS.md 的 Agent（如 Codex、Claude Code、TRAE）本项目通常已自带文档体系，可跳过本 Skill，直接使用仓库根级规则与 docs/rules/。
规则优先级
- 当前会话的系统、开发者和用户明确指令。
- 目标文件所在目录中更深层的
AGENTS.md（若存在）。
- 根级
AGENTS.md / CLAUDE.md（本 Skill 已内嵌其等价内容）。
docs/rules/ 中与任务相关的专题规则。README.md、部署文档和其他当前文档。docs/_archive/ 与 docs/*_legacy.md 仅供历史查阅，不作实现依据。
文档与实现冲突时，先以当前代码、构建配置、测试和 version.json 交叉验证，再修正文档；不要照搬历史说明。
按任务读哪条规则（必读索引）
| 任务 | 先读 | 关键实现入口 |
|---|
| 理解架构、增加模块/路由 | overview.md | app.py、backend/routes/、frontend-react/src/router/index.tsx |
| 修改漏斗、开户、资产、主播、对账 | business-invariants.md | backend/routes/data/{cost_analysis,leads}.py、backend/routes/reports/app_market.py |
| 修改模型、导入、API、SQLite、WebDAV | backend.md | backend/models_v2.py、backend/processors/v2/raw_import.py、backend/routes/ |
| 修改 React、组件、筛选、类型、样式 | frontend.md | frontend-react/src/ |
| 跨端兼容（API/路由/featureFlag/SQL 同步） | cross-platform.md | mobileRouteHandler.ts、config/features.ts、scripts/check_*.py |
| 测试、提交、CI、发布 | testing-and-delivery.md | tests/、scripts/、.github/ |
| 打包、工具链、依赖工具位置 | toolchain.md | scripts/build-installer.ps1、android/scripts/post-sync-patch.ps1、tools/ |
| 数据安全红线：打包/发布/数据库初始化 | security-data-leak.md | WebDAV 同步、空库生成、Release 资产 |
| 开发新需求 | workflows/feature.md + templates/tech-spec.md | — |
| 修复 Bug | workflows/bugfix.md | 相关回归测试目录 |
提示：以上文件在仓库内读 docs/rules/<对应>.md；不在仓库时读本 Skill 的 references/docs-rules/<对应>.md 快照。数据助手模式（模式 B）另见下文专门的「数据口径」小节。
单一权威源（谁说了算）
| 信息 | 权威源 | 规则 |
|---|
| 当前版本/日期/版本号规则/changelog | version.json | 别处只引用，不复制 |
| 产品定位/安装/使用 | README.md | 规则只留任务所需摘要 |
| 会话入口与最高频红线 | AGENTS.md/CLAUDE.md/.workbuddy/memory/MEMORY.md | 三份必须字节一致 |
| 当前业务与工程规则 | docs/rules/ | 只写当前有效状态 |
| 主播类型映射 | backend/config/anchor_live_types.json | 启动同步，别直接改库 |
| API 数据导入类型 | backend/routes/upload.py::DATA_TYPES | 前端常量跟随 |
| 业务表与中文列名 | backend/models_v2.py 及上游源表 | 不为迎合前端改名 |
| 前端生成 API 类型 | Orval 生成 | 禁止手改 types/api.ts |
产品边界（最容易越界的红线）
省心投 BI 是券商财富管理场景的广告投放与开户转化分析平台，职责严格限制为：
上游 ETL 文件 -> 原样入库 -> SQL 查询/聚合 -> React 报表展示
- 上游 ETL 负责业务 mapping、清洗、归一化、字段补全、漏斗预计算和口径修正。
- 本项目导入层只做格式安全处理（空值、日期、布尔、超长 ID）。
- 查询层可 SELECT/SUM/GROUP BY/分页/兼容派生字段，不新增下游业务口径补丁。
- 新数据源必须走
backend/processors/v2/raw_import.py；旧 v1 上传类型返回 410 Gone，禁止恢复旧 processor/旧表。
最高风险业务不变式（改口径前必读详情）
- 新开户优先：新开户及引进资产是主产出；存量客户/存量资产单独作辅助，不能混算。
- 内容平台非存量条件：
是否为存量客户 == 0 OR IS NULL；存量在有效线索之后剔除。
- 应用市场真实获客：强制
渠道类型 = 互联网引流，统一用 _funnel_filters。
- 禁止漏斗变平：不能用
WHERE 是否新开户 == 1 过滤整条应用市场漏斗；“新开户”是“开户成功”之后的阶段。
- 应用市场「开户成功」阶段必须用
是否创建完资金账号（不是 是否开户成功），否则新开户人数会冒过开户成功人数。
- 双链路（加微/APP下载）不可混算：APP激活 ≈ 线索、APP激活成本 ≈ 线索成本，列序紧贴线索。
- 复合来源线索均分：同名主播跨平台聚合时，源头含多个主播的线索需按匹配主播数均分所有指标，避免重复计数。
- 主播映射：
anchor_live_types.json 是权威源，库表只是缓存；不直接改库维护。
- 青鸟导入：
qingniao_leads 按批次 append 是明确例外，其他 v2 类型默认 replace；conversion_appmarket/vendor_daily 按日期分区替换（保留 2026-06-30 之前历史，只重写 07-01 起，常量 APPMARKET_CONV_REPLACE_FROM/VENDOR_DAILY_REPLACE_FROM）。
- 代理商映射：来自
dim_account 全称/简称/字母简称；不要恢复已删除的 dim_vendor。
- 数据安全红线：APK/EXE/frontend-dist.zip 一律只内置表结构空库，真实业务库（含手机号/资产/创收）禁止进入任何分发产物与 Release 资产，仅由用户 WebDAV 从坚果云拉取；历史含数据 Release 资产必须清理。
docs/rules/security-data-leak.md 是打包/发布/数据库初始化前必读。
架构地图（简）
后端：app.py（Flask/蓝图/SPA/中间件）+ config.py + backend/（models、models_v2、processors/v2/raw_import.py、routes/{data,reports,system}、utils）+ server_entry.py（PyInstaller 打包入口）。
前端：frontend-react/src/（router/layouts/pages/components/config/services/stores/types/styles/utils）。API 前缀 /api/v1。
四端单一代码库、仅配置不同：开发版（Web+SQLite）、桌面 Electron（PG/Supabase+AUTH_ENABLED=true）、移动端 Android（Capacitor SQLite）、PWA（IndexedDB+sql.js）。生产时 Flask 托管 frontend-react/dist/。
修改红线（做任何改动前确认）
- 先读后写：改前读完整目标文件、调用方和同类实现；只改需求范围、修根因，不夹带无关重构。
- 不改
models_v2.py 中文列名来迎合前端；不新增下游 mapping/归一化 processor。
- 不手改生成文件；API 类型走
npm run generate:api。
- 报表头统一
MetricCard + MetricSection；筛选器统一 FilterBar；数据源/端点/口径放 ReportFooter；Excel 脏文本 sanitizeText()。
- Flask 后台线程用显式 application context，不依赖继承
current_app。
- WebDAV 网络层错误
502 + UPSTREAM_UNAVAILABLE；其他列表失败 500 + LIST_FAILED。
验证（最小 → 按风险扩大）
| 改动 | 最小验证 |
|---|
| 规则架构/核心文件 | python scripts/check_rule_architecture.py |
| Python 后端 | python -m unittest discover -s tests/api -v |
| 前端 TS/TSX | cd frontend-react && npm run typecheck |
| 前端页面/组件/样式 | typecheck + npm run build |
| lazy 路由 | npm run test:smoke |
| 跨端契约 | python scripts/check_api_contract.py + check_route_drift.py + check_feature_flags.py + check_mobile_routes_coverage.py |
| 发版前 | scripts/run-full-tests.bat |
使用方式（开发模式工作逻辑）
- 按「按任务读哪条规则」表定位必读专题；优先读仓库
docs/rules/<对应>.md（实时），仓库不可用时读 references/docs-rules/ 快照。
- 涉及业务口径/跨端契约时，务必先读
business-invariants.md 与 cross-platform.md，再动手。
- 收尾跑对应最小验证 + 提交前
scripts/pre-commit-check.bat；不擅自 commit/push/发版。
模式 B：数据助手模式（不在项目仓库内，面向已安装软件的原始库表）
本模式服务业务人员：基于本地省心投软件的实际数据，做小问题排查、数据问答、查询和临时图表。本模式不是在写项目代码，绝不能破坏已安装的软件。
B1. 第一步：确认软件目录与原始库表
- 确认已安装/运行的省心投软件目录（例如本机
D:\Program Files\shengxintou\shengxintou-bi-desktop）。可通过询问用户、或用系统搜索 / 常见安装路径探测。
- 数据库通常在用户数据目录而非安装目录（桌面版 frozen 构建）：默认
%APPDATA%\省心投 BI\database\shengxintou.db（即环境变量 APPDATA 下 省心投 BI\database\shengxintou.db，可用 SHENGXINTOU_USER_DATA_DIR 覆盖）。安装目录只含程序代码与只读 resources/，一般没有实时业务库。
- 允许的定位顺序：
- 环境变量
SHENGXINTOU_USER_DATA_DIR 指向目录下的 database/shengxintou.db；
%APPDATA%\省心投 BI\database\shengxintou.db；- 用户自定
DATABASE_PATH 指向的路径；
- 若
.env / 环境变量配了 DATABASE_URL=postgresql+psycopg://...（Supabase PG），则数据在云端 PG，需另行告知用户走 WebDAV 同步到本地 SQLite 再分析，本模式不直连云库。
- 拿到库后用只读方式打开并
SELECT name FROM sqlite_master WHERE type='table' 自省表与列结构（表列含中文，与 models_v2.py 及上游源表 1:1 对齐）。
B2. 只读红线（避免破坏软件）
- 只允许 SELECT 查询；禁止对实时业务库执行 UPDATE / INSERT / DELETE / DROP / ALTER / VACUUM 等写操作。优先用只读连接打开（如 SQLite URI
file:...?mode=ro 或 SQLAlchemy 只读 URI）。
- 不得修改、新建、删除软件仓库目录下的任何代码/配置文件（
resources/ 只读区、server.exe、.env 等一律不动）。
- 需要往库里写临时表/中间结果时，不要写进业务库，改为在输出目录生成独立 SQLite 文件，或用 SELECT 派生直接得到结果。
- 若遇到「软件正在运行」占用了数据库文件，不要强制改锁，改为复制该 DB 到
./.技能临时分析 后用副本分析（保持原件只读）。
B3. 输出目录约定（所有产物放这里）
- 所有产物（查询 SQL、结果 CSV/JSON、图表 PNG/HTML、分析说明 Markdown）统一放到：
<软件目录>/.技能临时分析/。
- 若
<软件目录> 不可写（例如 Program Files 权限不足），回退到 $HOME/.省心投技能临时分析/ 并明确告知用户实际存放位置。
- 每次分析按文件名/时间组织（如
查询结果_2026-08-26.csv），不覆盖软件原始文件；最后用一句话汇报产物所在路径清单。
B4. 数据口径（回答业务问题必须遵守，否则数字是错的）
- 新开户优先：新开户及引进资产是主产出；存量客户/存量资产单独作辅助，不能混算。报告口径一律「非存量」=
是否为存量客户 == 0 OR IS NULL（内容平台在「有效线索」之后剔除存量）。
- 应用市场：只统计
渠道类型 = 互联网引流 的真实获客；「开户成功」阶段用 是否创建完资金账号；不要用 是否新开户=1 过滤整条漏斗（会变平）；新增资产只累计 是否新开户=1 行。
- 双链路不可混算：加微链路主指标=线索数、APP下载链路主指标=APP激活人数（APP激活≈线索、APP激活成本≈线索成本），列序「线索→APP激活→开户」。
- 复合来源线索：画面含多个主播的线索，聚合各指标时按匹配主播数均分，避免虚增。
- 主播映射：JSON 是权威源，库表只是缓存；查询展示以
dim_anchor_live_type 已同步的映射为准。
- 回答时标注数值口径与「近似/估算」，别把存量当新开户、别把加微和APP激活混着说。
B5. 敏感数据处理
- 库内含客户手机号、资产、创收等敏感字段。不要把整表/大批量原始手机号或资产明细原样导出到分析产物；优先返回聚合、分桶、去标识结果。
- 图表和表格中如需展示，做脱敏/聚合；同样遵守
security-data-leak.md：分析产物不与仓库分发、不打包进任何发布物。
- 面向业务人员的问答以「概括性结论 + 关键数字 + 口径说明」为主，不倾倒原始明细。
B6. 数据助手模式工作流程
- 判定模式为 B → 确认软件目录 → 定位并只读打开原始库 →
sqlite_master 自省结构。
- 与用户对齐想回答的问题/要排查的现象；按 B4 口径设计 SELECT。
- 查询结果写入
<软件目录>/.技能临时分析/；需要看趋势/对比时生成临时图表（PNG/HTML）到该目录。
- 汇报结论、口径说明与产物路径；提醒敏感数据处理方式。全程不触碰软件目录代码与实时库写操作。
维护提示：本文件在 skills/shengxintou-bi-rules/SKILL.md；references/ 是从 docs/rules/ + 根 AGENTS.md/CLAUDE.md 复制的快照。根级规则或 docs/rules/ 调整时，需把根级规则与 docs/rules/ 重新复制到 references/，保持分发版与权威源一致。
