shanxia2.0/backend/AGENTS.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 目录执行：

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。