lab-edu 管理后台框架选型提案

本提案已于 2026-10-29 经用户整稿确认正式采用；采用的是框架方向及职责边界，不把最小前端实验等同于完整集成通过。 需求输入：鉴权需求与后台需求，两份均已正式批准。技术设计和精确构建版本由后续 Plan 与构建配置承接。

1. 已批准结论

采用 Refine CORE 5.x，配套官方 Next.js 路由适配及 Ant Design UI 适配。 推荐理由是可沿用 Next.js App Router，以通用表格、表单、导航和 provider（适配接口）连接既有服务端职责，不改变 web → core 的边界。此采用结论基于项目匹配度判断，不是官方对本项目兼容性的保证。[S1][S2][S3]

候选版本线为 @refinedev/core 5.x、@refinedev/nextjs-router 7.x、@refinedev/antd 6.x、antd 5.x；包名相近但主版本并不相同。官方主分支的 UI 适配包声明依赖 antd ^5.23.0，不能因 Ant Design 官网已显示 6.x 就混装。[S8][S9]

推荐有条件成立：本轮已执行隔离安装和最小界面构建验证，详见兼容报告（本地资料，未发布）。它只验证候选前端组合，不代表已完成真实注册、登录、授权或会话联调。官方路由适配包的 next: "*" 本身也不构成已测试所有版本的证据。[S10]

2. 选型边界

必须满足：

  1. web 使用 Next.js App Router，仅负责展示、交互和调用 core；最终认证、授权、业务校验及数据写入由 Spring Boot / Spring Security 承担。
  2. 优先采用成熟框架组件，不自行实现通用表格、表单、后台布局或权限引擎。
  3. 当前只服务账户、角色、权限、菜单的基础平台管理，不设计实验任务、报告、评分。
  4. 不自动采用模板中的消息、报表、导入导出、实时订阅或审计增强功能。
  5. 本稿推荐采用社区开源包；这是降低许可证和采购成本的提案取舍，既有宪法没有禁止付费方案。

必须区分的两件事

框架提供 CRUD 页面构件与认证/授权扩展点，不等于已经提供 lab-edu 的账户模型、三角色配置、密码重置、最后一个管理员保护、会话撤销或完整权限与菜单管理。这些项目规则仍需 Spec、服务端实现及页面装配。[S2][S3][S4]

因此，路线图中的“基于框架自带能力”在本提案中指复用通用界面与适配机制。若评审原意是“直接获得无需业务开发的完整用户/角色/权限/菜单系统”，本次推荐不能满足，必须先重新评审该需求，不能用“框架自带”掩盖适配开发量。

本轮反馈：细粒度权限与自助注册

  • 可行性：细粒度许可与当前技术路线兼容。Spring Security 提供基于 authority 的请求与方法授权；Refine 提供 resource/action 形式的展示许可适配接口。项目仍需定义权限目录与绑定关系，框架不会自动生成这些业务规则。[S2][S15]
  • 已确认粒度：支持“资源 × 操作”并按角色分配；例如 users:read、users:disable、users:reset-password、roles:grant-permissions，这些标识仅为命名示意，最终目录在后台设计中按批准需求确定。能查看用户不隐含能禁用用户，进入管理区不隐含获得全部操作许可。
  • 已确认分配方式与配套建议：权限组成角色，角色关联账户。后台需求规定保留三个内置角色、允许自定义角色、每账户一个角色，以支持只读管理账户；原“权限目录先只读”的推荐撤回。本期不加入个人授权例外；自定义角色等范围已经随整稿确认，规则引用正式后台规格。
  • 边界：前端只消费 core 的有效许可，不能复制角色权限映射；core 对操作及必要的本人资源归属分别判定。本期不加入通用行级或字段级授权，不设计实验业务的数据权限；不引入通用条件授权引擎。
  • 撤权效果：权限集合变更后撤销受影响账户全部会话，并在重新登录后读取新许可；防止仅隐藏按钮或使用过期缓存导致撤权无效。该配套规则已随整稿批准。
  • 注册流程：普通用户自助注册，不再依赖管理员逐个创建。默认 student、注册者不能自选 teacher/admin 或夹带权限；首位管理员仍由 core 的受控初始化产生。注册页和接口适配需列入 auth 交付，后端负责唯一性、输入校验与防注册提权。
  • 注册与会话的关系：注册完成回登录入口，用户使用本人密码登录；管理员重置密码的恢复场景继续保留。无新增身份服务或消息发送依赖。

