BBIT-Kai
566 lines
14 KiB
Markdown
566 lines
14 KiB
Markdown
# 通用中后台框架建设顺序
|
|
|
|
本文用于指导后续实现，按“先后端、再前端”的方式推进。整体分为四期：
|
|
|
|
1. 一期：基础后端
|
|
2. 二期：完整后端
|
|
3. 三期：基础前端
|
|
4. 四期：完整前端
|
|
|
|
原则：
|
|
|
|
- 后端先稳定数据模型、认证、权限和接口契约。
|
|
- 前端尽量基于真实接口开发，减少假数据页面返工。
|
|
- 每一期都要能编译、能启动、能验证，不留下半成品入口。
|
|
- 前端 UI 统一走极简、圆角、干净、高端、现代、有层次感、有动效、年轻化的中后台风格。
|
|
- 新增代码保持 UTF-8 编码。
|
|
|
|
## 一期：基础后端
|
|
|
|
目标：把后端基础设施和认证权限闭环跑起来，为前端提供稳定接口契约。
|
|
|
|
### 1. 整理后端基础结构
|
|
|
|
- 保持当前 `server` 工程结构。
|
|
- 保留 `common`、`config`、`plugins`、`database/system`、`database/business`。
|
|
- 新增必要目录：
|
|
- `security`
|
|
- `bootstrap`
|
|
- `modules/auth`
|
|
- 模块内部只按需要创建 `Routes`、`Service`、`Dtos`，不创建空文件。
|
|
|
|
验收：
|
|
|
|
- `./gradlew.bat compileKotlin` 通过。
|
|
- `/health` 可访问。
|
|
- 应用启动日志清晰，无无关异常。
|
|
|
|
### 2. 完善公共能力
|
|
|
|
- 补充分页模型：
|
|
- `PageQuery`
|
|
- `PageResult`
|
|
- 补充错误码模型：
|
|
- `ErrorCode`
|
|
- 补充 traceId 机制：
|
|
- 每个请求生成 traceId。
|
|
- 异常响应返回 traceId。
|
|
- 日志输出 traceId。
|
|
- 保持统一响应：
|
|
- 成功：`code = "0"`
|
|
- 失败：稳定错误码 + 中文错误信息。
|
|
|
|
验收：
|
|
|
|
- 所有接口响应统一为 `ApiResult`。
|
|
- 业务异常、参数异常、未知异常都进入统一异常处理。
|
|
- 失败响应包含 traceId。
|
|
|
|
### 3. 完成数据库初始化
|
|
|
|
- 在 `bootstrap` 中实现数据库初始化。
|
|
- 使用当前 `database/system` 下的表定义创建系统基础表。
|
|
- 暂时以 Exposed 表定义表达结构，后续生产前再决定是否迁移到正式迁移工具。
|
|
- 主数据表按默认软删除设计：
|
|
- `deleted_at`
|
|
- `deleted_by`
|
|
- 关系表和日志表不强制软删除。
|
|
|
|
验收：
|
|
|
|
- 空数据库启动后能完成建表。
|
|
- 重复启动不会因为表已存在导致失败。
|
|
- 初始化失败时服务启动失败，不进入半可用状态。
|
|
|
|
### 4. 完成种子数据
|
|
|
|
- 在 `bootstrap/SeedData.kt` 中维护初始化数据。
|
|
- 初始化数据必须可重复执行。
|
|
- 默认写入：
|
|
- 默认组织
|
|
- 管理员用户 `admin`
|
|
- 超级管理员角色
|
|
- 基础菜单
|
|
- 基础权限码
|
|
- 基础字典
|
|
- 管理员账号固定为 `admin`，初始化密码固定写入后端种子数据，首次登录后可在系统内修改。
|
|
|
|
验收：
|
|
|
|
- 空库启动后存在 `admin` 用户。
|
|
- 存在超级管理员角色。
|
|
- 存在基础菜单和权限码。
|
|
- 多次启动不会重复插入相同数据。
|
|
|
|
### 5. 完成认证能力
|
|
|
|
- 实现密码处理：
|
|
- 密码哈希。
|
|
- 密码校验。
|
|
- 实现 JWT 服务：
|
|
- 签发 access token。
|
|
- 校验 issuer、audience、token_type。
|
|
- 写入 `sub`、`username`、`orgId`、`roles`、`tokenVersion`。
|
|
- 实现认证接口：
|
|
- `POST /api/auth/login`
|
|
- `POST /api/auth/logout`
|
|
- `GET /api/auth/me`
|
|
|
|
验收：
|
|
|
|
- `admin` 可以登录。
|
|
- 登录失败返回稳定错误码。
|
|
- `/api/auth/me` 返回当前用户、菜单树、权限码。
|
|
- 用户禁用后不能继续登录。
|
|
- `tokenVersion` 变化后旧 token 失效。
|
|
|
|
### 6. 完成权限基础能力
|
|
|
|
- 实现当前用户上下文。
|
|
- 实现 `requirePermission`。
|
|
- 后端接口必须显式声明权限码。
|
|
- 超级管理员拥有全部权限。
|
|
|
|
验收：
|
|
|
|
- 未登录访问受保护接口返回 401。
|
|
- 登录但无权限返回 403。
|
|
- 有权限用户可以访问对应接口。
|
|
|
|
## 二期：完整后端
|
|
|
|
目标：完成后端全部基础模块接口，形成稳定的中后台 API 能力。
|
|
|
|
### 1. 用户管理接口
|
|
|
|
接口范围：
|
|
|
|
- `GET /api/system/users`
|
|
- `POST /api/system/users`
|
|
- `GET /api/system/users/{id}`
|
|
- `PUT /api/system/users/{id}`
|
|
- `DELETE /api/system/users/{id}`
|
|
- `PUT /api/system/users/{id}/status`
|
|
- `PUT /api/system/users/{id}/password`
|
|
- `PUT /api/system/users/{id}/roles`
|
|
|
|
要求：
|
|
|
|
- 支持分页查询。
|
|
- 支持按用户名、昵称、状态、组织查询。
|
|
- 新增用户时校验用户名唯一。
|
|
- 删除默认软删除。
|
|
- 修改密码更新 `tokenVersion`。
|
|
- 分配角色要校验角色状态。
|
|
|
|
验收：
|
|
|
|
- 用户 CRUD 可完整调用。
|
|
- 软删除用户默认不出现在列表。
|
|
- 用户角色分配后 `/api/auth/me` 权限生效。
|
|
|
|
### 2. 组织管理接口
|
|
|
|
接口范围：
|
|
|
|
- `GET /api/system/orgs`
|
|
- `POST /api/system/orgs`
|
|
- `PUT /api/system/orgs/{id}`
|
|
- `DELETE /api/system/orgs/{id}`
|
|
|
|
要求：
|
|
|
|
- 组织按树结构返回。
|
|
- 编码唯一。
|
|
- 删除组织前校验是否存在子组织或用户。
|
|
- 系统内置组织可禁止删除。
|
|
|
|
验收：
|
|
|
|
- 组织树排序稳定。
|
|
- 有引用的组织不能删除。
|
|
|
|
### 3. 角色管理接口
|
|
|
|
接口范围：
|
|
|
|
- `GET /api/system/roles`
|
|
- `POST /api/system/roles`
|
|
- `GET /api/system/roles/{id}`
|
|
- `PUT /api/system/roles/{id}`
|
|
- `DELETE /api/system/roles/{id}`
|
|
- `PUT /api/system/roles/{id}/menus`
|
|
|
|
要求：
|
|
|
|
- 角色编码唯一。
|
|
- 支持启用、禁用。
|
|
- 删除前校验是否被用户使用。
|
|
- 角色菜单分配同时决定菜单权限和按钮权限。
|
|
|
|
验收：
|
|
|
|
- 角色 CRUD 可完整调用。
|
|
- 角色分配菜单后用户权限正确变化。
|
|
|
|
### 4. 菜单管理接口
|
|
|
|
接口范围：
|
|
|
|
- `GET /api/system/menus`
|
|
- `POST /api/system/menus`
|
|
- `PUT /api/system/menus/{id}`
|
|
- `DELETE /api/system/menus/{id}`
|
|
|
|
要求：
|
|
|
|
- 菜单按树结构返回。
|
|
- 菜单类型：
|
|
- `CATALOG`
|
|
- `MENU`
|
|
- `BUTTON`
|
|
- `MENU` 类型可配置路由路径、组件标识、图标、缓存。
|
|
- `BUTTON` 类型配置权限码。
|
|
- 删除菜单前校验是否存在子菜单或角色引用。
|
|
|
|
验收：
|
|
|
|
- `/api/auth/me` 返回的菜单树能直接供前端生成动态菜单。
|
|
- 权限码能覆盖页面和按钮操作。
|
|
|
|
### 5. 字典管理接口
|
|
|
|
接口范围：
|
|
|
|
- `GET /api/system/dict-types`
|
|
- `POST /api/system/dict-types`
|
|
- `PUT /api/system/dict-types/{id}`
|
|
- `DELETE /api/system/dict-types/{id}`
|
|
- `GET /api/system/dict-items`
|
|
- `POST /api/system/dict-items`
|
|
- `PUT /api/system/dict-items/{id}`
|
|
- `DELETE /api/system/dict-items/{id}`
|
|
|
|
要求：
|
|
|
|
- 字典类型编码唯一。
|
|
- 字典项按类型查询。
|
|
- 字典项支持排序、状态、颜色。
|
|
- 代码枚举和业务字典边界清晰，安全规则不依赖可配置字典。
|
|
|
|
验收：
|
|
|
|
- 常用字典可供前端缓存。
|
|
- 禁用字典项不影响历史数据展示。
|
|
|
|
### 6. 日志接口
|
|
|
|
接口范围：
|
|
|
|
- `GET /api/logs/operation`
|
|
- `GET /api/logs/api-access`
|
|
|
|
要求：
|
|
|
|
- 操作日志记录关键后台操作。
|
|
- 开放接口调用日志保留表结构和查询能力。
|
|
- 敏感字段脱敏：
|
|
- 密码不记录。
|
|
- token 不记录。
|
|
- Authorization 不记录原文。
|
|
- 大请求体不记录 body。
|
|
|
|
验收：
|
|
|
|
- 登录、失败登录、新增、修改、删除、分配角色等关键操作有日志。
|
|
- 日志查询支持分页和时间范围。
|
|
|
|
### 7. 后端整体收口
|
|
|
|
- 补齐接口参数校验。
|
|
- 补齐错误码。
|
|
- 补齐权限码。
|
|
- 补齐基础接口测试。
|
|
- 检查所有接口是否统一返回 `ApiResult`。
|
|
|
|
验收：
|
|
|
|
- `./gradlew.bat test` 通过。
|
|
- `./gradlew.bat compileKotlin` 通过。
|
|
- 后端接口能支撑前端完整开发。
|
|
|
|
## 三期：基础前端
|
|
|
|
目标：搭建 SPA 单页应用基础框架，打通登录、布局、动态菜单和权限控制。
|
|
|
|
### 1. 初始化前端工程
|
|
|
|
- 使用 Vue 3、TypeScript、Vite。
|
|
- 接入 Vue Router、Pinia、TanStack Query、Naive UI、Tailwind CSS、Axios、lucide-vue-next。
|
|
- 配置 ESLint、Prettier、Vitest。
|
|
|
|
验收：
|
|
|
|
- 前端可启动。
|
|
- 基础路由可访问。
|
|
- 构建无 TypeScript 错误。
|
|
|
|
### 2. 建立 UI 视觉规范
|
|
|
|
- 在前端工程初始化阶段同步建立全局 UI 基调。
|
|
- 风格关键词：
|
|
- 极简
|
|
- 圆角
|
|
- 干净
|
|
- 高端
|
|
- 现代
|
|
- 有层次感
|
|
- 有动效
|
|
- 年轻化
|
|
- 使用 Naive UI 主题统一：
|
|
- 主色
|
|
- 圆角
|
|
- 字体
|
|
- 组件尺寸
|
|
- 边框颜色
|
|
- 浅阴影
|
|
- 使用 Tailwind CSS 统一：
|
|
- 页面背景
|
|
- 间距尺度
|
|
- 内容面板
|
|
- 响应式布局
|
|
- 过渡动画
|
|
- 视觉要求：
|
|
- 整体留白克制，信息密度适中。
|
|
- 页面背景使用浅灰或近白色，主体内容使用白色面板。
|
|
- 卡片、按钮、输入框、弹窗保持统一圆角。
|
|
- 阴影轻、边框细，层次通过背景、边框、间距和轻阴影表达。
|
|
- 不使用厚重阴影、大面积渐变、复杂纹理和花哨装饰。
|
|
- 图标统一使用 lucide-vue-next，线性、轻量、现代。
|
|
- 交互动效保持轻快，例如 hover、active、展开收起、弹窗进入、页签切换。
|
|
- 动效只服务反馈和层次，不做干扰操作的炫技动画。
|
|
|
|
验收：
|
|
|
|
- 已配置 Naive UI 全局主题。
|
|
- 已配置 Tailwind 全局基础样式。
|
|
- 基础按钮、表单、表格、弹窗、菜单、页签视觉风格一致。
|
|
- UI 第一眼呈现干净、现代、高端、年轻的后台系统气质。
|
|
|
|
### 3. 完成请求层
|
|
|
|
- 封装 `api/http.ts`。
|
|
- 自动附加 JWT。
|
|
- 统一处理 `ApiResult`。
|
|
- 处理 401、403。
|
|
- 记录 traceId。
|
|
- 封装 TanStack Query client。
|
|
|
|
验收：
|
|
|
|
- 登录接口可真实调用。
|
|
- 业务错误能统一提示。
|
|
- 401 能跳转登录页。
|
|
|
|
### 4. 完成登录和认证状态
|
|
|
|
- 完成登录页。
|
|
- 登录页要体现整体 UI 风格：
|
|
- 极简布局。
|
|
- 清爽背景。
|
|
- 圆角登录面板。
|
|
- 轻量动效。
|
|
- 高端、年轻、现代的视觉气质。
|
|
- 登录后保存 token。
|
|
- 调用 `/api/auth/me` 获取当前用户、菜单、权限码。
|
|
- Pinia 保存：
|
|
- token
|
|
- 当前用户
|
|
- 菜单树
|
|
- 权限码
|
|
- 布局状态
|
|
- 字典缓存
|
|
|
|
验收：
|
|
|
|
- `admin` 可登录进入后台。
|
|
- 刷新页面后可恢复登录状态。
|
|
- 退出登录后清理本地状态。
|
|
|
|
### 5. 完成基础布局
|
|
|
|
- 完成后台主布局。
|
|
- 包含：
|
|
- 侧边菜单
|
|
- 顶部栏
|
|
- 面包屑
|
|
- 页签栏
|
|
- 内容区
|
|
- 整体风格保持极简、圆角、干净、高端、现代、工作台化。
|
|
- 布局层次要求：
|
|
- 侧边栏、顶部栏、页签栏、内容区层次清晰。
|
|
- 内容区以浅背景承托白色内容面板。
|
|
- 面板不堆叠卡片，不做厚重装饰。
|
|
- 菜单展开收起、页签切换、内容进入要有轻量过渡。
|
|
|
|
验收：
|
|
|
|
- 菜单可展开、收起。
|
|
- 当前路由高亮正确。
|
|
- 页面在常见桌面宽度下无明显错位。
|
|
- 布局整体干净、有层次感，交互动效自然不突兀。
|
|
|
|
### 6. 完成动态路由和权限控制
|
|
|
|
- 根据 `/api/auth/me` 返回菜单生成动态路由。
|
|
- 支持 `keepAlive` 页面缓存。
|
|
- 无权限路由进入 403。
|
|
- 未匹配路由进入 404。
|
|
- 实现权限按钮组件。
|
|
|
|
验收：
|
|
|
|
- 后端菜单变化后，重新登录可生效。
|
|
- 无菜单权限不能进入页面。
|
|
- 无按钮权限不显示操作按钮。
|
|
|
|
### 7. 完成基础字典缓存
|
|
|
|
- 登录后加载常用字典，或按需加载。
|
|
- 字典缓存放入 Pinia。
|
|
- 页面可通过统一方法读取字典标签、颜色、状态。
|
|
|
|
验收：
|
|
|
|
- 用户状态、组织状态、角色状态、菜单类型等字典可正常展示。
|
|
|
|
## 四期：完整前端
|
|
|
|
目标：完成全部管理页面和体验打磨，形成可复制的页面开发模式。
|
|
|
|
### 1. 用户管理页面
|
|
|
|
- 先做用户管理，作为标准 CRUD 样板。
|
|
- 用户管理页面同时作为 UI 样板页，沉淀列表页标准风格。
|
|
- 包含：
|
|
- 查询
|
|
- 分页
|
|
- 新增
|
|
- 编辑
|
|
- 删除
|
|
- 启用禁用
|
|
- 重置密码
|
|
- 分配角色
|
|
- 使用 TanStack Query 管理列表和详情。
|
|
- UI 要求：
|
|
- 查询区轻量、紧凑、干净。
|
|
- 表格信息层次清晰，行 hover 有轻量反馈。
|
|
- 主要操作按钮突出但不厚重。
|
|
- 弹窗表单圆角、留白舒适、校验反馈清晰。
|
|
- 加载、空状态、错误状态风格统一。
|
|
|
|
验收：
|
|
|
|
- 用户管理从前端到后端完整可用。
|
|
- 新增、编辑、删除后缓存刷新正确。
|
|
- 错误、空状态、加载状态完整。
|
|
- 页面观感符合极简、现代、高端、年轻化要求。
|
|
|
|
### 2. 组织管理页面
|
|
|
|
- 组织树展示。
|
|
- 新增、编辑、删除组织。
|
|
- 删除前端提示引用限制。
|
|
- 支持排序和状态展示。
|
|
|
|
验收：
|
|
|
|
- 组织树展示稳定。
|
|
- 有子组织或用户引用时删除失败提示清晰。
|
|
|
|
### 3. 角色管理页面
|
|
|
|
- 角色列表。
|
|
- 新增、编辑、删除角色。
|
|
- 启用、禁用角色。
|
|
- 菜单权限分配。
|
|
- 按钮权限展示。
|
|
|
|
验收：
|
|
|
|
- 角色菜单分配后用户重新登录权限生效。
|
|
- 超级管理员角色有明确标识。
|
|
|
|
### 4. 菜单管理页面
|
|
|
|
- 菜单树管理。
|
|
- 支持目录、菜单、按钮三种类型。
|
|
- 支持图标、路由、组件标识、权限码、排序、缓存配置。
|
|
|
|
验收：
|
|
|
|
- 菜单调整后重新登录可影响左侧菜单和动态路由。
|
|
- 权限码调整后按钮显示和接口权限一致。
|
|
|
|
### 5. 字典管理页面
|
|
|
|
- 字典类型管理。
|
|
- 字典项管理。
|
|
- 支持颜色、排序、状态。
|
|
- 字典项变更后刷新相关缓存。
|
|
|
|
验收：
|
|
|
|
- 字典展示和筛选可复用。
|
|
- 禁用字典项有清晰展示。
|
|
|
|
### 6. 日志页面
|
|
|
|
- 操作日志查询页面。
|
|
- 开放接口调用日志查询页面。
|
|
- 支持时间范围、状态、用户、路径等常用筛选。
|
|
|
|
验收：
|
|
|
|
- 日志列表可分页查询。
|
|
- 敏感字段不在页面展示。
|
|
|
|
### 7. 页签栏和页面缓存完善
|
|
|
|
- 页签支持：
|
|
- 切换
|
|
- 关闭
|
|
- 关闭其他
|
|
- 关闭全部
|
|
- 刷新当前页签
|
|
- 页面缓存支持：
|
|
- 按菜单 `keepAlive` 缓存。
|
|
- 权限变化后清理不可访问页签。
|
|
- 退出登录后清理全部缓存。
|
|
|
|
验收：
|
|
|
|
- 多页面切换状态稳定。
|
|
- 刷新当前页签不影响其他页签。
|
|
|
|
### 8. 整体体验打磨
|
|
|
|
- 按极简、圆角、干净、高端、现代、有层次感、有动效、年轻化的目标统一全站视觉。
|
|
- 统一空状态。
|
|
- 统一加载状态。
|
|
- 统一错误状态。
|
|
- 统一删除确认。
|
|
- 统一表单校验。
|
|
- 统一权限缺失提示。
|
|
- 统一页面进入、弹窗、抽屉、菜单展开、页签切换、按钮反馈等动效。
|
|
- 检查圆角、边框、阴影、间距、字体、图标是否一致。
|
|
- 检查页面是否存在厚重阴影、花哨渐变、拥挤表单、过度装饰等问题。
|
|
- 补齐前端基础测试。
|
|
|
|
验收：
|
|
|
|
- 前端构建通过。
|
|
- 核心页面无明显布局错位。
|
|
- 常用管理流程可连续完成。
|
|
- 全站 UI 风格统一，第一眼干净现代，细节有层次，交互动效轻快。
|