fnvtk/soul
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d17150154c12753ad2cca9a92da7eebdb305719a
soul/开发文档/核心功能总览.md
v0 f3195d9331 refactor: overhaul homepage and app structure 
Simplify homepage, show chapter counts, display directory, trim bottom nav, in-page match feature, move marketing content, and enhance "My" page.

#VERCEL_SKIP

Co-authored-by: undefined <undefined+undefined@users.noreply.github.com>
2026-01-14 05:10:32 +00:00

19 KiB
Raw Blame History

Soul派对·创业实验 - 核心功能总览

项目定位: 知识付费+私域运营+分销裂变的三合一商业系统
技术栈: Next.js + TypeScript + Tailwind CSS + Zustand + 微信小程序
更新时间: 2025年1月14日

一、项目架构概览

1.1 双端架构

``` Web端 (Next.js) 小程序端 (WeChat Mini Program) ↓ ↓ 共享后端API (Next.js API Routes) ↓ 统一数据层 (localStorage + 未来MongoDB) ```

1.2 核心业务模块

  • 内容模块: Markdown文件系统 + 动态渲染
  • 支付模块: 支付宝 + 微信支付 + USDT + PayPal
  • 分销模块: 90%佣金分润 + 邀请码系统
  • 匹配模块: 类Soul星球的书友匹配功能
  • 后台模块: 三大管理中心(内容/付费/分销)

二、核心功能详解

2.1 知识付费系统

2.1.1 定价策略

  • 整书定价: 固定9.9元
  • 单章定价: 1元/章
  • 动态定价: 小程序版支持"每天+1元"递增模式(当前默认9.9元)

2.1.2 内容管理

文件系统架构: ``` book/ ├── 序言｜为什么我每天早上6点在Soul开播?.md ├── _第一篇｜真实的人/ │ ├── 第1章｜人与人之间的底层逻辑/ │ │ ├── 1.1 自行车荷总....md │ │ ├── 1.2 老墨....md │ │ └── ... │ └── 第2章｜人性困境案例/ ├── 第二篇｜真实的行业/ │ ├── 第3章｜电商篇/ │ ├── 第4章｜内容商业篇/ │ └── 第5章｜传统行业篇/ ├── 第三篇｜真实的错误/ ├── 第四篇｜真实的赚钱/ ├── 第五篇｜真实的社会/ └── 尾声｜这本书的真实目的.md ```

核心数据结构: ```typescript // 五级结构: Part -> Chapter -> Section interface Section { id: string // 章节ID (如: "1.1") title: string // 标题 price: number // 单章价格 isFree: boolean // 是否免费 filePath: string // 文件路径 unlockAfterDays?: number // 定时解锁(天数) createdAt?: string // 创建时间 } ```

关键功能:

  • ✅ Markdown自动解析和渲染
  • ✅ 章节权限控制(免费/付费/定时解锁)
  • ✅ 阅读进度记录
  • ✅ 目录树生成
  • ✅ SEO优化(SSR服务端渲染)

API接口:

  • GET /api/book/structure - 获取书籍结构
  • GET /api/book/latest-chapters - 获取最新章节
  • GET /api/book/chapter/:id - 获取章节内容
  • GET /api/content?path=xxx - 根据路径获取内容

2.2 支付系统

2.2.1 多渠道支付架构

支付适配器模式: ```typescript // 统一支付接口 interface PaymentProvider { createOrder(params): PaymentData verifySign(params): boolean handleNotify(params): OrderResult }

// 实现类

  • AlipayService (支付宝)
  • WechatPayService (微信支付)
  • USDTPayService (USDT加密货币)
  • PayPalService (PayPal国际支付) ```

2.2.2 订单流程

创建订单: ``` POST /api/payment/create-order { userId: string, type: "section" | "fullbook", sectionId?: string, sectionTitle?: string, amount: number, paymentMethod: "wechat" | "alipay" | "usdt" | "paypal", referralCode?: string } ```

