Zhl2010 第二博客 (Cloud + Local) Spec

Why

Zhl2010 需要一个完全自控的第二博客：本地自由修改配置与文章，通过 Git 推送到 Cloudflare Pages 自动构建上线，不受云存储限制。博客需具备现代化、清新的极致视觉，拥有账号系统、评论、AI 总结、完整洛谷风格 Markdown/LaTeX 渲染，并实现与第一博客（zhlblog.ccwu.cc）的文章自动同步。

What Changes

• 全新的 Astro + TypeScript 博客项目，@astrojs/cloudflare 适配（server 输出），一套代码支持「云端 / 本地」两种构建模式。
• 双部署方式（可并存）：① 本地 Git 仓库 + Cloudflare Pages Git 自动构建；② 不经过 GitHub，本地构建后用 wrangler pages deploy 直接上传同一 Pages 项目（绕过 Git）。若目标域名受限无法用于直传，则回退部署到 weblog.zhl2010.cc。
• Cloudflare Workers(D1) 提供后端 API：账号注册/登录/验证码、评论、站点配置管理。
• 洛谷全功能 Markdown 渲染：KaTeX(LaTeX)、折叠框、align、epigraph、cute-table、表格合并、行号与高亮、Bilibili 内嵌、内嵌原始 HTML。
• 现代化清新 UI，参考 Hexo 主题库审美；生成式图片（Seedream）与算法艺术（algorithmic-art）用于视觉装饰。
• 文章功能：分类/标签/封面/摘要/置顶/目录导航、右侧列表、链接、AI 总结（OpenAI 兼容 API）。
• 账号系统：QQ 邮箱白名单注册、用户自己的邮箱(RESEND)发送验证码、登录会话、角色。
• 管理员无限权限：站点信息/底部/导航/简介等全部在线可改，文章在线 CRUD，评论管理。
• 与第一博客的文章自动同步脚本。

Impact

• 影响能力：全新项目，无既有代码。
• 影响代码：本仓库为第二博客唯一代码库（web 前端 + Worker API + D1 schema + 部署配置）。

关键外部依赖（需用户提供/授权）

• Cloudflare 账号（Pages 项目可 Git 连接也可直传、D1 数据库、Workers 与 API Token / wrangler 登录）。
• 部署域名：Git 路径目标 blog.zhl2010.ccwu.cc；直传回退域名 weblog.zhl2010.cc。
• 发信 API：Resend Authorization: Bearer re_9hsAtxAs_M8UAiX5Pn5S1BYuqqMydAMkZ，发件人 zhl2010.ccwu.cc（已验证域名）。见 http://note.ms/ZhlMailToolMyuse。
• AI 总结：用户后续提供 OpenAI 兼容 BaseURL + API Key，配置化。
• 第一博客同步：第一博客仓库路径与折叠框转换服务 https://my.zhl2010.ccwu.cc/blog/change（需用户在 GitHub/CF 提供访问）。

ADDED Requirements

Requirement: 工程基础与双模式构建

系统 SHALL 是一个 Astro + TypeScript 项目，使用 @astrojs/cloudflare 适配器，可输出到 Cloudflare Pages。

• 通过环境变量（如 PUBLIC_MODE=cloud|local）区分云端/本地，仅修改底部简介文案：云端=Zhl2010 第二博客，云端版本。（云端），本地=Zhl2010 第二博客，本地版本。（本地）。
• 本地 npm run dev 可预览；npm run build 输出 .vercel/wrangler 产物由 Pages 托管。
• 仓库根目录文件组织整齐：src/、public/、workers/（如需要）、db/、scripts/、content/。

Scenario: 本地开发

• WHEN 开发者运行 npm run dev 并设 PUBLIC_MODE=local
• THEN 博客在本地打开，底部显示「本地版本」文案，且无数据库依赖的核心页面可用。

Scenario: 云端构建

• WHEN 推送代码到连接的 Git 仓库
• THEN Cloudflare Pages 自动构建发布到 blog.zhl2010.ccwu.cc，底部显示「云端版本」文案。

Scenario: 本地直传（不经 Git）

• WHEN 用户本地 npm run build 后运行直传脚本（wrangler pages deploy）
• THEN 产物直接上传同一 Pages 项目并生效，无需 push/Git 触发；若直传域名受限于改用 weblog.zhl2010.cc，则部署到该域名。
• 说明：Pages 项目可同时开启 Git 连接与直传，两者可并存（后上传者生效最后）。

Requirement: 洛谷兼容 Markdown / LaTeX 渲染

系统 SHALL 将文章 Markdown 按洛谷手册渲染，至少支持：

• KaTeX 数学：行内 $...$、行间 $$...$$，支持 \displaystyle/\textstyle、矩阵、求和/积分、环境等 KaTeX 支持的语法。
• 代码块：按语言高亮；line-numbers 显示行号；lines=start-end 高亮范围；未指定语言默认 C++ 样式。
• 表格：GFM 表格、合并单元格（^ 向上、< 向左，单元格内唯一纯文本）、::cute-table{tuack} 增强表格。
• 折叠框：::::info/success/warning/error[标题]{open}，{open} 默认展开，标题支持 LaTeX，支持多层冒号嵌套。
• 区块：:::align{center}/{right}、:::epigraph[——来源]。
• 其他：标题/强调/删除线/引用/有序无序任务列表/链接/标题链接/图片/自动链接/分隔线/转义/表格。
• Bilibili 视频内嵌。
• 允许内嵌原始 HTML（用户自行使用），不按洛谷禁 HTML 处理。
• 在折叠框等容器中数学公式与 Markdown 正常嵌套。

Scenario: 渲染折叠框