3. 候选比较

以下为定性比较；未进行本地性能、工时或可用性测量，也不按未经核实的 star 数打分。

维度 Refine CORE + Ant Design React-admin 社区版 Ant Design Pro 完整脚手架
Next.js 接入 官方提供 Next.js 路由集成及 App Router 用法 [S1] 官方支持；文档采用客户端管理应用并关闭该部分服务端渲染 [S5] 官方当前示例采用 Umi；直接采用完整脚手架不符合本项目 Next.js 基线 [S7]
通用管理界面 官方表格、表单、布局与资源页构件；需装配项目页面 [S3] 成熟资源型 CRUD 页面及导航；需定义资源与字段 [S4] 完整管理界面示例；迁移到 Next.js 需额外改造 [S7]
对接 core dataProvider / authProvider 对接项目接口；不能默认后端恰好兼容 [S2][S11] dataProvider / authProvider 对接项目接口 [S4][S6] 需要将脚手架的请求、路由与权限接入方式重新适配，属于项目判断
权限展示 accessControlProvider 返回展示许可；最终判定仍来自 core [S2] 社区版已有 canAccess 等扩展点；专门的 ra-rbac 为企业模块，不能误判为所有权限能力都收费 [S6][S4] 不能将示例中的前端权限判断当成服务端授权
文档与学习成本 文档覆盖所需适配点；需学习资源、provider 与客户端组件边界，属本项目成本判断 资源型后台文档完整；需处理客户端应用嵌入与项目路由衔接，属本项目成本判断 直接使用示例需了解 Umi；迁移另需 Next.js 经验
社区与维护证据 官方公开仓库、发行记录及 v5 文档持续可访问；不能由此保证后续维护 [S1][S12] 官方仓库与版本化文档可访问；官方介绍维护主体为 Marmelab [S4][S13] Ant Design 官方公开仓库与当前预览可访问 [S7]
许可证边界 Refine 仓库为 MIT；直接与传递依赖另核查 [S12] 社区版 MIT；企业扩展另有商业条件 [S4] 官方仓库 MIT；不因此改变架构适配结论 [S7]
本稿结论 首选，进入兼容验证 有效备选，不因收费误解排除；当前更倾向直接沿用 App Router 的集成方式 不采用完整脚手架；独立 Ant Design 组件与完整 Pro 脚手架分别判断

Decision / Rationale / Alternatives

  • Decision：建议采用 §1 的 Refine 版本线，先完成最小集成验证，再锁定依赖。
  • Rationale：保留既定路由体系；官方界面适配与 provider 边界可以承接通用管理需求；避免迁移完整脚手架。它仍需要项目适配，并非零开发方案。
  • Alternative 1 — React-admin：不是不可用，也不需要为基础权限接入必然采购；本次暂不采用，是因为官方 Next.js 方式将管理区作为客户端应用嵌入，而本项目优先直接沿用 App Router 资源页面。若 Refine 兼容验证失败，可回到此方案评审。[S5][S6]
  • Alternative 2 — Ant Design Pro 完整脚手架：暂不采用，原因是当前 Umi 技术路线与既定 Next.js 基线不同；迁移会增加需要维护的代码。单独采用 Ant Design 不等于采用整个脚手架。[S7][S9]
  • Alternative 3 — 只用 Ant Design 手工搭后台：组件能接入 Next.js，但仍需自行组织资源页面、数据请求状态及登录流程；在成熟管理框架可用时不作为默认方案。若验证后确需此方案，按宪法 §4 提交理由评审。[S9]

4. 推荐方案的职责划分