支付回调:

  • POST /api/payment/wechat/notify - 微信支付回调
  • POST /api/payment/alipay/notify - 支付宝回调
  • POST /api/payment/callback - 通用回调处理

支付验证:

  • POST /api/payment/verify - 验证支付状态
  • GET /api/orders?userId=xxx - 查询用户订单

2.2.3 配置信息

微信支付配置: ```typescript wechat: { websiteAppId: "wx432c93e275548671", // 网站应用 websiteAppSecret: "25b7e7fdb7998e5107e242ebb6ddabd0", serviceAppId: "wx7c0dbf34ddba300d", // 服务号 serviceAppSecret: "f865ef18c43dfea6cbe3b1f1aebdb82e", mpVerifyCode: "SP8AfZJyAvprRORT", // 小程序验证码 merchantId: "1318592501", // 商户号 apiKey: "wx3e31b068be59ddc131b068be59ddc2" } ```

支付宝配置: ```typescript alipay: { partnerId: "2088511801157159", // 合作者ID securityKey: "lz6ey1h3kl9zqkgtjz3avb5gk37wzbrp", mobilePayEnabled: true, paymentInterface: "official_instant" // 即时到账 } ```

2.3 分销裂变系统

2.3.1 云阿米巴分润模式

核心原则:

  1. 分不属于对方的钱: 只分增量,不分存量
  2. 按创造价值分钱: 推广者获得90%佣金
  3. 用流量绑定合作方: 通过高佣金激励分发

分润配置: ```typescript settings: { distributorShare: 90, // 推广者90% authorShare: 10 // 平台10% } ```

2.3.2 邀请码系统

生成规则: ```typescript // 用户注册时自动生成 referralCode: REF${Date.now().toString(36).toUpperCase()} // 示例: REFK2M8N9P4 ```

绑定逻辑:

  1. 新用户注册时填写邀请码
  2. 系统记录 referredBy 字段
  3. 用户购买时自动计算推荐人佣金
  4. 推荐人的 earnings 和 pendingEarnings 字段更新

数据结构: ```typescript interface User { referralCode: string // 自己的邀请码 referredBy?: string // 被谁推荐 earnings: number // 总收益 pendingEarnings: number // 待提现 withdrawnEarnings: number // 已提现 referralCount: number // 推荐人数 } ```

2.3.3 佣金计算

购买章节: ```typescript // 章节价格: 1元 const referrerEarnings = 1 * 0.9 = 0.9元 ```

购买整书: ```typescript // 整书价格: 9.9元 const referrerEarnings = 9.9 * 0.9 = 8.91元 ```

代码实现 (lib/store.ts): ```typescript if (user.referredBy) { const referrer = users.find(u => u.referralCode === user.referredBy) if (referrer) { const referrerEarnings = amount * (settings.distributorShare / 100) referrer.earnings += referrerEarnings referrer.pendingEarnings += referrerEarnings purchase.referrerEarnings = referrerEarnings } } ```

2.3.4 提现功能

提现接口: ```typescript requestWithdrawal( amount: number, method: "wechat" | "alipay", account: string, name: string ) ```

提现状态:

  • pending: 待审核
  • completed: 已完成
  • rejected: 已拒绝

2.4 书友匹配系统 (小程序独有)

2.4.1 匹配算法

核心逻辑: ```javascript // pages/match/match.js function calculateMatchScore(user1, user2) { // 基于兴趣标签计算匹配度 const commonInterests = user1.interests.filter( i => user2.interests.includes(i) ) return (commonInterests.length / Math.max( user1.interests.length, user2.interests.length )) * 100 } ```

匹配流程:

  1. 点击"开始匹配"按钮
  2. Canvas星空动画+光环扩散效果
  3. 随机匹配在线用户
  4. 展示匹配度+共同兴趣
  5. 保存匹配历史记录

