diff --git a/开发文档 b/开发文档 deleted file mode 160000 index 28f5a09..0000000 --- a/开发文档 +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 28f5a094a6b3bc4cdce4fcfd7b805f64367b7f89 diff --git a/开发文档/.github/workflows/sync_from_coding.yml b/开发文档/.github/workflows/sync_from_coding.yml new file mode 100644 index 0000000..a52398b --- /dev/null +++ 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 \ No newline at end of file diff --git a/开发文档/0、Mycontent-book 项目总览.md b/开发文档/0、Mycontent-book 项目总览.md new file mode 100644 index 0000000..124dbc4 --- /dev/null +++ b/开发文档/0、Mycontent-book 项目总览.md @@ -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。这一步步来，别贪多。 diff --git a/开发文档/10、项目管理/项目落地推进表.md b/开发文档/10、项目管理/项目落地推进表.md new file mode 100644 index 0000000..8ba3f0a --- /dev/null +++ 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%（第四阶段） + +（此处省略旧记录） diff --git a/开发文档/1、需求/业务需求.md b/开发文档/1、需求/业务需求.md new file mode 100644 index 0000000..f2f8102 --- /dev/null +++ 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. **在线评论**: 没精力管杠精。想喷我？加微信私聊喷。 + +--- +**卡若说：** +生意逻辑很简单：**内容是饵，私域是鱼塘，产品是网。** 这个系统就是那根鱼竿。 diff --git a/开发文档/1、需求/成本.md b/开发文档/1、需求/成本.md new file mode 100644 index 0000000..3792625 --- /dev/null +++ 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. **人力外包**: 重复性的切图工作，丢给兼职做；核心架构我自己把控。 + +--- +**卡若说：** +省下来的每一分钱，都是纯利润。 diff --git a/开发文档/1、需求/技术需求.md b/开发文档/1、需求/技术需求.md new file mode 100644 index 0000000..e5a758a --- /dev/null +++ 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。 + +--- +**卡若说：** +技术不用最牛的，要用最稳的。把地基打牢，楼才能盖高。 diff --git a/开发文档/2、架构/前后端架构分离策略.md b/开发文档/2、架构/前后端架构分离策略.md new file mode 100644 index 0000000..71307be --- /dev/null +++ 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%。效率就是这么抠出来的。 diff --git a/开发文档/2、架构/变现模块设计.md b/开发文档/2、架构/变现模块设计.md new file mode 100644 index 0000000..ad7a63c --- /dev/null +++ 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/ +``` diff --git a/开发文档/2、架构/技术选型与全景图.md b/开发文档/2、架构/技术选型与全景图.md new file mode 100644 index 0000000..61738b0 --- /dev/null +++ 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。 + +--- +**卡若说：** +技术选型没有“最好”，只有“最合适”。这一套架构，扛个百万日活没问题，够我们折腾好几年了。 diff --git a/开发文档/2、架构/数据库.md b/开发文档/2、架构/数据库.md new file mode 100644 index 0000000..61b4da6 --- /dev/null +++ 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`：编辑标注与写作计划 + diff --git a/开发文档/2、架构/系统架构.md b/开发文档/2、架构/系统架构.md new file mode 100644 index 0000000..881be5a --- /dev/null +++ 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 里解决的，就别拆微服务。 diff --git a/开发文档/3、前端/前端架构.md b/开发文档/3、前端/前端架构.md new file mode 100644 index 0000000..2ff90d3 --- /dev/null +++ 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 两个尺寸测。 +- [ ] 优化字体栈，确保在安卓上也不难看。 + +--- +**总结**： +前端不仅是写代码，是**做产品**。每一个像素的偏移都影响用户的信任感。把细节抠好，转化率自然就高了。 diff --git a/开发文档/4、后端/后端架构.md b/开发文档/4、后端/后端架构.md new file mode 100644 index 0000000..ae96fb7 --- /dev/null +++ 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 { + 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 队列里异步处理。 + +--- +**卡若说：** +后端代码要写得像瑞士军刀一样，功能明确，结实耐用。 diff --git a/开发文档/5、接口/API接口.md b/开发文档/5、接口/API接口.md new file mode 100644 index 0000000..64c6d2d --- /dev/null +++ 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 ` +- **Body**: `{ "format": "docx" }` +- **Response**: Binary Stream (文件下载) + +--- +**卡若说：** +接口越少越好，参数越简单越好。 diff --git a/开发文档/6、数据库/数据库设计.md b/开发文档/6、数据库/数据库设计.md new file mode 100644 index 0000000..a50d548 --- /dev/null +++ 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。 + +--- +**卡若说：** +数据结构定好了，业务逻辑就跑偏不了。 diff --git a/开发文档/7、测试/测试策略.md b/开发文档/7、测试/测试策略.md new file mode 100644 index 0000000..52bba20 --- /dev/null +++ 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 以内吗？ +- [ ] 所有的图片都加载出来了吗？ +- [ ] 在微信里打开链接，分享卡片正常吗？ + +--- +**行动：** +别迷信自动化。在你没钱雇测试之前，你自己就是最好的测试员。哪怕代码写得再烂，只要用户用着爽，就是好代码。 diff --git a/开发文档/8、部署/Next.js自动化部署流程.md b/开发文档/8、部署/Next.js自动化部署流程.md new file mode 100644 index 0000000..b75d998 --- /dev/null +++ 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[自动部署脚本:
git pull
npm install
npm run build
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 +&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` 后是以生产模式构建的。 +* **持续学习**：自动化部署是一个持续优化的过程，您可以根据项目需求和服务器性能，不断调整部署脚本。 \ No newline at end of file diff --git a/开发文档/8、部署/WEBHOOK部署的提示词.md b/开发文档/8、部署/WEBHOOK部署的提示词.md new file mode 100644 index 0000000..e69de29 diff --git a/开发文档/8、部署/基于 GitHub Webhook 与宝塔面板的自动化部署流程文档.md b/开发文档/8、部署/基于 GitHub Webhook 与宝塔面板的自动化部署流程文档.md new file mode 100644 index 0000000..abd4020 --- /dev/null +++ b/开发文档/8、部署/基于 GitHub Webhook 与宝塔面板的自动化部署流程文档.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`）进行自动部署，开发分支可以手动部署或使用单独的测试环境。 +- 环境区分：生产环境和开发环境应严格区分，避免将开发中的不稳定代码直接部署到生产环境。 +- 备份：在进行任何部署操作之前，务必定期备份您的网站代码和数据库。 \ No newline at end of file diff --git a/开发文档/8、部署/本地运行.md b/开发文档/8、部署/本地运行.md new file mode 100644 index 0000000..286058f --- /dev/null +++ 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 没把目录拉下来 +- 依赖慢：先停掉当前安装，再换镜像或网络后重试 + diff --git a/开发文档/8、部署/本项目部署总览.md b/开发文档/8、部署/本项目部署总览.md new file mode 100644 index 0000000..6062547 --- /dev/null +++ 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 只拉写作部分，不影响写作 + diff --git a/开发文档/8、部署/自动同步与分支策略.md b/开发文档/8、部署/自动同步与分支策略.md new file mode 100644 index 0000000..8b698ff --- /dev/null +++ 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`）。 + diff --git a/开发文档/8、部署/项目程序提示词.md b/开发文档/8、部署/项目程序提示词.md new file mode 100644 index 0000000..e69de29 diff --git a/开发文档/9、手册/写作与结构维护手册.md b/开发文档/9、手册/写作与结构维护手册.md new file mode 100644 index 0000000..1d679ee --- /dev/null +++ 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` + +我会按你最新文档执行。 + diff --git a/开发文档/9、手册/提示词/使用手册提示词.md b/开发文档/9、手册/提示词/使用手册提示词.md new file mode 100644 index 0000000..358ad48 --- /dev/null +++ b/开发文档/9、手册/提示词/使用手册提示词.md @@ -0,0 +1,14 @@ +在这个应用程序中开发一个实用工具，目录名称为“/documentation”，只能用地址访问不要放到可以点击的地方，用于自动生成一套全面的文档集。 + +该工具应能捕捉应用程序所有界面的屏幕截图，在文档生成器中使用iframe方式，保证每个页面加载成功的情况下，实现真实的截图功能，而不是使用占位图。 + +系统应自动整理这些截图，将其与文档的相关部分关联起来。然后，该工具应将这些截图和相关文本汇编成一个可导出的Word文档（.docx）。 + +Word文档应包含目录、与应用程序功能相对应的清晰标题和副标题，以及每张截图的说明文字。 + +确保导出过程简化为一键生成，最大限度减少人工干预。 + +生成的文档应反映所提供示例的结构和内容，融入应用程序的特定功能和特性。处理截图捕获或文档生成过程中的任何潜在错误，以确保准确性和完整性。 + +最终输出应为适合分发给利益相关者和用户的专业质量文档。 + diff --git a/开发文档/9、手册/提示词/落地方案提示词.md b/开发文档/9、手册/提示词/落地方案提示词.md new file mode 100644 index 0000000..70f0bf2 --- /dev/null +++ b/开发文档/9、手册/提示词/落地方案提示词.md @@ -0,0 +1,6 @@ +# 落地方案提示词（占位） + +用于记录“把需求落到代码/流程”的提示词。 + +当你后面需要我按固定模板输出落地方案，就把模板写在这里。 + diff --git a/开发文档/9、手册/提示词/说明手册提示词.md b/开发文档/9、手册/提示词/说明手册提示词.md new file mode 100644 index 0000000..1e6f457 --- /dev/null +++ b/开发文档/9、手册/提示词/说明手册提示词.md @@ -0,0 +1,6 @@ +# 说明手册提示词（占位） + +用于记录“对外说明/交付手册”的提示词。 + +当你后面需要我按固定模板输出说明手册，就把模板写在这里。 + diff --git a/开发文档/API/配置清单.md b/开发文档/API/配置清单.md new file mode 100644 index 0000000..2c379e9 --- /dev/null +++ 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% diff --git a/开发文档/功能迭代记录.md b/开发文档/功能迭代记录.md new file mode 100644 index 0000000..a0858db --- /dev/null +++ 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展示）。 +- 准备部署上线。