akmon/doc_admin/admin.md

管理后台（Admins）在多租户场景下的页面与权限设计说明

本说明面向后台管理的使用者与开发者，梳理当前 pages/admins 下的页面实现，评估其在“多租户（学校）”场景下对学校管理员、教师、家长三类主体管理手环与学生状态的适配度，并提出改进与落地建议。

适用角色与多租户边界

• 多租户定义：按学校或教育集团划分租户（tenant）。每条数据均需要携带 tenant_id（或 school_id）。
• 典型角色
  • 平台管理员（Platform Admin）：跨租户运维、系统配置、全局审计与安全。
  • 学校管理员（School Admin）：本校组织架构、教师、学生、手环设备、课程/训练等管理。
  • 教师（Teacher）：所授班级/课程维度的学生、手环绑定状态、训练/作业与告警查看。
  • 家长（Parent/Guardian）：仅查看与其子女相关的数据（非“后台管理”常用角色，但文末给出最小后台接入点建议）。
• 权限建议（部分示例）
  • 系统与用户：admin.system.manage, admin.roles.manage, admin.users.manage
  • 学校域：school_admin.school.manage, school_admin.class.manage, school_admin.teacher.manage, school_admin.student.manage, school_admin.device.manage
  • 教师域：teacher.class.view, teacher.student.view, teacher.device.assign, teacher.training.manage
  • 家长域：parent.child.view

现有代码中已出现的权限码（如 admin.roles.manage, admin.users.manage, school_admin.class.manage, school_admin.teacher.manage）与上述建议兼容，可继续延展。

当前页面盘点（pages/admins）

• layout.uvue（后台通用布局）

  • 功能：侧边导航、头部用户/通知、统一内容区域、权限控制导航项显示。
  • 亮点：
    • 菜单分区清晰（数据中心、学校管理、训练管理、系统设置）。
    • 通过 hasPermission 动态控制菜单项可见性。
    • 内置通知抽屉、修改密码弹窗等后台常用交互。
  • 发现的问题与建议：
    • 路由路径混用 /pages/admin/... 与实际目录 /pages/admins/...，存在不一致，建议统一为 /pages/admins/... 并补齐对应页面。
    • 少量字符编码异常（<EFBFBD>?），建议统一文件编码为 UTF-8 并清理。

• roles/index.uvue（角色与权限）

  • 功能：角色列表、权限列表的分页浏览，角色新增/编辑/删除，查看与分配权限（含资源类型筛选）。
  • 适配：已做部分 UTS 兼容（如用 for 循环替代 filter/map）。
  • 建议：
    • 将“角色-权限”的增删改查完全串起（当前部分提交/持久化逻辑可能仍需打通）。
    • 增加“按租户/学校范围”的权限视图与授权（角色可带 scope：region/school/grade/class）。

• user-management.uvue（用户管理）

  • 功能：用户列表分页、检索（or: username/email ilike）、跳转详情。
  • 亮点：同屏支持“大屏表格/小屏卡片”双布局，自适配优雅。
  • 建议：
    • 路由上统一到 /pages/admins/users/index（当前文件名为 user-management.uvue，建议重命名或增加中转 index.uvue）。
    • 检索条件建议支持租户/学校过滤，默认绑定当前管理员可见的 tenant_id 范围（UI 增加“范围选择器”）。

• users/detail.uvue（用户详情 + 角色分配）

  • 功能：展示用户基本信息、激活状态、最后登录；按“作用域（region/school/grade/class）”分配角色；移除角色。
  • 亮点：符合教育域多层级授权的常见需求，交互路径清晰。
  • 建议：
    • 作用域下拉选项应根据管理员的最大可管理范围动态过滤。
    • 加入操作审计（谁在何时给谁授了什么范围的角色）。

• permission-management.uvue（命名与内容不匹配）

  • 当前实现拉取 ak_roles，更像“角色管理”。建议要么改名为 role-management.uvue，要么将其改为权限集合（ak_permissions）的浏览与维护页面。

以上页面集合为“系统/用户/角色”维度提供了基本后台能力，但和“学校、老师、家长端对手环及学生状况的管理”相比，仍缺少“学校域业务页面”。

面向学校域的必备后台页面（推荐补齐）

建议在 pages/admins 下新增如下页面，以覆盖手环与学生管理的核心场景：

• 学校/组织

  • schools/index.uvue：学校列表（租户），平台管理员可见全部；学校管理员仅可见本校。
  • schools/detail.uvue（可选）：学校基本信息、管理员、配置（时区/地址/告警策略默认值）。
  • org/scope-picker 组件：在头部或侧栏快速切换“地区/学校/年级/班级”。

