cma-management/AGENTS.md

CMA 管理会计OS — 项目级 AGENTS.md

本文件是给 AI 编程代理（Claude Code）的项目级指令。修改代码前必读。

项目总览

• 产品：管理会计OS（CMA），面向中小企业的管理会计 SaaS
• 访问：cma.sxbh.ltd（生产）/ learn.sxbh.ltd（学习站）
• 仓库：Gitea git.sxbh.ltd/sxbh_admin/（CI/CD: Woodpecker 自动构建部署）

技术栈

• 后端：FastAPI + SQLAlchemy + MySQL（生产） + Redis（token/缓存）
  • systemd 服务 cma-backend，端口 8010，WorkingDirectory=/root/cma-management
  • nginx root=/var/www/cma（前端静态）
• 前端：Vue3 + TypeScript + Element Plus + Vite + pnpm
• AI：DeepSeek（deepseek-chat），LangChain 为备选集成方案

多租户铁律（最重要）

• entity_id 是租户隔离核心：所有业务表必须有 entity_id 字段，查询必须按当前租户过滤
• 登录前选公司，token 绑定 entity_id（Redis 存 JSON {user_id, entity_id}）
• deps.get_entity_id 解析链：token优先(query/header不一致→403) → Bot白名单 → entity_id=1
• 写代码时永远不要忽略 entity_id——漏了就是跨租户数据泄漏（P0 安全bug）

编码规范

• Python：FastAPI 依赖注入用 deps 模块；Pydantic 校验输入
• SQLAlchemy 模型 NOT NULL 字段必须给默认值或明确插入（缺了 500: IntegrityError 1048）
  • 例：Excel导入建KPI须补 entity_id=1, formula="-", data_source="Excel导入", data_owner="财务部", unit="元"
• 前端：表单负责部门/负责人字段必须下拉框动态加载（禁手输）
• 提交前：跑 pytest + 冒烟（health/bot/schema/login/kpis，登录须 entity_id=1）

修改边界

• 只改任务指明的文件；表结构迁移须先备份（backups/）
• 不破坏：deploy.sh 提交纪律、冒烟检查、/api/cma/bot/* 的 X-BOT-KEY 机制
• 安全敏感改动（权限/支付/删除/核心表）完成后必须自审，标注风险

验证标准（怎么算完成）

1. 改完能跑：pytest 通过或冒烟脚本通过
2. 数据变化可回查（DESC 表/查库确认）
3. 生产部署走 deploy.sh（含备份+回滚预案）
4. 不允许"看起来对了"——必须有实际执行输出证明

常用命令

# 后端冒烟
cd /root/cma-management && bash deploy.sh smoke   # 或 deploy.sh 完整部署
# 登录拿token（entity_id=1）
curl -s -X POST http://127.0.0.1:8010/api/login -H 'Content-Type: application/json' -d '{"username":"...","password":"..."}'
# 查服务
systemctl status cma-backend