位置 拟复用或适配的能力 不得放入的规则
web / Next.js 页面路由、布局、用户交互、加载/失败展示 业务授权、账户状态裁决、密码核实、数据库访问
Refine + Ant Design 资源列表、分页/筛选界面、表单、资源菜单、登录页构件 不将资源注册、隐藏按钮或页面重定向当成权限来源
dataProvider 调用 core 的已批准契约，转换列表、总数与错误表示 不复制账户规则，不用模板假数据替代真实后端
authProvider 调用 core 的登录、退出与当前身份能力，解释结果并更新界面 不签发另一套身份凭证，不接入另一个身份系统
accessControlProvider 消费 core 给出的允许操作，控制按钮与导航展示 不在 web 另写角色到权限的裁决表，不增加第二个权限引擎
core / Spring Security 自助注册、凭证核实、会话、逐操作授权、输入校验与数据读写 不依赖 web 是否隐藏入口来保护数据；不信任注册者提交的角色与权限
infra 按后续部署设计组织服务与网络 不写账户初始化或业务权限规则；业务初始化由 core 承担

登录后的传输与会话方案留给 auth Plan；本提案不选择令牌或会话存储方式。若使用浏览器自动携带凭证，技术设计必须覆盖跨站请求防护、跨域与安全属性；不将官方教程的 mock 用户、可读 Cookie 或本地凭证示例直接当作生产设计。

页面身份查询只用于展示与导航；core 必须对每次受保护操作自行判定。身份失败时清除前一账户的页面缓存，防止切换账户后残留数据。UI 内操作结果提示属于交互反馈，不据此引入路线图排除的消息通知系统。

5. 框架复用与项目工作量边界

目标 框架可复用部分 项目仍需交付
注册/登录/退出 注册与登录表单构件、认证 hooks、provider 接口 自助注册契约、唯一性与防提权；core 鉴权与会话；连接 provider；改密与失败场景页面
用户管理 列表、表单、分页/筛选交互、操作按钮 账户契约、字段装配、启用/禁用、角色分配、密码重置及保护规则；管理员创建账户不再是普通注册的前置条件
角色与权限 通用资源页、选择器与展示许可接口 操作级权限目录、自定义角色与绑定编辑、授权范围及最后管理员保护；具体范围见后台需求，已随整稿批准；本期无个人例外
菜单 资源导航及菜单展示构件 选择由批准资源声明生成导航还是可编辑菜单；本稿不承诺动态菜单编辑已完成

本轮建议交付角色与已有操作权限的绑定配置，不再以目录只读替代权限管理；后台 Spec 须明确谁能赋权、可授予哪些许可、如何保护最后管理员及如何撤销旧授权。权限目录与菜单编辑是不同能力，不能由此推导任意新增权限或动态菜单编辑已获批准。

本次没有为范围外能力申请“框架自带”的豁免。依赖中包含通用功能不等于已授权将其暴露为产品能力；未评审的功能不注册入口、不启用示例服务。

6. 版本、许可证与维护风险

已核查事实与证据局限

  • Refine 主分支快照显示 core 为 5.x、Next.js 适配为 7.x、Ant Design 适配为 6.x；快照不是已发布包的安装证明，不作为最终精确版本。[S8][S10][S14]
  • UI 适配声明 antd ^5.23.0 与 React 18/19；Next.js 适配声明 next: "*"，其开发依赖仍列 Next.js 14.x。需要验证实际目标版本，不能只看范围满足。[S8][S10]
  • 本稿仅确认主要候选的顶层许可证信息；传递依赖许可证、是否含需单独处理的资产及供应链问题，在锁版本时检查。没有执行法律兼容性审计。
  • 官方文档与主分支、发行记录可能不同步；立项时检查已发布稳定包元数据、发行说明与维护状态，不能从文章或主分支猜最新稳定版。

控制方式

  1. Next.js 遵守宪法“当前最新稳定版”，不得为了适配静默降级；若候选不兼容，停止锁版本，改选候选或提案评审。
  2. Spring Boot 保持宪法限定的 3.x 系列；“最新稳定”不能解释成自动跨主版本升级。其精确版本与 JDK 配套由 auth Plan 查询官方资料后决定。
  3. 精确依赖在构建配置及锁文件中落地，本文只维护版本线；禁止用强制安装或忽略 peer dependency 冲突证明兼容。
  4. 主干分支地址可变，后续记录实际采用的发布版本、提交标识及核查日期，便于重现。

7. 后续兼容验证与通过门槛

本节是完整验证清单；本次已完成的最小前端验证和未完成的后端集成分别记录在兼容报告。不能将局部成功等同于整张清单已通过。用户本轮“继续”授权下执行的是独立草稿目录的兼容实验，未将候选依赖写入正式仓库。

