zlwu
b220298f89
为减少仓库噪声和重复规则，整理当前开发入口并移除已废弃资料。 - 精简根 AGENTS，补充四个应用规则与 README，统一规范入口 - 归整部署文件、SOP 原稿和参考资源，修正迁移后的脚本路径 - 取消虚拟环境、工具状态、业务导出及备份的跟踪，本机所需原件保留 - 移除停用的 graphify 配置、脚本与产物 - 删除历史业务文档、执行计划、OpenSpec 业务变更和移动 UI 原型 - 清理失效引用，历史细胞产品导入改为必须显式指定 --file 验证：git diff --cached --check、OpenSpec 严格校验、导入参数隔离检查 3/3 通过； 迁移文件完整性和现行链接已核对。未执行部署、业务数据导入或服务启停。
4.4 KiB
4.4 KiB
后端开发约束
适用 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。测试工具安装在开发环境，不为清理改动覆盖现有环境。