---
name: ai-tool-base 文章能力计划书
overview: 在 ai-tool-base（新站，尚无博客）上从零增加文章/教程发布能力。非独立 CMS、非 shipany-template。数据库表结构由 Codex 按项目现有约定自行设计。含多语言发布、目录 URL、代码/视频/图、R2、前台作者编辑。
todos:
- id: codex-review-schema
content: Codex 根据 ai-tool-base 现有 DB/ORM 设计文章相关表（本计划不规定字段名）
status: pending
- id: step1-foundation
content: 步骤1：数据层、后台目录与文章 CRUD、前台路由与列表
status: pending
- id: step2-editor
content: 步骤2：富编辑器、代码块、视频、R2 媒体
status: pending
- id: step3-frontend-edit
content: 步骤3：前台编辑、权限、草稿预览
status: pending
- id: step4-display
content: 步骤4：阅读模板、TOC、相关文章、分页
status: pending
isProject: false
---
# ai-tool-base 文章/教程能力 — 计划书（重做版）
> **给 Codex 用**：你已在 **ai-tool-base** 完成约 2/3 开发，本计划只写**产品要什么**；**表名、字段名、迁移方式由你按项目现有栈决定**（Drizzle/Prisma、命名风格、是否与现有 `user` 表关联等），与现有代码保持一致即可。
> **不要参考 shipany-template**；ai-tool-base **目前没有**博客与发文功能，本模块为**新增**。
**计划书路径**：`C:\Users\Administrator\.cursor\plans\文章发布系统计划书_407c92bb.plan.md`
---
## 零、项目定位
| 项 | 说明 |
| ------------ | ------------------------------------------------------------ |
| **项目** | **ai-tool-base**（你的 AI 工具站，进行中） |
| **不是什么** | 不是 shipanybase；不是单独做一个 WordPress 替代品 |
| **本需求** | 在已有 AI 工具、用户、后台、R2 等基础上，**新增**「文章/教程/博客」一整块能力 |
| **现状** | **尚无**文章发布、博客列表、后台发文；需从零做，但要**接入已有**登录、权限、多语言、R2、主题布局 |
| **谁定库表** | **Codex**（你最熟当前库表与目录结构） |
---
## 一、要达成的体验
管理人员在后台：
- 选**发布语言**（中文 / English / 日后日语等）
- 选**目录**（可选，如 `blog`）或发在站点根路径
- 用富编辑器写文：**图片、代码块、视频**
- 存草稿 / 发布
访客在前台：
- 按语言与目录打开文章（URL 规则见 §三）
- 阅读体验丰富（多模板、TOC、代码高亮等）
作者（登录用户）：
- 在文章页**编辑自己的文**（管理员可管全部）
---
## 二、已确认的产品规则（必须实现）
### 2.1 URL（路径 + 语言）
**路径规则（与语言无关）：**
| 场景 | 路径示例 |
| --------------- | ------------------- |
| 全部文章归档 | `/articles` |
| 选了目录 `blog` 的文章 | `/blog/{文章slug}` |
| 未选目录的文章 | `/{文章slug}` |
| 目录首页 | `/blog` 显示该目录下的文章列表 |
**语言前缀（与站点 next-intl / `localePrefix: as-needed` 一致）：**
| 管理人员选择语言 | 前台 URL 示例（目录 blog、slug 为 `my-post`） |
| --------------------- | -------------------------------------- |
| **站点默认语言**（如 `en`） | `/blog/my-post`（**不要** `/en/blog/...`） |
| 中文 `zh` | `/zh/blog/my-post` |
| 日语 `jp`（日后加入 locales） | `/jp/blog/my-post` |
**原则：** 后台选什么语言发布，前台就是该语言的路径；默认语言**无前缀**，其它语言**加 `/{locale}` 前缀**。列表页同理，如中文全部文章：`/zh/articles`。
### 2.2 后台「发布语言」
- 发文/编辑时 **必选一种语言**（下拉或多选框展示站点已配置的 `locales`）
- 文案示例：勾选「中文」即本篇为中文，只出现在中文 URL 与中文列表筛选中
- 后台文章列表支持按语言筛选
- **一期**：一篇文章对应一种语言、一条记录（不做「一篇文自动翻多语言」；多语言同一主题 = 多篇文，slug 可相同但 locale 不同，由 Codex 用联合唯一约束实现）
### 2.3 目录
- **一期仅单层目录**（如 `blog`、`guides`），不要 `guides/seo` 多级
- 目录 slug 避开保留路径：`admin`、`api`、`articles`、`settings` 等
### 2.4 权限
- 管理员：后台管理所有文章与目录
- 作者：**仅编辑自己创建的文章**（前台 + 后台均可，具体权限码与现有 RBAC 对齐，由 Codex 命名）
- 上传图片/视频：需登录
### 2.5 媒体
- **R2 已接好**，编辑器上传图片/视频**直接复用现有存储**，本计划不写 API 细节
- 生产环境以 R2 为准；本地目录仅开发备选（若项目已有约定）
### 2.6 内容存储
- **全部走数据库**（后台创建的正文）
- **不要**依赖 shipany 式 `content/posts/*.mdx` 文件（ai-tool-base 本来就没有）
---
## 三、数据层 — 只提能力，字段由 Codex 定
以下是你需要落库支撑的**业务能力**（表名/字段名/索引请你设计）：
### 3.1 文章目录（Directory）
- 可增删改、排序
- 字段能力：slug、标题、简介、发布状态
- slug 唯一
### 3.2 文章（Post / Article）
- 关联：作者（现有 user）、可选目录、**locale（必填）**
- 内容：标题、slug、摘要、正文（Markdown）、封面图、作者展示名/头像（可选）
- 状态：草稿 / 待审 / 已发布 / 已归档（至少要有草稿与已发布）
- 展示：`template`（default / magazine / minimal）
- **路径唯一性**：同一 `locale` 下，同一 URL 路径（由目录+slug 算出）不可重复
- 时间：创建、更新、可选定时发布（二期）
### 3.3 可选扩展（Codex 视进度决定）
- 分类/标签（若 ai-tool-base 已有 taxonomy 可复用）
- 同主题多语言关联 id（二期）
**请你（Codex）在动手前：** 快速扫一眼现有 schema、admin 路由、i18n 配置，再定表结构并写迁移。
---
## 四、后台功能（新增菜单）
在现有 **admin** 中增加（具体菜单名与路由与项目风格一致）：
1. **目录管理**：CRUD、slug 校验
2. **文章管理**：列表（筛：语言、目录、状态、作者）、新建、编辑、软删、预览
3. **文章表单必填/必选**：发布语言、标题、slug、状态；可选目录、模板、分类、标签、封面
**预览：** 草稿仅作者与管理员可打开前台预览链接。
---
## 五、编辑器与正文能力（一期）
**推荐** Tiptap + Markdown（或与你项目已引入的编辑器栈统一）。
| 能力 | 要求 |
| ------ | ----------------------------------------- |
| 排版 | 标题、粗斜体、列表、引用、链接；可切换 Markdown 源码 |
| **代码** | 插入代码块、选语言；前台 Shiki（或项目已有高亮方案）+ 复制按钮 |
| **视频** | 外链（YouTube/Bilibili 等，iframe 白名单）+ 上传到 R2 |
| **图片** | 上传 R2，插入 `` |
| 安全 | 过滤危险 HTML；视频 iframe 域名白名单 |
---
## 六、前台
### 6.1 路由（catch-all 或专用路由，与现有页面不冲突）
解析顺序建议：
1. 现有静态/营销页（不动）
2. **DB 文章**（`urlPath` + `locale` + 已发布）
3. 404
需新增页面能力：
- `/articles`（可按当前 locale 过滤）
- `/{directorySlug}` 目录列表
- `/{...path}` 文章详情（含语言前缀逻辑）
### 6.2 阅读页
- 至少 **2～3 种模板**（default / magazine / minimal）
- TOC、阅读时间、上/下一篇（同目录同语言）、相关文章
- 代码块、视频响应式
### 6.3 前台编辑
- 已发布文：作者见「编辑」→ `/{文章路径}/edit`（语言前缀规则同阅读页）
- 与后台**同一编辑器组件**
- 保存权限：本人或管理员
---
## 七、开发步骤（可合并一轮做完）
| 步骤 | 目标 |
| ----- | ------------------------------------------------------ |
| **1** | Codex 定表并迁移 → 后台目录+文章 CRUD → 前台能打开文章与 `/articles`、目录列表 |
| **2** | 富编辑器 + 代码 + 视频 + R2 上传 |
| **3** | 前台 `/edit`、作者权限、草稿预览 |
| **4** | 阅读模板、TOC、相关文章、分页、SEO（JSON-LD 等） |
---
## 八、验收清单
- 后台必选发布语言；选中文则仅中文 URL/列表
- 默认语言文章：`/blog/slug`，无 `/en/`
- 中文文章：`/zh/blog/slug`（无目录则为 `/zh/slug`）
- `/articles` 为全部文章（遵循当前 locale）
- 可选目录；目录 `blog` → `/blog/slug`
- 编辑器：图 / 代码 / 视频；R2 上传
- 草稿不公开；作者可预览
- 作者仅能改自己的文
- 至少 2 种阅读模板
- 与现有 AI 工具、登录、后台共存，无独立第二套站
---
## 九、本期不做
评论、审稿流、版本历史、全站搜索、RSS、开放 API、WordPress 同步、MDX 文件博客。
---
---
**说明给产品方：**划书文件` 即可。