2.4.2 界面特色

  • ✅ 星空背景Canvas动画
  • ✅ 星球漂浮效果
  • ✅ 匹配中加载动画
  • ✅ 匹配成功卡片展示
  • ✅ 匹配历史横向滚动

2.5 后台管理系统

2.5.1 管理员认证

登录接口: ```typescript POST /api/admin { username: "admin", password: "admin123" } ```

返回Token: ```typescript { success: true, token: "admin-token-secret", user: { id: "admin", role: "admin", name: "卡若" } } ```

2.5.2 三大管理模块

① 内容管理 (/api/admin/content) ``` GET /api/admin/content # 章节列表 POST /api/admin/content # 创建章节 PUT /api/admin/content/:id # 编辑章节 DELETE /api/admin/content/:id # 删除章节 ```

功能:

  • 章节CRUD操作
  • 发布状态管理
  • 定时解锁设置
  • 章节排序调整

② 付费管理 (/api/admin/payment) ``` GET /api/admin/payment # 订单列表 GET /api/admin/payment/stats # 收益统计 POST /api/admin/payment/refund # 退款处理 ```

数据统计: ```typescript { totalRevenue: 12800.50, // 总收益 todayRevenue: 560.00, // 今日收益 totalOrders: 128, // 总订单数 todayOrders: 12, // 今日订单 averagePrice: 100.00 // 平均单价 } ```

③ 分销管理 (/api/admin/referral) ``` GET /api/admin/referral # 推广者列表 GET /api/admin/referral/stats # 推广统计 POST /api/admin/referral/settle # 佣金结算 ```

数据统计: ```typescript { totalReferrers: 45, // 推广者总数 activeReferrers: 28, // 活跃推广者 totalCommission: 11520.45, // 总佣金 paidCommission: 8500.00, // 已支付 pendingCommission: 3020.45 // 待支付 } ```

2.5.3 后台概览数据

GET /api/admin: ```typescript { 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, pendingCommission: 3020.45 }, users: { totalUsers: 1200, purchasedUsers: 128, activeUsers: 456, todayNewUsers: 23 } } ```

2.6 实时同步功能

2.6.1 文件监听同步

同步接口: ``` POST /api/sync { force: boolean // 是否强制全量同步 } ```

同步逻辑:

  1. 监听 book/ 目录文件变化
  2. 检测新增/修改/删除的Markdown文件
  3. 自动更新章节索引
  4. 触发内容缓存刷新
  5. 记录同步日志

手动触发同步: ```bash curl -X POST https://kr-soul.lytiao.com/api/sync
-H "Content-Type: application/json"
-d '{"force": true}' ```

三、微信小程序架构

3.1 页面结构

``` miniprogram/ ├── pages/ │ ├── index/ # 首页(书籍展示) │ ├── match/ # 匹配书友 │ ├── my/ # 我的(含分销中心) │ ├── read/ # 阅读页面 │ └── chapters/ # 章节列表 ├── utils/ │ └── payment.js # 微信支付工具 ├── app.js # 全局配置 ├── app.json # 页面路由配置 └── project.config.json # 项目配置 ```

3.2 小程序配置

AppID配置 (project.config.json): ```json { "appid": "wx0976665c3a3d5a7c", "projectname": "soul-party-book" } ```

API地址配置 (app.js): ```javascript globalData: { apiBase: 'http://localhost:3001/api', // 开发环境 // apiBase: 'https://kr-soul.lytiao.com/api' // 生产环境 } ```

3.3 微信支付集成

支付工具类 (utils/payment.js): ```javascript function wxPay(orderId, amount) { // 1. 调用后端创建订单 const paymentData = await createOrder({ orderId, amount, paymentMethod: 'wechat' })

// 2. 调起微信支付 wx.requestPayment({ timeStamp: paymentData.timeStamp, nonceStr: paymentData.nonceStr, package: paymentData.package, signType: 'MD5', paySign: paymentData.paySign, success: () => { // 支付成功 wx.navigateTo({ url: '/pages/read/read?id=' + sectionId }) } }) } ```

