zkxw/openspec/changes/zkxw-engineering-standards/specs/api-conventions/spec.md

ADDED Requirements

来源说明：文中《中科兴皖需求 V0.3》及其章节引用为历史出处，原文已清理；以下既有 SHALL 要求继续有效，当前入口见根 AGENTS.md 与本工程标准。

Requirement: 租户隔离

所有面向业务数据的查询接口 SHALL 仅返回 tenant_no 等于当前登录用户租户编号的数据；所有写入或更新类接口 SHALL 将目标业务行的 tenant_no 设置为当前登录用户的 tenant_no（与《中科兴皖需求 V0.3》§3 一致）。

Scenario: 列表查询

• WHEN 调用任意业务数据列表或详情接口
• THEN 后端 SHALL 在查询条件中强制包含当前用户的 tenant_no

Scenario: 新建业务主表

• WHEN 创建新的业务主表记录
• THEN 持久化的 tenant_no SHALL 等于当前登录用户租户，且不得信任客户端单独提交的租户覆盖服务端策略（除非经安全评审的多租户管理接口）

Requirement: 数据权限过滤

除超级管理员等需求明确豁免的场景外，所有业务查询接口 SHALL 叠加当前登录用户全部角色合并后的数据权限范围进行过滤（与需求 §2.1.5「多角色取权限之和」一致）。

Scenario: 用户绑定多角色

• WHEN 用户拥有角色 A 与角色 B
• THEN 可访问数据范围 SHALL 为两角色数据权限的并集（菜单与数据权限均适用并集语义）

Requirement: 列表默认排序

在无单独产品排序要求的前提下，列表类接口返回的数据集合 SHALL 按 create_time 降序排列（与需求 §3 一致）。

Scenario: 默认分页列表

• WHEN 接口未声明自定义排序参数且业务无例外说明
• THEN 默认排序 SHALL 为 create_time DESC

Requirement: API 前缀与工程约定

对外 HTTP API SHALL 使用统一前缀（当前仓库为 /api 及版本/子路径，见 AGENTS.md）；新增路由 SHALL 注册到既有路由聚合机制，避免绕过中间件（鉴权、加解密、审计等）。

Scenario: 新增 admin 路由

• WHEN 在 app/api/ 增加新的路由模块
• THEN 该模块 SHALL 在 app/api/__init__.py 与 app/main.py 中完成注册，并符合现有认证与租户上下文注入模式

Requirement: 细胞存储样本跨表关联键

细胞存储场景下，将协议样本行（biz_protocol_sample）与下游业务（样本接收 biz_sample_reception、质检工单 biz_qc_work_order 等）进行业务匹配时，关联键 SHALL 仅为 tenant_no + sample_code（租户内样本编码唯一且不变；接收/工单表须持久化 sample_code 快照）。不得使用 collection_protocol_id 或 protocol_sample_id 作为查询、列表排除、详情回显的关联依据（协议单可换号/转科研、编辑保存会重建样本行 id，但样本编码不变）。

Scenario: 协议单查看弹窗展示样本接收

• WHEN 用户打开采集协议单详情，且租户内某 sample_code 已登记接收
• THEN 详情接口 SHALL 仅按样本编码返回对应 sampleReception（及同规则的 qcInfo），与当前协议单 ID、样本行 id 是否变更无关

Scenario: 待接收列表排除已接收样本

• WHEN 租户内某 sample_code 已存在有效接收记录（del_flag=0）
• THEN 该编码的协议样本 SHALL NOT 出现在待接收列表

Scenario: 登记接收防重复

• WHEN 用户对某协议样本提交接收登记
• THEN 服务端 SHALL 按 tenant_no + sample_code 校验是否已接收，已存在则拒绝重复登记