forge-admin-blog-roadmap.md 22 KB
Forge Admin 技术与业务实现细节博客规划
目标：通过连续博客把 Forge Admin 从“后台管理框架”讲成“可落地的企业应用工程体系”，让读者理解项目的架构取舍、业务实现方式和二次开发价值，最终引导用户试用、收藏、加群、参与共建或落地使用。
1. 内容定位
1.1 核心叙事
Forge Admin 不只是在堆常见后台功能，而是在解决企业后台长期演进中的四类问题：
| 问题 | Forge Admin 的讲法 | 对应能力 |
|---|---|---|
| 业务页面交付慢 | 从表单、CRUD、导入导出到菜单权限，尽量配置化和生成化 | AiCrudPage、低代码 CRUD、AI 代码生成 |
| 企业权限复杂 | 认证、菜单、按钮、租户、数据权限分层处理 | Sa-Token、RBAC、多租户、DataScope |
| 系统能力难复用 | 技术能力沉到 Starter，业务能力做成 Plugin | 微内核、插件化、Spring Boot 自动配置 |
| 数据和流程要闭环 | 业务数据、审批流、消息、报表和 AI 能串起来 | Flowable、消息中心、AI 大屏、动态 API |
博客不要写成“功能清单”，要多写“为什么这样设计”、“一个真实业务需求怎么落到代码里”、“这个坑在企业项目里为什么常见”。
1.2 目标读者
| 读者 | 他们关心什么 | 内容侧重点 |
|---|---|---|
| 后端开发 | 架构分层、权限、租户、SQL、可扩展性 | Starter/Plugin、MyBatis XML、拦截器、注解、数据库迁移 |
| 前端开发 | 后台页面怎么快速搭、组件协议、权限菜单、文件图片 | AiCrudPage、动态路由、Naive UI、UnoCSS、上传组件 |
| 技术负责人 | 能不能支撑团队长期二开，规范是否完整 | 模块边界、SDD 流程、代码生成、测试和发布 |
| 产品/业务负责人 | 能不能快速搭业务系统和审批流程 | 低代码 CRUD、工作流、报表大屏、消息通知 |
| 开源用户 | 怎么跑起来、怎么二开、坑多不多 | 快速体验、真实案例、踩坑总结、对比文章 |
2. 栏目设计
建议拆成 5 个系列，每个系列解决一类读者问题。发布时不要按源码模块顺序机械展开，而是按“从看见价值到理解实现”的路径推进。
系列 A：架构底座篇
定位：建立项目专业感，让读者知道 Forge Admin 的骨架为什么适合长期维护。
| 期数 | 标题建议 | 核心问题 | 重点素材 |
|---|---|---|---|
| A01 | 从零搭一个企业后台，为什么我把能力拆成 Starter 和 Plugin？ | 微内核插件化到底解决什么问题 | forge-framework/forge-starter-parent、forge-plugin-parent、后端模块概览 |
| A02 | Spring Boot 3 后台框架的自动配置设计：少写配置，多做组合 | Starter 如何做到引入即生效 | AutoConfiguration.imports、code-copilot/knowledge/tech-spring-boot-autoconfig.md |
| A03 | Maven 多模块项目如何避免越写越乱？Forge Admin 的模块边界实践 | 多模块工程依赖如何分层 | forge-dependencies、父子 POM、tech-maven-multimodule.md |
| A04 | 统一响应、异常处理和日志：后台系统最容易被低估的基础设施 | 为什么基础规范决定二开体验 | forge-starter-core、forge-starter-web、全局异常文档 |
| A05 | 从配置到运行时：Forge Admin 的动态 API 配置管理是怎么做的 | API 行为如何集中管理和刷新 | forge-starter-api-config |
系列 B：权限、租户与安全篇
定位：这是企业后台最容易打动技术负责人的部分，适合做深度文章和对比文章。
| 期数 | 标题建议 | 核心问题 | 重点素材 |
|---|---|---|---|
| B01 | 后台权限不只是菜单隐藏：Forge Admin 的 RBAC 权限链路拆解 | 登录、菜单、按钮、接口权限如何闭环 | forge-starter-auth、系统管理插件、前端动态路由 |
| B02 | 多租户后台怎么做数据隔离？从 tenant_id 到拦截器的完整链路 | 租户隔离如何避免业务代码散落判断 | forge-starter-tenant、数据库规范 |
| B03 | 数据权限为什么必须写在 Mapper XML？DataScope 拦截器的工程取舍 | 组织/角色数据范围如何改写 SQL | forge-starter-datascope、XML SQL 规则 |
| B04 | 后台接口加解密实践：什么时候该用 @ApiEncrypt 和 @ApiDecrypt |
敏感接口如何保护传输数据 | forge-starter-crypto、前端 encrypt-request |
| B05 | 文件访问不能只返回 URL：Forge Admin 鉴权图片和文件存储设计 | 私有文件怎么在后台安全展示 | forge-starter-file、AuthImage、getFileUrl |
| B06 | 分布式幂等怎么落地到业务接口？从 Token 到 Redisson 锁 | 重复提交、重复审批、重复支付类问题 | forge-starter-idempotent、SpEL 知识库 |
系列 C：低代码与 AI 生成篇
定位：这是引流最强的系列，标题要更业务化，文章中再展开技术细节。
| 期数 | 标题建议 | 核心问题 | 重点素材 |
|---|---|---|---|
| C01 | 一个 CRUD 页面从 2 天到 10 分钟：AiCrudPage 的协议化设计 | 表格、搜索、表单、接口如何用一份配置驱动 | AiCrudPage 文档、前端组件源码 |
| C02 | 低代码 CRUD 搭建器如何把“业务字段”变成“可运行页面”？ | 模型协议、页面协议、发布态配置如何衔接 | lowcode-crud-builder.md、低代码组件 |
| C03 | 在线建表为什么要克制？Forge Admin 低代码 DDL 安全边界 | 为什么只允许建表和追加字段 | 低代码 DDL 约束、Flyway 规则 |
| C04 | AI 代码生成不是生成一坨代码：Forge Admin 的模板和配置思路 | AI 如何和模板、业务字段、下载代码包结合 | forge-plugin-generator、AI 生成变更文档 |
| C05 | 多 AI 供应商接入：如何让 OpenAI、DeepSeek、Ollama 等模型统一调用 | AI 供应商抽象和配置管理 | forge-plugin-ai、AI 供应商配置 |
| C06 | 从自然语言到数据大屏：Forge Report Studio 的 AI 生成链路 | 大屏结构、组件、主题、数据源如何生成和调整 | README AI 大屏、报表相关文章 |
| C07 | 大屏动态数据接入：从静态 Mock 到真实业务 API | 数据源、数据集、动态参数如何落地 | report datasource/dataset 变更文档 |
系列 D：业务场景实现篇
定位：把技术能力放进具体业务。读者看到的是“我能拿它做什么”，而不是“里面有什么模块”。
| 期数 | 标题建议 | 核心问题 | 重点素材 |
|---|---|---|---|
| D01 | 用户、角色、菜单、按钮权限：一个后台系统的权限业务闭环 | 系统管理模块如何支撑真实后台 | forge-plugin-system、菜单管理截图 |
| D02 | 字典系统为什么不能硬编码？从 DictSelect 到 DictTag 的前后端联动 | 状态、类型、标签如何统一维护 | 字典组件文档、useDict |
| D03 | 请假审批只是 Demo？用 Flowable 讲清业务流程接入方式 | 发起、审批、驳回、时间轴如何串起来 | forge-plugin-flow、BPMN 组件、流程文档 |
| D04 | 审批人动态计算：SPEL 表达式在工作流里的真实用法 | 节点审批人如何按业务变量计算 | tech-spel-expression.md、流程踩坑记录 |
| D05 | 消息中心怎么设计才不只是站内信？业务通知的统一入口 | 审批、系统通知、模板消息如何扩展 | forge-plugin-message、消息管理截图 |
| D06 | Excel 导入导出不要到处写临时代码：可配置导出的后台实践 | 导出列、字典翻译、脱敏如何统一 | forge-starter-excel、低代码导入导出 |
| D07 | 定时任务、操作日志和服务监控：后台运维能力如何内置 | 业务运行后如何排查和治理 | forge-plugin-job、forge-starter-log、监控截图 |
系列 E：工程规范与二开实战篇
定位：降低开源用户试用和二开门槛，把“能跑起来”和“能改得动”讲清楚。
| 期数 | 标题建议 | 核心问题 | 重点素材 |
|---|---|---|---|
| E01 | No Spec No Code：我在 Forge Admin 里如何做渐进式需求开发 | 为什么先写 spec/tasks 再编码 | forge-docs/guide/sdd-workflow.md、code-copilot/changes |
| E02 | 新增一个业务模块的标准姿势：从数据库脚本到菜单权限 | 二开用户最需要的完整路径 | AGENTS 规范、Flyway、Controller/Service/Mapper |
| E03 | Flyway 迁移脚本怎么写才不坑生产？ | 数据库变更如何可重复、可审查 | forge/db/migration、数据库脚本规范 |
| E04 | Forge Admin 常见踩坑 10 条：分页、占位符、租户、加解密 | 把真实踩坑转成用户信任 | .opencode/memory/pitfalls.md |
| E05 | 如何把 Forge Admin 裁剪成自己的业务中台？ | 哪些模块可选，哪些能力建议保留 | Starter/Plugin 模块清单 |
| E06 | 从本地启动到线上部署：Forge Admin 的环境配置和排查清单 | 新用户如何少踩环境坑 | README、应用配置、前后端启动命令 |
3. 首批 8 篇推荐排期
首批文章要同时兼顾“吸引点击”和“体现深度”。建议不要一开始就写太底层的自动配置，可以先用读者熟悉的场景开局。
| 周次 | 文章 | 目标 |
|---|---|---|
| 第 1 周 | C01：一个 CRUD 页面从 2 天到 10 分钟：AiCrudPage 的协议化设计 | 用效率提升吸引前后端开发 |
| 第 1 周 | B01：后台权限不只是菜单隐藏：Forge Admin 的 RBAC 权限链路拆解 | 建立企业后台专业感 |
| 第 2 周 | C02：低代码 CRUD 搭建器如何把“业务字段”变成“可运行页面”？ | 展示项目差异化能力 |
| 第 2 周 | D03：请假审批只是 Demo？用 Flowable 讲清业务流程接入方式 | 吸引有审批流需求的用户 |
| 第 3 周 | A01：从零搭一个企业后台，为什么我把能力拆成 Starter 和 Plugin？ | 讲清架构底座 |
| 第 3 周 | C06：从自然语言到数据大屏：Forge Report Studio 的 AI 生成链路 | 承接 AI 热点和产品截图 |
| 第 4 周 | B03：数据权限为什么必须写在 Mapper XML？DataScope 拦截器的工程取舍 | 打技术深度和工程可信度 |
| 第 4 周 | E04：Forge Admin 常见踩坑 10 条：分页、占位符、租户、加解密 | 用真实经验增强收藏和转发 |
发布频率建议：
- 每周 2 篇：1 篇偏业务/产品价值，1 篇偏技术实现。
- 每 4 周做一次合集文章：《Forge Admin 一个月技术文章索引：CRUD、权限、低代码、工作流》。
- 每篇末尾都放统一入口：GitHub/Gitee、在线演示、默认账号、文档站、交流群或联系方式。
4. 单篇文章模板
每篇建议固定成 7 段，降低后续写作成本。
# 标题：用一个具体问题开头
## 1. 这个问题在企业后台里为什么常见
用业务场景开头，避免直接贴源码。
## 2. Forge Admin 是怎么解决的
先给整体链路图或模块表。
## 3. 核心数据结构 / 配置协议
展示关键 DTO、Schema、配置字段或数据库表。
## 4. 核心实现链路
按请求入口、服务编排、持久化、前端渲染讲清楚。
## 5. 关键取舍和坑
解释为什么这么做，以及常见错误。
## 6. 如何二开
给出“如果你要新增一个类似功能，应该改哪些文件”。
## 7. 体验入口和下一篇预告
引导读者访问演示、收藏项目、阅读下一篇。
5. 每篇必备素材清单
为了让文章更像真实工程复盘，每篇至少准备 4 类素材。
| 素材 | 用途 | 示例 |
|---|---|---|
| 业务截图 | 让非技术读者知道功能长什么样 | 菜单管理、流程设计、低代码搭建器、大屏编辑器 |
| 链路图 | 让技术读者快速建立结构 | 请求链路、权限链路、低代码发布链路 |
| 关键代码片段 | 证明不是概念文章 | Controller、Service、Mapper XML、组件配置 |
| 踩坑提醒 | 增强可信度和收藏价值 | :id 占位符、pageNum、tenant_id=1、加解密注解 |
配图建议：
- 架构篇：模块依赖图、请求链路图、目录结构截图。
- 权限篇：登录到菜单加载链路、角色资源绑定截图、SQL 改写示意。
- 低代码篇：搭建器页面、协议 JSON、发布后运行页对比。
- 工作流篇：BPMN 设计器、节点配置、待办审批、流程时间轴。
- 大屏篇：AI 生成入口、画布编辑器、数据源配置、发布预览。
6. 重点文章详细大纲
6.1 C01：AiCrudPage 的协议化设计
目标读者：前端开发、全栈开发、想快速做后台页面的用户。
开篇问题：后台 CRUD 页面大量重复，搜索区、表格、弹窗表单、删除、分页、导入导出都类似，但每个页面又有少量差异。
核心大纲：
- 传统写法的问题：复制页面、复制接口、复制校验、复制字典渲染。
- AiCrudPage 的抽象：
columns、searchSchema、editSchema、apiConfig。 - 请求协议：
get@/api/user/page这类METHOD@URL格式如何统一解析。 - RESTful 默认约定：分页、新增、修改、删除、详情。
- 插槽和钩子：如何保留复杂业务扩展点。
- 常见坑：分页参数必须是
pageNum/pageSize，URL 占位符必须是:id。 - 二开建议：什么时候用 AiCrudPage，什么时候手写复杂页面。
转化动作：引导读者打开在线演示里的系统管理页面，再查看 AiCrudPage 文档。
6.2 B01：RBAC 权限链路拆解
目标读者：后端开发、技术负责人。
开篇问题：很多后台只做了“菜单隐藏”，但真实系统需要登录态、菜单、按钮、接口、数据范围一起闭环。
核心大纲：
- 权限模型：用户、角色、菜单、按钮、资源。
- 登录认证：Sa-Token 如何维护登录状态。
- 菜单权限：后端资源如何变成前端动态路由。
- 按钮权限：前端控制展示，后端接口继续兜底。
- 接口权限：
@SaCheckPermission的使用边界。 - 数据权限和租户权限为什么要单独拆出来讲。
- 二开建议：新增菜单、按钮权限和接口权限的步骤。
转化动作：引导读者体验菜单管理、角色授权、按钮权限。
6.3 C02：低代码 CRUD 发布链路
目标读者：产品/业务负责人、低代码平台开发者、全栈开发。
开篇问题：低代码如果只能画页面，最后还要开发手工接接口，就不能真正降本。
核心大纲：
- 搭建流程：数据模型、页面搭建、实时预览、发布上线。
modelSchema：字段、表名、业务名称、组件类型。pageSchema：搜索区、列表区、表单区、详情区。- 发布态配置：草稿不会影响线上，发布后写入版本快照。
- 动态 CRUD 运行时：白名单字段读写，避免任意字段操作。
- DDL 安全边界：只允许创建表和追加字段。
- 菜单和权限：发布后如何进入后台菜单体系。
转化动作：引导读者用一个“合同管理”或“客户管理”示例试搭。
6.4 D03：Flowable 工作流接入
目标读者：需要审批流、工单流、合同流的开发者。
开篇问题：审批流难点不是画 BPMN，而是业务表单、审批人、待办、时间轴和业务状态联动。
核心大纲：
- 工作流涉及的对象：模型、定义、实例、任务、审批记录。
- 前端 BPMN 设计器如何承载流程建模。
- 业务发起：业务数据和流程实例如何绑定。
- 节点配置：审批人、表单、按钮动作。
- 待办审批：通过、驳回、转办等动作如何进入流程引擎。
- 时间轴：为什么审批记录是业务用户最关心的部分。
- 踩坑：BPMN 属性 trim、SPEL 日志、流程定义不存在时的排查。
转化动作：引导读者体验“流程管理”和“我的待办”。
6.5 B03：DataScope 数据权限
目标读者：后端开发、架构师。
开篇问题：同一个列表接口，不同角色能看到的数据不同，最怕把权限条件散落在业务 Service 里。
核心大纲：
- 数据权限和菜单权限的区别。
- 为什么选择 MyBatis XML SQL 作为改写目标。
mapperMethod精确匹配的好处。- 组织、角色、区域等数据范围如何表达。
- 行政区划
ALL规则的 SQL 写法。 - 为什么查询类 SQL 不建议写在 Service 的
LambdaQueryWrapper。 - 二开建议：新增业务列表时如何预留数据权限能力。
转化动作：引导技术读者阅读数据权限模块文档和编码规范。
6.6 C06：AI 数据大屏生成链路
目标读者：产品、数据可视化开发者、企业内部工具负责人。
开篇问题：很多大屏工具只能拖组件，真正耗时的是从业务目标到布局、图表、数据源和发布的完整链路。
核心大纲：
- AI 生成大屏的输入：自然语言业务目标。
- 生成结果：画布、组件、布局、主题、静态数据。
- 人工编辑：拖拽、属性面板、素材库、多画布、弹窗。
- 数据接入：静态数据到动态 HTTP API。
- 发布预览：从编辑态到可访问页面。
- 多 AI 供应商：为什么要支持 OpenAI 兼容、自定义服务和本地模型。
- 二开建议：如何接入自己的业务接口和组件。
转化动作：放大屏设计器在线体验链接，建议读者用一个行业场景生成大屏。
7. 平台分发策略
不同平台的读者耐心不同，同一篇文章需要改标题和结构。
| 平台 | 内容形态 | 标题风格 | 重点 |
|---|---|---|---|
| 公众号 | 深度文章，2500-4000 字 | 场景化、结果导向 | 业务价值 + 架构解释 + 截图 |
| 掘金 | 技术拆解，2000-3500 字 | 技术关键词明确 | 源码链路、代码片段、坑 |
| CSDN | 教程型，1500-3000 字 | 搜索友好 | 快速上手、配置、问题解决 |
| Gitee/GitHub README | 精简入口 | 项目能力概览 | 引导 star、demo、文档 |
| 视频号/B 站 | 3-8 分钟演示 | 功能结果先行 | 录屏演示 + 关键架构图 |
同一选题可以拆成三种版本：
- 引流版：讲业务痛点和效果，少贴源码。
- 技术版：讲源码链路、模块边界和扩展点。
- 教程版：讲从 0 到 1 操作步骤。
8. 转化路径设计
每篇文章结尾建议固定放 5 个入口，形成稳定转化。
## 体验 Forge Admin
- 在线演示：后台管理 / 大屏设计器
- 默认账号：admin / 123456
- Gitee：ForgeLab/forge-admin
- GitHub：yaomindong1996/forge-admin
- 文档站：Forge Admin Docs
下一篇预告：xxx
转化目标分层：
| 用户行为 | 目标 |
|---|---|
| 点开文章 | 被具体场景吸引 |
| 看完文章 | 知道 Forge Admin 解决什么问题 |
| 访问演示 | 形成产品感知 |
| 收藏/star | 进入长期关注池 |
| 加群/咨询 | 转成潜在用户或贡献者 |
| 按教程二开 | 转成真实使用者 |
9. 内容生产流程
建议每篇文章按这个流程生产，避免写成散文。
- 选题确认：明确这篇给谁看，想让读者做什么。
- 素材收集：截图、代码路径、已有文档、踩坑记录。
- 大纲编写：先写 7 段模板，不急着展开。
- 代码核对：确认文章里的类名、接口、参数和当前代码一致。
- 截图补齐：每篇至少 2 张业务截图或链路图。
- 发布适配：公众号/掘金/CSDN 标题和开头分别调整。
- 数据复盘：记录阅读量、收藏、star 增量、演示访问量、咨询数。
10. 文章质量标准
一篇合格的 Forge Admin 博客至少满足：
- 有明确业务场景，不从“本模块提供”开头。
- 有一张链路图或表格，让读者 30 秒理解结构。
- 有 1-3 个真实代码/配置片段，但不堆大段源码。
- 有“为什么这样设计”的解释。
- 有“二开时怎么做”的落地步骤。
- 有“常见坑/边界”的提醒。
- 有项目入口和下一篇预告。
需要避免：
- 只罗列功能，没有实现细节。
- 只贴源码，没有业务场景。
- 标题过大，正文落不到 Forge Admin。
- 文章里暴露真实密钥、数据库密码、Token、生产地址敏感信息。
- 把还不稳定或暂未开放的能力写成已完整支持。
11. 可直接进入写作的选题池
优先级 P0：最适合近期引流。
| 优先级 | 选题 |
|---|---|
| P0 | AiCrudPage 协议化 CRUD |
| P0 | 低代码 CRUD 搭建器 |
| P0 | RBAC 权限链路 |
| P0 | Flowable 审批流接入 |
| P0 | AI 数据大屏生成 |
| P0 | Forge Admin 常见踩坑 |
优先级 P1：适合做技术深度和收藏。
| 优先级 | 选题 |
|---|---|
| P1 | Starter/Plugin 插件化架构 |
| P1 | DataScope 数据权限 |
| P1 | 多租户隔离 |
| P1 | 分布式幂等 |
| P1 | 文件存储和鉴权图片 |
| P1 | Excel 导入导出 |
优先级 P2：适合后续完善内容矩阵。
| 优先级 | 选题 |
|---|---|
| P2 | API 加解密 |
| P2 | 动态配置 |
| P2 | 消息中心 |
| P2 | 定时任务 |
| P2 | 操作日志 |
| P2 | WebSocket |
| P2 | 社交登录 |
12. 建议的第一篇文章
第一篇建议写：
《一个 CRUD 页面从 2 天到 10 分钟：Forge Admin 的 AiCrudPage 是怎么设计的？》
原因：
- 读者感知强，所有后台开发都写过重复 CRUD。
- 能自然带出 Forge Admin 的前端组件、RESTful API、字典、导入导出、权限和低代码能力。
- 文章难度适中，适合作为系列入口。
- 后续可以顺接低代码 CRUD、AI 代码生成和数据权限。
第一篇末尾预告：
下一篇我们继续拆：低代码 CRUD 搭建器如何把业务字段、页面配置、动态接口和菜单权限串成一个可发布的后台应用。