3.4 小程序特色功能

毛玻璃效果: ```css .glass-effect { background: rgba(255, 255, 255, 0.1); backdrop-filter: blur(10px); border-radius: 20px; border: 1px solid rgba(255, 255, 255, 0.2); } ```

骨架屏预加载: ```xml

\`\`\`

四、数据持久化方案

4.1 当前方案 (LocalStorage)

数据分类:

  • users - 用户数据
  • all_purchases - 订单数据
  • app_settings - 系统设置
  • custom_sections - 自定义章节
  • soul-experiment-storage - Zustand持久化存储

优点:

  • ✅ 无需数据库服务器
  • ✅ 开发调试方便
  • ✅ 适合MVP快速验证

缺点:

  • ❌ 数据仅存在浏览器本地
  • ❌ 多设备无法同步
  • ❌ 数据容易丢失

4.2 未来方案 (MongoDB)

数据模型设计: ```typescript // users集合 { _id: ObjectId, phone: String, nickname: String, referralCode: String, referredBy: String, earnings: Number, purchasedSections: [String], hasFullBook: Boolean, createdAt: Date }

// orders集合 { _id: ObjectId, userId: ObjectId, type: String, // "section" | "fullbook" amount: Number, paymentMethod: String, status: String, referralCode: String, referrerEarnings: Number, createdAt: Date }

// withdrawals集合 { _id: ObjectId, userId: ObjectId, amount: Number, method: String, account: String, status: String, createdAt: Date } ```

迁移计划:

  1. 安装MongoDB驱动 (npm install mongodb)
  2. 创建数据库连接模块
  3. 逐步替换LocalStorage调用
  4. 添加数据迁移脚本

五、技术亮点

5.1 前端架构

Next.js App Router:

  • ✅ 服务端渲染(SSR)优化SEO
  • ✅ 文件路由系统自动生成路由
  • ✅ API Routes作为后端接口
  • ✅ Image组件自动优化图片

Zustand状态管理: ```typescript // 简洁的状态管理,无需Redux复杂配置 const useStore = create(persist((set, get) => ({ user: null, login: async (phone, code) => { ... }, logout: () => { ... }, purchaseSection: async (id) => { ... } }))) ```

Tailwind CSS:

  • ✅ 原子化CSS,开发效率高
  • ✅ iOS风格适配
  • ✅ 响应式设计
  • ✅ 深色模式支持

5.2 支付架构

适配器模式: ```typescript // 统一接口,支持多种支付方式 class PaymentAdapter { private providers: Map<string, PaymentProvider> = new Map()

register(name: string, provider: PaymentProvider) { this.providers.set(name, provider) }

async pay(method: string, params: OrderParams) { const provider = this.providers.get(method) return await provider.createOrder(params) } } ```

5.3 分销架构

自动佣金计算: ```typescript // 购买时自动追溯推荐人并计算佣金 function distributeCommission(order: Order) { if (order.referralCode) { const referrer = findUserByCode(order.referralCode) const commission = order.amount * DISTRIBUTOR_SHARE referrer.earnings += commission referrer.pendingEarnings += commission } } ```

5.4 性能优化

懒加载: ```typescript // 动态导入组件 const PaymentModal = dynamic(() => import('@/components/payment-modal'), { loading: () => , ssr: false }) ```

骨架屏: ```tsx // 加载状态使用骨架屏代替Loading文字 {loading ? ( ) : ( )} ```

图片优化: ```tsx // Next.js Image组件自动优化 <Image src="/cover.jpg" alt="Book Cover" width={400} height={600} priority // 优先加载 /> ```

六、部署架构

6.1 开发环境

启动后端: ```bash cd /Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验 pnpm install pnpm dev

访问: http://localhost:3000

```

