fix(organization): 科室接口增加分页参数

2026-09-03 10:01:05 +08:00
parent 612e43aeff
commit f9b556896b
2 changed files with 74 additions and 1 deletions
@@ -263,3 +263,74 @@ DELETE /api/v1/templates/{templateId}/permissions/{permissionId}
 3. 补批量导入预览、确认和任务查询；
 4. 根据产品是否保留角色卡片人数，补角色统计接口；
 5. 如果要管理 API 权限，再补角色与 API 权限的关联接口，不能复用 `/api/v1/permissions` CRUD 代替。
+
+## 6. 以最新 OpenAPI 核验授权链路（2026-09-02）
+
+### 6.1 已有能力与当前状态
+
+| 核验项             | 最新接口/实现                                                           | 状态                                 |
+| ------------------ | ----------------------------------------------------------------------- | ------------------------------------ |
+| 登录认证           | `POST /api/v1/auth/login` 返回 `X-Token`、`dataScope` 和 `permissions`  | 已具备                               |
+| 当前用户刷新       | `GET /api/v1/auth/me` 返回 `UserResponse`，该 schema 没有 `permissions` | 字段不足                             |
+| 用户页面登录保护   | 路由只判断是否存在 Token                                                | 已具备认证，缺少权限门控             |
+| 用户/角色/权限 API | `/users`、`/roles`、`/permissions` 的 CRUD 接口均在 OpenAPI 中          | API 封装已接入；权限目录暂无对应页面 |
+| 用户角色关联       | 最新 OpenAPI 没有用户-角色关系接口                                      | 后端缺口                             |
+| 角色 API 权限关联  | 最新 OpenAPI 没有角色-API 权限关系接口                                  | 后端缺口                             |
+| 模板文档权限       | `/api/v1/templates/{templateId}/permissions`                            | 独立能力，不能替代 API 权限          |
+
+当前侧边栏会向所有已登录用户展示“用户与权限”和“文档权限”，直接输入管理端 URL 也可以进入；按钮是否真正可执行目前依赖后端返回 `403`。这不能替代前端菜单/路由门控，但安全边界必须仍由后端执行。
+
+### 6.2 后端需要确认或补充的内容
+
+1. **补齐当前用户权限刷新**
+
+   建议修改 `GET /api/v1/auth/me` 的成功响应，使其至少包含登录摘要中的 `dataScope` 和 `permissions: string[]`。权限集合只返回当前用户实际拥有的启用权限，不返回密码或未脱敏敏感信息。若不改现有接口，需新增等价的 `GET /api/v1/auth/me/permissions`，但应只保留一个权威来源。
+
+2. **定义并初始化权限编码**
+
+   OpenAPI 只建议使用 `system:<资源>:<动作>` 格式，没有给出本页面实际权限编码。建议后端确认并初始化：
+
+   - `system:user:query`、`system:user:create`、`system:user:update`、`system:user:disable`；
+   - `system:role:query`、`system:role:create`、`system:role:update`、`system:role:disable`；
+   - `system:permission:query`、`system:permission:create`、`system:permission:update`、`system:permission:disable`。
+
+   上述编码是建议值，最终以后端权限中心的命名为准；报表权限还应单独定义 query/export 权限，不能用页面名称或前端隐藏按钮代替。
+
+3. **提供 API 权限关系接口**
+
+   `/api/v1/permissions` 只负责权限目录增删改查。若管理端需要真正分配 API 权限，需提供：
+
+   ```http
+   GET /api/v1/roles/{roleId}/permissions
+   PUT /api/v1/roles/{roleId}/permissions
+   Content-Type: application/json
+   ```
+
+   ```json
+   { "permissionIds": ["API 权限 UUID 1", "API 权限 UUID 2"] }
+   ```
+
+   用户角色关系仍需提供：
+
+   ```http
+   GET /api/v1/users/{userId}/roles
+   PUT /api/v1/users/{userId}/roles
+   ```
+
+   关系更新建议使用完整替换、幂等语义，校验角色/权限状态和当前操作人权限，并记录审计日志。
+
+4. **所有管理接口必须服务端授权**
+
+   用户、角色、API 权限及模板权限接口都应按操作区分 query/create/update/disable 权限；用户 `dataScope` 只能限制数据范围，不能替代操作权限。客户端传入的 `campusId`、`departmentId` 不得扩大操作人的数据范围，越权统一返回 `403`。
+
+5. **补齐错误和审计契约**
+
+   所有授权关系和管理写接口建议明确 `400/401/403/404/409/500`；权限变更、用户停用、角色绑定和 API 权限绑定应记录操作人、目标、动作、结果、时间和 traceId，不记录密码、完整手机号、身份证号或病历内容。
+
+### 6.3 前端联调验收
+
+- 登录后调用 `/auth/me` 能拿到最新权限，权限撤销后旧会话访问受保护接口立即得到 `403`；
+- 无用户查询权限的账号不能看到用户数据，直接访问 URL 也不能绕过后端；
+- 只有对应 create/update/disable 权限的按钮才可用，前端隐藏只是体验优化，不能作为安全措施；
+- 用户角色和角色 API 权限变更后，重新登录或刷新当前用户即可看到最新权限；
+- Mock 模式仅用于页面演示，真实权限验证必须设置 `VITE_USE_MOCK=false`，使用不同权限账号检查 Network 请求和 401/403 响应。
@@ -46,9 +46,11 @@ export function getDepartments(campusId?: string): Promise<DepartmentRecord[]> {
    return Promise.resolve([])
  }

+  const params = campusId ? { page: 1, size: 200, campusId } : { page: 1, size: 200 }
+
  return request
    .get<ApiResponse<BackendCollection<OrganizationResponseDto>>>('/v1/departments', {
-      params: campusId ? { campusId } : undefined,
+      params,
    })
    .then(unwrapApiResponse)
    .then((data) =>