# 通用中后台框架建设顺序 本文用于指导后续实现，按“先后端、再前端”的方式推进。整体分为四期： 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 风格统一，第一眼干净现代，细节有层次，交互动效轻快。