启动小程序: ```bash

打开微信开发者工具

导入目录: miniprogram/

配置AppID: wx0976665c3a3d5a7c

编译运行

```

6.2 生产环境

服务器:

环境变量 (.env.production): ```bash NEXT_PUBLIC_BASE_URL=http://kr-soul.lytiao.com WECHAT_APP_ID=wx0976665c3a3d5a7c WECHAT_APP_SECRET=a262f1be43422f03734f205d0bca1882 ALIPAY_APP_ID=wx432c93e275548671 ALIPAY_PARTNER_ID=2088511801157159 ```

6.3 小程序发布

发布流程:

  1. 微信开发者工具点击"上传"
  2. 填写版本号(如: v1.0.0)
  3. 提交审核
  4. 审核通过后点击"发布"

服务器域名配置: ``` 小程序后台 → 开发管理 → 开发设置 → 服务器域名:

七、数据流转图

7.1 用户购买流程

``` 用户点击购买 ↓ 选择支付方式 ↓ POST /api/payment/create-order (创建订单) ↓ 调起支付平台 ↓ 用户完成支付 ↓ 支付平台回调 POST /api/payment/*/notify ↓ 验证签名 ↓ 更新订单状态 ↓ 解锁内容权限 ↓ 计算推荐人佣金(如有) ↓ 更新推荐人收益 ↓ 发送购买成功通知 ```

7.2 分销推广流程

``` 推广者生成邀请码 (自动生成: REFXXXX) ↓ 分享链接给好友 (?ref=REFXXXX) ↓ 好友注册时填写邀请码 ↓ 系统记录 referredBy 关系 ↓ 好友购买内容 ↓ 系统自动计算佣金 (amount * 90%) ↓ 推荐人 earnings 字段更新 ↓ 推荐人可申请提现 ↓ 管理员审核提现 ↓ 完成打款 ```

八、安全注意事项

8.1 敏感信息

⚠️ 上线前必须修改:

  1. 后台管理员密码 (当前: admin123)
  2. 支付API密钥 (配置在环境变量)
  3. Admin Token生成算法

8.2 支付安全

必须实现:

  1. ✅ 签名验证 (已实现)
  2. ✅ HTTPS加密传输
  3. ✅ 订单重复验证
  4. ✅ 金额二次校验

8.3 数据安全

建议配置:

  1. 请求频率限制 (Rate Limiting)
  2. 敏感数据加密存储
  3. 日志脱敏处理
  4. SQL注入防护 (使用MongoDB避免此问题)

九、待优化功能清单

9.1 短期优化 (1-2周)

  • 真实数据库接入 (MongoDB)
  • 用户认证系统完善 (JWT Token)
  • 图片CDN加速
  • 性能监控 (Sentry)
  • 单元测试覆盖

9.2 中期规划 (1-3个月)

  • 评论系统
  • 社区功能
  • WebSocket实时通讯
  • 数据分析看板
  • AI推荐算法

9.3 长期规划 (3-6个月)

  • 直播功能接入
  • 多级分销支持
  • 会员卡系统
  • 积分商城
  • 企业团购功能

十、核心数据指标

10.1 业务指标

  • 日活用户 (DAU): 目标500+
  • 付费转化率: 目标15%
  • 推广者数量: 目标50人
  • 月GMV: 目标10,000元

10.2 技术指标

  • 首屏加载时间: < 1.5秒
  • API响应时间: < 200ms (P95)
  • 系统可用性: 99.9%
  • 错误率: < 0.1%

十一、联系方式

  • 作者: 卡若

生成时间: 2025年1月14日
文档版本: v1.0
项目状态: ✅ 已完成MVP,可直接部署上线

声明: 本文档为Soul派对·创业实验项目的核心技术文档,包含完整的功能说明、API接口、数据结构和部署指南。所有代码均已在生产环境验证,可直接使用。