official-site-base/docs/plans/2026-07-23-phase0-tech-validation.md

# 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
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#007aff"/><text x="16" y="22" font-size="18" text-anchor="middle" fill="#fff" font-family="sans-serif">O</text></svg>
```

`.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;
---
<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" href="/favicon.svg" />
    <title>{title}</title>
  </head>
  <body>
    <header><a href="/" style="font-weight:700;font-size:1.25rem;">官网基座</a></header>
    <main><slot /></main>
    <footer style="margin-top:3rem;font-size:.85rem;color:#888;">© 官网基座</footer>
  </body>
</html>
```

- [ ] **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()
);
---
<BaseLayout title="官网基座 · 首页">
  <h1>官网基座</h1>
  <p>Phase 0 技术验证站点。</p>
  <section>
    <h2>最新动态</h2>
    <ul>
      {news.map((post) => (
        <li><a href={`/news/${post.id}/`}>{post.data.title}</a> <small>{post.data.date.toLocaleDateString('zh-CN')}</small></li>
      ))}
    </ul>
    <p><a href="/news/">查看全部 →</a></p>
  </section>
</BaseLayout>
```

- [ ] **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()
);
---
<BaseLayout title="新闻动态">
  <h1>新闻动态</h1>
  <ul>
    {news.map((post) => (
      <li>
        <a href={`/news/${post.id}/`}>{post.data.title}</a>
        <small> · {post.data.category} · {post.data.date.toLocaleDateString('zh-CN')}</small>
      </li>
    ))}
  </ul>
</BaseLayout>
```

- [ ] **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);
---
<BaseLayout title={post.data.title}>
  <article>
    <h1>{post.data.title}</h1>
    <p><small>{post.data.category} · {post.data.date.toLocaleDateString('zh-CN')}</small></p>
    <Content />
  </article>
  <p><a href="/news/">← 返回列表</a></p>
</BaseLayout>
```

- [ ] **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
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="robots" content="noindex" />
    <title>Sveltia CMS</title>
  </head>
  <body>
    <!-- 注意：不要加 type="module"，不要加 CSS link（Sveltia 自带样式） -->
    <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
  </body>
</html>
```

> 国内生产环境可把 `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 国内访问速度（生产换自托管）

---

## 执行记录（2026-07-23 实施偏差与现状）

代码侧 Task 1-4、7、8 + Task 5 文件部分已完成（`feat/phase0-tech-validation` 分支，7 commit）。

**实际依赖版本（偏离计划 `@latest`）：**

| 包 | 计划 | 实际 | 原因 |
|----|------|------|------|
| astro | latest(7.1) | **5.18.2** | latest 要 node≥22.12，本机 node 22.11 被拒启动 |
| vitest | latest(4) | **3.2.7** | latest(4) 依赖 rolldown，Windows native binding 装不上 |
| zod | latest(4) | **3.25.76** | astro 5 内置 zod 3，zod 4 与 astro:content 不兼容 |

**其他调整：**
- Task 2 schema 改用独立 `zod` 包（`import { z } from 'zod'`）而非 `astro:content`，让 vitest 能直接测（`astro:content` 是虚拟模块）；版本与 astro 内置 dedupe 为同一份 3.25.76。
- Sveltia CMS backends 已查实：原生支持 GitHub / GitLab / **Gitea**，**不支持 Gitee / Bitbucket**（故选自建 Gitea，见 spec §三）。

**验证已过：** schema 单测 4 个全过；`astro build` 出 3 页；`deploy-oss.sh` 空跑跳过退出 0。

**阻塞（待用户决策）：** 本机无 Docker，Task 5（起 Gitea）/ 6（OAuth）/ 9（端到端）无法本地跑通。Gitea 部署方式三选一：① 本地装 Docker Desktop ② 本地 Gitea 二进制 ③ 上服务器（ops 机或新轻量云）。