csctalon/AGENTS.md

全局行为约束（00-global）

性质：元需求（META）—— 仓库级约束源，约束所有在本仓库内执行的 AI 任务

本文件对应"AI 协作治理规范" 4.1 铁律与 4.2 00-global.md，作为仓库级指令被 AI 助手自动加载。 适用范围：所有在本仓库内执行的 AI 代码生成 / 文档 / 审查任务。 文档性质索引见 docs/README.md §六。

身份

你是本项目的 AI 开发助手。技术栈：

• 前端：Vue 3 + Vite 5 + Element Plus（SPA，75+ 页面组件）
• 后端：FastAPI + SQLAlchemy 2.0 + Gunicorn（单 worker，保证互斥锁有效）
• 数据库：PostgreSQL 15（86 张表，含 SCD Type 2 历史表）
• 缓存/队列：Redis 7
• 数据采集：Playwright + ddddocr（浏览器自动化 + OCR 自动登录）
• 迁移：Alembic（单一 head）
• 部署：Docker Compose（db / redis / backend / web 四服务）

绝对禁止

1. 禁止在生产代码中使用 console.log（前端）或裸 print（后端），必须使用项目封装的 logger（后端 app/core 下各模块的 logging logger）。
   • 唯一例外：console.log('[TODO:...]') 形式的显式 TODO 标记，可保留但必须带 [TODO: 前缀。
2. 禁止无参数化地拼接 SQL。允许 text() + 绑定参数（如 db.execute(text(...), {...})），禁止字符串 f"...{var}..." 直接拼进 SQL。
3. 禁止在代码中硬编码密码、密钥、内网 IP、数据库账号，必须走环境变量（.env / settings）。 连带：禁止让"库名"的默认值指向真实库，也禁止让模式与库名可以不一致。
   • 库名必须与运行模式自洽（APP_MODE=dev → 库名以 _dev 结尾；test → _test； prod → 不含 _dev/_test）。启动期会硬校验，不一致即拒绝启动。
   • 破坏性操作（DELETE/TRUNCATE/DROP/批量 UPDATE）必须先过 app.core.db_guard.assert_safe_to_destroy()；操作真实库须显式传 allow_real_db=True（脚本参数为 --allow-real-db），禁止用环境变量绕过。
   • 新写 scripts/** 必须经 scripts/_bootstrap.py 的 bootstrap() 进入， 不得自己拼 POSTGRES_DB 环境变量（那是两份定义，必漏）。
   • 全文见 docs/arch/A-20260922-001-运行模式框架与配置分离.md。

   为什么不单列一条：本条与"禁止硬编码 DB 账号"是同一个风险面—— 把库名默认成生产库名，等价于把连接信息硬编码到代码里。 现有 13 条已足够长，另开一条会稀释权威性（参见 docs/standards/跨项目经验迁移指南.md "铁律只列最重要的，避免冗长失效"）。

4. 禁止擅自修改已锁定的架构文档（docs/arch/ 下标记为 LOCKED 的文件），修改必须先走人工审核流程。
5. 禁止删除或绕过 docs/standards/数据时间字段使用规范.md 中规定的时区换算（AT TIME ZONE 'Asia/Shanghai'）与 SYS/system 系统操作人排除标准。
6. 禁止绕过 Alembic 直接改表结构；表结构变更必须新增 migration 版本。
7. 禁止「无设计说明」的界面改动（见 docs/standards/界面设计说明规范.md）。 新增/改造任何前端界面（页面 / 标签页 / 区块），必须先写清「替谁回答什么问题、 为什么这样组织、不做什么及原因」，并按该规范三层落地（代码注释 + 页面可见说明 + 审查清单）。 禁止「顺手加一张图 / 多堆一个 tab」式的无意图改动。
8. 禁止绕过后端响应格式规范（见 docs/standards/error-code.md）。 成功返回 {code:0, data, message}，错误一律走 HTTPException，禁止自定义裸 dict。
9. 禁止绕过 docs/standards/数据采集合并去重机制说明.md 规定的去重键。 该规范约束所有采集通道（投诉指纹 / 手动退款复合键 / 各 data_type 唯一键）； 新增采集源必须先确认去重键，否则会产生重复入库。
10. 禁止擅自变更 docs/standards/投诉渠道口径与对账说明.md 中的渠道口径权威定义 （内部 / 商户号 / 外部投诉的归类判据）。口径是统计的根，改动会影响全部投诉数字， 必须走人工审核 + 回归验证。
11. 禁止绕开 docs/standards/数据源接入与缓存加速规范.md 的缓存铁律： 新增数据源 / 看板接口时，写入后必须失效对应缓存 pattern，Redis key 必须逐字符对齐。
12. 禁止「无数据说明 / 不可下钻」的看板卡片（见 docs/standards/看板卡片数据说明与下钻规范.md）。 任何看板卡片必须同时做到：① 有 ⓘ 数据说明（来源 / 口径 / 时点，并写明"空"的含义）； ② 可下钻且带时间窗口与筛选条件。确不下钻的须在代码注释 + 页面 ⓘ 显式声明理由。 禁止「点了没反应」的数字，禁止跳到空白明细页让使用者自己再筛一遍。
13. 禁止绕过 docs/standards/数据源命名与分组规范.md 的数据源命名与分组元规则：
    • 分组顺序唯一来源是 data_source_registry.CATEGORY_ORDER，前端不得再定义一份 （两份定义必然漂移，同 A-20260910-004 菜单漂移）；组内顺序由服务端 sort_order 决定。
    • code / table_name / name_cn 必须一一对应，name_cn 全树唯一且必须带域前缀 （前缀·中文语义，禁止出现 code 原文）；例外须在该规范 §3.5 登记。
    • 数据已停用或口径易误用（如 E 路对账基准）→ 必须在显示名中标注， 只写 description 不算（树上看到名字的人不会点开描述）。
    • 同一张表禁止注册两个 code（统计口径分裂）；需要第二入口请用投影 （DATA_SOURCE_PROJECTIONS），且投影必须声明真身分组与名称，否则视为 「无声明重复展示」违规。
14. 禁止绕过《仓库入库规范》的文件入库分类纪律（见 docs/standards/仓库入库规范.md，META）：
    • C5 密钥凭证（.env / token / 私钥 / 真实密码）与 C6 PII/业务数据（含真实手机号/单号/SN 的语料、xlsx/csv/pkl 导出、01样本数据/）严禁入 git，由 gitleaks + CI 兜底 （与第 3 条互补：第 3 条管"代码内不许硬编码"，本条管"什么文件根本不许入库"）。
    • 一次性任务现场（临时脚本 / 模型 raw 输出 / 探针 / 冻结语料）落本地 workdata/（gitignore）， 不入 git；任务收尾把结论提炼进 docs/reports/，耐用脚本证明可复用后才进 scripts/。
    • 点号 ≠ 不入库：.gitea/ 等协作配置必须入库；__pycache__ / .venv / node_modules 等缓存运行时忽略。唯一判据：别人 clone 后是否需要它才能跑起来 / 理解系统。
15. 禁止绕过《退款五路数据标准与采纳规则》的采纳口径（见 docs/standards/退款五路数据标准与采纳规则.md，META）：
    • 退款五路（A 线上直退 / B 钱包流水 / C 闪猫 / D 手动 / E 企微记录）统计一律读 std_* 标准表 （std_refund_online / std_wallet_flow / std_refund_shanmao / std_refund_manual / std_refund_record）， 禁止在查询侧散落复刻采纳条件（失败/冻结关键词、质量状态过滤等已由采纳作业在表层固化）。
    • ods 原始表只同步不治理：采集 upsert 不得覆盖采纳标识四列（adopt_state / adopt_reason / adopt_rule_ver / adopted_at）；质量治理入口 = 人工覆盖 API（adoption_overrides），禁止直接改原始数据。
    • 采纳规则变更必须升版 ADOPT_RULE_VER 并同步修订口径文档；全状态/全方式语义例外 （挽回漏斗、状态分布、工作量统计、导出原始明细、链路台账、设备档案、对账勾稽） 一律读 std_*_all 全量镜像视图（ods 同构透传），业务代码禁止直读 ods； ods 仅剩采集写入、采纳作业读取、质量治理标记三个本职消费（#334）。
    • 企业商户维度统一经 dim_device_merchant（as-of 分段维表）回填，禁止各处自行实现商户回落逻辑。

输出风格

1. 代码块必须带注释说明关键逻辑（尤其涉及时间换算、金额单位、事务回滚处）。
2. 修改现有文件时，必须先说明改动意图（涉及哪几个文件、改了什么），禁止静默大改。
3. 遇到不确定的需求，必须停下来提问，禁止猜测实现。
4. 金额字段一律使用定点数（Decimal），禁止二进制浮点进入金额存储与计算。 现行口径（#217 拍板方案 C′，2026-10-08）：
   • DB 层 Numeric(12,2)/(12,4)（元单位）不变；ORM 注解 Mapped[Decimal | None]；
   • 采集写入经 upsert._core._to_decimal；计算路径用 analytics._core.D() 定点化；
   • 出参边界（JSON API / Excel 导出 / JSONB 落库）允许 float(...) 一次性表示层转换， 对外契约保持 JSON number（元）不变；
   • 例外登记（保留 float，非金额语义）：merchant_refund.rate（费率 Numeric(8,4)）、 device_flow_usage.flow_gb（流量 GB）。新增金额列必须走 Decimal，例外须在此登记。

工具使用

1. 使用文件系统 / 读写工具前，必须先确认目标文件路径存在。
2. 执行任何会改动数据的命令前，先输出将要执行的命令，等待确认。
3. 数据库操作默认使用只读账号（如 db 容器内的查询），除非明确获得授权。
4. 运行测试 / lint：优先使用项目既有命令（如 ruff、pytest），不要擅自引入新工具链。

界面设计纪律（强制）

全文见 docs/standards/界面设计说明规范.md。核心铁律： 说不清「替谁解决什么问题」的界面，不许开工。

1. 五要素必填：目的（替谁/答何决策）· 逻辑（为何这样组织）· 口径（数据判据 + 文档指针）· 取舍（不做什么及原因） · 工单（issue 号 + 设计文档）。
2. 三层落地，缺一即未完成：
   • ① 代码层：界面文件头部 设计说明（Design Rationale） 注释块；
   • ② 页面层：使用者可见的 ⓘ 气泡 或「设计说明」抽屉（必须含「取舍」段）；
   • ③ 审查层：docs/standards/review-checklist.md 对应检查项通过。
3. 禁止无意图改动：不得「顺手加一张图」「多堆一个 tab」；每个图表必须指向一个动作。
4. 可控指标前置：优先展示可控指标（如升级率），而非只有后果指标（如总量/金额）。
5. 禁止重复展示：同一指标全站应有唯一「真身」，其它位置为「投影」； 投影必须在设计说明中声明，并注明真身位置。
6. 删掉无损判据：若某界面被删掉后没有任何人的任何决定会改变，则它属于「秀好看」，应删。
7. 存量不追溯，改动即补齐：未改造的存量界面不强制追溯；但谁改动、谁补齐。
8. 看板卡片双强制（见 docs/standards/看板卡片数据说明与下钻规范.md）： 任何看板卡片必须有数据说明（来源/口径/时点 + "空"的含义）且可下钻 （带当前时间窗口与筛选条件）；不可下钻的须显式声明理由。详见该规范全文。
9. 数据源命名与分组（见 docs/standards/数据源命名与分组规范.md）： 数据查看树的每一项必须让人看出「这是哪一类/哪一路」；分组顺序与组内顺序均由服务端 单一来源决定；停用与易误用口径必须在显示名标注；同表第二入口只能走投影 且必须声明真身位置。详见「绝对禁止」第 13 条。

工单纪律（强制）

1. 所有任务必须先建工单，再动手（见 docs/standards/issue-workflow.md）。
2. 提交信息必须携带 #issue号，否则关联不上、无法审计。
3. 关闭工单前必须先写「关闭凭证核验」评论：
   • 标题固定 ## 关闭凭证核验 (YYYY-MM-DD)
   • 用表格逐条对应正文的「验收标准 / 关闭条件」，每条给出可复现的核验方式 （测试用例名 / commit sha / 实测命令），禁止写「已测试通过」这类不可验证的话
   • 同时把正文里对应的 - [ ] 勾成 - [x]
   • 批量关闭多张工单时，每张各写一条自己的凭证评论
   • 确属降级接受的，写 结论: 以 <理由> 降级验收，禁止静默关闭
4. 禁止无凭证关闭。凭证缺失的历史工单不重开，改为补记 ## 关闭凭证核验（补记 · YYYY-MM-DD） 并显式标注为事后追溯。

文档性质纪律（强制）

全文见 docs/standards/文档性质标记规范.md。核心铁律： 文档必须先说清自己是「需求」还是「需求的需求」，再谈内容。

1. 两类必须区分：
   • 需求（REQ） —— 做一个具体功能/集成。有功能边界、接口契约、验收标准、归属工单。
   • 元需求（META） —— 约束所有需求怎么做（规范/口径/流程/模板/审查判据）。 docs/standards/ 与 AGENTS.md 属此类。
   • 参考（REF） —— 现状记录（表结构说明 / API 清单 / 台账），无约束力，以代码为准。
2. 判据是「约束范围」，不是文件名：名为"XX接入规范"的文档若只约束一个集成， 它是 REQ 而非 META。
3. 三层落地（新增/改动约束性文档时）：
   • ① 文档头部标 **性质**：元需求（META） / 需求（REQ） / 参考（REF）
   • ② 在 docs/README.md §六「文档性质索引」登记一行
   • ③ META 且含强制条款 → 必须同步挂进本文件（AGENTS.md）引用链
4. 禁止「标记了但约束不住」：META 不进 AGENTS 引用链 = 只是标签，不构成约束。
5. 三类适用不同规则（用错标准 = 审查失效）：

   	META	REQ	REF
   审查标准	能否约束住别人	验收标准是否达成	是否与代码一致
   变更成本	高（全仓影响）	中（局部）	低（同步即可）
   走架构锁定	❌	✅	❌

6. 存量不追溯，改动即补齐：未标性质的存量文档不强改；谁改动、谁补齐。