From dbb5e791f0c228369605d126dd590962ebe1eddc Mon Sep 17 00:00:00 2001 From: Bertrand Yuan Date: Mon, 27 Apr 2026 20:52:54 +0800 Subject: docs: add comprehensive documentation for operations This commit introduces a complete set of documentation files covering various aspects of the project, including environment setup, quality checks, command references, and architecture. The documentation is structured to assist developers and contributors in understanding the project's configuration, workflow, and best practices. Additionally, translations for Simplified and Traditional Chinese have been added to ensure accessibility for a wider audience. This enhances the overall usability and maintainability of the project. Signed-off-by: Bertrand Yuan --- Documentation/source/zh_CN/architecture.rst | 50 ++++++++++++++++++ Documentation/source/zh_CN/contributing.rst | 38 ++++++++++++++ Documentation/source/zh_CN/frontend.rst | 49 ++++++++++++++++++ Documentation/source/zh_CN/getting-started.rst | 72 ++++++++++++++++++++++++++ Documentation/source/zh_CN/index.rst | 17 ++++++ Documentation/source/zh_CN/introduction.rst | 46 ++++++++++++++++ Documentation/source/zh_CN/operations.rst | 65 +++++++++++++++++++++++ Documentation/source/zh_CN/reference.rst | 57 ++++++++++++++++++++ 8 files changed, 394 insertions(+) create mode 100644 Documentation/source/zh_CN/architecture.rst create mode 100644 Documentation/source/zh_CN/contributing.rst create mode 100644 Documentation/source/zh_CN/frontend.rst create mode 100644 Documentation/source/zh_CN/getting-started.rst create mode 100644 Documentation/source/zh_CN/index.rst create mode 100644 Documentation/source/zh_CN/introduction.rst create mode 100644 Documentation/source/zh_CN/operations.rst create mode 100644 Documentation/source/zh_CN/reference.rst (limited to 'Documentation/source/zh_CN') 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 + + (): + +常用类型包括 ``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`` 返回的前端规范化文章结构。 -- cgit v1.2.3