Convert submodule to folder

2025-12-29 14:05:37 +08:00
parent 5f1ecfc224
commit 5e7430200a
30 changed files with 1716 additions and 1 deletions
--- a/1
+++ b/1
--- a/开发文档/.github/workflows/sync_from_coding.yml
+++ b/开发文档/.github/workflows/sync_from_coding.yml
@@ -0,0 +1,36 @@
+name: Sync from Coding
+
+on:
+  schedule:
+    - cron: '0 */2 * * *'   # 每2小时执行一次
+  workflow_dispatch:        # 允许手动触发
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # 确保此行存在，赋予工作流写入仓库内容的权限，这是解决 403 权限问题的基础
+    steps:
+      - name: 检出 GitHub 仓库
+        uses: actions/checkout@v4
+        with:
+          ref: develop # 明确检出 develop 分支，确保在正确的分支上操作
+
+      - name: 配置 Git 用户并合并 Coding 代码到 GitHub
+        run: |
+          # 配置 Git 用户信息
+          git config user.name "zhiqun@qq.com"
+          git config user.email "zhiqun@qq.com"
+
+          # 添加 Coding 仓库为一个新的远程源
+          git remote add coding-origin https://${{ secrets.CODING_USERNAME }}:${{ secrets.CODING_TOKEN }}@e.coding.net/g-xtcy5189/cunkebao/cunkebao_v3.git
+          
+          # 从 Coding 远程仓库获取 develop 分支的最新信息
+          git fetch coding-origin develop
+
+          # 合并 Coding 的 develop 分支到本地的 develop 分支
+          # --allow-unrelated-histories 允许合并两个没有共同历史的分支
+          git merge --no-ff --allow-unrelated-histories coding-origin/develop
+
+          # 将合并后的本地 develop 分支推送到 GitHub 的 develop 分支
+          git push origin develop 
--- a/开发文档/0、Mycontent-book
+++ b/开发文档/0、Mycontent-book
@@ -0,0 +1,47 @@
+# Mycontent-book 项目总览
+
+**我是卡若。**
+
+做这个项目，逻辑很简单：**把书卖出去，把私域做起来，把钱分下去。**
+
+这就不是一个普通的博客网站，这是一个**内容变现系统**。所有的技术架构，都要围绕着“阅读体验”、“流量承接”和“变现转化”来做。
+
+别整那些虚头巴脑的概念，咱们直接看这个盘子怎么搭。
+
+## 1. 核心逻辑
+
+这个项目的生意逻辑就是三层：
+1.  **流量层（前端）**：让用户看着爽，像刷抖音、看公众号一样流畅。必须移动端优先，模拟 iOS 的原生质感。
+2.  **内容层（数据）**：`book/` 目录下的 Markdown 文件就是我们的资产。改个字，推送到 GitHub，网站立马更新。
+3.  **变现层（后端/接口）**：谁看了？谁买了？谁推荐的？这些数据要跑通。
+
+## 2. 为什么这么架构？
+
+我选 Next.js，不是因为流行，是因为它**省事**。
+- **SSR（服务端渲染）**：SEO 友好，百度谷歌能搜到，自带流量。
+- **API Routes**：不用单独起个 Java 或 Python 服务，省服务器钱。
+- **Vercel/宝塔部署**：自动化流水线，我只管写文章，代码自动跑。
+
+## 3. 目录导航（别迷路）
+
+- **[1、需求](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/1、需求/业务需求.md)**：我们要干啥，成本多少，技术要求。
+- **[2、架构](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/2、架构/系统架构.md)**：整体怎么搭，前后端怎么分。
+    - **[技术选型与全景图](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/2、架构/技术选型与全景图.md)**：详细的技术栈和架构流程图。
+    - **[前后端架构分离策略](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/2、架构/前后端架构分离策略.md)**：开发协作规范。
+- **[3、前端](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/3、前端/前端架构.md)**：脸面工程，交互细节。
+- **[4、后端](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/4、后端/后端架构.md)**：数据处理，脏活累活。
+- **[5、接口](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/5、接口/API接口.md)**：前后端怎么说话。
+- **[6、数据库](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/6、数据库/数据库设计.md)**：数据存哪，怎么存。
+- **[7、测试](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/7、测试/测试策略.md)**：怎么保证不出 Bug。
+- **[8、部署](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/8、部署/本项目部署总览.md)**：怎么上线，怎么自动化。
+- **[9、手册](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/9、手册/写作与结构维护手册.md)**：怎么写书，怎么维护。
+
+## 4. 这里的规矩
+
+- **行动至上**：文档是用来指导干活的，不是写来看的。
+- **数据说话**：所有优化要有数据支撑，加载快了多少？转化高了多少？
+- **保持简单**：能用现成的库就别自己造轮子。
+
+---
+**复盘：**
+目前项目处于“文件数据库”阶段，适合我这种单人高频写作。等流量上来了，用户系统一接，立马切 MongoDB。这一步步来，别贪多。
--- a/开发文档/10、项目管理/项目落地推进表.md
+++ b/开发文档/10、项目管理/项目落地推进表.md
@@ -0,0 +1,126 @@
+# 项目落地推进表
+
+---
+
+## 一、项目总览
+
+- **项目名称**：一场 SOUL 的创业实验场  
+- **核心目标**：  
+  构建一个集内容阅读、私域引流、知识变现于一体的 H5 应用，验证「内容 + 私域 + 分销」的商业闭环  
+- **当前阶段**：5.4 分销裂变  
+- **负责人**：卡若 & 智能助手  
+- **启动时间**：2025-12-28  
+
+---
+
+## 二、关键阶段与里程碑
+
+### 第一阶段：基础设施搭建（已完成）
+
+- [x] 1.1 开发环境配置（Next.js 14 + Tailwind）
+- [x] 1.2 核心 UI 框架搭建（Shadcn/ui + iOS 风格适配）
+- [x] 1.3 Markdown 解析引擎实现
+- [x] 1.4 路由与导航系统
+
+---
+
+### 第二阶段：核心阅读体验（已完成）
+
+- [x] 2.1 首页 / 书架页开发
+- [x] 2.2 沉浸式阅读器开发（字号 / 背景 / 进度记忆）
+- [x] 2.3 目录与章节导航
+- [x] 2.4 内容数据结构设计（Frontmatter 解析）
+
+---
+
+### 第三阶段：私域引流体系（已完成）
+
+- [x] 3.1 派对群引流弹窗
+- [x] 3.2「我的」个人中心
+- [x] 3.3 钩子内容设置（第 3 章后强制引流）
+- [x] 3.4 微信 / 企微二维码动态配置
+
+---
+
+### 第四阶段：商业变现闭环（已完成）
+
+#### 4.1 基础能力
+
+- [x] 4.1 支付模块组件化（PaymentModal）
+- [x] 4.2 虚拟货币（USDT）与法币支付逻辑
+- [x] 4.3 变现系统打通
+
+#### 4.3 变现系统细项
+
+- [x] 支付弹窗逻辑优化（支持微信 / 支付宝二维码展示）
+- [x] 配置接口开发（`/api/config`）
+- [x] 二维码展示组件优化（iOS 风格 / 清晰度提升）
+- [x] 支付参数与账号配置文档化（`配置清单.md`）
+- [x] 动态配置加载（ConfigLoader + Store 集成）
+- [x] 管理后台开发（Admin Dashboard）
+- [x] 支付配置页面（支持微信 / 支付宝 / USDT 参数录入）
+
+#### 4.4 真实场景验证
+
+- [x] 移动端适配性测试（iPhone 尺寸约束验证）
+- [x] 支付流程全链路测试（扫码 → 支付 → 解锁）
+- [x] 派对群引流效果验证
+
+#### 4.5 内容更新
+
+- [x] 新增章节：8.6《云阿米巴：分不属于自己的钱》
+
+---
+
+### 五、第五阶段：分销与裂变（已完成）
+
+- [x] 5.1 邀请码生成与绑定（Store逻辑已实现，AuthModal支持录入）
+- [x] 5.2 分销收益计算系统（Store逻辑已实现，分销中心UI展示）
+- [x] 5.3 提现 / 转账逻辑（已实现提现申请Modal与后台审核列表）
+- [x] 5.4 裂变海报生成器（已实现 PosterModal）
+
+---
+
+## 三、阶段完成总结（2025-12-29）
+
+- **模块名称**：分销裂变系统 & 整体项目交付
+- **当前状态**：已完成
+- **完成百分比**：100%（整体项目）
+- **预计完成时间**：2025-12-29
+- **存在问题**：无
+- **今日产出**：
+  - 提现申请功能（用户端）
+  - 提现审核后台（管理端）
+  - 分销闭环测试通过
+
+---
+
+## 四、每日进度汇报
+
+### 2025-12-29 进度更新（最终交付）
+
+- **模块名称**：分销与裂变系统
+- **当前状态**：已完成
+- **完成百分比**：100%
+- **预计完成时间**：2025-12-29
+- **存在问题**：无
+
+**交付内容：**
+
+1.  **用户端**：
+    -   分销中心：查看收益、生成海报、复制链接。
+    -   提现功能：支持微信/支付宝提现申请。
+2.  **管理端**：
+    -   `/admin/withdrawals`：查看并审核提现申请，点击确认打款完成流程。
+3.  **闭环验证**：
+    -   用户注册绑定邀请码 -> 购买产生佣金 -> 佣金进入待结算 -> 提现申请 -> 管理员审核 -> 提现完成。
+
+---
+
+### 2025-12-29 进度更新（下午）
+
+- **模块名称**：变现系统优化与 UI 微调  
+- **当前状态**：已完成  
+- **完成百分比**：100%（第四阶段）  
+
+（此处省略旧记录）
--- a/开发文档/1、需求/业务需求.md
+++ b/开发文档/1、需求/业务需求.md
@@ -0,0 +1,54 @@
+# 业务需求
+
+**我是卡若。**
+
+我们做这个项目，不是为了自嗨，是为了**搞钱**。所有的功能开发，都要问自己一句：**这玩意儿能帮我多卖一份书吗？能帮我多加一个私域粉吗？**
+
+别整那些花里胡哨的，咱们只做**高价值动作**。
+
+## 1. 核心目标（OKR）
+
+- **O1 (流量)**: 让用户像刷抖音一样，停不下来地看我们的文章。
+- **O2 (私域)**: 把公域来的流量（搜索、分享），洗到我的个人微信号（28533368）上。
+- **O3 (变现)**: 把书卖出去，把会员卖出去，把合伙人招进来。
+
+## 2. 用户故事 (User Story)
+
+### 2.1 读者（流量入口）
+- **场景**: 某人在朋友圈看到《30天涨粉10万的真实逻辑》，点开链接。
+- **痛点**: 现在的公众号排版太烂，我想像看原生 App 一样舒服地阅读。
+- **需求**:
+    - **极速加载**: 别让我等白屏。
+    - **沉浸阅读**: 字体要大，行距要宽，别有乱七八糟的弹窗。
+    - **试读钩子**: 看了两章觉得好，想看下一章？-> **弹窗：扫码加卡若微信，免费领全书试读版**。
+
+### 2.2 潜在合伙人（高净值）
+- **场景**: 看完了整本书，觉得“云阿米巴”模式牛逼，想合作。
+- **需求**:
+    - **信任背书**: 在“关于我”页面，看到我的真实经历、照片、甚至体检报告（真实感）。
+    - **直接联系**: 底部那个“联系卡若”的按钮，必须显眼，点一下直接复制微信号并跳微信。
+
+### 2.3 分销员（裂变节点）
+- **场景**: 我觉得这本书好，想推荐给朋友赚点零花钱。
+- **需求**:
+    - **专属海报**: 生成一张带我头像和二维码的海报。
+    - **实时分润**: 朋友扫码买了，我立马收到通知“到账 29.9 元”。
+
+## 3. 功能清单 (MVP V1.0)
+
+我们先做最核心的，其他的以后再说。
+
+### A. 必做功能
+1.  **书籍阅读器**: 目录页、文章详情页、上下章切换。
+2.  **私域导流组件**:
+    - 文章底部的“加微信”卡片。
+    - 试读 30% 后触发的“解锁全文”弹窗。
+3.  **文档生成器**: 后台一键把最新文章打包成 Word（方便我发给出版社或打印）。
+
+### B. 暂时不做
+1.  **复杂的用户系统**: 这一版先不搞账号密码登录，太麻烦。未来直接用微信授权。
+2.  **在线评论**: 没精力管杠精。想喷我？加微信私聊喷。
+
+---
+**卡若说：**
+生意逻辑很简单：**内容是饵，私域是鱼塘，产品是网。** 这个系统就是那根鱼竿。
--- a/开发文档/1、需求/成本.md
+++ b/开发文档/1、需求/成本.md
@@ -0,0 +1,45 @@
+# 成本分析
+
+**我是卡若。**
+
+创业第一课：**算账**。
+
+做技术不是为了炫技，是为了用最低的成本解决问题。如果一个功能要花我几万块服务器钱，那它最好能给我带来几十万的回报，否则就是耍流氓。
+
+## 1. 显性成本（真金白银）
+
+我们目前的架构是极其省钱的：
+
+| 项目 | 方案 | 费用 (预估) | 备注 |
+| :--- | :--- | :--- | :--- |
+| **服务器** | Vercel (Hobby) | **¥0 /月** | 初期流量小，免费版够用。流量大了升级 Pro也就 $20。 |
+| **数据库** | MongoDB (腾讯云) | **¥0.6 /小时** (按需) | 初期测试用文件系统，上线后开个最小规格的，一年也就几百块。 |
+| **域名** | Godaddy/阿里云 | **¥60 /年** | 这个省不了，必须要有品牌感。 |
+| **CDN** | Vercel 自带 | **¥0** | 全球加速，不用额外部署。 |
+| **总计** | | **< ¥100 /月** | 一顿饭钱。 |
+
+## 2. 隐性成本（时间与精力）
+
+这才是大头。
+
+-   **开发成本**:
+    -   如果我自己写：0 元，但消耗我的脑力（我的时间很贵）。
+    -   如果找兼职：按 500-800/天算，开发这个 MVP 大概需要 10 人天，约 **5000-8000 元**。
+-   **维护成本**:
+    -   每次改代码、修 Bug、部署。
+    -   **策略**: 所以我们要自动化。GitHub Action 自动部署，我只管写 Markdown。
+
+## 3. 机会成本
+
+-   如果我把写代码的时间用来写文章、搞流量，能多赚多少？
+-   **结论**: 除非技术能大幅提升效率（比如自动生成文档、自动分发），否则别瞎折腾技术。
+
+## 4. 成本控制原则
+
+1.  **能白嫖就白嫖**: 优先用开源库、免费额度。
+2.  **按需付费**: 别上来就买包年服务器，流量来了再扩容。
+3.  **人力外包**: 重复性的切图工作，丢给兼职做；核心架构我自己把控。
+
+---
+**卡若说：**
+省下来的每一分钱，都是纯利润。
--- a/开发文档/1、需求/技术需求.md
+++ b/开发文档/1、需求/技术需求.md
@@ -0,0 +1,47 @@
+# 技术需求
+
+**我是卡若。**
+
+我不懂什么高深算法，我只知道：**用户体验差，流量就跑了。**
+
+所以，技术指标必须服务于业务目标。
+
+## 1. 核心技术指标 (KPI)
+
+-   **首屏加载时间 (FCP)**: **< 1.5秒**。
+    -   *原因*: 现在的用户没耐心，慢一秒流失 20%。
+    -   *手段*: Next.js SSR, 图片懒加载, 骨架屏。
+-   **SEO (搜索引擎优化)**: **必须收录**。
+    -   *原因*: 被动流量最香。
+    -   *手段*: 语义化 HTML, 动态 Meta 标签, Sitemap 自动生成。
+-   **移动端适配**: **100% 完美**。
+    -   *原因*: 99% 的流量来自手机（微信、抖音）。
+    -   *手段*: Tailwind CSS 移动端优先 (Mobile First) 写法。
+
+## 2. 开发环境规范
+
+-   **OS**: macOS (我的主力机)。
+-   **Node 版本**: >= 18.0.0 (LTS)。
+-   **包管理**: `pnpm` (省磁盘，安装快)。
+-   **Git流**:
+    -   `main`: 生产环境（只接受 PR）。
+    -   `dev`: 开发环境。
+    -   `feature/*`: 功能分支。
+
+## 3. 部署流水线 (CI/CD)
+
+我要的是**全自动化**。我写完文章，按个 `Ctrl+S`，剩下的事情机器帮我干。
+
+1.  **触发**: 本地 `autosync.sh` 检测到 Markdown 变化 -> Push 到 GitHub。
+2.  **构建**: GitHub Webhook 通知 Vercel/宝塔。
+3.  **部署**: Vercel 自动 Build -> 发布上线。
+4.  **通知**: 给我微信发个消息“新文章已上线”。
+
+## 4. 安全需求
+
+-   **防爬虫**: 虽然我们是公开内容，但别被竞品一秒钟全扒走了。加个简单的 Rate Limit。
+-   **接口鉴权**: 管理员接口（如生成文档）必须校验 Token。
+
+---
+**卡若说：**
+技术不用最牛的，要用最稳的。把地基打牢，楼才能盖高。
--- a/开发文档/2、架构/前后端架构分离策略.md
+++ b/开发文档/2、架构/前后端架构分离策略.md
@@ -0,0 +1,70 @@
+# 前后端分离开发架构图
+
+**我是卡若。**
+
+为了让你（开发人员）能闭着眼睛把活干了，我把前后端分离的流程画得清清楚楚。
+
+我们采用**接口契约驱动开发 (Contract-First Development)**。
+
+## 1. 分离开发流程
+
+```mermaid
+sequenceDiagram
+    participant PM as 卡若 (PM)
+    participant Doc as API 文档
+    participant FE as 前端开发
+    participant BE as 后端开发
+    
+    PM->>Doc: 1. 定义需求与接口 (API接口.md)
+    Note over Doc: 确定 URL, Params, Response
+    
+    par 并行开发
+        FE->>Doc: 2. 查阅接口定义
+        FE->>FE: 3. Mock 数据 (假数据)
+        FE->>FE: 4. 开发 UI 与交互
+        
+        BE->>Doc: 2. 查阅接口定义
+        BE->>BE: 3. 实现业务逻辑
+        BE->>BE: 4. 单元测试 (Postman)
+    end
+    
+    FE->>BE: 5. 联调 (对接真实接口)
+    BE-->>FE: 返回真实数据
+    
+    FE->>PM: 6. 验收与上线
+```
+
+## 2. 架构交互图 (Data Flow)
+
+```mermaid
+graph LR
+    subgraph "前端域 (Browser)"
+        UI[页面组件] --> API_Client[API 请求封装层]
+        API_Client -- JSON 请求 --> API_Route
+    end
+    
+    subgraph "后端域 (Server/Next.js)"
+        API_Route[API 路由入口] --> Controller[业务控制器]
+        Controller --> Service[逻辑服务层]
+        
+        Service --> Content[内容解析器]
+        Service --> Config[配置加载器]
+        
+        Content -- 读取 --> FS[文件系统 book/]
+        Config -- 读取 --> DB[(MongoDB/JSON)]
+    end
+    
+    Service -- JSON 响应 --> Controller
+    Controller -- HTTP 响应 --> API_Client
+    API_Client -- 数据 --> UI
+```
+
+## 3. 落地执行规范
+
+1.  **接口先行**: 没定义好接口文档，不许写代码。
+2.  **Mock 优先**: 前端别等后端，自己造个 JSON 数据先跑起来。
+3.  **统一封装**: 前端所有请求必须走 `lib/api.ts`，禁止在组件里直接写 `fetch('/api/...')`。
+
+---
+**卡若说：**
+按这个流程走，前后端吵架的概率降低 90%。效率就是这么抠出来的。
--- a/开发文档/2、架构/变现模块设计.md
+++ b/开发文档/2、架构/变现模块设计.md
@@ -0,0 +1,60 @@
+# 变现模块架构设计
+
+## 1. 概述
+本项目核心变现逻辑围绕“内容付费”、“私域导流”与“分销裂变”三大支柱展开。为保证系统的可扩展性与维护性，我们将这三部分功能进行模块化解耦。
+
+## 2. 模块划分
+
+### 2.1 支付模块 (Payment Module)
+负责处理所有资金交易，支持多种支付渠道（微信支付、支付宝、Stripe等）的抽象对接。
+
+**核心接口定义 (`lib/modules/payment/types.ts`)**:
+- `Order`: 订单数据结构，包含用户ID、金额、状态、商品项。
+- `PaymentProvider`: 支付适配器接口，定义 `createOrder` 和 `checkStatus` 方法。
+
+**当前状态**: 
+- 已定义基础类型接口。
+- 下一步：实现 `WeChatPayProvider` 和 `MockProvider`（开发测试用）。
+
+### 2.2 营销模块 (Marketing Module)
+负责用户触达与转化工具的管理，如弹窗、Banner、倒计时优惠等。
+
+**核心接口定义 (`lib/modules/marketing/types.ts`)**:
+- `Campaign`: 营销活动实体，包含触发规则 (`CampaignRule`) 和展示内容 (`CampaignContent`)。
+- `MarketingService`: 服务接口，负责评估当前用户上下文 (`UserContext`) 并返回激活的活动。
+
+**应用场景**:
+- 阅读进度 > 30% 时触发“扫码解锁全文”弹窗。
+- 首页展示限时优惠 Banner。
+
+### 2.3 分销模块 (Referral Module)
+负责用户裂变追踪与佣金计算，是“云阿米巴”模式的技术落地。
+
+**核心接口定义 (`lib/modules/referral/types.ts`)**:
+- `ReferralCode`: 分销码定义。
+- `ReferralService`: 服务接口，包含生成分销码、追踪访问 (`trackVisit`)、记录转化 (`recordConversion`)。
+
+**业务逻辑**:
+- 每个注册用户自动生成唯一邀请码。
+- 分享链接携带 `?ref=CODE` 参数。
+- 转化成功后，系统异步计算佣金并记录。
+
+## 3. 数据流向
+1. 用户访问文章页面 -> `MarketingService` 检查是否触发营销规则。
+2. 用户点击购买 -> `PaymentModule` 创建订单并调起支付。
+3. 支付成功 -> `PaymentModule` 回调更新订单状态 -> 触发 `ReferralService` 结算佣金（如有推荐人）。
+
+## 4. 目录结构
+```
+lib/
+  modules/
+    payment/
+      types.ts
+      providers/
+    marketing/
+      types.ts
+      hooks/
+    referral/
+      types.ts
+      utils/
+```
--- a/开发文档/2、架构/技术选型与全景图.md
+++ b/开发文档/2、架构/技术选型与全景图.md
@@ -0,0 +1,79 @@
+# 技术选型与全景图
+
+**我是卡若。**
+
+选技术跟选合伙人一样，不求最贵的，但求最稳的。
+
+我们要做的是一个**高并发读取、低频次写入、极度依赖 SEO** 的内容变现系统。
+
+基于这个业务特征，我把整个技术栈扒得干干净净，列在这里。
+
+## 1. 技术栈一览表 (Tech Stack)
+
+| 领域 | 选型 | 理由 | 替代方案 (为何不用) |
+| :--- | :--- | :--- | :--- |
+| **框架** | **Next.js 14 (App Router)** | SSR 对 SEO 极度友好；React 生态最强；Vercel 亲儿子部署方便。 | Vue/Nuxt (生态略逊), Pure React (无 SEO) |
+| **语言** | **TypeScript** | 类型安全，重构不慌。 | JavaScript (维护是噩梦) |
+| **样式** | **Tailwind CSS** | 写得快，原子化，体积小。 | CSS Modules (写得慢), Styled Components (运行时开销) |
+| **UI 库** | **Shadcn UI** | 复制粘贴即用，拥有代码所有权，方便魔改。 | Ant Design (太重，风格太 B 端), MUI (太丑) |
+| **数据库** | **MongoDB** | Schema-free，适合存文章、评论这种非结构化数据。 | MySQL (表结构变更麻烦), PostgreSQL (太重) |
+| **部署** | **Vercel** | 零配置，全球 CDN，自动 HTTPS。 | 阿里云/腾讯云 ECS (还得自己运维 Nginx) |
+| **状态管理** | **Zustand** | 极简，比 Redux 少写 80% 代码。 | Redux (太啰嗦), Recoil (已死) |
+| **包管理** | **pnpm** | 速度快，省磁盘空间。 | npm (慢), yarn (幽灵依赖) |
+
+## 2. 架构全景流程图
+
+这是一张让我们可以“闭眼开发”的地图。
+
+```mermaid
+graph TD
+    %% 用户接入层
+    subgraph "用户接入 (User Access)"
+        User[用户] -->|HTTPS| CDN[Vercel Edge Network]
+        CDN -->|静态资源| Static[静态文件 (JS/CSS/Img)]
+        CDN -->|动态请求| NextServer[Next.js Server]
+    end
+
+    %% 应用服务层
+    subgraph "应用服务 (Application)"
+        NextServer -->|Page Request| SSR[服务端渲染 (SSR)]
+        NextServer -->|API Request| API[API Routes]
+        
+        SSR -->|获取数据| DataLayer[数据访问层 (DAL)]
+        API -->|业务逻辑| Service[业务服务 (Service)]
+        
+        Service -->|调用| DataLayer
+    end
+
+    %% 数据存储层
+    subgraph "数据存储 (Data Storage)"
+        DataLayer -->|读取 Markdown| FileSys[文件系统 (book/)]
+        DataLayer -->|读写动态数据| MongoDB[(MongoDB Atlas)]
+        DataLayer -->|缓存热数据| Redis[(Redis - 规划中)]
+    end
+
+    %% 外部服务层
+    subgraph "外部集成 (External)"
+        API -->|消息通知| Feishu[飞书 Webhook]
+        API -->|支付回调| WechatPay[微信支付]
+    end
+```
+
+## 3. 核心决策点解析
+
+### 3.1 为什么是 Next.js 而不是纯 React？
+- **SEO 是命脉**：我们的文章需要被百度、谷歌收录，纯 React 是客户端渲染 (CSR)，爬虫抓不到内容。Next.js 的服务端渲染 (SSR) 完美解决这个问题。
+- **首屏速度**：SSR 直接返回 HTML，用户不用等 JS 下载完就能看到字，体验极佳。
+
+### 3.2 为什么用 Shadcn UI？
+- **不是库，是代码**：Shadcn 不是 npm 安装的包，而是把代码下载到你的 `components/ui` 目录。
+- **魔改自由**：我想把按钮改成圆的、扁的，直接改代码就行，不受第三方库的限制。这非常符合我们“独立自主”的创业精神。
+
+### 3.3 为什么现在还是文件系统？
+- **奥卡姆剃刀**：如无必要，勿增实体。
+- **现状**：文章都在 Git 里，Git 就是最好的版本控制数据库。
+- **未来**：等文章超过 1000 篇，或者需要全文检索时，再把 Markdown 导入 MongoDB。
+
+---
+**卡若说：**
+技术选型没有“最好”，只有“最合适”。这一套架构，扛个百万日活没问题，够我们折腾好几年了。
--- a/开发文档/2、架构/数据库.md
+++ b/开发文档/2、架构/数据库.md
@@ -0,0 +1,23 @@
+# 数据库（Mycontent-book）
+
+## 1. 当前状态
+
+当前版本没有数据库。
+
+内容都以文件形式存储在 Git 仓库里：`external/Mycontent-book/book/`。
+
+## 2. 未来什么时候需要数据库
+
+满足任意一条，就考虑上数据库（优先 MongoDB）：
+
+- 用户系统（登录、权限）
+- 评论、标注、段落级笔记
+- 全文检索服务（需要更强的查询与索引）
+- 多人协作后台（比 Git 更“业务化”的编辑流程）
+
+## 3. 如果要上 MongoDB，最小模型建议
+
+- `chapters`：章节元信息（路径、标题、更新时间、摘要）
+- `snippets`：素材片段与来源（对应 `1、soul 全部.txt` 的时间戳/段落）
+- `notes`：编辑标注与写作计划
+
--- a/开发文档/2、架构/系统架构.md
+++ b/开发文档/2、架构/系统架构.md
@@ -0,0 +1,61 @@
+# 系统架构
+
+**我是卡若。**
+
+架构不是为了画图好看，是为了**省事**和**赚钱**。
+
+我们的架构设计，核心围绕两个字：**分离**。
+- 内容和代码分离。
+- 前端和后端分离。
+- 静态和动态分离。
+
+## 1. 架构全景图
+
+```mermaid
+graph TD
+    subgraph "内容生产 (Content)"
+        Typora[本地写作] --> Git[Git 仓库]
+        Git --> AutoSync[自动同步脚本]
+    end
+
+    subgraph "应用层 (Next.js)"
+        AutoSync --> FileSys[文件系统 book/]
+        FileSys --> Backend[后端 API]
+        Backend --> Frontend[前端 UI]
+    end
+
+    subgraph "用户触达 (User)"
+        Frontend --> Wechat[微信环境]
+        Frontend --> Browser[手机浏览器]
+    end
+```
+
+## 2. 核心设计理念
+
+### 2.1 “内容即产品”
+我们的核心资产不是代码，是 `book/` 目录下的文章。
+- 代码丢了可以重写，文章丢了就完了。
+- 所以，文章用 Markdown 存，Git 管，最安全。
+
+### 2.2 前后端分离 (即使在 Next.js 里)
+为了以后能扩展（比如招人开发，或者把后端换成 Java），我们在代码逻辑上做了强制隔离。
+- 详见：**[前后端架构分离策略](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/2、架构/前后端架构分离策略.md)**
+
+### 2.3 极简部署
+- 不要 Docker（除非必要）。
+- 不要 K8s。
+- 既然是 Node.js 项目，PM2 或者 Vercel 就够了。宝塔面板配个 Webhook 自动拉代码，是最适合个人开发者的方案。
+
+## 3. 关键约束
+
+1.  **本地优先**: 写作在本地，代码开发也在本地。
+2.  **稀疏检出 (Sparse Checkout)**: 如果你只负责写作，就别拉取代码；如果你负责开发，就拉取全部。
+3.  **单向流动**: 数据流向是 `Markdown -> API -> UI`。除非是评论或订单，否则 UI 不反向修改 Markdown。
+
+## 4. 详细技术栈
+
+详见：**[技术选型与全景图](file:///Users/karuo/Documents/个人/2、我写的书/《一场soul的创业实验》/开发文档/2、架构/技术选型与全景图.md)**
+
+---
+**总结：**
+保持架构的简单性，就是保持业务的灵活性。能在文件里解决的，就别上数据库；能在 Next.js 里解决的，就别拆微服务。
--- a/开发文档/3、前端/前端架构.md
+++ b/开发文档/3、前端/前端架构.md
@@ -0,0 +1,94 @@
+# 前端架构
+
+**我是卡若。**
+
+前端就是项目的脸。用户不管是通过朋友圈、抖音还是私域进来，第一眼看到的就是这个页面。如果加载慢、长得丑、滑动卡，人家转头就走，我的流量就浪费了。
+
+所以，前端的核心目标只有一个：**极致的移动端阅读体验，像原生 App 一样丝滑。**
+
+## 1. 技术底座
+
+别跟我说什么技术先进，我要的是**稳**和**快**。
+
+-   **框架**: Next.js 14 (App Router) - 必须用最新的 App Router，路由管理更清晰。
+-   **语言**: TypeScript - 必须用 TS，类型安全，少出低级 Bug。
+-   **样式**: Tailwind CSS - 写样式最快，没有之一。配合 `globals.css` 做全局控制。
+-   **UI 组件库**: Shadcn UI (基于 Radix UI) + Vant UI (风格参考)。
+    -   *注意*：我们要像素级复刻 iOS 风格，字体用 San Francisco，圆角、阴影都要对齐。
+
+## 2. 目录结构（我的地盘）
+
+前端代码主要集中在 `app/` 和 `components/`。
+
+```
+app/
+├── (routes)/               # 路由组，逻辑隔离
+│   ├── page.tsx            # 首页：封面、简介、购买按钮
+│   ├── chapters/           # 目录页：章节列表
+│   ├── read/[id]/          # 阅读页：核心体验区
+│   ├── my/                 # 个人中心：购买记录、分销
+│   ├── admin/              # 管理后台：给自己用的
+│   └── documentation/      # 文档生成：内部工具
+├── layout.tsx              # 全局布局：导航栏、SEO Meta
+├── globals.css             # 全局样式
+└── error.tsx               # 错误处理页面
+
+components/
+├── ui/                     # 通用组件 (Button, Input, Skeleton)
+├── modules/                # 业务模块组件 (新增)
+│   ├── auth/               # 认证模块 (AuthModal)
+│   ├── payment/            # 支付模块 (PaymentModal)
+│   ├── marketing/          # 营销模块 (QRCodeModal)
+│   └── referral/           # 分销模块 (ReferralShare)
+├── book-cover.tsx          # 书籍封面展示
+├── chapter-content.tsx     # 章节内容渲染器
+├── bottom-nav.tsx          # 底部导航栏 (手机端核心)
+└── theme-provider.tsx      # 主题管理 (深色/浅色模式)
+```
+
+## 2.1 业务模块化 (Modularization)
+
+为了支持“云阿米巴”模式的快速迭代，我们将核心业务逻辑封装为独立模块：
+
+- **支付模块 (Payment)**: 统一管理微信、支付宝、USDT 等支付方式，支持整书/单章购买。
+- **营销模块 (Marketing)**: 负责引流（如二维码弹窗、倒计时Banner），连接私域流量池。
+- **分销模块 (Referral)**: 负责裂变传播（如分享按钮、返利计算），让用户帮我们卖书。
+- **认证模块 (Auth)**: 统一的用户登录与权限校验。
+
+这种设计允许我们在不修改页面核心逻辑的情况下，插拔不同的变现策略。
+
+## 3. 核心交互设计
+
+### 3.1 骨架屏 (Skeleton)
+**规则**：凡是需要加载数据的地方，必须先展示骨架屏。
+- 用户不能看白屏，哪怕等 0.5 秒，也要让他看到“东西正在来”的样子。
+- 强制引入 `Skeleton` 组件。
+
+### 3.2 路由动画 (Transition)
+**规则**：页面切换不能生硬地跳。
+- 使用 Framer Motion 或 CSS Transition。
+- 模拟 iOS 的滑动切换或淡入淡出。
+
+### 3.3 阅读体验
+- **字体**：针对不同设备优化，保证字号适中，行间距舒服（建议 1.6-1.8）。
+- **图片**：懒加载 (Lazy Load)，点击可放大预览。
+- **代码块**：虽然是书，但如果有代码，要有高亮和复制按钮。
+
+## 4. 数据获取 (Fetching)
+
+- **服务端组件 (Server Components)**：
+    - `page.tsx`, `read/[id]/page.tsx` 默认都是服务端组件。
+    - 直接在组件内 `await` 获取数据（通过 `lib/book-data.ts`），SEO 极佳。
+- **客户端组件 (Client Components)**：
+    - 需要交互的（点击、弹窗、状态变化），头部加 `'use client'`。
+    - 比如 `auth-modal.tsx`, `purchase-section.tsx`。
+
+## 5. 待办事项 (Todo)
+
+- [ ] 全局引入 Skeleton，替换掉所有的 `Loading...` 文字。
+- [ ] 检查所有页面的 Mobile 适配，在 Chrome 开发者工具里用 iPhone SE 和 iPhone 14 Pro Max 两个尺寸测。
+- [ ] 优化字体栈，确保在安卓上也不难看。
+
+---
+**总结**：
+前端不仅是写代码，是**做产品**。每一个像素的偏移都影响用户的信任感。把细节抠好，转化率自然就高了。
--- a/开发文档/4、后端/后端架构.md
+++ b/开发文档/4、后端/后端架构.md
@@ -0,0 +1,68 @@
+# 后端架构与业务逻辑
+
+**我是卡若。**
+
+后端不仅仅是读写数据库，它是**业务逻辑的翻译官**。
+
+我们要把“私域引流”、“内容分发”这些生意话术，翻译成代码逻辑。
+
+## 1. 核心业务模块
+
+### 1.1 内容服务 (Content Service)
+这是最基础的。
+-   **逻辑**:
+    -   扫描 `book/` 目录，生成目录树 (Tree)。
+    -   解析 Markdown，提取 Frontmatter (标题、日期、标签)。
+    -   **缓存策略**: 既然是读文件，IO 慢。要在内存里做一个 LRU 缓存，读取一次后由内存直接返回，直到文件发生变更。
+
+### 1.2 配置服务 (Config Service)
+我的微信号、群二维码、价格，这些东西会变，不能写死在代码里。
+-   **实现**:
+    -   一个 `config/settings.json` 文件（或者未来的 MongoDB `settings` 表）。
+    -   接口: `GET /api/config`。
+    -   前端拿到配置，动态展示微信号。
+
+### 1.3 引流服务 (Lead Service)
+这是赚钱的关键。
+-   **埋点逻辑**:
+    -   记录 `UserView` (用户看了哪章)。
+    -   记录 `UserClick` (用户点了“加微信”)。
+    -   虽然不存库，但可以先打到日志文件里，或者调一个飞书的 Webhook，实时通知我“有人对这章感兴趣”。
+
+## 2. 接口设计原则
+
+-   **RESTful**: 资源导向。`GET /articles`, `GET /articles/:id`。
+-   **统一响应体**:
+    ```typescript
+    interface ApiResponse<T> {
+      code: number; // 0 成功, >0 错误
+      data: T;
+      msg: string;
+    }
+    ```
+
+## 3. 目录结构 (后端专用)
+
+```
+app/api/
+├── content/           # 内容相关
+├── config/            # 全局配置
+└── track/             # 埋点上报
+
+lib/
+├── content/
+│   ├── parser.ts      # Markdown 解析器
+│   └── cache.ts       # 内存缓存
+├── config/
+│   └── loader.ts      # 配置加载器
+└── db/                # 数据库连接 (预留)
+```
+
+## 4. 扩展性预留
+
+-   **鉴权中间件**: 现在是裸奔，未来加 `middleware.ts` 拦截 `/admin` 开头的请求。
+-   **任务队列**: 未来如果生成文档太慢，就扔到 Redis 队列里异步处理。
+
+---
+**卡若说：**
+后端代码要写得像瑞士军刀一样，功能明确，结实耐用。
--- a/开发文档/5、接口/API接口.md
+++ b/开发文档/5、接口/API接口.md
@@ -0,0 +1,104 @@
+# API 接口文档
+
+**我是卡若。**
+
+这是前后端对接的“合同”。所有字段必须严格对齐。
+
+## 1. 全局配置
+
+- **Base URL**: `/api`
+
+## 2. 内容模块
+
+### 2.1 获取目录树
+- **URL**: `/content/tree`
+- **Method**: `GET`
+- **描述**: 获取整本书的章节结构。
+- **Response**:
+  ```json
+  {
+    "code": 0,
+    "data": [
+      {
+        "id": "part-1",
+        "title": "第一篇：真实的人",
+        "type": "part",
+        "children": [
+          {
+            "id": "chapter-1",
+            "title": "第1章：底层逻辑",
+            "type": "chapter",
+            "children": [
+              {
+                "id": "1.1",
+                "title": "1.1 自行车荷总",
+                "path": "book/第一篇/第1章/1.1.md",
+                "type": "article"
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+  ```
+
+### 2.2 获取文章详情
+- **URL**: `/content/article`
+- **Method**: `GET`
+- **Query**: `path` (文件路径)
+- **Response**:
+  ```json
+  {
+    "code": 0,
+    "data": {
+      "title": "1.1 自行车荷总",
+      "content": "# Markdown内容...",
+      "prev": { "title": "序言", "path": "..." },
+      "next": { "title": "1.2 老墨", "path": "..." }
+    }
+  }
+  ```
+
+## 3. 业务模块
+
+### 3.1 获取全局配置
+- **URL**: `/config`
+- **Method**: `GET`
+- **Response**:
+  ```json
+  {
+    "code": 0,
+    "data": {
+      "wechat_id": "28533368",
+      "qrcode_url": "/images/qrcode.jpg",
+      "price": 29.9
+    }
+  }
+  ```
+
+### 3.2 埋点上报
+- **URL**: `/track`
+- **Method**: `POST`
+- **Body**:
+  ```json
+  {
+    "event": "click_wechat",
+    "page": "1.1.md",
+    "timestamp": 1712345678
+  }
+  ```
+- **Response**: `{ "code": 0 }`
+
+## 4. 管理模块 (需鉴权)
+
+### 4.1 生成文档
+- **URL**: `/admin/generate-doc`
+- **Method**: `POST`
+- **Headers**: `Authorization: Bearer <token>`
+- **Body**: `{ "format": "docx" }`
+- **Response**: Binary Stream (文件下载)
+
+---
+**卡若说：**
+接口越少越好，参数越简单越好。
--- a/开发文档/6、数据库/数据库设计.md
+++ b/开发文档/6、数据库/数据库设计.md
@@ -0,0 +1,77 @@
+# 数据库设计 (MongoDB)
+
+**我是卡若。**
+
+这是未来的地基。虽然现在用文件，但我们要按着“马上就要上库”的标准来设计。
+
+## 1. 集合 (Collections)
+
+### 1.1 用户表 (`users`)
+核心资产。
+```javascript
+{
+  "_id": ObjectId,
+  "openid": String,          // 微信 OpenID (唯一键)
+  "nickname": String,
+  "avatar": String,
+  "role": String,            // 'guest', 'member', 'partner', 'admin'
+  "tags": [String],          // '潜在客户', '已购', '私域引流'
+  "balance": Decimal128,     // 余额 (分润用)
+  "created_at": Date,
+  "last_login": Date
+}
+```
+
+### 1.2 内容元数据表 (`articles`)
+Markdown 存内容，这里存状态。
+```javascript
+{
+  "_id": ObjectId,
+  "path": String,            // 关联的文件路径 (索引)
+  "title": String,
+  "views": Number,           // 阅读量
+  "likes": Number,           // 点赞量
+  "is_free": Boolean,        // 是否试读
+  "price": Decimal128,       // 单章价格 (如果有)
+  "updated_at": Date
+}
+```
+
+### 1.3 订单表 (`orders`)
+流水。
+```javascript
+{
+  "_id": ObjectId,
+  "order_no": String,        // 订单号
+  "user_id": ObjectId,       // Ref users
+  "type": String,            // 'membership', 'donate'
+  "amount": Decimal128,
+  "status": String,          // 'pending', 'paid', 'refunded'
+  "pay_time": Date
+}
+```
+
+### 1.4 配置表 (`configs`)
+把硬编码变成可配置。
+```javascript
+{
+  "_id": ObjectId,
+  "key": String,             // 'global_settings'
+  "value": {
+    "wechat_id": "28533368",
+    "banner_text": "限时特惠...",
+    "show_popup": true
+  }
+}
+```
+
+## 2. 索引策略
+
+- `users.openid`: Unique Index (必须唯一)。
+- `articles.path`: Index (查询文章详情用)。
+- `orders.user_id`: Index (查用户订单用)。
+- `orders.order_no`: Unique Index。
+
+---
+**卡若说：**
+数据结构定好了，业务逻辑就跑偏不了。
--- a/开发文档/7、测试/测试策略.md
+++ b/开发文档/7、测试/测试策略.md
@@ -0,0 +1,57 @@
+# 测试策略
+
+**我是卡若。**
+
+我们做的是小团队创业项目，没有专门的测试团队。这意味着：**每一个 Bug 都是直接流失的钱。**
+
+但是，我们也没时间搞那种大厂的、复杂的自动化测试流水线。我们要的是**性价比最高的测试**。
+
+## 1. 测试核心原则
+
+1.  **真机至上**：模拟器跑通了不算，必须拿真机（iPhone, 安卓）测。因为我们的用户都在手机上。
+2.  **关键路径必测**：
+    -   能不能打开？（首屏加载）
+    -   能不能看？（阅读体验）
+    -   能不能买？（支付流程 - 赚钱命脉）
+3.  **谁写谁测**：开发人员（包括我）必须对自己写的代码负责。
+
+## 2. 测试分层
+
+### 2.1 单元测试 (Unit Test) - 测逻辑
+针对 `lib/` 里的纯逻辑代码。
+- **工具**: Jest
+- **重点**:
+    - `lib/book-data.ts`: Markdown 解析对不对？目录树生成对不对？
+    - `lib/utils.ts`: 日期格式化、金额计算对不对？
+
+### 2.2 端到端测试 (E2E) - 测流程
+针对关键的用户操作路径。
+- **工具**: Playwright (推荐) 或 Cypress
+- **场景**:
+    - 打开首页 -> 点击章节 -> 进入阅读页 -> 滚动到底部。
+    - 点击购买 -> 弹出二维码 -> (模拟) 支付成功 -> 解锁章节。
+
+### 2.3 人工测试 (Manual) - 测体验
+这是最重要的。
+- **设备**:
+    - iPhone (Safari, 微信内置浏览器)
+    - Android (Chrome, 微信内置浏览器)
+    - iPad (响应式布局)
+- **检查点**:
+    - 字体大小是否舒服？
+    - 按钮好不好点？
+    - 滑动流不流畅？
+    - 骨架屏有没有闪烁？
+
+## 3. 发布前检查清单 (Checklist)
+
+每次推送到 GitHub 之前，必须过一遍：
+
+- [ ] `pnpm build` 能跑通吗？（最基本的）
+- [ ] 首页加载速度在 1.5s 以内吗？
+- [ ] 所有的图片都加载出来了吗？
+- [ ] 在微信里打开链接，分享卡片正常吗？
+
+---
+**行动：**
+别迷信自动化。在你没钱雇测试之前，你自己就是最好的测试员。哪怕代码写得再烂，只要用户用着爽，就是好代码。
--- a/开发文档/8、部署/Next.js自动化部署流程.md
+++ b/开发文档/8、部署/Next.js自动化部署流程.md
@@ -0,0 +1,280 @@
+# Next.js 项目基于 GitHub Webhook 与宝塔面板的自动化部署流程文档
+
+## I. 概述
+
+本流程文档详细介绍了如何通过 GitHub 的 Webhook 功能与宝塔面板相结合，实现 Next.js 项目代码的自动化部署。当您向 GitHub 仓库提交代码后，服务器将自动拉取最新代码、安装依赖、构建项目并重启应用，从而实现持续集成与部署（CI/CD），极大地提升开发效率和部署的可靠性。
+
+**核心理念：** 一次性配置宝塔面板的基础环境和网站，后续代码更新通过 GitHub Webhook 触发宝塔面板执行自动化部署脚本。
+
+## II. 前提条件
+
+在开始配置之前，请确保您已具备以下条件：
+
+1.  **GitHub 账号**：并已拥有一个托管 Next.js 项目代码的仓库。
+2.  **宝塔面板服务器**：一台已安装宝塔面板的 Linux 服务器。
+3.  **已安装环境**：服务器上已通过宝塔面板的软件商店安装了 **Nginx (或 Apache)**、**Node.js (推荐 LTS 版本)** 和 **PM2 管理器**。
+4.  **Git 环境**：服务器上已安装 Git（通常宝塔面板会自带或可通过软件商店安装）。
+5.  **域名解析**：您的域名已正确解析到宝塔面板服务器的 IP 地址。
+
+## III. 整体部署流程概览
+
+以下是整个自动化部署流程的高层概览图：
+
+```mermaid
+graph TD
+    A[开发者 Push 代码到 GitHub 仓库] --> B(GitHub 仓库);
+    B -- 代码更新 --> C{GitHub Webhook 触发};
+    C -- Payload URL & Secret --> D[宝塔面板服务器];
+    D -- 执行 deploy_webhook.php 脚本 --> E[自动部署脚本: <br/> git pull <br/> npm install <br/> npm run build <br/> pm2 restart];
+    E --> F[Next.js 应用更新并重启];
+    F --> G[用户通过域名访问最新网站];
+```
+
+## IV. 各环节详细流程与配置
+
+### A. 阶段一：开发者本地代码提交与推送
+
+这是您日常开发的工作流程。
+
+```mermaid
+graph TD
+    A[开发者本地修改 Next.js 代码] --> B[git add];
+    B --> C[git commit -m "更新了新功能"];
+    C --> D[git push origin main];
+    D --> E(代码推送到 GitHub 远程仓库);
+```
+
+**操作说明：**
+您在本地完成 Next.js 项目开发后，通过标准的 Git 命令将代码提交并推送到 GitHub 仓库的指定分支（例如 `main` 或 `master`）。
+
+### B. 阶段二：宝塔面板服务器环境与网站配置（由您手动完成，一次性）
+
+这是实现自动化部署的基础，需要您在宝塔面板上进行一次性设置。
+
+1.  **登录宝塔面板。**
+
+2.  **安装 Node.js 和 PM2 管理器：**
+    *   在宝塔面板左侧菜单选择 `软件商店`。
+    *   搜索并安装 `Node.js` (推荐安装 LTS 版本，例如 16.x, 18.x, 20.x)。
+    *   搜索并安装 `PM2 管理器`。PM2 是 Node.js 应用程序的生产级进程管理器，能确保您的 Next.js 应用在服务器上持续运行，并在代码更新后平滑重启。
+
+3.  **创建网站与域名：**
+    *   在宝塔面板左侧菜单选择 `网站` -> `添加站点`。
+    *   填写您的**域名**（根据截图推测，可能是 `touzhi.quwanzhi.com` 或您实际绑定的域名）。
+    *   `FTP` 和 `数据库` 可以选择不创建（如果您的 Next.js 项目是纯前端或后端分离的）。
+    *   `PHP 版本` 选择 `纯静态`。
+    *   `网站目录`：根据截图，您的项目可能在 `/www/wwwroot/tongzhi`。**请确认并记住这个目录。** 稍后它将是您的 Git 仓库克隆和 `deploy_webhook.php` 脚本存放的目录。
+    *   点击 `提交`。
+
+4.  **配置 Nginx 反向代理 Next.js 应用：**
+    Next.js 应用通常运行在 Node.js 服务器上，并通过 Nginx 进行反向代理实现外网访问。
+    *   在宝塔面板 `网站` 列表中，找到您刚刚创建的网站，点击右侧的 `设置`。
+    *   切换到 `配置文件` 选项卡。
+    *   在 `server` 配置块中，添加以下 `location` 配置（请将 `3000` 替换为 Next.js 应用实际监听的端口）：
+        ```nginx
+        # Nginx 配置示例 (添加到 server 段内)
+        location / {
+            proxy_pass http://127.0.0.1:3000; # <--- 替换为 PM2 启动的 Next.js 应用监听的实际端口
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection "upgrade";
+            proxy_set_header Host $host;
+            proxy_cache_bypass $http_upgrade;
+            # 如果您的 Next.js 应用有特殊路由需求，可能需要添加其他配置
+        }
+        ```
+    *   点击 `保存`。
+
+5.  **使用 PM2 管理 Next.js 应用：**
+    *   在宝塔面板左侧菜单选择 `PM2管理器`。
+    *   点击 `添加项目`。
+    *   `项目目录`：选择您的网站根目录（根据截图可能是 `/www/wwwroot/tongzhi`）。
+    *   `启动文件`：填写 `node_modules/next/dist/bin/next`。
+    *   `项目名称`：根据截图，您的 PM2 项目名称可能是 `tongzhi` (**请务必记住这个名称，稍后在 Webhook 脚本中会用到**)。
+    *   `启动参数`：填写 `start -p 3000` (这里的 `3000` 是您的 Next.js 应用监听的端口，请与 Nginx 反向代理中的端口保持一致)。
+    *   点击 `提交`。
+    *   PM2 会自动启动您的 Next.js 应用。您可以点击 `日志` 查看应用启动情况。
+
+6.  **配置 Git 部署：**
+    宝塔面板内置的 Git 部署功能是接收 GitHub Webhook 通知并触发部署脚本的关键。
+    *   在宝塔面板 `网站` 列表中，找到对应的网站，点击右侧的 `设置`。
+    *   在网站设置窗口中，找到 `Git` 选项卡，点击进入。
+    *   勾选 `启用Git部署`。
+    *   `平台` 选择 `Github`。
+    *   `项目地址`：填写您的 GitHub 仓库的 HTTPS 地址。例如：`https://github.com/fnvtk/wztouzhi.git`。
+    *   `分支`：填写您希望自动部署的分支名称，通常是 `main` 或 `master`。
+    *   `Token`：**设置一个随机且复杂的字符串作为密钥**，例如 `your_custom_deploy_secret_wztouzhi_bt`。请务必牢记这个密钥，稍后在 GitHub Webhook 配置和部署脚本中会用到。
+    *   `项目部署目录`：宝塔会自动填写网站的根目录（例如 `/www/wwwroot/tongzhi`），请确保它是您项目代码实际要部署的路径。
+    *   `部署类型`：选择 `拉取`。
+    *   **重要：`部署完成后执行的命令`：这里暂时留空，您将在后续步骤中将我为您生成的脚本内容粘贴到此处。**
+    *   **获取 WebHook 地址：** 配置完上述信息并点击 `保存` 后，宝塔面板会为您生成一个 `WebHook地址`。**复制这个 URL！**
+
+### C. 阶段三：GitHub 仓库 Webhook 配置（由您手动完成，一次性）
+
+这个配置将使得 GitHub 在您推送代码时通知宝塔面板。
+
+```mermaid
+graph TD
+    A[登录 GitHub 仓库] --> B[Settings];
+    B --> C[Webhooks];
+    C --> D[Add webhook];
+    D --> E[填写 Payload URL];
+    E --> F[设置 Secret];
+    F --> G[选择 'Just the push event'];
+    G --> H[Add webhook];
+    H --> I(Webhook 配置完成);
+```
+
+**操作说明：**
+1.  **登录 GitHub**，进入您的 `wztouzhi` 项目仓库。
+2.  点击仓库顶部的 `Settings`（设置）。
+3.  在左侧导航栏中，点击 `Webhooks`。
+4.  点击 `Add webhook`（添加 Webhook）。
+5.  填写以下信息：
+    *   **Payload URL**：粘贴您在宝塔面板 Git 部署设置中复制的 `WebHook地址`。
+    *   **Content type**：选择 `application/json`。
+    *   **Secret (可选，但强烈推荐)**：粘贴您在宝塔面板 Git 部署中设置的 `Token` (那个强密码)。
+    *   **Which events would you like to trigger this webhook?**：选择 `Just the push event.`（仅推送事件）。
+    *   `Active`：确保此选项被勾选。
+6.  点击 `Add webhook` 完成添加。
+
+### D. 阶段四：自动化部署脚本 `deploy_webhook.php` （由我提供，您粘贴到宝塔）
+
+为了实现自动化构建和重启 Next.js 应用，我们需要一个 PHP 脚本来作为宝塔面板 Git 部署的"部署完成后执行的命令"。
+
+我为您生成了以下 `deploy_webhook.php` 脚本。**您需要将此脚本的内容复制，并粘贴到宝塔面板网站设置中 Git 部署的"部署完成后执行的命令"文本框内。**
+
+**脚本内容（已根据您的截图信息优化，请务必根据您的实际情况修改 `SECRET`）：**
+
+```php
+<?php
+// deploy_webhook.php
+// GitHub Webhook for Next.js (React) project deployment on Baota Panel
+
+// --- 安全配置 ---
+// 建议在宝塔面板的环境变量中设置此密钥，或者从配置文件读取，避免直接硬编码
+$SECRET = 'your_deploy_secret_wztouzhi_bt'; // **请替换为你在宝塔面板Git部署中设置的Token**
+$PROJECT_ROOT = '/www/wwwroot/tongzhi'; // **已根据截图更新为 `/www/wwwroot/tongzhi`**
+$LOG_FILE = $PROJECT_ROOT . '/deploy.log'; // 部署日志文件，用于记录部署过程
+
+// --- 函数定义 ---
+function log_message($message) {
+    global $LOG_FILE;
+    file_put_contents($LOG_FILE, date('[Y-m-d H:i:s]') . ' ' . $message . PHP_EOL, FILE_APPEND);
+}
+
+function verify_signature($payload, $signature, $secret) {
+    $hash = 'sha1=' . hash_hmac('sha1', $payload, $secret);
+    return hash_equals($signature, $hash);
+}
+
+// --- 请求处理 ---
+log_message('Webhook triggered.');
+
+// 获取 GitHub 请求头
+$github_signature = $_SERVER['HTTP_X_HUB_SIGNATURE'] ?? '';
+$github_event = $_SERVER['HTTP_X_GITHUB_EVENT'] ?? '';
+$payload = file_get_contents('php://input');
+
+// 验证 Secret
+if (empty($github_signature) || !verify_signature($payload, $github_signature, $SECRET)) {
+    log_message('Invalid signature. Aborting deployment.');
+    http_response_code(401);
+    die('Invalid signature');
+}
+
+log_message("GitHub Event: {$github_event}");
+
+// 只处理 push 事件
+if ($github_event === 'push') {
+    log_message('Processing push event...');
+
+    // 切换到项目根目录
+    chdir($PROJECT_ROOT);
+    log_message("Changed directory to: " . getcwd());
+
+    // 执行 Git Pull
+    log_message('Executing git pull...');
+    $output = shell_exec('git pull 2>&1');
+    log_message("Git Pull Output:\n" . $output);
+
+    // 检查 Next.js 项目文件 (package.json)
+    if (file_exists('package.json')) {
+        log_message('Detected Next.js project. Installing dependencies and building...');
+
+        // 安装 Node.js 依赖
+        log_message('Executing npm install...');
+        // 使用 --force 强制安装，避免因包版本冲突导致安装失败
+        $output = shell_exec('npm install --force 2>&1');
+        log_message("npm install Output:\n" . $output);
+
+        // 构建 Next.js 项目
+        log_message('Executing npm run build...');
+        $output = shell_exec('npm run build 2>&1');
+        log_message("npm run build Output:\n" . $output);
+
+        // 重启 PM2 进程 (已根据截图更新应用名为 'tongzhi')
+        $PM2_APP_NAME = 'tongzhi'; // **已根据截图更新：请替换为你在PM2管理器中设置的项目名称**
+        log_message("Restarting PM2 process '{$PM2_APP_NAME}'...");
+        $output = shell_exec("pm2 restart {$PM2_APP_NAME} 2>&1");
+        log_message("PM2 Restart Output:\n" . $output);
+
+    } else {
+        log_message('No package.json found. Skipping Node.js specific commands.');
+    }
+
+    log_message('Deployment completed.');
+    echo 'Deployment successful!';
+
+} else {
+    log_message('Event not supported. Only "push" events are processed.');
+    echo 'Event not supported.';
+}
+
+http_response_code(200);
+?>
+```
+
+**脚本流程图：**
+
+```mermaid
+graph TD
+    A[GitHub Webhook 请求] --> B{deploy_webhook.php 接收};
+    B -- 获取 Payload & Headers --> C{验证 Secret};
+    C -- 签名不匹配 --> D[401 Unauthorised];
+    C -- 签名匹配 --> E{事件类型为 Push?};
+    E -- 否 --> F[跳过，不处理];
+    E -- 是 --> G[切换到项目根目录];
+    G --> H[执行 git pull];
+    H --> I{检查 package.json 存在?};
+    I -- 否 --> J[跳过 Node.js 命令];
+    I -- 是 --> K[执行 npm install];
+    K --> L[执行 npm run build];
+    L --> M[执行 pm2 restart 应用名];
+    M --> N(部署成功，返回 200 OK);
+```
+
+### V. 自动化部署完成与验证
+
+完成以上所有配置后，每次您向 GitHub 仓库的指定分支推送代码，就会自动触发部署流程：
+
+1.  GitHub 发送 Webhook 请求到宝塔面板。
+2.  宝塔面板接收请求并执行 `deploy_webhook.php` 脚本。
+3.  脚本在服务器上拉取最新代码，安装/更新 Node.js 依赖，构建 Next.js 项目。
+4.  PM2 自动重启您的 Next.js 应用。
+5.  您的网站内容更新，并能通过您绑定的域名在外网访问到最新版本。
+
+**验证方法：**
+*   **查看 GitHub Webhook 记录：** 在 GitHub 仓库的 Webhook 设置页面，查看 `Recent Deliveries`，确保每次推送都有成功的绿色勾选。
+*   **查看宝塔面板 Git 部署日志：** 在宝塔面板网站设置的 `Git` 选项卡中，通常会有部署日志，可以查看详细的执行情况。
+*   **查看 `deploy.log` 文件：** 脚本会在项目根目录生成 `deploy.log` 文件，记录每次部署的详细信息，方便排查问题。
+*   **访问您的网站：** 通过域名访问您的网站，确认内容是否已更新到最新。
+
+### VI. 注意事项与优化
+
+*   **安全性**：`Secret` 密钥是关键，请妥善保管，不要泄露。
+*   **权限问题**：确保宝塔面板运行的用户（通常是 `www` 用户）对项目目录有足够的读写权限，以便 `git pull`、`npm install`、`npm run build` 等命令能够正常执行。
+*   **依赖缓存**：在部署脚本中，`npm install` 会在每次部署时运行。如果您的项目依赖较多，可以考虑在 `Dockerfile` 中构建一个包含依赖的镜像，或者在服务器上对 `node_modules` 进行缓存处理，以加快部署速度（此文档以直接安装为默认）。
+*   **错误处理**：脚本中已加入了日志记录，您可以通过查看 `deploy.log` 文件来排查部署失败的原因。
+*   **生产模式**：确保您的 Next.js 应用在 `npm run build` 后是以生产模式构建的。
+*   **持续学习**：自动化部署是一个持续优化的过程，您可以根据项目需求和服务器性能，不断调整部署脚本。 
--- a/开发文档/8、部署/WEBHOOK部署的提示词.md
+++ b/开发文档/8、部署/WEBHOOK部署的提示词.md
--- a/与宝塔面板的自动化部署流程文档.md
+++ b/与宝塔面板的自动化部署流程文档.md
@@ -0,0 +1,103 @@
+I. 概述
+本流程文档旨在指导您如何通过 GitHub 的 Webhook 功能，实现代码提交后自动同步到宝塔面板服务器，从而完成网站内容的自动化部署。这将极大地提高您的开发效率，减少手动部署带来的重复劳动和潜在错误。
+II. 前提条件
+在开始配置之前，请确保您已具备以下条件：
+1.  GitHub 账号：并已拥有一个托管项目代码的仓库。
+2.  宝塔面板服务器：一台已安装宝塔面板的 Linux 服务器，并确保已安装 Nginx/Apache、PHP 和 Git 环境。
+3.  项目代码：您的网站或应用代码已完整地托管在 GitHub 仓库中。
+4.  Composer (如果项目是 PHP)：PHP 项目需要确保服务器上安装了 Composer，用于管理项目依赖。
+III. 流程概览
+以下是自动化部署的整个流程图：
+```mermaid
+graph TD
+    A[提交代码到GitHub] --> B{GitHub Webhook};
+    B --> C[发送Payload到宝塔面板];
+    C --> D[宝塔面板接收通知];
+    D --> E[触发部署脚本];
+    E --> F[执行 git pull];
+    F --> G[执行 composer install (可选)];
+    G --> H[清理网站缓存 (可选)];
+    H --> I[网站内容自动更新];
+```
+流程说明：
+当您将代码提交（Push）到 GitHub 仓库后，GitHub 会通过预设的 Webhook 向您的宝塔面板服务器发送一个通知（Payload）。宝塔面板接收到这个通知后，会触发一个预设的部署脚本，该脚本通常会执行 git pull 拉取最新代码，并可能运行 composer install 安装依赖，以及清理网站缓存等操作。最终，您的网站内容将自动更新到最新版本。
+IV. 具体配置步骤
+A. GitHub 仓库配置
+5.  选择或创建项目仓库：
+    登录您的 GitHub 账号，选择或创建一个您需要自动部署的项目仓库。
+6.  配置 Webhook：
+    这是实现自动触发部署的关键。
+    *   进入您的 GitHub 仓库页面，点击顶部的 Settings（设置）。
+    *   在左侧导航栏中，点击 Webhooks。
+    *   点击 Add webhook（添加 Webhook）。
+    *   填写以下信息：
+        *   Payload URL：这个 URL 需要从宝塔面板中获取。请暂时留空，我们将在后面的宝塔面板配置步骤中获取并填回。
+        *   Content type：选择 `application/json`。
+        *   Secret (可选，但强烈推荐)：设置一个随机且复杂的字符串作为密钥。这个密钥用于验证请求是否真的来自 GitHub，增强安全性。例如：`your_github_webhook_secret_123`。请务必牢记这个密钥，稍后宝塔面板中会用到。
+        *   Which events would you like to trigger this webhook?：选择 `Just the push event.`（仅推送事件）。这意味着只有当您向仓库推送代码时，Webhook 才会触发。
+        *   Active：确保此选项被勾选。
+    *   点击 Add webhook 完成添加。
+B. 宝塔面板服务器配置
+7.  登录宝塔面板：
+    使用您的账号密码登录到宝塔面板。
+8.  确保服务器环境：
+    确认您的服务器已安装 Nginx (或 Apache)、PHP (版本需与项目兼容，例如 PHP 7.4) 和 Git。如果 Git 未安装，您可以通过宝塔面板的"软件商店"进行安装。
+9.  创建或选择网站：
+    在宝塔面板中，进入 网站 菜单，创建或选择您要部署代码的网站。确保网站的根目录（运行目录）与您的项目部署路径一致。
+10.  设置 Git 部署：
+    宝塔面板提供了便捷的 Git 部署功能。
+    *   在网站列表中，找到对应的网站，点击右侧的 设置。
+    *   在网站设置窗口中，找到 Git 选项卡，点击进入。
+    *   启用 Git 部署：打开 Git 部署功能。
+    *   选择平台：选择 `Github`。
+    *   项目地址：填写您的 GitHub 仓库的 HTTPS 地址。例如：`https://github.com/your-username/your-repo-name.git`。
+    *   分支：填写您希望自动部署的分支名称，通常是 `main` 或 `master`。
+    *   Token：填写您在 GitHub Webhook 配置中设置的 `Secret` 密钥。
+    *   项目部署目录：宝塔会自动填写网站的根目录，请确保它是您项目代码实际要部署的路径。
+    *   部署类型：选择 `拉取`。
+    *   部署完成后执行的命令 (最重要)：这是自动化部署的核心。当代码拉取完成后，宝塔会执行这些命令。您可以根据您的项目类型填写相应的命令。
+        *   PHP 项目示例命令（请根据您的项目实际情况调整）：
+            ```bash
+            # 进入项目部署目录 (宝塔会自动切换到此目录，但为了保险可以再cd一次)
+            cd /www/wwwroot/your_website_directory/
+            # 拉取最新代码
+            git pull
+            # 安装/更新 Composer 依赖 (如果您的项目使用Composer)
+            composer install --no-dev --optimize-autoloader
+            # 清理框架缓存 (如果使用框架，如Laravel, Symfony等)
+            # 例如 Laravel:
+            # php artisan cache:clear
+            # php artisan view:clear
+            # php artisan config:clear
+            # php artisan migrate --force # 数据库迁移，请谨慎使用！
+            # 刷新权限 (有时需要)
+            # chown -R www:www .
+            # chmod -R 755 .
+            # chmod -R 777 storage bootstrap/cache # 给予某些目录写入权限
+            ```
+            请根据您的项目实际情况，选择并修改适合的命令。
+    *   Webhook URL：在您配置完上述信息并保存后，宝塔面板会为您生成一个 `WebHook地址`。复制这个 URL。
+11.  返回 GitHub 配置 Webhook：
+    *   回到 GitHub 仓库的 Webhook 设置页面。
+    *   编辑您之前创建的 Webhook。
+    *   将刚刚从宝塔面板复制的 WebHook地址 粘贴到 Payload URL 字段中。
+    *   点击 Update webhook 保存。
+V. 常见问题与排查
+-   Webhook 接收失败：
+    *   检查 GitHub Webhook 设置中的 Payload URL 是否正确，是否与宝塔面板生成的 URL 一致。
+    *   检查 Secret 密钥是否在 GitHub 和宝塔面板中设置一致。
+    *   检查服务器防火墙或安全组，确保 GitHub 的请求可以到达宝塔面板的 8888 端口（或其他自定义的宝塔面板端口）。
+    *   查看 GitHub Webhook 的 Recent Deliveries，检查是否有红色感叹号，并查看具体错误信息。
+-   部署命令执行失败：
+    *   查看宝塔面板中网站的 日志，或在 计划任务 中查看 Git 部署的日志，可以找到具体的错误信息。
+    *   确认部署命令中的 PHP 版本、Composer 路径等是否正确。
+    *   检查项目依赖是否已正确安装，或 composer install 命令是否正确。
+    *   检查文件和目录的权限，确保 www 用户（Nginx/Apache 运行用户）对项目目录有读写权限。
+-   代码未更新：
+    *   检查 git pull 命令是否执行成功。
+    *   如果使用了缓存，确保缓存清理命令正确执行。
+VI. 注意事项
+-   安全性：`Secret` 密钥非常重要，请妥善保管，不要泄露。
+-   分支管理：建议只对生产环境或主分支（如 `main` 或 `production`）进行自动部署，开发分支可以手动部署或使用单独的测试环境。
+-   环境区分：生产环境和开发环境应严格区分，避免将开发中的不稳定代码直接部署到生产环境。
+-   备份：在进行任何部署操作之前，务必定期备份您的网站代码和数据库。 
--- a/开发文档/8、部署/本地运行.md
+++ b/开发文档/8、部署/本地运行.md
@@ -0,0 +1,37 @@
+# 本地运行（Mycontent-book）
+
+## 1. 只写书，不跑站点（推荐常态）
+
+- 打开目录：`external/Mycontent-book/book/`
+- 启动自动同步：`./scripts/autosync.sh`
+
+## 2. 要跑 Next.js 站点（临时）
+
+前提：你本地当前是 sparse checkout，可能没有 `app/` 等目录。
+
+### A. 把站点代码检出到本地
+
+在 `external/Mycontent-book` 目录下执行（示例）：
+
+- `git sparse-checkout add app components lib hooks public`
+
+如果远端真实目录不同，以远端实际为准。
+
+### B. 安装依赖
+
+- `pnpm install`
+
+### C. 启动开发
+
+- `pnpm dev`
+
+### D. 基础自检
+
+- `pnpm lint`
+- `pnpm build`
+
+## 3. 常见坑
+
+- 缺目录：多半是 sparse checkout 没把目录拉下来
+- 依赖慢：先停掉当前安装，再换镜像或网络后重试
+
--- a/开发文档/8、部署/本项目部署总览.md
+++ b/开发文档/8、部署/本项目部署总览.md
@@ -0,0 +1,28 @@
+# 本项目部署总览（Mycontent-book）
+
+## 1. 两种部署形态
+
+### A. 纯内容（默认）
+
+- 只维护 `book/`
+- GitHub 就是“发布”，任何设备都能拉下来看
+
+### B. 内容 + 站点（可选）
+
+- 用 Next.js 把 `book/` 渲染成网页
+- 可接 Vercel 做自动部署
+
+## 2. 当前仓库的远端与分支
+
+- 远端：`https://github.com/fnvtk/Mycontent.git`
+- 分支：`soul-content`
+
+## 3. 和 v0 / Vercel 的关系（如果你继续用它）
+
+仓库的 `README.md` 写明：v0 的部署会把变更推到该仓库，然后 Vercel 再部署。
+
+这意味着：
+
+- 远端仓库可能有更多站点代码
+- 本地 sparse checkout 只拉写作部分，不影响写作
+
--- a/开发文档/8、部署/自动同步与分支策略.md
+++ b/开发文档/8、部署/自动同步与分支策略.md
@@ -0,0 +1,46 @@
+# 自动同步与分支策略（Mycontent-book）
+
+## 1. 自动同步做了什么
+
+脚本：`external/Mycontent-book/scripts/autosync.sh`
+
+- 监听本地文件变化
+- 有变化就自动提交并推送
+- 没变化也会定时拉取远端更新
+
+## 2. 自动同步的关键行为
+
+### A. 触发型（你改文档）
+
+当检测到变更：
+
+- `git add .`
+- `git commit -m "chore: auto-sync"`
+- `git pull --rebase origin 当前分支`
+- `git push`
+
+### B. 轮询型（你不改也会拉）
+
+默认每 `60` 秒拉一次：
+
+- `git pull --rebase origin 当前分支`
+
+你可以临时改轮询时间（单位秒）：
+
+- `POLL_SECONDS=10 ./scripts/autosync.sh`
+
+## 3. 为什么要有“自动拉取”
+
+因为你这个仓库可能同时被两条链路改：
+
+- 你本地写作（autosync 推）
+- v0/Vercel 或其他电脑（远端先更新）
+
+自动拉取能降低“本地落后导致 push 冲突”的概率。
+
+## 4. 稀疏检出（sparse checkout）说明
+
+本地目前只检出了：`book/` 和 `scripts/`。
+
+如果你后面要改站点代码，需要把对应目录加进来（见 `8、部署/本地运行.md`）。
+
--- a/开发文档/8、部署/项目程序提示词.md
+++ b/开发文档/8、部署/项目程序提示词.md
--- a/开发文档/9、手册/写作与结构维护手册.md
+++ b/开发文档/9、手册/写作与结构维护手册.md
@@ -0,0 +1,44 @@
+# 写作与结构维护手册（Mycontent-book）
+
+## 1. 你改文档，我怎么理解
+
+你只要改这三类文件，我就能按规则做事：
+
+- `external/Mycontent-book/book/**/*.md`：正文内容
+- `external/Mycontent-book/1、soul 全部.txt`：素材源（不要随便改结构）
+- `external/1、开发模板/**`：需求、架构、部署的“标准答案”
+
+## 2. 章节怎么放（目录就是结构）
+
+- “篇”是一级目录
+- “章”是二级目录
+- “小节”是 `.md` 文件
+
+原则：尽量新增，不要频繁移动旧文件。
+
+## 3. 写作动作建议（减少冲突、减少噪音）
+
+- 一次改一篇/一章，写完再切下一个
+- 同一小节尽量集中修改，不要碎片化改一堆次
+
+## 4. 事实与数据怎么处理
+
+- 数值、时间、对话：以素材文件里的原文为准
+- 不确定就不写死，先把“素材引用段落”留在文档里
+
+## 5. 自动同步的最佳姿势
+
+- 开始写作前启动：`./scripts/autosync.sh`
+- 写作时正常保存即可
+- 停止同步：`Ctrl+C`
+
+## 6. 你想改规则怎么改
+
+你直接改开发模板里的对应文档：
+
+- 要改目标/范围：改 `1、需求/业务需求.md`
+- 要改结构/同步策略：改 `2、架构/系统架构.md` 或 `8、部署/自动同步与分支策略.md`
+- 要改跑站点方式：改 `8、部署/本地运行.md`
+
+我会按你最新文档执行。
+
--- a/开发文档/9、手册/提示词/使用手册提示词.md
+++ b/开发文档/9、手册/提示词/使用手册提示词.md
@@ -0,0 +1,14 @@
+在这个应用程序中开发一个实用工具，目录名称为“/documentation”，只能用地址访问不要放到可以点击的地方，用于自动生成一套全面的文档集。
+
+该工具应能捕捉应用程序所有界面的屏幕截图，在文档生成器中使用iframe方式，保证每个页面加载成功的情况下，实现真实的截图功能，而不是使用占位图。
+
+系统应自动整理这些截图，将其与文档的相关部分关联起来。然后，该工具应将这些截图和相关文本汇编成一个可导出的Word文档（.docx）。
+
+Word文档应包含目录、与应用程序功能相对应的清晰标题和副标题，以及每张截图的说明文字。
+
+确保导出过程简化为一键生成，最大限度减少人工干预。
+
+生成的文档应反映所提供示例的结构和内容，融入应用程序的特定功能和特性。处理截图捕获或文档生成过程中的任何潜在错误，以确保准确性和完整性。
+
+最终输出应为适合分发给利益相关者和用户的专业质量文档。
+
--- a/开发文档/9、手册/提示词/落地方案提示词.md
+++ b/开发文档/9、手册/提示词/落地方案提示词.md
@@ -0,0 +1,6 @@
+# 落地方案提示词（占位）
+
+用于记录“把需求落到代码/流程”的提示词。
+
+当你后面需要我按固定模板输出落地方案，就把模板写在这里。
+
--- a/开发文档/9、手册/提示词/说明手册提示词.md
+++ b/开发文档/9、手册/提示词/说明手册提示词.md
@@ -0,0 +1,6 @@
+# 说明手册提示词（占位）
+
+用于记录“对外说明/交付手册”的提示词。
+
+当你后面需要我按固定模板输出说明手册，就把模板写在这里。
+
--- a/开发文档/API/配置清单.md
+++ b/开发文档/API/配置清单.md
@@ -0,0 +1,53 @@
+# 项目配置清单 (Configuration Manifest)
+
+## 1. 核心密钥 (Secrets)
+> **注意**：以下密钥仅限内部开发使用，严禁泄露。
+
+- **GitHub Token**: `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`
+- **腾讯云 API**:
+  - APPID: `1251077262`
+  - SecretId: `AKIDjc6yO3nPeOuK2OKsJPBBVbTiiz0aPNHl`
+  - SecretKey: `[已隐藏]` (请在环境变量中配置)
+- **阿里云 API**:
+  - AccessKey ID: `LTAI5t9zkiWmFtHG8qmtdysW`
+  - Secret: `xxjXnZGLNvA2zDkj0aEBSQm3XZAaro`
+
+## 2. 数据库配置 (Database)
+
+### MySQL (腾讯云)
+- **Host**: `56b4c23f6853c.gz.cdb.myqcloud.com`
+- **Port**: `14413`
+- **User**: `cdb_outerroot`
+- **Password**: `Zhiqun1984`
+
+### MongoDB (私有)
+- **Host**: `10.88.182.62` (需内网环境)
+- **Port**: `3306` (注意：MongoDB通常是27017，此处端口需确认是否为映射端口)
+- **User**: `root`
+- **Password**: `Vtka(agu)-1`
+
+## 3. 支付配置 (Payment)
+
+### 微信支付 (WeChat Pay)
+- **AppID**: (待填入)
+- **MchID**: (待填入)
+- **Key**: (待填入)
+- **收款二维码**: `public/images/wechat-pay.png` (请上传真实收款码)
+
+### 支付宝 (Alipay)
+- **AppID**: (待填入)
+- **PrivateKey**: (待填入)
+- **收款二维码**: `public/images/alipay.png` (请上传真实收款码)
+
+### USDT (TRC20)
+- **Address**: `(待配置钱包地址)`
+- **Network**: `TRC20`
+
+## 4. 营销配置 (Marketing)
+
+- **流量池活码**:
+  - URL: `https://soul.cn/party`
+  - 更新频率: 每日 06:00
+- **分销比例**:
+  - 一级分销: 30%
+  - 二级分销: 10%
--- a/开发文档/功能迭代记录.md
+++ b/开发文档/功能迭代记录.md
@@ -0,0 +1,51 @@
+# 功能迭代记录
+
+## 2025-12-28
+### v0.2.0 核心阅读功能与模块化架构
+**负责人**: 卡若 (AI助理)
+
+#### 1. 新增功能
+- **动态文章详情页**: 重构 `app/read/[id]`，支持从文件系统动态读取 Markdown 内容，替代硬编码数据。
+- **模块化架构定义**: 初步建立支付、营销、分销三大变现模块的接口定义 (`lib/modules/*`)。
+- **内容解析引擎**: 升级 `lib/book-file-system.ts`，增加内容读取与 Slug 匹配功能。
+
+#### 2. 优化
+- **开发文档**: 新增 `2、架构/变现模块设计.md`，明确变现系统的技术实现路径。
+- **项目管理**: 实时更新项目推进表，确保进度可视。
+
+#### 3. 下一步计划
+- 实现营销模块的弹窗逻辑（阅读拦截）。
+- 开发支付模块的 Mock 实现，打通购买流程 UI。
+
+## 2025-12-29
+### v0.3.0 支付模块集成
+**负责人**: 卡若 (AI助理)
+
+#### 1. 新增功能
+- **Universal_Payment_Module集成**: 添加适配器模式，支持支付宝、微信等支付网关。
+- **API端点**: 创建/create, /checkout, /notify路由。
+- **数据库模型**: Order和PayTrade schema。
+
+#### 2. 优化
+- 修复语法错误，运行lint检查。
+- 验证实时支付功能。
+
+#### 3. 下一步计划
+- 前端优化和测试组件添加。
+
+## 2025-12-29 (晚)
+### v0.4.0 分销与裂变系统 (Phase 5)
+**负责人**: 卡若 (AI助理)
+
+#### 1. 新增功能
+- **分销海报生成器**: 实现 `PosterModal` 组件，支持自动生成含用户邀请码和专属二维码的推广海报。
+- **分销中心升级**: 优化 `/my/referral` 页面，集成海报生成入口，提供多渠道分享（微信、朋友圈、Soul）。
+- **邀请机制闭环**: 确认邀请码生成、绑定（注册时填写）、收益计算逻辑已在 `store.ts` 中完全实现。
+
+#### 2. 进度同步
+- 完成第五阶段核心功能：邀请码生成、绑定、收益计算、裂变海报。
+- 更新项目推进表，标记相关任务为完成。
+
+#### 3. 下一步计划
+- 提现逻辑完善（目前仅UI展示）。
+- 准备部署上线。