今日主題

Portfolio

為什麼想做

• 陸續將零散專案做整合
• 練習SDD框架
• 用的上

思考怎麼做

• SDD框架思考規格書
• 建立專案md文檔、開發日誌、部署前 Checklists
• 開發紀錄迭代

成果校驗

今日主軸：用 SDD 把「該做什麼、怎麼驗證、有沒有達到」講清楚

一、產品願景（Why / Outcome）

• 目標：用最少文字、最直觀 Demo，呈現「想法到成品」，可定時自動更新（新作品、成效數據）
• 關鍵結果（可量化）
  • 任何作品上線 ≤ 1 天即可被收錄顯示
  • 作品都含「 Demo / Repo」至少其一
  • 網站每日自動檢查更新（無變動不重建，有變動 ≤ 10 分鐘上線）

二、使用者與場景（For Whom / When）

• Persona

  • 瀏覽者：30–120 秒內判斷「從 0 到 1 能力」、掃描解題脈絡與技術框架
  • 建立者(我本人)：持續可看見進展、驗證節奏、維持創作動能的工具

• 關鍵場景

  • S1：用手機分享單一作品連結（秒開、秒看懂、可立即試）
  • S2：面試前 5 分鐘快速翻作品總覽（需排序、可按標籤篩）
  • S3：每日自動抓新作品或數據，觸發重建佈署（Zero-touch upkeep）

三、功能範圍（Scope）

• MVP（必做）
  • 作品清單：卡片式，包括標題、一句話價值、技術標籤、行動按鈕
  • 作品詳情頁：問題→解法→結果；含 Demo/Repo/GIF 動圖
  • pipeline：排程抓資料源→產生 JSON→重建
  • 後台資料來源：Single Source of Truth

*Next
* 搜尋 / 標籤交叉篩選
* 中/英語言

四、領域詞彙（Domain Glossary）

• Work / Project：成品屬性（Web / App / 自動化流程 / 娛樂工具等）
• Run：自動化的某次運行紀錄（成功/失敗、開始/結束時間）
• Metric：作品相關數據（例：啟動次數、API 回應成功率）
• Source：資料來源（GitHub、n8n、Supabase等）

五、資料模型（Single Source of Truth, SSOT）

• 使用單一 repository 下的 /data 目錄管理內容（人可讀＋機器可用）。
• 規格用 JSON Schema 驗證，頁面在 build 時以此為唯一來源

六、API 規格（可選）

• 若用靜態站（如Zeabur + SSG）可不需 API
• 若動態拉資料，OpenAPI 先行
  • 當前端頁面需要透過 API 即時抓資料，而不是讀固定檔案時，先定義 API 規格（OpenAPI）再動工，以確保資料結構一致、開發過程自動化、測試較容易

七、頁面與元件規格（UI Spec）

• 頁面

  • /：作品總覽（排序預設：sortWeight desc → updatedAt desc）
  • /p/[id]：作品詳情（固定區塊：問題 / 解法 / 結果）
  • /changelog：自動更新紀錄（來源：build 時間與變更摘要）

• 元件

  • ProjectCard：標題、one-liner、Tech chips、CTA（Demo / Repo / Video）
  • MetricBadge：顯示週使用、成功率（無數據 → 顯示「先看 Demo」）
  • AutoUpdateBanner：顯示上次更新時間（ISO → 本地友善格式）

七、Pipeline Spec

• 核心：每天 09:00（台北時間）跑一次收斂腳本 → 產生 /data/portfolio.json → 觸發重建 → 部署。

• 資料來源（可擇一或混用）

  • GitHub：讀取指定 repo 的 stars/最新 release（以 token 抓）
  • n8n / Supabase：讀近期 workflow/run 次數與成功率
  • 手動 YAML：新增作品 metadata

