chore: 文档与 IDE 配置整理

- .kiro/specs/ → docs/specs/(41 个历史需求 spec 迁移,移除 .config.kiro)
- CLAUDE.md 三层拆分:根文件精简 + apps/backend/CLAUDE.md + .claude/commands/
- 新增 /spec-close、/pre-change 两个工作流命令
- DDL 基线刷新(从测试库重新导出 11 个文件,dws 35→38 表,biz 18→21 表)
- BD_Manual → BD_manual 命名统一(48 个文件)
- 修复 3 处文档与数据库不一致(auth.users.status 默认值、scheduled_tasks 字段、RLS 视图数)
- 新增 BD_manual_public_rbac_tables.md(public schema 8 张 RBAC/工作流表)
- 合并 biz.trigger_jobs 文档(10→12 字段,归档独立文档)
- docs/database/README.md 索引更新

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Neo
2026-04-06 00:02:37 +08:00
parent 8228b3fa37
commit 70324d8542
185 changed files with 13595 additions and 1219 deletions

52
apps/backend/CLAUDE.md Normal file
View File

@@ -0,0 +1,52 @@
# CLAUDE.md — Backend (FastAPI)
进入本目录时自动加载。
## 架构模式
### 全局响应包装
`ResponseWrapperMiddleware` 把所有 2xx 响应包为 `{ "code": 0, "data": <payload> }`
非 2xx 响应保持原样。前端统一通过 `response.data` 解包。
### 序列化
`CamelModel` 基类snake_case → camelCase 自动转换(小程序 API 用)。
后端代码始终用 snake_caseJSON 输出自动转驼峰。
### JWT 双认证
| 认证方式 | 用途 | 表 | JWT aud |
|---------|------|-----|---------|
| 用户名+密码 | admin-web 登录 | `auth.admin_users` | `admin` |
| 微信 code | 小程序登录 | `auth.users` | `miniapp` |
| 用户名+密码 | tenant-admin 登录 | `auth.tenant_admins` | `tenant-admin` |
待审核用户有 limited token仅可访问审核状态接口
### AI 集成
8 个千问应用通过 DashScope SDK
chat / finance / clue / analysis / tactics / note / customer / consolidate
特性:熔断(连续失败自动断路)、限流(每分钟/每日)、预算追踪、对话缓存。
### 后台服务lifespan
- `TaskQueue`:按 site_id 消费FIFO 队列
- `Scheduler`:读 `meta.scheduled_tasks` 自动入队
- 4 个触发器:日结/月结/工资/关系指数
### 数据库访问
- 业务库通过 `APP_DB_DSN` 直连 `zqyy_app`
- ETL 数据通过 FDW 映射的 `app.v_*` RLS 视图访问
- 查询前必须 `SET LOCAL app.current_site_id = :site_id`
## 测试
```bash
cd apps/backend && pytest tests/ -v
```
使用测试库(`TEST_APP_DB_DSN`),禁止连正式库。