diff --git a/docs/plans/2026-07-23-phase0-tech-validation.md b/docs/plans/2026-07-23-phase0-tech-validation.md new file mode 100644 index 0000000..14652cc --- /dev/null +++ b/docs/plans/2026-07-23-phase0-tech-validation.md @@ -0,0 +1,838 @@ +# Phase 0 技术验证 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 本地跑通「客户在 Sveltia CMS 改内容 → 提交到自建 Gitea → Gitea Action 自动构建 Astro → ossutil 同步到阿里云 OSS」的完整链路，验证设计文档（[../specs/2026-07-23-official-site-cms-design.md](../specs/2026-07-23-official-site-cms-design.md)）的技术可行性。 + +**Architecture:** Astro 5（SSG）生成纯静态站；Sveltia CMS（CDN SPA）作为客户可视化后台，经 Gitea OAuth 提交 Markdown 到仓库；本地 Docker Gitea + act_runner 提供 Git 后端 + CI；构建产物由 ossutil 推到阿里云 OSS。内容用 Astro Content Collections + Zod schema 强类型校验。 + +**Tech Stack:** Astro 5 · Sveltia CMS · Gitea（+Gitea Actions / act_runner）· ossutil · 阿里云 OSS · Vitest + +**前置条件:** 本机已装 Node.js 20+、Docker；后续接真实 OSS 时需阿里云账号 + AK/SK + 已建 bucket。 + +--- + +## Scope + +本计划**只覆盖 Phase 0 技术验证**（设计文档 §十二 Phase 0）。Phase 1 基座化、Phase 2 首客户上线、Phase 3 Payload 适配器各自后续单独出计划。 + +**验证成功标准（端到端）：** 在 `http://localhost:4321/admin/` 用 Sveltia 新增一条新闻 → 提交 → 本地 Gitea 收到 commit → Gitea Action 触发并构建成功 → `dist/` 生成新页面 → ossutil 脚本可把 `dist/` 同步到 OSS（凭据就绪时实推）。 + +--- + +## File Structure + +``` +official-site-base/ +├── package.json # 依赖：astro, vitest +├── astro.config.mjs # Astro 配置 +├── tsconfig.json +├── vitest.config.ts +├── src/ +│ ├── content.config.ts # Content Collections（news）+ schema 引用 +│ ├── content/ +│ │ ├── schemas.ts # Zod schema（可单独单测） +│ │ └── news/ +│ │ └── welcome.md # 示例新闻 +│ ├── layouts/BaseLayout.astro +│ ├── pages/ +│ │ ├── index.astro # 首页 +│ │ └── news/ +│ │ ├── index.astro # 新闻列表 +│ │ └── [slug].astro # 新闻详情 +│ └── styles/global.css # 设计 token（白标入口） +├── public/ +│ ├── admin/ +│ │ ├── index.html # Sveltia CMS 入口 +│ │ └── config.yml # Sveltia 配置（gitea backend） +│ └── favicon.svg +├── tests/content-schema.test.ts # Zod schema 单测 +├── scripts/deploy-oss.sh # ossutil 发布脚本 +├── .gitea/workflows/deploy.yml # Gitea Action +├── docker/gitea.docker-compose.yml # 本地 Gitea + runner +├── .env.example # OSS 凭据模板 +└── docs/{specs,plans}/... +``` + +**职责边界：** +- `src/content/schemas.ts` —— 纯 Zod schema，与 Astro 解耦，可单测 +- `src/content.config.ts` —— 把 schema 绑到 collection，定义 loader +- `public/admin/config.yml` —— Sveltia 字段配置，与 schema 字段保持一致（重复但必要：Sveltia 是 YAML、Astro 是 TS） +- `scripts/deploy-oss.sh` —— 独立发布脚本，本地和 CI 共用（DRY） + +--- + +## Task 1: 初始化 Astro 项目 + 工具链 + +**Files:** +- Create: `package.json`, `astro.config.mjs`, `tsconfig.json`, `vitest.config.ts` +- Create: `src/styles/global.css`, `public/favicon.svg`, `.env.example` + +- [ ] **Step 1: 初始化 Astro 项目（在 official-site-base 目录内）** + +```bash +# 已在 official-site-base 目录，初始化最小 Astro（不加模板） +npm init -y +npm install astro@latest +npm install -D vitest@latest +``` + +- [ ] **Step 2: 写 package.json scripts** + +把 `package.json` 的 `scripts` 改为： + +```json +{ + "name": "official-site-base", + "type": "module", + "version": "0.1.0", + "scripts": { + "dev": "astro dev", + "build": "astro build", + "preview": "astro preview", + "test": "vitest run" + } +} +``` + +- [ ] **Step 3: 写 astro.config.mjs** + +```js +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + site: 'https://example.com', +}); +``` + +- [ ] **Step 4: 写 tsconfig.json** + +```json +{ + "extends": "astro/tsconfigs/strict", + "include": [".astro/types.d.ts", "**/*"], + "exclude": ["dist"] +} +``` + +- [ ] **Step 5: 写 vitest.config.ts** + +```ts +import { defineConfig } from 'vitest/config'; + +export default defineConfig({ + test: { + include: ['tests/**/*.test.ts'], + }, +}); +``` + +- [ ] **Step 6: 写设计 token 入口 src/styles/global.css** + +```css +:root { + /* 白标入口：换客户时改这里 */ + --color-primary: #007aff; + --color-text: #1a1a1a; + --color-bg: #ffffff; + --font-sans: system-ui, -apple-system, 'PingFang SC', 'Microsoft YaHei', sans-serif; +} + +html { font-family: var(--font-sans); color: var(--color-text); background: var(--color-bg); } +body { margin: 0; max-width: 960px; margin-inline: auto; padding: 1.5rem; } +a { color: var(--color-primary); } +``` + +- [ ] **Step 7: 写 public/favicon.svg 与 .env.example** + +`public/favicon.svg`: +```xml +O +``` + +`.env.example`: +```bash +# 阿里云 OSS 发布凭据（复制为 .env 后填真值，.env 已被 .gitignore 排除） +OSS_ACCESS_KEY_ID= +OSS_ACCESS_KEY_SECRET= +OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com +OSS_BUCKET=official-site-base-demo +OSS_REGION=cn-hangzhou +# 本地 Gitea +GITEA_BASE_URL=http://localhost:3000 +``` + +- [ ] **Step 8: 验证 Astro 能起** + +Run: `npx astro --version && npm run dev`，浏览器开 `http://localhost:4321`，Ctrl+C 停止。 +Expected: 版本号输出（5.x）；dev server 起来无报错（此时还没有页面，404 正常）。 + +- [ ] **Step 9: Commit** + +```bash +git add -A +git commit -m "feat: 初始化 Astro 项目与工具链（vitest/设计token/env）" +``` + +--- + +## Task 2: news Content Collection + Zod schema（TDD） + +**Files:** +- Create: `src/content/schemas.ts`, `src/content.config.ts`, `src/content/news/welcome.md` +- Test: `tests/content-schema.test.ts` + +- [ ] **Step 1: 写失败测试 tests/content-schema.test.ts** + +```ts +import { describe, it, expect } from 'vitest'; +import { newsSchema } from '../src/content/schemas'; + +describe('newsSchema', () => { + it('accepts valid frontmatter and coerces date', () => { + const parsed = newsSchema.parse({ + title: '官网基座启动', + date: '2026-07-23', + category: '公告', + }); + expect(parsed.title).toBe('官网基座启动'); + expect(parsed.date).toEqual(new Date('2026-07-23')); + expect(parsed.category).toBe('公告'); + }); + + it('defaults category to 未分类', () => { + const parsed = newsSchema.parse({ title: '测试', date: '2026-07-23' }); + expect(parsed.category).toBe('未分类'); + }); + + it('rejects missing title', () => { + expect(() => newsSchema.parse({ date: '2026-07-23' })).toThrow(); + }); + + it('rejects missing date', () => { + expect(() => newsSchema.parse({ title: '测试' })).toThrow(); + }); +}); +``` + +- [ ] **Step 2: 运行测试，确认失败** + +Run: `npm test` +Expected: FAIL —— `Cannot find module '../src/content/schemas'`（文件还没建）。 + +- [ ] **Step 3: 写 schema src/content/schemas.ts** + +```ts +import { z } from 'astro:content'; + +export const newsSchema = z.object({ + title: z.string(), + date: z.coerce.date(), + category: z.string().default('未分类'), +}); +``` + +> `z` 直接从 `astro:content` 导出（Astro 内置 zod，无需单独装）。 + +- [ ] **Step 4: 写 collection 配置 src/content.config.ts** + +```ts +import { defineCollection } from 'astro:content'; +import { glob } from 'astro/loaders'; +import { newsSchema } from './content/schemas'; + +const news = defineCollection({ + loader: glob({ pattern: '**/*.md', base: './src/content/news' }), + schema: newsSchema, +}); + +export const collections = { news }; +``` + +- [ ] **Step 5: 写示例内容 src/content/news/welcome.md** + +```markdown +--- +title: 官网基座启动 +date: 2026-07-23 +category: 公告 +--- + +这是 Phase 0 技术验证的第一条新闻。内容编辑链路跑通后，客户可在 Sveltia CMS 自助新增。 +``` + +- [ ] **Step 6: 运行测试，确认通过** + +Run: `npm test` +Expected: PASS（4 个测试全过）。 + +- [ ] **Step 7: Commit** + +```bash +git add -A +git commit -m "feat: 新增 news 内容集合与 Zod schema（含单测）" +``` + +--- + +## Task 3: 首页 + 新闻列表/详情页面 + +**Files:** +- Create: `src/layouts/BaseLayout.astro`, `src/pages/index.astro`, `src/pages/news/index.astro`, `src/pages/news/[slug].astro` + +- [ ] **Step 1: 写 BaseLayout src/layouts/BaseLayout.astro** + +```astro +--- +import '../styles/global.css'; +interface Props { title: string; } +const { title } = Astro.props; +--- + + + + + + + {title} + + +
官网基座
+
+ + + +``` + +- [ ] **Step 2: 写首页 src/pages/index.astro** + +```astro +--- +import BaseLayout from '../layouts/BaseLayout.astro'; +import { getCollection } from 'astro:content'; + +const news = (await getCollection('news')).sort( + (a, b) => b.data.date.getTime() - a.data.date.getTime() +); +--- + +

