Neo
81e41730ec
Co-Authored-By: OpenAI Codex <codex@openai.com> Co-authored-by: Cursor <cursoragent@cursor.com>
53 lines
1.5 KiB
Markdown
53 lines
1.5 KiB
Markdown
# AGENTS.md - Backend (FastAPI)
|
||
|
||
进入本目录时自动加载。
|
||
|
||
## 架构模式
|
||
|
||
### 全局响应包装
|
||
|
||
`ResponseWrapperMiddleware` 把所有 2xx 响应包为 `{ "code": 0, "data": <payload> }`。
|
||
非 2xx 响应保持原样。前端统一通过 `response.data` 解包。
|
||
|
||
### 序列化
|
||
|
||
`CamelModel` 基类：snake_case -> camelCase 自动转换（小程序 API 用）。
|
||
后端代码始终用 snake_case，JSON 输出自动转驼峰。
|
||
|
||
### 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`），禁止连正式库。
|