84 lines
4.9 KiB
Markdown
84 lines
4.9 KiB
Markdown
# Phase 1：Astro 骨架+设计系统+五页型+极客层 P0 - 项目范围
|
||
|
||
<!-- spec-format: 2 -->
|
||
|
||
## 1. 问题定义
|
||
- **项目目标**：在 Astro 5 上实现博客前端全骨架——设计 tokens、自托管分片字体、三轨内容集合、五类页面、明暗模式、极客层 P0、搜索/RSS，可在 staging 演练部署
|
||
- **目标用户**：站长（Phase 2 迁入真实内容即可上线）
|
||
- **核心价值**：丙路线「灰阶骨架×分轨正文」从样板变成可构建可部署的真实代码
|
||
|
||
## 2. 假设与待确认
|
||
|
||
### 2.1 已确认事实
|
||
- Node v22.22.3 + pnpm 11.3.0 可用；remote origin = https://git.wait4x.online/wait4x/blog.git（Phase 0 已推 main）
|
||
- 设计规格全部定稿（docs/博客重设计调研报告.md v1.8 §2 丙路线/§3 排版参数/§4c 极客层/§4e 多端）
|
||
- 样板参考 design/mockup.html（v2，1050 行，三属性驱动：route/scheme/page）
|
||
- 预字体包：lxgw-wenkai-screen-webfont / @fontsource/noto-sans-sc / @fontsource/jetbrains-mono（npm 预分片自托管，替代 cn-font-split 构建步）
|
||
|
||
### 2.2 关键假设
|
||
- 上述 npm 预分片字体包的 unicode-range 切片质量满足按需加载（若不满足，回退 vite-plugin-font 方案）
|
||
- 样例内容（等待戈多等）可先行入库 content/，Phase 2 再被真实迁移覆盖
|
||
|
||
### 2.3 待确认问题
|
||
- [x] Lighthouse 移动端 ≥90 需真实域名（Phase 4 预发布验收执行；本包只做结构自查）→ 结论：按此执行
|
||
|
||
### 2.4 可选解释与取舍
|
||
- 预分片 npm 字体包 > cn-font-split 构建：零构建工具、社区维护切片、同样自托管；代价是包体切片策略不可定制 → 接受
|
||
- 样例内容先行 > 空集合：页面开发需要真实排版观感（书评长文/代码块/照片比例）→ 接受
|
||
|
||
### 2.5 已证伪路径
|
||
- 无
|
||
|
||
## 3. 功能范围
|
||
|
||
### 3.1 核心功能（MVP）
|
||
- [ ] T1 Astro 5 初始化（pnpm+TS strict）
|
||
- [ ] T2 设计 tokens + 全局样式（丙路线参数）
|
||
- [ ] T3 自托管分片字体三轨接入
|
||
- [ ] T4 内容集合（posts/moments/photos + EXIF loader）
|
||
- [ ] T5 布局/导航/页脚/明暗不闪烁
|
||
- [ ] T6 五页型（首页/文章双模板/图库/瞬间/关于）
|
||
- [ ] T7 极客层 P0（键盘+帮助/build-info/View Transitions/项目墙）
|
||
- [ ] T8 Artalk 占位 + Pagefind + RSS + sitemap
|
||
- [ ] T9 响应式结构自查（§4e 断点全覆盖）
|
||
- [ ] T10 staging 部署演练（build.sh 填实）
|
||
|
||
### 3.2 扩展功能
|
||
- 书评索引画廊页、/now·/stack·/colophon（Phase 4+ 二期）
|
||
|
||
### 3.3 不在范围内
|
||
- 真实内容迁移（Phase 2）、双语管线（Phase 3）、上线切换与 Lighthouse 实测（Phase 4）、Halo 退役（Phase 5）
|
||
|
||
## 4. 最小实现路径
|
||
- 单 Astro 项目根目录 src/{layouts,components,pages,styles,content}，无多余工作区
|
||
- 暂不引入：React/Vue 框架、tailwind（原生 CSS + tokens 足够且更快）、CMS 适配层
|
||
- 项目墙构建时 fetch 失败用仓内缓存 JSON 兜底（src/data/projects-fallback.json）
|
||
|
||
## 5. 技术决策
|
||
- 技术栈：Astro 5 + 原生 TS/CSS；包管理 pnpm
|
||
- 证据协议：evidence: runs（verify 由 spec_verify 真实执行）
|
||
- 本轮允许改动：仓库 src/、public/、package.json、pnpm-lock.yaml、astro.config.*、tsconfig.json、content/、infra/deploy/build.sh、.spec/
|
||
- 本轮不应触碰：infra/{gitea,artalk}/、~/docker_apps/ 运行实例、nginx、生产 Halo
|
||
- Git integration branch：`spec/2026-10-24_add-blog-skeleton`
|
||
|
||
### 5.1 验证策略
|
||
- 范围级别：package
|
||
- 变更对象：src/ 全部源码、content/ 样例集合、public/ 静态资产、构建配置、build.sh
|
||
- 快速检查：`pnpm astro build`（全包 verify 的基座命令）
|
||
- 集成检查：dist/ 路由产物断言（五页型 HTML 存在、字体分片计数、pagefind/rss/sitemap 产出）
|
||
- 全项目检查：staging 部署演练 + rollback-dryrun 仍绿；仅在 src 构建链/部署脚本/共享基础设施变更时升级范围重跑
|
||
- 升级触发：只有改动构建链（astro/字体/搜索集成）、build.sh 或暴露公网入口时，才升级验证范围并记录理由
|
||
|
||
## 6. 成功标准与验证方式
|
||
- [ ] `pnpm astro build` exit 0 且零框架 JS 依赖（仅原生脚本） -> verify: task_0001
|
||
- [ ] 五页型路由 HTML 全部生成于 dist/ -> verify: task_0006
|
||
- [ ] 字体分片自托管产出（woff2 切片 >50 个文件） -> verify: task_0003
|
||
- [ ] 极客层 P0 标记齐全（键盘脚本/帮助浮层/built-from/ClientRouter/项目墙区块） -> verify: task_0007
|
||
- [ ] Pagefind 索引 + rss.xml + sitemap 产出 -> verify: task_0008
|
||
- [ ] staging 目录更新 + 回滚干跑仍绿 -> verify: task_0010
|
||
|
||
## 7. 风险与约束
|
||
- 预分片字体包若含 latin-only 假冒 CJK 切片 → 构建后抽查切片数与体积 -> 验证步覆盖
|
||
- exifr 对样例占位图无 EXIF → loader 需容错空值 -> schema 可选字段
|
||
- View Transitions 三引擎兼容（caniuse 已核）→ 降级 CSS 直切，无破坏
|