# 后端规则

修改前先读 [根规则](../AGENTS.md) 和 [工程规则](../docs/development/engineering-rules.md)。保存、批量更新、导入、复制、子数据移除与流程配置必须完整阅读 [子数据保存规则](../docs/development/child-data-save-rules.md)。

## 技术栈与分层

Python 3.9、FastAPI、SQLAlchemy、Pydantic v2、MySQL / pymysql、Redis、MinIO、JWT。依赖中包含 Alembic，但当前仓库未配置应用级 Alembic 迁移目录，不能将其视为现行迁移流程。入口 `app/main.py` → `app.main:app`。历史工程约定为 Python 3.9，`start.sh` 的缺失解释器提示写作 3.10+，存在文档与脚本提示不一致；本次整理不升级运行环境，执行前确认本地解释器与依赖兼容。

- `app/api/` 保持薄路由；业务逻辑放 `app/services/`、数据库访问放 `app/crud/`。
- 模型 `app/models/`，输入输出 `app/schemas/`，定时任务 `app/tasks/`；配置由 `app/core/config.py` 的 pydantic-settings 读取环境文件。
- CRM、db、bx、pl 与工作流都是当前仓库已有模块，维护前从实际路由追踪到服务、CRUD 和客户端。
- 新路由必须同时注册在 `app/api/__init__.py` 与 `app/main.py`，不能绕过认证、加密、审计。
- 业务查询和写入强制租户隔离、数据范围多角色并集；禁止客户端覆盖 tenant_no。详见工程规则中的 API、数据库和权限章节。
- 列表默认 `create_time DESC`；业务数据软删除；数据库变更同步 `../docs/sql/`。
- `_row_to_dict`、CreateBody/UpdateBody 和前端 formData 的可写字段逐项对齐，计算字段排除。通过相关回归验证，不调用仓库中不存在的通用字段检查脚本。
- 现有细胞存储样本业务仍遵守 `tenant_no + sample_code` 跨表关联，不能使用可变化的协议 ID；该规则仅适用于相关样本功能。

## 本地命令

在 backend 目录执行：

```bash
source venv/bin/activate
pip install -r requirements.txt
./start.sh --reload
pytest
```

`./start.sh --help` 查看本地选项，默认监听 `0.0.0.0:8000`；按需求明确 host / port。生产脚本 `./start-prod.sh` 支持 `install|start|stop|restart|status|logs`，读取生产环境；不能把生产操作当成本地验证。

`tests/` 已有多个业务回归测试模块。先执行受影响测试，再按风险补充验证；记录实际命令和结果，不把未执行的测试写成通过。

## 配置与接口

- API 前缀受 `API_V1_PREFIX` 控制，通常 `/api`；以已注册路由为准。
- JWT + RSA 登录；RSA 私钥通过既有生成或 `LOGIN_RSA_PRIVATE_KEY_PEM` 配置机制提供。
- API 加密由 `API_ENCRYPT_*` 配置控制，排除接口在 `API_ENCRYPT_EXCLUDE_PATHS`，不得通过新路由绕过中间件。
- 配置读取 `.env` / `.env.local` / `.env.production`；不在文档传播真实凭据，不依赖历史默认管理员密码。
- 数据库快照使用 `../docs/sql/shanxia2.0.sql` 并结合迁移确认当前结构；Swagger `/docs`、ReDoc `/redoc`。