• 班级与教师

  • classes/index.uvue：按年级/班级维度管理班级、班主任与课程归属，导入/导出班级花名册。
  • teachers/index.uvue：教师列表与任课信息。

• 学生与家长

  • students/index.uvue、students/detail.uvue：学生档案、班级、监护人（家长）绑定、联系方式。
  • 家长通常不进入后台，但学校管理员需要维护“学生-家长”关联关系。

• 手环设备

  • devices/index.uvue：手环列表（设备编号、状态、固件版本、上次在线/上报时间、所属学生）。
  • devices/assign.uvue：手环与学生的绑定/解绑（支持扫码/录入序列号）。
  • 运行状态看板：在线率、异常统计（低电、离线、佩戴异常）。

• 训练/作业与数据

  • training/index.uvue：训练计划模板、布置与完成度。
  • assignments/index.uvue：作业布置与回收、异常提醒。
  • analytics/index.uvue：数据分析（出勤、运动量、心率与睡眠等）。

• 系统设置与审计

  • settings/index.uvue：学校维度的参数（告警阈值、上报频率）。
  • 审计日志（可合并至 settings 或新增 audit/index.uvue）。

多租户与 RLS 建议

• 每张业务表携带 tenant_id/school_id，并建立相应索引。
• Supabase/Postgres 建议开启行级安全（RLS），基于角色/作用域限定可见范围。
• UI 层：
  • 全局注入“当前作用域”上下文，所有列表/搜索默认带上作用域过滤。
  • 仅当拥有跨范围权限（如平台管理员）时才允许切换租户或无范围搜索。

导航与路由一致性

• 建议统一使用 /pages/admins/... 路径。
• 对现有 layout.uvue 菜单中仍指向 /pages/admin/... 的项目进行修正。
• 为现有页面补充 pages.json 路由注册（当前未注册后台页面）。

数据模型对接（建议）

• 用户与组织
  • ak_users（已用）：id, email, username, role, created_at, tenant_id 等。
  • ak_roles, ak_permissions, ak_user_roles, ak_role_permissions：角色-权限-用户多对多关系。
• 学校域与班级
  • ak_schools（租户表）、ak_grades, ak_classes, ak_teacher_classes, ak_student_classes。
• 学生与监护人
  • ak_students, ak_guardians, ak_student_guardians。
• 手环设备
  • ak_devices：id, imei/serial, firmware, status, last_seen_at, tenant_id。
  • ak_device_assignments：device_id, student_id, bind_at, unbind_at, tenant_id。
• 告警与通知
  • ak_alerts、ak_notifications（现有使用中）。

角色与菜单项可见性（示例）

• 平台管理员：显示全部菜单；可跨租户查看/运维。
• 学校管理员：显示学校/班级/教师/学生/设备/训练/分析/设置；隐藏平台级别的系统管理项。
• 教师：显示班级与学生、训练/作业、分析（受限于参与班级），允许“设备绑定”但仅限本班。
• 家长：通常不进入后台；如有需要，显示仅与子女相关的只读数据面板。

现存问题清单与改进计划

1. 路由不一致：layout.uvue 菜单路径应统一至 /pages/admins/...。
2. 字符编码：若文件出现 <EFBFBD>?，请统一保存为 UTF-8 并修正文案。
3. 权限页面命名：permission-management.uvue 与内容不符，建议改名或改内容。
4. 学校域页面缺口：按“学校/班级/教师/学生/设备/训练/分析/设置”补齐页面与路由。
5. 多租户过滤：所有列表与搜索默认按作用域过滤；仅高权限可切换。
6. 审计与合规：关键操作（赋权、绑定/解绑设备）写入审计日志。
7. pages.json：补充后台页面注册，方便从入口跳转（后续由你确认名称后我来批量写入）。

使用与导航（管理员）

• 从登录进入后台：/pages/user/login → 根据角色跳转后台首页（建议 /pages/admins/index）。
• 在侧栏选择“学校管理”系列页面进行组织与人员管理；
• 在“系统设置/角色权限/用户管理”进行后台权限治理；
• 在“设备管理”完成手环与学生的绑定与监控；
• 在“数据中心/分析”查看统计与异常。

结论

• 现有 pages/admins 已基本覆盖“系统/角色/用户”管理，并具备可扩展的权限控制与通知能力，适合作为统一后台的基础。
• 要满足“学校、老师、家长端对手环及学生状况的管理”，需补齐“学校域”业务页面与设备管理链路，并统一路由、完善租户过滤和审计。
• 按本说明的目录与权限建议扩展后，可以较好地服务学校多租户环境下的后台管理需求。

---

如需，我可以：

• 批量创建上述缺失页面的空壳（SFC + 路由注册）；
• 统一修正 layout.uvue 的路由与编码问题；
• 接好 pages.json 的后台路由并添加一个后台首页入口。