# Soul创业派对 - 项目交付文档

> 版本: v0.1.0  
> 更新日期: 2026-01-26  
> 作者: 卡若 & Cunkebao

---

## 一、项目概述

### 1.1 项目简介

| 项目 | 说明 |
|------|------|
| **项目名称** | Soul创业派对（一场soul的创业实验） |
| **项目类型** | 电子书销售 + 创业者匹配平台 |
| **技术栈** | Next.js 16 + React + TypeScript + Tailwind CSS v4 |
| **数据库** | MySQL (腾讯云) |
| **小程序** | 微信原生小程序 |

### 1.2 核心功能

1. **电子书阅读与销售** - 章节付费阅读、整本购买
2. **创业者匹配** - 合伙人/投资人/导师/团队匹配
3. **分销推广系统** - 推广码绑定、佣金分成、自动提现
4. **管理后台** - 数据概览、用户管理、内容管理、分账管理

---

## 二、服务器部署信息

### 2.1 服务器配置

| 项目 | 配置 |
|------|------|
| **服务器名称** | 小型宝塔 |
| **服务器IP** | 42.194.232.22 |
| **配置** | 2核4G 5M带宽 |
| **操作系统** | CentOS |
| **运行环境** | Node.js v22.14.0 |
| **进程管理** | PM2 |

### 2.2 SSH连接信息

```bash
# SSH连接
ssh root@42.194.232.22
密码: Zhiqun1984

# 或使用sshpass
sshpass -p 'Zhiqun1984' ssh root@42.194.232.22
```

### 2.3 宝塔面板

| 项目 | 信息 |
|------|------|
| **面板地址** | https://42.194.232.22:9988/ckbpanel |
| **账号** | ckb |
| **密码** | zhiqun1984 |
| **API密钥** | hsAWqFSi0GOCrunhmYdkxy92tBXfqYjd |

### 2.4 项目部署路径

| 项目 | 路径/配置 |
|------|----------|
| **项目目录** | /www/wwwroot/soul |
| **PM2配置** | /www/server/nodejs/vhost/pm2_configs/soul/ecosystem.config.cjs |
| **PID文件** | /www/server/nodejs/vhost/pids/soul.pid |
| **错误日志** | /www/wwwlogs/nodejs/soul_error.log |
| **输出日志** | /www/wwwlogs/nodejs/soul_out.log |
| **运行端口** | 3006 |
| **访问域名** | https://soul.quwanzhi.com |

### 2.5 PM2配置详情

```javascript
// /www/server/nodejs/vhost/pm2_configs/soul/ecosystem.config.cjs
module.exports = {
  apps: [{
    name: 'soul',
    script: 'npm',
    args: 'start',
    cwd: '/www/wwwroot/soul',
    env: {
      NODE_ENV: 'production',
      PORT: '3006'
    },
    instances: 1,
    exec_mode: 'fork',
    autorestart: true,
    watch: false,
    max_memory_restart: '500M',
    error_file: '/www/wwwlogs/nodejs/soul_error.log',
    out_file: '/www/wwwlogs/nodejs/soul_out.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss'
  }]
}
```

---

## 三、数据库配置

### 3.1 MySQL连接信息

| 项目 | 配置 |
|------|------|
| **数据库类型** | MySQL (腾讯云) |
| **主机地址** | 56b4c23f6853c.gz.cdb.myqcloud.com |
| **端口** | 14413 |
| **用户名** | cdb_outerroot |
| **密码** | Zhiqun1984 |
| **数据库名** | soul_miniprogram |
| **字符集** | utf8mb4 |

### 3.2 连接字符串

```bash
# MySQL命令行连接
mysql -h 56b4c23f6853c.gz.cdb.myqcloud.com -P 14413 -u cdb_outerroot -p soul_miniprogram

# 密码: Zhiqun1984
```

### 3.3 数据表结构

| 表名 | 用途 | 主要字段 |
|------|------|----------|
| **users** | 用户表 | id, open_id, nickname, phone, referral_code, has_full_book, earnings, pending_earnings |
| **orders** | 订单表 | id, order_sn, user_id, product_type, amount, status, transaction_id |
| **referral_bindings** | 推广绑定表 | referrer_id, referee_id, referral_code, commission_amount, status |
| **match_records** | 匹配记录表 | user_id, match_type, phone, wechat_id, status |
| **chapters** | 章节内容表 | id, part_title, chapter_title, section_title, content, is_free, price |
| **system_config** | 系统配置表 | config_key, config_value, description |

### 3.4 数据库初始化

访问以下API自动创建表结构：
```
GET https://soul.quwanzhi.com/api/db/init
```

---

