Neo-ZQYY/apps/backend/AGENTS.md

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

测试

cd apps/backend && pytest tests/ -v

使用测试库（TEST_APP_DB_DSN），禁止连正式库。