feat(doc): 栏目内容两级结构与悬浮目录

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-10 04:22:52 +08:00
parent 0bb288dc86
commit b82b07b84f
16 changed files with 473 additions and 640 deletions

View File

@ -81,9 +81,9 @@ packService/
- [x] **登录入口与文档站(2026-11-07)**:
- **`/` 就是入口**:已登录 → 自动进看板 `/dashboard`;未登录 → **原地**显示登录页(地址保持在 `/`,不再跳 `/login`);
看板路由从 `/` 挪到 `/dashboard`,侧边栏「首页」与各处「被拒绝」回跳同步改过去;
- **文档站** `/doc/**`:后端生成的**静态 HTML**(顶部 tab 切分类、左侧「栏目 → 内容页」、右侧本页目录),
- **文档站** `/doc/**`:后端生成的**静态 HTML**(顶部 tab 切栏目、左侧直接列出该栏目的内容页、右侧本页目录),
页面保存后自动重生成,新链接追加到 `/sitemap.txt`;
- **平台管理 · 文档管理**(`/admin/doc`):分类 / 栏目 / 内容页(Markdown)的简易 CMS,保存即重生成;
- **平台管理 · 文档管理**(`/admin/doc`):**栏目 → 内容页**(Markdown)两级简易 CMS,保存即重生成;
- 登录页右下角、顶栏(登录后)与看板右上角都有进入文档站的链接
- [x] **待支付订单 2 小时自动失效(2026-10-29)**:下单后 2 小时(`PAY_ORDER_TTL`,默认 7200 秒)内未支付,
订单自动关闭(`status=2`);之后的支付回调 / 手工确认一律 409。与微信扫码支付二维码有效期对齐,

View File

