From 78cee0fe1a36d38c663cec4ffdf2f1685a8064d8 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Sat, 7 Nov 2026 20:33:46 +0800 Subject: [PATCH] =?UTF-8?q?feat(doc):=20=E9=A6=96=E9=A1=B5=E7=99=BB?= =?UTF-8?q?=E5=BD=95=E5=88=86=E6=B5=81=20+=20=E6=96=87=E6=A1=A3=E7=AB=99?= =?UTF-8?q?=EF=BC=88=E7=AE=80=E6=98=93=20CMS=20/=20=E9=9D=99=E6=80=81=20HT?= =?UTF-8?q?ML=20/=20sitemap=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 首页:`/` 未登录原地显示登录页(不再跳 /login),已登录直接进 `/dashboard`; 看板路由由 `/` 迁到 `/dashboard`,侧边栏「首页」与无权限回跳同步; 桌面端「工具 → 打开配置页」的 `/?token=` 免登录仍然可用 - 文档站:`/doc/**` 由后端整站生成静态 HTML(顶部分类 tab 全局切换、左侧栏目 → 内容页、 右侧本页目录);`/sitemap.txt` 新链接追加到末尾,下架 / 删除的会被清理 - 平台管理 · 文档管理(`/admin/doc`):分类 / 栏目 / 内容页(Markdown)简易 CMS, 内容页有编辑表单与列表,保存后自动重生成目录与静态页面 - 登录页右下角、顶栏(登录后)、看板右上角新增进入文档站的链接 - 部署:nginx 模板为 `/doc`、`/doc/`、`/sitemap.txt` 增加反代(否则会落到 SPA 回退); Vite dev server 增加同名代理;`middleware/frontend.js` 排除这些路径 - 登录页插画改为内联 SVG(沿用工作区已有的未提交改动) - 测试:新增 Markdown 渲染单测;后端 218 个用例通过,前端 typecheck / build 通过 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 7 + backend/README.md | 46 +- backend/app/controller/web/admin_doc.js | 120 +++ backend/app/controller/web/doc.js | 73 ++ backend/app/lib/markdown.js | 175 ++++ backend/app/middleware/frontend.js | 2 + backend/app/model/doc_article.js | 31 + backend/app/model/doc_category.js | 28 + backend/app/model/doc_section.js | 25 + backend/app/router.js | 20 + backend/app/service/doc.js | 454 ++++++++++ backend/app/service/doc_site.js | 523 +++++++++++ backend/config/config.default.js | 11 + .../20261107120000-create-doc-tables.js | 127 +++ backend/scripts/deploy/deploy-lib.cjs | 10 +- backend/test/app/lib/markdown.test.js | 60 ++ frontend/src/api/admin.ts | 130 +++ frontend/src/assets/login-hero.svg | 102 --- frontend/src/assets/packing-station-hero.svg | 279 ++++++ frontend/src/components/AppLayout.vue | 33 +- frontend/src/router/index.ts | 27 +- frontend/src/views/AdminDocView.vue | 839 ++++++++++++++++++ frontend/src/views/HomeView.vue | 5 + frontend/src/views/LoginView.vue | 47 +- frontend/vite.config.ts | 3 + 25 files changed, 3059 insertions(+), 118 deletions(-) create mode 100644 backend/app/controller/web/admin_doc.js create mode 100644 backend/app/controller/web/doc.js create mode 100644 backend/app/lib/markdown.js create mode 100644 backend/app/model/doc_article.js create mode 100644 backend/app/model/doc_category.js create mode 100644 backend/app/model/doc_section.js create mode 100644 backend/app/service/doc.js create mode 100644 backend/app/service/doc_site.js create mode 100644 backend/database/migrations/20261107120000-create-doc-tables.js create mode 100644 backend/test/app/lib/markdown.test.js delete mode 100644 frontend/src/assets/login-hero.svg create mode 100644 frontend/src/assets/packing-station-hero.svg create mode 100644 frontend/src/views/AdminDocView.vue diff --git a/README.md b/README.md index 787d69f..c1db95e 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,13 @@ packService/ - [x] **平台管理 · 套餐管理(2026-11-07)**:左侧「平台管理」新增**套餐管理**(`/admin/plans`): 新增 / 改价 / 改天数 / 上下架 / 删除续期套餐;续期下单只按库里的售价算钱,改完即生效、不用发版 (接口 `GET/POST/PUT/DELETE /api/web/admin/plans`,详见 [`backend/README.md`](backend/README.md)) +- [x] **登录入口与文档站(2026-11-07)**: + - **`/` 就是入口**:已登录 → 自动进看板 `/dashboard`;未登录 → **原地**显示登录页(地址保持在 `/`,不再跳 `/login`); + 看板路由从 `/` 挪到 `/dashboard`,侧边栏「首页」与各处「被拒绝」回跳同步改过去; + - **文档站** `/doc/**`:后端生成的**静态 HTML**(顶部 tab 切分类、左侧「栏目 → 内容页」、右侧本页目录), + 页面保存后自动重生成,新链接追加到 `/sitemap.txt`; + - **平台管理 · 文档管理**(`/admin/doc`):分类 / 栏目 / 内容页(Markdown)的简易 CMS,保存即重生成; + - 登录页右下角、顶栏(登录后)与看板右上角都有进入文档站的链接 - [x] **待支付订单 2 小时自动失效(2026-10-29)**:下单后 2 小时(`PAY_ORDER_TTL`,默认 7200 秒)内未支付, 订单自动关闭(`status=2`);之后的支付回调 / 手工确认一律 409。与微信扫码支付二维码有效期对齐, 定时任务每分钟扫一次,详情 / 列表 / 回调读路径也会顺手收口(详见 [`backend/README.md`](backend/README.md)) diff --git a/backend/README.md b/backend/README.md index ec189e2..0de4c9e 100644 --- a/backend/README.md +++ b/backend/README.md @@ -39,6 +39,8 @@ 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(分类 / 栏目 / 内容页,❗需平台管理员) +│ │ │ ├── doc.js # GET /doc/**、/sitemap.txt 文档站(公开,直接回生成好的静态 HTML) │ │ │ ├── extension.js # /api/web/extension/config 插件读取的配置(公开只读,无令牌) │ │ │ └── test.js # /api/web/test/{device-login,scan} 前端测试页的模拟接口(仅非生产环境注册) │ │ ├── internal/ # 运维/内部(❗需内部令牌,挂在 middleware.internalAuth() 后面) @@ -67,7 +69,10 @@ packService/backend │ │ ├── sys_config.js # sys_config │ │ ├── scanner.js # scanners │ │ ├── scan_channel.js # scan_channels -│ │ └── scan_record.js # scan_records(去重) +│ │ ├── scan_record.js # scan_records(去重) +│ │ ├── doc_category.js # doc_categories(文档分类 = 顶部 tab) +│ │ ├── doc_section.js # doc_sections(分类下的一级栏目) +│ │ └── doc_article.js # doc_articles(内容页,Markdown 原文) │ ├── service │ │ ├── auth.js # 登录校验(bcrypt 密码比对)+ 自助注册 │ │ ├── admin_member.js # 平台管理员:名单维护 + isAdmin(admin_members / INTERNAL_ADMIN_IDS) @@ -82,7 +87,11 @@ packService/backend │ │ ├── scan.js # 中控通道上报 / 扫码入库去重 / 扫码查询 │ │ ├── health.js # MySQL / Redis 连通性探测 │ │ ├── user.js # 用户数据访问(app.model.User) -│ │ └── wx_gateway.js # 微信登录网关:临时码 / 验签 / 会话长轮询 / 绑定关系 +│ │ ├── wx_gateway.js # 微信登录网关:临时码 / 验签 / 会话长轮询 / 绑定关系 +│ │ ├── doc.js # 文档站 CMS:分类 / 栏目 / 内容页的增删改查(写完自动重生成) +│ │ └── doc_site.js # 文档站生成:把库里的内容渲染成 /doc/** 静态 HTML + /sitemap.txt +│ ├── lib +│ │ └── markdown.js # 极简 Markdown → HTML(先转义再拼标签,附文章内目录) │ └── router.js ├── config │ ├── config.default.js # 统一配置(连接 / 端口 / 安全 / 前端入口 / 内部鉴权) @@ -975,7 +984,7 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql()); - 「查状态」→ `GET /api/wechat/status?code=…`(无需登录):`pending`(待扫码)/ `confirmed`(已被确认)/ `expired`(没这个码); - 「请求登录」→ `POST /api/wechat/confirm`(`{ code }`):`data.status='confirmed'` 即授权成功,电脑端正在长轮询的请求会**立即**完成登录;已用过/不存在/格式错分别返回 `used` / `expired` / `bad_format`; - **鉴权完全模仿小程序**:AJAX 把用户 JWT 放在 `Authorization: Bearer` 头里(`fetch` 不带 `credentials`),页面上也把这枚令牌显示出来方便贴到小程序里调试; -- **鉴权总览**:`/api/web/*`、`/api/wechat/confirm` 走 `app/middleware/api_auth.js`(**只认 header 里的用户令牌**),其中 `/api/web/admin/*` 再叠一层 `app/middleware/platform_admin.js`(平台管理员);`/api/users*`、`/api/configs*`、`/api/scanners*` 走 `app/middleware/internal_auth.js`(`X-Internal-Token` 或白名单账号的 user JWT);`/api/scanner/*`、`/api/scan/*` 走 `app/middleware/scanner_auth.js`(设备长期 JWT);公开接口只有 `/api/info`、`/health`、`/api/wechat/{status,qrcode.svg}`、`/api/wechat-gateway/notify`、`/api/device/login` 与 `/api/web/auth/*`; +- **鉴权总览**:`/api/web/*`、`/api/wechat/confirm` 走 `app/middleware/api_auth.js`(**只认 header 里的用户令牌**),其中 `/api/web/admin/*` 再叠一层 `app/middleware/platform_admin.js`(平台管理员);`/api/users*`、`/api/configs*`、`/api/scanners*` 走 `app/middleware/internal_auth.js`(`X-Internal-Token` 或白名单账号的 user JWT);`/api/scanner/*`、`/api/scan/*` 走 `app/middleware/scanner_auth.js`(设备长期 JWT);公开接口只有 `/api/info`、`/health`、`/api/wechat/{status,qrcode.svg}`、`/api/wechat-gateway/notify`、`/api/device/login` 与 `/api/web/auth/*`;另外 `/doc/**`、`/sitemap.txt` 是文档站的静态页面(公开,不走 SPA,见「文档站」一节); - 密码等敏感信息放 `config/config.local.js`(已 gitignore)或环境变量,不要写进 `config.default.js`。 - 生产环境请修改 `config/config.default.js` 中的 `config.keys`。 @@ -1049,6 +1058,36 @@ await this.ctx.service.cache.remember('user:1', 60, () => loadFromMysql()); (后台页面已不提供这个输入框;配置里的值只在 version.json 拉不到时兜底); - 生产若配了 `CORS_ORIGINS` 白名单,记得把 `chrome-extension://<扩展ID>` 加进去(默认 `*` 不用管)。 +## 文档站(简易 CMS,2026-11-07) + +文档站是**静态 HTML**:内容存在库里,保存时由 `service/docSite` 整站渲染到 `run/doc-site/`(`run/` 被 gitignore), +`controller/web/doc.js` 只负责回文件(文件不存在时按需重新生成,部署后不用手工跑构建)。 + +- 层级:**分类**(文档站顶部 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。 + +### 接口(`/api/web/admin/doc/*`,全部要求平台管理员) + +| 方法 | 路径 | 说明 | +|---|---|---| +| 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/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` 作草稿,不生成页面) | +| DELETE | `/api/web/admin/doc/articles/:id` | 删除内容页 | +| POST | `/api/web/admin/doc/rebuild` | 手动整站重生成(排查用,返回页面数与 sitemap 条数) | + +公开读取(无令牌):`GET /doc/**`、`GET /sitemap.txt`。 + ### 前端(`frontend/`) 左侧菜单在**平台管理员**登录后会多出一组「平台管理」(`components/AppLayout.vue`): @@ -1060,6 +1099,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),保存即重生成静态页面 | - 是否显示这组菜单靠 `GET /api/web/admin/me`(`composables/usePlatformAdmin.ts`;非管理员 403 静默当 false); - 路由带 `meta.platformAdmin`,不是平台管理员会被守卫踢回首页(`?denied=1`); diff --git a/backend/app/controller/web/admin_doc.js b/backend/app/controller/web/admin_doc.js new file mode 100644 index 0000000..943b98f --- /dev/null +++ b/backend/app/controller/web/admin_doc.js @@ -0,0 +1,120 @@ +'use strict'; + +const { Controller } = require('egg'); + +/** 路径参数转正整数,非法返回 null */ +function toId(value) { + const id = Number(value); + return Number.isInteger(id) && id > 0 ? id : null; +} + +/** + * web 平台管理员:文档站(简易 CMS) + * + * 鉴权:`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` 删除分类(栏目与内容页一起删) + * - `POST /api/web/admin/doc/sections` 新增栏目 + * - `PUT /api/web/admin/doc/sections/:id` 修改栏目 + * - `DELETE /api/web/admin/doc/sections/:id` 删除栏目(内容页一起删) + * - `GET /api/web/admin/doc/articles/:id` 单篇(含正文) + * - `POST /api/web/admin/doc/articles` 新增内容页 + * - `PUT /api/web/admin/doc/articles/:id` 修改内容页 + * - `DELETE /api/web/admin/doc/articles/:id` 删除内容页 + * - `POST /api/web/admin/doc/rebuild` 手动整站重生成(排查用) + * + * 所有写操作都会重生成 `/doc/**` 静态页面与 `/sitemap.txt`(见 `service/doc.js`)。 + */ +class WebAdminDocController extends Controller { + /** GET /api/web/admin/doc/tree */ + async tree() { + const data = await this.ctx.service.doc.tree(); + 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 || {}); + this.ctx.status = 201; + this.ctx.body = { ok: true, data }; + } + + /** PUT /api/web/admin/doc/sections/:id */ + async updateSection() { + const id = this.requireId(); + const data = await this.ctx.service.doc.updateSection(id, this.ctx.request.body || {}); + this.ctx.body = { ok: true, data }; + } + + /** DELETE /api/web/admin/doc/sections/:id */ + async destroySection() { + const data = await this.ctx.service.doc.removeSection(this.requireId()); + this.ctx.body = { ok: true, data }; + } + + /** GET /api/web/admin/doc/articles/:id */ + async showArticle() { + const data = await this.ctx.service.doc.findArticle(this.requireId()); + this.ctx.body = { ok: true, data }; + } + + /** POST /api/web/admin/doc/articles */ + async createArticle() { + const data = await this.ctx.service.doc.createArticle(this.ctx.request.body || {}); + this.ctx.status = 201; + this.ctx.body = { ok: true, data }; + } + + /** PUT /api/web/admin/doc/articles/:id */ + async updateArticle() { + const id = this.requireId(); + const data = await this.ctx.service.doc.updateArticle(id, this.ctx.request.body || {}); + this.ctx.body = { ok: true, data }; + } + + /** DELETE /api/web/admin/doc/articles/:id */ + async destroyArticle() { + const data = await this.ctx.service.doc.removeArticle(this.requireId()); + this.ctx.body = { ok: true, data }; + } + + /** POST /api/web/admin/doc/rebuild */ + async rebuild() { + const { ctx } = this; + const files = await ctx.service.docSite.generate(ctx); + const model = await ctx.service.docSite.loadModel(); + const urls = ctx.service.docSite.buildSitemapUrls(model, ctx.service.docSite.baseUrl(ctx)); + ctx.body = { ok: true, data: { files: files.length, urls: urls.length } }; + } + + requireId() { + const id = toId(this.ctx.params.id); + if (!id) this.ctx.throw(400, 'id 必须是正整数'); + return id; + } +} + +module.exports = WebAdminDocController; diff --git a/backend/app/controller/web/doc.js b/backend/app/controller/web/doc.js new file mode 100644 index 0000000..04c2784 --- /dev/null +++ b/backend/app/controller/web/doc.js @@ -0,0 +1,73 @@ +'use strict'; + +const fs = require('fs'); +const { Controller } = require('egg'); + +/** + * 文档站(公开,静态 HTML) + * + * 后端**不参与渲染**:`service/docSite` 在内容保存时把页面生成到 `run/doc-site`, + * 这里只做「路径 → 文件」的映射与缓存头控制。文件被人删了 / 刚部署上来时按需重新生成。 + * + * - `GET /doc` → 301 到 `/doc/` + * - `GET /doc/…` → 生成好的 HTML(分类首页 `index.html` / 内容页 `.html`) + * - `GET /sitemap.txt` → 全站 URL(页面顺序稳定,新增的追加在末尾) + */ +class WebDocController extends Controller { + /** GET /doc(`/doc/` 会被 koa-router 的 strict:false 归到同一条路由,这里区分处理) */ + async redirect() { + const { ctx } = this; + if (ctx.path === '/doc') { + ctx.redirect('/doc/'); + return; + } + await this.page(); + } + + /** GET /doc/** */ + async page() { + const { ctx } = this; + await ctx.service.docSite.ensureSite(ctx); + + const file = ctx.service.docSite.resolveFile(this.relativePath(ctx.path)); + if (!file || !this.isfile(file)) { + // 页面已经下架 / 改名,文件被清掉了:整站重生成一次再试 + await ctx.service.docSite.generate(ctx); + if (!file || !this.isfile(file)) ctx.throw(404, '文档页面不存在'); + } + + ctx.set('Cache-Control', 'no-cache'); + ctx.type = 'html'; + ctx.body = fs.createReadStream(file); + } + + /** GET /sitemap.txt */ + async sitemap() { + const { ctx } = this; + await ctx.service.docSite.ensureSite(ctx); + + const file = ctx.service.docSite.sitemapPath; + if (!this.isfile(file)) await ctx.service.docSite.generate(ctx); + + ctx.set('Cache-Control', 'no-cache'); + ctx.type = 'text/plain; charset=utf-8'; + ctx.body = fs.createReadStream(file); + } + + /** `/doc/guide/welcome.html` → `guide/welcome.html`;`/doc/guide/` → `guide/index.html` */ + relativePath(pathname) { + const clean = String(pathname || '').replace(/^\/doc\/?/, ''); + if (!clean) return 'index.html'; + return clean.endsWith('/') ? `${clean}index.html` : clean; + } + + isfile(file) { + try { + return fs.statSync(file).isFile(); + } catch { + return false; + } + } +} + +module.exports = WebDocController; diff --git a/backend/app/lib/markdown.js b/backend/app/lib/markdown.js new file mode 100644 index 0000000..9d3b753 --- /dev/null +++ b/backend/app/lib/markdown.js @@ -0,0 +1,175 @@ +'use strict'; + +/** + * 极简 Markdown → HTML(文档站专用) + * + * 只支持写文档够用的子集:标题 / 段落 / 列表 / 引用 / 代码块 / 行内代码 / 粗体 / 斜体 / 删除线 / 链接 / 分割线。 + * **先转义再拼 HTML**:文档站是公开页面,后台输入的内容一律当纯文本处理,避免把 `', + '', + '[点我](javascript:alert(1))', + '', + '![图](http://x.com/a.png)', + ].join('\n')).html; + + assert.ok(!html.includes(' + +