## 四、支付配置

### 4.1 支付宝配置

| 项目 | 配置值 |
|------|--------|
| **PID** | 2088511801157159 |
| **收款账户** | zhengzhiqun@vip.qq.com |
| **MD5密钥** | lz6ey1h3kl9zqkgtjz3avb5gk37wzbrp |
| **回调地址** | https://soul.quwanzhi.com/api/payment/alipay/notify |

### 4.2 微信支付配置

| 项目 | 配置值 |
|------|--------|
| **服务号AppID** | wx7c0dbf34ddba300d |
| **服务号AppSecret** | f865ef18c43dfea6cbe3b1f1aebdb82e |
| **商户号** | 1318592501 |
| **商户API密钥** | wx3e31b068be59ddc131b068be59ddc2 |
| **回调地址** | https://soul.quwanzhi.com/api/payment/wechat/notify |

### 4.3 网站微信配置（可选）

| 项目 | 配置值 |
|------|--------|
| **网站AppID** | wx432c93e275548671 |
| **网站AppSecret** | 25b7e7fdb7998e5107e242ebb6ddabd0 |
| **MP验证文件** | SP8AfZJyAvprRORT |

---

## 五、小程序配置

### 5.1 微信小程序

| 项目 | 配置值 |
|------|--------|
| **小程序AppID** | wxb8bbb2b10dec74aa |
| **后端API地址** | https://soul.quwanzhi.com |
| **代码位置** | 项目根目录/miniprogram/ |

### 5.2 小程序目录结构

```
miniprogram/
├── app.js              # 入口文件
├── app.json            # 全局配置
├── pages/
│   ├── index/          # 首页
│   ├── chapters/       # 目录页
│   ├── read/           # 阅读页
│   ├── match/          # 匹配页
│   ├── my/             # 我的页面
│   └── ...
├── custom-tab-bar/     # 自定义TabBar
└── utils/
    ├── payment.js      # 支付工具
    └── util.js         # 通用工具
```

---

## 六、API接口清单

### 6.1 用户相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/wechat/login` | POST | 微信登录 |
| `/api/user/profile` | GET/PUT | 获取/更新用户信息 |
| `/api/miniprogram/login` | POST | 小程序登录 |

### 6.2 书籍相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/book/chapters` | GET | 获取目录 |
| `/api/book/chapter/[id]` | GET | 获取章节内容 |
| `/api/book/all-chapters` | GET | 获取所有章节 |
| `/api/search` | GET | 搜索内容 |

### 6.3 支付相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/payment/create-order` | POST | 创建订单 |
| `/api/payment/methods` | GET | 获取支付方式 |
| `/api/payment/status/[orderSn]` | GET | 查询订单状态 |
| `/api/payment/alipay/notify` | POST | 支付宝回调 |
| `/api/payment/wechat/notify` | POST | 微信回调 |
| `/api/miniprogram/pay` | POST | 小程序支付 |

### 6.4 推广相关

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/referral/bind` | POST | 绑定推广码 |
| `/api/referral/data` | GET | 获取推广数据 |
| `/api/withdraw` | POST | 申请提现 |

### 6.5 管理后台

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/admin` | GET | 管理后台数据概览 |
| `/api/admin/chapters` | GET/POST/PUT | 章节管理 |
| `/api/admin/content` | GET/PUT | 内容管理 |
| `/api/admin/payment` | GET | 支付记录 |
| `/api/admin/referral` | GET | 推广数据 |
| `/api/admin/withdrawals` | GET/POST | 提现管理 |

---

## 七、项目结构

```
soul/
├── app/                      # Next.js App Router
│   ├── api/                  # API路由
│   ├── admin/                # 管理后台页面
│   ├── chapters/             # 目录页
│   ├── read/                 # 阅读页
│   ├── match/                # 匹配页
│   ├── my/                   # 个人中心
│   └── page.tsx              # 首页
├── book/                     # 书籍Markdown内容
│   ├── 第一篇｜真实的人/
│   ├── 第二篇｜真实的行业/
│   ├── 第三篇｜真实的错误/
│   ├── 第四篇｜真实的赚钱/
│   └── 第五篇｜真实的社会/
├── components/               # React组件
│   ├── ui/                   # 基础UI组件
│   └── modules/              # 业务模块组件
├── lib/                      # 工具库
│   ├── db.ts                 # 数据库连接
│   ├── payment/              # 支付模块
│   └── modules/              # 业务模块
├── miniprogram/              # 微信小程序代码
├── public/                   # 静态资源
├── styles/                   # 样式文件
└── 开发文档/                  # 开发文档
```

---

## 八、本地开发

### 8.1 环境要求

