生活碎片 / Blog 设计总纲

Blog 设计总纲

blog.ysoseri.us — 一座可被阅读的 Obsidian 式个人博客仓库

状态：设计冻结 v1.0，待本地实现

最后更新：2026-07-30

依据：blog_thought.md、design.md、soul.md 与 ref.png

一、文档使用方式

本文件是 Blog 实现的必读入口，只保存产品定义、跨模块约束和详细规范索引。已经确认的完整规则位于 blog_spec/；这些文件共同构成实施依据，不是可选参考。

开始完整实现前，必须阅读本文件和六份详细规范。
有界修改至少阅读本文件、对应详细规范及其验收文件。
涉及内容状态、权限、发布、缓存、搜索或数据恢复时，必须同时阅读发布工程与工程验收规范。
摘要用于导航，不能覆盖详细规则；文件之间如有冲突，先修正文档再实现。
当前用户指令优先于既有文档，并应在确认后同步写回相应规范。

详细规范索引

文件	负责范围
content.md	仓库、分类、标签、文章属性、永久链接、`/manage` 与 API 路由
interface.md	Obsidian 工作区结构、桌面与移动端、主站视觉映射、折角、cursor、材质与动效
reading-editing.md	浏览、搜索、排序、Markdown 阅读、管理工作区、编辑器、快捷键与界面语言
publishing-engineering.md	内容状态、鉴权、保存历史、媒体、导入、D1 / R2 / Worker、搜索、备份、SEO 与性能
acceptance-product.md	内容模型、导航、搜索、标签页、属性、侧栏与移动端验收 SOP
acceptance-engineering.md	编辑、快捷键、冲突、定时发布、鉴权、语法、部署、SEO、性能与文档维护 SOP

二、产品定义

2.1 产品定位

Blog 使用接近原生 Obsidian 的界面结构和操作语义组织个人写作，不是在普通文章列表外套一层 Obsidian 皮肤。访客进入的是可以浏览、搜索和切换内容仓库的个人写作空间；主站的配色、字体、cursor、材质和动效让它明确属于 ysoseri.us。

2.2 用户

访客：阅读、搜索和发现公开文章。
作者：仅用户本人，负责新建、导入、编辑、发布和管理内容。
不做公开注册、多用户写作或多作者协作。

2.3 核心体验

左侧文件树、仓库、标签页、搜索和右侧栏都对应真实内容与状态，不保留没有博客语义的假控件。
仓库是独立内容空间，切换时整套文件树、标签现场、搜索、精选和侧栏状态一起切换。
Markdown 正文始终是中间区域的视觉与阅读焦点。
文章关联通过真实链接、Wiki 链接、嵌入与反向链接表达，不做关系图谱。
公开阅读和作者管理共享同一内容真相，但使用不同权限、快照和路由边界。

2.4 明确不做

不做文章机器翻译或双语配对；中英切换只改变界面语言。
不做关系图谱、白板、今日日记、模板、数据库、插件入口或无真实能力的 Obsidian 装饰。
不保留窗口最小化、还原、关闭按钮和空白新标签页 +。
不用隐藏入口、前端状态、robots 或不可猜测 ID 代替服务端鉴权。
不为技术展示引入没有明确故障或性能需求的 Cloudflare 产品。

三、不可违背的跨模块约束

视觉归属：Obsidian 与 ref.png 决定结构、密度和操作；根域 /homepage 与 design.md 决定暖中性色、珊瑚陶土橙、衬线正文、无衬线 UI、cursor、纸面材质和克制动效。
内容组织：分类单选、标签多选；仓库可新增、改名、修改 URL key、切换公开 / 不列出 / 私密和删除。显示路径随整理更新，内容身份不随标题或路径变化。
路由分层：公开文章使用 /{repository-key}/{article-slug}；/manage 是唯一管理入口；管理页面和作者 API 使用不可变 post_id；API 分为 /api/auth/*、/api/manage/* 与 /api/public/*，不建立公开 /post/{id} 第二页面。
内容实时性：工作稿与公开快照分离。普通保存不改变访客内容；发布、更新发布、定时发布和撤回只在完整操作成功后切换公开状态。
时间语义：计划时间保存 IANA 时区与 UTC 执行时刻，必须正确处理 Pacific/Auckland 等地区的夏令时。
编辑与历史：默认 Live Preview，同时提供源码和正式发布预览；本地即时保护、约 1 秒云同步、可查看差异与历史恢复，并使用 revision 防止多标签页或多设备静默覆盖。
鉴权：使用站内密码和可撤销的 30 天服务端会话；高风险操作再次验证；每个作者 API 独立检查会话、来源与权限。
媒体边界：媒体资产面向整个 ysoseri.us 生态共享；Blog 管理工作区提供一级媒体入口，编辑器只保留轻量选择器。完整 /media 服务仍按 todo.md 单独实施。
数据架构：blog-content D1 保存内容真相，blog-search D1 保存可重建 FTS5，R2 保存媒体、不可变历史、公开快照与备份，Worker 负责鉴权、API、渲染、发布和定时任务，UI 使用 Workers Static Assets。
安全同步：发布先完成 R2 快照，再切换内容指针并通过幂等 outbox 更新公共搜索；撤回或转私密先退出公共索引，再关闭公开访问。允许暂时搜不到，不能提前泄露。
备份恢复：近期误操作使用 D1 Time Travel；Cron 触发 Workflow 把可导出的内容库备份到受 90 天 Bucket Lock / Lifecycle 保护的私有 R2；正式恢复导入新 D1、校验引用、切换 binding，再重建搜索库。
公开出口：canonical、可抓取目录、完整正文 RSS、sitemap、Open Graph、JSON-LD 与分享卡片统一来自当前公开快照；不列出内容使用 noindex 并退出所有主动发现出口。
质感与性能：纸面颗粒、字体、cursor 和微动效是正式要求；优化重复计算、重绘和加载时机，不能默认删除质感。公开页目标为 LCP ≤ 2.5 秒、INP ≤ 200 ms、CLS ≤ 0.1、TTFB ≤ 800 ms。
测试数据：标准边界测试集最多 100 篇，由固定种子程序化生成并覆盖状态、权限、语法、媒体、语言和长度；只存在于隔离环境，测试后删除，不产生生产僵尸数据。额外规模压测使用临时轻量记录。
权限与部署：设计和本地实现阶段不零碎申请 Cloudflare 权限。全部本地任务完成后统一提交最小 scope 清单，由作者一次签发 for blog Token，再集中创建资源、迁移、配置域名、部署和端到端测试；Token 明文只保存在根目录本地 assets.md，不进入公开 Blog 仓库或浏览器。

四、当前状态与维护边界

原 22 项设计讨论已全部确认；已完成的讨论队列和重复确认清单不再保留。
当前阶段是“设计冻结、本地实现已完成、待统一部署”，不能把本文指标描述成已经达成的线上结果。
预览部署后再执行真实 Core Web Vitals、性能 trace、网络瀑布和跨浏览器回归。
/media 全站媒体服务与 /dashboard 统一后台仍是 todo.md 中的独立任务，不扩大本轮 Blog 实现范围。
纯设计讨论只修改设计文档；开始修改代码、配置、数据库、资产或部署后，按 CLAUDE.md 更新 dev.md，涉及资产时同步更新 assets.md。