# 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 含大量历史未提交时，只传本次会话文件列表。