zlwu
b220298f89
为减少仓库噪声和重复规则，整理当前开发入口并移除已废弃资料。 - 精简根 AGENTS，补充四个应用规则与 README，统一规范入口 - 归整部署文件、SOP 原稿和参考资源，修正迁移后的脚本路径 - 取消虚拟环境、工具状态、业务导出及备份的跟踪，本机所需原件保留 - 移除停用的 graphify 配置、脚本与产物 - 删除历史业务文档、执行计划、OpenSpec 业务变更和移动 UI 原型 - 清理失效引用，历史细胞产品导入改为必须显式指定 --file 验证：git diff --cached --check、OpenSpec 严格校验、导入参数隔离检查 3/3 通过； 迁移文件完整性和现行链接已核对。未执行部署、业务数据导入或服务启停。
51 lines
4.4 KiB
Markdown
51 lines
4.4 KiB
Markdown
# 后端开发约束
|
||
|
||
适用 `backend/`，与[根规则](../AGENTS.md)同时生效。环境与命令见 [README](README.md)。
|
||
|
||
## 分层与入口
|
||
|
||
- 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`，并按[指南](../docs/dev-field-consistency.md)核对受影响实体。检查器只覆盖注册实体，不能代替新增实体检查。
|
||
- 当前检查器有两个前端路径失效，详情见[字段一致性指南](../docs/dev-field-consistency.md)。失败需区分既有问题和新改动，不能隐藏结果。
|
||
|
||
## 工作流与 OA
|
||
|
||
- `app/services/workflow_engine.py` 与 `app/services/oa_engine.py` 均有实现；不得将其描述为尚未实现或当作重复文件删除。
|
||
- 流程由后端独立、可配置地执行；支持开始、结束、审批人、多条件分支，扩展不得破坏已发布定义。
|
||
- 审批人策略遵循指定用户、角色或受控 SQL 解析，以及任一通过／全员通过的正式要求；不能让前端独占流程状态机。
|
||
- 运行实例绑定发起版本，新发布版本只影响新实例；维护待办、已办中心的权限与状态一致性。
|
||
- 具体要求见 [workflow-conventions](../openspec/changes/zkxw-engineering-standards/specs/workflow-conventions/spec.md)，不同引擎的能力差异应单独核实。
|
||
|
||
## 验证与工具
|
||
|
||
- 在隔离数据环境执行受影响测试，不运行清库、导入、重置密码等脚本作为通用验收。
|
||
- 环境与文档清理不重启服务；影响范围通过源码检索和测试核对。
|
||
- `requirements.txt` 保存运行依赖，`venv/`、`.venv/` 是本地环境，不能纳入 Git。测试工具安装在开发环境，不为清理改动覆盖现有环境。
|