@ -39,7 +39,7 @@ packService/backend
│ │ │ ├── admin_order.js # /api/web/admin/orders[/:orderNo/confirm] 所有订单 + 确认订单
│ │ │ ├── admin_plan.js # /api/web/admin/plans[/:id] 续期套餐(改价 / 改天数 / 上下架)
│ │ │ ├── admin_extension.js # /api/web/admin/extension Chrome 插件集中配置(❗需平台管理员)
│ │ │ ├── admin_doc.js # /api/web/admin/doc/* 文档站 CMS(分类 / 栏目 / 内容页,❗需平台管理员)
│ │ │ ├── admin_doc.js # /api/web/admin/doc/* 文档站 CMS(栏目 / 内容页,❗需平台管理员)
│ │ │ ├── doc.js # GET /doc/**、/sitemap.txt 文档站(公开,直接回生成好的静态 HTML)
│ │ │ ├── extension.js # /api/web/extension/config 插件读取的配置(公开只读,无令牌)
│ │ │ └── test.js # /api/web/test/{device-login,scan} 前端测试页的模拟接口(仅非生产环境注册)
@ -70,8 +70,7 @@ packService/backend
│ │ ├── scanner.js # scanners
│ │ ├── scan_channel.js # scan_channels
│ │ ├── scan_record.js # scan_records(去重)
│ │ ├── doc_category.js # doc_categories(文档分类 = 顶部 tab)
│ │ ├── doc_section.js # doc_sections(分类下的一级栏目)
│ │ ├── doc_section.js # doc_sections(栏目 = 顶部 tab,下挂内容页)
│ │ └── doc_article.js # doc_articles(内容页,Markdown 原文)
│ ├── service
│ │ ├── auth.js # 登录校验(bcrypt 密码比对)+ 自助注册
@ -88,7 +87,7 @@ packService/backend
│ │ ├── health.js # MySQL / Redis 连通性探测
│ │ ├── user.js # 用户数据访问(app.model.User)
│ │ ├── wx_gateway.js # 微信登录网关:临时码 / 验签 / 会话长轮询 / 绑定关系
│ │ ├── doc.js # 文档站 CMS:分类 / 栏目 / 内容页的增删改查(写完自动重生成)
│ │ ├── doc.js # 文档站 CMS:栏目 / 内容页的增删改查(写完自动重生成)
│ │ └── doc_site.js # 文档站生成:把库里的内容渲染成 /doc/** 静态 HTML + /sitemap.txt
│ ├── lib
│ │ └── markdown.js # 极简 Markdown → HTML(先转义再拼标签,附文章内目录)
@ -1064,8 +1063,8 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
文档站是**静态 HTML**:内容存在库里,保存时由 `service/docSite` 整站渲染到 `run/doc-site/`(`run/` 被 gitignore),
`controller/web/doc.js` 只负责回文件(文件不存在时按需重新生成,部署后不用手工跑构建)。
- 层级:**分类**(文档站顶部 tab)→ **栏目**(侧边栏分组)→ **内容页**(Markdown,`lib/markdown.js` 渲染);
- 页面地址:`/doc/`、`/doc/<分类编码>/`、`/doc/<分类编码>/<文章 slug>.html`;
- 层级:**栏目**(文档站顶部 tab,也是左侧列表的标题)→ **内容页**(Markdown,`lib/markdown.js` 渲染),只有两级;
- 页面地址:`/doc/`、`/doc/<栏目编码>/`、`/doc/<栏目编码>/<文章 slug>.html`;
- 新链接按顺序追加到 `/sitemap.txt` 末尾(下架 / 删除的会被清掉);
- `middleware/frontend.js` 已把 `/doc/**`、`/sitemap.txt` 从 SPA 里排除;Vite dev server 也把它们反代给后端;
- 生成目录 / sitemap 的站点根地址:`config.docSite.baseUrl`(env `SITE_BASE_URL`),不配就用触发请求的 origin。
@ -1074,16 +1073,13 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/web/admin/doc/tree` | 分类 → 栏目 → 内容页(树;文章不带正文,带 `url` / `statusText`) |
| POST | `/api/web/admin/doc/categories` | 新增分类 `{ code?, name, description?, sort?, status? }`;`code` 留空自动 `cat1`、`cat2`… |
| PUT | `/api/web/admin/doc/categories/:id` | 修改分类(`code` 创建后不可改,其余只改传了的字段) |
| DELETE | `/api/web/admin/doc/categories/:id` | 删除分类(栏目与内容页一起软删,页面与 sitemap 一并移除) |
| POST | `/api/web/admin/doc/sections` | 新增栏目 `{ categoryId, name, sort?, status? }` |
| PUT | `/api/web/admin/doc/sections/:id` | 修改栏目(传 `categoryId` 可换分类,底下内容页跟着走) |
| DELETE | `/api/web/admin/doc/sections/:id` | 删除栏目(内容页一起软删) |
| GET | `/api/web/admin/doc/tree` | 栏目 → 内容页(树;文章不带正文,带 `url` / `sectionCode` / `statusText`) |
| POST | `/api/web/admin/doc/sections` | 新增栏目 `{ code?, name, description?, sort?, status? }`;`code` 留空自动 `sec1`、`sec2`… |
| PUT | `/api/web/admin/doc/sections/:id` | 修改栏目(`code` 创建后不可改,其余只改传了的字段) |
| DELETE | `/api/web/admin/doc/sections/:id` | 删除栏目(内容页一起软删,页面与 sitemap 一并移除) |
| GET | `/api/web/admin/doc/articles/:id` | 单篇(含 Markdown 正文) |
| POST | `/api/web/admin/doc/articles` | 新增内容页 `{ sectionId, title, slug?, summary?, content?, sort?, status? }`;`slug` 留空自动 `a1`、`a2`… |
| PUT | `/api/web/admin/doc/articles/:id` | 修改内容页(`slug` 创建后不可改;`status=0` 作草稿,不生成页面) |
| PUT | `/api/web/admin/doc/articles/:id` | 修改内容页(`slug` 创建后不可改;传 `sectionId` 可换栏目;`status=0` 作草稿,不生成页面) |
| DELETE | `/api/web/admin/doc/articles/:id` | 删除内容页 |
| POST | `/api/web/admin/doc/rebuild` | 手动整站重生成(排查用,返回页面数与 sitemap 条数) |
@ -1100,7 +1096,7 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql());
| 套餐管理 | `/admin/plans` | `views/AdminPlansView.vue` | 续期套餐的新增 / 改价 / 改天数 / 上下架 / 删除(下单只按这里的售价算钱) |
| 管理员 | `/admin/members` | `views/AdminMembersView.vue` | 平台管理员列表 + 添加(按账号)+ 移除 |
| 插件配置 | `/admin/extension` | `views/AdminExtensionView.vue` | Chrome 插件的单号前缀 / 生效站点 / 跳转模板 |
| 文档管理 | `/admin/doc` | `views/AdminDocView.vue` | 文档站 CMS:分类(顶部 tab)→ 栏目 → 内容页(Markdown),保存即重生成静态页面 |
| 文档管理 | `/admin/doc` | `views/AdminDocView.vue` | 文档站 CMS:栏目 → 内容页(Markdown)两级,保存即重生成静态页面 |
- 是否显示这组菜单靠 `GET /api/web/admin/me`(`composables/usePlatformAdmin.ts`;非管理员 403 静默当 false);
- 路由带 `meta.platformAdmin`,不是平台管理员会被守卫踢回首页(`?denied=1`);

View File

@ -13,12 +13,9 @@ function toId(value) {
*
* 鉴权:`middleware.apiAuth()` + `middleware.platformAdmin()`(能进来的都是平台管理员)。
*
* - `GET /api/web/admin/doc/tree` 分类 → 栏目 → 内容页(树,文章不带正文)
* - `POST /api/web/admin/doc/categories` 新增分类
* - `PUT /api/web/admin/doc/categories/:id` 修改分类(名称 / 排序 / 显隐;`code` 不可改)
* - `DELETE /api/web/admin/doc/categories/:id` 删除分类(栏目与内容页一起删)
* - `GET /api/web/admin/doc/tree` 栏目 → 内容页(树,文章不带正文)
* - `POST /api/web/admin/doc/sections` 新增栏目
* - `PUT /api/web/admin/doc/sections/:id` 修改栏目
* - `PUT /api/web/admin/doc/sections/:id` 修改栏目(名称 / 排序 / 显隐 / 说明;`code` 不可改)
* - `DELETE /api/web/admin/doc/sections/:id` 删除栏目(内容页一起删)
* - `GET /api/web/admin/doc/articles/:id` 单篇(含正文)
* - `POST /api/web/admin/doc/articles` 新增内容页
@ -35,26 +32,6 @@ class WebAdminDocController extends Controller {
this.ctx.body = { ok: true, data };
}
/** POST /api/web/admin/doc/categories */
async createCategory() {
const data = await this.ctx.service.doc.createCategory(this.ctx.request.body || {});
this.ctx.status = 201;
this.ctx.body = { ok: true, data };
}
/** PUT /api/web/admin/doc/categories/:id */
async updateCategory() {
const id = this.requireId();
const data = await this.ctx.service.doc.updateCategory(id, this.ctx.request.body || {});
this.ctx.body = { ok: true, data };
}
/** DELETE /api/web/admin/doc/categories/:id */
async destroyCategory() {
const data = await this.ctx.service.doc.removeCategory(this.requireId());
this.ctx.body = { ok: true, data };
}
/** POST /api/web/admin/doc/sections */
async createSection() {
const data = await this.ctx.service.doc.createSection(this.ctx.request.body || {});

View File

@ -10,7 +10,7 @@ const { Controller } = require('egg');
* 这里只做「路径 → 文件」的映射与缓存头控制。文件被人删了 / 刚部署上来时按需重新生成。
*
* - `GET /doc` → 301 到 `/doc/`
* - `GET /doc/…` → 生成好的 HTML(分类首页 `index.html` / 内容页 `<slug>.html`)
* - `GET /doc/…` → 生成好的 HTML(栏目首页 `index.html` / 内容页 `<slug>.html`)
* - `GET /sitemap.txt` → 全站 URL(页面顺序稳定,新增的追加在末尾)
*/
class WebDocController extends Controller {

View File

@ -3,20 +3,19 @@
/**
* 文档内容页(doc_articles)
*
* 直接挂在栏目下(两级结构),一个栏目下的一批内容页就是文档站左侧的导航列表。
* - `content`:Markdown 原文(保存后由 `service/docSite` 渲染成静态 HTML)
* - `slug`:URL 片段(`/doc/<categoryCode>/<slug>.html`),创建后不能改
* - `slug`:URL 片段(`/doc/<栏目 code>/<slug>.html`),创建后不能改
* - `status`:1 发布 0 草稿(草稿不生成页面,也不进 sitemap)
* - `categoryId` 冗余一份:列表 / 生成文档站时不用每次都 join 栏目
*/
module.exports = (app) => {
const { BIGINT, STRING, TINYINT, INTEGER, TEXT } = app.Sequelize;
const DocArticle = app.model.define('doc_article', {
id: { type: BIGINT.UNSIGNED, primaryKey: true, autoIncrement: true, comment: '主键' },
categoryId: { type: BIGINT.UNSIGNED, allowNull: false, comment: '所属分类 doc_categories.id' },
sectionId: { type: BIGINT.UNSIGNED, allowNull: false, comment: '所属栏目 doc_sections.id' },
title: { type: STRING(128), allowNull: false, comment: '标题' },
slug: { type: STRING(64), allowNull: false, comment: 'URL 片段(/doc/<分类>/<slug>.html)' },
slug: { type: STRING(64), allowNull: false, comment: 'URL 片段(/doc/<栏目>/<slug>.html)' },
summary: { type: STRING(255), allowNull: true, comment: '摘要(列表 / meta description)' },
content: { type: TEXT('medium'), allowNull: true, comment: '正文(Markdown)' },
sort: { type: INTEGER.UNSIGNED, allowNull: false, defaultValue: 0, comment: '栏目内排序(小的在前)' },

View File

@ -1,28 +0,0 @@
'use strict';
/**
* 文档分类(doc_categories)
*
* 一行 = 文档站顶部的一个 tab(「快速开始」「设备接入」「常见问题」…)。
* - `code`:URL 片段(`/doc/<code>/`),**创建后不能改**(改了旧链接就失效)
* - `status`:1 展示 0 隐藏(隐藏后不生成页面,也不再进 sitemap)
* - `sort`:tab 顺序(小的在前)
*/
module.exports = (app) => {
const { BIGINT, STRING, TINYINT, INTEGER } = app.Sequelize;
const DocCategory = app.model.define('doc_category', {
id: { type: BIGINT.UNSIGNED, primaryKey: true, autoIncrement: true, comment: '主键' },
code: { type: STRING(32), allowNull: false, unique: true, comment: 'URL 片段(/doc/<code>/)' },
name: { type: STRING(64), allowNull: false, comment: '分类名称(tab 文案)' },
description: { type: STRING(255), allowNull: true, comment: '分类说明(可选)' },
sort: { type: INTEGER.UNSIGNED, allowNull: false, defaultValue: 0, comment: '排序(小的在前)' },
status: { type: TINYINT.UNSIGNED, allowNull: false, defaultValue: 1, comment: '状态:1 展示 0 隐藏' },
}, {
tableName: 'doc_categories',
paranoid: true,
comment: '文档分类表',
});
return DocCategory;
};

View File

@ -3,16 +3,19 @@
/**
* 文档栏目(doc_sections)
*
* 分类底下的**一级**列表(「安装部署」「扫码上报」…),栏目下面才是内容页。
* 层级只有两级:分类 → 栏目 → 内容页,够用且不会把侧边栏撑爆。
* 文档站最外层(顶部 tab),栏目下面**直接**就是内容页 —— 只有两级,不再有分类。
* - `code`:URL 片段(`/doc/<code>/`),**创建后不能改**(改了旧链接就失效)
* - `status`:1 展示 0 隐藏(隐藏后不生成页面,也不再进 sitemap)
* - `sort`:栏目顺序(小的在前)
*/
module.exports = (app) => {
const { BIGINT, STRING, TINYINT, INTEGER } = app.Sequelize;
const DocSection = app.model.define('doc_section', {
id: { type: BIGINT.UNSIGNED, primaryKey: true, autoIncrement: true, comment: '主键' },
categoryId: { type: BIGINT.UNSIGNED, allowNull: false, comment: '所属分类 doc_categories.id' },
name: { type: STRING(64), allowNull: false, comment: '栏目名称(侧边栏分组标题)' },
code: { type: STRING(32), allowNull: false, unique: true, comment: 'URL 片段(/doc/<code>/)' },
name: { type: STRING(64), allowNull: false, comment: '栏目名称(顶部 tab 文案)' },
description: { type: STRING(255), allowNull: true, comment: '栏目说明(可选)' },
sort: { type: INTEGER.UNSIGNED, allowNull: false, defaultValue: 0, comment: '排序(小的在前)' },
status: { type: TINYINT.UNSIGNED, allowNull: false, defaultValue: 1, comment: '状态:1 展示 0 隐藏' },
}, {

View File

@ -92,11 +92,8 @@ module.exports = (app) => {
router.get('/api/web/admin/extension', apiAuth, platformAdmin, controller.web.adminExtension.show);
router.put('/api/web/admin/extension', apiAuth, platformAdmin, controller.web.adminExtension.update);
// 文档站(简易 CMS):分类 → 栏目 → 内容页;保存后自动重生成 /doc/** 与 /sitemap.txt
// 文档站(简易 CMS):栏目 → 内容页(两级);保存后自动重生成 /doc/** 与 /sitemap.txt
router.get('/api/web/admin/doc/tree', apiAuth, platformAdmin, controller.web.adminDoc.tree);
router.post('/api/web/admin/doc/categories', apiAuth, platformAdmin, controller.web.adminDoc.createCategory);
router.put('/api/web/admin/doc/categories/:id', apiAuth, platformAdmin, controller.web.adminDoc.updateCategory);
router.delete('/api/web/admin/doc/categories/:id', apiAuth, platformAdmin, controller.web.adminDoc.destroyCategory);
router.post('/api/web/admin/doc/sections', apiAuth, platformAdmin, controller.web.adminDoc.createSection);
router.put('/api/web/admin/doc/sections/:id', apiAuth, platformAdmin, controller.web.adminDoc.updateSection);
router.delete('/api/web/admin/doc/sections/:id', apiAuth, platformAdmin, controller.web.adminDoc.destroySection);

View File

@ -2,8 +2,8 @@
const { Service } = require('egg');
/** 分类 code:URL 片段,只用安全字符 */
const CATEGORY_CODE = /^[a-z0-9][a-z0-9-]{0,31}$/;
/** 栏目 code:URL 片段,只用安全字符 */
const SECTION_CODE = /^[a-z0-9][a-z0-9-]{0,31}$/;
/** 文章 slug:URL 文件名 */
const ARTICLE_SLUG = /^[a-z0-9][a-z0-9_-]{0,63}$/;
const MAX_CONTENT = 200000;
@ -16,14 +16,10 @@ function toId(value) {
/**
* 文档站(简易 CMS)的增删改查
*
* 层级固定两级:分类(顶部 tab)→ 栏目(侧边栏分组)→ 内容页(Markdown)。
* 层级固定两级:**栏目**(顶部 tab,也是左侧列表的标题)→ **内容页**(Markdown)。
* **每次写操作后都会整站重生成**(`service/docSite`),保证页面 / 目录 / sitemap 与库一致。
*/
class DocService extends Service {
get Category() {
return this.app.model.DocCategory;
}
get Section() {
return this.app.model.DocSection;
}
@ -32,11 +28,10 @@ class DocService extends Service {
return this.app.model.DocArticle;
}
/** CMS 树:分类 → 栏目 → 文章(文章不带正文,点开再取) */
/** CMS 树:栏目 → 文章(文章不带正文,点开再取) */
async tree() {
const order = [ [ 'sort', 'ASC' ], [ 'id', 'ASC' ] ];
const [ categories, sections, articles ] = await Promise.all([
this.Category.findAll({ order }),
const [ sections, articles ] = await Promise.all([
this.Section.findAll({ order }),
this.Article.findAll({ order }),
]);
@ -48,38 +43,13 @@ class DocService extends Service {
articlesBySection.get(key).push(article);
}
const sectionsByCategory = new Map();
for (const section of sections) {
const key = String(section.categoryId);
if (!sectionsByCategory.has(key)) sectionsByCategory.set(key, []);
sectionsByCategory.get(key).push(section);
}
const list = categories.map(category => {
const code = category.code;
const ownSections = sectionsByCategory.get(String(category.id)) || [];
const groups = ownSections.map(section => ({
id: Number(section.id),
categoryId: Number(section.categoryId),
name: section.name,
sort: Number(section.sort),
status: Number(section.status),
statusText: Number(section.status) === 1 ? '展示' : '隐藏',
deleted: Boolean(section.deletedAt),
articles: (articlesBySection.get(String(section.id)) || []).map(article => this.presentArticle(article, code)),
}));
const list = sections.map(section => {
const own = articlesBySection.get(String(section.id)) || [];
return {
id: Number(category.id),
code,
name: category.name,
description: category.description || '',
sort: Number(category.sort),
status: Number(category.status),
statusText: Number(category.status) === 1 ? '展示' : '隐藏',
deleted: Boolean(category.deletedAt),
sections: groups,
articleCount: groups.reduce((total, group) => total + group.articles.length, 0),
...this.presentSection(section),
deleted: Boolean(section.deletedAt),
articles: own.map(article => this.presentArticle(article, section.code)),
articleCount: own.length,
};
});
@ -94,91 +64,40 @@ class DocService extends Service {
const row = await this.Article.findByPk(articleId, { paranoid: false });
if (!row || row.deletedAt) this.ctx.throw(404, '内容页不存在');
const category = await this.Category.findByPk(row.categoryId, { paranoid: false });
const section = await this.Section.findByPk(row.sectionId, { paranoid: false });
return {
...this.presentArticle(row, category ? category.code : ''),
...this.presentArticle(row, section ? section.code : ''),
content: row.content || '',
categoryId: Number(row.categoryId),
sectionId: Number(row.sectionId),
};
}
// ---------------- 分类 ----------------
async createCategory(body = {}) {
const payload = await this.normalizeCategory(body, null);
if (!payload.code) payload.code = await this.uniqueCategoryCode();
const row = await this.Category.create(payload);
this.app.logger.info('[doc] 新增分类:id=%s code=%s', row.id, row.code);
await this.regenerate();
return this.presentCategory(row);
}
async updateCategory(id, body = {}) {
const row = await this.findCategory(id);
const payload = await this.normalizeCategory(body, row);
await row.update(payload);
this.app.logger.info('[doc] 修改分类:id=%s %s', row.id, JSON.stringify(payload));
await this.regenerate();
return this.presentCategory(row);
}
/** 删除分类:连同栏目 / 内容页一起软删(页面与 sitemap 一并清掉) */
async removeCategory(id) {
const row = await this.findCategory(id);
const sections = await this.Section.findAll({ where: { categoryId: row.id } });
const sectionIds = sections.map(section => section.id);
if (sectionIds.length) {
await this.Article.destroy({ where: { sectionId: sectionIds } });
await this.Section.destroy({ where: { id: sectionIds } });
}
await row.destroy();
this.app.logger.info('[doc] 删除分类:id=%s code=%s', row.id, row.code);
await this.regenerate();
return { id: Number(row.id) };
}
async findCategory(id) {
const categoryId = toId(id);
if (!categoryId) this.ctx.throw(400, 'id 必须是正整数');
const row = await this.Category.findByPk(categoryId);
if (!row) this.ctx.throw(404, '分类不存在');
return row;
}
// ---------------- 栏目 ----------------
async createSection(body = {}) {
const payload = this.normalizeSection(body, null);
payload.categoryId = await this.assertCategory(body.categoryId);
const payload = await this.normalizeSection(body, null);
if (!payload.code) payload.code = await this.uniqueSectionCode();
const row = await this.Section.create(payload);
this.app.logger.info('[doc] 新增栏目:id=%s category=%s', row.id, payload.categoryId);
this.app.logger.info('[doc] 新增栏目:id=%s code=%s', row.id, row.code);
await this.regenerate();
return this.presentSection(row);
}
async updateSection(id, body = {}) {
const row = await this.findSection(id);
const payload = this.normalizeSection(body, row);
if (body.categoryId !== undefined && Number(body.categoryId) !== Number(row.categoryId)) {
payload.categoryId = await this.assertCategory(body.categoryId);
// 栏目换分类时,底下的内容页跟着走(categoryId 冗余在文章上)
await this.Article.update({ categoryId: payload.categoryId }, { where: { sectionId: row.id } });
}
const payload = await this.normalizeSection(body, row);
await row.update(payload);
this.app.logger.info('[doc] 修改栏目:id=%s %s', row.id, JSON.stringify(payload));
await this.regenerate();
return this.presentSection(row);
}
/** 删除栏目:底下的内容页一起软删 */
/** 删除栏目:底下的内容页一起软删(页面与 sitemap 一并清掉) */
async removeSection(id) {
const row = await this.findSection(id);
await this.Article.destroy({ where: { sectionId: row.id } });
await row.destroy();
this.app.logger.info('[doc] 删除栏目:id=%s', row.id);
this.app.logger.info('[doc] 删除栏目:id=%s code=%s', row.id, row.code);
await this.regenerate();
return { id: Number(row.id) };
}
@ -198,11 +117,10 @@ class DocService extends Service {
const section = await this.findSection(body.sectionId);
payload.sectionId = Number(section.id);
payload.categoryId = Number(section.categoryId);
const customSlug = payload.slug;
if (customSlug) {
await this.assertSlugFree(payload.categoryId, customSlug, null);
await this.assertSlugFree(payload.sectionId, customSlug, null);
} else {
// slug 是非空列:先插一个临时值,拿到 id 后再改成稳定的 `a12`
payload.slug = `tmp${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
@ -213,7 +131,7 @@ class DocService extends Service {
await row.update({ slug: `a${row.id}` });
}
this.app.logger.info('[doc] 新增内容页:id=%s %s/%s', row.id, payload.categoryId, row.slug);
this.app.logger.info('[doc] 新增内容页:id=%s 栏目=%s slug=%s', row.id, payload.sectionId, row.slug);
await this.regenerate();
return this.findArticle(row.id);
}
@ -227,16 +145,15 @@ class DocService extends Service {
if (body.sectionId !== undefined && Number(body.sectionId) !== Number(row.sectionId)) {
const section = await this.findSection(body.sectionId);
payload.sectionId = Number(section.id);
payload.categoryId = Number(section.categoryId);
}
if (payload.slug && payload.slug !== row.slug) {
// slug 改了旧链接就失效,所以创建后不允许改
this.ctx.throw(409, '内容页地址(slug)创建后不能修改');
}
if (payload.categoryId && Number(payload.categoryId) !== Number(row.categoryId)) {
// 换分类:目标分类下不能已有同名地址
await this.assertSlugFree(Number(payload.categoryId), row.slug, null);
if (payload.sectionId && Number(payload.sectionId) !== Number(row.sectionId)) {
// 换栏目:目标栏目下不能已有同名地址
await this.assertSlugFree(Number(payload.sectionId), row.slug, null);
}
await row.update(payload);
@ -256,7 +173,7 @@ class DocService extends Service {
}
// ---------------- 校验 ----------------
async normalizeCategory(body = {}, base = null) {
async normalizeSection(body = {}, base = null) {
const has = key => Object.prototype.hasOwnProperty.call(body, key);
const data = {};
if (!base) {
@ -268,42 +185,15 @@ class DocService extends Service {
if (!base || has('code')) {
const code = body.code === undefined || body.code === null ? '' : String(body.code).trim().toLowerCase();
if (base) {
if (code && code !== String(base.code)) this.ctx.throw(409, '分类编码创建后不能修改');
if (code && code !== String(base.code)) this.ctx.throw(409, '栏目编码创建后不能修改');
} else if (code) {
if (!CATEGORY_CODE.test(code)) this.ctx.throw(422, '分类编码只能用小写字母 / 数字 / 短横线(1~32 位)');
const existing = await this.Category.findOne({ where: { code }, paranoid: false });
if (existing) this.ctx.throw(409, `分类编码「${code}」已存在`);
if (!SECTION_CODE.test(code)) this.ctx.throw(422, '栏目编码只能用小写字母 / 数字 / 短横线(1~32 位)');
const existing = await this.Section.findOne({ where: { code }, paranoid: false });
if (existing) this.ctx.throw(409, `栏目编码「${code}」已存在`);
data.code = code;
}
}
if (!base || has('name')) {
const name = String(body.name === undefined || body.name === null ? '' : body.name).trim();
if (!name) this.ctx.throw(422, '请填写分类名称');
if (name.length > 64) this.ctx.throw(422, '分类名称不能超过 64 个字符');
data.name = name;
}
if (!base || has('description')) {
const description = String(body.description === undefined || body.description === null ? '' : body.description).trim();
if (description.length > 255) this.ctx.throw(422, '分类说明不能超过 255 个字符');
data.description = description || null;
}
if (!base || has('sort')) data.sort = this.normalizeSort(body.sort);
if (!base || has('status')) data.status = this.normalizeStatus(body.status);
return data;
}
normalizeSection(body = {}, base = null) {
const has = key => Object.prototype.hasOwnProperty.call(body, key);
const data = {};
if (!base) {
if (body.status === undefined || body.status === null) body.status = 1;
if (body.sort === undefined || body.sort === null) body.sort = 0;
}
if (!base || has('name')) {
const name = String(body.name === undefined || body.name === null ? '' : body.name).trim();
if (!name) this.ctx.throw(422, '请填写栏目名称');
@ -311,6 +201,12 @@ class DocService extends Service {
data.name = name;
}
if (!base || has('description')) {
const description = String(body.description === undefined || body.description === null ? '' : body.description).trim();
if (description.length > 255) this.ctx.throw(422, '栏目说明不能超过 255 个字符');
data.description = description || null;
}
if (!base || has('sort')) data.sort = this.normalizeSort(body.sort);
if (!base || has('status')) data.status = this.normalizeStatus(body.status);
return data;
@ -372,32 +268,27 @@ class DocService extends Service {
return status;
}
async assertCategory(id) {
const row = await this.findCategory(id);
return Number(row.id);
}
/** 同一分类下 slug 不能重复(含已删除的行:唯一索引还在) */
async assertSlugFree(categoryId, slug, id) {
/** 同一栏目下 slug 不能重复 */
async assertSlugFree(sectionId, slug, id) {
const existing = await this.Article.findOne({
where: { categoryId, slug },
where: { sectionId, slug },
paranoid: false,
});
if (existing && Number(existing.id) !== Number(id)) this.ctx.throw(409, `该分类下已有地址「${slug}」`);
if (existing && Number(existing.id) !== Number(id)) this.ctx.throw(409, `该栏目下已有地址「${slug}」`);
}
/** 没填 code 时生成 `cat1`、`cat2`…(和已有 code 不冲突) */
async uniqueCategoryCode() {
/** 没填 code 时生成 `sec1`、`sec2`…(和已有 code 不冲突) */
async uniqueSectionCode() {
for (let i = 1; i <= 999; i++) {
const code = `cat${i}`;
const existing = await this.Category.findOne({ where: { code }, paranoid: false });
const code = `sec${i}`;
const existing = await this.Section.findOne({ where: { code }, paranoid: false });
if (!existing) return code;
}
this.ctx.throw(409, '分类过多,请手动填写分类编码');
this.ctx.throw(409, '栏目过多,请手动填写栏目编码');
}
// ---------------- 展示 ----------------
presentCategory(row) {
presentSection(row) {
return {
id: Number(row.id),
code: row.code,
@ -411,23 +302,11 @@ class DocService extends Service {
};
}
presentSection(row) {
presentArticle(row, sectionCode) {
return {
id: Number(row.id),
categoryId: Number(row.categoryId),
name: row.name,
sort: Number(row.sort),
status: Number(row.status),
statusText: Number(row.status) === 1 ? '展示' : '隐藏',
};
}
presentArticle(row, categoryCode) {
return {
id: Number(row.id),
categoryId: Number(row.categoryId),
sectionId: Number(row.sectionId),
categoryCode: categoryCode || '',
sectionCode: sectionCode || '',
title: row.title,
slug: row.slug,
summary: row.summary || '',
@ -435,7 +314,7 @@ class DocService extends Service {
status: Number(row.status),
statusText: Number(row.status) === 1 ? '已发布' : '草稿',
deleted: Boolean(row.deletedAt),
url: categoryCode && row.slug ? `/doc/${categoryCode}/${row.slug}.html` : '',
url: sectionCode && row.slug ? `/doc/${sectionCode}/${row.slug}.html` : '',
updatedAt: row.updatedAt || null,
};
}

View File

@ -7,7 +7,7 @@ const markdown = require('../lib/markdown');
const SITE_NAME = '云仓视频溯源';
/** 目录 / 文件名只允许安全的 ASCII:分类 code、文章 slug 都按这个校验 */
/** 目录 / 文件名只允许安全的 ASCII:栏目 code、文章 slug 都按这个校验 */
const SAFE_SEGMENT = /^[a-z0-9][a-z0-9_-]{0,63}$/;
function ensureDir(dir) {
@ -35,7 +35,7 @@ function dateOnly(value) {
* 文档站生成器(`/doc/**` 的静态 HTML + `/sitemap.txt`)
*
* 设计取舍:
* - **静态优先**:每次内容变更(增删改分类 / 栏目 / 文章)整站重写一遍,文章量级小(几十篇)足够快;
* - **静态优先**:每次内容变更(增删改栏目 / 文章)整站重写一遍,文章量级小(几十篇)足够快;
* - 首次访问 / 部署后文件不存在时 **按需生成**(`ensureSite`),不依赖启动钩子;
* - 生成目录放在 `run/doc-site`(不进仓库),由 `controller/web/doc.js` 直接读文件返回。
*/
@ -60,12 +60,11 @@ class DocSiteService extends Service {
return origin.replace(/\/+$/, '');
}
/** 已发布的分类 → 栏目 → 文章(仅 status=1,按 sort 排序) */
/** 已发布的栏目 → 文章(仅 status=1,按 sort 排序) */
async loadModel() {
const { DocCategory, DocSection, DocArticle } = this.app.model;
const { DocSection, DocArticle } = this.app.model;
const order = [ [ 'sort', 'ASC' ], [ 'id', 'ASC' ] ];
const [ categories, sections, articles ] = await Promise.all([
DocCategory.findAll({ where: { status: 1 }, order }),
const [ sections, articles ] = await Promise.all([
DocSection.findAll({ where: { status: 1 }, order }),
DocArticle.findAll({ where: { status: 1 }, order }),
]);
@ -77,30 +76,13 @@ class DocSiteService extends Service {
articlesBySection.get(key).push(article);
}
const sectionsByCategory = new Map();
for (const section of sections) {
const key = String(section.categoryId);
if (!sectionsByCategory.has(key)) sectionsByCategory.set(key, []);
sectionsByCategory.get(key).push(section);
}
return categories.map(category => {
const ownSections = sectionsByCategory.get(String(category.id)) || [];
const groups = ownSections.map(section => ({
id: Number(section.id),
name: section.name,
articles: articlesBySection.get(String(section.id)) || [],
})).filter(group => group.articles.length > 0);
return {
id: Number(category.id),
code: category.code,
name: category.name,
description: category.description || '',
groups,
articles: groups.reduce((all, group) => all.concat(group.articles), []),
};
}).filter(category => SAFE_SEGMENT.test(category.code));
return sections.map(section => ({
id: Number(section.id),
code: section.code,
name: section.name,
description: section.description || '',
articles: articlesBySection.get(String(section.id)) || [],
})).filter(section => SAFE_SEGMENT.test(section.code));
}
/** 生成整站(页面 + sitemap),返回生成的文件相对路径列表 */
@ -110,25 +92,25 @@ class DocSiteService extends Service {
ensureDir(this.siteDir);
const written = [];
const firstCategory = model[0] || null;
const firstSection = model[0] || null;
// `/doc/`:默认展示第一个分类(没有分类就展示空态)
writeFile(this.indexPath, this.renderPage({ model, base, active: firstCategory, article: null }));
// `/doc/`:默认展示第一个栏目(没有栏目就展示空态)
writeFile(this.indexPath, this.renderPage({ model, base, active: firstSection, article: null }));
written.push('index.html');
for (const category of model) {
for (const section of model) {
writeFile(
path.join(this.siteDir, category.code, 'index.html'),
this.renderPage({ model, base, active: category, article: null }),
path.join(this.siteDir, section.code, 'index.html'),
this.renderPage({ model, base, active: section, article: null }),
);
written.push(`${category.code}/index.html`);
written.push(`${section.code}/index.html`);
for (const article of category.articles) {
for (const article of section.articles) {
writeFile(
path.join(this.siteDir, category.code, `${article.slug}.html`),
this.renderPage({ model, base, active: category, article }),
path.join(this.siteDir, section.code, `${article.slug}.html`),
this.renderPage({ model, base, active: section, article }),
);
written.push(`${category.code}/${article.slug}.html`);
written.push(`${section.code}/${article.slug}.html`);
}
}
@ -143,10 +125,10 @@ class DocSiteService extends Service {
await this.generate(ctx);
}
/** 删掉已经不该存在的目录 / 页面(分类改名、文章下架后不留旧链接) */
/** 删掉已经不该存在的目录 / 页面(栏目改名、文章下架后不留旧链接) */
prune(model) {
const codes = new Set(model.map(category => category.code));
const slugsByCode = new Map(model.map(category => [ category.code, new Set(category.articles.map(article => `${article.slug}.html`)) ]));
const codes = new Set(model.map(section => section.code));
const slugsByCode = new Map(model.map(section => [ section.code, new Set(section.articles.map(article => `${article.slug}.html`)) ]));
for (const entry of fs.readdirSync(this.siteDir, { withFileTypes: true })) {
if (!entry.isDirectory()) continue;
@ -165,10 +147,10 @@ class DocSiteService extends Service {
/** 全站 URL:站点首页 + 文档站各级页面(顺序稳定,新增的排在最后) */
buildSitemapUrls(model, base) {
const urls = [ `${base}/`, `${base}/doc/` ];
for (const category of model) {
urls.push(`${base}/doc/${category.code}/`);
for (const article of category.articles) {
urls.push(`${base}/doc/${category.code}/${article.slug}.html`);
for (const section of model) {
urls.push(`${base}/doc/${section.code}/`);
for (const article of section.articles) {
urls.push(`${base}/doc/${section.code}/${article.slug}.html`);
}
}
return urls;
@ -212,30 +194,26 @@ class DocSiteService extends Service {
}
// ---------------- 渲染 ----------------
/** 顶部 tab(分类全量展示,全局可切换) */
/** 顶部 tab(栏目全量展示,全局可切换) */
renderTabs(model, active) {
return model.map(category => {
const isActive = active && category.code === active.code;
return `<a class="tab${isActive ? ' is-active' : ''}" href="/doc/${escape(category.code)}/">${escape(category.name)}</a>`;
return model.map(section => {
const isActive = active && section.code === active.code;
return `<a class="tab${isActive ? ' is-active' : ''}" href="/doc/${escape(section.code)}/">${escape(section.name)}</a>`;
}).join('');
}
/** 侧边栏:当前分类下的「栏目 → 内容页」 */
/** 侧边栏:当前栏目下的内容页列表(不再分组,直接就是文章) */
renderSidebar(active, article) {
if (!active) return '<p class="side-empty">还没有文档分类。</p>';
if (!active.groups.length) return '<p class="side-empty">这个分类下还没有内容。</p>';
if (!active) return '<p class="side-empty">还没有文档栏目。</p>';
if (!active.articles.length) return '<p class="side-empty">这个栏目下还没有内容。</p>';
return active.groups.map(group => `
<div class="side-group">
<div class="side-group__title">${escape(group.name)}</div>
<ul>
${group.articles.map(item => {
const href = `/doc/${escape(active.code)}/${escape(item.slug)}.html`;
const isActive = article && Number(article.id) === Number(item.id);
return `<li><a class="side-link${isActive ? ' is-active' : ''}" href="${href}">${escape(item.title)}</a></li>`;
}).join('')}
</ul>
</div>`).join('');
return `<ul>
${active.articles.map(item => {
const href = `/doc/${escape(active.code)}/${escape(item.slug)}.html`;
const isActive = article && Number(article.id) === Number(item.id);
return `<li><a class="side-link${isActive ? ' is-active' : ''}" href="${href}">${escape(item.title)}</a></li>`;
}).join('')}
</ul>`;
}
/** 正文第一行如果就是文章标题(`# 标题`),去掉它:标题已经在页头渲染过了 */
@ -247,12 +225,12 @@ class DocSiteService extends Service {
return source;
}
/** 文章正文(分类首页展示该分类第一篇文章) */
/** 文章正文(栏目首页展示该栏目第一篇文章) */
renderBody(active, article) {
if (!active) {
return `<div class="empty">
<h1>${SITE_NAME} · 文档</h1>
<p>文档站还没有内容。平台管理员可以在「平台管理 → 文档管理」里新建分类与内容页。</p>
<p>文档站还没有内容。平台管理员可以在「平台管理 → 文档管理」里新建栏目与内容页。</p>
</div>`;
}
@ -260,7 +238,7 @@ class DocSiteService extends Service {
if (!current) {
return `<div class="empty">
<h1>${escape(active.name)}</h1>
<p>${escape(active.description || '这个分类下还没有已发布的内容。')}</p>
<p>${escape(active.description || '这个栏目下还没有已发布的内容。')}</p>
</div>`;
}
@ -276,13 +254,13 @@ class DocSiteService extends Service {
${summary ? `<p class="doc-summary">${escape(summary)}</p>` : ''}
${created ? `<p class="doc-meta">创建于:${created}</p>` : ''}
</header>
${toc.length ? `<nav class="doc-toc" aria-label="本页目录">
<div class="doc-toc__title">本页目录</div>
<ul>${toc.map(item => `<li class="lv-${item.level}"><a class="doc-toc__link" href="#${item.id}" data-toc-id="${item.id}">${escape(item.text)}</a></li>`).join('')}</ul>
</nav>` : ''}
<div class="doc-body">
${rendered.html}
</div>
${toc.length ? `<nav class="doc-toc">
<div class="doc-toc__title">本页目录</div>
<ul>${toc.map(item => `<li class="lv-${item.level}"><a href="#${item.id}">${escape(item.text)}</a></li>`).join('')}</ul>
</nav>` : ''}
${updated ? `<p class="doc-foot">最后更新:${updated}</p>` : ''}
</article>`;
}
@ -315,7 +293,7 @@ ${this.styles()}
<span class="brand-dot" aria-hidden="true"></span>
${SITE_NAME} · 文档
</a>
<nav class="tabs" aria-label="文档分类">${this.renderTabs(model, active)}</nav>
<nav class="tabs" aria-label="文档栏目">${this.renderTabs(model, active)}</nav>
<a class="back" href="/">返回控制台 →</a>
</header>
@ -328,15 +306,74 @@ ${this.styles()}
${this.renderBody(active, current)}
</main>
</div>
<footer class="footer">
<span>${SITE_NAME} · 文档由「平台管理 → 文档管理」维护</span>
</footer>
${this.tocScript()}
</body>
</html>
`;
}
tocScript() {
return `<script>
(() => {
const content = document.querySelector('.content');
const toc = document.querySelector('.doc-toc');
if (!content || !toc) return;
const links = Array.from(toc.querySelectorAll('.doc-toc__link'));
const headings = links
.map(link => document.getElementById(link.dataset.tocId))
.filter(Boolean);
if (!headings.length) return;
let scheduled = false;
const updateActive = () => {
scheduled = false;
const root = content.getBoundingClientRect();
const threshold = root.top + Math.min(120, content.clientHeight * 0.2);
let active = headings[0];
for (const heading of headings) {
if (heading.getBoundingClientRect().top <= threshold) active = heading;
else break;
}
if (content.scrollTop + content.clientHeight >= content.scrollHeight - 2) {
active = headings[headings.length - 1];
}
links.forEach(link => {
const selected = link.dataset.tocId === active.id;
link.classList.toggle('is-active', selected);
if (selected) link.setAttribute('aria-current', 'location');
else link.removeAttribute('aria-current');
});
const activeLink = links.find(link => link.dataset.tocId === active.id);
if (activeLink) {
const tocRect = toc.getBoundingClientRect();
const linkRect = activeLink.getBoundingClientRect();
if (linkRect.top < tocRect.top) toc.scrollTop -= tocRect.top - linkRect.top;
else if (linkRect.bottom > tocRect.bottom) toc.scrollTop += linkRect.bottom - tocRect.bottom;
}
};
const scheduleUpdate = () => {
if (scheduled) return;
scheduled = true;
requestAnimationFrame(updateActive);
};
content.addEventListener('scroll', scheduleUpdate, { passive: true });
window.addEventListener('resize', scheduleUpdate, { passive: true });
window.addEventListener('load', scheduleUpdate, { once: true });
updateActive();
})();
</script>`;
}
styles() {
return `
:root {
@ -439,13 +476,6 @@ a:hover { text-decoration: underline; }
color: var(--text-muted);
margin: 0 6px 14px;
}
.side-group { margin-bottom: 18px; }
.side-group__title {
font-size: 12px;
font-weight: 700;
color: #334155;
margin: 0 6px 6px;
}
.sidebar ul { list-style: none; margin: 0; padding: 0; }
.side-link {
display: block;
@ -460,7 +490,7 @@ a:hover { text-decoration: underline; }
.side-empty { color: var(--text-muted); font-size: 13px; padding: 0 6px; }
.content {
padding: 32px 40px 64px;
padding: 32px 300px 64px 40px;
min-width: 0;
min-height: 0;
overflow-y: auto;
@ -505,19 +535,39 @@ a:hover { text-decoration: underline; }
.doc-body a { word-break: break-word; }
.doc-toc {
margin-top: 40px;
padding: 16px 18px;
position: fixed;
z-index: 20;
top: 76px;
right: 20px;
width: 260px;
max-height: calc(100vh - 96px);
overflow-y: auto;
padding: 14px 12px;
border: 1px solid var(--border);
border-radius: 10px;
background: var(--side-bg);
max-width: 820px;
box-shadow: 0 8px 24px rgba(15, 23, 42, 0.08);
}
.doc-toc__title { font-size: 12px; letter-spacing: 0.08em; color: var(--text-muted); margin-bottom: 8px; }
.doc-toc__title { font-size: 12px; letter-spacing: 0.08em; color: var(--text-muted); margin: 0 8px 8px; }
.doc-toc ul { list-style: none; margin: 0; padding: 0; }
.doc-toc li { margin: 3px 0; font-size: 13.5px; }
.doc-toc li { margin: 2px 0; font-size: 13px; }
.doc-toc__link {
display: block;
padding: 5px 8px;
border-radius: 6px;
color: #475569;
line-height: 1.5;
transition: background-color 0.15s ease, color 0.15s ease;
}
.doc-toc__link:hover { background: var(--brand-soft); text-decoration: none; }
.doc-toc__link.is-active { background: var(--brand); color: #fff; font-weight: 600; }
.doc-toc .lv-3 { padding-left: 14px; }
.doc-toc .lv-4 { padding-left: 28px; }
.doc-body h2,
.doc-body h3,
.doc-body h4 { scroll-margin-top: 20px; }
.doc-foot {
max-width: 820px;
margin: 32px 0 0;
@ -551,10 +601,22 @@ a:hover { text-decoration: underline; }
border-bottom: 1px solid var(--border);
padding: 16px 16px 20px;
}
.content { padding: 24px 20px 48px; }
.content { padding: 24px 280px 48px 20px; }
.doc-head h1 { font-size: 24px; }
}
@media (max-width: 860px) {
.content { padding-right: 20px; }
.doc-toc {
position: static;
width: auto;
max-height: none;
overflow: visible;
margin: 0 0 24px;
box-shadow: none;
}
}
/* 打印时恢复自然文档流,避免长文被固定高度裁掉 */
@media print {
html, body { height: auto; overflow: visible; }
@ -562,6 +624,7 @@ a:hover { text-decoration: underline; }
.topbar { position: static; }
.layout { display: block; overflow: visible; min-height: 0; }
.sidebar, .content { overflow: visible; max-height: none; height: auto; }
.doc-toc { position: static; width: auto; max-height: none; box-shadow: none; }
}
`;
}

View File

@ -76,8 +76,8 @@ module.exports = (appInfo) => {
};
// ==================== 文档站(简易 CMS 生成的静态页面)====================
// 内容存在 doc_categories / doc_sections / doc_articles,保存时由 service/docSite 整站生成:
// /doc/index.html、/doc/<分类>/index.html、/doc/<分类>/<文章>.html、/sitemap.txt
// 内容存在 doc_sections / doc_articles,保存时由 service/docSite 整站生成:
// /doc/index.html、/doc/<栏目>/index.html、/doc/<栏目>/<文章>.html、/sitemap.txt
// - dir:生成目录(run/ 已被 .gitignore 忽略,部署后首次访问会按需生成)
// - baseUrl:sitemap 里的站点根地址;不配则用触发生成的那次请求的 origin
// (生产建议配 SITE_BASE_URL=https://your.domain,避免 sitemap 里混进内网地址)

View File

@ -59,5 +59,7 @@ npm run db:migration:generate -- create_xxx_tables # 生成迁移骨架
| `20261028121000-drop-workstation-login-code` | 删除 `workstations.login_code`(`WSC-` 登录码已废弃,扫码登入改走微信登录网关的一次性二维码);`workstation_login_records.login_code` 保留作历史 |
| `20261029100000-drop-legacy-wechat-tables` | 删除 `wechat_oauth`(自建公众号网页授权)与 `wechat_mp_accounts`(小程序 code2Session 一键登录):微信侧接入已统一走登录网关;`down` 按原结构重建两张空表 |
| `20261029120000-create-admin-members` | 新表 `admin_members`(平台管理员:`user_id` 唯一、`name`、`role`、`status`、`remark`)+ 把内置管理员(`username='admin'`,没有就 `id=1`)先入表 |
| `20261107120000-create-doc-tables` | 新表 `doc_categories` / `doc_sections` / `doc_articles`(文档站三级结构)+ 一页「欢迎使用」示例(⚠️ 表结构已被 `20261109230000` 收紧成两级) |
| `20261109230000-doc-two-level-structure` | 文档站改成**两级**:`doc_categories` 改名 `doc_sections`(即「栏目」,保留 `code` / 名称 / 说明 / 排序 / 显隐),删掉原二级栏目表,`doc_articles.section_id` 改指栏目并删 `category_id` |
> 历史遗留的 `sql/schema.sql` + `sql/migrations/*.sql`(用 `npm run db:init` 执行)是接入 sequelize-cli 之前的做法,
> 只用于初始化老表;**新变更一律写 `database/migrations/*.js`**。

View File

@ -0,0 +1,136 @@
'use strict';
/**
* 文档站层级从「分类 → 栏目 → 内容页」收紧成两级:**栏目 → 内容页**
*
* - 原来的「分类」整表升级成「栏目」:`doc_categories` 改名 `doc_sections`,
* `code` / `name` / `description` / `sort` / `status` 全部保留,页面地址 `/doc/<code>/<slug>.html` 不变;
* - 原来的二级「栏目」表删掉,底下的内容页直接挂到顶层(`section_id` 改指原 `category_id`);
* - `doc_articles.category_id` 不再需要(栏目就是顶层),一并删除。
*
* 内容页一条不丢:只是从「分类 → 栏目 → 文章」压平成「栏目 → 文章」。
*/
/** 索引存在才删(生产环境可能有人手工调整过) */
async function removeIndexIfExists(queryInterface, table, name) {
const [rows] = await queryInterface.sequelize.query(
'SELECT 1 FROM information_schema.statistics WHERE table_schema = DATABASE() AND table_name = ? AND index_name = ? LIMIT 1',
{ replacements: [ table, name ] },
);
if (rows.length) await queryInterface.removeIndex(table, name);
}
module.exports = {
async up(queryInterface) {
// 1. 内容页改挂在顶层上(原分类 id),随后二级栏目表就没用了
await queryInterface.sequelize.query('UPDATE doc_articles SET section_id = category_id');
await removeIndexIfExists(queryInterface, 'doc_articles', 'idx_doc_articles_tree');
await removeIndexIfExists(queryInterface, 'doc_articles', 'idx_doc_articles_slug');
await queryInterface.removeColumn('doc_articles', 'category_id');
await queryInterface.dropTable('doc_sections');
// 2. 原「分类」表改名成「栏目」表(文章的 section_id 已经指过来了)
await removeIndexIfExists(queryInterface, 'doc_categories', 'idx_doc_categories_status_sort');
await queryInterface.renameTable('doc_categories', 'doc_sections');
// 3. 表 / 字段注释跟着改语义(只改文案,不动类型与索引)
await queryInterface.sequelize.query("ALTER TABLE `doc_sections` COMMENT = '文档栏目表'");
await queryInterface.sequelize.query(
"ALTER TABLE `doc_sections` MODIFY COLUMN `name` VARCHAR(64) NOT NULL COMMENT '栏目名称(顶部 tab 文案)', MODIFY COLUMN `description` VARCHAR(255) NULL COMMENT '栏目说明(可选)'",
);
await queryInterface.sequelize.query(
"ALTER TABLE `doc_articles` MODIFY COLUMN `section_id` BIGINT UNSIGNED NOT NULL COMMENT '所属栏目 doc_sections.id'",
);
// 4. 索引按新层级重建
await queryInterface.addIndex('doc_sections', [ 'status', 'sort' ], { name: 'idx_doc_sections_status_sort' });
await queryInterface.addIndex('doc_articles', [ 'section_id', 'sort' ], { name: 'idx_doc_articles_section_sort' });
await queryInterface.addIndex('doc_articles', [ 'section_id', 'slug' ], { name: 'idx_doc_articles_slug' });
// 5. 演示内容跟着新文案走(只改还有旧措辞的那一页)
await queryInterface.sequelize.query(
`UPDATE doc_articles
SET content = REPLACE(
REPLACE(
REPLACE(content,
'- 顶部 tab 是「分类」,点一下就能切换;', '- 顶部 tab 是「栏目」,点一下就能切换;'),
'- 左侧是分类下的「栏目 → 内容页」;', '- 左侧直接列出当前栏目的内容页;'),
'在「文档管理」里新建分类 / 栏目 / 内容页;', '在「文档管理」里新建栏目,再往栏目里加内容页;')
WHERE slug = 'welcome' AND deleted_at IS NULL`,
);
},
async down(queryInterface, Sequelize) {
const { BIGINT, STRING, INTEGER, TINYINT, DATE } = Sequelize;
// ---- 先按新结构把数据复制回「分类」,再重建二级栏目 ----
await queryInterface.addColumn('doc_articles', 'category_id', {
type: BIGINT.UNSIGNED, allowNull: true, comment: '所属分类(冗余,列表用)',
});
await queryInterface.sequelize.query('UPDATE doc_articles SET category_id = section_id');
await queryInterface.createTable('doc_categories', {
id: { type: BIGINT.UNSIGNED, primaryKey: true, autoIncrement: true, allowNull: false },
code: { type: STRING(32), allowNull: false, unique: true, comment: 'URL 片段(/doc/<code>/)' },
name: { type: STRING(64), allowNull: false, comment: '分类名称(tab 文案)' },
description: { type: STRING(255), allowNull: true, comment: '分类说明(可选)' },
sort: { type: INTEGER.UNSIGNED, allowNull: false, defaultValue: 0, comment: '排序(小的在前)' },
status: { type: TINYINT.UNSIGNED, allowNull: false, defaultValue: 1, comment: '状态:1 展示 0 隐藏' },
created_at: { type: DATE, allowNull: false, defaultValue: Sequelize.literal('CURRENT_TIMESTAMP') },
updated_at: { type: DATE, allowNull: false, defaultValue: Sequelize.literal('CURRENT_TIMESTAMP') },
deleted_at: { type: DATE, allowNull: true },
}, { comment: '文档分类表' });
await queryInterface.sequelize.query(
`INSERT INTO doc_categories (id, code, name, description, sort, status, created_at, updated_at, deleted_at)
SELECT id, code, name, description, sort, status, created_at, updated_at, deleted_at FROM doc_sections`,
);
await queryInterface.dropTable('doc_sections');
await queryInterface.createTable('doc_sections', {
id: { type: BIGINT.UNSIGNED, primaryKey: true, autoIncrement: true, allowNull: false },
category_id: { type: BIGINT.UNSIGNED, allowNull: false, comment: '所属分类 doc_categories.id' },
name: { type: STRING(64), allowNull: false, comment: '栏目名称(侧边栏分组标题)' },
sort: { type: INTEGER.UNSIGNED, allowNull: false, defaultValue: 0, comment: '排序(小的在前)' },
status: { type: TINYINT.UNSIGNED, allowNull: false, defaultValue: 1, comment: '状态:1 展示 0 隐藏' },
created_at: { type: DATE, allowNull: false, defaultValue: Sequelize.literal('CURRENT_TIMESTAMP') },
updated_at: { type: DATE, allowNull: false, defaultValue: Sequelize.literal('CURRENT_TIMESTAMP') },
deleted_at: { type: DATE, allowNull: true },
}, { comment: '文档栏目表' });
// 每个分类补一个同名栏目,内容页都挂上去
await queryInterface.sequelize.query(
`INSERT INTO doc_sections (category_id, name, sort, status, created_at, updated_at)
SELECT id, name, 10, status, created_at, updated_at FROM doc_categories`,
);
await queryInterface.sequelize.query(
`UPDATE doc_articles a
JOIN doc_sections s ON s.category_id = a.category_id
SET a.section_id = s.id`,
);
await queryInterface.changeColumn('doc_articles', 'category_id', {
type: BIGINT.UNSIGNED, allowNull: false, comment: '所属分类(冗余,列表用)',
});
// ---- 索引恢复成三级结构 ----
await removeIndexIfExists(queryInterface, 'doc_articles', 'idx_doc_articles_section_sort');
await removeIndexIfExists(queryInterface, 'doc_articles', 'idx_doc_articles_slug');
await removeIndexIfExists(queryInterface, 'doc_sections', 'idx_doc_sections_status_sort');
await queryInterface.addIndex('doc_categories', [ 'status', 'sort' ], { name: 'idx_doc_categories_status_sort' });
await queryInterface.addIndex('doc_sections', [ 'category_id', 'sort' ], { name: 'idx_doc_sections_category_sort' });
await queryInterface.addIndex('doc_articles', [ 'category_id', 'section_id', 'sort' ], { name: 'idx_doc_articles_tree' });
await queryInterface.addIndex('doc_articles', [ 'category_id', 'slug' ], { name: 'idx_doc_articles_slug' });
await queryInterface.sequelize.query(
`UPDATE doc_articles
SET content = REPLACE(
REPLACE(
REPLACE(content,
'- 顶部 tab 是「栏目」,点一下就能切换;', '- 顶部 tab 是「分类」,点一下就能切换;'),
'- 左侧直接列出当前栏目的内容页;', '- 左侧是分类下的「栏目 → 内容页」;'),
'在「文档管理」里新建栏目,再往栏目里加内容页;', '在「文档管理」里新建分类 / 栏目 / 内容页;')
WHERE slug = 'welcome' AND deleted_at IS NULL`,
);
},
};

View File

@ -209,15 +209,14 @@ export function removeAdminPlan(id: number): Promise<{ id: number }> {
}
// ==================== 文档站(简易 CMS)====================
// 层级:分类(顶部 tab)→ 栏目(侧边栏分组)→ 内容页(Markdown)。
// 层级:栏目(顶部 tab,也是左侧列表的标题)→ 内容页(Markdown),只有两级。
// 每次保存都会让后端**整站重生成** `/doc/**` 的静态页面与 `/sitemap.txt`。
/** 内容页(列表里不带正文) */
export interface DocArticleNode {
id: number;
categoryId: number;
sectionId: number;
categoryCode: string;
sectionCode: string;
title: string;
slug: string;
summary: string;
@ -225,7 +224,7 @@ export interface DocArticleNode {
/** 1 已发布 0 草稿 */
status: number;
statusText: string;
/** 站点内地址(`/doc/<分类>/<文章>.html`) */
/** 站点内地址(`/doc/<栏目>/<文章>.html`) */
url: string;
updatedAt?: string | null;
}
@ -235,20 +234,8 @@ export interface DocArticleDetail extends DocArticleNode {
content: string;
}
/** 栏目(分类下的一级列表) */
/** 栏目(文档站最外层,左栏直接列出它下面的内容页) */
export interface DocSectionNode {
id: number;
categoryId: number;
name: string;
sort: number;
/** 1 展示 0 隐藏 */
status: number;
statusText: string;
articles: DocArticleNode[];
}
/** 分类(顶部 tab) */
export interface DocCategoryNode {
id: number;
code: string;
name: string;
@ -258,20 +245,13 @@ export interface DocCategoryNode {
status: number;
statusText: string;
articleCount: number;
sections: DocSectionNode[];
}
export interface DocCategoryInput {
code?: string;
name?: string;
description?: string | null;
sort?: number;
status?: number;
articles: DocArticleNode[];
}
export interface DocSectionInput {
categoryId?: number;
code?: string;
name?: string;
description?: string | null;
sort?: number;
status?: number;
}
@ -286,24 +266,11 @@ export interface DocArticleInput {
status?: number;
}
/** 整棵文档树(分类 → 栏目 → 内容页) */
export function fetchDocTree(): Promise<{ list: DocCategoryNode[]; total: number }> {
/** 整棵文档树(栏目 → 内容页) */
export function fetchDocTree(): Promise<{ list: DocSectionNode[]; total: number }> {
return api.get('/api/web/admin/doc/tree');
}
export function createDocCategory(body: DocCategoryInput): Promise<DocCategoryNode> {
return api.post('/api/web/admin/doc/categories', body);
}
export function updateDocCategory(id: number, body: DocCategoryInput): Promise<DocCategoryNode> {
return api.put(`/api/web/admin/doc/categories/${id}`, body);
}
/** 删除分类(栏目与内容页一起删) */
export function removeDocCategory(id: number): Promise<{ id: number }> {
return api.del(`/api/web/admin/doc/categories/${id}`);
}
export function createDocSection(body: DocSectionInput): Promise<DocSectionNode> {
return api.post('/api/web/admin/doc/sections', body);
}

View File

@ -77,7 +77,7 @@ const routes: RouteRecordRaw[] = [
component: () => import('@/views/AdminExtensionView.vue'),
meta: { allowNoSubject: true, platformAdmin: true },
},
// 文档站(简易 CMS):分类 → 栏目 → 内容页;保存后自动生成 /doc/** 静态页面与 sitemap.txt
// 文档站(简易 CMS):栏目 → 内容页(两级);保存后自动生成 /doc/** 静态页面与 sitemap.txt
{
path: '/admin/doc',
name: 'admin-doc',

View File

@ -2,7 +2,8 @@
/**
* 平台管理 · 文档管理(简易 CMS)
*
* 层级固定两级:**分类**(文档站顶部 tab)→ **栏目**(侧边栏分组)→ **内容页**(Markdown)。
* 层级固定两级:**栏目**(文档站顶部 tab,也是左栏标题)→ **内容页**(Markdown)。
* 左栏直接列出当前栏目下的内容页,不再有「分类」这一级。
* 保存后由后端整站重生成 `/doc/**` 静态页面与 `/sitemap.txt`(新链接追加在 sitemap 末尾)。
*
* 接口:`/api/web/admin/doc/*`(平台管理员)
@ -13,20 +14,15 @@ import ModalBox from '@/components/ModalBox.vue';
import { ApiError } from '@/api/client';
import {
createDocArticle,
createDocCategory,
createDocSection,
fetchDocArticle,
fetchDocTree,
rebuildDocSite,
removeDocArticle,
removeDocCategory,
removeDocSection,
updateDocArticle,
updateDocCategory,
updateDocSection,
type DocArticleInput,
type DocCategoryInput,
type DocCategoryNode,
type DocSectionInput,
type DocSectionNode,
} from '@/api/admin';
@ -34,27 +30,26 @@ import {
/** 文档站在站点里的入口(后端生成的静态 HTML) */
const DOC_SITE_URL = '/doc/';
const tree = ref<DocCategoryNode[]>([]);
const sections = ref<DocSectionNode[]>([]);
const loading = ref(false);
const error = ref('');
const ok = ref('');
const activeCategoryId = ref(0);
const activeSectionId = ref(0);
const activeArticleId = ref(0);
const categories = computed(() => tree.value);
const activeCategory = computed(() => tree.value.find(item => item.id === activeCategoryId.value) || null);
const sections = computed(() => activeCategory.value?.sections || []);
const activeSection = computed(() => sections.value.find(item => item.id === activeSectionId.value) || null);
const articles = computed(() => activeSection.value?.articles || []);
async function load(keepSelection = true) {
loading.value = true;
error.value = '';
try {
const data = await fetchDocTree();
tree.value = data.list;
const exists = tree.value.some(item => item.id === activeCategoryId.value);
sections.value = data.list;
const exists = sections.value.some(item => item.id === activeSectionId.value);
if (!keepSelection || !exists) {
activeCategoryId.value = tree.value.length ? tree.value[0].id : 0;
activeSectionId.value = sections.value.length ? sections.value[0].id : 0;
activeArticleId.value = 0;
resetArticle();
}
@ -65,10 +60,11 @@ async function load(keepSelection = true) {
}
}
/** 生成地址:`/doc/<分类编码>/<文章地址>.html` */
/** 生成地址:`/doc/<栏目编码>/<文章地址>.html` */
function articleUrl(slug: string): string {
if (!slug || !activeCategory.value) return '';
return `/doc/${activeCategory.value.code}/${slug}.html`;
const section = sections.value.find(item => item.id === Number(articleForm.sectionId)) || activeSection.value;
if (!slug || !section) return '';
return `/doc/${section.code}/${slug}.html`;
}
// ==================== 内容页编辑 ====================
@ -121,8 +117,10 @@ async function selectArticle(id: number) {
}
}
/** 新建内容页:默认落在某个栏目下,排序排到最后 */
function openArticleCreate(section: DocSectionNode) {
/** 新建内容页:落在当前栏目下,排序排到最后 */
function openArticleCreate() {
const section = activeSection.value;
if (!section) return;
error.value = '';
ok.value = '';
activeArticleId.value = 0;
@ -133,11 +131,11 @@ function openArticleCreate(section: DocSectionNode) {
: 10;
}
/** 切分类:当前文章不在新分类里就换成该分类第一篇 */
function selectCategory(id: number) {
if (id === activeCategoryId.value) return;
activeCategoryId.value = id;
const all = sections.value.flatMap(section => section.articles);
/** 切栏目:当前文章不在新栏目里就换成该栏目第一篇 */
function selectSection(id: number) {
if (id === activeSectionId.value) return;
activeSectionId.value = id;
const all = activeSection.value?.articles || [];
if (all.some(item => item.id === activeArticleId.value)) return;
if (all.length) {
void selectArticle(all[0].id);
@ -173,6 +171,7 @@ async function saveArticle() {
if (editing.value) {
const data = await updateDocArticle(articleForm.id, body);
ok.value = `已保存「${data.title}」,已重新生成文档页面与 sitemap`;
activeSectionId.value = data.sectionId;
await load();
await selectArticle(data.id);
} else {
@ -180,6 +179,7 @@ async function saveArticle() {
if (slug) body.slug = slug;
const data = await createDocArticle(body);
ok.value = `已新增「${data.title}」:${data.url || articleUrl(data.slug)}`;
activeSectionId.value = data.sectionId;
await load();
await selectArticle(data.id);
}
@ -210,8 +210,8 @@ async function deleteArticle() {
}
}
// ==================== 分类 ====================
interface CategoryForm {
// ==================== 栏目 ====================
interface SectionForm {
id: number;
code: string;
name: string;
@ -220,115 +220,18 @@ interface CategoryForm {
status: number;
}
const categoryOpen = ref(false);
const categorySaving = ref(false);
const categoryForm = reactive<CategoryForm>({ id: 0, code: '', name: '', description: '', sort: 10, status: 1 });
function openCategoryCreate() {
error.value = '';
ok.value = '';
Object.assign(categoryForm, {
id: 0,
code: '',
name: '',
description: '',
sort: categories.value.length
? Math.max(...categories.value.map(item => item.sort)) + 10
: 10,
status: 1,
});
categoryOpen.value = true;
}
function openCategoryEdit() {
const current = activeCategory.value;
if (!current) return;
error.value = '';
ok.value = '';
Object.assign(categoryForm, {
id: current.id,
code: current.code,
name: current.name,
description: current.description || '',
sort: current.sort,
status: current.status,
});
categoryOpen.value = true;
}
const canSaveCategory = computed(() => Boolean(categoryForm.name.trim()));
async function saveCategory() {
if (!canSaveCategory.value) return;
const body: DocCategoryInput = {
name: categoryForm.name.trim(),
description: categoryForm.description.trim() || null,
sort: Number(categoryForm.sort),
status: categoryForm.status,
};
categorySaving.value = true;
error.value = '';
ok.value = '';
try {
if (categoryForm.id) {
const data = await updateDocCategory(categoryForm.id, body);
ok.value = `分类「${data.name}」已保存`;
} else {
const code = categoryForm.code.trim().toLowerCase();
if (code) body.code = code;
const data = await createDocCategory(body);
ok.value = `分类「${data.name}」已新增(地址 /doc/${data.code}/ )`;
activeCategoryId.value = data.id;
}
categoryOpen.value = false;
await load();
} catch (err) {
error.value = err instanceof ApiError ? err.message : '保存失败';
} finally {
categorySaving.value = false;
}
}
async function deleteCategory() {
const current = activeCategory.value;
if (!current) return;
if (!window.confirm(`确认删除分类「${current.name}」?\n\n底下的 ${current.sections.length} 个栏目和 ${current.articleCount} 篇内容会一起删除。`)) return;
error.value = '';
ok.value = '';
try {
await removeDocCategory(current.id);
ok.value = `分类「${current.name}」已删除`;
activeCategoryId.value = 0;
activeArticleId.value = 0;
resetArticle();
await load(false);
} catch (err) {
error.value = err instanceof ApiError ? err.message : '删除失败';
}
}
// ==================== 栏目 ====================
interface SectionForm {
id: number;
name: string;
sort: number | string;
status: number;
}
const sectionOpen = ref(false);
const sectionSaving = ref(false);
const sectionForm = reactive<SectionForm>({ id: 0, name: '', sort: 10, status: 1 });
const sectionForm = reactive<SectionForm>({ id: 0, code: '', name: '', description: '', sort: 10, status: 1 });
function openSectionCreate() {
if (!activeCategory.value) return;
error.value = '';
ok.value = '';
Object.assign(sectionForm, {
id: 0,
code: '',
name: '',
description: '',
sort: sections.value.length
? Math.max(...sections.value.map(item => item.sort)) + 10
: 10,
@ -337,14 +240,18 @@ function openSectionCreate() {
sectionOpen.value = true;
}
function openSectionEdit(section: DocSectionNode) {
function openSectionEdit() {
const current = activeSection.value;
if (!current) return;
error.value = '';
ok.value = '';
Object.assign(sectionForm, {
id: section.id,
name: section.name,
sort: section.sort,
status: section.status,
id: current.id,
code: current.code,
name: current.name,
description: current.description || '',
sort: current.sort,
status: current.status,
});
sectionOpen.value = true;
}
@ -356,6 +263,7 @@ async function saveSection() {
const body: DocSectionInput = {
name: sectionForm.name.trim(),
description: sectionForm.description.trim() || null,
sort: Number(sectionForm.sort),
status: sectionForm.status,
};
@ -368,8 +276,13 @@ async function saveSection() {
const data = await updateDocSection(sectionForm.id, body);
ok.value = `栏目「${data.name}」已保存`;
} else {
const data = await createDocSection({ ...body, categoryId: activeCategoryId.value });
ok.value = `栏目「${data.name}」已新增`;
const code = sectionForm.code.trim().toLowerCase();
if (code) body.code = code;
const data = await createDocSection(body);
ok.value = `栏目「${data.name}」已新增(地址 /doc/${data.code}/ )`;
activeSectionId.value = data.id;
activeArticleId.value = 0;
resetArticle();
}
sectionOpen.value = false;
await load();
@ -380,20 +293,20 @@ async function saveSection() {
}
}
async function deleteSection(section: DocSectionNode) {
const tip = `确认删除栏目「${section.name}」?\n\n底下的 ${section.articles.length} 篇内容会一起删除。`;
if (!window.confirm(tip)) return;
async function deleteSection() {
const current = activeSection.value;
if (!current) return;
if (!window.confirm(`确认删除栏目「${current.name}」?\n\n底下的 ${current.articleCount} 篇内容会一起删除。`)) return;
error.value = '';
ok.value = '';
try {
await removeDocSection(section.id);
ok.value = `栏目「${section.name}」已删除`;
if (section.articles.some(item => item.id === activeArticleId.value)) {
activeArticleId.value = 0;
resetArticle();
}
await load();
await removeDocSection(current.id);
ok.value = `栏目「${current.name}」已删除`;
activeSectionId.value = 0;
activeArticleId.value = 0;
resetArticle();
await load(false);
} catch (err) {
error.value = err instanceof ApiError ? err.message : '删除失败';
}
@ -427,22 +340,22 @@ onMounted(() => load(false));
<div v-if="ok" class="alert alert-ok">{{ ok }}</div>
<div class="doc-admin">
<!-- 左:分类 tab + 栏目 / 内容页树 -->
<!-- 左:栏目 tab + 当前栏目的内容页列表 -->
<section class="card doc-nav">
<div class="toolbar toolbar-wrap">
<button class="btn btn-sm" @click="openCategoryCreate">新增分类</button>
<button class="btn btn-ghost btn-sm" :disabled="!activeCategory" @click="openCategoryEdit">编辑分类</button>
<button class="btn btn-danger btn-sm" :disabled="!activeCategory" @click="deleteCategory">删除分类</button>
<button class="btn btn-sm" @click="openSectionCreate">新增栏目</button>
<button class="btn btn-ghost btn-sm" :disabled="!activeSection" @click="openSectionEdit">编辑栏目</button>
<button class="btn btn-danger btn-sm" :disabled="!activeSection" @click="deleteSection">删除栏目</button>
</div>
<div class="cat-tabs">
<button
v-for="item in categories"
v-for="item in sections"
:key="item.id"
type="button"
class="cat-tab"
:class="{ 'is-active': item.id === activeCategoryId }"
@click="selectCategory(item.id)"
:class="{ 'is-active': item.id === activeSectionId }"
@click="selectSection(item.id)"
>
{{ item.name }}
<span class="cat-count">{{ item.articleCount }}</span>
@ -451,36 +364,25 @@ onMounted(() => load(false));
</div>
<p v-if="loading" class="hint">加载中…</p>
<p v-else-if="!categories.length" class="hint">还没有分类,点「新增分类」开始。</p>
<p v-else-if="!sections.length" class="hint">还没有栏目,点「新增栏目」开始。</p>
<div v-else class="tree">
<div v-for="section in sections" :key="section.id" class="tree-group">
<div class="tree-head">
<b>{{ section.name }}</b>
<span v-if="section.status === 0" class="badge badge-off">隐藏</span>
<span class="tree-ops">
<a href="#" @click.prevent="openArticleCreate(section)">+内容</a>
<a href="#" @click.prevent="openSectionEdit(section)">编辑</a>
<a href="#" class="is-danger" @click.prevent="deleteSection(section)">删除</a>
</span>
</div>
<ul>
<li
v-for="article in section.articles"
:key="article.id"
class="tree-item"
:class="{ 'is-active': article.id === activeArticleId }"
@click="selectArticle(article.id)"
>
<span class="tree-title">{{ article.title }}</span>
<span v-if="article.status === 0" class="badge badge-off">草稿</span>
</li>
<li v-if="!section.articles.length" class="tree-empty">这个栏目还没有内容</li>
</ul>
</div>
<ul>
<li
v-for="article in articles"
:key="article.id"
class="tree-item"
:class="{ 'is-active': article.id === activeArticleId }"
@click="selectArticle(article.id)"
>
<span class="tree-title">{{ article.title }}</span>
<span v-if="article.status === 0" class="badge badge-off">草稿</span>
</li>
<li v-if="!articles.length" class="tree-empty">这个栏目还没有内容</li>
</ul>
<div class="tree-foot">
<button class="btn btn-ghost btn-sm" :disabled="!activeCategory" @click="openSectionCreate">新增栏目</button>
<button class="btn btn-ghost btn-sm" :disabled="!activeSection" @click="openArticleCreate">新增内容</button>
<button class="btn btn-ghost btn-sm" :disabled="rebuilding" @click="rebuild">
{{ rebuilding ? '生成中…' : '重新生成文档站' }}
</button>
@ -491,10 +393,9 @@ onMounted(() => load(false));
<!-- 右:内容页编辑 -->
<section class="card doc-editor">
<p v-if="!activeCategory" class="hint">先在左边选一个分类。</p>
<p v-else-if="!sections.length" class="hint">这个分类下还没有栏目,点「新增栏目」建一个,再往里面加内容页。</p>
<p v-if="!activeSection" class="hint">先在左边选一个栏目。</p>
<p v-else-if="!articleForm.id && articleForm.sectionId === ''" class="hint">
点左侧「+内容」新建内容页,或点某一篇开始编辑。
点左侧「新增内容」新建内容页,或点某一篇开始编辑。
</p>
<template v-else>
@ -567,61 +468,21 @@ onMounted(() => load(false));
</section>
</div>
<!-- 分类弹窗 -->
<ModalBox
:open="categoryOpen"
:title="categoryForm.id ? '编辑分类' : '新增分类'"
width="520px"
@close="categoryOpen = false"
>
<div class="form-grid">
<label class="field span-2">
<span>分类名称(文档站顶部 tab)</span>
<input v-model="categoryForm.name" maxlength="64" placeholder="如:设备接入" />
</label>
<label v-if="!categoryForm.id" class="field span-2">
<span>分类编码(可选,留空自动生成 cat1)</span>
<input v-model="categoryForm.code" maxlength="32" placeholder="小写字母 / 数字 / 短横线,创建后不可改" />
</label>
<label class="field">
<span>排序(小的在前)</span>
<input v-model="categoryForm.sort" type="number" min="0" max="9999" />
</label>
<label class="field">
<span>状态</span>
<select v-model.number="categoryForm.status">
<option :value="1">展示</option>
<option :value="0">隐藏(不生成页面)</option>
</select>
</label>
<label class="field span-2">
<span>分类说明(可选)</span>
<input v-model="categoryForm.description" maxlength="255" placeholder="如:录像机 / 摄像头 / 工作台的接入步骤" />
</label>
</div>
<p v-if="categoryForm.id" class="hint">
分类编码 <code>{{ categoryForm.code }}</code> 决定地址 <code>/doc/{{ categoryForm.code }}/</code>,创建后不能修改。
</p>
<template #footer>
<button class="btn btn-ghost" :disabled="categorySaving" @click="categoryOpen = false">取消</button>
<button class="btn" :disabled="categorySaving || !canSaveCategory" @click="saveCategory">
{{ categorySaving ? '保存中…' : '保存' }}
</button>
</template>
</ModalBox>
<!-- 栏目弹窗 -->
<ModalBox
:open="sectionOpen"
:title="sectionForm.id ? '编辑栏目' : '新增栏目'"
width="440px"
width="520px"
@close="sectionOpen = false"
>
<div class="form-grid">
<label class="field span-2">
<span>栏目名称(侧边栏分组标题)</span>
<input v-model="sectionForm.name" maxlength="64" placeholder="如:安装部署" />
<span>栏目名称(文档站顶部 tab)</span>
<input v-model="sectionForm.name" maxlength="64" placeholder="如:设备接入" />
</label>
<label v-if="!sectionForm.id" class="field span-2">
<span>栏目编码(可选,留空自动生成 sec1)</span>
<input v-model="sectionForm.code" maxlength="32" placeholder="小写字母 / 数字 / 短横线,创建后不可改" />
</label>
<label class="field">
<span>排序(小的在前)</span>
@ -634,7 +495,14 @@ onMounted(() => load(false));
<option :value="0">隐藏(不生成页面)</option>
</select>
</label>
<label class="field span-2">
<span>栏目说明(可选)</span>
<input v-model="sectionForm.description" maxlength="255" placeholder="如:录像机 / 摄像头 / 工作台的接入步骤" />
</label>
</div>
<p v-if="sectionForm.id" class="hint">
栏目编码 <code>{{ sectionForm.code }}</code> 决定地址 <code>/doc/{{ sectionForm.code }}/</code>,创建后不能修改。
</p>
<template #footer>
<button class="btn btn-ghost" :disabled="sectionSaving" @click="sectionOpen = false">取消</button>
@ -654,7 +522,7 @@ onMounted(() => load(false));
align-items: start;
}
/* 左侧导航:分类 tab 换行铺满,树列表可滚动 */
/* 左侧导航:栏目 tab 换行铺满,内容页列表可滚动 */
.doc-nav {
display: flex;
flex-direction: column;
@ -700,35 +568,9 @@ onMounted(() => load(false));
opacity: 0.75;
}
.tree-group {
margin-bottom: 14px;
}
.tree-head {
display: flex;
align-items: center;
gap: 6px;
padding: 4px 2px;
}
.tree-head b {
font-size: 13px;
}
.tree-ops {
margin-left: auto;
display: flex;
gap: 8px;
font-size: 12px;
}
.tree-ops .is-danger {
color: var(--danger);
}
.tree ul {
list-style: none;
margin: 4px 0 0;
margin: 0;
padding: 0;
}