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_CN/architecture.rst b/Documentation/source/zh_CN/architecture.rst
new file mode 100644
index 0000000..55d5b54
--- /dev/null
+++ b/Documentation/source/zh_CN/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、会话、评论存储和评论权限。
+   * - 数据层
+     - ``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_CN/contributing.rst b/Documentation/source/zh_CN/contributing.rst
new file mode 100644
index 0000000..cc0b39f
--- /dev/null
+++ b/Documentation/source/zh_CN/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_CN/frontend.rst b/Documentation/source/zh_CN/frontend.rst
new file mode 100644
index 0000000..4c58ed6
--- /dev/null
+++ b/Documentation/source/zh_CN/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``
+     - 文章详情、富文本、元数据、分享和评论。
+   * - ``/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_CN/getting-started.rst b/Documentation/source/zh_CN/getting-started.rst
new file mode 100644
index 0000000..88a6a87
--- /dev/null
+++ b/Documentation/source/zh_CN/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_CN/index.rst b/Documentation/source/zh_CN/index.rst
new file mode 100644
index 0000000..44f9f58
--- /dev/null
+++ b/Documentation/source/zh_CN/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_CN/introduction.rst b/Documentation/source/zh_CN/introduction.rst
new file mode 100644
index 0000000..1746b00
--- /dev/null
+++ b/Documentation/source/zh_CN/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_CN/operations.rst b/Documentation/source/zh_CN/operations.rst
new file mode 100644
index 0000000..ddacb09
--- /dev/null
+++ b/Documentation/source/zh_CN/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_CN/reference.rst b/Documentation/source/zh_CN/reference.rst
new file mode 100644
index 0000000..c295315
--- /dev/null
+++ b/Documentation/source/zh_CN/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 和会话能力的认证库。
+
+BlogPost
+   ``src/lib/payload-posts.ts`` 返回的前端规范化文章结构。