官网基座

+

Phase 0 技术验证站点。

+
+

最新动态

+ +

查看全部 →

+
+ +``` + +- [ ] **Step 3: 写新闻列表 src/pages/news/index.astro** + +```astro +--- +import BaseLayout from '../../layouts/BaseLayout.astro'; +import { getCollection } from 'astro:content'; + +const news = (await getCollection('news')).sort( + (a, b) => b.data.date.getTime() - a.data.date.getTime() +); +--- + +

新闻动态

+ + +``` + +- [ ] **Step 4: 写新闻详情 src/pages/news/[slug].astro** + +```astro +--- +import BaseLayout from '../../layouts/BaseLayout.astro'; +import { getCollection, render } from 'astro:content'; + +export async function getStaticPaths() { + const news = await getCollection('news'); + return news.map((post) => ({ + params: { slug: post.id }, + props: { post }, + })); +} + +const { post } = Astro.props; +const { Content } = await render(post); +--- + +
+

{post.data.title}

+

{post.data.category} · {post.data.date.toLocaleDateString('zh-CN')}

+ +
+

← 返回列表

+ +``` + +- [ ] **Step 5: 构建并验证产物** + +Run: `npm run build` +Expected: `dist/index.html`、`dist/news/index.html`、`dist/news/welcome/index.html` 生成，无报错。 + +Run: `npm run preview`，浏览器开 `http://localhost:4321`，点进新闻详情。 +Expected: 首页列出到「官网基座启动」一条；详情页正文渲染。 + +- [ ] **Step 6: Commit** + +```bash +git add -A +git commit -m "feat: 首页与新闻列表/详情页面" +``` + +--- + +## Task 4: Sveltia CMS 接入（/admin） + +**Files:** +- Create: `public/admin/index.html`, `public/admin/config.yml` + +- [ ] **Step 1: 写 CMS 入口 public/admin/index.html** + +```html + + + + + + Sveltia CMS + + + + + + +``` + +> 国内生产环境可把 `sveltia-cms.js` 自托管到 OSS 或换国内 CDN（unpkg 国内可能慢），Phase 0 先用官方 CDN 验证。 + +- [ ] **Step 2: 写 Sveltia 配置 public/admin/config.yml** + +```yaml +# yaml-language-server: $schema=https://unpkg.com/@sveltia/cms/schema/sveltia-cms.json + +# 本地验证用本地 Gitea（Task 5 起的）；生产换真实 Gitea 地址 +backend: + name: gitea + repo: lzy/official-site-base + base_url: http://localhost:3000 + api_root: http://localhost:3000/api/v1 + +media_folder: /public/media +public_folder: /media + +collections: + - name: news + label: 新闻动态 + label_singular: 新闻 + folder: /src/content/news + create: true + slug: '{{slug}}' + fields: + - { label: 标题, name: title, widget: string } + - { label: 日期, name: date, widget: datetime, type: date } + - { label: 分类, name: category, widget: string, default: 未分类 } + - { label: 正文, name: body, widget: richtext } +``` + +> Sveltia 的 `folder` 路径要和 Astro `content.config.ts` 的 `base`（`./src/content/news`）一致；字段要和 `newsSchema` 一一对应（title/date/category）。 + +- [ ] **Step 3: 验证 CMS 界面能加载** + +Run: `npm run dev`，浏览器开 `http://localhost:4321/admin/`。 +Expected: 看到 Sveltia CMS 登录/界面（此时还没连 Gitea，点登录会报错或重定向失败——属正常，Task 6 接 Gitea 后通）。 + +- [ ] **Step 4: Commit** + +```bash +git add -A +git commit -m "feat: 接入 Sveltia CMS（/admin + gitea backend 配置）" +``` + +--- + +## Task 5: 本地 Gitea + act_runner（Docker） + +**Files:** +- Create: `docker/gitea.docker-compose.yml` + +- [ ] **Step 1: 写 docker-compose docker/gitea.docker-compose.yml** + +```yaml +services: + gitea: + image: gitea/gitea:1 + environment: + - USER_UID=1000 + - USER_GID=1000 + volumes: + - ./gitea-data:/data + ports: + - "3000:3000" # Web + - "2222:22" # SSH + restart: unless-stopped + + runner: + image: gitea/act_runner:latest + environment: + - GITEA_INSTANCE_URL=http://gitea:3000 + - GITEA_RUNNER_REGISTRATION_TOKEN=phase0-local-token + volumes: + - ./runner-data:/data + - /var/run/docker.sock:/var/run/docker.sock + depends_on: + - gitea + restart: unless-stopped +``` + +- [ ] **Step 2: 启动 Gitea + runner** + +```bash +cd docker +docker compose -f gitea.docker-compose.yml up -d +docker compose -f gitea.docker-compose.yml ps +``` +Expected: 两个容器 `Up`。 + +- [ ] **Step 3: 完成 Gitea 首次安装（Web 向导）** + +浏览器开 `http://localhost:3000`。 +- 数据库选 SQLite（默认） +- 站点 URL：`http://localhost:3000` +- 创建管理员账户：用户名 `lzy`，密码自设（记牢） +- 点「立即安装」 + +Expected: 安装完成，跳转登录页，能登入。 + +- [ ] **Step 4: 注册 runner 到 Gitea** + +在 Gitea Web：`http://localhost:3000/admin/actions/runners`，确认 `runner` 容器已注册并 `idle`（compose 里 token 写死为 `phase0-local-token`，runner 自动注册）。如未注册，到「Site Administration → Actions → Runners」用 `phase0-local-token` 手动添加。 + +Expected: runners 列表有一条 `idle` 的 runner。 + +- [ ] **Step 5: 把 official-site-base 推到本地 Gitea** + +```bash +# 在 official-site-base 目录 +git remote add local http://localhost:3000/lzy/official-site-base.git +# 先在 Gitea Web 「新建仓库」official-site-base（空仓库，不要勾 README） +git push -u local main +``` +Expected: 推送成功，Gitea 上能看到代码。 + +- [ ] **Step 6: Commit docker 配置** + +```bash +# 回 official-site-base 目录 +git add docker/gitea.docker-compose.yml +git commit -m "chore: 本地 Gitea + act_runner docker-compose" +``` + +> 注意：`docker/gitea-data/` 和 `docker/runner-data/` 不要提交（本地数据），后续加到 .gitignore。 + +- [ ] **Step 7: 补 .gitignore 排除本地数据** + +在 `.gitignore` 末尾追加： +``` +# 本地 Gitea/runner 数据 +docker/gitea-data/ +docker/runner-data/ +``` + +```bash +git add .gitignore +git commit -m "chore: 忽略本地 Gitea/runner 数据目录" +``` + +--- + +## Task 6: Gitea OAuth App + Sveltia 提交链路验证 + +**Files:** +- Modify: `public/admin/config.yml`（确认 base_url） + +- [ ] **Step 1: 在 Gitea 创建 OAuth2 应用** + +Gitea Web：头像 → Settings → Applications → **OAuth2 Applications** → 「Create Application」： +- Name: `Sveltia CMS` +- Redirect URI: `http://localhost:4321/admin/` +- 创建后记录 `Client ID` 和 `Client Secret` + +Expected: 拿到一对 Client ID / Secret。 + +- [ ] **Step 2: 在 Sveltia config 补 auth 配置** + +修改 `public/admin/config.yml` 的 backend 段（追加 `app_id` / `client_id`，Sveltia gitea backend 用 OAuth）： + +```yaml +backend: + name: gitea + repo: lzy/official-site-base + base_url: http://localhost:3000 + api_root: http://localhost:3000/api/v1 + # Gitea OAuth2 App（Step 1 创建） + app_id: <填 Client ID> +``` +> `client_secret` 不写进配置（Sveltia gitea backend 走 PKCE/标准 OAuth 流，仅用 client_id + redirect；如 Gitea 要求 secret，参考 Sveltia Backends 文档配 `auth_type`）。Phase 0 若 PKCE 流不通，降级用 `git-gateway` 或本地 token 方式，记录到 spec 风险项。 + +- [ ] **Step 3: 验证 Sveltia 登录 Gitea** + +Run: `npm run dev`，浏览器开 `http://localhost:4321/admin/`，点登录。 +Expected: 跳转到 Gitea 授权页 → 授权 → 回到 Sveltia 看到「新闻动态」集合，能看到 Task 2 的 welcome.md。 + +- [ ] **Step 4: 新增一条新闻并提交** + +在 Sveltia：进入「新闻动态」→「新增新闻」→ 填标题/日期/分类/正文 → 保存 → 「Publish」。 +Expected: 提交成功，本地 Gitea 仓库（`http://localhost:3000/lzy/official-site-base`）出现新 commit，`src/content/news/` 多一个 md 文件。 + +- [ ] **Step 5: 拉取并验证内容进入构建** + +```bash +git pull local main +ls src/content/news/ +npm run build +``` +Expected: 新文件出现；build 产物 `dist/news/<新slug>/index.html` 生成。 + +- [ ] **Step 6: Commit config 调整** + +```bash +git add public/admin/config.yml +git commit -m "feat: Sveltia 接 Gitea OAuth，跑通提交链路" +``` + +--- + +## Task 7: Gitea Action 自动构建 + +**Files:** +- Create: `.gitea/workflows/deploy.yml` + +- [ ] **Step 1: 写工作流 .gitea/workflows/deploy.yml** + +```yaml +name: build-and-deploy + +on: + push: + branches: [main] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install deps + run: npm ci + + - name: Build + run: npm run build + + - name: Upload dist artifact + uses: actions/upload-artifact@v4 + with: + name: dist + path: dist/ + + - name: Sync to OSS + env: + OSS_ACCESS_KEY_ID: ${{ secrets.OSS_ACCESS_KEY_ID }} + OSS_ACCESS_KEY_SECRET: ${{ secrets.OSS_ACCESS_KEY_SECRET }} + OSS_ENDPOINT: ${{ secrets.OSS_ENDPOINT }} + OSS_BUCKET: ${{ secrets.OSS_BUCKET }} + run: bash scripts/deploy-oss.sh +``` + +> Gitea Actions 兼容 GitHub Actions 语法；`secrets` 在 Gitea 仓库 Settings → Actions → Secrets 配。OSS 同步在 Task 8 写脚本；本地验证时若未配 OSS secrets，该 step 会跳过（脚本内判空）。 + +- [ ] **Step 2: 推送触发 Action** + +```bash +git add .gitea/workflows/deploy.yml +git commit -m "ci: Gitea Action 构建并发布到 OSS" +git push local main +``` + +- [ ] **Step 3: 验证 Action 执行** + +Gitea Web：`http://localhost:3000/lzy/official-site-base/actions`。 +Expected: 看到一次 push 触发的运行，`build` 作业绿色，artifact `dist` 上传成功；`Sync to OSS` 步骤因无凭据显示跳过/失败（Task 8 配齐后转绿）。 + +--- + +## Task 8: ossutil 发布脚本 + +**Files:** +- Create: `scripts/deploy-oss.sh` + +- [ ] **Step 1: 安装 ossutil（如未装）** + +```bash +# 参考 https://help.aliyun.com/document_detail/120075.html +# macOS/Linux: +curl -o /usr/local/bin/ossutil https://gosspublic.alicdn.com/ossutil/install.sh && bash /usr/local/bin/ossutil +ossutil version +``` +> Windows 下载 `ossutil64.exe` 放进 PATH。Phase 0 本地不强求装；CI 环境在 workflow 里装。 + +- [ ] **Step 2: 写脚本 scripts/deploy-oss.sh** + +```bash +#!/usr/bin/env bash +set -euo pipefail + +# 判空：没配凭据时跳过（Phase 0 本地/未配 OSS 时不阻塞） +if [ -z "${OSS_ACCESS_KEY_ID:-}" ] || [ -z "${OSS_BUCKET:-}" ]; then + echo "[deploy-oss] 未配置 OSS 凭据，跳过同步。" + exit 0 +fi + +: "${OSS_ACCESS_KEY_SECRET:?需 OSS_ACCESS_KEY_SECRET}" +: "${OSS_ENDPOINT:?需 OSS_ENDPOINT}" +: "${OSS_BUCKET:?需 OSS_BUCKET}" + +DIST_DIR="${1:-dist}" +[ -d "$DIST_DIR" ] || { echo "[deploy-oss] $DIST_DIR 不存在，请先 build"; exit 1; } + +echo "[deploy-oss] 同步 $DIST_DIR → oss://$OSS_BUCKET/" +ossutil sync "$DIST_DIR" "oss://$OSS_BUCKET/" \ + -i "$OSS_ACCESS_KEY_ID" \ + -k "$OSS_ACCESS_KEY_SECRET" \ + -e "$OSS_ENDPOINT" \ + --force --delete + +echo "[deploy-oss] 刷新 CDN（如配了 CDN_DOMAIN）" +if [ -n "${CDN_DOMAIN:-}" ]; then + ossutil cdn refresh --dirs "https://${CDN_DOMAIN}/" \ + -i "$OSS_ACCESS_KEY_ID" -k "$OSS_ACCESS_KEY_SECRET" -e "$OSS_ENDPOINT" || true +fi + +echo "[deploy-oss] 完成" +``` + +- [ ] **Step 3: 本地空跑验证（无凭据应跳过）** + +```bash +chmod +x scripts/deploy-oss.sh +./scripts/deploy-oss.sh +``` +Expected: 输出 `[deploy-oss] 未配置 OSS 凭据，跳过同步。`，退出码 0。 + +- [ ] **Step 4: 本地真实推送验证（需 OSS 凭据）** + +在阿里云控制台建 bucket（如 `official-site-base-demo`，公共读），拿 AK/SK： +```bash +cp .env.example .env +# 编辑 .env 填真值 +set -a; source .env; set +a # bash 加载环境变量 +npm run build +./scripts/deploy-oss.sh +``` +Expected: 输出同步文件列表；浏览器开 `https://official-site-base-demo.oss-cn-hangzhou.aliyuncs.com/index.html` 能看到首页。 + +- [ ] **Step 5: 配 Gitea Secrets 让 CI 同步** + +Gitea Web：仓库 Settings → Actions → Secrets，新增： +- `OSS_ACCESS_KEY_ID`、`OSS_ACCESS_KEY_SECRET`、`OSS_ENDPOINT`、`OSS_BUCKET` + +再 push 一次： +```bash +git add scripts/deploy-oss.sh +git commit -m "feat: ossutil 发布脚本（本地与 CI 共用）" +git push local main +``` +Expected: CI 的 `Sync to OSS` 步骤变绿，OSS 内容更新。 + +--- + +## Task 9: 端到端验证 + README 更新 + +**Files:** +- Modify: `README.md` + +- [ ] **Step 1: 端到端验证清单** + +按下列顺序操作并逐条勾选： +- [ ] `npm run dev`，开 `http://localhost:4321/admin/`，登录 Gitea +- [ ] Sveltia 新增一条新闻 → Publish +- [ ] 本地 Gitea 仓库出现新 commit +- [ ] `git pull local main`，本地 `src/content/news/` 出现新 md +- [ ] push 后 Gitea Action 触发并构建成功 +- [ ] OSS 同步成功（如已配凭据） +- [ ] `npm run build` + preview，首页与详情页展示新内容 + +- [ ] **Step 2: 更新 README.md 状态段** + +把 README 的「状态」段从： +``` +📋 设计已确认，待出实施计划（Phase 0 技术验证）。 +``` +改为： +``` +✅ Phase 0 技术验证已跑通：Sveltia CMS → Gitea → Action → OSS 全链路。 + +## 本地开发 +npm install +npm run dev # 站点 http://localhost:4321，CMS http://localhost:4321/admin/ +docker compose -f docker/gitea.docker-compose.yml up -d # 起 Gitea + +## 发布 +npm run build +./scripts/deploy-oss.sh # 需配 .env 的 OSS 凭据 +``` + +- [ ] **Step 3: 最终提交** + +```bash +git add README.md +git commit -m "docs: Phase 0 验证完成，更新 README 与本地开发说明" +git push local main +``` + +--- + +## Self-Review + +**1. Spec 覆盖检查**（对照 spec §五 内容模型 / §四架构 / §九部署）： +- ✅ news 集合 + Zod schema（Task 2）—— 代表 Content Collections 机制，其余 7 个集合在 Phase 1 基座化时按同模式补 +- ✅ Sveltia CMS /admin 可视化编辑（Task 4） +- ✅ 自建 Gitea + Actions（Task 5/7） +- ✅ 阿里云 OSS 发布（Task 8） +- ✅ 端到端链路验证（Task 9） +- ⏭ 留待后续计划：jobs/downloads/messages 集合、表单微服务、白标换 token 脚本、CMS 适配器接口（Phase 1-3） + +**2. 占位符扫描：** Task 6 Step 2 的 `<填 Client ID>` 是执行时填入的真实值（来自 Step 1 创建的 App），非 TODO 占位符；其余步骤代码完整。✅ + +**3. 类型/命名一致性：** +- `newsSchema` 字段（title/date/category）在 Task 2 schema、Task 4 config.yml、Task 3 页面三处一致 ✅ +- collection 名 `news` 在 content.config.ts、config.yml、页面 getCollection('news') 一致 ✅ +- OSS 环境变量名（OSS_ACCESS_KEY_ID 等）在 .env.example、deploy-oss.sh、deploy.yml secrets 三处一致 ✅ +- Gitea 仓库路径 `lzy/official-site-base` 在 config.yml、push 命令一致 ✅ + +**已知风险（执行时留意，已写入 spec §十一）：** +- Gitea OAuth PKCE 流是否开箱通（Task 6 Step 2 注明了降级方案） +- `act_runner` 注册 token（compose 写死 `phase0-local-token`，仅本地） +- unpkg CDN 国内访问速度（生产换自托管）