AI Coding 项目案例：企业组织架构与 RBAC 权限管理系统

这是 AI 通识课第三次作业的项目记录。项目依据第六天课件 7.8 节的实战主题"基于 RBAC 模式的企业级组织架构和权限管理的实现"完成，目标是做出一个可以本地运行、可以演示、可以测试的前后端分离 MVP。

一、项目要解决的问题

企业内部管理系统通常同时处理组织、用户、角色和权限四类数据。如果只在前端隐藏菜单，用户仍然可能直接调用接口，因此权限控制必须由后端完成。这个项目把权限抽象为"用户通过角色获得权限"，并用权限码控制菜单和 API。

本次作业保留三个演示角色：

• 超级管理员：管理组织、用户、角色和权限；
• 部门管理员：可以查看组织和用户，但不能修改角色及权限；
• 普通员工：只能访问工作台和自己的基础信息。

项目范围经过主动收敛，没有加入 Redis、MySQL 生产部署、多租户、真实审计日志、短信找回密码和云端部署。这些内容不属于本次 MVP 的验收重点。

二、为什么先写 Spec

课件将 SDD（Spec-Driven Development，规范驱动开发）作为 AI Coding 的重要方法：先把"做什么"写清楚，再在设计文档中确定"怎么做"，最后编码和验证。

因此项目没有直接从页面或数据库开始，而是先建立了三个文档：

• spec.md：定义角色、功能范围、权限边界、异常场景和验收标准；
• design.md：确定技术栈、目录结构、数据表、API 约定和测试策略；
• tasks.md：把实现拆成数据库、认证、业务 API、前端和测试任务。

这样的拆分解决了两个实际问题。第一，AI 生成代码时有明确边界，不容易把项目扩展成没有验收标准的大系统。第二，测试可以直接对应规格中的验收标准，而不是只验证"页面能打开"。

三、技术方案

后端采用 Python、FastAPI 和 Uvicorn，数据库使用 SQLite，密码使用 bcrypt 哈希，登录认证使用 JWT。前端使用 HTML5、CSS3 和原生 JavaScript，通过fetch调用后端 API，避免引入构建工具和大型依赖，使课程项目可以快速启动。

主要数据表如下：

departments 组织部门 users 用户 roles 角色 permissions 权限 user_roles 用户与角色关联 role_permissions 角色与权限关联

数据库首次启动时会自动建表并插入演示数据。系统内置 4 个部门、3 个用户、3 个角色和 9 个权限，方便直接演示不同角色之间的差异。

认证和授权流程是：

1. 用户提交用户名和密码；
2. 后端校验密码哈希和账号状态；
3. 登录成功后签发 JWT；
4. 受保护接口从 Bearer Token 获取当前用户；
5. 后端查询用户的角色权限并执行权限依赖；
6. 前端根据当前用户权限渲染菜单，但菜单隐藏不作为安全边界。

四、AI Coding 的开发流程

1. 读取课程资料并确认范围

先浏览 AI 通识课文件夹，定位第六天课件，并确认本次项目主题、可选技术栈以及 SDD/TDD 相关要求。根据课程给出的 Python、SQLite、H5/CSS/TS 等选择空间，项目最终采用 Python + SQLite + 原生 HTML/CSS/JavaScript。

2. 把需求整理为可验收条目

规格文档中没有只写"做一个权限系统"，而是把需求拆成登录、组织架构、用户管理、角色权限、权限控制和数据约束。例如：

• 普通员工请求用户接口必须返回 403；
• 部门有子部门或成员时不能删除；
• 用户响应中不能出现密码字段；
• 登录后普通员工不显示用户管理和角色权限菜单。

这些条目都能通过 API 测试或浏览器测试验证。

3. 依据设计文档实现后端

后端先完成 SQLite 初始化和种子数据，再实现认证依赖、权限依赖和业务服务，最后接入 FastAPI 路由。组织、用户、角色和权限的处理集中在服务层，路由层负责参数校验、权限依赖和错误状态码转换。

实现时特别保留了两层权限控制：

• 前端根据权限隐藏没有访问资格的菜单；
• 后端每个受保护接口再次校验权限。

这样即使用户绕过页面直接请求接口，也不能获得越权数据。

4. 实现前端工作台

页面采用控制台布局，包含登录页、工作台、组织架构、用户管理和角色权限五个视图。新增和编辑操作使用统一弹窗表单，减少重复页面代码。页面还处理了加载状态、错误提示、退出登录和移动端基本宽度适配。

前端没有把权限判断写成唯一安全逻辑，而是把/api/auth/me返回的权限用于界面展示；真正的权限判断仍然由 FastAPI 后端负责。

5. 测试驱动的校验与调试

API 测试覆盖了以下场景：

1. 管理员登录和当前用户信息；
2. 错误密码被拒绝；
3. 普通员工访问用户 API 被拒绝；
4. 部门管理员可以读取组织，但不能创建角色；
5. 删除仍有子部门的部门被拒绝；
6. 管理员可以创建用户和角色，且密码不会返回。

浏览器测试使用本机 Microsoft Edge，验证了管理员登录、管理员菜单、组织架构页面、普通员工菜单权限和 390 像素移动端页面。

开发过程中遇到两个实际问题。第一个是组织页面点击后立即断言文本，异步请求尚未完成，测试偶发找不到"技术研发部"；处理方式是等待该节点真正出现在页面后再断言。第二个是组织树没有子节点时渲染了"暂无组织数据"，这与树组件的递归结构不一致，后来让空节点直接返回空字符串。

五、验证结果

在项目根目录执行：

python -m pytest -q

结果为：

6 passed

随后启动 Uvicorn，并执行浏览器检查脚本，结果为：

browser_check: PASS

浏览器验证还检查了移动端页面没有横向溢出。测试过程中出现 FastAPIon_event的弃用警告，这是当前依赖版本的 API 迁移提示，不影响本次功能验收，后续可改为 lifespan 写法。

六、项目边界与后续改进

当前版本是课程作业级 MVP，不应直接当作生产系统使用。后续如果继续开发，可以优先完成：

• 将 SQLite 迁移到 MySQL；
• 使用环境变量管理 JWT 密钥；
• 增加操作审计日志；
• 增加更细粒度的数据范围权限；
• 使用 Vue3 或 TypeScript 重构前端；
• 增加 CI 自动测试和部署配置；
• 将 FastAPI 的弃用事件处理迁移到 lifespan。

这次开发最重要的收获不是让 AI 一次生成全部代码，而是把需求、设计、实现和验证串成了一个可检查的流程。AI 可以加快代码和页面的生成，但开发者仍然需要确认课程要求、控制项目范围、检查权限边界，并用测试证明功能确实完成。

另外附上个人Git仓库连接：433525/-，供大家参考