BlogLoom 博客专栏规划
一、专栏愿景
把 Markdown 内容编织成可创作、可发布、可运营、可持续演进的博客系统。BlogLoom 的博客专栏不只介绍如何搭建一个博客页面，而是完整记录一套内容工程系统从需求、模型、接口、前端交互到部署运维的实现过程。每一篇文章都尽量对应仓库中的真实代码、设计文档或可运行的验证步骤，读者可以沿着文章理解“为什么这样设计”，也可以直接运行项目验证“这样设计是否可靠”。 BlogLoom 的内容主线不是单向的文章 CRUD，而是一条完整闭环：
- 系统如何分层，后端、CMS、博客前台如何协作；
- 一篇文章如何从 Markdown 变成数据库中的内容实体；
- 图片、封面和附件如何上传、归档、访问和清理；
- 知识库、专栏和批量迁移如何解决内容整理问题；
- 内容如何被搜索引擎、读者和外部分发渠道消费；
- 系统如何被部署、升级、监控和持续维护。
1.1 专栏定位
- 面向对象：希望理解博客系统工程实现的 Java / Vue 开发者、个人站长和开源项目贡献者。
- 内容风格：原理解释 + 源码拆解 + 接口/数据流 + 可运行实战 + 边界复盘。
- 代码原则：文章中的结论必须能在当前仓库代码、SQL、前端页面或设计文档中找到依据。
- 演进原则：代码已经支持的能力优先沉淀；仍在设计中的能力明确标记为规划项，不把设想写成现状。
1.2 文章类型与命名规范
每篇文章建议使用以下格式：
完成进度使用以下标记：
[已完成]：仓库已有对应实现或设计文档，可直接整理为博客；[进行中]：已有部分代码或方案，仍需补齐验证、示例或文章内容；[规划中]：后续随着功能演进再实现和撰写。
这里的“已完成”表示已有可复用的代码/设计素材，不等同于文章已经发布到官网。
二、第一层：系统架构与工程基础
目标：先让读者建立 BlogLoom 的全局认知，再理解后续每个模块为什么这样拆分。
2.1 系统全貌与模块边界
BlogLoom 的核心组成如下：
2.2 数据流总览
一篇文章从创建到展示，至少会经过以下边界：- 数据在哪一层产生，在哪一层校验；
- 哪些内容是数据库字段，哪些内容是正文中的 Markdown；
- 哪些操作必须放在同一个事务中；
- 一个失败发生后，文件、数据库、缓存和前端状态如何保持可恢复。
三、第二层：内容域与后端核心业务
目标：解释博客系统最核心的内容模型，以及文章从草稿、发布到下线的生命周期。
3.1 文章模型、发布状态与查询规则
这一组文章重点讲清楚：
- 文章元数据与正文内容分离，避免把展示字段和正文解析逻辑混在一起；
- 前台只消费公开内容，后台可以看到更多管理状态；
- 分类用于主分类筛选，标签用于横向关键词，专栏用于系列内容聚合；
- 置顶、推荐、发布时间、更新时间等字段必须有稳定的排序和展示语义；
- 删除操作需要区分“业务不可见”“可恢复删除”和“彻底删除”。
3.2 专栏模型与多对多关系
专栏篇必须明确以下约束：
parent_id=0表示一级专栏，首期最多两级；- 一篇博客可以加入多个专栏，但同一专栏中不能重复关联；
- 专栏是系列聚合，不替代分类、标签和知识库目录；
- 有子专栏或博客引用的专栏默认采用保守删除策略；
- 前台只展示公开专栏和公开博客，后台数据不能直接透传。
3.3 Markdown 解析与正文扩展
四、第三层：知识库、迁移与内容资产管理
目标：把“本地 Markdown 文件”纳入平台内容闭环，解决目录归位、元数据解析、批量导入、导出和重复导入问题。
4.1 知识库目录模型
知识库导入文章需要覆盖一条完整链路：
4.2 专栏与平台内容批量迁移
五、第四层：上传、图床与资源归档
目标：解释图片和附件为什么不能只当作一个 URL 字符串处理，以及资源如何在临时目录、文章目录和图床渠道之间流转。
5.1 本地资源生命周期
资源归档文章需要强调一致性边界：
- 文件先上传到临时目录，保存成功后再归档到文章目录；
- 复制成功后才把临时资源加入待清理集合；
- 数据库保存失败时，不能假设文件操作自动回滚；
- 已归档 URL、历史
/image/**URL 和外部图床 URL 必须兼容； - 服务端生成文件名并校验规范化后的绝对路径，不能直接信任客户端路径。
5.2 图床渠道抽象
六、第五层：认证、安全与后端横切能力
目标：讲清楚一个内容平台如何区分公开访问和管理访问，并让异常、审计、限流、访客统计和任务执行具备可追踪性。
6.1 管理端认证与接口安全
6.2 统一异常、日志、统计与定时任务
七、第六层：博客前台与阅读体验
目标：从访客视角讲清楚内容如何被发现、阅读和互动，并解释视觉效果背后的性能与兼容性取舍。
7.1 前台页面与内容消费
7.2 响应式视觉与交互
八、第七层：CMS 内容创作与运营后台
目标：围绕“站长每天真正会使用的工作流”，讲解编辑、管理、迁移、配置、统计和审计如何组合成一个可用的后台。
8.1 内容创作与管理
8.2 站点配置、数据看板与日志中心
九、第八层：SEO、搜索与服务端输出
目标：解释 SPA 博客为什么需要额外的 SEO 设计，以及标题、摘要、目录、站点地图、RSS 和验证文件如何统一生成。
9.1 SEO 基础与第一阶段改造
SEO 篇应将“理论指标”和“代码行为”分开：搜索引擎是否收录不能由应用直接保证，但应用可以稳定输出可抓取的标题、描述、规范链接、站点地图、RSS 和验证文件，并通过数据监测不断调整。
十、第九层：BlogLoom Publisher Skill 与多渠道分发
目标：记录如何把 BlogLoom 的内容管理能力封装成 AI Agent 可以理解、调用、验证和扩展的 Skill。
10.1 Skill 基础架构
Skill 的统一调用链路：
10.2 渠道适配：CSDN 与公众号
渠道分发文章必须明确：
- BlogLoom 内部内容模型是唯一的源数据；渠道适配只负责格式转换和渠道动作；
- 登录态、Cookie、Token 等敏感信息不能进入文章正文、日志或提交记录；
- 浏览器自动化必须有明确的选择器、成功判定、超时、重试和人工接管边界；
- 发布、存草稿、删除等破坏性动作需要显式确认或单独的测试命令；
- 每个渠道都要有独立 SOP 和测试，不能把渠道差异塞进通用脚本。
十一、第十层：部署、升级、质量与开源协作
目标：说明 BlogLoom 如何从本地开发项目变成别人可以安装、升级、备份和排障的开源产品。
11.1 Docker 与增量升级
11.2 测试、压测与发布规范
十二、番外篇：设计取舍与长期演进
这一组文章不以某个单独功能为主，而是记录 BlogLoom 在持续开发过程中值得复用的工程判断。- 补齐文章版本、草稿和发布审核等内容工作流；
- 增强资源引用分析、孤儿资源清理和备份恢复；
- 完善 SEO 数据监测、搜索能力和服务端输出；
- 将渠道分发抽象为可独立测试、可替换的适配器；
- 在不破坏个人博客简单部署体验的前提下探索主题、插件和多作者能力。
十三、发布节奏与优先级建议
13.1 推荐的首批文章顺序
建议先发布下面 12 篇，读者可以从“项目是什么”一路读到“如何部署和扩展”：BlogLoom系统架构 原理01、从前后端分离到内容生产闭环BlogLoom内容域 原理01、从 Blog 实体到 Blog DTO / VO 的内容模型设计BlogLoom Markdown 原理01、从 Markdown 文本到安全 HTMLBlogLoom资源 原理02、临时上传、文章归档与正文 URL 重写BlogLoom知识库 原理03、导入预检、异步任务与进度轮询BlogLoom专栏 原理02、两级专栏模型与 blog_column_relation 关系表BlogLoom CMS 实战01、文章新建、编辑、发布和回收站操作BlogLoom前台 原理03、文章详情页的 Markdown 渲染、目录与图片预览BlogLoom SEO 原理02、SPA 博客为什么需要服务端直出与站点级文件BlogLoom Publisher Skill 原理02、SKILL.md、SOP 与脚本工具的三层分离BlogLoom部署 实战01、Docker 一键部署的镜像、Compose 与数据目录设计BlogLoom质量保障 番外03、压力测试、容量测试与结果报告
13.2 每篇文章的固定交付模板
为了让专栏长期保持一致，每篇文章建议包含以下内容：- 背景与问题：当前功能解决了什么真实痛点；
- 方案对比：至少说明一个未采用方案及原因；
- 核心模型：表结构、DTO、接口或前端状态；
- 数据流：从用户操作到数据库、文件或外部渠道的完整路径；
- 源码索引：列出关键类、页面、SQL 和脚本；
- 可运行实战：给出启动条件、请求示例或页面操作；
- 边界与失败：重复执行、异常、权限、安全和兼容性；
- 验证结果：测试、截图、日志或压测数据；
- 后续演进：明确当前未实现的能力，不把规划项混入现状。
13.3 专栏维护规则
- 代码变更先更新对应设计文档，再决定是否新增或调整博客文章；
- 文章标题、文章路径和代码模块保持稳定，重构时增加迁移说明；
- 已完成、进行中和规划中的状态必须随代码真实情况更新；
- 每篇文章尽量提供一个最小可运行示例，避免只停留在概念描述；
- 涉及账号、Token、Cookie、密码和对象存储密钥时，示例只使用脱敏占位符；
- 文章中引用的截图、接口和配置应与当前版本保持一致；
- 当一个功能同时涉及后端、CMS、前台和部署时，明确主文章与交叉引用，避免重复解释。
十四、核心源码索引
选题原则：先有真实能力，再沉淀文章；先讲清边界，再扩展抽象；先保证可运行，再追求完整生态。