Merge pull request #21 from bertyuan/Documentationv1.2

docs: add comprehensive documentation for operations

8 files changed, 394 insertions, 0 deletions

diff --git a/Documentation/source/zh_TW/architecture.rst b/Documentation/source/zh_TW/architecture.rst
new file mode 100644
index 0000000..7c8da41
--- /dev/null
+++ b/Documentation/source/zh_TW/architecture.rst
@@ -0,0 +1,50 @@
+架構
+====
+
+分層視圖
+--------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 34 44
+
+   * - 層
+     - 主要檔案
+     - 職責
+   * - 展示層
+     - ``src/app/(main)``、``src/components``
+     - 呈現公開頁面、路由處理器、共用 UI、富文字和版面。
+   * - 內容存取層
+     - ``src/lib/payload-posts.ts``
+     - 查詢 Payload，並把 CMS 文件正規化為前端可用的資料結構。
+   * - CMS 後台
+     - ``payload.config.ts``、``src/payload``
+     - 定義內容集合並提供後台管理體驗。
+   * - 認證與留言
+     - ``src/server/auth``、``src/server/comments``
+     - 處理 OAuth、Session、留言儲存與留言權限。
+   * - 資料層
+     - ``src/server/db``、``src/migrations``
+     - 管理 Drizzle schema、資料庫連線與應用遷移。
+
+文章讀取流程
+------------
+
+1. ``/posts/[slug]`` 頁面接收文章 slug。
+2. Server Component 呼叫 ``getPostBySlug``。
+3. ``src/lib/payload-posts.ts`` 取得 Payload client 並查詢 ``published`` 狀態的文章。
+4. 原始 Payload 文件被轉換為 ``BlogPost``。
+5. 頁面呈現富文字，並掛載分享、留言等互動。
+
+資料邊界
+--------
+
+Payload 負責編輯內容與媒體中繼資料；應用層負責認證、留言、路由行為、UI 狀態與整合邏輯。新增功能前應先判斷資料歸屬：編輯內容放入 Payload collection；帳號、互動、審核與營運記錄放入 Drizzle schema。
+
+已知風險
+--------
+
+* 正式環境不應使用 Payload secret 預設值。
+* RSS 路徑應統一為 ``/rss.xml``。
+* 標籤統計與搜尋索引目前依賴批次讀取，內容規模變大後應引入快取或資料庫側聚合。
+* 留言角色策略需要更明確的服務端規則與測試覆蓋。
diff --git a/Documentation/source/zh_TW/contributing.rst b/Documentation/source/zh_TW/contributing.rst
new file mode 100644
index 0000000..8b12920
--- /dev/null
+++ b/Documentation/source/zh_TW/contributing.rst
@@ -0,0 +1,38 @@
+貢獻指南
+========
+
+工作流程
+--------
+
+1. 先判斷變更屬於哪個子系統。
+2. 閱讀相鄰實作和測試。
+3. 確認變更是否影響執行期行為、schema、UI、文件或維運流程。
+4. 保持 patch 聚焦，不做無關重構。
+
+提交訊息
+--------
+
+推薦格式：
+
+.. code-block:: text
+
+   <type>(<scope>): <short summary>
+
+常用類型包括 ``build``、``ci``、``docs``、``feat``、``fix``、``perf``、``refactor`` 和 ``test``。摘要使用祈使句、現在式，不以句號結尾。
+
+程式碼完整性
+------------
+
+* 發布版本時優先使用簽名 commit 和簽名 tag。
+* 不提交密鑰、本機資料庫狀態或建置產物。
+* 依賴變更應和原始碼變更一樣認真審查。
+* 非平凡變更應在分支上開發，並通過測試和文件建置。
+
+提交前檢查
+----------
+
+.. code-block:: bash
+
+   pnpm lint
+   pnpm test
+   make -C Documentation html
diff --git a/Documentation/source/zh_TW/frontend.rst b/Documentation/source/zh_TW/frontend.rst
new file mode 100644
index 0000000..b13a747
--- /dev/null
+++ b/Documentation/source/zh_TW/frontend.rst
@@ -0,0 +1,49 @@
+前端
+====
+
+頁面職責
+--------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 34 44
+
+   * - 路由
+     - 主要檔案
+     - 職責
+   * - ``/``
+     - ``src/app/(main)/(home)/page.tsx``
+     - 首頁，包含 Hero、最新文章和 Newsletter CTA。
+   * - ``/posts``
+     - ``src/app/(main)/(home)/posts/page.tsx``
+     - 已發布文章的分頁列表。
+   * - ``/posts/[slug]``
+     - ``src/app/(main)/(home)/posts/[slug]/page.tsx``
+     - 文章詳情、富文字、metadata、分享和留言。
+   * - ``/tags``
+     - ``src/app/(main)/(home)/tags/page.tsx``
+     - 標籤索引與文章數量。
+   * - ``/tags/[tag]``
+     - ``src/app/(main)/(home)/tags/[...slug]/page.tsx``
+     - 按標籤篩選的文章列表。
+   * - ``/login``
+     - ``src/app/(main)/(auth)/login/page.tsx``
+     - OAuth 登入入口。
+
+UI 原則
+-------
+
+* 閱讀優先：排版、行寬和對比度應服務長文閱讀。
+* 導航輕量：文章、標籤、搜尋、主題切換和帳號入口應容易找到。
+* 視覺一致：延續虛線邊框、角標和克制動效。
+* 跨端一致：行動端和桌面端保持相同資訊層級。
+
+元件約定
+--------
+
+新增元件前先檢查 ``src/components/ui`` 和現有頁面元件。共用元件應接收正規化 props，資料取得應放在 Server Component 或 ``src/lib`` helper 中。圖示按鈕必須有明確的可存取名稱。
+
+可存取性
+--------
+
+自訂控制項要保留鍵盤焦點；圖示按鈕和連結需要可讀名稱；淺色和深色主題都要保持足夠對比度；表單必須覆蓋空、載入、成功和錯誤狀態。
diff --git a/Documentation/source/zh_TW/getting-started.rst b/Documentation/source/zh_TW/getting-started.rst
new file mode 100644
index 0000000..5ab7907
--- /dev/null
+++ b/Documentation/source/zh_TW/getting-started.rst
@@ -0,0 +1,72 @@
+快速開始
+========
+
+本頁說明本機開發的基本流程：安裝依賴、準備環境變數、啟動資料庫、執行應用與建置文件。
+
+準備工具
+--------
+
+需要安裝：
+
+* Node.js，版本需符合 Next.js 15；
+* pnpm 10.x；
+* Docker 或 Podman，用於本機 PostgreSQL；
+* Git；
+* 可選：Sphinx，用於本機建置文件。
+
+環境變數
+--------
+
+複製範例檔：
+
+.. code-block:: bash
+
+   cp .env.example .env
+
+環境變數由 ``src/env.js`` 透過 ``@t3-oss/env-nextjs`` 和 ``zod`` 驗證。只做本機 UI 或文件除錯時，可以暫時使用 ``SKIP_ENV_VALIDATION=1``，但正式環境不應依賴它。
+
+資料庫
+------
+
+啟動本機 PostgreSQL：
+
+.. code-block:: bash
+
+   ./start-database.sh
+
+資料庫可用後，按需要執行：
+
+.. code-block:: bash
+
+   pnpm payload:migrate
+   pnpm db:push
+
+執行專案
+--------
+
+.. code-block:: bash
+
+   pnpm install
+   pnpm dev
+
+公開站台預設位於 ``http://localhost:3000``，Payload 後台位於 ``/admin``。
+
+常用檢查
+--------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 50
+
+   * - 命令
+     - 作用
+   * - ``pnpm lint``
+     - 驗證內容連結並執行 Biome lint。
+   * - ``pnpm check``
+     - 執行 Biome 檢查。
+   * - ``pnpm test``
+     - 執行 Vitest 測試。
+   * - ``pnpm build``
+     - 建置 Next.js 應用並產生網站地圖。
+   * - ``make -C Documentation html``
+     - 建置 Sphinx 文件。
diff --git a/Documentation/source/zh_TW/index.rst b/Documentation/source/zh_TW/index.rst
new file mode 100644
index 0000000..1dc6fb7
--- /dev/null
+++ b/Documentation/source/zh_TW/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+Next Blog 文件（繁體中文）
+=============================
+
+這是 Next Blog 文件的繁體中文版本。本文面向維護者、貢獻者與部署人員，說明專案的產品邊界、架構設計、前端約定、維運流程與貢獻規則。
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   getting-started
+   architecture
+   frontend
+   operations
+   contributing
+   reference
diff --git a/Documentation/source/zh_TW/introduction.rst b/Documentation/source/zh_TW/introduction.rst
new file mode 100644
index 0000000..8ca15d4
--- /dev/null
+++ b/Documentation/source/zh_TW/introduction.rst
@@ -0,0 +1,46 @@
+專案介紹
+========
+
+Next Blog 是一個以閱讀體驗為核心的全端部落格平台。它使用 Next.js App Router 建置公開站台，使用 Payload CMS 管理內容，並透過 PostgreSQL、Drizzle ORM、better-auth 與 Fuma Comments 提供認證、留言與應用資料能力。
+
+產品範圍
+--------
+
+目前專案聚焦於以下能力：
+
+* 透過 Payload CMS 建立、編輯、發布文章；
+* 呈現首頁、文章列表、文章詳情、標籤頁與個人頁面；
+* 透過 Google 與 GitHub OAuth 登入；
+* 為登入使用者提供留言功能；
+* 輸出搜尋索引、RSS、網站地圖、JSON-LD 與 Open Graph 圖片；
+* 提供 Newsletter 表單與 React Email 範本。
+
+這個專案不是通用社群 CMS，而是一個受控的個人發布系統：公開側重閱讀，後台側重內容管理。
+
+核心角色
+--------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 34 36
+
+   * - 角色
+     - 目標
+     - 主要入口
+   * - 訪客
+     - 瀏覽和閱讀內容。
+     - ``/``、``/posts``、``/posts/[slug]``、``/tags``
+   * - 回訪讀者
+     - 透過標籤篩選內容並使用訂閱入口。
+     - ``/tags/[tag]``、``/rss.xml``
+   * - 登入使用者
+     - 發表留言與使用帳號相關操作。
+     - ``/login``、``/posts/[slug]``
+   * - 內容管理員
+     - 維護、排程與發布內容。
+     - ``/admin``
+
+文件定位
+--------
+
+``Documentation/source`` 是本專案正式的 Sphinx 文件來源目錄。``docs/`` 中的 Markdown 檔案可以作為調研或草稿材料，但穩定的工程文件應整理為 reStructuredText 後進入本目錄。
diff --git a/Documentation/source/zh_TW/operations.rst b/Documentation/source/zh_TW/operations.rst
new file mode 100644
index 0000000..a513a10
--- /dev/null
+++ b/Documentation/source/zh_TW/operations.rst
@@ -0,0 +1,65 @@
+維運
+====
+
+環境設定
+--------
+
+關鍵環境變數在 ``src/env.js`` 中驗證：
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 44
+
+   * - 變數
+     - 用途
+   * - ``DATABASE_URL``
+     - PostgreSQL 連線字串。
+   * - ``RESEND_API_KEY``
+     - Resend API key。
+   * - ``RESEND_AUDIENCE_ID``
+     - Resend audience ID。
+   * - ``EMAIL_FROM``
+     - 寄件信箱。
+   * - ``BETTER_AUTH_SECRET``
+     - better-auth secret，正式環境必填。
+   * - ``GOOGLE_CLIENT_ID`` / ``GOOGLE_CLIENT_SECRET``
+     - Google OAuth 憑證。
+   * - ``GITHUB_CLIENT_ID`` / ``GITHUB_CLIENT_SECRET``
+     - GitHub OAuth 憑證。
+
+資料庫流程
+----------
+
+Payload collection 變更：
+
+.. code-block:: bash
+
+   pnpm payload:migrate:create
+   pnpm payload:migrate
+   pnpm payload:generate
+
+應用 schema 變更：
+
+.. code-block:: bash
+
+   pnpm db:generate
+   pnpm db:migrate
+
+品質檢查
+--------
+
+.. code-block:: bash
+
+   pnpm lint
+   pnpm check
+   pnpm test
+   pnpm build
+
+文件建置
+--------
+
+.. code-block:: bash
+
+   make -C Documentation html
+
+產生的 ``Documentation/build`` 不應提交。
diff --git a/Documentation/source/zh_TW/reference.rst b/Documentation/source/zh_TW/reference.rst
new file mode 100644
index 0000000..4da4c12
--- /dev/null
+++ b/Documentation/source/zh_TW/reference.rst
@@ -0,0 +1,57 @@
+參考
+====
+
+常用命令
+--------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 26 50
+
+   * - 命令
+     - 說明
+   * - ``pnpm dev``
+     - 啟動開發伺服器。
+   * - ``pnpm build``
+     - 建置正式應用。
+   * - ``pnpm lint``
+     - 執行內容連結驗證和 Biome lint。
+   * - ``pnpm test``
+     - 執行測試。
+   * - ``pnpm db:migrate``
+     - 套用 Drizzle 遷移。
+   * - ``pnpm payload:generate``
+     - 產生 Payload TypeScript 型別。
+
+路由
+----
+
+.. code-block:: text
+
+   /
+   /posts
+   /posts/[slug]
+   /tags
+   /tags/[tag]
+   /about
+   /login
+   /admin
+   /api/auth/[...all]
+   /api/comments/[...comment]
+   /api/search
+   /rss.xml
+
+術語
+----
+
+Payload
+   管理文章、使用者、媒體和後台介面的 CMS。
+
+Drizzle
+   管理應用自有資料庫表的 TypeScript ORM。
+
+better-auth
+   提供 OAuth 和 Session 能力的認證庫。
+
+BlogPost
+   ``src/lib/payload-posts.ts`` 回傳的前端正規化文章結構。