# rbac-project **Repository Path**: Job_Wang/rbac-project ## Basic Information - **Project Name**: rbac-project - **Description**: RBAC0 权限管理系统(课程验收) - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-21 - **Last Updated**: 2026-11-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README = 市政统一权限管理系统 前端使用 Vue 3、TypeScript 和 Tailwind CSS。后端使用 Java 21、Spring Boot、Spring MVC、Spring Data JPA。JWT 使用 RS256,由 Spring Security 验证,角色和权限按请求实时查询。 后端请求依次经过 Controller、Service 和 Repository。Service 负责权限规则和事务,Repository 负责持久化。MySQL 保存六个核心实体及其关联、管理范围。权限目录统一为菜单/按钮树,父子关系不自动授予权限;角色权限和账号状态在请求时实时查询。业务审计、会话和角色版本机制已移除,普通运行错误日志保留。 角色与角色继承提供两种可切换实现,并共用 Controller、OpenAPI、前端、JPA 实体和数据库。默认 +RBAC_BACKEND_STRATEGY=structured+ 使用事务脚本;设置为 +object-oriented+ 时由角色聚合和继承策略维护直接权限、继承边、无环及保护规则。两种模式都使用同一组真实 HTTP 行为契约,不需要切换表或迁移数据。当前双实现边界集中在 RBAC1 角色核心;认证、人员目录、系统目录及持久化适配器是两种模式的共享支撑。 == 本机运行 需要 Java 21、Maven、Node.js、MySQL 服务端命令。macOS 启动脚本自动选择已安装的 Java 21。前端与后端分开运行,也可用 +npm run dev+ 同时运行。 [source,bash] ---- npm ci npm run db:up # 初始化四个明确标注的演示账号,仅用于本地开发。 RBAC_DEMO_SEED=true npm run dev:api # 另一个终端 npm run dev:web ---- 需要运行面向对象实现时,在启动后端前设置 +RBAC_BACKEND_STRATEGY=object-oriented+。同一数据库同一时刻只需运行一种策略,切换前停止旧后端进程即可。 访问 http://127.0.0.1:5173,API 位于 http://127.0.0.1:3100/api。 已有旧数据库必须先备份并停止旧后端,依次执行 +deploy/migrations/2026-11-14-permission-tree-simplification.sql+、+deploy/migrations/2026-11-14-role-inheritance.sql+。新库直接使用 +schema.sql+;迁移脚本不能重复执行。移除的 MongoDB 审计集合不再访问,旧存储数据由维护者按备份策略处理。 === 本机前端读取服务器数据 浏览器不能直接连接 MySQL。本机开发前端通过 Vite 的 +/api+ 代理访问后端。默认代理目标是本机 +127.0.0.1:3100+;需要查看服务器数据时,先建立到服务器 Nginx 的 SSH 隧道,再把代理目标设为隧道本地端口: [source,bash] ---- # 终端一:保持 SSH 隧道运行 ssh -N -L 18082:127.0.0.1:80 root@120.46.86.237 # 终端二:从项目目录启动本机前端 VITE_API_PROXY_TARGET=http://127.0.0.1:18082 VITE_API_ENV_LABEL="服务器 API(SSH 隧道)" npm run dev:web ---- 访问 http://127.0.0.1:5173。该页面的 +/api+ 请求会经过本机 Vite、SSH 隧道、服务器 Nginx,最终到达服务器后端和 MySQL。先打开 http://127.0.0.1:5173/api/health 确认返回 +{"status":"ok"}+;然后重新登录服务器账号,进入人员授权,选择“Excel 导入员工”,清空搜索框并查询。若端口已占用,请复用已运行的隧道或换一个本地端口,并让 +VITE_API_PROXY_TARGET+ 与之相同。不要把 MySQL 端口暴露到公网。 本次工作区已配置使用本机端口 +18082+ 的隧道;该隧道由 SSH 密钥认证并保持运行。重新打开终端或电脑重启后,需要重新建立隧道并用相同代理目标启动 Vite。服务器当前后端可查询 10,000 名导入员工;本地最新版新增的多系统管理写接口尚未部署到服务器,不能据此在服务器上修改系统目录。 本地演示管理员:+demo.admin+ / +AdminDemo!2026+。演示员工:+demo.user+ / +UserDemo!2026+。受限部门管理员:+demo.limited+ / +LimitedDemo!2026+。这些账号都是虚构测试账号,与 Excel 员工无关联;启动时不会自动给真实员工分配角色或设置统一密码。 本地多系统演示另含“市政设施巡检系统”(系统 ID +demo-facility+),系统管理员:+demo.facility.admin+ / +FacilityDemo!2026+。管理员能力由普通角色权限提供;部门范围限制可管理人员,系统范围限制可查看系统,角色涉及的系统不得越过该范围。只有全局演示管理员能修改系统、权限和 API 目录。演示数据在 +RBAC_DEMO_SEED=true+ 时建立,不会写入生产环境。 开发 MySQL 使用项目 +.local/mysql+,仅监听 127.0.0.1:53306,开发账号为空密码;不允许沿用该配置部署生产。现有系统 MySQL 实例不受此脚本管理。本轮实体仓储与权限树回归使用独立 MySQL 8.4.8。 配置环境变量见 +.env.example+;Spring Boot 从进程环境读取,+.env+ 不会自动加载。RSA 与隐私密钥默认位于 +.local/keys+,不要删除密钥后继续使用同一个数据库。 == 导入提供的 Excel 用包含 openpyxl 的 Python 执行: [source,bash] ---- python3 scripts/prepare-import.py --source /path/to/excel-directory # 停止之前的 API,再启动一次带导入文件的进程。 RBAC_DEMO_SEED=true RBAC_IMPORT_FILE=../.local/import.json npm run dev:api ---- Maven 应用的工作目录为 +backend+。首次导入在一个事务内写入:10000 名员工、111 个组织、18 套应用目录和 359 个功能点。原始 JSON 保留在 Git 忽略的 +.local+,姓名和手机号在数据库中加密,默认接口返回脱敏姓名;全局管理员的人员页面可按页读取完整姓名、岗位和脱敏手机号;手机号用 HMAC 唯一索引。员工保持暂停、无密码、无角色。 重复运行采用相同源标识,不重复创建身份;这不是 HR 持续同步,现有员工资料与任职不会被自动替换。五种角色模板以停用状态导入,不导入未审核的角色权限矩阵。+全部+、本人范围、空值与 view 归一记录保留在私有 JSON 的 review 列表。原功能动作目录有 808 个候选操作权限(含 17 个应用准入);模块、功能目录现统一为未授权菜单节点,不等于已确认或已授予权限。 演示应用另有 OA、工程项目两套,页面总数会包含它们,不能当成原始资料统计。真实 API 路径未提供,现有映射仅展示演示配置。 == 验证 先启动独立测试 MySQL,准备 +rbac_test+、+rbac_jpa_test+、+rbac_tree_test+、+rbac_migration_test+,为测试用户 +rbac+ 授予各测试库权限。测试数据库可清空,不得使用业务库。 [source,bash] ---- npm test npm run build npm run build:api # JaCoCo 后端测试与覆盖率报告(需先启动独立测试 MySQL) bash scripts/backend.sh verify ---- 测试连接独立 MySQL 并启动真实 HTTP 服务。覆盖身份 JWT、显式权限并集、实时撤权、管理员越权、权限树结构、父子权限独立授权、旧库升级及六实体 JPA 仓储。JWT 不再绑定服务端会话:退出清除浏览器内存中的令牌,刷新页面需重新登录,已签发令牌在到期前仍可能有效;账号暂停/离职即时拒绝访问。 JaCoCo 报告由 +verify+ 阶段生成,HTML 报告位于 +backend/target/site/jacoco/index.html+,不提交构建产物。 验收步骤:管理员检索 +demo.user+,查看授权,选择演示工程部来源,分配公文查阅员;权限验证页使用员工凭据检查 +demo-oa / document:view+;撤销角色后再次检查应拒绝。 == 规格与共同记忆 最终交付包含界面原型、API 设计、数据库设计、详细设计、华为云 MySQL 部署与 Spring Boot 后端部署;现场先展示完整流程,再随机调用接口查看真实数据。见 link:docs/ACCEPTANCE.adoc[验收清单]、link:docs/detailed-design.adoc[详细设计]与link:deploy/README.adoc[部署说明]。 * link:docs/SDD-RBAC0.adoc[需求草案]、link:docs/requirements/CONFLICTS.adoc[来源冲突]、link:docs/requirements/TRACEABILITY.adoc[需求追溯]。 * link:docs/design.adoc[技术决策]、link:docs/database/ER.adoc[数据库设计文档(ER 图与数据表说明)]、link:docs/database/rbac-current-er.jpg[ER 图图片]、link:docs/database/rbac-current.er.mmd[完整 ER 图源文件]、link:backend/src/main/resources/schema.sql[MySQL 建表 SQL]。 * link:docs/CODE-GUIDE.md[项目目录与代码阅读导读]说明各目录职责和建议阅读顺序;link:docs/DATABASE-ER-BACKEND-GUIDE.md[数据库表结构、ER 图与后端代码详解]按表和代码逐步说明实现。 * link:docs/api/openapi.json[OpenAPI],供 Apifox 导入;已验证官方 MCP 本地 OAS 与云端项目8930412读取。 * link:docs/STATUS.adoc[项目状态]保存已完成能力、未决项与剩余工作;link:docs/APIFOX_ACCEPTANCE_GUIDE.adoc[Apifox 验收指南]可供队友照步骤调用 API。 * link:docs/DEFENSE-PREP.adoc[助教与教师检查答辩准备]汇总项目问答、演示顺序、JaCoCo 结果和课程实验待核对项。 准备可迁移源码部署包:+bash scripts/package-release.sh+。生成结果位于被 Git 忽略的 +.local/release+,不包含 Excel、导入明文、数据库目录或密钥。该打包步骤与现有华为云验收环境分开,服务器现状以 link:deploy/README.adoc[部署说明] 和验收时的健康检查为准。 +.agents/skills+ 保存 grill-me、grilling、tdd、frontend-design 快照。真实数据、数据库文件、依赖、构建输出和密钥不提交。目标仓库为 https://github.com/WangJiabo0905/rbac-project;用户授权以当前项目替换旧代码,原 main 已做完整历史备份,同步结果以远端提交校验为准。 == 尚未交付 批量授权、临时账号维护、部门冻结管理页面、HR/OA 与真实外部系统对接、数据库记录防篡改、生产部署及正式性能验收。当前为基础迭代,不是全部需求完成版。 == 本轮权限目录整改 菜单和按钮共用 +permissions+;+kind+ 区分 menu/button,+parent_id+ 表达父子关系。系统管理支持创建、编辑、移动节点,角色管理以独立复选框树维护显式授权,勾选父节点不会联动子节点。拒绝跨系统父节点、成环及按钮含子节点;有子节点、角色引用或 API 映射时不能删除。 接口以 link:docs/api/openapi.json[本地契约] 为准,旧文档中的日志页、刷新 Cookie 和角色版本参数已过时;本次未向远端部署或同步 Apifox。角色自联系现已实现:上级继承下级有效权限,支持传递、去重与即时撤销;管理范围按继承闭包检查。面向功能与面向对象两种独立实现仍有后续工作。 == 角色管理 全局管理员在角色管理页创建停用的角色草稿,选择应用并勾选权限,启用后保存。进入应用与操作权限分别选择,未授准入即拒绝访问。编辑前显示关联人数,角色权限变化对已有 JWT 的后续鉴权立即生效。平台初始化角色只读,受限管理员不能编辑共享角色。 Apifox 本地 MCP 验证:+npm run mcp:check+,说明见 link:docs/api/APIFOX.adoc[Apifox 接入]。 == RBAC1 角色继承 角色管理页在当前上级角色中选择下级角色并保存继承关系。上级继承下级的直接及传递权限;相同权限只返回一次,下级不反向获得上级权限。空下级集合撤销直接继承;其他有效路径和直接授权保留,不复制或删除其权限。 不存在角色返回404;自继承、成环或受保护系统管理角色参与维护返回409。继承边及角色启停变化对已有 JWT 的后续鉴权即时生效。停用角色中断其继承路径;范围校验包含停用下级,避免重新启用后越界。已有数据库增加 +role_inheritances+ 表,不为存量角色自动配置继承。