• WHEN 文章含 ::::warning[警告]{open} ... :::: 且返回页面
• THEN 页面显示可折叠警告框（默认展开），支持嵌套，框内数学公式正常渲染。

Scenario: 渲染数学公式

• WHEN 文章含 $$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$$
• THEN 以 KaTeX 数学块渲染，点击可缩放/复制源码。

Scenario: 内嵌 HTML

• WHEN 文章含自定义 <div class="..."> 等原始 HTML
• THEN 原样渲染，不被转义。

Requirement: 文章与信息架构

系统 SHALL 支持常见博客功能：

• 文章 frontmatter：title、date、updated、tags、categories、summary、cover、draft、sticky(置顶)、order、hidden。
• 首页/归档/文章详情；文章列表卡片式。
• 顶部导航（可配置链接）；文章页右侧目录(TOC)/文章列表；支持站外链接。
• 分类与标签页；搜索文章。
• 上一篇/下一篇与相关推荐。

Scenario: 查看文章

• WHEN 用户打开一篇文章 URL
• THEN 看到标题、日期、标签、目录、正文、上一篇/下一篇、评论区。

Scenario: 分类/标签浏览

• WHEN 用户点击某标签或分类
• THEN 过滤出对应文章列表。

Requirement: AI 总结

系统 SHALL 提供文章 AI 总结：管理员配置 OpenAI 兼容 BaseURL/API Key/Model 后，文章页提供「AI 总结」按钮，调用接口生成结构化摘要（可含关键点列表），结果可缓存/复制。

• API 与凭据仅存后端环境变量/配置，不暴露到前端。

Scenario: 生成 AI 总结

• WHEN 已配置 API 且用户点击「AI 总结」
• THEN 显示正在生成状态，完成后展示摘要与关键点，可复制、可再次生成。

Requirement: 用户账号系统

系统 SHALL 支持邮箱注册/登录：

• 注册邮箱 仅限 QQ 邮箱（白名单 @qq.com，含 foxmail.com 可选，管理员可配置）。
• 发送验证码邮件使用用户的 Resend 邮箱（zhl2010.ccwu.cc），验证码 5 分钟有效，可配置频控。
• 登录态通过 Worker 会话（D1 + Cookie，HttpOnly）。
• 角色：user / admin。首个注册用户或通过环境变量 ADMIN_EMAIL 设为管理员。
• 隐私：密码哈希存储（如 scrypt/argon2），不存明文。

Scenario: 注册

• WHEN 用户提交非 QQ/不在白名单邮箱
• THEN 提示该邮箱不在白名单内，注册失败。

Scenario: 登录

• WHEN 用户输入 QQ 邮箱、接收验证码并提交
• THEN 校验通过后建立登录会话并跳转回原页面。

Requirement: 评论系统

系统 SHALL 提供文章评论：

• 登录用户可发表评论；支持 Markdown/数学/折叠框等安全渲染（与正文渲染一致但做安全过滤）。
• 评论支持回复、点赞；管理员可编辑/删除/隐藏。
• 游客可浏览评论，发表需登录。

Scenario: 发表评论

• WHEN 登录用户在某文章下提交评论
• THEN 评论保存到 D1 并即时显示，支持 Markdown 渲染与回复。

Requirement: 管理员后台与站点配置

系统 SHALL 为管理员提供在线后台（无限权限）：

• 站点信息可改：标题、副标题、描述、作者、头像、Logo、footer（底部）全部字样、备案/版权、导航/友链、简介文案（云端/本地）。
• 文章管理：新建/编辑/删除/发布/隐藏/置顶在线操作。
• 用户管理：查看用户、设置角色、封禁。
• 评论管理：审核/删除。
• 系统配置：白名单邮箱、AI 总结 OpenAI 配置、验证码频控。
• 以上配置持久化到 D1，前端读取生效。

Scenario: 修改底部字样

• WHEN 管理员在后台编辑 footer 文本并保存
• THEN 站点所有页面底部显示新文本（前台无需重新构建）。

Scenario: 在线发文

• WHEN 管理员在后台创建/编辑文章（可含 Markdown、LaTeX、折叠框）并发布
• THEN 文章出现在前台，无需本地提交。

Requirement: 现代化清新 UI

系统 SHALL 提供极致现代、清新、整齐的视觉：

• 参考 Hexo 主题库（如 a.minifog.org.cn 的清爽风格）与 web 开发 UI 规范（uicraft）。
• 响应式；亮/暗主题；平滑动效；现代字体与排版；卡片、圆角、柔和阴影、渐变点缀。
• 用 generated 图片（Seedream）生成封面/OG/品牌素材；用 algorithmic-art(p5.js) 制作装饰背景/页头动效。
• 保证性能：字体子集、图片懒加载、KaTeX 按需加载、无闪烁的暗色主题。

Scenario: 暗色主题

• WHEN 用户切换深色模式或跟随系统
• THEN 全站配色平滑过渡，阅读区对比度良好。

Requirement: 与第一博客自动同步

系统 SHALL 支持将第一博客新增文章自动同步到第二博客：

• 脚本读取第一博客仓库新文章（Markdown）。
• 经 https://my.zhl2010.ccwu.cc/blog/change 转换折叠框语法（第一博客配置的转换流）。
• 转换后写入第二博客 content/，提交并推送 → 触发第二博客 Pages 自动构建。
• 避免重复同步（按标题/内容指纹去重）。本项依赖 GitHub/CF 访问与第一博客仓库路径，需用户提供后才能完成。

Scenario: 第一博客新增文章

• WHEN 第一博客新增/更新一篇文章且脚本被触发
• THEN 该文章经折叠框转换后出现在第二博客并上线，且不会重复产生。

REMOVED Requirements

无（全新项目）。