Initial commit of akmon project

doc_admin/admin.md

@@ -0,0 +1,155 @@
+# 管理后台（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/...` 并补齐对应页面。
+    - 少量字符编码异常（`<60>?`），建议统一文件编码为 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. 字符编码：若文件出现 `<60>?`，请统一保存为 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` 的后台路由并添加一个后台首页入口。