• 流程（Mermaid）

   flowchart TD
    CRON[每日 09:00] --> COLLECT[收斂腳本: fetch sources]
    COLLECT --> VALIDATE[以 JSON Schema 驗證]
    VALIDATE -->|pass| WRITE[/更新 data/portfolio.json/]
    VALIDATE -->|fail| ALERT[開 Issue or 發 Slack 通知]
    WRITE --> COMMIT[Git commit & push]
    COMMIT --> BUILD[CI 觸發 SSG 重建]
    BUILD --> DEPLOY[部署上線]

• 變更規則
  • 若收斂結果與上一次 portfolio.json 無差異 → 不重建
  • 僅允許 schema-valid 的變更進入主分支

九、驗收規格（Acceptance Criteria)

• 以 BDD 風格撰寫，測試可在 CI 中執行。
  • Behavior-Driven Development：以使用者的行為描述系統應該怎麼反應

* SDD 定義規格 → BDD 轉成行為場景 → TDD 驗證程式邏輯 

• AC-1：首頁載入與排序

Given 有3個作品且各自有 sortWeight
When 使用者開啟首頁
Then 作品應按 sortWeight 高→低顯示
And 首屏每張卡片至少含：標題、oneLiner、至少1個 CTA

• AC-2：詳情頁可操作且可視

Given 使用者開啟 /p/{id}
Then 頁面至少包含「問題 / 解法 / 結果」三段
And 若有 demo 連結，CTA 可點擊且 HTTP 200
And 若 evidence.gif 存在，於首屏顯示

• AC-3：每日自動更新成功

Given 到了每日 09:00 台北時間
When Pipeline 觸發
Then 若 sources 有變更 -> 10 分鐘內網站更新
Else 不進行部署

• AC-4：資料有效性

Given 有新的 portfolio.json
When 以 JSON Schema 驗證
Then 必須通過驗證方可合併

十、非功能性需求（NFR）

• 可維護性：新增作品 = 新增一筆 JSON/YAML，不需改程式
• 效能：首頁 LCP < 2.5s（桌機），行動裝置 < 3s
• 可用性：無資料/失敗率過高時，UI 顯示備用文案（空態）
• 可觀測性：CI 紀錄 build 次數與耗時；跑錯要有通知（Email）

十一、版本與治理（Governance）

• schema/portfolio.schema.json：任何破壞性變更 → major
• 資料檔 data/portfolio.json：每次更新 auto-tag changelog（日期＋摘要）

十二、CI/CD 規格（範例，偽 YAML）

name: portfolio-pipeline
on:
  schedule: [{ cron: "0 1 * * *" }] # 每日 09:00 台北（= UTC+8 -> 01:00 UTC）
  workflow_dispatch: {}
jobs:
  collect-and-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with: { node-version: 20 }
      - name: Collect sources
        run: node scripts/collect.mjs  # 產出 data/portfolio.json
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
          N8N_API_KEY: ${{ secrets.N8N_API_KEY }}
      - name: Validate schema
        run: node scripts/validate.mjs
      - name: Commit if changed
        run: |
          git config user.name "bot"
          git config user.email "bot@example.com"
          git add data/portfolio.json
          git diff --staged --quiet || git commit -m "chore: data update"
      - name: Build
        run: npm run build
      - name: Deploy
        run: npx vercel deploy --prod --token ${{ secrets.VERCEL_TOKEN }}

十三、內容撰寫規格（Copy Spec）

• 卡片 one-liner 公式：[誰] 用 [你的作品] 在 [情境] 可以 [達成的效果]（≤ 20 字）
• 詳情三段：Problem（<120 字） / Approach（<120 字） / Result（數據或 GIF）

十四、監測與成功指標（Analytics Spec）

• 事件：view_project, click_demo, click_repo, time_on_page
• 看板：每週自動輸出一張圖（Top-5 作品點擊 / Demo 轉換率）

十五、風險與對策

• 資料源掛點：允許使用「上一次成功結果」，並標註「資料時間」
• Demo 貼外站失效：定期 link-check；失效自動標「修復中」
• 內容增多難維護：以 sortWeight 控制首屏曝光，避免首頁過載

下一步

• 規格、過程、決策、日誌保存成 .md 之合理流程與文檔