zkxw/backend/AGENTS.md

后端开发约束

适用 backend/，与根规则同时生效。环境与命令见 README。

分层与入口

• Python 3.9、FastAPI、SQLAlchemy、Pydantic v2；配置通过 app/core/config.py 的 pydantic-settings 与环境文件读取。
• 路由保持薄层；业务逻辑在 app/services/，持久化在 app/crud/，模型与 Schema 在 app/models/、app/schemas/；既有 API 内联 Schema 按周边方式维护。
• 新路由模块必须同时在 app/api/__init__.py 导出并在 app/main.py 注册；保持鉴权、API 加密和请求审计。
• API 总前缀由 API_V1_PREFIX 控制，默认 /api；实际模块主要使用 /web/...、/mini/...，以路由定义为准。
• 列表无自定义排序时使用 create_time DESC。

数据库与权限

• MySQL 5.7、utf8mb4。主键 id VARCHAR(64) NOT NULL，值为 UUID。
• 字段顺序：id → 业务字段 → tenant_no、order_num、remark、create_by、create_dept_id、create_time、update_by、update_time、del_flag；del_flag 默认 0。
• 查询按租户与数据权限过滤，默认排除 del_flag=1；写入租户从当前用户取得。禁止业务物理删除。
• 数据范围支持全部、本部门、本部门及下级、本人、自定义；自定义使用 sys_role_data_scope_detail.scope_type（dept/user）和 scope_value。
• 权限取有效角色并集，包括现有职位继承角色链；复用 app/services/web_auth_roles.py、app/core/data_scope.py，不要另造单角色判断。
• SQL 变更维护在 ../docs/sql/，区分结构迁移、种子数据与一次性数据修复；有写库行为的 scripts/ 不是普通检查命令。

子行与样本关联

• 通过 app/crud/child_row_sync.py 的 sync_child_rows 按行保存，已有行保持原 ID。
• 请求无 ID 时，用稳定业务键（样本编码、物料编码、条码、组分 ID 等）匹配尚未占用的有效行，匹配不到才生成 UUID。
• 拒绝其他父记录或其他租户的 ID。只软删除用户移除的行；删除父记录可级联软删除，复制或克隆父记录必须为子行生成新 ID。
• 禁止先把全部子行软删除再插入，否则会破坏 production_step_output_id、protocol_sample_id、donation_sample_id 等外部引用。
• 细胞存储样本与接收、质检等下游匹配使用 tenant_no + sample_code，不使用 collection_protocol_id 或 protocol_sample_id 作为跨表匹配键。

字段一致性

• _row_to_dict 是实体可读字段基准；CreateBody、UpdateBody、前端 formData 必须包含其中所有可写字段。
• 排除 id、tenantNo、createTime、updateTime、stockQty 等服务端或计算字段；租户不能成为客户端可写字段。
• 逐层核对 Schema → API Handler → CRUD 参数 → ORM 赋值；字段映射不只检查返回值。
• 修改后从仓库根目录运行 python backend/scripts/check_field_consistency.py，并按指南核对受影响实体。检查器只覆盖注册实体，不能代替新增实体检查。
• 当前检查器有两个前端路径失效，详情见字段一致性指南。失败需区分既有问题和新改动，不能隐藏结果。

工作流与 OA

• app/services/workflow_engine.py 与 app/services/oa_engine.py 均有实现；不得将其描述为尚未实现或当作重复文件删除。
• 流程由后端独立、可配置地执行；支持开始、结束、审批人、多条件分支，扩展不得破坏已发布定义。
• 审批人策略遵循指定用户、角色或受控 SQL 解析，以及任一通过／全员通过的正式要求；不能让前端独占流程状态机。
• 运行实例绑定发起版本，新发布版本只影响新实例；维护待办、已办中心的权限与状态一致性。
• 具体要求见 workflow-conventions，不同引擎的能力差异应单独核实。

验证与工具

• 在隔离数据环境执行受影响测试，不运行清库、导入、重置密码等脚本作为通用验收。
• 环境与文档清理不重启服务；影响范围通过源码检索和测试核对。
• requirements.txt 保存运行依赖，venv/、.venv/ 是本地环境，不能纳入 Git。测试工具安装在开发环境，不为清理改动覆盖现有环境。