bbit/Common_Platform

Fork 0

Files

T

BBIT-Kai b8d25869c6 通用中后台框架第一版

2026-04-28 16:27:16 +08:00

14 KiB

Raw Blame History

通用中后台框架建设顺序

本文用于指导后续实现，按“先后端、再前端”的方式推进。整体分为四期：

一期：基础后端
二期：完整后端
三期：基础前端
四期：完整前端

原则：

后端先稳定数据模型、认证、权限和接口契约。
前端尽量基于真实接口开发，减少假数据页面返工。
每一期都要能编译、能启动、能验证，不留下半成品入口。
前端 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 风格统一，第一眼干净现代，细节有层次，交互动效轻快。

14 KiB Raw Blame History

通用中后台框架建设顺序

一期：基础后端

1. 整理后端基础结构

2. 完善公共能力

3. 完成数据库初始化

4. 完成种子数据

5. 完成认证能力

6. 完成权限基础能力

二期：完整后端

1. 用户管理接口

2. 组织管理接口

3. 角色管理接口

4. 菜单管理接口

5. 字典管理接口

6. 日志接口

7. 后端整体收口

三期：基础前端

1. 初始化前端工程

2. 建立 UI 视觉规范

3. 完成请求层

4. 完成登录和认证状态

5. 完成基础布局

6. 完成动态路由和权限控制

7. 完成基础字典缓存

四期：完整前端

1. 用户管理页面

2. 组织管理页面

3. 角色管理页面

4. 菜单管理页面

5. 字典管理页面

6. 日志页面

7. 页签栏和页面缓存完善

8. 整体体验打磨

14 KiB

Raw Blame History