Neo-ZQYY/AGENTS.md

AGENTS.md

NeoZQYY Monorepo 顶层规则。子模块详细规范见各自 apps/*/AGENTS.md、docs/database/、apps/etl/connectors/feiqiu/AGENTS.md。

语言（强制）

始终中文：对话、解释、代码注释、commit message（中文描述 + 英文 Co-Authored-By 签名）、PR、审计、文档、错误日志。 保持原文：变量/函数/类名、第三方 API 字段名、CLI 命令、技术术语。 禁止英文段落或英文标题。

CLI / Shell 中文处理

• Python encoding="utf-8" / PYTHONUTF8=1；CSV 给 Excel 用 utf-8-sig；PowerShell/Node 不依赖系统 ANSI。
• 终端中文乱码时，不当作事实；先调编码重跑，或说明"终端编码异常，结果需复核"。
• Shell 路径含中文/空格/特殊字符必须加引号；复杂中文输出走脚本或结构化 API。

项目概览

NeoZQYY = 台球门店全栈数据平台。多门店隔离（site_id + RLS），中文领域语言，CNY，金额 numeric(2)。

目录	用途
apps/etl/connectors/feiqiu/	飞球 ETL：API → ODS → DWD → DWS
apps/backend/	FastAPI（JWT 双认证 + WebSocket + AI）
apps/miniprogram/	微信小程序 C 端（Donut + TDesign）
apps/admin-web/	系统管理后台（开发/运维视角，操作 ETL 库）
apps/tenant-admin/	租户管理后台（门店管理员视角，操作业务库）
apps/demo-miniprogram/	MOCK 标杆小程序（样式校对，禁改）
apps/mcp-server/	MCP Server（PostgreSQL 只读）
packages/shared/	跨项目共享包
db/	DDL（schemas/）+ 迁移 + FDW
tools/	通用工具
scripts/ops/	日常运维脚本

技术栈：Python 3.10+ uv workspace、React+Vite+AntD、PostgreSQL 四库（etl_feiqiu/test_etl_feiqiu/zqyy_app/test_zqyy_app，DSN PG_DSN/APP_DB_DSN）。配置分层 .env < .env.local < env < CLI。

数据库

• 六层 Schema：meta → ods → dwd → core → dws → app（RLS 视图）
• 跨库：zqyy_app 通过 FDW 只读映射 etl_feiqiu.app
• RLS：site_id + app.current_site_id 会话变量
• RLS 双 Schema 踩坑：DWS/DWD 表的 RLS 视图必须同时建在 dws 和 app schema，后端走 app.v_*。只建 dws 会让后端查询失败。回滚需逆序 DROP。

飞球数据规范（速查）

• consume_money 禁止直接计算 → 用 items_sum 拆分字段
• 取数优先级：DWS > DWD > 禁止 ODS
• 参考优先级：DWD-DOC > DWS 权威规范 > BD 手册 > ETL 任务文档 > DDL 注释
• _archived/ 目录禁止读取或参考
• 完整规则见 apps/etl/connectors/feiqiu/AGENTS.md

文件归属

类型	位置
模块内文档/测试/脚本	模块内 docs/、tests/、scripts/
跨模块文档	根 docs/
Monorepo 守护测试	根 tests/
日常运维脚本	scripts/ops/
通用工具	tools/（按类型分子目录）
审计记录	根 docs/audit/changes/<YYYY-MM-DD>__<slug>.md（禁止写子模块）
数据库文档	根 docs/database/
归档/待删	_DEL/（保持原路径，定期清理）

docs/audit/audit_dashboard.md 由 scripts/audit/gen_audit_dashboard.py 生成，勿手动编辑。

编码前需求审问（强制）

新建功能/接口、重构、多模块联动、需求模糊时：

1. 不立即动手，先提问循环（每轮 3-5 个问题）
2. 必问：用户角色、核心操作、数据写入/展示/来源、错误/成功反馈、认证权限、存储（哪库/新表）、终端适配、边界（并发/幂等/超时）
3. 输出「需求确认摘要」，用户确认后实施

例外：用户说"直接改/跳过审问"、Bug 有明确复现步骤、纯格式调整、已有 spec

逻辑改动前置调研（强制）

任何逻辑改动（ETL/业务规则/API/数据模型/前端交互）：

1. 委托 Explore 子代理调研：目标模块、docs/audit/changes/ 历史、调用方/被调用方、数据流向、影响范围
2. 输出「改动前上下文摘要」，用户确认后实施

流程：需求审问 → 确认 → 前置调研 → 确认 → 编码

例外：纯格式/注释/文档修改、用户说"直接改/跳过调研"、新建独立文件

改动后验证（强制）

1. 运行相关测试（单元/集成/lint），不能运行需说明原因
2. 输出 diff 摘要（文件清单 + 每个改动要点）
3. 列出未覆盖风险点（未测路径、副作用、需人工验证场景）

例外：纯格式/文档/注释、用户说"跳过验证"

数据库 Schema 变更

修改 PostgreSQL schema（迁移/DDL/表定义/ORM）时，必须同步 docs/database/：变更说明、兼容性影响、回滚策略、≥3 条校验 SQL。

测试环境

1. load_dotenv 加根 .env；必需变量缺失立即报错，禁止静默回退空串
2. cwd 与正式一致：ETL → apps/etl/connectors/feiqiu/、后端 → apps/backend/
3. 配置走 AppConfig.load()，不得为测试构造简化配置
4. 用测试库（TEST_DB_DSN），禁止连正式库
5. 属性测试分组执行（-k 筛选），禁止一次性全跑；hypothesis 默认 max_examples=100

例外：用户指定简化环境、纯单元测试用 FakeDB/FakeAPI、--dry-run CLI 验证

脚本规范

• 复杂操作写 Python 脚本，避免复杂 shell
• 一次性运维 → scripts/ops/；模块专属 → 模块内 scripts/
• scripts/ops/ 不在 uv workspace 内，导入 ETL 纯函数用 importlib.util + stub（参考 scripts/ops/backfill_finance_area_daily.py）

子代理

• 委托：批量读 ≥3 文件、大范围搜索、不熟悉模块探索、多步 shell
• 主流程直接处理：单文件、单命令、小范围精确搜索

审计

任何逻辑改动必须可追溯、可验证、可回滚。

完成一轮后用 /audit：

1. python scripts/audit/prescan.py 预扫描（自动识别+分类+合规，零 token）
2. 补充语义上下文（从对话提取每变更原因）
3. 委托子代理写 docs/audit/changes/
4. 补齐文档同步
5. python scripts/audit/gen_audit_dashboard.py 刷新一览表

prescan.py --files 参数：git status 含大量历史未提交时，只传本次会话文件列表。