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

ADDED Requirements

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 按 order_num 升序、create_time 降序排列（与需求 §3 一致）。

Scenario: 默认分页列表

• WHEN 接口未声明自定义排序参数且业务无例外说明
• THEN 默认排序 SHALL 为 order_num ASC, 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 中完成注册，并符合现有认证与租户上下文注入模式