- Node.js >= 22.x
- pnpm >= 9.x
- MySQL 8.x（或使用线上数据库）

### 8.2 安装与运行

```bash
# 克隆项目
git clone <仓库地址>
cd 一场soul的创业实验

# 安装依赖
pnpm install

# 开发模式运行
pnpm dev

# 构建
pnpm build

# 生产模式运行
pnpm start
```

### 8.3 环境变量（可选）

项目使用硬编码配置，如需修改可创建 `.env.local`：

```env
# 数据库配置
DB_HOST=56b4c23f6853c.gz.cdb.myqcloud.com
DB_PORT=14413
DB_USER=cdb_outerroot
DB_PASSWORD=Zhiqun1984
DB_NAME=soul_miniprogram

# 应用配置
NEXT_PUBLIC_BASE_URL=https://soul.quwanzhi.com
NODE_ENV=production
PORT=3006
```

---

## 九、部署流程

### 9.1 标准部署步骤

```bash
# 1. 本地压缩代码（排除大目录）
cd /项目路径
tar --exclude='node_modules' --exclude='.next' --exclude='.git' --exclude='miniprogram' \
    -czf /tmp/soul_update.tar.gz .

# 2. 上传到服务器
sshpass -p 'Zhiqun1984' scp /tmp/soul_update.tar.gz root@42.194.232.22:/tmp/

# 3. SSH登录服务器
sshpass -p 'Zhiqun1984' ssh root@42.194.232.22

# 4. 停止服务
export PATH=/www/server/nodejs/v22.14.0/bin:$PATH
pm2 stop soul

# 5. 更新代码
cd /www/wwwroot/soul
rm -rf app components lib public styles book api addons scripts 开发文档 *.json *.ts *.mjs .next
tar -xzf /tmp/soul_update.tar.gz
rm /tmp/soul_update.tar.gz

# 6. 安装依赖并构建
pnpm install
pnpm run build

# 7. 启动服务
pm2 start /www/server/nodejs/vhost/pm2_configs/soul/ecosystem.config.cjs
pm2 save

# 8. 验证
curl http://localhost:3006
```

### 9.2 快速部署脚本

项目根目录有 `quick_deploy.sh`，可一键部署。

---

## 十、常用运维命令

### 10.1 服务管理

```bash
# 登录服务器
sshpass -p 'Zhiqun1984' ssh root@42.194.232.22

# 设置环境变量
export PATH=/www/server/nodejs/v22.14.0/bin:$PATH

# 查看进程状态
pm2 list

# 重启服务
pm2 restart soul

# 查看日志
pm2 logs soul --lines 50

# 查看实时日志
pm2 logs soul

# 停止服务
pm2 stop soul

# 启动服务
pm2 start /www/server/nodejs/vhost/pm2_configs/soul/ecosystem.config.cjs
```

### 10.2 日志查看

```bash
# 错误日志
tail -100 /www/wwwlogs/nodejs/soul_error.log

# 输出日志
tail -100 /www/wwwlogs/nodejs/soul_out.log
```

### 10.3 端口检查

```bash
# 检查3006端口
ss -tlnp | grep 3006

# 测试本地访问
curl http://localhost:3006
```

---

## 十一、Git仓库

### 11.1 仓库信息

| 项目 | 信息 |
|------|------|
| **分支** | soul-content |
| **本地路径** | /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验 |

### 11.2 Git操作

```bash
# 查看状态
git status

# 提交代码
git add .
git commit -m "feat: 功能描述"

# 推送
git push origin soul-content
```

---

## 十二、联系信息

| 项目 | 信息 |
|------|------|
| **项目负责人** | 卡若 |
| **电话** | 15880802661 |
| **微信** | 28533368 |
| **邮箱** | zhiqun@qq.com |

---

## 十三、附录

### A. 技术栈版本

| 技术 | 版本 |
|------|------|
| Next.js | 16.0.10 |
| React | Latest |
| TypeScript | 5.9.3 |
| Tailwind CSS | 4.1.9 |
| Node.js | 22.14.0 |
| MySQL | 8.x |
| PM2 | Latest |

### B. 相关文档

- 开发文档目录: `/开发文档/`
- 小程序配置指南: `/miniprogram/小程序快速配置指南.md`
- 部署说明: `/miniprogram/小程序部署说明.md`

### C. 访问入口

| 入口 | 地址 |
|------|------|
| **前台首页** | https://soul.quwanzhi.com |
| **管理后台** | https://soul.quwanzhi.com/admin |
| **宝塔面板** | https://42.194.232.22:9988/ckbpanel |

---

**文档版本**: v1.0  
**最后更新**: 2026-01-26
