soul/miniprogram/README.md

# Soul派对·创业实验 - 微信小程序版

> 一场真实的商业探索，从Soul平台直播到私域运营实战

## 📱 项目简介

这是《Soul派对·创业实验》电子书的微信小程序版本，集成了以下核心功能：

### 🎯 核心功能

1. **电子书阅读**
   - 完整的章节内容阅读
   - Markdown格式渲染
   - 书签和笔记功能
   - 阅读进度记录

2. **随机匹配书友**（类Soul星球）
   - 实时匹配志同道合的读者
   - 星空背景动画效果
   - 共同兴趣展示
   - 匹配度计算

3. **微信支付**（腾讯轻松付款）
   - 动态定价（9.9元起，每天+1元）
   - 微信支付接口集成
   - 订单管理
   - 支付状态查询

4. **分销系统**
   - 90%高佣金比例
   - 推广海报生成
   - 邀请码分享
   - 收益统计和提现

5. **后台管理**
   - 内容管理模块
   - 付费管理模块
   - 分销管理模块
   - 实时数据同步

## 🚀 快速开始

### 1. 环境准备

- 微信开发者工具（最新版）
- Node.js 16.x 或以上
- pnpm 或 npm

### 2. 配置小程序

修改 `project.config.json`：

\`\`\`json
{
  "appid": "你的小程序AppID",
  "projectname": "soul-party-book"
}
\`\`\`

### 3. 配置API地址

修改 `app.js` 中的 `apiBase`：

\`\`\`javascript
globalData: {
  apiBase: 'https://your-domain.com/api', // 改为你的实际域名
}
\`\`\`

### 4. 导入项目

1. 打开微信开发者工具
2. 选择"导入项目"
3. 选择 `miniprogram` 文件夹
4. 填入小程序AppID
5. 点击"导入"

### 5. 运行项目

- 点击"编译"按钮
- 在模拟器中查看效果
- 或扫码在真机上预览

## 📂 目录结构

\`\`\`
miniprogram/
├── pages/              # 页面目录
│   ├── index/         # 首页（书籍展示）
│   ├── match/         # 匹配书友页
│   ├── my/            # 我的页面（含分销）
│   ├── read/          # 阅读页面
│   └── chapters/      # 章节列表
├── utils/             # 工具类
│   └── payment.js     # 微信支付工具
├── assets/            # 静态资源
│   ├── images/        # 图片
│   └── icons/         # 图标
├── app.js             # 小程序入口
├── app.json           # 小程序配置
├── app.wxss           # 全局样式
└── project.config.json # 项目配置
\`\`\`

## 🔧 后端API配置

### 必需的API接口

小程序需要以下后端API支持：

#### 1. 认证接口

\`\`\`
POST /api/auth/wx-login      # 微信登录
POST /api/auth/validate      # Token验证
\`\`\`

#### 2. 书籍接口

\`\`\`
GET  /api/book/structure      # 获取书籍结构
GET  /api/book/latest-chapters # 获取最新章节
GET  /api/book/chapter/:id    # 获取章节内容
GET  /api/book/chapters       # 获取所有章节
\`\`\`

#### 3. 支付接口

\`\`\`
POST /api/payment/create      # 创建支付订单
POST /api/payment/notify      # 支付回调通知
GET  /api/payment/query       # 查询订单状态
\`\`\`

#### 4. 匹配接口

\`\`\`
GET  /api/match/online-count  # 获取在线人数
POST /api/match/find          # 开始匹配
GET  /api/match/recent        # 获取最近匹配
\`\`\`

#### 5. 分销接口

\`\`\`
GET  /api/referral/earnings   # 获取收益数据
GET  /api/referral/stats      # 获取推广统计
\`\`\`

#### 6. 用户接口

\`\`\`
GET  /api/user/stats          # 获取用户统计
POST /api/user/read-progress  # 记录阅读进度
\`\`\`

### API服务器部署

后端API已在项目的 `app/api/` 目录下实现，使用 Next.js API Routes。

启动后端服务：

\`\`\`bash
# 在项目根目录
pnpm install
pnpm dev
\`\`\`

服务将运行在 `http://localhost:3000`

## 💰 支付配置

### 1. 申请微信支付

1. 登录[微信支付商户平台](https://pay.weixin.qq.com/)
2. 申请开通"小程序支付"
3. 获取商户号和API密钥

### 2. 配置支付参数

在后端配置文件中设置：

\`\`\`javascript
// 微信支付配置
const WECHAT_PAY_CONFIG = {
  appId: 'your-miniprogram-appid',
  mchId: '你的商户号',
  apiKey: '你的API密钥',
  notifyUrl: 'https://your-domain.com/api/payment/notify'
}
\`\`\`

### 3. 配置服务器域名

在小程序后台 → 开发管理 → 开发设置 → 服务器域名：

\`\`\`
request合法域名:
- https://your-domain.com

uploadFile合法域名:
- https://your-domain.com

downloadFile合法域名:
- https://your-domain.com
\`\`\`

## 🎨 界面定制

### 修改主题色

在 `app.wxss` 中修改：

\`\`\`css
.brand-color {
  color: #FF4D4F;  /* 改为你的品牌色 */
}

.brand-bg {
  background-color: #FF4D4F;
}
\`\`\`

### 修改Logo和图标

替换 `assets/images/` 目录下的图片：

- `book-cover.png` - 书籍封面
- `planet.png` - 匹配星球图标
- `share-cover.png` - 分享封面
- `default-avatar.png` - 默认头像

## 📊 后台管理

访问后台管理系统：`https://your-domain.com/admin`

### 管理模块

1. **内容管理** - `/api/admin/content`
   - 章节列表
   - 创建/编辑/删除章节
   - 发布管理

2. **付费管理** - `/api/admin/payment`
   - 订单列表
   - 收益统计
   - 退款处理

3. **分销管理** - `/api/admin/referral`
   - 推广者列表
   - 佣金结算
   - 数据分析

### 默认账号

\`\`\`
用户名: admin
密码: admin123
\`\`\`

**⚠️ 上线前务必修改默认密码！**

## 🔄 实时同步

章节内容会自动从 `book/` 目录同步到小程序。

手动触发同步：

\`\`\`bash
curl -X POST https://your-domain.com/api/sync \
  -H "Content-Type: application/json" \
  -d '{"force": true}'
\`\`\`

## 📝 开发说明

### 添加新页面

1. 在 `pages/` 目录下创建页面文件夹
2. 创建 `.wxml`、`.wxss`、`.js` 文件
3. 在 `app.json` 的 `pages` 数组中注册

### 调试技巧

1. 使用 `console.log()` 输出调试信息
2. 在开发者工具中查看 Network 请求
3. 使用真机调试测试支付功能

## 🚢 发布上线

### 1. 代码审核

1. 点击"上传"按钮
2. 填写版本号和项目备注
3. 提交审核

### 2. 审核要点

- 确保所有功能正常
- 支付功能需完整测试
- 用户隐私协议完善
- 内容合规检查

### 3. 发布版本

审核通过后，在小程序后台点击"发布"。

## 📚 项目文档

- 项目文档：查看 `/开发文档/` 目录
- 使用说明：参考本文档

## 📄 许可证

本项目仅供学习交流使用。

---

**卡若** @ 2025年1月  
一场真实的创业实验，从0到1的完整记录。