tyt-api-nest/docs/frontend-api-integration.md

前端接口接入说明（tyt-admin）

1. 本次接入范围

• 登录页：/auth/login，支持可选 hospitalId。
• 首页看板：按角色拉取组织与患者统计。
• 任务页：接入 publish/accept/complete/cancel 四个真实任务接口。
• 用户页：修复用户列表响应结构、组织字段联动、工程师分配医院参数。
• 患者页：接入真实患者字段与生命周期查询参数（phone + idCardHash）。

2. 接口契约对齐点

• GET /users 当前返回数组，前端已在 api/users.js 做本地分页与筛选适配。
• PATCH /b/users/:id/assign-engineer-hospital 参数为单个 hospitalId，非数组。
• GET /b/patients 返回数组，前端已改为本地分页与筛选。
• GET /c/patients/lifecycle 必须同时传 phone 和 idCardHash。
• 任务模块暂无任务列表接口，前端改为“表单操作 + 最近结果”模式。

3. 角色权限提示

• 任务接口权限：
  • DOCTOR/DIRECTOR/LEADER：发布、取消（仅可取消自己创建的任务）
  • ENGINEER：接收、完成
• 患者列表权限：
  • SYSTEM_ADMIN 查询时必须传 hospitalId
• 用户管理接口：
  • SYSTEM_ADMIN/HOSPITAL_ADMIN 可访问列表与创建
  • 删除和工程师绑定医院仅 SYSTEM_ADMIN

3.1 结构图页面交互调整

• 医院管理员视角下，右侧下级列表会优先显示“人员”节点，再显示组织节点。
• 选中人员节点时，右侧展示人员详情（角色、手机号、所属医院/科室/小组），不再显示空白占位。

3.2 后台页面路由权限（与后端 RBAC 对齐）

• organization/tree、organization/departments、organization/groups、users
  • organization/tree、organization/departments、organization/groups： SYSTEM_ADMIN、HOSPITAL_ADMIN、DIRECTOR、LEADER 可访问
  • users：仅 SYSTEM_ADMIN、HOSPITAL_ADMIN 可访问
• organization/hospitals
  • 仅 SYSTEM_ADMIN 可访问
• tasks
  • 仅 DOCTOR、DIRECTOR、LEADER、ENGINEER 可访问
• patients
  • 仅 SYSTEM_ADMIN、HOSPITAL_ADMIN、DIRECTOR、LEADER 可访问

前端已在路由守卫和侧边栏菜单同时做权限控制，无权限角色会被拦截并跳转到首页，避免进入页面后触发接口 403。

3.3 主任/组长组织管理范围

• DIRECTOR
  • 可查看组织架构、科室列表、小组列表（限定本科室范围）
  • 可编辑本科室名称、创建/编辑/删除本科室下小组
• LEADER
  • 可查看组织架构、科室列表、小组列表（限定本科室/本小组范围）
  • 可编辑本科室名称与本小组名称
• 负责人设置（设主任/设组长）与人员管理入口仍仅 SYSTEM_ADMIN、HOSPITAL_ADMIN 显示。

4. 本地运行

在 tyt-admin 目录执行：

pnpm install
pnpm dev