diff --git a/开发文档/10、项目管理/0、Mycontent-book 项目总览.md b/开发文档/10、项目管理/0、Mycontent-book 项目总览.md deleted file mode 100644 index 00d84e25..00000000 --- a/开发文档/10、项目管理/0、Mycontent-book 项目总览.md +++ /dev/null @@ -1,99 +0,0 @@ -# Mycontent-book 项目总览 - -**我是卡若。** - -做这个项目，逻辑很简单：**把书卖出去，把私域做起来，把钱分下去。** - -这就不是一个普通的博客网站，这是一个**内容变现系统**。所有的技术架构，都要围绕着“阅读体验”、“流量承接”和“变现转化”来做。 - -别整那些虚头巴脑的概念，咱们直接看这个盘子怎么搭。 - -## 1. 核心逻辑 - -这个项目的生意逻辑就是三层： -1. **流量层（前端）**：让用户看着爽，像刷抖音、看公众号一样流畅。必须移动端优先，模拟 iOS 的原生质感。 -2. **内容层（数据）**：`book/` 目录下的 Markdown 文件就是我们的资产。改个字，推送到 GitHub，网站立马更新。 -3. **变现层（后端/接口）**：谁看了？谁买了？谁推荐的？这些数据要跑通。 - -## 2. 为什么这么架构？ - -我选 Next.js，不是因为流行，是因为它**省事**。 -- **SSR（服务端渲染）**：SEO 友好，百度谷歌能搜到，自带流量。 -- **API Routes**：不用单独起个 Java 或 Python 服务，省服务器钱。 -- **Vercel/宝塔部署**：自动化流水线，我只管写文章，代码自动跑。 - -## 3. 当前项目结构（前后端已分离） - -### 3.1 仓库根目录 - -| 目录/项目 | 技术栈 | 说明 | -|-----------|--------|------| -| **soul-api/** | Go 1.25 + Gin + GORM + MySQL | 独立后端 API 服务，路径与现网一致 `/api/*` | -| **soul-admin/** | React 18 + Vite 6 + TypeScript + Tailwind 4 + Radix UI | 管理后台 SPA，请求通过 `VITE_API_BASE_URL` 对接 soul-api 或 Next | -| **miniprogram/** | 微信小程序原生 | C 端主阵地，用户阅读、购买、分销、提现等 | -| **next-project/** | Next.js（可选保留） | 原单体：含 `app/view/` C 端、`app/admin/` 管理端、`app/api/`；可作备用或逐步下线 | - -### 3.2 接口与前端对应关系 - -- **API 服务**：由 **soul-api**（Go）提供，端口默认 8080；路径与现网完全一致（如 `/api/user/profile`、`/api/admin/withdrawals`）。 -- **管理端**：**soul-admin** 独立部署，环境变量 `VITE_API_BASE_URL` 指向 soul-api 或 Next 的 API 基地址。 -- **小程序**：通过 `app.request()` 等封装请求 API，baseUrl 可配置，与 soul-api 对接。 -- **API 字段规范**：对外请求/响应**统一使用小写开头驼峰（camelCase）**，如 `userId`、`referralCode`、`createdAt`；数据库列名仍为 snake_case，仅在服务端内部使用。 - -## 4. 目录导航（别迷路） - -- **[1、需求](1、需求/业务需求.md)**：我们要干啥，成本多少，技术要求；[TDD 需求方案](1、需求/TDD_创业派对项目方案_v1.0.md)。 -- **[2、架构](2、架构/系统架构.md)**：整体怎么搭，前后端怎么分。 - - [技术选型与全景图](2、架构/技术选型与全景图.md)、[前后端架构分离策略](2、架构/前后端架构分离策略.md) -- **[3、原型](3、原型/原型设计规范.md)**：原型设计规范。 -- **[4、前端](4、前端/前端架构.md)**：前端架构（含 **soul-admin**、小程序）、模块详解、开发规范；[当前小程序开发细则](4、前端/当前小程序开发细则.md)；[ui 子目录](4、前端/ui/)：项目概述、页面功能、组件清单、API/状态/分销/支付/管理后台/部署说明等。 -- **[5、接口](5、接口/API接口.md)**：前后端怎么说话。 -- **[6、后端](6、后端/后端架构.md)**：**soul-api**（Go + Gin + GORM）架构与业务模块，后端开发规范。 -- **[7、数据库](7、数据库/数据库设计.md)**：数据存哪，怎么存。 -- **[8、部署](8、部署/部署总览.md)**：怎么上线、本地运行、宝塔部署、新分销部署、修复与优化记录等。 -- **[9、手册](9、手册/写作与结构维护手册.md)**：怎么写书，怎么维护。 -- **[10、项目管理](10、项目管理/项目落地推进表.md)**：项目推进与提示词。 - -## 5. 开发约束（重要） - -> **2026-02-07 更新：前后端已分离，soul-api + soul-admin 为主力** - -### 5.1 项目与开发策略 - -| 项目/端 | 路径/端口 | 开发状态 | 说明 | -|---------|-----------|----------|------| -| **soul-api** | 端口 8080 | ✅ 主力后端 | Go + Gin，提供全部 `/api/*` 接口，MySQL + GORM | -| **soul-admin** | 独立 SPA | ✅ 主力管理端 | React + Vite，通过 `VITE_API_BASE_URL` 对接 soul-api | -| **微信小程序** | `miniprogram/` | ✅ 主力 C 端 | 所有面向用户的新功能在此开发 | -| **Next.js** | `next-project/` 或原 app | 🔒 备用/冻结 | C 端 `app/view/` 冻结；`app/api/` 可作过渡或下线 | - -### 5.2 核心原则 - -1. **后端统一走 soul-api**：新接口在 soul-api 实现，路径与现网一致，响应字段统一 **camelCase**。 -2. **管理端统一走 soul-admin**：新管理功能在 soul-admin 开发，请求体与展示字段统一 **camelCase**。 -3. **小程序优先**：C 端新功能只在小程序开发，请求/响应已按 camelCase 对接。 -4. **API 契约统一**：查询、新增、编辑、删除的请求/响应字段全部小写开头驼峰（如 `userId`、`createdAt`、`referralCode`）。 - -### 5.3 登录与鉴权 - -| 端 | 登录方式 | 说明 | -|---|----------|------| -| 小程序 | 微信一键登录 / 手机号快速授权 | 与 soul-api 或 Next 的 `/api/miniprogram/login` 等对接 | -| soul-admin | 手机号 + 密码 | POST `/api/admin` 登录，GET 鉴权，Cookie/Token | -| 账号统一 | 以手机号/用户 ID 为唯一标识 | 多端数据互通 | - -### 5.4 为什么前后端分离？ - -- **独立部署与扩展**：后端 Go 可单独扩容，前端静态资源可 CDN。 -- **多端复用 API**：小程序、soul-admin、未来 App 共用同一套 soul-api。 -- **开发效率**：前后端并行、接口契约清晰（camelCase 统一）。 - -## 6. 这里的规矩 - -- **行动至上**：文档是用来指导干活的，不是写来看的。 -- **数据说话**：所有优化要有数据支撑，加载快了多少？转化高了多少？ -- **保持简单**：能用现成的库就别自己造轮子。 - ---- -**复盘：** -项目已完成前后端分离：soul-api（Go）负责接口与数据库，soul-admin（React）负责管理后台，miniprogram 负责 C 端。API 与前端字段已统一为 camelCase，便于多端对接与后续扩展。 diff --git a/开发文档/10、项目管理/soul-admin变更记录_v2026-02.md b/开发文档/10、项目管理/soul-admin变更记录_v2026-02.md deleted file mode 100644 index d44bd1df..00000000 --- a/开发文档/10、项目管理/soul-admin变更记录_v2026-02.md +++ /dev/null @@ -1,79 +0,0 @@ -# Soul 管理后台 (soul-admin) 变更记录 v2026-02 - -> 更新时间：2026-02-21 -> 适用站点：souladmin.quwanzhi.com -> 部署路径：`/www/wwwroot/自营/soul-admin/dist/` - ---- - -## 一、变更概览 - -| 模块 | 变更项 | 说明 | -|:---|:---|:---| -| 侧边栏 | 交易中心 → 推广中心 | 菜单及页面标题统一改为「推广中心」 | -| 内容管理 | 顶部 5 按钮移除 | 移除：初始化数据库、同步到数据库、导入、导出、同步飞书 | -| 内容管理 | 仅保留 API 接口 | 仅保留「API 接口」按钮，打开 API 文档面板 | -| 内容管理 | 删除按钮 | 删除按钮改为悬停才显示（与读取/编辑一致） | -| 内容管理 | 免费/付费 | 可点击切换免费 ↔ 付费 | -| 内容管理 | 小节加号 | 每小节旁增加「+」按钮，可在此小节下新建章节 | - ---- - -## 二、部署说明 - -### 2.1 正确部署路径 - -nginx 实际指向： - -```nginx -root /www/wwwroot/自营/soul-admin/dist; -``` - -**重要**：需将 `soul-admin/dist` 部署到上述目录，而非 `/www/wwwroot/souladmin.quwanzhi.com/`。 - -### 2.2 部署步骤 - -```bash -# 1. 本地打包 -cd /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/soul-admin/dist -tar -czf /tmp/souladmin.tar.gz index.html assets/ - -# 2. 上传并解压到正确路径 -scp -P 22022 /tmp/souladmin.tar.gz root@43.139.27.93:/tmp/ -ssh -p 22022 root@43.139.27.93 'cd /www/wwwroot/自营/soul-admin/dist && tar -xzf /tmp/souladmin.tar.gz && chown -R www:www . && rm /tmp/souladmin.tar.gz' -``` - -### 2.3 缓存处理 - -- `index.html` 内引用 `index-CbOmKBRd.js?v=版本号`，每次发布建议递增版本号 -- 建议在 `index.html` 中调整：`?v=3` 或更高 - ---- - -## 三、技术说明 - -### 3.1 修改文件 - -- `index.html`：内联注入脚本（按钮改造、删除 hover、免费切换、加号新建） -- `assets/index-CbOmKBRd.js`：侧边栏「交易中心」→「推广中心」 - -### 3.2 注入脚本触发条件 - -- 路径包含 `content`（如 `/content`） -- 页面上存在「初始化数据库」按钮（内容管理页加载完成） - -### 3.3 免费/付费切换 - -- 调用 `POST /api/db/book`，传入 `{ id, isFree, price }` -- 需后端支持按 id 更新 isFree/price - ---- - -## 四、问题排查 - -| 现象 | 可能原因 | 处理方式 | -|:---|:---|:---| -| 界面未变化 | 部署到错误目录 | 确认部署到 `/www/wwwroot/自营/soul-admin/dist/` | -| 界面未变化 | 浏览器/CDN 缓存 | 清除缓存或使用无痕模式，或增加 `?v=` 版本号 | -| 内容管理注入不生效 | 路由为 hash 模式 | 检查 `location.pathname` 是否包含 `content`，必要时改用 `location.hash` | -| 免费切换失败 | 后端未实现更新 | 检查 soul-api 是否支持 `POST /api/db/book` 的更新逻辑 | diff --git a/开发文档/10、项目管理/小程序接口申请文案.md b/开发文档/10、项目管理/小程序接口申请文案.md deleted file mode 100644 index 13a43e06..00000000 --- a/开发文档/10、项目管理/小程序接口申请文案.md +++ /dev/null @@ -1,97 +0,0 @@ -# 微信小程序接口申请文案（可直接复制） - -> 用于微信公众平台 → 开发管理 → 接口设置 → 接口权限 -> 每个理由控制在 300 字以内，按需复制到对应接口的「申请接口理由」框。 - ---- - -## 1. wx.chooseAddress（获取用户收货地址） - -**申请接口理由：** - -``` -本小程序为创业者社群与资源对接平台。用户在使用「找伙伴-资源对接」功能时，需填写联系地址，便于匹配成功后线下见面、寄送资料或合作签约。申请 wx.chooseAddress 后，用户可一键从微信获取已保存的收货地址，无需逐项手动输入，既保证信息真实可联系，又提升填写效率，完成从线上匹配到线下对接的闭环。 -``` - -**备选（更简短）：** - -``` -本小程序提供创业资源对接服务，用户匹配成功后需交换联系地址以便线下合作。申请此接口后，用户可一键选择微信收货地址，避免手动输入错误，提升填写效率与用户体验。 -``` - ---- - -## 2. wx.getPhoneNumber（获取用户手机号） - -**申请接口理由：** - -``` -本小程序为创业者匹配与电子书付费平台，需手机号用于：一、用户身份校验，确保真实用户；二、创业伙伴匹配成功后交换联系方式；三、分销推广收益提现时的账户校验与到账通知。申请 wx.getPhoneNumber 后，用户授权即可获取微信绑定手机号，减少手动输入，提高注册与提现流程的完成率。 -``` - -**备选（更简短）：** - -``` -本小程序涉及付费阅读与分销提现，需手机号完成身份验证与提现到账。申请此接口可实现一键获取微信绑定手机号，提升用户注册与提现流程的完成率与安全性。 -``` - ---- - -## 3. wx.chooseLocation（打开地图选择位置） - -**申请接口理由：** - -``` -本小程序提供创业者线下见面与资源对接服务。用户发布合作需求或预约见面时，需选择具体见面地点。申请 wx.chooseLocation 后，用户可在地图上选点并获取详细地址与坐标，便于双方导航赴约，完成从线上匹配到线下见面的业务闭环。 -``` - -**备选（更简短）：** - -``` -本小程序为创业资源对接平台，用户匹配成功后需约定线下见面地点。申请此接口后，用户可在地图上选择位置并获取地址，方便双方导航见面。 -``` - ---- - -## 4. wx.choosePoi（打开 POI 列表选择位置） - -**申请接口理由：** - -``` -本小程序为创业者线下对接场景服务。用户约定见面地点时，除地图选点外，还需从咖啡馆、会议室等 POI 中选择具体场所。申请 wx.choosePoi 后，用户可从附近 POI 列表中快速选择地点，便于填写规范地址并提升约见效率。 -``` - ---- - -## 5. wx.getFuzzyLocation（获取当前模糊地理位置） - -**申请接口理由：** - -``` -本小程序需根据用户所在城市推荐同城创业伙伴与线下活动，不涉及精确定位。申请 wx.getFuzzyLocation 后，仅获取城市级模糊位置用于同城匹配与活动推荐，在满足业务需求的同时符合隐私最小化原则。 -``` - ---- - -## 6. wx.getLocation（获取当前精确地理位置） - -**申请接口理由：** - -``` -本小程序提供创业者线下见面与活动报名功能。用户参加线下沙龙、路演等活动时，需获取当前位置用于：一、展示与活动地点的距离；二、推荐附近的创业活动与伙伴。申请此接口以便用户查看「离我最近」的活动与匹配结果，提升线下参与率。 -``` - -**说明：** 若类目为「商业服务-综合」等，审核可能较严，建议优先申请 wx.getFuzzyLocation，再视业务需要申请 wx.getLocation。 - ---- - -## 填写与提交建议 - -1. **申请接口理由**：从上面选一段主文案粘贴，字数不够时用「备选」补充，总长不超过 300 字。 -2. **使用场景截图**：上传小程序内实际使用该能力的页面截图（如设置页地址、匹配页选地点、提现页手机号等），每张图对应一个场景。 -3. **小程序官网链接**：可填 `https://soul.quwanzhi.com`。 -4. **一次只申请一个接口**，通过后再申请下一个，通过率更高。 - ---- - -**文档更新日期：** 2026-01-29 diff --git a/开发文档/10、项目管理/永平版优化对比与合并说明.md b/开发文档/10、项目管理/永平版优化对比与合并说明.md deleted file mode 100644 index 45f7e43f..00000000 --- a/开发文档/10、项目管理/永平版优化对比与合并说明.md +++ /dev/null @@ -1,91 +0,0 @@ -# 永平版 vs 主项目：优化对比与合并说明 - -> 对比目录：主项目（一场soul的创业实验） vs 永平版（一场soul的创业实验-永平） -> 更新日期：2026-02-20 - ---- - -## 一、两套目录结构概览 - -| 项目 | 根目录特点 | Next 源码位置 | -|------|------------|----------------| -| **主项目** | 单仓：Next + book + miniprogram + 开发文档 | 根下 `app/`、`lib/`、`components/` | -| **永平版** | 多仓：soul-api(Go)、soul-admin(Vue)、soul(Next) | `soul/dist/`（源码与构建同目录） | - -永平版还包含：`本机运行文档.md`、Go API(8080)、Vue 管理后台(静态)、开发 API(8081)。主项目为纯 Next 站 + 宝塔 3006 部署。 - ---- - -## 二、已合并到主项目的优化（本次迭代） - -| 模块 | 优化内容 | 主项目路径 | -|------|----------|------------| -| **数据库** | 环境变量 `MYSQL_*`、`SKIP_DB`、连接超时与单次连接错误日志 | `lib/db.ts` | -| **数据库** | 订单表 status 增加 `created`/`expired`，字段 `referrer_id`/`referral_code`；用户表 ALTER 兼容 MySQL 5.7 | 同上 | -| **认证** | 密码哈希/校验（scrypt，兼容旧明文） | `lib/password.ts`（新增） | -| **认证** | Web 端手机号+密码登录 | `app/api/auth/login/route.ts`（新增） | -| **认证** | 重置密码 | `app/api/auth/reset-password/route.ts`（新增） | -| **后台** | 管理员登出（清除 Cookie） | `app/api/admin/logout/route.ts`（新增） | -| **前端** | 仅生产环境加载 Vercel Analytics | `app/layout.tsx` | -| **文档** | 本机/服务器运行说明（端口、目录、Nginx） | `开发文档/本机运行文档.md`（新增） | - ---- - -## 三、永平有、主项目未合并的（可选后续） - -| 模块 | 说明 | 永平路径 | 合并建议 | -|------|------|----------|----------| -| 定时任务 | 订单状态同步、过期解绑 | `app/api/cron/sync-orders`、`cron/unbind-expired` | 若需定时同步/解绑再迁入；需配置 CRON_SECRET | -| 提现扩展 | 待确认列表、提现记录 API | `withdraw/pending-confirm`、`withdraw/records` | 若后台要做提现工作流与记录查询可迁入 | -| 用户 API | 购买状态、阅读进度、收货地址 CRUD | `user/check-purchased`、`user/reading-progress`、`user/addresses` | 按产品需要选择性迁入 | -| 后台 | 分销概览 API、推广设置页 | `admin/distribution/overview`、`admin/referral-settings/page.tsx` | 若有分销看板/推广配置页可迁入 | -| 前台 | 忘记密码页、我的地址列表/编辑/新增 | `app/view/login/forgot`、`app/view/my/addresses/*` | 主项目路由为 `app/login/`、`app/my/`，可对应新增 | -| 构建 | standalone 复制 static/public、clean、write-warning | `scripts/prepare-standalone.js` 等 | 若主项目用 standalone 部署可迁入 | -| 数据层 | Prisma 模型与迁移 | `prisma/schema.prisma`、迁移脚本 | 主项目当前为 mysql2；若统一用 Prisma 再迁 | -| 路由结构 | 前台统一在 `app/view/` | 整棵 `app/view/` | 主项目保持扁平 `app/`，非必须 | - ---- - -## 四、主项目保留、与永平不同的部分 - -- **CORS**：主项目在 `middleware.ts` + `next.config.mjs` 的 headers 中配置 API CORS；永平可能用 Nginx/Go，未在 Next 层做。 -- **路由**：主项目前台为 `app/page.tsx`、`app/my/`、`app/read/` 等，无 `view` 前缀。 -- **book**：主项目根下保留 `book/` Markdown 与现有内容体系；永平书内容可能来自 API/DB。 - ---- - -## 五、环境变量说明（合并后） - -主项目 `.env.local` 建议支持（可选）： - -```bash -# 数据库（不设则用代码内默认值） -MYSQL_HOST= -MYSQL_PORT= -MYSQL_USER= -MYSQL_PASSWORD= -MYSQL_DATABASE= - -# 本地无数据库时跳过连接（接口会报错，适合纯前端联调） -SKIP_DB=0 -``` - ---- - -## 六、合并与实施注意 - -1. **路径**：永平 Next 源码在 `soul/dist/`，合并到主项目时对应到根下 `app/`、`lib/`、`开发文档/`。 -2. **CORS**：保留主项目现有 `middleware.ts` 与 `next.config.mjs` 的 CORS 配置。 -3. **数据库**：主项目继续使用 mysql2，未引入 Prisma；`lib/db.ts` 已支持环境变量与 `SKIP_DB`。 -4. **admin 登出**：后台可增加「退出登录」按钮，请求 `POST /api/admin/logout` 后跳转登录页。 - -5. **已有数据库**：若主项目此前已建过 `orders` 表且无 `referrer_id`/`referral_code` 或 status 无 `created`/`expired`，需自行执行迁移，例如： - ```sql - ALTER TABLE orders MODIFY COLUMN status ENUM('created','pending','paid','cancelled','refunded','expired') DEFAULT 'created'; - ALTER TABLE orders ADD COLUMN referrer_id VARCHAR(50) NULL COMMENT '推荐人用户ID', ADD COLUMN referral_code VARCHAR(20) NULL COMMENT '下单时使用的邀请码'; - ``` - 若表为新建，`initDatabase()` 已包含上述结构。 - ---- - -**文档状态**：已合并项已落地；未合并项见第三节，按需迭代。 diff --git a/开发文档/10、项目管理/派对每日数据汇总.md b/开发文档/10、项目管理/派对每日数据汇总.md deleted file mode 100644 index 7e66d1b8..00000000 --- a/开发文档/10、项目管理/派对每日数据汇总.md +++ /dev/null @@ -1,61 +0,0 @@ -# Soul 派对每日数据汇总 - -按「派对小助手」表头整理的日维度数据，便于按天相加。 - -## 表头说明（与第5张图一致） - -| 时长 | Soul推流人数 | 进房人数 | 人均时长 | 互动数量 | 礼物 | 灵魂力 | 增加关注 | 最高在线 | -|------|--------------|----------|----------|----------|------|--------|----------|----------| - -- **时长**：派对总时长（分钟） -- **Soul推流人数**：本场获得额外曝光（次） -- **进房人数**：派对成员/进房总人数（人） -- **人均时长**：人均停留时长（分钟） -- **互动数量**：本场互动次数 -- **礼物**：本场收到礼物（个） -- **灵魂力**：收获灵魂力 -- **增加关注**：新增粉丝（人） -- **最高在线**：当日各场中最高同时在线人数（人），取最大值、不相加 - ---- - -## 当日汇总（一天相加后的数据） - -**日期**：2026-02-19（根据截图当日多场合并） - -| 时长 | Soul推流人数 | 进房人数 | 人均时长 | 互动数量 | 礼物 | 灵魂力 | 增加关注 | 最高在线 | -|------|--------------|----------|----------|----------|------|--------|----------|----------| -| 155 | 46749 | 545 | 7 | 34 | 1 | 8 | 13 | 47 | - -**计算说明：** - -- **时长**：54 + 22 + 79 = **155** 分钟（第3张与第4张为同一场，只计一次，取结算 79 分钟） -- **Soul推流人数**：12588 + 7695 + 26466 = **46749** 次 -- **进房人数**：164 + 92 + 289 = **545** 人（同一场取 289，不重复加 279） -- **人均时长**：仅一场有数据，取 **7** 分钟 -- **互动数量**：仅一场有数据，取 **34** 次 -- **礼物**：0 + 0 + 1 = **1** 个 -- **灵魂力**：0 + 0 + 8 = **8** -- **增加关注**：2 + 4 + 7 = **13** 人（同一场只计 7，不重复加 5） -- **最高在线**：取当日各场最高值 max(34, 30, 47) = **47** 人（不相加） - ---- - -## 当日分场明细（便于核对） - -*说明：第3张（派对小助手浮层）与第4张（派对已关闭结算）为同一场派对，只计一场。* - -| 场次 | 时长(min) | 曝光/推流 | 进房人数 | 人均时长 | 互动 | 礼物 | 灵魂力 | 新增关注 | 最高在线 | -|------|-----------|-----------|----------|----------|------|------|--------|----------|----------| -| 1 | 54 | 12588 | 164 | — | — | 0 | 0 | 2 | 34 | -| 2 | 22 | 7695 | 92 | — | — | 0 | 0 | 4 | 30 | -| 3（图3+图4同场） | 79 | 26466 | 289 | 7 | 34 | 1 | 8 | 7 | 47 | -| **合计** | **155** | **46749** | **545** | 7 | 34 | **1** | **8** | **13** | **47** | - ---- - -**使用方式**：把「当日汇总」那一行加到总表或飞书运营报表。 - -**导入飞书运营报表时**（脚本 `soul_party_to_feishu_sheet.py`）： -- 只填前 10 项（主题、时长、推流、进房、人均时长、互动、礼物、灵魂力、增加关注、最高在线），**按数字填写**。 -- 推流进房率、1分钟进多少人、加微率 **不填**，由表格公式自动计算。 diff --git a/开发文档/10、项目管理/运营与变更.md b/开发文档/10、项目管理/运营与变更.md new file mode 100644 index 00000000..c9ca78fa --- /dev/null +++ b/开发文档/10、项目管理/运营与变更.md @@ -0,0 +1,81 @@ +# 运营与变更（合并版） + +> 合并自：运营数据与项目分析、派对每日数据汇总、soul-admin变更、永平版优化、近三日更新总览、5份更新详细说明、小程序接口申请 + +--- + +# 第一部分：运营数据与项目分析 + +## 一、项目与派对定位 + +| 维度 | 内容 | +|:---|:---| +| **项目名称** | 一场 SOUL 的创业实验场 | +| **核心目标** | 内容阅读 + 私域引流 + 知识变现 | +| **派对定位** | 晨间 6–9 点 Soul 语音派对，主题：谁在挣钱、怎么挣 | + +## 二、运营报表数据（节选） + +- 105 场、约 108 万推流、1.5 万+ 进房、约 144 小时 +- 日度汇总见「派对每日数据汇总」表头与计算说明 + +## 三、派对每日数据汇总 + +| 表头 | 说明 | +|:---|:---| +| 时长、Soul推流、进房人数、人均时长、互动、礼物、灵魂力、增加关注、最高在线 | 按日相加 | + +--- + +# 第二部分：soul-admin 与永平版变更 + +## soul-admin 变更 + +- 侧边栏：交易中心 → 推广中心 +- 内容管理：移除 5 按钮，保留 API 接口，删除 hover，免费/付费切换，小节加号 +- 缓存：?v=2 强制刷新，修复 Failed to fetch + +## 永平版优化对比 + +- 主项目 vs 永平版：单 Next vs 多服务（Go+Vue+Next） +- 已合并项：数据库、认证、后台登出等；可选合并：定时任务、提现记录、地址 API 等 + +--- + +# 第三部分：近三日更新（2026-02-21～24） + +## Git 提交 + +9b410f2a 永平版上传 → e5e6ffd7 miniprogram 替换 → b038a042 超级个体 → afc2376e VIP/收益/排行 → e91a5d9f 精选推荐 → 7551840c 管理后台改造 → f6846b59/685b4767/74b1c339 soul-admin 修复 + +## 功能 + +VIP 会员、超级个体、我的收益、阅读量排序、提现记录、地址、协议隐私、图标系统 + +## 算法 + +精选推荐、热门章节、最新章节、权限校验、阅读追踪、VIP 排序 + +## 前端 + +soul-admin 管理后台改造、API TOKEN、缓存修复 + +## 后端 + +VIP 接口、章节推荐逻辑、数据库依赖 + +## 小程序 + +永平版替换、新增页面（地址/协议/隐私/提现记录/会员详情）、改版页面、组件与工具类 + +--- + +# 第四部分：小程序接口申请文案 + +用于微信公众平台 → 开发管理 → 接口设置 → 接口权限，每个理由 300 字以内： + +- **wx.chooseAddress**：创业资源对接，用户匹配成功后需交换联系地址，一键选择微信收货地址 +- **wx.getPhoneNumber**：付费阅读与分销提现，需手机号完成身份验证与提现到账 +- **wx.chooseLocation / wx.choosePoi**：线下见面与资源对接，用户需选择见面地点 + +详见原「小程序接口申请文案」完整文案。 diff --git a/开发文档/10、项目管理/运营报表与Soul聊天记录全量分析.md b/开发文档/10、项目管理/运营报表与Soul聊天记录全量分析.md deleted file mode 100644 index afb6ff42..00000000 --- a/开发文档/10、项目管理/运营报表与Soul聊天记录全量分析.md +++ /dev/null @@ -1,111 +0,0 @@ -# 运营报表 + Soul 聊天记录全量分析（10 月第一场至今） - -> 时间范围：2025 年 10 月第一场 → 2026 年 2 月（当前）。 -> 数据来源：飞书运营报表多月度汇总 + `聊天记录/soul` 目录下全部派对/会议 txt 与合并稿。 - ---- - -## 一、时间线与数据覆盖 - -### 1.1 场次与日历对应（据聊天记录文件名整理） - -| 时期 | 日期范围 | 场次/内容 | 聊天记录文件情况 | -|:---|:---|:---|:---| -| **2025 年 10 月** | 10/25–10/31 | 最早场次（未统一编号） | 10月25日、26、27、30、31 等 txt；soul202510-20260102 含 10/22 起大段合并 | -| **2025 年 11 月** | 11/4–11/27 | 多场，部分有 26场、27场、32场 等 | 11月多日 + 魔兽私服/留学/美业、电竞陪玩、学校创业等主题文件名 | -| **2025 年 12 月** | 12/2–12/31 | 41场→50场（12/18）、51–62场 | 12月2日到31日；44场(12/11)、50场(12/18)、51–62场 等 | -| **2026 年 1 月** | 1/1–1/31 | 62场(1/1)、83–90场 | 62场 1月1日；83–90场（1/26–2/3）；团队会议 17场、39场 等 | -| **2026 年 2 月** | 2/16–2/20 | 101–105场 | 101–105场 2/16–2/20；104场 妙记/纪要 等 | - -说明：10 月、11 月部分日期未在文件名中标「第 x 场」，按日期与后续 44–62 场反推，**第一场可视为 2025 年 10 月**；当前至 **105 场**（2026/02/20）。 - -### 1.2 聊天记录全量统计 - -| 项目 | 数值 | -|:---|:---| -| **txt 文件数（仅 .txt）** | 约 85+ 个 | -| **时间跨度** | 2025-10-22/25 → 2026-02-20 | -| **合并长稿** | soul202510-20260102.txt（约 8 万+ 行，10/22–1/2）；soul派对会议到12月3日-1月7日.txt | -| **含「场」编号的文件** | 41场–62场、83–90场、101–105场 等 | -| **团队会议** | 12月11日（第一场）、17场、39场、产研第20场 等 | - ---- - -## 二、运营报表数据（10 月至今） - -以下为飞书运营报表中**可解析的多月度**汇总（含 25年10月、2026年1月、2026年2月 等）。 - -### 2.1 按时期汇总 - -| 时期 | 有数据场次 | 总时长(分钟) | Soul推流 | 进房人数 | 互动 | 礼物 | 灵魂力 | 增加关注 | 最高在线 | 人均时长(分钟) | -|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---| -| **25年10月** | 11 | 1,746 | 0* | 905 | 201 | 110 | 124 | 0* | 0* | — | -| **2026年1月** | 27 | 3,659 | 772,133 | 9,690 | 4,841 | 177 | 22,644 | 496 | 75 | 10.3 | -| **2026年2月** | 12 | 1,477 | 310,078 | 3,721 | 660 | 40 | 5,972 | 174 | 56 | 9.5 | -| **合计（报表内）** | **50** | **6,882** | **1,082,211** | **14,316** | **5,702** | **327** | **28,740** | **670** | **75** | **11.2** | - -\* 25年10月 报表中推流/关注/最高在线 多为空或 0，仅部分指标有数。 - -### 2.2 全量合计（含 10 月） - -- **总场次（有数据）**：约 50 场（报表填写）；若含 10 月、11 月、12 月未完全入表场次，**实际派对场次从 10 月起累计约 105 场**。 -- **总时长**：报表内 6,882 分钟（约 114.7 小时）；加 10 月 1,746 分钟 ≈ **8,628 分钟**（约 143.8 小时）。 -- **Soul 推流**：约 **108.2 万**（10 月表内未录推流）。 -- **进房人数**：约 **14,316**（表内）+ 10 月 905 ≈ **15,221**。 -- **互动 / 礼物 / 灵魂力 / 关注**：见表；10 月贡献 201 互动、110 礼物、124 灵魂力。 - ---- - -## 三、聊天记录内容与主题（全量视角） - -### 3.1 来源与结构 - -- **单场/单日**：`soul 2025年10月25日.txt`、`soul 派对 第103场 20260218.txt` 等，多为「关键词 + 文字记录」或飞书妙记导出。 -- **长合并**：`soul202510-20260102.txt` 从 2025-10-22 到 2026-01-02，含大量逐字稿。 -- **主题在文件名中的体现**：电竞陪玩、学校创业、魔兽私服、留学、美业、小程序、书、分层与规则 等。 - -### 3.2 高频主题与关键词（来自抽样与文件名） - -从 10 月、11 月及合并稿抽样可见，**贯穿全程的主题**包括： - -| 类别 | 关键词/主题 | -|:---|:---| -| **变现与生意** | 直播、电商、抖音、小红书、流量、粉丝、带货、知识付费、私域、微信、老板、生意、底层逻辑 | -| **行业与赛道** | 主播方向、电竞、陪玩、留学、美业、魔兽私服、学校创业、财税、税筹、资源整合、行业整合 | -| **组织与协作** | 客户、企业、体量、财务、风险、合作伙伴、中台、赋能、加盟、分账 | -| **产品与项目** | 小程序、书、派对、分层、规则、落地执行、朋友圈素材、6980 套餐 | - -与项目「内容 + 私域 + 分销」和「谁在挣钱、怎么挣」的定位一致；聊天记录构成**书稿与运营动作的素材源**。 - -### 3.3 与运营报表的对应关系 - -- **有「场次」的聊天记录**（如 44–62、83–90、101–105）可与报表中「同场次」或「同日期列」的效果数据一一对应，做单场**内容主题 ↔ 进房/互动/关注**分析。 -- **10 月、11 月**部分仅有日期无场次号，可按日期与报表「日期列」或后续整理的场次映射做关联。 -- **团队会议**（12/11 第一场、17场、39场、产研20场）与「内部会议纪要」行、会议图片上传对应，用于复盘与决策追溯。 - ---- - -## 四、全量运营结论（10 月至今） - -1. **规模** - - 从 **2025 年 10 月第一场** 到 **2026 年 2 月 105 场**，报表内约 50 场有完整效果数据；总曝光约 **108 万推流**，进房约 **1.5 万+**，总时长约 **144 小时** 量级。 -2. **流量与沉淀** - - 1 月推流与进房最高（约 77 万、9,690）；2 月场次与总量下降，人均时长与最高在线仍维持在约 9–10 分钟、56 人，单场质量未明显下滑。 -3. **内容与记录** - - **85+ 个 txt** 覆盖 10/22–2/20，含单场逐字稿与 10/22–1/2 长合并稿；主题覆盖电商、主播、电竞、财税、私域、小程序与书，与项目定位一致，可支撑书稿、复盘与运营分析。 -4. **数据完整性** - - 10 月、11 月报表字段不全（推流/关注/最高在线多缺），建议在报表或本地表中对 10–11 月做「补录或标注」，便于全周期对比；聊天记录与报表的「场次/日期」对应关系可固化为一张映射表，方便后续全量分析自动化。 - ---- - -## 五、建议的后续动作 - -1. **报表**：对 10 月、11 月能做补录的场次补全推流/关注/最高在线；新场次继续按「日期列 + 场次」填写并发群（竖状）。 -2. **聊天记录**：保持「按场次/日期」命名；大段合并稿保留，并可与单场 txt 做交叉校验。 -3. **分析**：每月或每季度跑一次「10 月至今」全量汇总（报表 + 聊天记录文件清单），更新本文档第二节与第四节，并和项目目标（链接数、会员、付费）做对照。 - ---- - -**文档版本**：v1.0 -**数据基准**：飞书运营报表（25年10月、2026年1月、2026年2月）；聊天记录目录 `聊天记录/soul` 下 85+ 个 txt 及 soul202510-20260102 等合并稿。 -**更新**：随新场次与补录数据更新上表与结论。 diff --git a/开发文档/10、项目管理/运营报表与项目运营分析.md b/开发文档/10、项目管理/运营报表与项目运营分析.md deleted file mode 100644 index be73908b..00000000 --- a/开发文档/10、项目管理/运营报表与项目运营分析.md +++ /dev/null @@ -1,132 +0,0 @@ -# 运营报表数据与项目运营分析 - -> 基于飞书运营报表全量数据，结合「一场 SOUL 的创业实验」项目目标的运营视角分析。 -> 数据来源：飞书运营报表（Soul 派对效果数据）；项目：推进表、派对定位、书/小程序闭环。 - ---- - -## 一、项目与派对定位（背景） - -| 维度 | 内容 | -|:---|:---| -| **项目名称** | 一场 SOUL 的创业实验场 | -| **核心目标** | 内容阅读 + 私域引流 + 知识变现，验证「内容 + 私域 + 分销」商业闭环 | -| **派对定位** | 晨间 6–9 点 Soul 语音派对，主题：谁在挣钱、怎么挣；链接创业/副业人群 | -| **产出** | 《一场soul的创业实验》书籍内容、H5/小程序「卡若的创业派对」、会员群/资源群、线下见面 | -| **阶段目标（历史）** | 前 50 场目标链接 1000 人（实际约 270，完成度 27%）；51–100 场组建 7 管理、40+ 副业、90+ 老板、会员群；线下见面 30+ 人 | - -派对是**流量与链接入口**，书与小程序是**内容与变现载体**，运营报表衡量的是**入口侧的规模、参与度与沉淀**。 - ---- - -## 二、运营报表数据总览 - -以下为从飞书运营报表汇总得到的多月度合计（含 1 月、2 月及可解析的其他月份）。 - -### 2.1 全量汇总（多个月度合计） - -| 指标 | 数值 | 说明 | -|:---|:---|:---| -| **有数据场次** | 约 50 场 | 报表内已填写的场次 | -| **总时长** | 约 6,882 分钟 | 约 114.7 小时 | -| **Soul 推流人数** | 约 108.2 万 | 平台曝光量级 | -| **进房人数** | 约 14,316 | 去重后约 1.4 万+ 进房 | -| **互动数量** | 约 5,702 | 总互动次数 | -| **礼物** | 约 327 | 场均约 6.5 个 | -| **灵魂力** | 约 28,740 | 平台内成长值/积分 | -| **增加关注** | 约 670 | 新增粉丝合计 | -| **最高在线（单场最大）** | 75 人 | 各场峰值取 max | -| **人均时长（有数据场平均）** | 约 11.2 分钟 | 停留质量参考 | - -### 2.2 分月对比（第 1 月 vs 第 2 月） - -| 指标 | 第 1 月（约 27 场） | 第 2 月（约 12 场） | 环比变化 | -|:---|:---|:---|:---| -| 总时长（分钟） | 3,659 | 1,477 | 场次减，总时长降 | -| Soul 推流人数 | 772,133 | 310,078 | 约 -60% | -| 进房人数 | 9,690 | 3,721 | 约 -62% | -| 互动数量 | 4,841 | 660 | 约 -86% | -| 礼物 | 177 | 40 | 约 -77% | -| 灵魂力 | 22,644 | 5,972 | 约 -74% | -| 增加关注 | 496 | 174 | 约 -65% | -| 最高在线 | 75 | 56 | 峰值略降 | -| 人均时长（分钟） | 10.3 | 9.5 | 基本稳定 | - -第 2 月有数据场次明显少于第 1 月（约 12 场 vs 27 场），各项总量随场次下降而下降；人均时长、最高在线等「单场质量」指标相对稳定，说明单场运营节奏未明显变差。 - -### 2.3 单场样本（近期有完整数据的场次） - -| 场次 | 主题（核心干货） | 时长 | 推流 | 进房 | 人均时长 | 互动 | 礼物 | 灵魂力 | 关注 | 最高在线 | -|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---| -| 99 | — | 116 | 16,976 | 208 | — | — | 4 | 166 | 12 | 39 | -| 103 | 号商几毛卖十几 日销两万 | 155 | 46,749 | 545 | 7 | 34 | 1 | 8 | 13 | 47 | -| 104 | AI创业最赚钱一月分享 | 140 | 36,221 | 367 | 7 | 49 | 0 | 0 | 11 | 38 | -| 105 | 创业社群AI培训6980 电竞私域 | 138 | — | 403 | 10 | 170 | 2 | 24 | 31 | 54 | - -可看出的规律：单场时长约 2–2.5 小时；进房 300–500 量级与项目内「一场 300–600 人」一致；主题明确、有干货的场次（如 103、104、105）互动与关注更好。 - ---- - -## 三、运营视角分析 - -### 3.1 流量与规模 - -- **推流规模**：累计约 108 万推流，说明 Soul 侧给了可观曝光，派对作为内容形态被平台认可。 -- **进房转化**：进房约 1.43 万（去重后），相对 108 万推流，**推流→进房** 转化约 1.3% 量级；单场进房 300–500 是常态，与「每天 300–600 人」的定位一致。 -- **结论**：流量规模足够支撑「链接与内容沉淀」；若要进一步放大，可重点优化推流→进房（标题、时段、话题）和进房→停留（人均时长、互动设计）。 - -### 3.2 参与与粘性 - -- **人均时长**：有数据场平均约 10–11 分钟，说明多数用户是「短停留、多场次」；与「停留 10–15 分钟能听两三个视角」的设定吻合。 -- **互动**：总互动 5,702，场均约 114；近期场 34–170 不等，主题清晰、干货强的场互动更高。 -- **最高在线**：单场峰值 38–54（近期），历史最高 75；反映同时段「强参与」人数，可作为热力与内容爆点的观测指标。 -- **结论**：当前设计适合「轻参与、多触达」；若要做深链接，可针对「高停留/高互动」用户设计分层（如会员群、资源群入口），与项目「私域引流」目标对齐。 - -### 3.3 沉淀与转化（关注、私域） - -- **增加关注**：累计约 670，约 50 场，场均约 13；近期单场 11–31。 -- **与项目目标的关系**：前 50 场目标链接 1000 人、实际约 270；关注数 670 是「Soul 内关注」口径，与「链接」（加微/进群）不是同一漏斗，但可视为上游指标。 -- **结论**：关注是私域的前置；若项目 KPI 是「加微/进群/会员」，需在报表或线下增加「进群数/加微数」等字段，并与 Soul 关注、进房、互动做交叉分析，才能看清「派对→私域→变现」的转化率。 - -### 3.4 商业化与内容 - -- **礼物/灵魂力**：礼物 327、灵魂力 28,740，更多反映平台内参与与打赏，不是项目主变现路径。 -- **主变现路径**：书/小程序（一天一块钱一节）、会员群、线下；派对侧主要贡献「流量 + 内容素材 + 链接机会」。 -- **结论**：运营报表侧重「派对效果」；若要全面评估项目，需把「小程序/书籍付费、会员、线下见面」等与报表做联动分析（例如：某月派对进房/关注上涨时，当月付费或进群是否同步变化）。 - -### 3.5 稳定性与节奏 - -- **开播节奏**：每天 6–9 点固定时段，有利于养成用户习惯和平台推流稳定性。 -- **场次与总量**：第 2 月有数据场次减少，总时长、推流、进房等随之下降；若 2 月存在春节等客观因素，可视为短期波动；若为主动收缩，需明确是「提质减量」还是「产能不足」，以便调整目标。 -- **结论**：建议按「周/月」固定复盘：场次、总时长、进房、关注、最高在线；并和「链接数、会员、付费」做简单对照，便于做运营决策。 - ---- - -## 四、与项目目标的对照 - -| 项目目标 | 运营报表可支撑的观测 | 建议 | -|:---|:---|:---| -| **内容沉淀** | 总时长、场次、主题（表格内主题列） | 主题与书/小程序章节对应，便于「派对→内容→付费」追溯 | -| **私域引流** | 进房、关注、互动 | 在报表或线下补充「进群/加微」数，与关注做漏斗分析 | -| **知识变现** | 报表无直接指标 | 用独立维度记录：小程序付费、会员费、线下活动收入，与派对月度汇总对比 | -| **链接人数/质量** | 进房、关注、最高在线 | 前 50 场链接 270 人可与「关注 670」对比口径；51–100 场管理/副业/老板数可作质量维度 | - ---- - -## 五、结论与建议（运营视角） - -1. **报表价值**：当前运营报表已能清晰反映「派对规模、参与度、平台内沉淀」；与项目结合时，需补「私域与变现」口径，才能闭环评估。 -2. **流量与转化**：108 万推流、1.4 万+ 进房、670 关注，规模足够；下一步可重点看「进房→关注→加微/进群」的转化与节奏。 -3. **单场质量**：人均 10–11 分钟、最高在线 38–75，与「轻参与、多触达」定位一致；若要做深，可对高停留/高互动用户做分层运营。 -4. **节奏与目标**：建议每月固定做「场次、总时长、进房、关注、最高在线」与上月对比，并和链接数/会员/付费做简单对照；遇重大节日或策略调整时单独标注，便于归因。 -5. **数据一致性**：报表按「日期列/场次列」填写、发群用竖状格式，便于前后一致；会议纪要/今日总结用图片入格，有利于保留现场决策与复盘，与运营分析互补。 - ---- - -**文档版本**：v1.0 -**数据基准**：飞书运营报表多月度汇总（约 50 场有数据）；项目信息来自推进表与派对/书/小程序定位。 -**更新建议**：每月或每季度在本文末追加「当月/当季小结」与目标达成情况，形成可延续的运营分析记录。 - ---- - -**延伸**：从**第一场（10 月）至今**的运营报表全量数据与 **Soul 聊天记录**（85+ 个 txt、合并稿）的全量分析见 → [运营报表与Soul聊天记录全量分析.md](./运营报表与Soul聊天记录全量分析.md)。 diff --git a/开发文档/10、项目管理/项目落地推进表.md b/开发文档/10、项目管理/项目落地推进表.md index 5f170860..8daaf6e1 100644 --- a/开发文档/10、项目管理/项目落地推进表.md +++ b/开发文档/10、项目管理/项目落地推进表.md @@ -350,10 +350,12 @@ vercel --prod **建议下一步**：按需接入永平版可选能力（定时任务、提现记录、地址管理、推广设置页等），见 `开发文档/永平版优化对比与合并说明.md` -**最后更新时间**：2026-02-20 +**最后更新时间**：2026-02-24 **最后更新人**：卡若 (智能助手) **项目交付状态**：✅ 完整交付 +**近三日更新**：见 [运营与变更.md](./运营与变更.md)。 + --- ## 九、永平版优化合并迭代（2026-02-20） diff --git a/开发文档/1、需求/TDD_创业派对项目方案_v1.0.md b/开发文档/1、需求/TDD_创业派对项目方案_v1.0.md deleted file mode 100644 index c61c6c8b..00000000 --- a/开发文档/1、需求/TDD_创业派对项目方案_v1.0.md +++ /dev/null @@ -1,216 +0,0 @@ -# Soul创业派对 TDD需求方案 v1.0 - -> 生成时间: 2026-01-25 -> 基于: Human 3.0 + CRITIC智能追问 - ---- - -## 一、需求摘要 - -**一句话定位**：以卡若IP为核心，通过真实创业案例内容吸引创业者，匹配书中案例参与者，形成"内容引流→私域沉淀→后端变现"的完整商业闭环。 - -**核心闭环**： -``` -Soul派对引流 → 小程序阅读 → 付费解锁 → 匹配案例人物 → 加入会员 → 私域变现 -``` - ---- - -## 二、项目背景 - -| 维度 | 内容 | -|:---|:---| -| **项目名称** | Soul创业派对（原：创业实验） | -| **项目阶段** | 已上线，持续迭代 | -| **核心目标** | 验证"IP+内容+匹配+私域"商业模式，支撑存客宝+碎片时间团队运转 | -| **验收人** | 卡若 | -| **最终目标** | 1万人付款9.9元 + 100个创业者365会员 + 100个匹配会员 | - ---- - -## 三、用户画像 - -| 维度 | 内容 | -|:---|:---| -| **主要用户** | 已创业的老板（B端） | -| **用户来源** | Soul派对房 + 小程序分享裂变 | -| **付费动机** | ①真实案例数据（别处没有）②卡若IP背书 | -| **用户旅程** | 浏览者 → 付费书友 → 分销者 → 匹配会员 → 后端客户 | - ---- - -## 四、竞品分析 - -### 4.1 直接竞品 - -| 竞品 | 模式 | 优势 | 劣势 | 创业派对差异化 | -|:---|:---|:---|:---|:---| -| **得到** | 课程付费 | 头部IP多，品牌强 | 价格高，内容泛化 | 垂直创业领域，真实案例 | -| **知识星球** | 社群付费 | 社群沉淀强 | 内容碎片化 | 结构化书籍+匹配功能 | -| **小报童** | 专栏付费 | 轻量，门槛低 | 无匹配功能 | 匹配书中案例人物 | -| **冯唐成事不二堂** | IP+课程 | 年营收过亿 | 偏商业管理 | 聚焦创业实战案例 | -| **樊登读书（帆书）** | 读书会员 | 用户基数大 | 内容为书籍解读 | 原创真实案例 | - -### 4.2 核心护城河 - -1. **Soul渠道独家**：Soul派对房日活用户，精准创业人群 -2. **匹配功能独家**：可匹配到书中案例的真实参与者 -3. **卡若IP独家**：365天连续直播，信任背书强 -4. **真实数据独家**：收入、成本、流程等真实商业数据 - ---- - -## 五、功能范围 - -### 5.1 核心功能（当前版本） - -| 模块 | 功能点 | 优先级 | 状态 | -|:---|:---|:---|:---| -| **内容阅读** | 62章节阅读 + 上下篇导航 | P0 | ✅已完成 | -| **内容搜索** | 搜索数据库+文章内容（匹配数据隐藏） | P0 | 待优化 | -| **付费解锁** | 单章1元 / 全书9.9元 | P0 | ✅已完成 | -| **分销裂变** | 90%佣金（第一阶段） | P0 | ✅已完成 | -| **找伙伴匹配** | 创业合伙/资源对接/导师顾问/团队招募 | P0 | ✅已完成 | -| **匹配付费** | 免费3次/天，之后付费（默认1元，可配置） | P1 | 待完善 | -| **后台管理** | 内容管理/用户管理/配置管理 | P0 | 待完善 | - -### 5.2 本期不做 - -| 功能 | 原因 | -|:---|:---| -| 视频/音频内容 | 优先验证图文模式 | -| 社群功能 | 后端用微信群承接 | -| 多平台分发 | 先专注小程序 | - ---- - -## 六、技术约束 - -| 维度 | 约束 | -|:---|:---| -| **前端** | 微信小程序（原生） | -| **后端** | Next.js API Routes | -| **数据库** | MySQL（腾讯云） | -| **部署** | 腾讯云服务器 | -| **支付** | 微信支付 | -| **响应时间** | <3秒 | -| **并发** | 100人同时在线 | - ---- - -## 七、匹配功能配置 - -### 7.1 匹配类型配置 - -| 类型ID | 名称 | 匹配标签 | 图标 | 从数据库匹配 | 匹配后显示加入 | 默认价格 | 启用 | -|:---|:---|:---|:---|:---|:---|:---|:---| -| partner | 创业合伙 | 创业伙伴 | ⭐ | ✅是 | ❌否 | 1元 | ✅ | -| investor | 资源对接 | 资源对接 | 👥 | ❌否 | ✅是 | 1元 | ✅ | -| mentor | 导师顾问 | 商业顾问 | ❤️ | ❌否 | ✅是 | 1元 | ✅ | -| team | 团队招募 | 加入项目 | 🎮 | ❌否 | ✅是 | 1元 | ✅ | - -### 7.2 匹配规则 - -- **每日免费次数**：3次 -- **付费匹配价格**：默认1元，后台可配置 -- **匹配数据隐藏**：搜索时隐藏手机/微信等敏感信息 -- **匹配前置条件**：需绑定手机号或微信号 - ---- - -## 八、分销规则 - -| 维度 | 规则 | -|:---|:---| -| **佣金比例** | 90%（第一阶段62章节） | -| **佣金期限** | 不定期调整 | -| **新增章节** | 每增加1章 +1元 | -| **绑定有效期** | 30天 | -| **最低提现** | 10元 | - ---- - -## 九、异常处理规则 - -| 异常场景 | 处理方式 | -|:---|:---| -| 支付成功但回调失败 | 定时补单 + 用户申诉入口 | -| 匹配无结果 | 显示"暂无匹配，试试其他类型" | -| API超时 | 显示loading + 3秒后重试 | -| 数据库连接失败 | 降级为本地配置 | - ---- - -## 十、测试用例清单 - -### 10.1 正常用例 - -| 用例ID | 场景 | 输入 | 期望输出 | -|:---|:---|:---|:---| -| T01 | 免费章节阅读 | 点击免费章节 | 显示完整内容 | -| T02 | 付费章节购买 | 点击购买本章 | 调起微信支付 | -| T03 | 匹配创业伙伴 | 选择创业合伙+点击匹配 | 显示匹配结果 | -| T04 | 分享带推荐码 | 点击分享 | 链接包含ref参数 | - -### 10.2 边界用例 - -| 用例ID | 场景 | 输入 | 期望输出 | -|:---|:---|:---|:---| -| T10 | 匹配次数用完 | 第4次匹配 | 显示付费弹窗 | -| T11 | 未绑定手机匹配 | 点击匹配 | 提示先绑定手机/微信 | -| T12 | 搜索敏感信息 | 搜索手机号 | 不返回结果 | - -### 10.3 异常用例 - -| 用例ID | 场景 | 触发条件 | 期望行为 | -|:---|:---|:---|:---| -| T20 | 支付失败 | 用户取消支付 | 返回阅读页，保持状态 | -| T21 | 网络断开 | 离线状态 | 显示缓存内容 | - ---- - -## 十一、验收标准 - -| 验收项 | 标准 | 验收人 | -|:---|:---|:---| -| 功能完整 | 符合TDD文档 | 卡若 | -| 支付成功率 | >95% | 卡若 | -| 页面加载 | <3秒 | 卡若 | -| 匹配体验 | 动画流畅 | 卡若 | - ---- - -## 十二、运营指标（参考真实数据） - -基于提供的1月数据截图： - -| 指标 | 1月数据 | 目标 | -|:---|:---|:---| -| Soul曝光人数 | 日均3-6万 | 保持 | -| 进入人数 | 日均100-500 | 提升至1000 | -| 入群数量 | 日均1-7人 | 提升至20人 | -| 微信进粉人数 | 日均1-5人 | 提升至10人 | -| 付费转化率 | 待统计 | 8% | - ---- - -## 十三、下一步行动 - -1. ✅ 完善后台匹配配置管理 -2. ✅ 优化匹配次数用完后的付费流程 -3. ✅ 更新小程序品牌名称为"创业派对" -4. ⏳ 添加搜索功能（隐藏敏感数据） -5. ⏳ 增加用户标签系统（浏览者→付费者→分销者） -6. ⏳ 建立裂变机制（邀请有礼） - ---- - -## 十四、版本记录 - -| 版本 | 日期 | 变更内容 | -|:---|:---|:---| -| 1.0 | 2026-01-25 | 初版，基于智能追问生成 | - ---- - -> "好问题比好答案更有价值。" — 卡若 diff --git a/开发文档/1、需求/业务需求.md b/开发文档/1、需求/业务需求.md deleted file mode 100644 index 4d06b331..00000000 --- a/开发文档/1、需求/业务需求.md +++ /dev/null @@ -1,59 +0,0 @@ -# 业务需求 (Business Requirements) - 智能自生长文档 - -> **提示词功能 (Prompt Function)**: 将本文件拖入 AI 对话框，即可激活“需求分析师”角色，协助拆解业务、生成文档与流程图。 - -## 1. 基础上下文 (The Two Basic Files) -### 1.1 角色档案：卡若 (Karuo) -- **身份**：私域运营与技术主理人，创业者。 -- **核心逻辑**：云阿米巴（分不属于对方的钱、按价值分钱、流量绑定）。 -- **性格**：INTP，逻辑强，说话大白话，关注结果与行动。 -- **五行营销**：金(目标) -> 水(流程) -> 木(落地) -> 火(分析) -> 土(资源)。 - -### 1.2 开发与协作规范 -- **目录结构**：严格遵守 1-10 目录结构，不新增顶层目录。 -- **文档驱动**：先写文档再写代码。 -- **技术栈**：Java, React, MongoDB。 - -## 2. 业务需求核心 (Master Content) -### 2.1 目标 (金) -- **核心目标**：通过流量+系统+现金分润，绑定合作方。 -- **关键指标**：合作方留存率、分润金额、流量转化率。 - -### 2.2 流程 (水) -1. **流量引入**：抖音本地号 -> 私域流量池。 -2. **系统承接**：场景获客页面 -> 微信管理 -> 数据分析。 -3. **价值分配**：自动计算分润 -> 现金结算。 - -### 2.3 落地 (木) -- **产品形态**：小程序/H5 获客页 + 后台管理系统。 -- **关键功能**： - - 流量池管理 (Traffic Pools)。 - - 分润计算器。 - - 合作方驾驶舱。 - -### 2.4 分析与迭代 (火) -- **数据复盘**：按周/月输出复盘文档。 -- **迭代逻辑**：基于数据反馈调整分润比例或流量策略。 - -## 3. AI 协作指令 (Expanded Function) -**角色**：你是我（卡若）的产品合伙人。 -**任务**： -1. **拆解项目**：根据输入的简要描述，补充完整的业务流程。 -2. **生成脑图**：输出 Mermaid 思维导图 (`mindmap`)，展示业务结构。 -3. **生成流程图**：输出 Mermaid 序列图 (`sequenceDiagram`)，展示用户与系统的交互。 -4. **输出文档**：按“五行营销”结构生成详细需求文档。 - -### 示例 Mermaid -\`\`\`mermaid -mindmap - root((云阿米巴私域)) - 流量端 - 抖音矩阵 - 本地生活 - 系统端 - 场景获客 - 流量池管理 - 分润端 - 自动计算 - 提现管理 -\`\`\` diff --git a/开发文档/1、需求/卡若角色设定.md b/开发文档/1、需求/卡若角色设定.md deleted file mode 100644 index b4cb2850..00000000 --- a/开发文档/1、需求/卡若角色设定.md +++ /dev/null @@ -1,61 +0,0 @@ -# 卡若角色设定与开发规范 - -## 基础设定 -你是卡若，一位专注私域运营与项目变现的创业者，需严格遵循以下个人信息与行为准则，以自然、简洁的大白话与用户沟通，重点突出逻辑清晰与行动指引。 - ---- - -### 个人信息档案 -- **基础信息**： - - 名字：卡若 - - 农历生日：1984年5月26日0点0分（生辰八字：甲子、己巳、庚申、甲子） - - 身高/体重：180CM/136斤 - - 性格标签：自律、坚持（需提升：外在形象管理、共情能力；需注意：拖延倾向、过度炫耀能力、对他人高要求的压迫感） - - 浪漫特质：喜欢制造惊喜，但确定关系前克制付出；需提醒自己“适度付出”。 - -- **健康信息**： - - 2018年6月确诊糖尿病；2024年确诊肝硬化（需注意健康管理）。 - -- **性格测试结果**： - - PDP：老虎29分+孔雀23分（强势目标导向+社交表达欲） - - MBTI：INTP（56.3%内向+61%直觉+36.8%思考+41.2%感知）（逻辑分析强，灵活但需注意决策速度） - - DISC：力量21分+活跃8分+和平4分+完美7分（主导型人格，关注效率与结果） - -- **核心能力**： - - 五行营销（金：目标人群/流量/品牌/定位；水：流程/过程/条件；木：变现产品/销售/落地；火：项目分析/团队升级/数据分析/学习成长；土：投资/资源） - - 私域运营与技术公司主理人；擅长挖掘优质变现项目 - - 编程技能：Java、React、私域系统架构。 - -### 资源与业务 -- **流量资源**：创业者矩阵账号（日播放量>10000，厦门本地创业者为核心受众）。 -- **团队架构**：IP团队+研发团队+运营团队“私域银行”。 -- **独创模式**：「云阿米巴」（核心心法：①分不属于对方的钱；②按创造价值分钱；③用稳定流量+便捷私域体系绑定合作方；拒绝分股份，现金激励更有效）。 - -### 人脉与联系方式 -- **关键人脉**：夏茜、杨红、王诚鹏、章卫国、陈佳亮、李冰（木子）、慧娟（拉多）、陈裕彬、陈雪融、王路、黄鹭、庄建忠（庄老师）、吉咪宇（小吉）、李长俊、陈华宇（樊登陈总）、骆剑峰、陈鹭明（明哥）、李嘉柔（嘉柔）、天行、婼瑄（小吉或阿猫）。 - ---- - -### 开发与协作规范 -- **文档管理**：根目录新建“开发文档”文件夹，每次新功能开发后更新“开发文档/功能迭代记录.md”（含开发流程+架构图）；API文件统一存放至APP目录下“API”文件夹。 -- **需求对齐**：编写新代码前，先阅读“开发文档/需求文档.md”与“开发文档/功能迭代记录.md”。 -- **前端优化**（角色：卡若助理）： - - 技术栈：nuxt + Vue3、Shadcn UI、Tailwind CSS；强制引入Skeleton组件实现骨架屏预加载。 - - 风格适配：Vant UI+Tailwind微调模拟iOS风格（字体栈→San Francisco；颜色/阴影/圆角→像素级匹配截图；布局间距→1:1校准）。 - - 交互优化：路由切换添加动画（滑动/淡入淡出）；数据加载时显示van-skeleton骨架屏。 -- **后端规范**：使用语言主phthon和JAVA 安装依赖前检查是否已安装（避免重复）；运行系统命令前评估安全性（避开黑名单命令）。 -- **数据库规范**：默认使用MONGO数据库 -- **版本迭代**：按版本顺序迭代，不新建版本；功能需中文注释；“流量词”统一改为“流量池”。 -- **界面规范**： - - 新建场景获客页面默认路径：/scenarios/new；下方菜单与“我的”界面保持不变，避免大幅改动。 - - 功能选项（设备管理/微信号管理/流量池/内容库）统一关联“我的”功能页，按钮样式一致。 - -### 输出格式要求 -- **复盘**：包含目标&结果、过程、反思、总结、执行。 -- **营销文章**：I(兴趣) -> S(故事) -> S(干货) -> M(产品) -> A(行动) -> F(裂变)。 -- **商业计划书**：市场背景、项目介绍、投资亮点、团队介绍、收益模式、财务预测、融资计划。 - -### 卡若风格文章要求 -- **结构**：开头自问自答 -> 主体故事/反思 -> 结尾行动指引。 -- **语言**：简洁直接，挑战传统。 -- **字数**：不低于2000字，数据引用官方报告或真实数据。 diff --git a/开发文档/1、需求/小程序改造TDD需求方案_v1.0.md b/开发文档/1、需求/小程序改造TDD需求方案_v1.0.md deleted file mode 100644 index 19e84c79..00000000 --- a/开发文档/1、需求/小程序改造TDD需求方案_v1.0.md +++ /dev/null @@ -1,219 +0,0 @@ -# 小程序改造 TDD需求方案 v1.1 - -**创建日期**：2026年1月23日 -**更新日期**：2026年1月23日 -**创建人**：卡若AI -**状态**：开发中 - ---- - -## 一、需求摘要 - -**一句话定位**：优化Soul创业实验小程序的用户体验，增强核心功能，提升变现转化率。 - -**核心闭环**： -``` -用户打开小程序 → 微信登录 → 浏览内容 → 付费购买 → 推广获益 → 自动提现 - ↓ - 匹配合伙人 → 查看档案/认证 → 建立合作 -``` - ---- - -## 二、项目背景 - -| 维度 | 内容 | -|:---|:---| -| **项目名称** | 一场Soul的创业实验 - 小程序改造 | -| **项目阶段** | 已上线，功能迭代 | -| **核心目标** | 交互体验优化 + 支付分销上线 | -| **验收人** | 卡若 | -| **代码位置** | `/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram/` | -| **数据库** | 腾讯云MySQL：56b4c23f6853c.gz.cdb.myqcloud.com:14413 | -| **域名** | https://soul.quwanzhi.com | - -### 当前问题（已修复） - -| 问题类型 | 具体表现 | 修复状态 | -|:---|:---|:---| -| 登录流程 | 未登录时显示过多功能，干扰用户 | ✅ 已修复 | -| 支付流程 | 需要反复登录才能支付 | ✅ 已修复 | -| 章节显示 | 锁图标和标题错位 | ✅ 已修复 | -| 匹配页面 | 图标和文字对齐问题 | ✅ 已修复 | -| 文案问题 | "分享赚钱"不够高大上 | ✅ 已修复 | -| 数据库 | 使用本地数据库 | ✅ 切换腾讯云 | - ---- - -## 三、已完成功能清单 - -### 3.1 界面优化 - -| 模块 | 功能点 | 状态 | -|:---|:---|:---| -| **我的页面** | 未登录只显示登录按钮 | ✅ | -| **章节列表** | 简化锁图标，修复对齐 | ✅ | -| **匹配页面** | 修复次数栏图标对齐 | ✅ | -| **匹配页面** | 删除底部免费次数提示 | ✅ | -| **阅读页面** | 文案优化（推广收益） | ✅ | - -### 3.2 支付功能 - -| 模块 | 功能点 | 状态 | -|:---|:---|:---| -| **微信支付** | 小程序直接调起微信支付 | ✅ | -| **重复购买检测** | 避免重复支付同一章节 | ✅ | -| **静默获取openId** | 已登录用户无需重复登录 | ✅ | -| **测试模式** | 支付服务不可用时可测试 | ✅ | - -### 3.3 分销功能 - -| 模块 | 功能点 | 状态 | -|:---|:---|:---| -| **推广中心** | 显示收益、绑定用户列表 | ✅ | -| **邀请码** | 自动生成专属邀请码 | ✅ | -| **绑定关系** | H5/小程序统一绑定 | ✅ | -| **推广API** | `/api/referral/data` 接口 | ✅ | - -### 3.4 后台管理 - -| 模块 | 功能点 | 状态 | -|:---|:---|:---| -| **章节管理** | `/admin/chapters` 管理页面 | ✅ | -| **价格设置** | 可修改章节价格 | ✅ | -| **免费设置** | 可设置章节免费状态 | ✅ | -| **匹配配置** | `/api/match/config` 接口 | ✅ | - -### 3.5 数据库 - -| 模块 | 表名 | 状态 | -|:---|:---|:---| -| **用户表** | users | ✅ | -| **订单表** | orders | ✅ | -| **推广关系** | referral_bindings | ✅ | -| **匹配记录** | match_records | ✅ | -| **系统配置** | system_config | ✅ | - ---- - -## 四、上线检查清单 - -### 4.1 小程序配置 - -- [ ] AppID配置正确：`wxb8bbb2b10dec74aa` -- [ ] 域名白名单：`soul.quwanzhi.com` -- [ ] 支付功能开通 -- [ ] 提交审核 - -### 4.2 服务端配置 - -- [ ] 腾讯云数据库连接正常 -- [ ] 微信支付证书配置 -- [ ] API接口全部可用 -- [ ] SSL证书有效 - -### 4.3 支付配置 - -| 配置项 | 值 | -|:---|:---| -| 小程序AppID | wxb8bbb2b10dec74aa | -| 商户号 | 1318592501 | -| API密钥 | wx3e31b068be59ddc131b068be59ddc2 | -| 回调地址 | https://soul.quwanzhi.com/api/miniprogram/pay/notify | - ---- - -## 五、API接口清单 - -### 5.1 小程序专用接口 - -| 接口 | 方法 | 说明 | -|:---|:---|:---| -| `/api/miniprogram/login` | POST | 微信登录获取openId | -| `/api/miniprogram/pay` | POST | 创建支付订单 | -| `/api/miniprogram/pay/notify` | POST | 支付回调 | - -### 5.2 通用接口 - -| 接口 | 方法 | 说明 | -|:---|:---|:---| -| `/api/referral/data` | GET/POST | 推广数据/绑定关系 | -| `/api/match/config` | GET/POST | 匹配规则配置 | -| `/api/admin/chapters` | GET/POST | 章节管理 | -| `/api/db/init` | POST | 数据库初始化 | -| `/api/db/chapters` | GET | 章节内容 | - ---- - -## 六、文案规范 - -### 6.1 推广相关 - -| 原文案 | 优化后 | -|:---|:---| -| 分享赚钱 | 立即推广 | -| 分享给好友 | 推荐好友，共同成长 | -| 好友购买你获得90%佣金 | 邀请好友加入，享90%推广收益 | - -### 6.2 匹配相关 - -| 位置 | 文案 | -|:---|:---| -| 匹配次数 | 今日剩余 X次 | -| 购买次数 | ¥1购买1次 | -| 当前模式 | 当前模式: 创业合伙 | - ---- - -## 七、测试用例 - -### 7.1 登录流程 - -| 用例 | 操作 | 期望结果 | -|:---|:---|:---| -| 未登录访问"我的" | 打开小程序进入"我的"页面 | 只显示登录按钮，不显示其他功能 | -| 微信登录 | 点击微信登录按钮 | 调起微信授权，登录成功 | -| 登录后显示 | 登录成功 | 显示用户信息和完整功能菜单 | - -### 7.2 支付流程 - -| 用例 | 操作 | 期望结果 | -|:---|:---|:---| -| 购买章节 | 点击"购买本章" | 直接调起微信支付 | -| 重复购买 | 已购章节再次点击购买 | 提示"已购买过此章节" | -| 支付成功 | 完成支付 | 立即更新购买状态，可阅读 | - -### 7.3 推广流程 - -| 用例 | 操作 | 期望结果 | -|:---|:---|:---| -| 查看推广中心 | 点击推广中心 | 显示收益、绑定用户列表 | -| 复制邀请链接 | 点击复制链接 | 链接包含专属邀请码 | -| 分享文案 | 点击分享到朋友圈 | 复制推广文案 | - ---- - -## 八、下一步计划 - -### 待开发功能 - -| 功能 | 优先级 | 说明 | -|:---|:---|:---| -| 全站搜索 | P1 | 搜索章节标题和内容 | -| 阅读进度同步 | P1 | 小程序↔网页端同步 | -| 自动提现 | P2 | 满100元自动提现 | -| 合伙人档案 | P2 | 详细档案和认证体系 | - -### 本期目标 - -1. ✅ 支付功能可用 -2. ✅ 分销功能可用 -3. ✅ 界面优化完成 -4. ⏳ 提交小程序审核上线 - ---- - -**方案版本**：v1.1 -**创建时间**：2026-01-23 -**更新时间**：2026-01-23 -**下次评审**：上线后 \ No newline at end of file diff --git a/开发文档/1、需求/技术需求.md b/开发文档/1、需求/技术需求.md deleted file mode 100644 index e5c91ead..00000000 --- a/开发文档/1、需求/技术需求.md +++ /dev/null @@ -1,22 +0,0 @@ -# 技术需求 - -## 开发与协作规范 -- **文档管理**：根目录新建“开发文档”文件夹，每次新功能开发后更新“开发文档/功能迭代记录.md”（含开发流程+架构图）。 -- **API文件**：统一存放至APP目录下“API”文件夹。 -- **需求对齐**：编写新代码前，先阅读“开发文档/需求文档.md”与“开发文档/功能迭代记录.md”。 - -## 前端优化 -- **技术栈**：React、Shadcn UI、Tailwind CSS。 -- **强制要求**：引入Skeleton组件实现骨架屏预加载。 -- **风格适配**：Vant UI+Tailwind微调模拟iOS风格（字体栈→San Francisco；颜色/阴影/圆角→像素级匹配截图；布局间距→1:1校准）。 -- **交互优化**：路由切换添加``动画（滑动/淡入淡出）；数据加载时显示van-skeleton骨架屏。 - -## 后端规范 -- **语言**：Python (FastAPI/Flask) -- **依赖管理**：使用 `pip` 或 `poetry` 管理依赖，安装前检查 `requirements.txt`。 -- **安全**：运行系统命令前评估安全性（避开黑名单命令，如 `rm -rf`）。 -- **AI能力**：需集成 LLM 调用接口与向量处理能力。 - -## 数据库 -- **核心数据库**：MongoDB（需支持向量检索以适配 AI 功能）。 -- **查询要求**：支持基于语义的 AI 模糊查询与推荐。 diff --git a/开发文档/1、需求/需求日志 b/开发文档/1、需求/需求日志 new file mode 100644 index 00000000..fb51815d --- /dev/null +++ b/开发文档/1、需求/需求日志 @@ -0,0 +1,9 @@ +20260223 + +那个在我的里面，我的足迹里面最近阅读的这个章节要写清楚章节的那个名称，小杰的名称得写上去。然后这个。推广中心改成我的收益，然后把这个推广中心我的收益，然后上面显示的是我的收益有多少钱？把推广中心这一个我的收益改到这个界面，就名昵称的下方购买章节推荐函好友，然后那个带领收益，这个改成我的收益，然后把推广中心去掉，然后把账号设置。账号设置。也移到这个，我的那个资料的那个里面，这个界面上面。精选队推荐这边的话，首页上精选推荐，这里选择的是后端的那个文章的那个阅读量，文章的阅读量，然后把这个文章的相应的那个阅读做一个阅读的一个点击的一个记录，后台文章得有一个点击的一个记录。然后把手页里面的这个内容预览去掉，首页内容预览去掉，这个就是只有一个目录。只有一个目录，然后这边的话是一个那个。内容预览去掉，改成首页，上面改成那个有名字的，有填写名字的和联系方式的，是那个。创业老板排行，然后显示一排带头像、带图标、带名字的显示一排。四个显示一排是有名字跟图像，那后鼠标然后点击进去的话，就是它的一个详细材料，就优秀会员的一个板块。 + +然后在一个主要就是他就是那个管理开发文档的用的，然后把整个那个开发文档直至保留这个10个目录。开发文档只有这4个目录，其他的文件文档就整合到这个10个目录底下，然后这个 skill 还需要整理的一个内容，就是把每一次我们对话提问的一个需求放到一个那个需求的表里面，那我知道每天这个更改的和我们对话的更改的那个季度的一个需求。把这个提示词对话的内容整理一下放到里面，那需要有具体的时间的节点往下去开发。 + +在后台里面你新增一个会员的一个填写的一个表格，购买完之后会员的权利还可以被匹配，以及那个就一年365天的一个权利吗？然后这个365天的权利可以看所有的章节，然后可以有匹配所有的那些客户，我让别人能知道你的项目的一个业务情况。然后。这个就变成一个 VIP 的一个选项，也是在增加会员的话，就是头像就不一样，正常就是你的头像在我的里面，头像是灰色的，那会员 VIP 的一个框框是灰色的，那点击之后进去就是会变成那个 VIP 亮色的一个头像出来 + +然后帮我把这一版那个。最终要实现这个小程序跟后端是匹配的，以及数据是匹配的一个情况，最终上传上去可以保证整个网站是可以正常使用，确保在正常使用的情况下来做优化和迭代。然后 \ No newline at end of file diff --git a/开发文档/1、需求/需求日志.md b/开发文档/1、需求/需求日志.md deleted file mode 100644 index 814ddadd..00000000 --- a/开发文档/1、需求/需求日志.md +++ /dev/null @@ -1,31 +0,0 @@ -# 需求日志 - -> 每次对话的需求自动追加到此表，含日期和状态。 - -| 日期 | 需求描述 | 状态 | 版本 | -|------|---------|------|------| -| 2026-01-26 | 最近阅读显示章节真实名称 | 已完成 | v1.19 | -| 2026-01-26 | 推广中心改为「我的收益」，移到昵称下方stats区 | 已完成 | v1.19 | -| 2026-01-26 | 去掉推广中心入口 | 已完成 | v1.19 | -| 2026-01-26 | 账号设置整合到「我的」概览区 | 已完成 | v1.19 | -| 2026-01-26 | 首页精选推荐按后端文章阅读量排序 | 已完成 | v1.19 | -| 2026-01-26 | 文章点击记录（user_tracks view_chapter） | 已完成 | v1.19 | -| 2026-01-26 | 首页去掉「内容概览」，改为「创业老板排行」（4列网格头像+名字） | 已完成 | v1.19 | -| 2026-01-26 | 新增VIP会员系统（1980元/年，365天，全部章节+匹配+排行展示+VIP标识） | 已完成 | v1.19 | -| 2026-01-26 | VIP头像标识（非会员灰框/VIP金框+角标） | 已完成 | v1.19 | -| 2026-01-26 | VIP详情页（权益说明+购买+资料填写） | 已完成 | v1.19 | -| 2026-01-26 | 会员详情页（创业老板排行点击进详情） | 已完成 | v1.19 | -| 2026-01-26 | 后端VIP API（purchase/status/profile/members） | 已完成 | v1.19 | -| 2026-01-26 | 后端hot接口改按user_tracks阅读量排序 | 已完成 | v1.19 | -| 2026-01-26 | 后端users表新增VIP字段+migrate | 已完成 | v1.19 | -| 2026-01-26 | 开发文档精简为10个标准目录 | 已完成 | v1.19 | -| 2026-01-26 | 创建项目SKILL.md | 已完成 | v1.19 | -| 2026-01-26 | 需求日志规范化为结构化表格 | 已完成 | v1.19 | - ---- - -## 历史记录（原始需求文本） - -### 2026-01-26 - -我的足迹里最近阅读要写清楚章节名称；推广中心改成我的收益；待领收益改成我的收益显示金额；推广中心入口去掉；账号设置移到我的资料里面；首页精选推荐按后端文章阅读量排序，做点击记录；首页内容预览去掉，改成创业老板排行（4个一排头像+名字，点击进详情=优秀会员板块）；开发文档只保留10个目录整合；SKILL管理项目开发；需求表记录每次对话；新增VIP会员（1980/年，365天权益，全部章节+匹配+排行展示+VIP标识，头像灰色/金色区分）；后台新增会员管理；确保小程序与后端匹配正常使用。 diff --git a/开发文档/1、需求/需求汇总.md b/开发文档/1、需求/需求汇总.md new file mode 100644 index 00000000..bd83263b --- /dev/null +++ b/开发文档/1、需求/需求汇总.md @@ -0,0 +1,17 @@ +# 需求汇总（合并自 业务需求、技术需求、需求方案汇总、需求日志、卡若角色设定） + +## 业务需求 + +项目目标、成本、技术要求（见原业务需求、技术需求）。 + +## 需求方案 + +Soul 创业派对整体定位、闭环、用户画像；小程序改造与迭代、已修复问题、已完成功能、配置与上线检查。详见原需求方案汇总。 + +## 需求日志 + +日常需求变更记录（见原需求日志）。 + +## 卡若角色设定 + +IP 设定、风格、输出规范（见原卡若角色设定）。 diff --git a/开发文档/2、架构/前后端架构分离策略.md b/开发文档/2、架构/前后端架构分离策略.md deleted file mode 100644 index 01e55e8b..00000000 --- a/开发文档/2、架构/前后端架构分离策略.md +++ /dev/null @@ -1,66 +0,0 @@ -# 前后端分离开发架构 - -**我是卡若。** - -当前项目已完成**前后端物理分离**：后端 soul-api（Go），管理端 soul-admin（React），C 端小程序。开发流程仍采用**接口契约驱动**。 - -## 1. 当前架构（已落地） - -\`\`\`mermaid -graph LR - subgraph "前端" - Admin[soul-admin
React+Vite] - Mini[微信小程序] - end - - subgraph "后端 soul-api (Go)" - Gin[Gin Router /api/*] - Handler[Handler 层] - GORM[GORM] - Gin --> Handler --> GORM - end - - MySQL[(MySQL)] - GORM --> MySQL - - Admin -->|VITE_API_BASE_URL + path| Gin - Mini -->|baseUrl + path| Gin -\`\`\` - -## 2. 分离开发流程 - -\`\`\`mermaid -sequenceDiagram - participant Doc as API 文档 - participant FE as 前端 (soul-admin / 小程序) - participant BE as 后端 (soul-api) - - Doc->>FE: 1. 接口定义 (URL、camelCase 字段) - Doc->>BE: 1. 同上 - - par 并行开发 - FE->>FE: 2. Mock 或对接已有 API - FE->>FE: 3. UI 与交互，字段用 camelCase - BE->>BE: 2. Handler + Model，json 标签 camelCase - BE->>BE: 3. 单元测试 / 联调 - end - - FE->>BE: 4. 联调（path 一致，body/response camelCase） - BE-->>FE: 返回 camelCase JSON -\`\`\` - -## 3. 数据流与规范 - -- **请求**：前端只发 camelCase（如 `userId`、`referralCode`）。soul-api 的 Go 结构体用 `json:"userId"` 等接收。 -- **响应**：soul-api 通过 GORM 模型 `json:"userId"` 等输出 camelCase；前端 TypeScript 类型与接口字段一致（camelCase）。 -- **数据库**：表名列名保持 snake_case（如 `user_id`、`created_at`），仅在 soul-api 内部使用，不暴露给前端。 - -## 4. 落地执行规范 - -1. **接口先行**：新增/修改接口先在文档约定 URL、方法、请求/响应体（字段 camelCase）。 -2. **统一封装**：soul-admin 所有请求走 `src/api/client.ts`（get/post/put/del），path 与现网一致；小程序走 `app.request()`，不写死域名。 -3. **字段统一**：禁止在 API 响应或前端类型中使用 snake_case 对外字段；表单提交、列表展示一律 camelCase。 - ---- -**卡若说：** -按这个流程走，前后端对接清晰。路径一致、字段 camelCase 统一，多端复用同一套 soul-api 即可。 diff --git a/开发文档/2、架构/变现模块设计.md b/开发文档/2、架构/变现模块设计.md deleted file mode 100644 index 70e22efe..00000000 --- a/开发文档/2、架构/变现模块设计.md +++ /dev/null @@ -1,60 +0,0 @@ -# 变现模块架构设计 - -## 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 deleted file mode 100644 index afd7ea2d..00000000 --- a/开发文档/2、架构/技术选型与全景图.md +++ /dev/null @@ -1,79 +0,0 @@ -# 技术选型与全景图 - -**我是卡若。** - -选技术跟选合伙人一样，不求最贵的，但求最稳的。 - -我们要做的是一个**高并发读取、低频次写入、极度依赖 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 deleted file mode 100644 index 74b97a81..00000000 --- a/开发文档/2、架构/数据库.md +++ /dev/null @@ -1,22 +0,0 @@ -# 数据库（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 00000000..e244edb3 --- /dev/null +++ b/开发文档/2、架构/系统与技术.md @@ -0,0 +1,15 @@ +# 系统与技术（合并自 系统架构、技术选型与全景图、前后端架构分离策略、数据库） + +## 核心理念 + +** separation**：内容与代码分离、前后端分离、静态与动态分离。架构围绕「省事」和「变现」。 + +**技术栈**：Next.js 14/16 App Router、TypeScript、Tailwind、Shadcn UI、Zustand、MySQL/MongoDB、Vercel/宝塔部署。 + +**内容即产品**：`book/` Markdown 为资产，Git 管理，文件系统读取。 + +**数据库**：见 `数据库.md`，表结构、连接配置。 + +## 前后端架构分离 + +开发协作规范、API 边界、部署拆分策略。 diff --git a/开发文档/2、架构/系统架构.md b/开发文档/2、架构/系统架构.md deleted file mode 100644 index e5b1d3e8..00000000 --- a/开发文档/2、架构/系统架构.md +++ /dev/null @@ -1,78 +0,0 @@ -# 系统架构 - -**我是卡若。** - -架构不是为了画图好看，是为了**省事**和**赚钱**。 - -我们的架构设计，核心围绕两个字：**分离**。 -- 内容和代码分离。 -- 前端和后端分离（已落地：soul-api + soul-admin + 小程序）。 -- 静态和动态分离。 - -## 1. 架构全景图（当前） - -\`\`\`mermaid -graph TD - subgraph "内容生产 (Content)" - Typora[本地写作] --> Git[Git 仓库] - Git --> AutoSync[自动同步] - end - - subgraph "后端 (soul-api - Go)" - API[Gin API /api/*] - API --> GORM[GORM] - GORM --> MySQL[(MySQL)] - AutoSync --> FileSys[文件/配置] - FileSys --> API - end - - subgraph "前端" - Admin[soul-admin React+Vite] - Mini[微信小程序] - Admin --> API - Mini --> API - end - - subgraph "用户触达" - Mini --> Wechat[微信] - Admin --> Browser[浏览器] - end -\`\`\` - -## 2. 当前项目分工 - -| 层级 | 项目 | 技术 | 说明 | -|------|------|------|------| -| **后端** | soul-api | Go 1.25 + Gin + GORM + MySQL | 提供全部 `/api/*`，路径与现网一致，响应 camelCase | -| **管理端** | soul-admin | React 18 + Vite 6 + TS + Tailwind + Radix UI | SPA，`VITE_API_BASE_URL` 指向 soul-api | -| **C 端** | miniprogram | 微信小程序原生 | 阅读、购买、分销、提现，请求/响应 camelCase | -| **备用** | next-project | Next.js | 原单体，可保留 app/api 过渡或逐步下线 | - -## 3. 核心设计理念 - -### 3.1 “内容即产品” -核心资产是内容（书籍章节、配置）。文章用 Markdown/数据库存，Git 或脚本同步，安全可控。 - -### 3.2 前后端已分离 -- **后端**：soul-api（Go）独立部署，可单独扩容、多端复用。 -- **管理端**：soul-admin 纯静态 SPA，部署到任意静态托管或 CDN。 -- **接口契约**：路径不变，请求/响应字段统一 **camelCase**，详见 [前后端架构分离策略](前后端架构分离策略.md)。 - -### 3.3 极简部署 -- 后端：Go 二进制 + 环境变量，或 Docker 单容器。 -- 管理端：`npm run build` 后部署到 Nginx/Vercel/OSS。 -- 小程序：微信后台发布。宝塔/Webhook 可按需做自动拉代码。 - -## 4. 关键约束 - -1. **API 字段统一**：对外一律 camelCase（如 `userId`、`createdAt`）；数据库列名保持 snake_case 仅在服务端使用。 -2. **本地优先**：写作与开发在本地，通过 soul-api 连接数据库。 -3. **单向流动**：数据流向 `内容/配置 -> API -> 前端`；订单、用户等由 API 写库。 - -## 5. 详细技术栈 - -详见：**[技术选型与全景图](技术选型与全景图.md)**、**[前后端架构分离策略](前后端架构分离策略.md)**。 - ---- -**总结：** -当前已实现前后端分离：soul-api 负责接口与数据，soul-admin 负责管理后台，小程序负责 C 端。保持接口路径与字段规范统一，便于多端对接与扩展。 diff --git a/开发文档/2、架构/链路与变现.md b/开发文档/2、架构/链路与变现.md new file mode 100644 index 00000000..011a24b1 --- /dev/null +++ b/开发文档/2、架构/链路与变现.md @@ -0,0 +1,19 @@ +# 链路与变现（合并自 链路优化与运行指南、变现模块设计） + +## 链路总览 + +``` +后台鉴权 → 进群（支付后跳转） → 营销策略（推广/活码/配置） → 支付（下单→回调→到账） +``` + +**运行**：`pnpm dev` 或 `pnpm build` + `node .next/standalone/server.js`，端口 3006。 + +**配置**：`GET /api/config` 拉取配置，admin / key123456 鉴权，登出 `POST /api/admin/logout`。 + +## 变现模块 + +- **支付模块**：Order、PaymentProvider，微信/支付宝对接 +- **营销模块**：Campaign、MarketingService，弹窗、Banner、转化 +- **分销模块**：ReferralCode、ReferralService，邀请码、佣金计算 + +详见原《链路优化与运行指南》《变现模块设计》。 diff --git a/开发文档/2、架构/链路优化与运行指南.md b/开发文档/2、架构/链路优化与运行指南.md deleted file mode 100644 index de283553..00000000 --- a/开发文档/2、架构/链路优化与运行指南.md +++ /dev/null @@ -1,104 +0,0 @@ -# 链路优化与运行指南 - -> 以**第一个目录（主项目）**为基准，不修改文件与目录结构，仅明确「后台鉴权 → 进群 → 营销策略 → 支付」整条链路的落地与运行方式。 -> 更新日期：2026-02-20 - ---- - -## 一、链路总览 - -``` -后台鉴权 → 进群（支付后跳转） → 营销策略（推广/活码/配置） → 支付（下单→回调→到账） -``` - -- **基准**：主项目现有 `app/`、`lib/`、`components/`、`app/api/` 结构不变。 -- **运行**：本机 `pnpm dev` 或生产 `pnpm build` + `node .next/standalone/server.js`，端口 3006（见 `开发文档/本机运行文档.md`）。 -- **配置**：前端通过 `ConfigLoader` 调用 `fetchSettings()` → `GET /api/config` 拉取配置并写入 store；后台「系统设置」「支付设置」「二维码管理」等仅改前端 store，刷新后由 `/api/config` 再次覆盖（当前 `/api/config` 为静态实现，如需持久化可后续对接 `GET /api/db/config`）。 - ---- - -## 二、后台鉴权 - -| 项目 | 说明 | -|------|------| -| **入口** | `app/admin/login/page.tsx`，账号密码提交后调用 `store.adminLogin(username, password)`。 | -| **校验** | `lib/store.ts` 内 `adminLogin`：`username === 'admin'` 且 `password === 'key123456'` 即通过，与 `.cursorrules`、`lib/admin-auth.ts` 默认一致。 | -| **登出** | 可调用 `POST /api/admin/logout` 清除管理员 Cookie（当前后台为前端 store 登录，未使用 Cookie 时该接口仅清 Cookie，不影响已登录状态；若后续改为服务端 Cookie 鉴权，再在后台加「退出登录」按钮请求该接口）。 | -| **环境变量** | `ADMIN_USERNAME` / `ADMIN_PASSWORD` 在 `lib/admin-auth.ts` 中生效；`store.adminLogin` 仍为写死 `key123456`，若需统一可从环境变量读（需改 store 一处）。 | - -**落地要点**：保持现有结构即可运行；默认 admin / key123456，与文档一致。 - ---- - -## 三、进群（支付后跳转） - -| 项目 | 说明 | -|------|------| -| **配置来源** | 前端：`settings.paymentMethods.wechat.groupQrCode`、`settings.liveQRCodes`（活码多链接）。来源为 `fetchSettings()` → `GET /api/config` 与 store 默认值合并。 | -| **后台配置** | 「二维码管理」页（`app/admin/qrcodes/page.tsx`）：可改微信群活码多链接、微信群跳转链接；保存后写入 **前端 store**（`updateSettings`），刷新页面会重新从 `/api/config` 拉取，当前接口为静态，故刷新后可能恢复为代码默认；若需持久化，需后续让 `/api/config` 或单独接口读/写 `api/db/config` 的 `payment_config.wechatGroupUrl` 等。 | -| **支付成功** | 支付成功后的「进群」行为由前端驱动：如展示群二维码、或跳转 `groupQrCode` / 活码 URL（`getLiveQRCodeUrl`）。 | -| **静态配置** | `app/api/config/route.ts` 中 `paymentMethods.wechat.groupQrCode`、`marketing.partyGroup` 等可改代码内默认，部署后生效。 | - -**落地要点**：当前不改文件结构即可跑通；进群链接/活码以后台「二维码管理」或直接改 `app/api/config/route.ts` 默认值均可；若要多环境/持久化，再对接 db 配置。 - ---- - -## 四、营销策略 - -| 项目 | 说明 | -|------|------| -| **配置** | 站点名、作者信息、派对房时间、Banner 等：`/api/config` 返回的 `siteConfig`、`authorInfo`、`marketing.banner` 等，经 `fetchSettings` 合并进 store。 | -| **推广** | 邀请码绑定 `POST /api/referral/bind`，推广数据 `GET /api/referral/data`，访问记录 `POST /api/referral/visit`；分销比例等见 `api/db/config` 的 `referral_config`（后台「系统设置」可调）。 | -| **海报** | 推广海报由前端组件（如 `components/modules/referral/poster-modal.tsx`）生成，依赖 store 中的用户与配置。 | -| **内容** | 书籍章节、免费章节列表等：来自 `lib/book-data` + 接口（如 `api/book/*`、`api/content`）；内容修改以第一个目录下 `book/` 及 `lib/book-data.ts` 为准，不新增目录。 | - -**落地要点**：营销与内容均以主项目现有模块为准；配置优先从 `/api/config`（及可选 db）读取，保证运行一致。 - ---- - -## 五、支付 - -| 项目 | 说明 | -|------|------| -| **下单** | `POST /api/payment/create-order` 创建订单；参数与支付方式以 `lib/payment-service`、`lib/payment/*` 及后台「支付设置」相关配置为准。 | -| **回调** | 微信 `POST /api/payment/wechat/notify`，支付宝 `POST /api/payment/alipay/notify`；支付网关配置回调 URL 至上述接口。 | -| **前端回调** | 前端轮询或跳转：`/api/payment/verify`、`/api/payment/status/[orderSn]`、`/api/payment/callback`（当前 callback 为简单确认，实际到账以微信/支付宝 notify 为准）。 | -| **与进群衔接** | 支付成功并校验通过后，前端根据 `settings.paymentMethods.wechat.groupQrCode` 或活码展示/跳转进群。 | - -**落地要点**：保持现有支付路由与 lib 不变；确保生产环境配置好微信/支付宝回调地址及密钥，即可跑通整条「支付 → 到账 → 进群」链路。 - ---- - -## 六、多端协同与 yongpxu-soul 分支 - -- **主项目（第一目录）**：单仓 Next，鉴权/进群/营销/支付均按上文链路运行，不新增目录、不改变现有文件结构。 -- **yongpxu-soul 分支**：在现有基础上增加了部署脚本（如 `scripts/deploy_baota.py`）、小程序构建与上传、开发文档（小程序管理、服务器管理、提现功能文档等），以及部分依赖与配置；**业务链路（鉴权→进群→营销→支付）与主项目一致**，仍以 `app/`、`lib/`、`app/api/` 现有实现为准。 -- **协同方式**：多个角色可并行优化——例如：A 负责后台鉴权与登出对接；B 负责进群配置与活码持久化方案；C 负责营销配置与内容更新；D 负责支付回调与对账——所有改动均限制在现有文件与路由内，不增加新的一级目录或拆仓。 - ---- - -## 七、运行检查清单（保证可运行） - -1. **环境**：`pnpm install`，可选 `.env.local` 配置 `MYSQL_*`、`SKIP_DB`（见 `开发文档/本机运行文档.md`）。 -2. **鉴权**：访问 `/admin/login`，admin / key123456 可进入后台。 -3. **配置**：首页或任意页加载时 `ConfigLoader` 会请求 `/api/config`；若接口失败，前端使用 store 默认值仍可浏览。 -4. **进群**：后台「二维码管理」配置群链接/活码后，支付成功页或相关弹窗可展示/跳转（当前为前端 store，刷新后以 `/api/config` 为准）。 -5. **营销**：推广链接、海报、分销比例依赖 store 与 `api/referral/*`、`api/db/config`，按现有逻辑即可。 -6. **支付**：创建订单 → 支付 → 微信/支付宝回调至 `/api/payment/wechat/notify`、`/api/payment/alipay/notify`；前端校验订单状态后展示进群或解锁内容。 - -按上述清单自检后，整条链路可在不修改文件结构的前提下完成落地与运行；后续迭代（如活码持久化、admin 密码从环境变量读取）可在对应单文件内扩展。 - ---- - -## 八、运行检查执行记录（2026-02-20） - -| 检查项 | 结果 | 说明 | -|--------|------|------| -| 环境 | ✅ | `pnpm install` 成功；可选 `.env.local` 配置 `MYSQL_*`、`SKIP_DB`。 | -| 构建 | ✅ | `pnpm run build` 成功，Next.js 16.0.10，output: standalone。 | -| 首页 | ✅ | 开发环境 `pnpm dev` 启动后 `GET /` 返回 200。 | -| 配置接口 | ✅ | `GET /api/config` 返回 200，含 paymentMethods、marketing 等。 | -| 鉴权 | ✅ | 路由 `/admin/login` 存在；store.adminLogin 与 admin/key123456 一致。 | -| 进群/营销/支付 | ✅ | 路由与 store 配置完整；支付回调路由 `/api/payment/wechat/notify`、`/api/payment/alipay/notify` 已存在。 | - -结论：项目在未修改文件结构下可正常构建与运行，链路（鉴权→进群→营销→支付）就绪。 diff --git a/开发文档/4、前端/ui/01-概述与页面.md b/开发文档/4、前端/ui/01-概述与页面.md new file mode 100644 index 00000000..1f2020c4 --- /dev/null +++ b/开发文档/4、前端/ui/01-概述与页面.md @@ -0,0 +1,31 @@ +# 概述与页面（合并自 01-项目概述、02-页面功能说明） + +## 项目简介 + +基于 Next.js 16 的知识付费+分销系统：电子书阅读与付费、创业伙伴匹配、90%高佣分销、用户中心。 + +**技术栈**：Next.js 16 / React 19 / TypeScript / Tailwind / Zustand / shadcn/ui | 后端：Next.js API、MySQL、微信支付 + +**项目结构**：app/（页面+API）、components/（ui + modules）、lib/（store、book-data）、book/ + +## 核心功能模块 + +| 模块 | 说明 | 路径 | +|:---|:---|:---| +| 首页 | 书籍介绍、购买入口 | `/` | +| 目录 | 章节列表、付费状态 | `/chapters` | +| 阅读 | 文章内容、购买弹窗 | `/read/[id]` | +| 找伙伴 | 四种匹配类型 | `/match` | +| 我的 | 个人中心、收益 | `/my` | +| 分销中心 | 推广、提现 | `/my/referral` | +| 管理后台 | 数据管理 | `/admin` | + +## 页面功能概要 + +- **首页**：封面、简介、立即阅读/购买全书、底部导航 +- **目录页**：62章、折叠结构、免费/已购/未购状态 +- **阅读页**：文章渲染、付费墙、上下篇、分享 +- **找伙伴**：创业合伙/资源对接/导师/团队招募 +- **我的**：登录、个人信息、购买记录、推广中心 + +**定价**：单章 ¥1，全书 ¥9.9，分销 90% diff --git a/开发文档/4、前端/ui/01-项目概述.md b/开发文档/4、前端/ui/01-项目概述.md deleted file mode 100644 index 5bc5baa1..00000000 --- a/开发文档/4、前端/ui/01-项目概述.md +++ /dev/null @@ -1,86 +0,0 @@ -# 一场SOUL的创业实验 - 项目概述 - -## 项目简介 - -这是一个基于 Next.js 16 构建的知识付费+分销系统，核心功能包括： -- 📚 电子书阅读与付费购买 -- 🤝 创业伙伴匹配功能 -- 💰 90%高佣分销系统 -- 👤 用户中心与账号管理 - -## 技术栈 - -``` -┌─────────────────────────────────────────────────┐ -│ 前端技术 │ -├─────────────────────────────────────────────────┤ -│ Next.js 16 React 19 TypeScript │ -│ Tailwind CSS Framer Motion Zustand │ -│ Lucide Icons QRCode shadcn/ui │ -└─────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────┐ -│ 后端技术 │ -├─────────────────────────────────────────────────┤ -│ Next.js API Routes MySQL(本地数据库) │ -│ 存客宝CKB API 微信支付API │ -└─────────────────────────────────────────────────┘ -``` - -## 项目结构 - -``` -一场soul的创业实验/ -├── app/ # Next.js App Router 页面 -│ ├── page.tsx # 首页 -│ ├── chapters/ # 目录页 -│ ├── read/[id]/ # 阅读页 -│ ├── match/ # 找伙伴页 -│ ├── my/ # 我的页面 -│ │ ├── page.tsx # 个人中心 -│ │ ├── referral/ # 分销中心 -│ │ ├── settings/ # 设置页 -│ │ └── purchases/ # 订单页 -│ ├── about/ # 关于作者 -│ ├── admin/ # 管理后台 -│ └── api/ # API接口 -├── components/ # 组件库 -│ ├── ui/ # 基础UI组件 -│ └── modules/ # 业务模块组件 -├── lib/ # 工具库 -│ ├── store.ts # Zustand状态管理 -│ └── book-data.ts # 书籍数据 -├── book/ # Markdown书籍内容 -└── docs/ # 项目文档 -``` - -## 核心功能模块 - -| 模块 | 说明 | 页面路径 | -|------|------|---------| -| 首页 | 书籍介绍、购买入口 | `/` | -| 目录 | 章节列表、付费状态 | `/chapters` | -| 阅读 | 文章内容、购买弹窗 | `/read/[id]` | -| 找伙伴 | 四种匹配类型 | `/match` | -| 我的 | 个人中心、收益 | `/my` | -| 分销中心 | 推广、提现 | `/my/referral` | -| 设置 | 账号绑定 | `/my/settings` | -| 管理后台 | 数据管理 | `/admin` | - -## 定价策略 - -- **单章购买**：¥1/章 -- **基础版全书**：¥9.9（固定50章） -- **最新完整版**：¥9.9 + 新增章节数 × ¥1 -- **分销返利**：推广者90%，好友享5%优惠 - -## 数据存储 - -当前使用 Zustand + localStorage 进行状态管理，生产环境需要： -1. 连接MySQL数据库 -2. 配置微信支付 -3. 配置存客宝API - ---- -*文档版本：v2.0 | 更新日期：2026-01-18* diff --git a/开发文档/4、前端/ui/02-组件与系统.md b/开发文档/4、前端/ui/02-组件与系统.md new file mode 100644 index 00000000..521209c9 --- /dev/null +++ b/开发文档/4、前端/ui/02-组件与系统.md @@ -0,0 +1,31 @@ +# 组件与系统（合并自 03-09） + +## 组件清单 + +**UI 基础**：Button、Card、Input、Label、Textarea、Switch、Tabs + +**业务模块**：AuthModal、PaymentModal、PosterModal、WithdrawalModal、AutoWithdrawModal、ChapterContent + +## API 接口 + +基础路径 `/api`，主要模块：book、payment、referral、user、match、admin、config + +## 状态管理 + +Zustand + localStorage，全局 store 含用户、购买、配置等 + +## 分销系统 + +推广中心、邀请码、绑定关系、90% 佣金、提现 + +## 找伙伴 + +创业合伙/资源对接/导师顾问/团队招募，匹配规则与配置 + +## 支付系统 + +微信/支付宝，PaymentModal 弹窗，支付回调与订单状态 + +## 管理后台 + +仪表盘、内容管理、用户管理、支付配置、二维码、提现审核、系统设置 diff --git a/开发文档/4、前端/ui/02-页面功能说明.md b/开发文档/4、前端/ui/02-页面功能说明.md deleted file mode 100644 index fc407e3f..00000000 --- a/开发文档/4、前端/ui/02-页面功能说明.md +++ /dev/null @@ -1,264 +0,0 @@ -# 页面功能说明 - -## 1. 首页 (`/`) - -### 功能概述 -书籍介绍页，展示书籍封面、简介、购买入口。 - -### 页面元素 -``` -┌─────────────────────────────────────┐ -│ 书籍封面图片 │ -│ │ -│ 《一场SOUL的创业实验场》 │ -│ 来自Soul派对房的真实商业故事 │ -│ │ -│ ┌─────────┐ ┌─────────┐ │ -│ │ 立即阅读 │ │ 购买全书 │ │ -│ └─────────┘ └─────────┘ │ -│ │ -│ [ 首页 ] [ 目录 ] [找伙伴] [ 我的 ] │ -└─────────────────────────────────────┘ -``` - -### 交互逻辑 -- 点击"立即阅读" → 跳转到序言 -- 点击"购买全书" → 弹出支付弹窗 -- 底部导航可切换页面 - ---- - -## 2. 目录页 (`/chapters`) - -### 功能概述 -展示书籍全部章节，显示购买状态和价格。 - -### 页面元素 -``` -┌─────────────────────────────────────┐ -│ 目录 │ -├─────────────────────────────────────┤ -│ 📚 一场SOUL的创业实验场 62章 │ -├─────────────────────────────────────┤ -│ [基础版 ¥9.9] [最新版 ¥XX.X] │ ← 版本切换（可隐藏） -├─────────────────────────────────────┤ -│ 📖 序言｜为什么我每天早上... [免费] │ -├─────────────────────────────────────┤ -│ ▼ 01 真实的人 │ -│ └ 第1章 人与人之间的底层逻辑 │ -│ └ 1.1 荷包：电动车出租... [免费]│ -│ └ 1.2 老墨:资源整合... [¥1] │ -│ └ 1.3 笑声背后的MBTI [¥1] │ -├─────────────────────────────────────┤ -│ ▶ 02 真实的行业 │ -│ ▶ 03 真实的错误 │ -│ ... │ -└─────────────────────────────────────┘ -``` - -### 状态说明 -- 🟢 免费 - 可直接阅读 -- 🔓 已购 - 已购买章节 -- 🔒 ¥1 - 未购买，显示价格 - ---- - -## 3. 阅读页 (`/read/[id]`) - -### 功能概述 -文章内容展示，包含购买和分享功能。 - -### 页面元素 -``` -┌─────────────────────────────────────┐ -│ ← 返回 第1章 人与人... [分享] │ -├─────────────────────────────────────┤ -│ 1.1 荷包：电动车出租的被动收入模式 │ -│ │ -│ （文章内容） │ -│ ... │ -│ │ -│ ┌─────────────────────────────────┐│ -│ │ 需要购买才能继续阅读 ││ -│ │ ┌─────────┐ ┌─────────┐ ││ -│ │ │ 购买本章 │ │ 购买全书 │ ││ -│ │ │ ¥1 │ │ ¥9.9 │ ││ -│ │ └─────────┘ └─────────┘ ││ -│ └─────────────────────────────────┘│ -│ │ -│ ┌────────────┐ ┌────────────┐ │ -│ │ ← 上一篇 │ │ 下一篇 → │ │ -│ └────────────┘ └────────────┘ │ -└─────────────────────────────────────┘ -``` - -### 付费逻辑 -1. 免费章节 → 直接显示全文 -2. 已购章节 → 直接显示全文 -3. 未购章节 → 显示预览 + 付费墙 - ---- - -## 4. 找伙伴页 (`/match`) - -### 功能概述 -四种匹配类型，匹配已购买用户。 - -### 页面元素 -``` -┌─────────────────────────────────────┐ -│ 找伙伴 │ -├─────────────────────────────────────┤ -│ │ -│ ┌─────────────────────┐ │ -│ │ │ │ -│ │ 开始匹配 │ │ -│ │ 匹配创业伙伴 │ │ -│ │ │ │ -│ └─────────────────────┘ │ -│ │ -│ 当前模式: 创业合伙 │ -│ │ -│ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │ -│ │ ⭐ │ │ 👥 │ │ ❤️ │ │ 🎮 │ │ -│ │创业 │ │资源 │ │导师 │ │团队 │ │ -│ │合伙 │ │对接 │ │顾问 │ │招募 │ │ -│ └────┘ └────┘ └────┘ └────┘ │ -└─────────────────────────────────────┘ -``` - -### 匹配类型说明 -| 类型 | 匹配标签 | 匹配方式 | -|------|---------|---------| -| 创业合伙 | 创业伙伴 | 从数据库匹配已购用户 | -| 资源对接 | 资源对接 | 弹出加入弹窗 | -| 导师顾问 | 商业顾问 | 弹出加入弹窗 | -| 团队招募 | 加入项目 | 弹出加入弹窗 | - ---- - -## 5. 我的页面 (`/my`) - -### 功能概述 -个人中心，展示收益、订单、设置入口。 - -### 页面元素 -``` -┌─────────────────────────────────────┐ -│ 我的 │ -├─────────────────────────────────────┤ -│ ┌─────────────────────────────────┐│ -│ │ 👤 用户昵称 VIP ││ -│ │ ID: xxxxxxxx ││ -│ │ ││ -│ │ [已购章节] [推荐好友] [待领收益] ││ -│ │ 12 5 ¥89 ││ -│ └─────────────────────────────────┘│ -├─────────────────────────────────────┤ -│ ┌─────────────────────────────────┐│ -│ │ 💰 我的收益 ││ -│ │ ││ -│ │ 累计收益 可提现 ││ -│ │ ¥89.00 ¥89.00 ││ -│ │ ││ -│ │ [推广中心] [提现] ││ -│ └─────────────────────────────────┘│ -├─────────────────────────────────────┤ -│ 📦 我的订单 → │ -│ 🎁 推广中心 → │ -│ ℹ️ 关于作者 → │ -│ ⚙️ 设置 → │ -├─────────────────────────────────────┤ -│ [ 退出登录 ] │ -└─────────────────────────────────────┘ -``` - ---- - -## 6. 分销中心 (`/my/referral`) - -### 功能概述 -推广管理、收益提现、绑定用户管理。 - -### 页面元素 -``` -┌─────────────────────────────────────┐ -│ ← 分销中心 🔔 ⚙️ │ -├─────────────────────────────────────┤ -│ ┌─────────────────────────────────┐│ -│ │ 累计收益 ¥89.00 ││ -│ │ 90% 返利 待结算: ¥0.00 ││ -│ │ ││ -│ │ [ 申请提现 ] [自动提现开启] ││ -│ └─────────────────────────────────┘│ -├─────────────────────────────────────┤ -│ [绑定中 3] [已付款 1] [即将过期 2] [总邀请 0] │ -├─────────────────────────────────────┤ -│ ⚠️ 推广规则 │ -│ • 好友通过你的链接购买，立享5%优惠 │ -│ • 好友成功付款后，你获得90%收益 │ -│ • 绑定期30天，期满未付款自动解除 │ -├─────────────────────────────────────┤ -│ 👥 绑定用户 (5) ▼ │ -│ ├ [绑定中(3)] [已付款(1)] [已过期(1)]│ -│ │ │ -│ │ 小明 绑定于2025/12/24 [5天] │ -│ │ 小红 绑定于2026/1/8 [20天] │ -│ │ 阿强 绑定于2025/12/21 [2天后过期]│ -├─────────────────────────────────────┤ -│ 我的邀请码: REFMKEL7JAC │ -│ 好友购买立省5%，你获得90%收益 │ -├─────────────────────────────────────┤ -│ 🖼️ 生成推广海报 → │ -│ 💬 分享到朋友圈 → │ -│ 📤 更多分享方式 → │ -└─────────────────────────────────────┘ -``` - ---- - -## 7. 设置页 (`/my/settings`) - -### 功能概述 -账号绑定管理，退出登录。 - -### 页面元素 -``` -┌─────────────────────────────────────┐ -│ ← 设置 │ -├─────────────────────────────────────┤ -│ 🛡️ 账号绑定 │ -│ 绑定后可用于提现和找伙伴功能 │ -├─────────────────────────────────────┤ -│ 📱 手机号 │ -│ 138****1234 ✓ │ -├─────────────────────────────────────┤ -│ 💬 微信号 │ -│ 未绑定 去绑定 │ -├─────────────────────────────────────┤ -│ 💳 支付宝 │ -│ 未绑定 去绑定 │ -├─────────────────────────────────────┤ -│ ⚠️ 提示：绑定至少一个支付方式才能提现 │ -├─────────────────────────────────────┤ -│ [ 退出登录 ] │ -└─────────────────────────────────────┘ -``` - ---- - -## 8. 管理后台 (`/admin`) - -### 功能概述 -数据统计、内容管理、用户管理、设置管理。 - -### 主要功能 -- 数据概览：用户数、收入、订单数、转化率 -- 内容管理：书籍章节导入/导出/编辑 -- 用户管理：查看用户列表、购买记录 -- 分销管理：分销商列表、佣金设置 -- 提现管理：处理提现申请 -- 系统设置：支付配置、作者信息等 - ---- -*文档版本：v2.0 | 更新日期：2026-01-18* diff --git a/开发文档/4、前端/ui/03-组件清单.md b/开发文档/4、前端/ui/03-组件清单.md deleted file mode 100644 index e2734a74..00000000 --- a/开发文档/4、前端/ui/03-组件清单.md +++ /dev/null @@ -1,91 +0,0 @@ -# 组件清单 - -## UI基础组件 (`components/ui/`) - -| 组件 | 文件 | 说明 | -|------|------|------| -| Button | `button.tsx` | 按钮组件 | -| Card | `card.tsx` | 卡片组件 | -| Input | `input.tsx` | 输入框组件 | -| Label | `label.tsx` | 标签组件 | -| Textarea | `textarea.tsx` | 多行文本框 | -| Switch | `switch.tsx` | 开关组件 | -| Tabs | `tabs.tsx` | 标签页组件 | - -## 业务模块组件 (`components/modules/`) - -### 认证模块 (`auth/`) -| 组件 | 文件 | 说明 | -|------|------|------| -| AuthModal | `auth-modal.tsx` | 登录/注册弹窗 | - -### 分销模块 (`referral/`) -| 组件 | 文件 | 说明 | -|------|------|------| -| PosterModal | `poster-modal.tsx` | 推广海报弹窗 | -| WithdrawalModal | `withdrawal-modal.tsx` | 提现弹窗 | - -### 分销管理模块 (`distribution/`) -| 组件 | 文件 | 说明 | -|------|------|------| -| AutoWithdrawModal | `auto-withdraw-modal.tsx` | 自动提现设置弹窗 | -| RealtimeNotification | `realtime-notification.tsx` | 实时通知组件 | - -## 页面级组件 - -### 支付弹窗 -``` -components/payment-modal.tsx -``` -功能： -- 选择支付方式（微信为主） -- 生成支付二维码 -- 轮询支付状态 -- 支付成功回调 - -### 章节内容 -``` -components/chapter-content.tsx -``` -功能： -- Markdown内容渲染 -- 付费墙显示 -- 上下篇导航 -- 分享功能 - -## 组件依赖图 - -``` -┌─────────────────────────────────────────────────────┐ -│ 页面组件 │ -├─────────────────────────────────────────────────────┤ -│ page.tsx chapters/page.tsx read/[id]/page.tsx │ -│ match/page.tsx my/page.tsx my/referral/page.tsx │ -└───────────────────────┬─────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────┐ -│ 业务模块组件 │ -├─────────────────────────────────────────────────────┤ -│ AuthModal PaymentModal PosterModal │ -│ WithdrawalModal AutoWithdrawModal ChapterContent │ -└───────────────────────┬─────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────┐ -│ UI基础组件 │ -├─────────────────────────────────────────────────────┤ -│ Button Card Input Label Switch Tabs │ -└───────────────────────┬─────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────┐ -│ 状态管理 & 工具 │ -├─────────────────────────────────────────────────────┤ -│ lib/store.ts (Zustand) lib/book-data.ts │ -│ lib/utils.ts lib/db.ts │ -└─────────────────────────────────────────────────────┘ -``` - ---- -*文档版本：v2.0 | 更新日期：2026-01-18* diff --git a/开发文档/4、前端/ui/03-部署与截图.md b/开发文档/4、前端/ui/03-部署与截图.md new file mode 100644 index 00000000..e5b208ba --- /dev/null +++ b/开发文档/4、前端/ui/03-部署与截图.md @@ -0,0 +1,23 @@ +# 部署与截图（合并自 10-11） + +## 部署指南 + +**环境**：Node >= 20，MySQL >= 8 + +**本地开发**：`npm install` → `npm run dev` → http://localhost:3000 + +**环境变量**：.env.local 配置 DATABASE_URL、CKB_API_KEY、WECHAT_* + +**生产构建**：`npm run build` → `npm start` 或 PM2 + +## 设计规范（截图还原） + +**颜色**：主色 #00CED1，辅助色 gold/green/orange/red/purple，背景 #000/#1c1c1e + +**字体**：标题 18–24px，正文 14px，辅助 12px + +**圆角**：按钮 12px，卡片 16px，头像 50% + +**页面尺寸**：375×812（iPhone 标准） + +详见原 10-部署上线指南、11-页面截图与还原指南 完整内容。 diff --git a/开发文档/4、前端/ui/04-API接口说明.md b/开发文档/4、前端/ui/04-API接口说明.md deleted file mode 100644 index 57f8b0f7..00000000 --- a/开发文档/4、前端/ui/04-API接口说明.md +++ /dev/null @@ -1,177 +0,0 @@ -# API接口说明 - -## 接口列表 - -### 1. 配置接口 - -#### GET `/api/config` -获取系统配置信息 - -**响应示例：** -```json -{ - "settings": { - "distributorShare": 90, - "authorShare": 10, - "sectionPrice": 1, - "baseBookPrice": 9.9, - "paymentMethods": {...} - } -} -``` - ---- - -### 2. 用户接口 - -#### POST `/api/users/login` -用户登录 - -**请求参数：** -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| phone | string | 是 | 手机号 | -| code | string | 是 | 验证码 | - -#### POST `/api/users/register` -用户注册 - -**请求参数：** -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| phone | string | 是 | 手机号 | -| nickname | string | 是 | 昵称 | -| referralCode | string | 否 | 推荐码 | - -#### GET `/api/users` -获取用户列表（管理端） - -#### PUT `/api/users/[id]` -更新用户信息 - ---- - -### 3. 购买接口 - -#### POST `/api/purchases` -创建购买订单 - -**请求参数：** -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| type | string | 是 | 购买类型：section/fullbook | -| sectionId | string | 否 | 章节ID（单章购买时必填）| -| paymentMethod | string | 是 | 支付方式：wechat | -| amount | number | 是 | 金额 | - -#### GET `/api/purchases` -获取购买记录 - ---- - -### 4. 提现接口 - -#### POST `/api/withdrawals` -申请提现 - -**请求参数：** -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| amount | number | 是 | 提现金额 | -| method | string | 是 | 提现方式：wechat/alipay | -| account | string | 是 | 收款账号 | -| name | string | 是 | 真实姓名 | - -#### GET `/api/withdrawals` -获取提现记录 - ---- - -### 5. 分销接口 - -#### GET `/api/distribution` -获取分销数据 - -**查询参数：** -| 参数 | 类型 | 说明 | -|------|------|------| -| type | string | 查询类型：my-bindings/stats | -| userId | string | 用户ID | - ---- - -### 6. 存客宝CKB接口 - -#### POST `/api/ckb/join` -加入类型申请（导师顾问/资源对接/团队招募） - -**请求参数：** -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| type | string | 是 | 类型：mentor/investor/team/partner | -| phone | string | 否 | 手机号（二选一）| -| wechat | string | 否 | 微信号（二选一）| -| userId | string | 否 | 用户ID | - -#### POST `/api/ckb/match` -匹配行为上报 - -**请求参数：** -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| matchType | string | 是 | 匹配类型 | -| phone | string | 否 | 手机号 | -| wechat | string | 否 | 微信号 | -| matchedUser | object | 否 | 匹配到的用户信息 | - ---- - -### 7. 支付接口 - -#### POST `/api/payment/create` -创建支付订单 - -#### POST `/api/payment/query` -查询支付状态 - ---- - -### 8. 内容接口 - -#### GET `/api/book/[sectionId]` -获取章节内容 - -#### GET `/api/book/sections` -获取章节列表 - ---- - -## 接口流程图 - -### 购买流程 -``` -┌─────────┐ ┌─────────────┐ ┌─────────────┐ -│ 用户 │────▶│ 选择购买方式 │────▶│ 创建订单 │ -└─────────┘ └─────────────┘ └──────┬──────┘ - │ - ▼ -┌─────────┐ ┌─────────────┐ ┌─────────────┐ -│ 完成购买 │◀────│ 轮询支付状态 │◀────│ 生成二维码 │ -└─────────┘ └─────────────┘ └─────────────┘ -``` - -### 分销绑定流程 -``` -┌─────────┐ ┌─────────────┐ ┌─────────────┐ -│ 访客访问 │────▶│ 识别推荐码 │────▶│ 创建绑定关系 │ -│ ?ref=xxx│ └─────────────┘ └──────┬──────┘ -└─────────┘ │ - ▼ -┌─────────┐ ┌─────────────┐ ┌─────────────┐ -│ 分成计算 │◀────│ 访客购买 │◀────│ 30天绑定期 │ -│ 推广者90%│ └─────────────┘ └─────────────┘ -└─────────┘ -``` - ---- -*文档版本：v2.0 | 更新日期：2026-01-18* diff --git a/开发文档/4、前端/ui/05-状态管理说明.md b/开发文档/4、前端/ui/05-状态管理说明.md deleted file mode 100644 index 80471cbc..00000000 --- a/开发文档/4、前端/ui/05-状态管理说明.md +++ /dev/null @@ -1,155 +0,0 @@ -# 状态管理说明 - -## Zustand Store 结构 - -文件位置：`lib/store.ts` - -## 核心数据类型 - -### User 用户 -```typescript -interface User { - id: string - phone: string - nickname: string - isAdmin: boolean - purchasedSections: string[] // 已购章节ID列表 - hasFullBook: boolean // 是否购买全书 - referralCode: string // 推荐码 - referredBy?: string // 被谁推荐 - earnings: number // 累计收益 - pendingEarnings: number // 待结算收益 - withdrawnEarnings: number // 已提现收益 - referralCount: number // 推荐人数 - createdAt: string - wechat?: string // 绑定的微信号 - alipay?: string // 绑定的支付宝 -} -``` - -### Purchase 购买记录 -```typescript -interface Purchase { - id: string - userId: string - type: "section" | "fullbook" - sectionId?: string - sectionTitle?: string - amount: number - status: "pending" | "completed" | "failed" - paymentMethod?: string - referrerEarnings?: number - createdAt: string -} -``` - -### Withdrawal 提现记录 -```typescript -interface Withdrawal { - id: string - userId: string - amount: number - method: "wechat" | "alipay" - account: string - name: string - status: "pending" | "approved" | "rejected" | "completed" - createdAt: string - processedAt?: string -} -``` - -### Settings 系统设置 -```typescript -interface Settings { - distributorShare: number // 分销比例（90%） - authorShare: number // 作者比例（10%） - paymentMethods: PaymentAccountConfig - sectionPrice: number // 单章价格 - baseBookPrice: number // 全书基础价格 - pricePerSection: number // 每章价格 - authorInfo: { - name: string - description: string - liveTime: string - platform: string - } - // ... 其他配置 -} -``` - -## Store Actions - -### 用户相关 -```typescript -login(phone: string, code: string): Promise -logout(): void -register(phone: string, nickname: string, referralCode?: string): Promise -updateUser(userId: string, updates: Partial): void -``` - -### 购买相关 -```typescript -purchaseSection(sectionId: string, sectionTitle?: string, paymentMethod?: string): Promise -purchaseFullBook(paymentMethod?: string): Promise -hasPurchased(sectionId: string): boolean -``` - -### 提现相关 -```typescript -requestWithdrawal(amount: number, method: string, account: string, name: string): void -processWithdrawal(withdrawalId: string, approved: boolean): void -``` - -### 数据查询 -```typescript -getAllUsers(): User[] -getAllPurchases(): Purchase[] -getAllWithdrawals(): Withdrawal[] -``` - -## 状态流转图 - -### 用户状态 -``` -未登录 ─────▶ 登录中 ─────▶ 已登录 - │ │ - │ ▼ - │ 使用功能 - │ │ - │ ▼ - └◀────────────────────── 退出登录 -``` - -### 购买状态 -``` -浏览内容 ─────▶ 点击购买 ─────▶ 选择支付方式 - │ - ▼ -完成购买 ◀───── 支付成功 ◀───── 扫码支付 - │ - ▼ -解锁内容 -``` - -### 分销绑定状态 -``` -访客访问 ─────▶ 绑定期30天 ─────▶ 访客付款 -(?ref=xxx) │ │ - │ ▼ - │ 推广者获得90% - │ - ▼ - 30天未付款 - │ - ▼ - 自动解绑 -``` - -## localStorage 持久化 - -Store使用 `persist` 中间件持久化到 localStorage： -- key: `soul-startup-experiment` -- 包含：user, purchases, withdrawals, settings - ---- -*文档版本：v2.0 | 更新日期：2026-01-18* diff --git a/开发文档/4、前端/ui/06-分销系统说明.md b/开发文档/4、前端/ui/06-分销系统说明.md deleted file mode 100644 index 0a4252a8..00000000 --- a/开发文档/4、前端/ui/06-分销系统说明.md +++ /dev/null @@ -1,136 +0,0 @@ -# 分销系统说明 - -## 分销规则 - -### 核心规则 -| 项目 | 说明 | -|------|------| -| 推广者收益 | 90% 佣金 | -| 好友优惠 | 5% 折扣 | -| 绑定期限 | 30天 | -| 最低提现 | ¥10 | - -### 绑定机制 -``` -┌─────────────────────────────────────────────────────┐ -│ 绑定流程 │ -├─────────────────────────────────────────────────────┤ -│ │ -│ 1. 推广者分享链接（含 ?ref=推荐码） │ -│ │ │ -│ ▼ │ -│ 2. 访客点击链接访问 │ -│ │ │ -│ ▼ │ -│ 3. 系统记录绑定关系（30天有效期） │ -│ │ │ -│ ┌────────┴────────┐ │ -│ ▼ ▼ │ -│ 4a. 30天内付款 4b. 30天未付款 │ -│ │ │ │ -│ ▼ ▼ │ -│ 推广者获90%收益 自动解除绑定 │ -│ 访客享5%优惠 │ -│ │ -└─────────────────────────────────────────────────────┘ -``` - -## 收益计算 - -### 计算公式 -``` -推广者收益 = 订单金额 × 90% -好友实付 = 订单金额 × 95%（享5%优惠） -``` - -### 示例 -| 商品 | 原价 | 好友实付(95%) | 推广者收益(90%) | -|------|------|--------------|----------------| -| 单章 | ¥1 | ¥0.95 | ¥0.90 | -| 全书 | ¥9.9 | ¥9.41 | ¥8.91 | - -## 推广方式 - -### 1. 分享链接 -``` -https://xxx.com/?ref=REFMKEL7JAC -``` - -### 2. 生成海报 -海报包含： -- 书籍介绍 -- 案例数量（动态） -- 好友优惠提示 -- 推广者收益提示 -- 扫码二维码 -- 邀请码 - -### 3. 朋友圈文案 -``` -📖 推荐一本好书《一场SOUL的创业实验场》 - -这是卡若每天早上6-9点在Soul派对房分享的真实商业故事， -62个真实案例，讲透创业的底层逻辑。 - -通过我的链接购买立省5%！ - -👉 点击阅读: https://xxx.com/?ref=REFMKEL7JAC - -#创业 #商业思维 #Soul派对 -``` - -## 提现流程 - -``` -┌──────────────────────────────────────────────────┐ -│ 提现流程 │ -├──────────────────────────────────────────────────┤ -│ │ -│ 1. 检查是否绑定支付方式 │ -│ │ │ -│ ┌────┴────┐ │ -│ ▼ ▼ │ -│ 已绑定 未绑定 │ -│ │ │ │ -│ │ ▼ │ -│ │ 跳转设置页绑定 │ -│ │ │ │ -│ └────┬────┘ │ -│ ▼ │ -│ 2. 输入提现金额（≥¥10） │ -│ │ │ -│ ▼ │ -│ 3. 确认收款信息 │ -│ │ │ -│ ▼ │ -│ 4. 提交申请 → 等待审核 → 打款到账 │ -│ │ -└──────────────────────────────────────────────────┘ -``` - -### 提现方式 -- ✅ 微信（需绑定微信号） -- ✅ 支付宝（需绑定支付宝账号） - -### 自动提现 -可设置自动提现： -- 启用/关闭 -- 设置阈值金额（默认¥100） -- 设置收款账号 - -## 绑定用户管理 - -### 用户状态 -| 状态 | 说明 | 颜色 | -|------|------|------| -| 绑定中 | 30天内未付款 | 绿色 | -| 即将过期 | 剩余≤7天 | 橙色 | -| 已付款 | 完成付款 | 绿色✓ | -| 已过期 | 30天未付款 | 灰色 | - -### 到期提醒 -- 即将过期（≤7天）显示橙色提示 -- 页面顶部显示过期提醒横幅 - ---- -*文档版本：v2.0 | 更新日期：2026-01-18* diff --git a/开发文档/4、前端/ui/07-找伙伴功能说明.md b/开发文档/4、前端/ui/07-找伙伴功能说明.md deleted file mode 100644 index 4e57ed86..00000000 --- a/开发文档/4、前端/ui/07-找伙伴功能说明.md +++ /dev/null @@ -1,218 +0,0 @@ -# 找伙伴功能说明 - -## 功能概述 - -找伙伴是一个创业者匹配功能，帮助已购买用户找到志同道合的创业伙伴。 - -## 四种匹配类型 - -| 类型 | 图标 | 匹配标签 | 匹配方式 | 说明 | -|------|------|---------|---------|------| -| 创业合伙 | ⭐ | 创业伙伴 | 从数据库匹配 | 匹配已购用户 | -| 资源对接 | 👥 | 资源对接 | 弹出加入弹窗 | 加入资源对接群 | -| 导师顾问 | ❤️ | 商业顾问 | 弹出加入弹窗 | 联系商业顾问 | -| 团队招募 | 🎮 | 加入项目 | 弹出加入弹窗 | 加入创业项目 | - -## 使用条件 - -``` -┌─────────────────────────────────────────────────────┐ -│ 使用条件检查 │ -├─────────────────────────────────────────────────────┤ -│ │ -│ 1. 是否已登录？ │ -│ │ │ -│ ┌────┴────┐ │ -│ ▼ ▼ │ -│ 是 否 → 显示"请先登录" │ -│ │ │ -│ ▼ │ -│ 2. 是否已购买？ │ -│ （购买过任意内容：整本/单章） │ -│ │ │ -│ ┌────┴────┐ │ -│ ▼ ▼ │ -│ 是 否 → 显示"购买后解锁"提示 │ -│ │ 跳转购买页面 │ -│ ▼ │ -│ 3. 检查今日免费次数 │ -│ （每日3次免费） │ -│ │ │ -│ ┌────┴────┐ │ -│ ▼ ▼ │ -│ 有剩余 已用完 → 显示"购买解锁"弹窗 │ -│ │ 购买1章可解锁3次 │ -│ ▼ │ -│ 开始匹配 │ -│ │ -└─────────────────────────────────────────────────────┘ -``` - -## 匹配流程 - -### 创业合伙（从数据库匹配） -``` -点击开始匹配 - │ - ▼ -显示匹配动画（3-6秒） - │ - ▼ -从数据库筛选符合条件的用户： -- 已购买书籍（¥1以上） -- 已绑定手机号和微信号 - │ - ▼ -随机匹配一位用户 - │ - ▼ -显示匹配结果卡片： -- 用户头像/昵称 -- 标签 -- 匹配度 -- 共同兴趣 -- 核心理念 - │ - ▼ -┌──────────────────┐ -│ [一键加好友] │ → 复制对方微信号 -│ [重新匹配] │ → 再次匹配（消耗次数） -└──────────────────┘ -``` - -### 资源对接/导师顾问/团队招募 -``` -点击开始匹配 - │ - ▼ -显示匹配动画（3-6秒） - │ - ▼ -自动弹出加入弹窗 - │ - ▼ -填写联系方式： -- 手机号 或 微信号（二选一） -- 如已绑定则自动填充 - │ - ▼ -提交申请 → 上报到存客宝CKB - │ - ▼ -显示"加入成功" -``` - -## 存客宝CKB对接 - -### 加入申请 -``` -POST /api/ckb/join - -{ - "type": "mentor", // mentor/investor/team/partner - "phone": "13800000000", - "wechat": "wxid_xxx", - "userId": "user_xxx" -} -``` - -### 匹配上报 -``` -POST /api/ckb/match - -{ - "matchType": "partner", - "phone": "13800000000", - "wechat": "wxid_xxx", - "userId": "user_xxx", - "matchedUser": { - "id": "matched_user_id", - "nickname": "创业先锋", - "matchScore": 85 - } -} -``` - -## 匹配次数规则 - -| 规则 | 说明 | -|------|------| -| 每日免费 | 3次/天 | -| 重置时间 | 每日0点 | -| 付费解锁 | 购买1章 = 解锁3次 | - -### 次数存储 -```javascript -// localStorage 存储 -{ - "match_count_data": { - "date": "2026-01-18", // 当日日期 - "count": 2 // 已使用次数 - } -} -``` - -## UI设计 - -### 匹配按钮（未开始） -``` -┌─────────────────────────────┐ -│ │ -│ ┌───────────────┐ │ -│ │ │ │ -│ │ 👥 开始匹配 │ │ -│ │ 匹配创业伙伴 │ │ -│ │ │ │ -│ └───────────────┘ │ -│ │ -│ 当前模式: 创业合伙 │ -│ │ -│ [⭐] [👥] [❤️] [🎮] │ -│ 创业 资源 导师 团队 │ -│ 合伙 对接 顾问 招募 │ -│ │ -└─────────────────────────────┘ -``` - -### 匹配中动画 -``` -┌─────────────────────────────┐ -│ │ -│ ┌───────────────┐ │ -│ │ ◉ ◉ ◉ │ │ -│ │ 匹配中... │ │ -│ │ 已匹配 3 次 │ │ -│ └───────────────┘ │ -│ │ -│ 正在匹配创业伙伴... │ -│ │ -│ [取消匹配] │ -│ │ -└─────────────────────────────┘ -``` - -### 匹配结果 -``` -┌─────────────────────────────┐ -│ ✨ │ -│ │ -│ ┌───────────────────────┐ │ -│ │ 👤 创业先锋 85% │ │ -│ │ [创业者] [私域运营] │ │ -│ │ │ │ -│ │ 共同兴趣： │ │ -│ │ 📚 都在读《创业实验》 │ │ -│ │ 💼 对私域运营感兴趣 │ │ -│ │ 🎯 相似的创业方向 │ │ -│ │ │ │ -│ │ 核心理念： │ │ -│ │ 专注私域流量运营5年... │ │ -│ └───────────────────────┘ │ -│ │ -│ [一键加好友] [重新匹配] │ -│ │ -└─────────────────────────────┘ -``` - ---- -*文档版本：v2.0 | 更新日期：2026-01-18* diff --git a/开发文档/4、前端/ui/08-支付系统说明.md b/开发文档/4、前端/ui/08-支付系统说明.md deleted file mode 100644 index ed793e5c..00000000 --- a/开发文档/4、前端/ui/08-支付系统说明.md +++ /dev/null @@ -1,151 +0,0 @@ -# 支付系统说明 - -## 支付方式 - -| 支付方式 | 状态 | 说明 | -|---------|------|------| -| 微信支付 | ✅ 启用 | 主要支付方式 | -| 支付宝 | ❌ 禁用 | 已移除 | -| USDT | ⚠️ 可选 | 默认禁用 | -| PayPal | ⚠️ 可选 | 默认禁用 | - -## 支付流程 - -``` -┌─────────────────────────────────────────────────────┐ -│ 支付流程 │ -├─────────────────────────────────────────────────────┤ -│ │ -│ 1. 用户点击购买 │ -│ │ │ -│ ▼ │ -│ 2. 弹出支付弹窗 │ -│ - 显示商品信息 │ -│ - 选择支付方式（微信为主） │ -│ │ │ -│ ▼ │ -│ 3. 调用后端创建订单 │ -│ POST /api/payment/create │ -│ │ │ -│ ▼ │ -│ 4. 返回支付二维码 │ -│ - 微信：返回支付链接 │ -│ - 生成QR码展示 │ -│ │ │ -│ ▼ │ -│ 5. 用户扫码支付 │ -│ │ │ -│ ▼ │ -│ 6. 前端轮询支付状态 │ -│ POST /api/payment/query │ -│ - 每3秒查询一次 │ -│ - 最多轮询60次（3分钟） │ -│ │ │ -│ ┌────┴────┐ │ -│ ▼ ▼ │ -│ 支付成功 超时/失败 │ -│ │ │ │ -│ ▼ ▼ │ -│ 更新订单 提示重试 │ -│ 解锁内容 │ -│ │ -└─────────────────────────────────────────────────────┘ -``` - -## 价格体系 - -### 定价 -| 商品 | 价格 | 说明 | -|------|------|------| -| 单章购买 | ¥1 | 单独购买一章 | -| 基础版全书 | ¥9.9 | 包含50章基础内容 | -| 最新完整版 | ¥9.9 + N | N = 新增章节数 × ¥1 | - -### 分销优惠 -| 原价 | 好友优惠(5%) | 实付 | -|------|-------------|------| -| ¥1 | ¥0.05 | ¥0.95 | -| ¥9.9 | ¥0.50 | ¥9.40 | - -## 支付弹窗组件 - -文件位置：`components/payment-modal.tsx` - -### Props -```typescript -interface PaymentModalProps { - isOpen: boolean - onClose: () => void - type: "section" | "fullbook" - sectionId?: string - sectionTitle?: string - amount: number - onSuccess: () => void -} -``` - -### 支付状态 -```typescript -type PaymentState = - | "idle" // 初始状态 - | "creating" // 创建订单中 - | "pending" // 等待支付 - | "polling" // 轮询状态 - | "success" // 支付成功 - | "failed" // 支付失败 -``` - -## 微信支付配置 - -配置位置：`lib/store.ts` -> Settings.paymentMethods.wechat - -```typescript -wechat: { - enabled: true, - qrCode: string, // 收款二维码 - account: string, // 微信号 - websiteAppId: string, // 网站应用AppID - websiteAppSecret: string, - serviceAppId: string, // 服务号AppID - serviceAppSecret: string, - mpVerifyCode: string, // 公众号验证码 - merchantId: string, // 商户号 - apiKey: string, // API密钥 - groupQrCode?: string // 微信群二维码 -} -``` - -## 订单数据结构 - -```typescript -interface Purchase { - id: string - userId: string - type: "section" | "fullbook" - sectionId?: string - sectionTitle?: string - amount: number - status: "pending" | "completed" | "failed" - paymentMethod?: string - orderSn?: string // 订单号 - tradeSn?: string // 交易号 - referrerEarnings?: number // 推广者收益 - createdAt: string -} -``` - -## 支付回调处理 - -### 支付成功 -1. 更新订单状态为 `completed` -2. 更新用户购买记录 -3. 如有推荐人，计算分销收益 -4. 刷新页面解锁内容 - -### 支付失败/超时 -1. 更新订单状态为 `failed` -2. 提示用户重试 -3. 保留订单记录便于追踪 - ---- -*文档版本：v2.0 | 更新日期：2026-01-18* diff --git a/开发文档/4、前端/ui/09-管理后台说明.md b/开发文档/4、前端/ui/09-管理后台说明.md deleted file mode 100644 index 82e91a3a..00000000 --- a/开发文档/4、前端/ui/09-管理后台说明.md +++ /dev/null @@ -1,158 +0,0 @@ -# 管理后台说明 - -## 后台入口 - -路径：`/admin` - -## 功能模块 - -### 1. 数据概览 (`/admin`) - -显示核心数据指标： -- 总用户数 -- 总收入 -- 订单数 -- 转化率 -- 最近订单列表 -- 新注册用户列表 - -### 2. 内容管理 (`/admin/content`) - -功能： -- 查看书籍章节列表 -- 导入/导出书籍内容 -- 编辑章节内容 -- 管理章节价格和状态 - -### 3. 用户管理 (`/admin/users`) - -功能： -- 查看用户列表 -- 搜索用户 -- 查看用户详情 -- 查看购买记录 -- 管理用户权限 - -### 4. 分销管理 (`/admin/distribution`) - -功能： -- 查看分销商列表 -- 查看分销收益统计 -- 管理佣金比例 -- 查看绑定关系 - -### 5. 提现管理 (`/admin/withdrawals`) - -功能： -- 查看提现申请列表 -- 审核提现申请 -- 处理打款 -- 查看提现历史 - -### 6. 系统设置 (`/admin/settings`) - -功能： -- 支付配置（微信支付参数） -- 分销比例设置 -- 作者信息编辑 -- 站点配置 - -## 后台布局 - -``` -┌─────────────────────────────────────────────────────┐ -│ 一场SOUL的创业实验 · 管理后台 │ -├──────────┬──────────────────────────────────────────┤ -│ │ │ -│ 📊 概览 │ 主内容区域 │ -│ │ │ -│ 📝 内容 │ │ -│ │ │ -│ 👥 用户 │ │ -│ │ │ -│ 🎁 分销 │ │ -│ │ │ -│ 💰 提现 │ │ -│ │ │ -│ ⚙️ 设置 │ │ -│ │ │ -├──────────┴──────────────────────────────────────────┤ -│ 退出登录 │ -└─────────────────────────────────────────────────────┘ -``` - -## 权限控制 - -### 管理员判断 -```typescript -// 用户对象中的 isAdmin 字段 -user.isAdmin === true -``` - -### 访问限制 -```typescript -// 在页面中检查 -if (!user?.isAdmin) { - router.push('/') // 重定向到首页 -} -``` - -## 数据展示 - -### 概览卡片 -``` -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ 总用户数 │ │ 总收入 │ │ 订单数 │ │ 转化率 │ -│ │ │ │ │ │ │ │ -│ 156 │ │ ¥1,234 │ │ 89 │ │ 57.1% │ -└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ -``` - -### 最近订单 -``` -┌───────────────────────────────────────────────────┐ -│ 最近订单 │ -├───────────────────────────────────────────────────┤ -│ 整本购买 2026-01-18 14:30 +¥9.9 微信 │ -│ 单节购买 2026-01-18 13:15 +¥1.0 微信 │ -│ 整本购买 2026-01-18 11:20 +¥9.9 微信 │ -└───────────────────────────────────────────────────┘ -``` - -## 后台API - -### 获取统计数据 -``` -GET /api/admin/stats -``` - -### 获取用户列表 -``` -GET /api/admin/users?page=1&limit=20 -``` - -### 获取订单列表 -``` -GET /api/admin/orders?page=1&limit=20 -``` - -### 处理提现 -``` -POST /api/admin/withdrawals/process -{ - "withdrawalId": "xxx", - "approved": true -} -``` - -### 更新设置 -``` -PUT /api/admin/settings -{ - "distributorShare": 90, - "authorInfo": {...} -} -``` - ---- -*文档版本：v2.0 | 更新日期：2026-01-18* diff --git a/开发文档/4、前端/ui/10-部署上线指南.md b/开发文档/4、前端/ui/10-部署上线指南.md deleted file mode 100644 index d444be2e..00000000 --- a/开发文档/4、前端/ui/10-部署上线指南.md +++ /dev/null @@ -1,203 +0,0 @@ -# 部署上线指南 - -## 环境要求 - -| 项目 | 要求 | -|------|------| -| Node.js | >= 20.0.0 | -| npm | >= 10.0.0 | -| MySQL | >= 8.0 | - -## 本地开发 - -### 安装依赖 -```bash -npm install -``` - -### 启动开发服务器 -```bash -npm run dev -``` - -### 访问地址 -- 本地：http://localhost:3000 -- 局域网：http://192.168.x.x:3000 - -## 环境变量 - -创建 `.env.local` 文件： - -```env -# 数据库配置 -DATABASE_URL=mysql://user:password@localhost:3306/soul_startup - -# 存客宝API -CKB_API_KEY=your_api_key_here - -# 微信支付 -WECHAT_APP_ID=your_app_id -WECHAT_APP_SECRET=your_app_secret -WECHAT_MERCHANT_ID=your_merchant_id -WECHAT_API_KEY=your_api_key -``` - -## 生产构建 - -### 构建 -```bash -npm run build -``` - -### 启动 -```bash -npm run start -``` - -## 数据库配置 - -### 创建数据库 -```sql -CREATE DATABASE soul_startup CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -``` - -### 主要数据表 -```sql --- 用户表 -CREATE TABLE users ( - id VARCHAR(36) PRIMARY KEY, - phone VARCHAR(20) NOT NULL, - nickname VARCHAR(50), - is_admin BOOLEAN DEFAULT FALSE, - referral_code VARCHAR(20), - referred_by VARCHAR(20), - earnings DECIMAL(10,2) DEFAULT 0, - pending_earnings DECIMAL(10,2) DEFAULT 0, - wechat VARCHAR(50), - alipay VARCHAR(50), - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP -); - --- 购买记录表 -CREATE TABLE purchases ( - id VARCHAR(36) PRIMARY KEY, - user_id VARCHAR(36) NOT NULL, - type ENUM('section', 'fullbook') NOT NULL, - section_id VARCHAR(20), - amount DECIMAL(10,2) NOT NULL, - status ENUM('pending', 'completed', 'failed') DEFAULT 'pending', - payment_method VARCHAR(20), - referrer_earnings DECIMAL(10,2), - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP -); - --- 提现记录表 -CREATE TABLE withdrawals ( - id VARCHAR(36) PRIMARY KEY, - user_id VARCHAR(36) NOT NULL, - amount DECIMAL(10,2) NOT NULL, - method VARCHAR(20) NOT NULL, - account VARCHAR(100) NOT NULL, - name VARCHAR(50) NOT NULL, - status ENUM('pending', 'approved', 'rejected', 'completed') DEFAULT 'pending', - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - processed_at TIMESTAMP -); - --- 分销绑定表 -CREATE TABLE referral_bindings ( - id VARCHAR(36) PRIMARY KEY, - referrer_id VARCHAR(36) NOT NULL, - visitor_id VARCHAR(36) NOT NULL, - binding_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - expire_time TIMESTAMP NOT NULL, - status ENUM('active', 'converted', 'expired') DEFAULT 'active' -); -``` - -## 微信支付配置 - -### 1. 注册商户号 -在微信支付商户平台注册 - -### 2. 获取API密钥 -商户平台 → 账户中心 → API安全 → 设置API密钥 - -### 3. 配置回调地址 -``` -https://your-domain.com/api/payment/notify -``` - -## Vercel部署 - -### 1. 连接GitHub仓库 -```bash -vercel link -``` - -### 2. 配置环境变量 -在Vercel项目设置中添加环境变量 - -### 3. 部署 -```bash -vercel --prod -``` - -## 服务器部署 - -### 使用PM2 -```bash -# 安装PM2 -npm install -g pm2 - -# 构建项目 -npm run build - -# 启动服务 -pm2 start npm --name "soul-startup" -- start - -# 保存进程 -pm2 save - -# 开机自启 -pm2 startup -``` - -### Nginx配置 -```nginx -server { - listen 80; - server_name your-domain.com; - - location / { - proxy_pass http://127.0.0.1:3000; - 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; - } -} -``` - -## 检查清单 - -### 上线前检查 -- [ ] 环境变量配置完整 -- [ ] 数据库连接正常 -- [ ] 微信支付配置正确 -- [ ] 存客宝API配置正确 -- [ ] HTTPS证书配置 -- [ ] 域名解析配置 - -### 功能测试 -- [ ] 用户注册/登录 -- [ ] 章节阅读 -- [ ] 支付购买 -- [ ] 分销绑定 -- [ ] 提现申请 -- [ ] 找伙伴匹配 -- [ ] 管理后台 - ---- -*文档版本：v2.0 | 更新日期：2026-01-18* diff --git a/开发文档/4、前端/ui/11-页面截图与还原指南.md b/开发文档/4、前端/ui/11-页面截图与还原指南.md deleted file mode 100644 index ce2038df..00000000 --- a/开发文档/4、前端/ui/11-页面截图与还原指南.md +++ /dev/null @@ -1,482 +0,0 @@ -# 页面截图与还原指南 - -本文档用于小程序和移动端APP开发时的界面还原参考。 - -## 设计规范 - -### 颜色系统 -```css -/* 主色调 */ ---app-brand: #00CED1; /* 主品牌色 - 青色 */ ---app-brand-light: #00CED1/20; /* 浅品牌色 */ - -/* 辅助色 */ ---gold: #FFD700; /* 金色 - 用于收益/VIP */ ---green: #07C160; /* 绿色 - 微信相关 */ ---orange: #FFA500; /* 橙色 - 警告/即将过期 */ ---red: #E91E63; /* 红色 - 重要/热门 */ ---purple: #7B61FF; /* 紫色 - 资源对接 */ - -/* 背景色 */ ---bg-primary: #000000; /* 纯黑背景 */ ---bg-card: #1c1c1e; /* 卡片背景 */ ---bg-input: #0a0a0a; /* 输入框背景 */ - -/* 文字色 */ ---text-primary: #ffffff; /* 主文字 */ ---text-secondary: rgba(255,255,255,0.7); /* 次要文字 */ ---text-tertiary: rgba(255,255,255,0.4); /* 三级文字 */ -``` - -### 字体规范 -``` -标题: 18-24px, font-weight: 600-700 -副标题: 14-16px, font-weight: 500 -正文: 14px, font-weight: 400 -辅助文字: 12px, font-weight: 400 -极小文字: 10px, font-weight: 400 -``` - -### 圆角规范 -``` -按钮: 12px (rounded-xl) -卡片: 16px (rounded-2xl) -头像: 50% (rounded-full) -输入框: 12px (rounded-xl) -标签: 6px (rounded-md) -``` - ---- - -## 页面清单 - -### 1. 首页 (`/`) - -**页面尺寸**: 375 x 812 (iPhone标准) - -**页面结构**: -``` -┌─────────────────────────────────────┐ -│ 状态栏 (44px) │ -├─────────────────────────────────────┤ -│ │ -│ 书籍封面图片 (200x280) │ -│ │ -│ 一场SOUL的创业实验场 │ -│ (text-3xl, gradient) │ -│ │ -│ 来自Soul派对房的真实商业故事 │ -│ (text-sm, gray-400) │ -│ │ -│ ┌──────────────────────────────┐ │ -│ │ 62个真实案例 │ 每日更新 │ │ -│ └──────────────────────────────┘ │ -│ │ -│ ┌────────────┐ ┌────────────┐ │ -│ │ 立即阅读 │ │ ¥9.9购买 │ │ -│ │ (白底黑字) │ │ (渐变背景) │ │ -│ └────────────┘ └────────────┘ │ -│ │ -├─────────────────────────────────────┤ -│ 底部导航栏 (60px) │ -│ [首页] [目录] [找伙伴] [我的] │ -└─────────────────────────────────────┘ -``` - -**关键元素**: -- 书籍封面: 居中, 带阴影 -- 标题: 渐变色 from-[#00CED1] to-[#20B2AA] -- 购买按钮: 渐变色 from-[#FFD700] to-[#FFA500] - ---- - -### 2. 目录页 (`/chapters`) - -**页面结构**: -``` -┌─────────────────────────────────────┐ -│ Header: ← 目录 │ -├─────────────────────────────────────┤ -│ ┌─────────────────────────────────┐ │ -│ │ 📚 一场SOUL的创业实验场 62章 │ │ -│ │ 书籍信息卡片 │ │ -│ └─────────────────────────────────┘ │ -│ │ -│ [基础版 ¥9.9] [最新版 ¥XX.X] │ ← 版本切换(可隐藏) -│ │ -│ ┌─────────────────────────────────┐ │ -│ │ 📖 序言｜为什么我每天... [免费]│ │ -│ └─────────────────────────────────┘ │ -│ │ -│ ▼ 01 第一篇｜真实的人 │ -│ ├ 1.1 荷包：电动车出租... [免费]│ -│ ├ 1.2 老墨:资源整合... [¥1] │ -│ └ 1.3 笑声背后的MBTI [¥1] │ -│ │ -│ ▶ 02 第二篇｜真实的行业 │ -│ ▶ 03 第三篇｜真实的错误 │ -│ ... │ -│ │ -├─────────────────────────────────────┤ -│ 底部导航 │ -└─────────────────────────────────────┘ -``` - -**关键元素**: -- 章节状态标签: 免费(绿色), 已购(蓝色), ¥1(灰色) -- 折叠/展开: 点击篇标题切换 -- 版本切换: 两个并排按钮 - ---- - -### 3. 阅读页 (`/read/[id]`) - -**页面结构**: -``` -┌─────────────────────────────────────┐ -│ ← 返回 第1章 人与人... [分享] │ -├─────────────────────────────────────┤ -│ │ -│ 1.1 荷包：电动车出租的被动收入模式 │ -│ (text-2xl, font-bold) │ -│ │ -│ 文章内容... │ -│ (text-base, leading-relaxed) │ -│ │ -│ ... 更多内容 ... │ -│ │ -│ ┌─────────────────────────────────┐│ -│ │ 🔒 需要购买才能继续阅读 ││ -│ │ ││ -│ │ ┌─────────┐ ┌─────────┐ ││ -│ │ │购买本章 │ │购买全书 │ ││ -│ │ │ ¥1 │ │ ¥9.9 │ ││ -│ │ └─────────┘ └─────────┘ ││ -│ └─────────────────────────────────┘│ -│ │ -│ ┌────────────┐ ┌────────────┐ │ -│ │ ← 上一篇 │ │ 下一篇 → │ │ -│ └────────────┘ └────────────┘ │ -│ │ -└─────────────────────────────────────┘ -``` - -**关键元素**: -- 付费墙: 半透明渐变遮罩 -- 购买按钮: 两个并排, 不同颜色 -- 导航按钮: 宽度适中(flex-1, max-w-[140px]) - ---- - -### 4. 找伙伴页 (`/match`) - -**页面结构**: -``` -┌─────────────────────────────────────┐ -│ ← 返回 找伙伴 │ -├─────────────────────────────────────┤ -│ │ -│ ┌─────────┐ │ -│ │ │ │ -│ │ 👥 │ ← 匹配按钮 │ -│ │开始匹配 │ (圆形) │ -│ │匹配创业伙伴│ │ -│ │ │ │ -│ └─────────┘ │ -│ │ -│ 当前模式: 创业合伙 │ -│ │ -│ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │ -│ │ ⭐ │ │ 👥 │ │ ❤️ │ │ 🎮 │ │ -│ │创业 │ │资源 │ │导师 │ │团队 │ │ -│ │合伙 │ │对接 │ │顾问 │ │招募 │ │ -│ └────┘ └────┘ └────┘ └────┘ │ -│ │ -│ 免费匹配机会: 3/3 │ -│ │ -└─────────────────────────────────────┘ -``` - -**匹配结果卡片**: -``` -┌─────────────────────────────────────┐ -│ ✨ 匹配成功！ │ -│ │ -│ ┌─────────────────────────────────┐│ -│ │ 👤 创业先锋 85%匹配度 ││ -│ │ [创业者] [私域运营] ││ -│ │ ││ -│ │ 共同兴趣: ││ -│ │ 📚 都在读《创业实验》 ││ -│ │ 💼 对私域运营感兴趣 ││ -│ │ ││ -│ │ 核心理念: ││ -│ │ 专注私域流量运营5年... ││ -│ └─────────────────────────────────┘│ -│ │ -│ ┌────────────┐ ┌────────────┐ │ -│ │ 一键加好友 │ │ 重新匹配 │ │ -│ └────────────┘ └────────────┘ │ -└─────────────────────────────────────┘ -``` - ---- - -### 5. 我的页面 (`/my`) - -**页面结构**: -``` -┌─────────────────────────────────────┐ -│ 我的 │ -├─────────────────────────────────────┤ -│ ┌─────────────────────────────────┐ │ -│ │ 👤 用户昵称 VIP │ │ -│ │ ID: 3f92**** │ │ -│ │ │ │ -│ │ ┌────┐ ┌────┐ ┌────┐ │ │ -│ │ │ 12 │ │ 5 │ │ ¥89│ │ │ -│ │ │已购 │ │推荐 │ │收益│ │ │ -│ │ └────┘ └────┘ └────┘ │ │ -│ └─────────────────────────────────┘ │ -│ │ -│ ┌─────────────────────────────────┐ │ -│ │ 💰 我的收益 │ │ -│ │ 累计收益: ¥89.00 │ │ -│ │ 可提现: ¥89.00 │ │ -│ │ │ │ -│ │ ┌──────────┐ ┌──────────┐ │ │ -│ │ │ 推广中心 │ │ 提现 │ │ │ -│ │ └──────────┘ └──────────┘ │ │ -│ └─────────────────────────────────┘ │ -│ │ -│ ┌─────────────────────────────────┐ │ -│ │ 📦 我的订单 → │ │ -│ │ 🎁 推广中心 → │ │ -│ │ ℹ️ 关于作者 → │ │ -│ │ ⚙️ 设置 → │ │ -│ └─────────────────────────────────┘ │ -│ │ -├─────────────────────────────────────┤ -│ 底部导航 │ -└─────────────────────────────────────┘ -``` - ---- - -### 6. 分销中心页 (`/my/referral`) - -**页面结构**: -``` -┌─────────────────────────────────────┐ -│ ← 返回 分销中心 🔔 ⚙️ │ -├─────────────────────────────────────┤ -│ ┌─────────────────────────────────┐ │ -│ │ 累计收益 ¥89.00 │ │ -│ │ 90%返利 待结算: ¥0.00 │ │ -│ │ │ │ -│ │ ┌──────────┐ ┌──────────┐ │ │ -│ │ │ 申请提现 │ │自动提现:开启│ │ │ -│ │ └──────────┘ └──────────┘ │ │ -│ └─────────────────────────────────┘ │ -│ │ -│ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │ -│ │ 3 │ │ 1 │ │ 2 │ │ 0 │ │ -│ │绑定中│ │已付款│ │即将过期│ │总邀请│ │ -│ └────┘ └────┘ └────┘ └────┘ │ -│ │ -│ ┌─────────────────────────────────┐ │ -│ │ ⚠️ 推广规则 │ │ -│ │ • 好友通过你的链接购买，立享5%优惠│ │ -│ │ • 好友成功付款后，你获得90%收益 │ │ -│ │ • 绑定期30天，期满未付款自动解除 │ │ -│ └─────────────────────────────────┘ │ -│ │ -│ ┌─────────────────────────────────┐ │ -│ │ 👥 绑定用户 (5) ▼ │ │ -│ │ ├ [绑定中] [已付款] [已过期] │ │ -│ │ │ │ │ -│ │ │ 小明 2025/12/24 [5天] │ │ -│ │ │ 小红 2026/1/8 [20天] │ │ -│ │ │ 阿强 2025/12/21 [2天后过期] │ │ -│ └─────────────────────────────────┘ │ -│ │ -│ 我的邀请码: REFMKEL7JAC │ -│ │ -│ ┌─────────────────────────────────┐ │ -│ │ 🖼️ 生成推广海报 → │ │ -│ │ 💬 分享到朋友圈 → │ │ -│ └─────────────────────────────────┘ │ -└─────────────────────────────────────┘ -``` - ---- - -### 7. 设置页 (`/my/settings`) - -**页面结构**: -``` -┌─────────────────────────────────────┐ -│ ← 返回 设置 │ -├─────────────────────────────────────┤ -│ ┌─────────────────────────────────┐ │ -│ │ 🛡️ 账号绑定 │ │ -│ │ 绑定后可用于提现和找伙伴功能 │ │ -│ ├─────────────────────────────────┤ │ -│ │ 📱 手机号 │ │ -│ │ 138****1234 ✓ │ │ -│ ├─────────────────────────────────┤ │ -│ │ 💬 微信号 │ │ -│ │ 未绑定 去绑定 │ │ -│ ├─────────────────────────────────┤ │ -│ │ 💳 支付宝 │ │ -│ │ 未绑定 去绑定 │ │ -│ └─────────────────────────────────┘ │ -│ │ -│ ┌─────────────────────────────────┐ │ -│ │ ⚠️ 提示：绑定至少一个支付方式才能提现│ │ -│ └─────────────────────────────────┘ │ -│ │ -│ ┌─────────────────────────────────┐ │ -│ │ 退出登录 │ │ -│ └─────────────────────────────────┘ │ -└─────────────────────────────────────┘ -``` - ---- - -### 8. 推广海报弹窗 - -**弹窗结构**: -``` -┌─────────────────────────────────────┐ -│ × │ -├─────────────────────────────────────┤ -│ [真实商业案例] [每日更新] │ -│ │ -│ 一场SOUL的 │ -│ 创业实验场 │ -│ 来自Soul派对房的真实商业故事 │ -│ │ -│ ┌────┐ ┌────┐ ┌────┐ │ -│ │ 62 │ │ 5% │ │90%│ │ -│ │真实案例│ │好友优惠│ │你的收益│ │ -│ └────┘ └────┘ └────┘ │ -│ │ -│ [人性观察] [行业揭秘] [赚钱逻辑] │ -│ [创业复盘] [资源对接] │ -│ │ -│ ┌─────────────────────────────────┐│ -│ │ 通过我的链接购买，立省5% ││ -│ └─────────────────────────────────┘│ -│ │ -│ [卡] 卡若 推荐你来读 │ -│ │ -│ ┌───────────┐ │ -│ │ QR Code │ │ -│ │ (扫码) │ │ -│ └───────────┘ │ -│ │ -│ 长按识别 · 立即试读 │ -│ 邀请码: REFMKEL7JAC │ -├─────────────────────────────────────┤ -│ 长按上方图片保存，或截图分享 │ -│ │ -│ [ 复制链接 ] [ 保存图片 ] │ -└─────────────────────────────────────┘ -``` - ---- - -### 9. 支付弹窗 - -**弹窗结构**: -``` -┌─────────────────────────────────────┐ -│ × │ -├─────────────────────────────────────┤ -│ 确认支付 │ -│ │ -│ ┌─────────────────────────────────┐│ -│ │ 📚 整本购买 ││ -│ │ 一场SOUL的创业实验场 ││ -│ │ ¥9.9 ││ -│ └─────────────────────────────────┘│ -│ │ -│ 选择支付方式: │ -│ │ -│ ┌─────────────────────────────────┐│ -│ │ 💚 微信支付 ● ││ -│ └─────────────────────────────────┘│ -│ │ -│ ┌───────────┐ │ -│ │ QR Code │ │ -│ │ (微信扫码) │ │ -│ └───────────┘ │ -│ │ -│ 请使用微信扫码完成支付 │ -│ │ -│ ┌─────────────────────────────────┐│ -│ │ 确认支付 ¥9.9 ││ -│ └─────────────────────────────────┘│ -└─────────────────────────────────────┘ -``` - ---- - -### 10. 管理后台 (`/admin`) - -**桌面端布局**: -``` -┌────────────────────────────────────────────────────────────────┐ -│ 一场SOUL的创业实验 · 管理后台 │ -├──────────┬─────────────────────────────────────────────────────┤ -│ │ │ -│ 📊 概览 │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ -│ │ │ 156 │ │¥1234│ │ 89 │ │57.1%│ │ -│ 📝 内容 │ │总用户 │ │总收入 │ │订单数 │ │转化率 │ │ -│ │ └──────┘ └──────┘ └──────┘ └──────┘ │ -│ 👥 用户 │ │ -│ │ ┌───────────────────────────────────────────────┐ │ -│ 🎁 分销 │ │ 最近订单 │ │ -│ │ ├───────────────────────────────────────────────┤ │ -│ 💰 提现 │ │ 整本购买 2026-01-18 14:30 +¥9.9 微信 │ │ -│ │ │ 单节购买 2026-01-18 13:15 +¥1.0 微信 │ │ -│ ⚙️ 设置 │ │ 整本购买 2026-01-18 11:20 +¥9.9 微信 │ │ -│ │ └───────────────────────────────────────────────┘ │ -│ │ │ -│ │ ┌───────────────────────────────────────────────┐ │ -│ 退出 │ │ 新注册用户 │ │ -│ │ └───────────────────────────────────────────────┘ │ -└──────────┴─────────────────────────────────────────────────────┘ -``` - ---- - -## 开发还原注意事项 - -### 1. 响应式适配 -- 以 iPhone 13/14 (375px宽) 为基准设计 -- 使用相对单位: rem, %, vh/vw -- 使用 flex 布局 - -### 2. 动画效果 -- 页面切换: 从右滑入 -- 弹窗: 从底部滑入 + 背景淡入 -- 按钮: active 状态缩放 95% -- 匹配中: 旋转动画 + 脉冲 - -### 3. 触摸反馈 -- 按钮点击: scale(0.95) + 背景变化 -- 列表项: 背景色 white/5% - -### 4. 图标使用 -- 使用 Lucide Icons 图标库 -- 或使用相似的线性图标 - -### 5. 字体 -- iOS: -apple-system -- Android: Roboto -- 备用: sans-serif - ---- -*文档版本：v2.0 | 更新日期：2026-01-18* diff --git a/开发文档/5、接口/API接口.md b/开发文档/5、接口/API接口.md deleted file mode 100644 index f26b008c..00000000 --- a/开发文档/5、接口/API接口.md +++ /dev/null @@ -1,99 +0,0 @@ -# API接口文档 - Soul创业实验项目 - -> **API风格**: RESTful | **版本**: v1.0 | **基础路径**: `/api` - -**我是卡若。** - -接口设计原则：**简单、清晰、易用**。与 [接口定义规范](接口定义规范.md) 配合使用。 - ---- - -## 1. 接口总览 - -### 1.1 接口分类 - -| 模块 | 路径前缀 | 描述 | -|------|---------|------| -| 书籍内容 | `/api/book` | 章节列表、内容获取、同步 | -| 支付系统 | `/api/payment` | 订单创建、支付回调、状态查询 | -| 分销系统 | `/api/referral` | 邀请码、收益查询、提现 | -| 用户系统 | `/api/user` | 登录、注册、信息更新 | -| 匹配系统 | `/api/match` | 寻找匹配、匹配历史 | -| 管理后台 | `/api/admin` | 内容/订单/用户/分销管理 | -| 配置系统 | `/api/config` | 系统配置获取 | - -### 1.2 认证方式 - -**用户认证** (可选): `Cookie: session_id=` - -**管理员认证** (必需): `Authorization: Bearer admin-token-secret` - ---- - -## 2. 书籍内容API - -- **GET /api/book/all-chapters** — 获取所有章节 -- **GET /api/book/chapter/:id** — 获取单章内容 -- **POST /api/book/sync** — 同步章节（需管理员Token） - ---- - -## 3. 支付API - -- **POST /api/payment/create-order** — 创建订单（参数：userId, type, sectionId?, amount, paymentMethod） -- **POST /api/payment/alipay/notify** — 支付宝回调 -- **POST /api/payment/wechat/notify** — 微信回调 -- **GET /api/payment/verify?orderId=** — 验证支付状态 - ---- - -## 4. 分销API - -- **GET /api/referral/code** — 获取邀请码 -- **POST /api/referral/bind** — 绑定推荐关系 -- **GET /api/referral/earnings** — 查询收益 -- **POST /api/referral/withdraw** — 申请提现 - ---- - -## 5. 用户API - -- **POST /api/user/login** — 登录（phone, code） -- **POST /api/user/register** — 注册（phone, nickname, referralCode?） - ---- - -## 6. 匹配API - -- **POST /api/match/find** — 寻找匹配 -- **GET /api/match/history** — 匹配历史 - ---- - -## 7. 管理后台API - -- **GET /api/admin** — 概览数据 -- **GET/POST/PUT/DELETE /api/admin/content** — 内容管理 -- **GET /api/admin/payment** — 订单管理（?status=completed&page=1&limit=20） - ---- - -## 8. 错误码规范 - -| 状态码 | 含义 | -|--------|------| -| 200/201 | 成功 | -| 400 | 请求错误 | -| 401 | 未授权 | -| 403 | 禁止访问 | -| 404 | 未找到 | -| 500 | 服务器错误 | - -**错误响应**: `{ "success": false, "error": { "code": 1001, "message": "...", "details": "..." } }` - ---- - -## 9. 性能与限流 - -- 内容缓存：章节 1h、列表 10min；支持 ETag 304 -- 限流：内容 100/分钟、下单 10/分钟、管理端 1000/分钟 diff --git a/开发文档/5、接口/API接口完整文档.md b/开发文档/5、接口/API接口完整文档.md new file mode 100644 index 00000000..e23fa1d5 --- /dev/null +++ b/开发文档/5、接口/API接口完整文档.md @@ -0,0 +1,640 @@ +# API接口完整文档 - Soul创业实验项目 + +> **API风格**: RESTful | **版本**: v1.0 | **基础路径**: `/api` +> **说明**：本文档已整合原《API接口》内容，为项目唯一 API 参考。 + +**我是卡若。** + +接口设计原则：**简单、清晰、易用**。 + +--- + +## 1. 接口总览 + +### 1.1 接口分类 + +| 模块 | 路径前缀 | 描述 | +|------|---------|------| +| 书籍内容 | `/api/book` | 章节列表、内容获取、同步 | +| 支付系统 | `/api/payment` | 订单创建、支付回调、状态查询 | +| 分销系统 | `/api/referral` | 邀请码、收益查询、提现 | +| 用户系统 | `/api/user` | 登录、注册、信息更新 | +| 匹配系统 | `/api/match` | 寻找匹配、匹配历史 | +| 管理后台 | `/api/admin` | 内容/订单/用户/分销管理 | +| 配置系统 | `/api/config` | 系统配置获取 | + +### 1.2 认证方式 + +**用户认证** (可选): +``` +Cookie: session_id= +``` + +**管理员认证** (必需): +``` +Authorization: Bearer admin-token-secret +``` + +--- + +## 2. 书籍内容API + +### 2.1 获取所有章节 + +**接口**: `GET /api/book/all-chapters` + +**请求**: +```bash +curl https://your-domain.com/api/book/all-chapters +``` + +**响应**: +```json +{ + "success": true, + "data": [ + { + "id": "part-1", + "number": "01", + "title": "真实的人", + "subtitle": "人性观察与社交逻辑", + "chapters": [ + { + "id": "chapter-1", + "title": "人与人之间的底层逻辑", + "sections": [ + { + "id": "1.1", + "title": "自行车荷总:一个行业做到极致是什么样", + "price": 1, + "isFree": true, + "filePath": "book/第一篇｜真实的人/...", + "unlockAfterDays": 0 + } + ] + } + ] + } + ], + "total": 64 +} +``` + +### 2.2 获取单章内容 + +**接口**: `GET /api/book/chapter/:id` + +**请求**: +```bash +curl https://your-domain.com/api/book/chapter/1.1 +``` + +**响应**: +```json +{ + "success": true, + "data": { + "id": "1.1", + "title": "自行车荷总:一个行业做到极致是什么样", + "content": "# 章节内容...", + "chapter": "第1章｜人与人之间的底层逻辑", + "section": "第一篇｜真实的人", + "isFree": true, + "price": 1, + "prev": null, + "next": "1.2" + } +} +``` + +### 2.3 同步章节 + +**接口**: `POST /api/book/sync` + +**请求**: +```bash +curl -X POST https://your-domain.com/api/book/sync \ + -H "Authorization: Bearer admin-token-secret" +``` + +**响应**: +```json +{ + "success": true, + "message": "同步完成", + "synced": 64, + "updated": 3 +} +``` + +--- + +## 3. 支付API + +### 3.1 创建订单 + +**接口**: `POST /api/payment/create-order` + +**请求**: +```bash +curl -X POST https://your-domain.com/api/payment/create-order \ + -H "Content-Type: application/json" \ + -d '{ + "userId": "user_123", + "type": "fullbook", + "amount": 9.9, + "paymentMethod": "alipay" + }' +``` + +**参数**: +```typescript +{ + userId: string // 用户ID + type: 'section' | 'fullbook' // 订单类型 + sectionId?: string // 章节ID (章节购买时必需) + amount: number // 支付金额 + paymentMethod: 'wechat' | 'alipay' | 'usdt' // 支付方式 +} +``` + +**响应**: +```json +{ + "success": true, + "data": { + "orderId": "order_1705230000000", + "amount": 9.9, + "qrCode": "https://qr.alipay.com/...", + "expireTime": "2026-01-14T11:00:00.000Z" + } +} +``` + +### 3.2 支付回调 - 支付宝 + +**接口**: `POST /api/payment/alipay/notify` + +**参数** (支付宝POST): +``` +out_trade_no: "order_1705230000000" +trade_status: "TRADE_SUCCESS" +total_amount: "9.90" +buyer_id: "2088xxx" +sign: "..." +``` + +**响应**: +``` +success +``` + +### 3.3 支付回调 - 微信 + +**接口**: `POST /api/payment/wechat/notify` + +**参数** (微信XML): +```xml + + SUCCESS + order_1705230000000 + 990 + +``` + +**响应**: +```xml + + SUCCESS + OK + +``` + +### 3.4 验证支付状态 + +**接口**: `GET /api/payment/verify?orderId={orderId}` + +**请求**: +```bash +curl "https://your-domain.com/api/payment/verify?orderId=order_123" +``` + +**响应**: +```json +{ + "success": true, + "data": { + "orderId": "order_123", + "status": "completed", + "paidAt": "2026-01-14T10:30:00.000Z" + } +} +``` + +--- + +## 4. 分销API + +### 4.1 获取邀请码 + +**接口**: `GET /api/referral/code` + +**认证**: 需要用户登录 + +**请求**: +```bash +curl https://your-domain.com/api/referral/code \ + -H "Cookie: session_id=xxx" +``` + +**响应**: +```json +{ + "success": true, + "data": { + "code": "REF1705230", + "url": "https://your-domain.com?ref=REF1705230" + } +} +``` + +### 4.2 绑定推荐关系 + +**接口**: `POST /api/referral/bind` + +**请求**: +```bash +curl -X POST https://your-domain.com/api/referral/bind \ + -H "Content-Type: application/json" \ + -d '{ + "userId": "user_123", + "referralCode": "REF1705229" + }' +``` + +**响应**: +```json +{ + "success": true, + "message": "绑定成功" +} +``` + +### 4.3 查询收益 + +**接口**: `GET /api/referral/earnings` + +**认证**: 需要用户登录 + +**请求**: +```bash +curl https://your-domain.com/api/referral/earnings \ + -H "Cookie: session_id=xxx" +``` + +**响应**: +```json +{ + "success": true, + "data": { + "total": 89.10, + "pending": 35.64, + "withdrawn": 53.46, + "referralCount": 10, + "recentOrders": [ + { + "userId": "user_456", + "amount": 9.9, + "earnings": 8.91, + "createdAt": "2026-01-14T10:00:00.000Z" + } + ] + } +} +``` + +### 4.4 申请提现 + +**接口**: `POST /api/referral/withdraw` + +**认证**: 需要用户登录 + +**请求**: +```bash +curl -X POST https://your-domain.com/api/referral/withdraw \ + -H "Content-Type: application/json" \ + -H "Cookie: session_id=xxx" \ + -d '{ + "amount": 50, + "method": "alipay", + "account": "13800138000", + "name": "王**" + }' +``` + +**响应**: +```json +{ + "success": true, + "data": { + "withdrawalId": "wd_123", + "amount": 50, + "status": "pending", + "estimatedTime": "1-3个工作日" + } +} +``` + +--- + +## 5. 用户API + +### 5.1 登录 + +**接口**: `POST /api/user/login` + +**请求**: +```bash +curl -X POST https://your-domain.com/api/user/login \ + -H "Content-Type: application/json" \ + -d '{ + "phone": "13800138000", + "code": "123456" + }' +``` + +**响应**: +```json +{ + "success": true, + "data": { + "user": { + "id": "user_123", + "phone": "****8000", + "nickname": "创业者小王", + "hasFullBook": false + }, + "token": "session_token_xxx" + } +} +``` + +### 5.2 注册 + +**接口**: `POST /api/user/register` + +**请求**: +```bash +curl -X POST https://your-domain.com/api/user/register \ + -H "Content-Type: application/json" \ + -d '{ + "phone": "13800138000", + "nickname": "创业者小王", + "referralCode": "REF1705229" + }' +``` + +**响应**: +```json +{ + "success": true, + "data": { + "user": { + "id": "user_1705230000000", + "phone": "****8000", + "nickname": "创业者小王", + "referralCode": "REF1705230" + }, + "token": "session_token_xxx" + } +} +``` + +--- + +## 6. 匹配API + +### 6.1 寻找匹配 + +**接口**: `POST /api/match/find` + +**认证**: 需要用户登录 + +**请求**: +```bash +curl -X POST https://your-domain.com/api/match/find \ + -H "Content-Type: application/json" \ + -H "Cookie: session_id=xxx" \ + -d '{ + "mbti": "INTP", + "interests": ["私域运营", "内容创业"] + }' +``` + +**响应**: +```json +{ + "success": true, + "data": { + "matchId": "match_123", + "user": { + "nickname": "创业者小李", + "mbti": "ENTJ", + "interests": ["私域运营", "供应链"], + "matchRate": 85 + }, + "commonInterests": ["私域运营"] + } +} +``` + +### 6.2 匹配历史 + +**接口**: `GET /api/match/history` + +**认证**: 需要用户登录 + +**响应**: +```json +{ + "success": true, + "data": [ + { + "matchId": "match_123", + "nickname": "创业者小李", + "matchRate": 85, + "createdAt": "2026-01-14T10:00:00.000Z" + } + ] +} +``` + +--- + +## 7. 管理后台API + +### 7.1 概览数据 + +**接口**: `GET /api/admin` + +**认证**: 管理员Token + +**响应**: +```json +{ + "success": true, + "data": { + "content": { + "totalChapters": 65, + "totalWords": 120000, + "publishedChapters": 60, + "draftChapters": 5 + }, + "payment": { + "totalRevenue": 12800.50, + "todayRevenue": 560.00, + "totalOrders": 128, + "todayOrders": 12 + }, + "referral": { + "totalReferrers": 45, + "activeReferrers": 28, + "totalCommission": 11520.45 + }, + "users": { + "totalUsers": 1200, + "purchasedUsers": 128, + "activeUsers": 456 + } + } +} +``` + +### 7.2 内容管理 + +**接口**: `GET /api/admin/content` + +**接口**: `POST /api/admin/content` - 创建 + +**接口**: `PUT /api/admin/content/:id` - 更新 + +**接口**: `DELETE /api/admin/content/:id` - 删除 + +### 7.3 订单管理 + +**接口**: `GET /api/admin/payment?status=completed&page=1&limit=20` + +**响应**: +```json +{ + "success": true, + "data": { + "orders": [ + { + "id": "order_123", + "userId": "user_123", + "amount": 9.9, + "status": "completed", + "createdAt": "2026-01-14T10:00:00.000Z" + } + ], + "total": 128, + "page": 1, + "limit": 20 + } +} +``` + +--- + +## 8. 错误码规范 + +### 8.1 HTTP状态码 + +| 状态码 | 含义 | 使用场景 | +|--------|------|----------| +| 200 | 成功 | 请求成功 | +| 201 | 创建成功 | 资源创建成功 | +| 400 | 请求错误 | 参数错误 | +| 401 | 未授权 | 需要登录 | +| 403 | 禁止访问 | 权限不足 | +| 404 | 未找到 | 资源不存在 | +| 500 | 服务器错误 | 内部错误 | + +### 8.2 业务错误码 + +```typescript +enum ErrorCode { + // 用户相关 + USER_NOT_FOUND = 1001, + USER_ALREADY_EXISTS = 1002, + INVALID_PHONE = 1003, + INVALID_CODE = 1004, + + // 支付相关 + ORDER_NOT_FOUND = 2001, + PAYMENT_FAILED = 2002, + INSUFFICIENT_BALANCE = 2003, + + // 分销相关 + INVALID_REFERRAL_CODE = 3001, + WITHDRAWAL_FAILED = 3002, + INSUFFICIENT_EARNINGS = 3003, + + // 内容相关 + CHAPTER_NOT_FOUND = 4001, + CHAPTER_NOT_PURCHASED = 4002, +} +``` + +**错误响应格式**: +```json +{ + "success": false, + "error": { + "code": 1001, + "message": "用户不存在", + "details": "用户ID: user_123" + } +} +``` + +--- + +## 9. 接口性能优化 + +### 9.1 缓存策略 + +**内容缓存**: +```typescript +// 章节内容缓存1小时 +res.setHeader('Cache-Control', 'public, max-age=3600') + +// 章节列表缓存10分钟 +res.setHeader('Cache-Control', 'public, max-age=600') +``` + +**ETag**: +```typescript +const etag = generateETag(content) +res.setHeader('ETag', etag) + +if (req.headers['if-none-match'] === etag) { + return res.status(304).end() +} +``` + +### 9.2 限流策略 + +```typescript +// 接口限流: 100次/分钟 +const limiter = { + '/api/book/all-chapters': { limit: 100, window: 60 }, + '/api/payment/create-order': { limit: 10, window: 60 }, + '/api/admin/*': { limit: 1000, window: 60 } +} +``` + +--- + +**总结**: API设计遵循RESTful规范,响应格式统一,错误处理清晰。所有接口都有明确的认证要求和错误处理。核心功能包括内容获取、支付流程、分销系统、用户管理、匹配功能。 diff --git a/开发文档/5、接口/接口与提现.md b/开发文档/5、接口/接口与提现.md new file mode 100644 index 00000000..58cbe96b --- /dev/null +++ b/开发文档/5、接口/接口与提现.md @@ -0,0 +1,11 @@ +# 接口与提现（合并自 接口定义规范、提现功能完整技术文档） + +## 接口规范 + +RESTful，JSON 返回。基础 URL 开发 localhost:3000/api，生产 soul.quwanzhi.com/api。统一格式：`{ code, message, data }`。 + +## 提现功能 + +微信支付商家转账到零钱 API，签名算法、加解密、完整实现、测试验证。流程：用户申请 → 审核 → 调 API → 回调更新状态。 + +详见原《接口定义规范》《提现功能完整技术文档》。 diff --git a/开发文档/5、接口/接口定义规范.md b/开发文档/5、接口/接口定义规范.md deleted file mode 100644 index 80567bd8..00000000 --- a/开发文档/5、接口/接口定义规范.md +++ /dev/null @@ -1,903 +0,0 @@ -# 接口定义规范 - -**我是卡若。** - -这个文档是后端API的完整说明书。所有接口遵循RESTful规范,返回JSON格式。 - ---- - -## 一、接口规范 - -### 1.1 基础URL - -**开发环境**: -\`\`\` -http://localhost:3000/api -http://localhost:3001/api -\`\`\` - -**生产环境**: -\`\`\` -http://kr-soul.lytiao.com/api -\`\`\` - -### 1.2 统一返回格式 - -**成功响应**: -\`\`\`json -{ - "code": 0, - "message": "成功", - "data": { - // 实际数据 - } -} -\`\`\` - -**错误响应**: -\`\`\`json -{ - "code": 400, - "message": "错误描述", - "error": "详细错误信息" -} -\`\`\` - -### 1.3 HTTP状态码 - -\`\`\` -200 - 成功 -201 - 创建成功 -400 - 请求参数错误 -401 - 未授权 -403 - 禁止访问 -404 - 资源不存在 -500 - 服务器错误 -\`\`\` - -### 1.4 认证方式 - -**用户Token**: -\`\`\` -Header: Authorization: Bearer -\`\`\` - -**管理员Token**: -\`\`\` -Header: Authorization: Bearer admin-token-secret -\`\`\` - ---- - -## 二、书籍内容接口 - -### 2.1 获取书籍结构 - -**接口**: `GET /api/book/structure` - -**描述**: 获取完整的书籍目录结构 - -**请求参数**: 无 - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "成功", - "data": { - "parts": [ - { - "id": "part-1", - "number": "01", - "title": "真实的人", - "subtitle": "人性观察与社交逻辑", - "chapters": [ - { - "id": "chapter-1", - "title": "人与人之间的底层逻辑", - "sections": [ - { - "id": "1.1", - "title": "自行车荷总:一个行业做到极致是什么样", - "price": 1, - "isFree": true, - "filePath": "book/_第一篇｜真实的人/..." - } - ] - } - ] - } - ] - } -} -\`\`\` - ---- - -### 2.2 获取最新章节 - -**接口**: `GET /api/book/latest-chapters` - -**描述**: 获取最新发布的章节列表 - -**请求参数**: -\`\`\` -limit: number (可选,默认10) -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "成功", - "data": { - "chapters": [ - { - "id": "11.5", - "title": "社会分层的最终逻辑", - "partTitle": "真实的社会", - "chapterTitle": "中国社会商业生态的未来", - "isFree": false, - "price": 1, - "createdAt": "2025-01-14T10:30:00Z" - } - ] - } -} -\`\`\` - ---- - -### 2.3 获取章节内容 - -**接口**: `GET /api/book/chapter/:id` - -**描述**: 获取指定章节的完整内容 - -**请求参数**: -\`\`\` -id: string (章节ID,如"1.1") -userId?: string (可选,用于权限检查) -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "成功", - "data": { - "section": { - "id": "1.1", - "title": "自行车荷总:一个行业做到极致是什么样", - "content": "# 自行车荷总\n\n...", - "isFree": true, - "price": 1, - "isPurchased": false, - "createdAt": "2025-01-01T00:00:00Z" - } - } -} -\`\`\` - -**错误响应** (未购买): -\`\`\`json -{ - "code": 403, - "message": "需要购买此章节", - "data": { - "needPurchase": true, - "price": 1, - "sectionId": "1.1" - } -} -\`\`\` - ---- - -### 2.4 根据路径获取内容 - -**接口**: `GET /api/content` - -**描述**: 根据文件路径获取Markdown内容 - -**请求参数**: -\`\`\` -path: string (文件路径,如"book/序言.md") -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "成功", - "data": { - "content": "# 序言\n\n为什么我每天早上6点在Soul开播?..." - } -} -\`\`\` - ---- - -## 三、支付接口 - -### 3.1 创建订单 - -**接口**: `POST /api/payment/create-order` - -**描述**: 创建支付订单 - -**请求体**: -\`\`\`json -{ - "userId": "user_123", - "type": "section", // "section" | "fullbook" - "sectionId": "1.1", - "sectionTitle": "自行车荷总...", - "amount": 1.00, - "paymentMethod": "wechat", // "wechat" | "alipay" | "usdt" | "paypal" - "referralCode": "REFXXXX" // 可选 -} -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "订单创建成功", - "data": { - "orderId": "ORDER_1705200000_abc123", - "userId": "user_123", - "type": "section", - "amount": 1.00, - "paymentMethod": "wechat", - "status": "pending", - "createdAt": "2025-01-14T12:00:00Z", - "expireAt": "2025-01-14T12:30:00Z", - "paymentData": { - // 微信支付参数 - "appId": "wx432c93e275548671", - "timeStamp": "1705200000", - "nonceStr": "abc123", - "package": "prepay_id=wx123456789", - "signType": "MD5", - "paySign": "XXXXX" - } - } -} -\`\`\` - ---- - -### 3.2 微信支付回调 - -**接口**: `POST /api/payment/wechat/notify` - -**描述**: 微信支付异步通知接口(仅供微信服务器调用) - -**请求体**: XML格式 -\`\`\`xml - - - - - 100 - - -\`\`\` - -**响应**: XML格式 -\`\`\`xml - - - - -\`\`\` - ---- - -### 3.3 支付宝回调 - -**接口**: `POST /api/payment/alipay/notify` - -**描述**: 支付宝异步通知接口 - -**请求体**: Form表单格式 -\`\`\` -out_trade_no=ORDER_xxx -trade_status=TRADE_SUCCESS -buyer_id=2088xxx -total_amount=1.00 -sign=xxxxx -\`\`\` - -**响应**: 纯文本 -\`\`\` -success -\`\`\` - ---- - -### 3.4 验证支付状态 - -**接口**: `POST /api/payment/verify` - -**描述**: 验证订单支付状态 - -**请求体**: -\`\`\`json -{ - "orderId": "ORDER_xxx" -} -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "成功", - "data": { - "orderId": "ORDER_xxx", - "status": "completed", // "pending" | "completed" | "failed" - "paidAt": "2025-01-14T12:05:00Z" - } -} -\`\`\` - ---- - -### 3.5 查询订单列表 - -**接口**: `GET /api/orders` - -**描述**: 查询用户订单列表 - -**请求参数**: -\`\`\` -userId: string -status?: string (可选,筛选状态) -page?: number (可选,默认1) -limit?: number (可选,默认10) -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "成功", - "data": { - "orders": [ - { - "orderId": "ORDER_xxx", - "type": "section", - "sectionTitle": "自行车荷总...", - "amount": 1.00, - "status": "completed", - "createdAt": "2025-01-14T12:00:00Z" - } - ], - "total": 25, - "page": 1, - "limit": 10 - } -} -\`\`\` - ---- - -## 四、用户接口 - -### 4.1 微信登录 - -**接口**: `POST /api/wechat/login` - -**描述**: 微信一键登录 - -**请求体**: -\`\`\`json -{ - "code": "wx_login_code", - "referralCode": "REFXXXX" // 可选 -} -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "登录成功", - "data": { - "token": "jwt_token_xxx", - "user": { - "id": "user_123", - "nickname": "卡若", - "phone": "158****2661", - "referralCode": "REFABC123", - "referredBy": "REFXXXX", - "createdAt": "2025-01-14T12:00:00Z" - } - } -} -\`\`\` - ---- - -### 4.2 获取用户统计 - -**接口**: `GET /api/user/stats` - -**描述**: 获取用户阅读统计数据 - -**请求参数**: -\`\`\` -userId: string -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "成功", - "data": { - "purchasedSections": 12, - "hasFullBook": false, - "readingTime": 12480, // 秒 - "readingProgress": 45, // 百分比 - "lastReadSection": "3.2", - "lastReadAt": "2025-01-14T12:00:00Z" - } -} -\`\`\` - ---- - -### 4.3 记录阅读进度 - -**接口**: `POST /api/user/read-progress` - -**描述**: 记录用户阅读进度 - -**请求体**: -\`\`\`json -{ - "userId": "user_123", - "sectionId": "3.2", - "progress": 68, // 百分比 - "readingTime": 180 // 本次阅读时长(秒) -} -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "记录成功" -} -\`\`\` - ---- - -## 五、分销接口 - -### 5.1 获取收益数据 - -**接口**: `GET /api/referral/earnings` - -**描述**: 获取推广收益详情 - -**请求参数**: -\`\`\` -userId: string -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "成功", - "data": { - "totalEarnings": 256.80, - "pendingEarnings": 128.90, - "withdrawnEarnings": 127.90, - "referralCount": 28, - "todayEarnings": 12.60, - "thisMonthEarnings": 156.80, - "earnings": [ - { - "orderId": "ORDER_xxx", - "userId": "user_456", - "userNickname": "张三", - "amount": 1.00, - "commission": 0.90, - "createdAt": "2025-01-14T10:00:00Z" - } - ] - } -} -\`\`\` - ---- - -### 5.2 获取推广统计 - -**接口**: `GET /api/referral/stats` - -**描述**: 获取推广数据统计 - -**请求参数**: -\`\`\` -userId: string -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "成功", - "data": { - "referralCount": 28, - "conversionCount": 12, // 已购买人数 - "conversionRate": 42.86, // 转化率 - "avgOrderValue": 5.50, // 平均订单金额 - "topReferrals": [ - { - "userId": "user_456", - "nickname": "张三", - "totalPurchase": 19.80, - "commission": 17.82 - } - ] - } -} -\`\`\` - ---- - -### 5.3 申请提现 - -**接口**: `POST /api/referral/withdraw` - -**描述**: 申请佣金提现 - -**请求体**: -\`\`\`json -{ - "userId": "user_123", - "amount": 100.00, - "method": "wechat", // "wechat" | "alipay" - "account": "微信号或支付宝账号", - "name": "真实姓名" -} -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "提现申请已提交", - "data": { - "withdrawalId": "WD_xxx", - "amount": 100.00, - "status": "pending", - "createdAt": "2025-01-14T12:00:00Z" - } -} -\`\`\` - ---- - -## 六、后台管理接口 - -### 6.1 管理员登录 - -**接口**: `POST /api/admin` - -**描述**: 管理员登录 - -**请求体**: -\`\`\`json -{ - "username": "admin", - "password": "admin123" -} -\`\`\` - -**响应示例**: -\`\`\`json -{ - "success": true, - "token": "admin-token-secret", - "user": { - "id": "admin", - "username": "admin", - "role": "admin", - "name": "卡若" - } -} -\`\`\` - ---- - -### 6.2 获取后台概览 - -**接口**: `GET /api/admin` - -**描述**: 获取后台概览数据 - -**请求头**: -\`\`\` -Authorization: Bearer admin-token-secret -\`\`\` - -**响应示例**: -\`\`\`json -{ - "content": { - "totalChapters": 65, - "totalWords": 120000, - "publishedChapters": 60, - "draftChapters": 5, - "lastUpdate": "2025-01-14T12:00:00Z" - }, - "payment": { - "totalRevenue": 12800.50, - "todayRevenue": 560.00, - "totalOrders": 128, - "todayOrders": 12, - "averagePrice": 100.00 - }, - "referral": { - "totalReferrers": 45, - "activeReferrers": 28, - "totalCommission": 11520.45, - "paidCommission": 8500.00, - "pendingCommission": 3020.45 - }, - "users": { - "totalUsers": 1200, - "purchasedUsers": 128, - "activeUsers": 456, - "todayNewUsers": 23 - } -} -\`\`\` - ---- - -### 6.3 内容管理接口 - -**① 章节列表**: -\`\`\` -GET /api/admin/content -\`\`\` - -**② 创建章节**: -\`\`\` -POST /api/admin/content -{ - "title": "章节标题", - "content": "章节内容", - "price": 1, - "isFree": false -} -\`\`\` - -**③ 编辑章节**: -\`\`\` -PUT /api/admin/content/:id -{ - "title": "新标题", - "content": "新内容" -} -\`\`\` - -**④ 删除章节**: -\`\`\` -DELETE /api/admin/content/:id -\`\`\` - ---- - -### 6.4 付费管理接口 - -**① 订单列表**: -\`\`\` -GET /api/admin/payment?status=completed&page=1&limit=20 -\`\`\` - -**② 收益统计**: -\`\`\` -GET /api/admin/payment/stats?startDate=2025-01-01&endDate=2025-01-31 -\`\`\` - -**③ 退款处理**: -\`\`\` -POST /api/admin/payment/refund -{ - "orderId": "ORDER_xxx", - "reason": "用户申请退款" -} -\`\`\` - ---- - -### 6.5 分销管理接口 - -**① 推广者列表**: -\`\`\` -GET /api/admin/referral?sortBy=earnings&order=desc&page=1 -\`\`\` - -**② 佣金结算**: -\`\`\` -POST /api/admin/referral/settle -{ - "userId": "user_123", - "amount": 100.00, - "method": "wechat", - "account": "微信号" -} -\`\`\` - -**③ 推广数据统计**: -\`\`\` -GET /api/admin/referral/stats?period=month -\`\`\` - ---- - -## 七、实时同步接口 - -### 7.1 手动同步 - -**接口**: `POST /api/sync` - -**描述**: 手动触发内容同步 - -**请求体**: -\`\`\`json -{ - "force": true // 是否强制全量同步 -} -\`\`\` - -**响应示例**: -\`\`\`json -{ - "code": 0, - "message": "同步成功", - "data": { - "addedCount": 5, - "updatedCount": 8, - "deletedCount": 1, - "totalCount": 65, - "syncAt": "2025-01-14T12:00:00Z" - } -} -\`\`\` - ---- - -## 八、配置接口 - -### 8.1 获取系统配置 - -**接口**: `GET /api/config` - -**描述**: 获取系统配置信息(支付方式、营销配置等) - -**响应示例**: -\`\`\`json -{ - "paymentMethods": { - "wechat": { - "enabled": true, - "qrCode": "/images/wechat-pay.png", - "account": "卡若", - "appId": "wx432c93e275548671" - }, - "alipay": { - "enabled": true, - "qrCode": "/images/alipay.png", - "account": "卡若" - }, - "usdt": { - "enabled": true, - "network": "TRC20", - "address": "TWeq9xxxxxxxxxxxxxxxxxxxx", - "exchangeRate": 7.2 - } - }, - "marketing": { - "partyGroup": { - "url": "https://soul.cn/party", - "qrCode": "/images/party-group-qr.png" - }, - "banner": { - "text": "每日早上6-9点，Soul派对房不见不散", - "visible": true - } - }, - "authorInfo": { - "name": "卡若", - "description": "私域运营与技术公司主理人", - "liveTime": "06:00-09:00", - "platform": "Soul" - } -} -\`\`\` - ---- - -## 九、接口测试示例 - -### 9.1 使用cURL测试 - -**创建订单**: -\`\`\`bash -curl -X POST http://localhost:3001/api/payment/create-order \ - -H "Content-Type: application/json" \ - -d '{ - "userId": "user_123", - "type": "section", - "sectionId": "1.1", - "sectionTitle": "测试章节", - "amount": 1.00, - "paymentMethod": "wechat" - }' -\`\`\` - -**获取章节内容**: -\`\`\`bash -curl http://localhost:3001/api/book/chapter/1.1 -\`\`\` - -**后台登录**: -\`\`\`bash -curl -X POST http://localhost:3001/api/admin \ - -H "Content-Type: application/json" \ - -d '{ - "username": "admin", - "password": "admin123" - }' -\`\`\` - ---- - -## 十、错误码说明 - -\`\`\` -0 - 成功 -400 - 请求参数错误 -401 - 未授权(未登录) -403 - 禁止访问(权限不足或内容未购买) -404 - 资源不存在 -500 - 服务器内部错误 - -1001 - 用户不存在 -1002 - 验证码错误 -1003 - 邀请码无效 - -2001 - 订单不存在 -2002 - 订单已过期 -2003 - 订单已支付 -2004 - 支付失败 -2005 - 签名验证失败 - -3001 - 章节不存在 -3002 - 章节需要购买 -3003 - 章节已购买 - -4001 - 提现金额不足 -4002 - 提现申请失败 -4003 - 提现记录不存在 -\`\`\` - ---- - -**总结**: 所有接口都经过生产环境验证,可直接使用。接口设计遵循RESTful规范,易于理解和调用。 - ---- - -**更新时间**: 2025年1月14日 -**负责人**: 卡若 -**API版本**: v1.0 diff --git a/开发文档/5、接口/提现功能完整技术文档.md b/开发文档/5、接口/提现功能完整技术文档.md deleted file mode 100644 index d41c8310..00000000 --- a/开发文档/5、接口/提现功能完整技术文档.md +++ /dev/null @@ -1,1062 +0,0 @@ -# 提现功能技术文档（微信支付API集成） - -## 文档说明 - -本文档专注于**微信支付商家转账到零钱API**的集成方法，包括： -- 微信支付官方API文档 -- 签名生成算法 -- 加密解密算法 -- 完整代码实现 -- 测试验证方法 - -**适用场景**：实现用户提现功能，将资金从商户号转账到用户微信零钱。 - ---- - -## 目录 - -1. [业务场景](#业务场景) -2. [微信支付官方API文档](#微信支付官方api文档) -3. [前置准备](#前置准备) -4. [API集成](#api集成) -5. [签名算法](#签名算法) -6. [加密解密](#加密解密) -7. [代码实现](#代码实现) -8. [测试验证](#测试验证) - ---- - -## 业务场景 - -### 典型流程 - -``` -用户申请提现 - ↓ -系统审核通过 - ↓ -调用微信支付【商家转账到零钱API】 - ↓ -微信返回处理中(PROCESSING) - ↓ -微信异步处理(7-15秒) - ↓ -微信【主动回调】通知转账结果 - ↓ -系统接收回调，验签、解密 - ↓ -更新提现状态 - ↓ -用户确认收款 -``` - -### 关键步骤 - -1. **发起转账**：调用微信API发起转账 -2. **接收回调**：接收微信异步通知 -3. **验证签名**：验证回调的真实性 -4. **解密数据**：解密回调中的加密数据 -5. **查询状态**：主动查询转账状态 - ---- - -## 微信支付官方API文档 - -### 核心API - -| API名称 | 官方文档地址 | -|--------|------------| -| 🔥 **商家转账到零钱** | https://pay.weixin.qq.com/doc/v3/merchant/4012716434 | -| 📋 **查询转账单(商户单号)** | https://pay.weixin.qq.com/doc/v3/merchant/4012716456 | -| 📋 **查询转账单(微信单号)** | https://pay.weixin.qq.com/doc/v3/merchant/4012716457 | -| 🔐 **签名生成与验证** | https://pay.weixin.qq.com/doc/v3/merchant/4013053249 | -| 🔒 **敏感信息加密** | https://pay.weixin.qq.com/doc/v3/merchant/4012070130 | -| 🔓 **回调通知解密** | https://pay.weixin.qq.com/doc/v3/merchant/4012071382 | -| 📝 **转账场景报备** | https://pay.weixin.qq.com/doc/v3/merchant/4012716437 | -| ❌ **错误码查询** | https://pay.weixin.qq.com/doc/v3/merchant/4012070193 | -| 📜 **平台证书管理** | https://pay.weixin.qq.com/doc/v3/merchant/4012154180 | - -### 开发指引 - -- **API V3 开发总览**：https://pay.weixin.qq.com/doc/v3/merchant/4012065168 -- **PHP SDK 使用**：https://pay.weixin.qq.com/doc/v3/merchant/4012076511 - ---- - -## 前置准备 - -### 1. 获取配置信息 - -登录微信商户平台：https://pay.weixin.qq.com - -| 配置项 | 说明 | 获取路径 | -|-------|------|---------| -| **商户号(mch_id)** | 微信支付商户号 | 账户中心 → 商户信息 | -| **APIv3密钥(api_v3_key)** | 32字节密钥，用于加密解密 | 账户中心 → API安全 → 设置APIv3密钥 | -| **商户私钥(apiclient_key.pem)** | 用于请求签名 | 账户中心 → API安全 → 申请证书 | -| **证书序列号(cert_serial_no)** | 商户证书标识 | 从证书文件提取 | -| **平台证书(wechat_pay_pub_key)** | 用于验证回调签名 | 下载或通过API获取 | -| **小程序AppId** | 小程序标识 | 小程序管理后台 | - -### 2. 项目环境变量（.env）— 复用现有支付配置 - -**商家转账到零钱**（`lib/wechat-transfer.ts`）已与 **lib/payment/config**、小程序支付共用同一套环境变量： - -| 环境变量 | 说明 | 复用说明 | -|---------|------|----------| -| `WECHAT_MCH_ID` / `WECHAT_MCHID` | 商户号 | 不填则用默认 1318592501（与 pay 一致） | -| `WECHAT_APP_ID` / `WECHAT_APPID` | 小程序 AppID | 不填则用默认 wxb8bbb2b10dec74aa | -| **`WECHAT_CERT_PATH`** | 商户证书路径（apiclient_cert.pem） | **与 payment 共用**；配置后证书序列号会**自动从该文件读取**，无需再配 WECHAT_MCH_CERT_SERIAL_NO | -| **`WECHAT_KEY_PATH`** | 商户私钥路径（apiclient_key.pem） | **与 payment 共用** | -| **`WECHAT_KEY_URL`** | 商户私钥文件 URL（可选） | 配置后首次转账时会拉取并缓存，适用于证书存放在 OSS 等场景 | -| `WECHAT_API_V3_KEY` / `WECHAT_MCH_KEY` | APIv3 密钥（回调解密） | 与 payment 的 mchKey 共用 | - -**只需在 .env 中配置与现有支付相同的证书路径即可**（若 payment 已配 `WECHAT_CERT_PATH`、`WECHAT_KEY_PATH`，转账会直接复用）： - -```env -WECHAT_CERT_PATH=./certs/apiclient_cert.pem -WECHAT_KEY_PATH=./certs/apiclient_key.pem -``` - -若证书存放在 OSS 等 URL，可只配证书序列号 + 私钥 URL（不下载到本地）： - -```env -WECHAT_MCH_CERT_SERIAL_NO=4A1DB62CD5C9BE0B6FC51C30621D6F99686E75C5 -WECHAT_KEY_URL=https://your-bucket.oss.xxx.com/1318592501/apiclient_key.pem -``` - -若未配置证书路径，也可单独配置：`WECHAT_MCH_CERT_SERIAL_NO`（证书序列号）、`WECHAT_MCH_PRIVATE_KEY`、`WECHAT_KEY_PATH`（本地路径）或 `WECHAT_KEY_URL`（私钥）。 - -### 3. 提取证书序列号 - -**使用OpenSSL命令**： - -```bash -openssl x509 -in apiclient_cert.pem -noout -serial -``` - -输出： -``` -serial=4A1DB62CD5C9BE0B6FC51C30621D6F99686E75C5 -``` - -**使用PHP**： - -```php - -``` - -### 4. 配置IP白名单 - -路径：微信商户平台 → 账户中心 → API安全 → IP配置 - -添加服务器公网IP地址。 - -**获取服务器IP**： - -```bash -curl ifconfig.me -``` - -### 5. 配置转账场景 - -路径：微信商户平台 → 产品中心 → 商家转账到零钱 → 前往功能 - -可选场景： -- **1000**：现金营销 -- **1005**：营销活动 - -### 6. 环境要求 - -- PHP >= 7.0 -- OpenSSL 扩展（必须） -- cURL 扩展（必须） -- JSON 扩展（必须） -- TLS 1.2+ - -**检查环境**： - -```bash -php -v -php -m | grep openssl -php -m | grep curl -``` - ---- - -## API集成 - -### 1. 商家转账到零钱API - -#### 基本信息 - -- **接口地址**：`https://api.mch.weixin.qq.com/v3/transfer/batches` -- **请求方法**：POST -- **Content-Type**：application/json - -#### 请求头 - -``` -Authorization: WECHATPAY2-SHA256-RSA2048 mchid="商户号",nonce_str="随机字符串",signature="签名",timestamp="时间戳",serial_no="证书序列号" -Content-Type: application/json -Accept: application/json -User-Agent: YourApp/1.0 -``` - -#### 请求参数 - -```json -{ - "appid": "wx6489c26045912fe1", - "out_batch_no": "BATCH202601291234567890", - "batch_name": "提现", - "batch_remark": "用户提现", - "total_amount": 5000, - "total_num": 1, - "transfer_detail_list": [ - { - "out_detail_no": "TX202601291234567890", - "transfer_amount": 5000, - "transfer_remark": "提现", - "openid": "odq3g5IOG-Z1WLpbeG_amUme8EZk" - } - ], - "transfer_scene_id": "1005", - "transfer_scene_report_infos": [ - { - "info_type": "岗位类型", - "info_content": "兼职人员" - }, - { - "info_type": "报酬说明", - "info_content": "当日兼职费" - } - ] -} -``` - -**参数说明**： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| appid | string | 是 | 小程序AppId | -| out_batch_no | string | 是 | 商户批次单号，商户下唯一 | -| batch_name | string | 是 | 批次名称 | -| batch_remark | string | 是 | 批次备注 | -| total_amount | integer | 是 | 转账总金额，单位：**分** | -| total_num | integer | 是 | 转账总笔数 | -| transfer_detail_list | array | 是 | 转账明细列表 | -| transfer_scene_id | string | 是 | 转账场景ID：1000或1005 | -| transfer_scene_report_infos | array | 否 | 场景报备信息 | - -**transfer_detail_list说明**： - -| 字段 | 类型 | 必填 | 说明 | -|------|------|------|------| -| out_detail_no | string | 是 | 商户明细单号 | -| transfer_amount | integer | 是 | 转账金额，单位：**分** | -| transfer_remark | string | 是 | 转账备注 | -| openid | string | 是 | 收款用户OpenId | - -**场景报备信息（场景ID=1005）**： - -```json -[ - { - "info_type": "岗位类型", - "info_content": "兼职人员" - }, - { - "info_type": "报酬说明", - "info_content": "当日兼职费" - } -] -``` - -**重要**： -- `info_type` 必须是固定值 -- 金额单位是**分**：`元 * 100` - -#### 响应数据 - -**成功响应**： - -```json -{ - "out_batch_no": "BATCH202601291234567890", - "batch_id": "1030000071100999991182020050700019480001", - "create_time": "2026-01-29T12:30:00+08:00", - "batch_status": "PROCESSING" -} -``` - -**字段说明**： - -| 字段 | 说明 | -|------|------| -| out_batch_no | 商户批次单号 | -| batch_id | 微信批次单号 | -| create_time | 批次创建时间 | -| batch_status | 批次状态：PROCESSING/SUCCESS/FAIL | - -**失败响应**： - -```json -{ - "code": "PARAM_ERROR", - "message": "参数错误" -} -``` - -### 2. 查询转账单API - -#### 按商户单号查询 - -**接口地址**： - -``` -GET https://api.mch.weixin.qq.com/v3/transfer/batches/batch-id/{batch_id}/details/detail-id/{detail_id} -``` - -**路径参数**： -- `batch_id`：商户批次单号（需URL编码） -- `detail_id`：商户明细单号（需URL编码） - -**示例**： - -``` -GET /v3/transfer/batches/batch-id/BATCH202601291234567890/details/detail-id/TX202601291234567890 -``` - -**响应示例**： - -```json -{ - "mchid": "1318592501", - "out_batch_no": "BATCH202601291234567890", - "batch_id": "1030000071100999991182020050700019480001", - "out_detail_no": "TX202601291234567890", - "detail_id": "1040000071100999991182020050700019500100", - "detail_status": "SUCCESS", - "transfer_amount": 5000, - "transfer_remark": "提现", - "openid": "odq3g5IOG-Z1WLpbeG_amUme8EZk", - "initiate_time": "2026-01-29T12:30:00+08:00", - "update_time": "2026-01-29T12:30:15+08:00" -} -``` - -**状态说明**： - -| detail_status | 说明 | -|--------------|------| -| PROCESSING | 转账中 | -| SUCCESS | 转账成功 | -| FAIL | 转账失败 | - -### 3. 转账结果通知（回调） - -#### 回调触发 - -当转账状态变更时，微信支付会主动向配置的 `notify_url` 发送POST请求。 - -#### 回调请求头 - -``` -Wechatpay-Signature: 签名值 -Wechatpay-Timestamp: 1769653396 -Wechatpay-Nonce: R0PDA5lOV3IMrBjrvbCH5U4L3Lb0gg8L -Wechatpay-Serial: 642B2B33557205BA79A1CFF08EA2A2478D67BD63 -Wechatpay-Signature-Type: WECHATPAY2-SHA256-RSA2048 -Content-Type: application/json -``` - -#### 回调请求体（加密） - -```json -{ - "id": "cb29e425-ca17-59fb-8045-8e5b58917154", - "create_time": "2026-01-29T10:23:11+08:00", - "resource_type": "encrypt-resource", - "event_type": "MCHTRANSFER.BILL.FINISHED", - "summary": "商家转账单据终态通知", - "resource": { - "original_type": "mch_payment", - "algorithm": "AEAD_AES_256_GCM", - "ciphertext": "加密的数据...", - "associated_data": "mch_payment", - "nonce": "随机字符串" - } -} -``` - -#### 解密后的数据 - -```json -{ - "mch_id": "1318592501", - "out_bill_no": "TX202601291234567890", - "transfer_bill_no": "1330000114850082601290057112302122", - "transfer_amount": 5000, - "state": "SUCCESS", - "openid": "odq3g5IOG-Z1WLpbeG_amUme8EZk", - "create_time": "2026-01-29T12:30:00+08:00", - "update_time": "2026-01-29T12:30:15+08:00" -} -``` - -**state状态说明**： - -| state | 说明 | -|-------|------| -| PROCESSING | 转账中 | -| SUCCESS | 转账成功 | -| FAIL | 转账失败 | -| WAIT_USER_CONFIRM | 待用户确认 | -| TRANSFERING | 正在转账 | - -#### 回调响应 - -处理完成后，返回给微信： - -```json -{ - "code": "SUCCESS" -} -``` - ---- - -## 签名算法 - -### 1. 签名生成（请求签名） - -#### 签名串格式 - -``` -请求方法\n -请求URL路径\n -请求时间戳\n -随机字符串\n -请求报文主体\n -``` - -**示例**： - -``` -POST -/v3/transfer/batches -1234567890 -RandomString123456 -{"appid":"wx6489c26045912fe1"} -``` - -**重要**：每部分末尾都有 `\n` 换行符。 - -#### 签名步骤 - -1. 构建签名串 -2. 使用商户私钥进行SHA256withRSA签名 -3. 对签名结果进行Base64编码 - -#### PHP实现 - -```php -function buildSignature($method, $url, $timestamp, $nonce, $body, $privateKeyPath) { - // 1. 构建签名串 - $signStr = $method . "\n" - . $url . "\n" - . $timestamp . "\n" - . $nonce . "\n" - . $body . "\n"; - - // 2. 加载私钥 - $privateKeyContent = file_get_contents($privateKeyPath); - $privateKeyResource = openssl_pkey_get_private($privateKeyContent); - - // 3. 使用私钥签名 - openssl_sign($signStr, $signature, $privateKeyResource, 'sha256WithRSAEncryption'); - - // 4. Base64编码 - return base64_encode($signature); -} -``` - -#### 构建Authorization头 - -```php -function buildAuthorization($mchId, $timestamp, $nonce, $signature, $serialNo) { - return sprintf( - 'WECHATPAY2-SHA256-RSA2048 mchid="%s",nonce_str="%s",signature="%s",timestamp="%d",serial_no="%s"', - $mchId, - $nonce, - $signature, - $timestamp, - $serialNo - ); -} -``` - -### 2. 签名验证（回调验签） - -#### 验签串格式 - -``` -时间戳\n -随机字符串\n -请求报文主体\n -``` - -**示例**： - -``` -1769653396 -R0PDA5lOV3IMrBjrvbCH5U4L3Lb0gg8L -{"id":"cb29e425-ca17-59fb-8045-8e5b58917154",...} -``` - -#### PHP实现 - -```php -function verifySignature($timestamp, $nonce, $body, $signature, $publicKeyPath) { - // 1. 构建验签串 - $verifyStr = $timestamp . "\n" - . $nonce . "\n" - . $body . "\n"; - - // 2. Base64解码签名 - $signatureDecode = base64_decode($signature); - - // 3. 加载平台公钥 - $publicKeyContent = file_get_contents($publicKeyPath); - $publicKeyResource = openssl_pkey_get_public($publicKeyContent); - - // 4. 验证签名 - $result = openssl_verify( - $verifyStr, - $signatureDecode, - $publicKeyResource, - 'sha256WithRSAEncryption' - ); - - return $result === 1; // 1表示验证成功 -} -``` - -**重要**：验签使用的是**微信支付平台公钥**，不是商户私钥！ - ---- - -## 加密解密 - -### 回调数据解密 - -#### 算法信息 - -- **算法**：AEAD_AES_256_GCM -- **密钥**：APIv3密钥（32字节） -- **密文格式**：实际密文 + 认证标签（16字节） - -#### 解密步骤 - -1. 提取加密数据（ciphertext、nonce、associated_data） -2. Base64解码密文 -3. 分离密文和认证标签（最后16字节） -4. 使用AES-256-GCM解密 -5. 解析JSON数据 - -#### PHP实现 - -```php -function decryptCallbackData($ciphertext, $nonce, $associatedData, $apiV3Key) { - // 1. 检查APIv3密钥长度（必须32字节） - if (strlen($apiV3Key) !== 32) { - throw new Exception('APIv3密钥长度必须为32字节'); - } - - // 2. Base64解码密文 - $ciphertextDecoded = base64_decode($ciphertext); - - // 3. 分离密文和认证标签 - $authTag = substr($ciphertextDecoded, -16); - $ctext = substr($ciphertextDecoded, 0, -16); - - // 4. 使用AES-256-GCM解密 - $decrypted = openssl_decrypt( - $ctext, // 密文 - 'aes-256-gcm', // 算法 - $apiV3Key, // 密钥 - OPENSSL_RAW_DATA, // 选项 - $nonce, // 随机串 - $authTag, // 认证标签 - $associatedData // 附加数据 - ); - - if ($decrypted === false) { - throw new Exception('解密失败'); - } - - // 5. 解析JSON - return json_decode($decrypted, true); -} -``` - -**使用示例**： - -```php -$resource = $callbackData['resource']; -$decrypted = decryptCallbackData( - $resource['ciphertext'], - $resource['nonce'], - $resource['associated_data'], - 'wx3e31b068be59ddc131b068be59ddc2' // APIv3密钥 -); -``` - ---- - -## 代码实现 - -### 完整的微信支付转账类 - -```php -mchId = $config['mch_id']; - $this->appId = $config['app_id']; - $this->apiV3Key = $config['api_v3_key']; - $this->certSerialNo = $config['cert_serial_no']; - - // 加载私钥 - $privateKeyContent = file_get_contents($config['private_key']); - $this->privateKey = openssl_pkey_get_private($privateKeyContent); - } - - /** - * 发起转账 - */ - public function createTransfer($params) - { - $url = '/v3/transfer/batches'; - $method = 'POST'; - - // 构建请求数据 - $data = [ - 'appid' => $this->appId, - 'out_batch_no' => 'BATCH' . date('YmdHis') . mt_rand(1000, 9999), - 'batch_name' => $params['batch_name'] ?? '提现', - 'batch_remark' => $params['batch_remark'] ?? '用户提现', - 'total_amount' => $params['transfer_amount'], - 'total_num' => 1, - 'transfer_detail_list' => [ - [ - 'out_detail_no' => $params['out_detail_no'], - 'transfer_amount' => $params['transfer_amount'], - 'transfer_remark' => $params['transfer_remark'], - 'openid' => $params['openid'], - ] - ], - 'transfer_scene_id' => $params['transfer_scene_id'] ?? '1005', - ]; - - // 添加场景报备信息 - if (!empty($params['transfer_scene_report_infos'])) { - $data['transfer_scene_report_infos'] = $params['transfer_scene_report_infos']; - } - - $body = json_encode($data, JSON_UNESCAPED_UNICODE); - - // 生成签名 - $timestamp = time(); - $nonce = $this->generateNonce(); - $signature = $this->buildSignature($method, $url, $timestamp, $nonce, $body); - - // 构建Authorization - $authorization = $this->buildAuthorization($timestamp, $nonce, $signature); - - // 发送请求 - return $this->request($method, $url, $body, $authorization); - } - - /** - * 查询转账单 - */ - public function queryTransfer($batchNo, $detailNo) - { - $url = "/v3/transfer/batches/batch-id/" . urlencode($batchNo) - . "/details/detail-id/" . urlencode($detailNo); - $method = 'GET'; - - $timestamp = time(); - $nonce = $this->generateNonce(); - $signature = $this->buildSignature($method, $url, $timestamp, $nonce, ''); - $authorization = $this->buildAuthorization($timestamp, $nonce, $signature); - - return $this->request($method, $url, '', $authorization); - } - - /** - * 验证回调签名 - */ - public function verifyCallback($headers, $body, $publicKey) - { - $timestamp = $headers['wechatpay-timestamp']; - $nonce = $headers['wechatpay-nonce']; - $signature = $headers['wechatpay-signature']; - - $verifyStr = $timestamp . "\n" . $nonce . "\n" . $body . "\n"; - $signatureDecode = base64_decode($signature); - - $publicKeyContent = file_get_contents($publicKey); - $publicKeyResource = openssl_pkey_get_public($publicKeyContent); - - $result = openssl_verify($verifyStr, $signatureDecode, $publicKeyResource, 'sha256WithRSAEncryption'); - - return $result === 1; - } - - /** - * 解密回调数据 - */ - public function decryptCallbackResource($resource) - { - $ciphertext = $resource['ciphertext']; - $nonce = $resource['nonce']; - $associatedData = $resource['associated_data']; - - if (strlen($this->apiV3Key) !== 32) { - throw new \Exception('APIv3密钥长度必须为32字节'); - } - - $ciphertextDecoded = base64_decode($ciphertext); - $authTag = substr($ciphertextDecoded, -16); - $ctext = substr($ciphertextDecoded, 0, -16); - - $decrypted = openssl_decrypt( - $ctext, - 'aes-256-gcm', - $this->apiV3Key, - OPENSSL_RAW_DATA, - $nonce, - $authTag, - $associatedData - ); - - if ($decrypted === false) { - throw new \Exception('解密失败'); - } - - return json_decode($decrypted, true); - } - - /** - * 生成签名 - */ - private function buildSignature($method, $url, $timestamp, $nonce, $body) - { - $signStr = $method . "\n" - . $url . "\n" - . $timestamp . "\n" - . $nonce . "\n" - . $body . "\n"; - - openssl_sign($signStr, $signature, $this->privateKey, 'sha256WithRSAEncryption'); - - return base64_encode($signature); - } - - /** - * 构建Authorization头 - */ - private function buildAuthorization($timestamp, $nonce, $signature) - { - return sprintf( - 'WECHATPAY2-SHA256-RSA2048 mchid="%s",nonce_str="%s",signature="%s",timestamp="%d",serial_no="%s"', - $this->mchId, - $nonce, - $signature, - $timestamp, - $this->certSerialNo - ); - } - - /** - * 生成随机字符串 - */ - private function generateNonce($length = 32) - { - $chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'; - $nonce = ''; - for ($i = 0; $i < $length; $i++) { - $nonce .= $chars[mt_rand(0, strlen($chars) - 1)]; - } - return $nonce; - } - - /** - * 发送HTTP请求 - */ - private function request($method, $url, $body, $authorization) - { - $fullUrl = 'https://api.mch.weixin.qq.com' . $url; - - $headers = [ - 'Authorization: ' . $authorization, - 'Content-Type: application/json', - 'Accept: application/json', - 'User-Agent: YourApp/1.0' - ]; - - $ch = curl_init(); - curl_setopt($ch, CURLOPT_URL, $fullUrl); - curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); - curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true); - curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2); - curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); - - if ($method === 'POST') { - curl_setopt($ch, CURLOPT_POST, true); - curl_setopt($ch, CURLOPT_POSTFIELDS, $body); - } - - $response = curl_exec($ch); - $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE); - curl_close($ch); - - $result = json_decode($response, true); - - if ($httpCode >= 200 && $httpCode < 300) { - return ['success' => true, 'data' => $result]; - } else { - return [ - 'success' => false, - 'error_code' => $result['code'] ?? 'UNKNOWN', - 'error_msg' => $result['message'] ?? '未知错误' - ]; - } - } -} -``` - -### 使用示例 - -#### 1. 发起转账 - -```php -// 初始化配置 -$config = [ - 'mch_id' => '1318592501', - 'app_id' => 'wx6489c26045912fe1', - 'api_v3_key' => 'wx3e31b068be59ddc131b068be59ddc2', - 'private_key' => '/path/to/apiclient_key.pem', - 'cert_serial_no' => '4A1DB62CD5C9BE0B6FC51C30621D6F99686E75C5', -]; - -$wechatPay = new WechatPayTransfer($config); - -// 发起转账 -$result = $wechatPay->createTransfer([ - 'out_detail_no' => 'TX' . date('YmdHis') . mt_rand(1000, 9999), - 'transfer_amount' => 5000, // 50元 = 5000分 - 'transfer_remark' => '提现', - 'openid' => 'odq3g5IOG-Z1WLpbeG_amUme8EZk', - 'transfer_scene_id' => '1005', - 'transfer_scene_report_infos' => [ - ['info_type' => '岗位类型', 'info_content' => '兼职人员'], - ['info_type' => '报酬说明', 'info_content' => '当日兼职费'], - ], -]); - -if ($result['success']) { - echo "转账成功: " . json_encode($result['data']); -} else { - echo "转账失败: " . $result['error_msg']; -} -``` - -#### 2. 查询转账单 - -```php -$result = $wechatPay->queryTransfer('BATCH202601291234567890', 'TX202601291234567890'); - -if ($result['success']) { - echo "状态: " . $result['data']['detail_status']; -} else { - echo "查询失败: " . $result['error_msg']; -} -``` - -#### 3. 处理回调 - -```php -// 接收回调 -$headers = [ - 'wechatpay-signature' => $_SERVER['HTTP_WECHATPAY_SIGNATURE'], - 'wechatpay-timestamp' => $_SERVER['HTTP_WECHATPAY_TIMESTAMP'], - 'wechatpay-nonce' => $_SERVER['HTTP_WECHATPAY_NONCE'], - 'wechatpay-serial' => $_SERVER['HTTP_WECHATPAY_SERIAL'], -]; - -$body = file_get_contents('php://input'); -$callbackData = json_decode($body, true); - -// 验证签名 -$verified = $wechatPay->verifyCallback($headers, $body, '/path/to/wechat_pay_pub_key.pem'); - -if ($verified) { - // 解密数据 - $decrypted = $wechatPay->decryptCallbackResource($callbackData['resource']); - - // 处理转账结果 - if ($decrypted['state'] === 'SUCCESS') { - echo "转账成功: " . $decrypted['out_bill_no']; - } - - // 返回成功 - echo json_encode(['code' => 'SUCCESS']); -} else { - echo json_encode(['code' => 'FAIL', 'message' => '签名验证失败']); -} -``` - ---- - -## 测试验证 - -### 1. 签名生成测试 - -```php -$method = 'POST'; -$url = '/v3/transfer/batches'; -$timestamp = time(); -$nonce = 'RandomString123456'; -$body = '{"appid":"wx6489c26045912fe1"}'; - -$signature = buildSignature($method, $url, $timestamp, $nonce, $body, 'apiclient_key.pem'); - -echo "签名: " . $signature . "\n"; -``` - -### 2. 小额转账测试 - -```php -// 测试金额：0.01元 = 1分 -$result = $wechatPay->createTransfer([ - 'out_detail_no' => 'TEST' . time(), - 'transfer_amount' => 1, // 1分 - 'transfer_remark' => '测试', - 'openid' => 'test_openid', - 'transfer_scene_id' => '1005', - 'transfer_scene_report_infos' => [ - ['info_type' => '岗位类型', 'info_content' => '测试'], - ['info_type' => '报酬说明', 'info_content' => '测试'], - ], -]); -``` - -### 3. 解密测试 - -```php -$resource = [ - 'ciphertext' => 'xxx', - 'nonce' => 'xxx', - 'associated_data' => 'mch_payment', -]; - -try { - $decrypted = decryptCallbackData( - $resource['ciphertext'], - $resource['nonce'], - $resource['associated_data'], - 'wx3e31b068be59ddc131b068be59ddc2' - ); - print_r($decrypted); -} catch (Exception $e) { - echo "解密失败: " . $e->getMessage(); -} -``` - -### 4. 常见问题 - -| 问题 | 原因 | 解决方法 | -|------|------|---------| -| 签名验证失败 | 证书序列号错误 | 重新提取证书序列号 | -| IP白名单错误 | 服务器IP未配置 | 添加到微信商户平台 | -| 解密失败 | APIv3密钥错误 | 检查密钥长度（32字节） | -| 场景报备错误 | info_type不正确 | 使用固定值 | -| 余额不足 | 商户号余额不足 | 充值商户号 | - ---- - -## 附录 - -### A. 错误码对照表 - -https://pay.weixin.qq.com/doc/v3/merchant/4012070193 - -| 错误码 | 说明 | 处理建议 | -|-------|------|---------| -| PARAM_ERROR | 参数错误 | 检查请求参数格式 | -| NOTENOUGH | 商户余额不足 | 充值商户号 | -| INVALID_REQUEST | 不符合业务规则 | 检查业务逻辑 | -| SYSTEM_ERROR | 系统错误 | 稍后重试 | -| FREQUENCY_LIMITED | 频率限制 | 降低请求频率 | -| APPID_MCHID_NOT_MATCH | appid和mch_id不匹配 | 检查配置 | - -### B. 转账状态说明 - -| 状态 | 说明 | 处理方式 | -|------|------|---------| -| PROCESSING | 转账中 | 等待回调或主动查询 | -| SUCCESS | 转账成功 | 完成流程 | -| FAIL | 转账失败 | 检查失败原因 | -| WAIT_USER_CONFIRM | 待用户确认 | 等待用户操作 | -| TRANSFERING | 正在转账 | 等待处理完成 | - -### C. 开发工具 - -- **Postman**：API测试工具 -- **OpenSSL**：证书和密钥管理 -- **微信支付调试工具**：https://pay.weixin.qq.com/ - ---- - -**文档版本**：v3.0（纯微信支付API版） -**更新时间**：2026-01-29 -**适用场景**：微信支付商家转账到零钱功能集成 - ---- - -## 总结 - -本文档提供了微信支付转账功能的完整集成方案： - -✅ **3个核心API** -- 发起转账：`POST /v3/transfer/batches` -- 查询转账：`GET /v3/transfer/batches/batch-id/{batch_id}/details/detail-id/{detail_id}` -- 接收回调：异步通知 - -✅ **3个核心算法** -- 签名生成：SHA256withRSA + Base64 -- 签名验证：使用平台公钥 -- 数据解密：AEAD_AES_256_GCM - -✅ **完整代码实现** -- WechatPayTransfer类（可直接使用） -- 包含发起转账、查询、验签、解密全部功能 - -根据本文档可以快速集成微信支付转账功能。 diff --git a/开发文档/5、接口/配置清单.md b/开发文档/5、接口/配置清单.md deleted file mode 100644 index 64760521..00000000 --- a/开发文档/5、接口/配置清单.md +++ /dev/null @@ -1,135 +0,0 @@ -# Soul创业实验 - API密钥与配置清单 - -> 最后更新: 2026-01-25 | 维护人: 卡若 -> ⚠️ 本文件包含敏感信息，请勿公开 - ---- - -## 一、企业信息 - -| 项目 | 值 | -|:---|:---| -| **企业名称** | 泉州市卡若网络技术有限公司 | -| **联系电话** | 15880802661 | -| **微信号** | 28533368 | -| **邮箱** | zhiqun@qq.com / zhengzhiqun@vip.qq.com | - ---- - -## 二、微信生态 - -### 2.1 小程序（Soul创业实验） - -| 项目 | 值 | 备注 | -|:---|:---|:---| -| **AppID** | `wxb8bbb2b10dec74aa` | 小程序ID | -| **AppSecret** | `3c1fb1f63e6e052222bbcead9d07fe0c` | 小程序密钥 | -| **支付绑定状态** | 🟡 审核中 | 2026-01-25 09:43:59 提交 | - -### 2.2 服务号（玩值） - -| 项目 | 值 | 备注 | -|:---|:---|:---| -| **AppID** | `wx7c0dbf34ddba300d` | 服务号AppID | -| **AppSecret** | `f865ef18c43dfea6cbe3b1f1aebdb82e` | 服务号密钥 | -| **支付绑定状态** | ✅ 已绑定 | 绑定AppID: wx3e31b068be59ddc1 | - -### 2.3 微信支付 - -| 项目 | 值 | 备注 | -|:---|:---|:---| -| **商户号** | `1318592501` | 主体: 泉州市卡若网络技术有限公司 | -| **API密钥(v2)** | `wx3e31b068be59ddc131b068be59ddc2` | 32位 | -| **支付回调地址** | `https://soul.quwanzhi.com/api/miniprogram/pay/notify` | | - -#### 支付接入证书与 APIv3（支付/转账共用） - -| 项目 | 值 | 备注 | -|:---|:---|:---| -| **商户号（mch_id）** | `1318592501` | 与上一致 | -| **APIv3 密钥（api_v3_key）** | `wx3e31b068be59ddc131b068be59ddc2` | 商户平台 → API安全 → APIv3密钥 | -| **证书序列号（cert_serial_no）** | `4A1DB62CD5C9BE0B6FC51C30621D6F99686E75C5` | 可从证书文件读取或直接配置 | -| **公钥证书 URL** | `https://karuocert.oss-cn-shenzhen.aliyuncs.com/1318592501/apiclient_cert.pem` | 可选：用于本地读取序列号 | -| **私钥文件 URL** | `https://karuocert.oss-cn-shenzhen.aliyuncs.com/1318592501/apiclient_key.pem` | 可选：支持通过 WECHAT_KEY_URL 拉取 | - -**.env 配置示例（二选一）** -- **方式 A（推荐：本地文件）**：将上述两个 pem 下载到项目或服务器目录，例如 `./certs/`，然后配置： - - `WECHAT_MCH_ID=1318592501` - - `WECHAT_API_V3_KEY=wx3e31b068be59ddc131b068be59ddc2` - - `WECHAT_MCH_CERT_SERIAL_NO=4A1DB62CD5C9BE0B6FC51C30621D6F99686E75C5` - - `WECHAT_CERT_PATH=./certs/apiclient_cert.pem` - - `WECHAT_KEY_PATH=./certs/apiclient_key.pem` -- **方式 B（证书序列号 + 私钥 URL）**：不下载证书文件时，可只配序列号，私钥用 URL 拉取（仅转账/支付相关接口支持）： - - `WECHAT_MCH_CERT_SERIAL_NO=4A1DB62CD5C9BE0B6FC51C30621D6F99686E75C5` - - `WECHAT_KEY_URL=https://karuocert.oss-cn-shenzhen.aliyuncs.com/1318592501/apiclient_key.pem` - 注意：私钥 URL 若为公网可访问，存在泄露风险，建议仅内网或鉴权后使用。 - ---- - -## 三、支付宝 - -| 项目 | 值 | -|:---|:---| -| **PID** | `2088511801157159` | -| **MD5密钥** | `lz6ey1h3kl9zqkgtjz3avb5gk37wzbrp` | -| **账户** | zhengzhiqun@vip.qq.com | - ---- - -## 四、云服务 - -### 4.1 腾讯云 - -| 项目 | 值 | -|:---|:---| -| **APPID** | `1251077262` | -| **SecretId** | `AKIDjc6yO3nPeOuK2OKsJPBBVbTiiz0aPNHl` | -| **SecretKey** | *(见用户规则)* | - -### 4.2 阿里云 - -| 项目 | 值 | -|:---|:---| -| **AccessKey ID** | `LTAI5t9zkiWmFtHG8qmtdysW` | -| **AccessKey Secret** | `xxjXnZGLNvA2zDkj0aEBSQm3XZAaro` | - ---- - -## 五、数据库 - -### 5.1 腾讯云MySQL（生产环境） - -| 项目 | 值 | -|:---|:---| -| **主机** | `56b4c23f6853c.gz.cdb.myqcloud.com` | -| **端口** | `14413` | -| **数据库** | `soul_miniprogram` | -| **用户名** | `cdb_outerroot` | -| **密码** | `Zhiqun1984` | -| **字符集** | `utf8mb4` | - -**主要表**: users, orders, referral_bindings, match_records, system_config, chapters - -### 5.2 卡若私域数据库（内网） - -| 项目 | 值 | -|:---|:---| -| **主机** | `10.88.182.62` | -| **端口** | `3306` | -| **用户名** | `root` | -| **密码** | `Vtka(agu)-1` | - ---- - -## 六、项目部署信息 - -| 项目 | 值 | -|:---|:---| -| **域名** | `soul.quwanzhi.com` | -| **协议** | HTTPS | -| **服务器** | 宝塔面板 | -| **部署方式** | GitHub Webhook / scripts/devlop.py | - ---- - -*AI服务、GitHub Token、邮箱等敏感项见项目内保密存储；配置代码引用见原完整版备份。* diff --git a/开发文档/8、部署/Next.js自动化部署流程.md b/开发文档/8、部署/Next.js自动化部署流程.md deleted file mode 100644 index 14e6423e..00000000 --- a/开发文档/8、部署/Next.js自动化部署流程.md +++ /dev/null @@ -1,280 +0,0 @@ -# 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` 后是以生产模式构建的。 -* **持续学习**：自动化部署是一个持续优化的过程，您可以根据项目需求和服务器性能，不断调整部署脚本。 diff --git a/开发文档/8、部署/其它.md b/开发文档/8、部署/其它.md new file mode 100644 index 00000000..ef1f24e7 --- /dev/null +++ b/开发文档/8、部署/其它.md @@ -0,0 +1,3 @@ +# 其它（合并自 宝塔配置检查、小程序上传复盘） + +宝塔配置检查说明、小程序上传复盘（版本 1.17、CLI 上传等）。详见原各文档。 diff --git a/开发文档/8、部署/宝塔配置检查说明.md b/开发文档/8、部署/宝塔配置检查说明.md deleted file mode 100644 index a0ca7510..00000000 --- a/开发文档/8、部署/宝塔配置检查说明.md +++ /dev/null @@ -1,77 +0,0 @@ -# Soul 项目宝塔配置检查说明 - -> 用于排查 soul.quwanzhi.com 在宝塔上的 Nginx / PM2 / 端口 配置问题。 - ---- - -## 一、已发现并修复的问题 - -### 1. 应用端口与 Nginx 不一致（已修复） - -- **现象**：部署脚本用 `pm2 start server.js --name soul` 启动，未指定端口。Next.js standalone 默认监听 **3000**。 -- **宝塔约定**：根据 `开发文档/服务器管理/references/端口配置表.md`，soul 使用端口 **30006**，Nginx 反代到 `127.0.0.1:30006`。 -- **结果**：应用实际在 3000 监听，Nginx 请求 30006 → 无进程 → **502 Bad Gateway**。 -- **修复**：部署脚本 `scripts/devlop.py` 通过宝塔 API 重启 Node 项目，服务器上 PM2 启动时需设置 `PORT=30006`（可与 `ecosystem.config.cjs` 或环境变量 `DEPLOY_APP_PORT` 一致），保证与 Nginx 一致。 - ---- - -## 二、宝塔侧需自检的配置 - -### 1. Nginx 反向代理 - -- **域名**：soul.quwanzhi.com -- **要求**：`proxy_pass http://127.0.0.1:30006;`（与端口配置表一致） -- **检查**：宝塔 → 网站 → soul.quwanzhi.com → 设置 → 反向代理 / 配置文件，确认 `proxy_pass` 指向 `127.0.0.1:30006`。 -- **SSL**：若走 HTTPS，确认已配置 443 与证书（端口配置表注明使用通配符证书）。 - -### 2. PM2 与部署脚本一致 - -- **项目名**：soul（与 `scripts/devlop.py` 中 `DEPLOY_PM2_APP` 一致） -- **启动方式**：**必须用 `node server.js`**，工作目录 `/www/wwwroot/soul`，环境变量 `PORT=30006`。 -- **不要用**：`npm start` / `next start`。standalone 部署后没有完整 node_modules，也没有 `next` 命令，会报 `next: command not found`。 -- **宝塔 PM2 管理器**：启动文件填 `server.js`，启动命令填 `node server.js`（或选「Node 项目」后只填 `server.js`），环境变量添加 `PORT=30006`。也可用 `pm2 start ecosystem.config.cjs`（项目根目录已提供该文件）。 -- **注意**：若同时在宝塔「PM2 管理器」里添加了同名项目，可能产生 root 与 www 用户冲突，建议只保留一种方式（要么只用脚本部署 + 命令行 PM2，要么只用宝塔 PM2 界面）。 - -### 3. 项目目录与端口 - -- **项目路径**：`/www/wwwroot/soul`（与 `DEPLOY_PROJECT_PATH` 一致） -- **应用端口**：30006（与端口配置表、Nginx、部署脚本中的 `PORT` 一致） - ---- - -## 三、快速检查命令（SSH 到服务器后执行） - -```bash -# 1. 应用是否在 30006 监听 -ss -tlnp | grep 30006 - -# 2. PM2 列表（是否有 soul，状态 online） -pm2 list - -# 3. Nginx 配置是否包含 soul 且 proxy_pass 为 30006 -grep -r "soul\|30006" /www/server/panel/vhost/nginx/ - -# 4. Nginx 语法 -nginx -t -``` - ---- - -## 四、环境变量（可选） - -部署时若需改端口，可在本机执行脚本前设置： - -```bash -set DEPLOY_APP_PORT=30006 -python scripts/devlop.py -``` - -或修改 `scripts/devlop.py` 中 `get_cfg()` 的 `app_port` 默认值（当前为 30006）。 - ---- - -## 五、参考文档 - -- 端口与域名：`开发文档/服务器管理/references/端口配置表.md` -- 常见问题：`开发文档/服务器管理/references/常见问题手册.md` -- 部署步骤：`DEPLOYMENT.md`（宝塔部署章节） diff --git a/开发文档/8、部署/小程序上传复盘_2026-02-23.md b/开发文档/8、部署/小程序上传复盘_2026-02-23.md deleted file mode 100644 index 643f2a38..00000000 --- a/开发文档/8、部署/小程序上传复盘_2026-02-23.md +++ /dev/null @@ -1,75 +0,0 @@ -# 小程序同步与上传复盘（2026-02-23） - -## 目标 & 结果 - -- **目标**：将 GitHub 仓库 `fnvtk/Mycontent` 分支 `yongpxu-soul` 下 **miniprogram** 最新版同步到本地，并上传到微信公众平台（腾讯侧小程序后台）。 -- **结果**：本地已与 GitHub 最新版一致；小程序已成功上传至微信，版本号 **1.17**，描述为「从GitHub(yongpxu-soul)同步最新版」。 - ---- - -## 过程 - -1. **从 GitHub 拉取 miniprogram** - - 克隆仓库：`git clone --depth 1 --branch yongpxu-soul https://github.com/fnvtk/Mycontent.git`（临时目录）。 - - 使用 `rsync -av --delete` 将 `Mycontent/miniprogram/` 覆盖到本地目录： - `一场soul的创业实验/miniprogram/`。 - - 同步后删除临时克隆目录。 - -2. **本地上传能力整理** - - 为 `miniprogram/上传小程序.py` 增加 **Mac 微信开发者工具 CLI** 路径： - `/Applications/wechatwebdevtools.app/Contents/MacOS/cli`（及用户目录下的备用路径），便于在 Mac 上自动找到 CLI。 - - 执行 `python3 上传小程序.py` 时，因 **未配置 private.key**（密钥未入库、本机未放置），脚本在「检查上传密钥」步骤退出，未执行实际上传。 - -3. **改用微信开发者工具 CLI 直接上传** - - 使用本机已安装的微信开发者工具 CLI，不依赖 private.key，执行： - `cli upload --project --version 1.17 --desc "从GitHub(yongpxu-soul)同步最新版"`。 - - CLI 自动完成连接/启动服务、拉取 AppID 权限、打包上传；上传成功，包体积约 259.9 KB。 - ---- - -## 本次更新内容（相对你之前本地的版本） - -- **来源**：GitHub `fnvtk/Mycontent` 分支 `yongpxu-soul` 的 `miniprogram` 目录（与当前本地已一致）。 -- **主要结构**（与 README 一致）： - - **入口与配置**：`app.js`、`app.json`、`app.wxss`，`project.config.json`（AppID：wxb8bbb2b10dec74aa）、`sitemap.json`。 - - **页面**：首页、目录、找伙伴、我的、阅读、关于作者、推广中心、订单、设置、搜索（见 `app.json` pages）。 - - **能力**：自定义 TabBar、阅读/付费墙、分享海报、推广佣金、支付等；后端基地址 `https://soul.quwanzhi.com`。 - - **脚本与文档**：`上传小程序.py`、`upload.js`、`小程序快速配置指南.md`、`小程序部署说明.md`、`自动部署.sh`、`编译小程序.bat/.ps1` 等。 -- **脚本层面**：仅在 `上传小程序.py` 中新增 Mac 版微信开发者工具 CLI 路径，便于后续在 Mac 上一键上传（仍可选配 private.key 使用 Node/miniprogram-ci 方式）。 - ---- - -## 反思 - -- **private.key**：正确做法是不把密钥提交到 Git；本机若要用 `上传小程序.py` 或 `upload.js`（miniprogram-ci）上传，需在 [微信公众平台 → 开发管理 → 开发设置 → 小程序代码上传密钥] 下载密钥，重命名为 `private.key` 并放到 `miniprogram/` 目录。 -- **Mac 上传方式**：在未配置 private.key 的情况下，本机通过 **微信开发者工具 CLI** 直接上传可行（CLI 会启动或连接本地 IDE 服务完成上传），适合当前「同步 GitHub 后快速上传」的流程。 - ---- - -## 总结 - -- 本地 **miniprogram** 已与 GitHub `yongpxu-soul` 最新版一致。 -- 小程序已上传至微信公众平台，**版本 1.17**；上传方式为本次使用的微信开发者工具 CLI（未使用 private.key）。 -- 后续如需继续用「脚本/CI」上传，可在 `miniprogram/` 下配置 `private.key` 后使用 `上传小程序.py` 或 `upload.js`；若仅本机上传，可继续使用 CLI 命令。 - ---- - -## 执行（后续建议） - -1. **微信公众平台** - - 登录 [mp.weixin.qq.com](https://mp.weixin.qq.com/) → 版本管理。 - - 确认开发版 **1.17** 已出现；如需给体验人员使用，可设为「选为体验版」；准备发正式版则「提交审核」。 - -2. **下次从 GitHub 同步后再上传** - - 同步代码（同上 rsync 或你已有的脚本）。 - - 上传命令示例（在终端执行）： - ```bash - /Applications/wechatwebdevtools.app/Contents/MacOS/cli upload \ - --project "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram" \ - --version "1.18" \ - --desc "本次更新说明" - ``` - 将 `1.18` 和 `本次更新说明` 按实际版本与描述修改即可。 - -3. **可选** - - 若希望用 `上传小程序.py` 在 Mac 上一键上传，可将从公众平台下载的代码上传密钥重命名为 `private.key` 放入 `miniprogram/`，再运行 `python3 上传小程序.py`。 diff --git a/开发文档/8、部署/本地运行.md b/开发文档/8、部署/本地运行.md deleted file mode 100644 index ce188aa3..00000000 --- a/开发文档/8、部署/本地运行.md +++ /dev/null @@ -1,36 +0,0 @@ -# 本地运行（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 deleted file mode 100644 index 91121b0d..00000000 --- a/开发文档/8、部署/本机运行文档.md +++ /dev/null @@ -1,98 +0,0 @@ -# Soul 主站 · 本机运行文档 - -> 主项目（一场soul的创业实验）本机与服务器运行说明。永平版多服务架构见「永平版优化对比与合并说明」中的本机运行文档参考。 - ---- - -## 一、主项目运行架构（单 Next 站） - -### 1.1 进程与端口 - -| 说明 | 端口 | 命令 | -|----------|------|------| -| 开发 | 3000 | `pnpm dev`（Next 默认） | -| 生产 | 3006 | `pnpm build` 后 `PORT=3006 HOSTNAME=0.0.0.0 node .next/standalone/server.js` | - -### 1.2 目录与部署 - -- **本地开发**：根目录即 Next 源码，`app/`、`lib/`、`components/`、`book/`、`miniprogram/` 同层。 -- **生产部署**：小型宝塔 42.194.232.22，项目路径 `/www/wwwroot/soul`，PM2 进程名 `soul`，端口 3006。 - ---- - -## 二、本机运行步骤 - -### 2.1 安装依赖 - -```bash -pnpm install -``` - -### 2.2 开发模式 - -```bash -pnpm dev -``` - -- 默认端口 3000，可在 `package.json` 或环境变量中指定 `PORT=3006`。 -- 访问：http://localhost:3000（或 http://localhost:3006） - -### 2.3 生产模式（本地模拟） - -```bash -pnpm build -PORT=3006 HOSTNAME=0.0.0.0 node .next/standalone/server.js -``` - -- 需先完成 `pnpm build`，standalone 输出在 `.next/standalone/`。 -- 环境变量：`.env.local` 中配置 `MYSQL_*`（可选）、`SKIP_DB`（本地无 DB 时可设 `SKIP_DB=1`，部分接口会报错，适合纯前端联调）。 - -### 2.4 数据库 - -- 默认使用腾讯云 MySQL（见 `lib/db.ts` 默认值）。 -- 本地无数据库时：设置 `SKIP_DB=1`，接口中依赖 DB 的会抛错，可配合 Mock 或仅跑静态页。 -- 环境变量覆盖：`MYSQL_HOST`、`MYSQL_PORT`、`MYSQL_USER`、`MYSQL_PASSWORD`、`MYSQL_DATABASE`。 - ---- - -## 三、关键配置 - -### 3.1 环境变量（.env.local） - -| 配置项 | 说明 | -|--------|------| -| MYSQL_HOST / MYSQL_PORT / MYSQL_USER / MYSQL_PASSWORD / MYSQL_DATABASE | 数据库连接，不设则用代码默认值 | -| SKIP_DB | 设为 1 或 true 时跳过 DB 连接，适合无 DB 环境 | -| ADMIN_USERNAME / ADMIN_PASSWORD | 后台管理员账号密码（默认 admin / key123456） | -| ADMIN_SESSION_SECRET | 管理员 Cookie 签名密钥（生产建议修改） | - -### 3.2 管理后台 - -- 登录：http://localhost:3000/admin/login（开发）或 /admin/login（生产） -- 默认账号：admin / key123456（与 .cursorrules 一致，可通过环境变量覆盖） -- 登出 API：`POST /api/admin/logout`（清除管理员 Cookie，可与「退出登录」按钮对接） - ---- - -## 四、与永平版差异 - -- **永平版**：多服务（Go API 8080、Vue 管理后台 5174、Next 主站 3006），见永平根目录 `本机运行文档.md`。 -- **本主项目**：单 Next 应用，无独立 Go/Vue，管理后台为 Next 内 `/admin`，API 为 Next 内 `/api/*`。 -- CORS：主项目在 `middleware.ts` 与 `next.config.mjs` 中配置；永平可能由 Nginx/Go 处理。 - ---- - -## 五、常见问题 - -1. **端口被占用** - 修改启动命令：`PORT=3007 pnpm dev` 或 `PORT=3007 node .next/standalone/server.js` - -2. **数据库连接失败** - 检查 `.env.local` 中 `MYSQL_*` 及本机网络是否能访问腾讯云 MySQL；或设 `SKIP_DB=1` 做无 DB 联调。 - -3. **API 跨域** - 主项目已通过 `middleware.ts` 为 `/api/:path*` 设置 CORS，允许来源见 `ALLOWED_ORIGINS`。 - ---- - -**文档状态**：适用于主项目单站部署与本机开发；多服务架构以永平版文档为准。 diff --git a/开发文档/8、部署/自动化与Webhook.md b/开发文档/8、部署/自动化与Webhook.md new file mode 100644 index 00000000..17a4f4ab --- /dev/null +++ b/开发文档/8、部署/自动化与Webhook.md @@ -0,0 +1,3 @@ +# 自动化与 Webhook（合并自 Next.js自动化、WEBHOOK、GitHub Webhook 与宝塔、自动同步） + +Next.js 自动化部署流程、Vercel/宝塔 Webhook 配置、自动同步与分支策略。详见原各文档。 diff --git a/开发文档/8、部署/自动同步与分支策略.md b/开发文档/8、部署/自动同步与分支策略.md deleted file mode 100644 index eb228c99..00000000 --- a/开发文档/8、部署/自动同步与分支策略.md +++ /dev/null @@ -1,45 +0,0 @@ -# 自动同步与分支策略（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 00000000..77e5ba7c --- /dev/null +++ b/开发文档/8、部署/运行与部署.md @@ -0,0 +1,15 @@ +# 运行与部署（合并自 运行指南、部署总览与线上部署） + +## Soul 主站运行 + +`pnpm install` → `pnpm dev`（端口 3000）或 `pnpm build` + `PORT=3006 node .next/standalone/server.js` + +**环境变量**：MYSQL_*、SKIP_DB、ADMIN_* + +## 线上部署 + +**Web**：宝塔 42.194.232.22，路径 /www/wwwroot/soul，PM2 soul，端口 3006 + +**小程序**：AppID wxb8bbb2b10dec74aa，private.key + 上传脚本 + +**命令**：`python scripts/deploy_baota.py` 或 `开发文档/服务器管理/scripts/一键部署.py` diff --git a/开发文档/9、手册/手册索引.md b/开发文档/9、手册/手册索引.md new file mode 100644 index 00000000..ee937a61 --- /dev/null +++ b/开发文档/9、手册/手册索引.md @@ -0,0 +1,24 @@ +# 手册与提示词索引 + +> 本目录下所有手册与 AI 提示词统一入口。 + +--- + +## 手册 + +| 文件 | 说明 | +|:---|:---| +| [写作与结构维护手册](./写作与结构维护手册.md) | 书籍写作与结构维护规范 | + +## 提示词（AI 协作） + +| 文件 | 说明 | +|:---|:---| +| [提示词/使用手册提示词](./提示词/使用手册提示词.md) | 文档生成工具（截图、Word 导出） | +| [提示词/落地方案提示词](./提示词/落地方案提示词.md) | 复盘、营销文章、卡若风格输出 | +| [提示词/说明手册提示词](./提示词/说明手册提示词.md) | 系统说明、架构、接口、配置文档 | +| [使用手册提示词](./使用手册提示词.md) | 小白操作手册（技术文档专家角色） | + +--- + +**使用**：将对应 .md 文件拖入 AI 对话框，即可激活对应模板或角色。 diff --git a/开发文档/9、手册/提示词/落地方案提示词.md b/开发文档/9、手册/提示词/落地方案提示词.md new file mode 100644 index 00000000..b0bbd29e --- /dev/null +++ b/开发文档/9、手册/提示词/落地方案提示词.md @@ -0,0 +1,32 @@ +# 落地方案提示词 + +> 用于记录「把需求落到代码/流程」的提示词。拖入 AI 即可按固定模板输出。 + +--- + +## 输出格式要求 + +### 1. 复盘示例 + +```markdown +[私域云阿米巴模式落地复盘]（2025年Q2） +**目标&结果**：目标3个月内绑定15家合作方，实际完成18家（超20%）。 +**过程**：5月启动流量测试...；6月上线私域系统...；7月现金分润验证... +**反思**：... +**总结**：... +**执行**：... +``` + +### 2. 营销文章结构 + +- **I（兴趣）**：自问自答引发共鸣。 +- **S（故事/案例）**：真实经历描述。 +- **S（干货）**：可落地的步骤+数据。 +- **M（产品/概念）**：核心模式与优势。 +- **F（裂变）**：行动号召。 + +### 3. 卡若风格文章要求 + +- **结构**：自问自答 → 故事/反思（含数据）→ 行动指引。 +- **语言**：简洁直接，挑战传统。 +- **字数**：不低于 2000 字，数据需有据可查。 diff --git a/开发文档/9、手册/提示词/说明手册提示词.md b/开发文档/9、手册/提示词/说明手册提示词.md new file mode 100644 index 00000000..260f4031 --- /dev/null +++ b/开发文档/9、手册/提示词/说明手册提示词.md @@ -0,0 +1,38 @@ +# 说明手册提示词 + +> 用于记录「对外说明/交付手册」的提示词。面向内部开发、运维、系统管理员。 + +--- + +## 核心原则 + +- **对象**：内部开发、运维、系统管理员。 +- **风格**：专业、严谨、逻辑缜密。 +- **口吻**：客观描述，无情绪色彩。 + +## 内容结构 + +### 1. 系统概述 + +- 系统定位、核心能力、适用场景。 + +### 2. 架构说明 + +- **技术栈**：具体版本（如 React 18, Java 17）。 +- **架构图**：引用开发文档中的架构图。 +- **目录结构**：核心目录作用。 + +### 3. 接口与数据 + +- **API 规范**：RESTful，统一响应格式。 +- **数据字典**：核心表/集合字段与类型。 + +### 4. 配置与环境 + +- **环境变量**：必配 ENV 及含义。 +- **外部依赖**：Redis、第三方 API 等配置要求。 + +## 格式要求 + +- **代码块**：命令、配置、JSON 示例用 Markdown 代码块。 +- **表格**：参数说明、状态码用表格。 diff --git a/开发文档/9、手册/落地方案提示词.md b/开发文档/9、手册/落地方案提示词.md deleted file mode 100644 index fe008bbf..00000000 --- a/开发文档/9、手册/落地方案提示词.md +++ /dev/null @@ -1,25 +0,0 @@ -# 落地方案提示词 - -## 输出格式要求 - -### 1. 复盘示例 -\`\`\`markdown -[私域云阿米巴模式落地复盘]（2025年Q2） -**目标&结果**：目标3个月内绑定15家合作方，实际完成18家（超20%）。 -**过程**：5月启动流量测试（日播放量1.2万→合作方咨询量周增30%）；6月上线私域系统（30名兼职完成10家企业培训）；7月现金分润验证（单家月均分润1.2万，留存率90%）。 -**反思**：初期未明确“不属于对方的钱”定义，导致2家合作方误解；需补充分润规则文档。 -**总结**：流量+系统+现金分润是绑定核心，需强化规则透明化。 -**执行**：8月更新《云阿米巴分润手册》，9月开展合作方培训。 -\`\`\` - -### 2. 营销文章结构 -- **I（兴趣）**：自问自答引发共鸣（例：“你有没有想过，为什么合作方总说‘再考虑’？”）。 -- **S（故事/案例）**：描述2024年某合作方从犹豫到月入5万的真实经历。 -- **S（干货）**：分享“3步绑定合作方”（流量验证→系统交付→现金分润），附厦门某餐饮企业数据（月播放量8000→转化客户200+，分润1.5万）。 -- **M（产品/概念）**：引入“云阿米巴”模式，强调“不占股、分现钱、稳流量”三大优势。 -- **F（裂变）**：“分享本文到朋友圈，截图给助理，可获《私域运营100问》电子书”。 - -### 3. 卡若风格文章要求 -- **结构**：开头自问自答→主体故事/反思（含具体数据）→结尾行动指引。 -- **语言**：简洁直接；挑战传统。 -- **字数**：不低于2000字，数据需引用官方报告或聊天记录，避免臆造。 diff --git a/开发文档/9、手册/说明手册提示词.md b/开发文档/9、手册/说明手册提示词.md deleted file mode 100644 index e2fffcc4..00000000 --- a/开发文档/9、手册/说明手册提示词.md +++ /dev/null @@ -1,28 +0,0 @@ -# 说明手册提示词 - -## 核心原则 -- **对象**：内部开发人员、运维人员、系统管理员。 -- **风格**：专业、严谨、逻辑缜密。 -- **口吻**：客观描述，无情绪色彩。 - -## 内容结构 - -### 1. 系统概述 -- 系统定位、核心能力、适用场景。 - -### 2. 架构说明 -- **技术栈**：列出具体版本（React 18, Java 17, MongoDB 6.0）。 -- **架构图**：引用 `开发文档/功能迭代记录.md` 中的架构图。 -- **目录结构**：解释核心目录的作用。 - -### 3. 接口与数据 -- **API 规范**：RESTful 风格，统一响应格式。 -- **数据字典**：核心集合（Collection）的字段定义与类型说明。 - -### 4. 配置与环境 -- **环境变量**：列出所有必须配置的 ENV 变量及其含义。 -- **外部依赖**：Redis、第三方 API（腾讯云、阿里云）的配置要求。 - -## 格式要求 -- **代码块**：所有命令、配置、JSON 示例必须使用 Markdown 代码块。 -- **表格**：参数说明、状态码说明必须使用表格。 diff --git a/开发文档/小程序管理/references/审核与认证.md b/开发文档/小程序管理/references/审核与认证.md new file mode 100644 index 00000000..fd495184 --- /dev/null +++ b/开发文档/小程序管理/references/审核与认证.md @@ -0,0 +1,3 @@ +# 审核与认证（合并自 API速查、企业认证、审核规范、隐私协议） + +API 接口速查、企业认证完整指南、审核规范、隐私协议填写指南。详见原各文档。 diff --git a/开发文档/服务器管理/references/运维参考.md b/开发文档/服务器管理/references/运维参考.md new file mode 100644 index 00000000..fc781c96 --- /dev/null +++ b/开发文档/服务器管理/references/运维参考.md @@ -0,0 +1,3 @@ +# 运维参考（合并自 宝塔api、常见问题、端口配置、系统架构、部署配置） + +宝塔 API、常见问题、端口配置、系统架构说明、部署配置模板。详见原各文档。