# 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 段，降低后续写作成本。

```md
# 标题：用一个具体问题开头

## 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 页面大量重复，搜索区、表格、弹窗表单、删除、分页、导入导出都类似，但每个页面又有少量差异。

核心大纲：

1. 传统写法的问题：复制页面、复制接口、复制校验、复制字典渲染。
2. AiCrudPage 的抽象：`columns`、`searchSchema`、`editSchema`、`apiConfig`。
3. 请求协议：`get@/api/user/page` 这类 `METHOD@URL` 格式如何统一解析。
4. RESTful 默认约定：分页、新增、修改、删除、详情。
5. 插槽和钩子：如何保留复杂业务扩展点。
6. 常见坑：分页参数必须是 `pageNum/pageSize`，URL 占位符必须是 `:id`。
7. 二开建议：什么时候用 AiCrudPage，什么时候手写复杂页面。

转化动作：引导读者打开在线演示里的系统管理页面，再查看 AiCrudPage 文档。

### 6.2 B01：RBAC 权限链路拆解

目标读者：后端开发、技术负责人。

开篇问题：很多后台只做了“菜单隐藏”，但真实系统需要登录态、菜单、按钮、接口、数据范围一起闭环。

核心大纲：

1. 权限模型：用户、角色、菜单、按钮、资源。
2. 登录认证：Sa-Token 如何维护登录状态。
3. 菜单权限：后端资源如何变成前端动态路由。
4. 按钮权限：前端控制展示，后端接口继续兜底。
5. 接口权限：`@SaCheckPermission` 的使用边界。
6. 数据权限和租户权限为什么要单独拆出来讲。
7. 二开建议：新增菜单、按钮权限和接口权限的步骤。

转化动作：引导读者体验菜单管理、角色授权、按钮权限。

### 6.3 C02：低代码 CRUD 发布链路

目标读者：产品/业务负责人、低代码平台开发者、全栈开发。

开篇问题：低代码如果只能画页面，最后还要开发手工接接口，就不能真正降本。

核心大纲：

1. 搭建流程：数据模型、页面搭建、实时预览、发布上线。
2. `modelSchema`：字段、表名、业务名称、组件类型。
3. `pageSchema`：搜索区、列表区、表单区、详情区。
4. 发布态配置：草稿不会影响线上，发布后写入版本快照。
5. 动态 CRUD 运行时：白名单字段读写，避免任意字段操作。
6. DDL 安全边界：只允许创建表和追加字段。
7. 菜单和权限：发布后如何进入后台菜单体系。

转化动作：引导读者用一个“合同管理”或“客户管理”示例试搭。

### 6.4 D03：Flowable 工作流接入

目标读者：需要审批流、工单流、合同流的开发者。

开篇问题：审批流难点不是画 BPMN，而是业务表单、审批人、待办、时间轴和业务状态联动。

核心大纲：

1. 工作流涉及的对象：模型、定义、实例、任务、审批记录。
2. 前端 BPMN 设计器如何承载流程建模。
3. 业务发起：业务数据和流程实例如何绑定。
4. 节点配置：审批人、表单、按钮动作。
5. 待办审批：通过、驳回、转办等动作如何进入流程引擎。
6. 时间轴：为什么审批记录是业务用户最关心的部分。
7. 踩坑：BPMN 属性 trim、SPEL 日志、流程定义不存在时的排查。

转化动作：引导读者体验“流程管理”和“我的待办”。

### 6.5 B03：DataScope 数据权限

目标读者：后端开发、架构师。

开篇问题：同一个列表接口，不同角色能看到的数据不同，最怕把权限条件散落在业务 Service 里。

核心大纲：

1. 数据权限和菜单权限的区别。
2. 为什么选择 MyBatis XML SQL 作为改写目标。
3. `mapperMethod` 精确匹配的好处。
4. 组织、角色、区域等数据范围如何表达。
5. 行政区划 `ALL` 规则的 SQL 写法。
6. 为什么查询类 SQL 不建议写在 Service 的 `LambdaQueryWrapper`。
7. 二开建议：新增业务列表时如何预留数据权限能力。

转化动作：引导技术读者阅读数据权限模块文档和编码规范。

### 6.6 C06：AI 数据大屏生成链路

目标读者：产品、数据可视化开发者、企业内部工具负责人。

开篇问题：很多大屏工具只能拖组件，真正耗时的是从业务目标到布局、图表、数据源和发布的完整链路。

核心大纲：

1. AI 生成大屏的输入：自然语言业务目标。
2. 生成结果：画布、组件、布局、主题、静态数据。
3. 人工编辑：拖拽、属性面板、素材库、多画布、弹窗。
4. 数据接入：静态数据到动态 HTTP API。
5. 发布预览：从编辑态到可访问页面。
6. 多 AI 供应商：为什么要支持 OpenAI 兼容、自定义服务和本地模型。
7. 二开建议：如何接入自己的业务接口和组件。

转化动作：放大屏设计器在线体验链接，建议读者用一个行业场景生成大屏。

## 7. 平台分发策略

不同平台的读者耐心不同，同一篇文章需要改标题和结构。

| 平台 | 内容形态 | 标题风格 | 重点 |
|------|----------|----------|------|
| 公众号 | 深度文章，2500-4000 字 | 场景化、结果导向 | 业务价值 + 架构解释 + 截图 |
| 掘金 | 技术拆解，2000-3500 字 | 技术关键词明确 | 源码链路、代码片段、坑 |
| CSDN | 教程型，1500-3000 字 | 搜索友好 | 快速上手、配置、问题解决 |
| Gitee/GitHub README | 精简入口 | 项目能力概览 | 引导 star、demo、文档 |
| 视频号/B 站 | 3-8 分钟演示 | 功能结果先行 | 录屏演示 + 关键架构图 |

同一选题可以拆成三种版本：

- 引流版：讲业务痛点和效果，少贴源码。
- 技术版：讲源码链路、模块边界和扩展点。
- 教程版：讲从 0 到 1 操作步骤。

## 8. 转化路径设计

每篇文章结尾建议固定放 5 个入口，形成稳定转化。

```md
## 体验 Forge Admin

- 在线演示：后台管理 / 大屏设计器
- 默认账号：admin / 123456
- Gitee：ForgeLab/forge-admin
- GitHub：yaomindong1996/forge-admin
- 文档站：Forge Admin Docs

下一篇预告：xxx
```

转化目标分层：

| 用户行为 | 目标 |
|----------|------|
| 点开文章 | 被具体场景吸引 |
| 看完文章 | 知道 Forge Admin 解决什么问题 |
| 访问演示 | 形成产品感知 |
| 收藏/star | 进入长期关注池 |
| 加群/咨询 | 转成潜在用户或贡献者 |
| 按教程二开 | 转成真实使用者 |

## 9. 内容生产流程

建议每篇文章按这个流程生产，避免写成散文。

1. 选题确认：明确这篇给谁看，想让读者做什么。
2. 素材收集：截图、代码路径、已有文档、踩坑记录。
3. 大纲编写：先写 7 段模板，不急着展开。
4. 代码核对：确认文章里的类名、接口、参数和当前代码一致。
5. 截图补齐：每篇至少 2 张业务截图或链路图。
6. 发布适配：公众号/掘金/CSDN 标题和开头分别调整。
7. 数据复盘：记录阅读量、收藏、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 搭建器如何把业务字段、页面配置、动态接口和菜单权限串成一个可发布的后台应用。