50 lines
2.5 KiB
Markdown
50 lines
2.5 KiB
Markdown
# 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. 不允许"看起来对了"——必须有实际执行输出证明
|
||
|
||
## 常用命令
|
||
```bash
|
||
# 后端冒烟
|
||
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
|
||
```
|