soul-yongping/开发文档/4、前端/ui/05-状态管理说明.md

状态管理说明

Zustand Store 结构

文件位置：lib/store.ts

核心数据类型

User 用户

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 购买记录

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 提现记录

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 系统设置

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

用户相关

login(phone: string, code: string): Promise<boolean>
logout(): void
register(phone: string, nickname: string, referralCode?: string): Promise<boolean>
updateUser(userId: string, updates: Partial<User>): void

购买相关

purchaseSection(sectionId: string, sectionTitle?: string, paymentMethod?: string): Promise<boolean>
purchaseFullBook(paymentMethod?: string): Promise<boolean>
hasPurchased(sectionId: string): boolean

提现相关

requestWithdrawal(amount: number, method: string, account: string, name: string): void
processWithdrawal(withdrawalId: string, approved: boolean): void

数据查询

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