门槛 必须保留的证据 失败处理
稳定版本与依赖 官方发布信息、包元数据、精确版本、运行时要求；干净安装无未处理依赖冲突 不强装、不降级既定基线；返回选型评审
App Router 与 UI 生产构建通过；资源页直接访问/刷新正常；中文布局、表格和表单无样式或 hydration 错误 记录复现路径与错误，不宣称文档支持等于实际通过
数据适配 用一页真实用户列表核对分页、总数、筛选、失败返回与空结果 修订契约适配；不为了模板便利改写业务规则
登录闭环 core 登录、当前身份、退出联调；未登录/失效/拒绝访问区分正确 返回 auth 设计，不增加独立前端身份系统
自助注册 普通账户注册后可登录；重复/并发注册不覆盖账户；夹带 teacher/admin 或权限信息均不能提权 修正 core 注册边界，不依赖表单隐藏字段
权限安全 无对应许可时绕过界面发起管理操作被 core 拒绝；仅有查看许可不允许禁用；web 没有角色权限裁决表；授权变更撤销全部受影响旧会话 修正服务端授权及 UI 消费方式，按已确认方向与后续批准的配套策略编写测试
缓存与隔离 退出和切换账户后旧身份及旧列表不再展示 修正缓存清理再复验
范围与依赖许可 实际依赖清单与许可证核查；未启用范围外示例；组件与业务代码边界说明 删除越界接入或返回评审

完整认证、授权、会话单元测试属于宪法质量底线；兼容验证不能替代这些测试，也不能用 mock 登录证明正式会话撤销成功。

8. 宪法检查与联动影响

原则 具体检查问题 当前结论 证据
§2 分层 web 是否只调用 core，身份与权限是否仍由 core 最终决定？ 通过：方案层面；实现待验证 本文 §4、§7
§3 技术栈 是否维持 Next.js 与 Spring Security，候选版本兼容是否已实测？ 通过：框架方向与前端最小组合已批准/验证；真实后端与部署继续作为后续门槛 本文 §1、§6、§7
§4 框架优先 是否说明框架复用、自定义适配及至少两个替代方案？ 通过：选型已随整稿批准 本文 §3、§5
§5 KISS/DRY 是否引入第二套身份库或权限引擎？ 通过：提案未引入 本文 §4
§5 质量 是否保留认证、授权、会话的单元测试要求？ 通过：要求已列，测试尚未执行 本文 §7
§7 治理 新依赖是否已批准并留 ADR？ 通过：选型已批准；新增依赖采用记录见 ADR-001 本文 §9
§8 范围 是否借框架启用实验业务或范围外能力？ 通过：只批准基础平台，未增加范围外能力 本文 §2、§5

本表结论属于采用方向与已记录证据，不代表后端或部署验收通过，也不授权绕过宪法。

本次批准后的联动状态：

  • 已在 ADR-001 记录 Accepted 决策及影响。
  • 本提案已正式归档，批准前原文与资料核查日期保留在历史快照。
  • 已按宪法 §7 同步 §3、版本与 Sync Impact Report，已同步路线图第 2 条。
  • 两份正式规格已定义各自交付；技术设计与任务位于 platform-001，其中后端新依赖另有 Proposed ADR，不因本次框架采用自动获准。

9. 正式评审结论

2026-10-29 用户针对整稿评审包确认“好的，我已经确定，请你继续。”，批准框架采用方向、两份需求及规范分工与 Git 粒度修订。技术自查结论经用户确认，未记录不存在的独立评审人。详见批准记录（本地资料，未发布）。

  • Refine CORE 5.x、官方 Next.js 路由适配、官方 Ant Design 适配及 Ant Design 5.x 为正式方向。
  • 管理角色、授权、菜单与恢复保护的唯一需求来源为正式后台规格。
  • 本次同步项目宪法 §3、路线图与 ADR-001；后端真实集成和部署门槛继续保留。
  • 早期草案原文及每阶段未批准状态保存在批准前快照，不能据其旧状态否定本次批准。

10. 官方资料索引

核查日期统一为 2026-10-29（北京时间）。链接为官方文档或官方仓库；主分支与在线文档会变化。没有将搜索摘要的“最新”字样当成已安装版本。