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

# 状态管理说明

## 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<boolean>
logout(): void
register(phone: string, nickname: string, referralCode?: string): Promise<boolean>
updateUser(userId: string, updates: Partial<User>): void
```

### 购买相关
```typescript
purchaseSection(sectionId: string, sectionTitle?: string, paymentMethod?: string): Promise<boolean>
purchaseFullBook(paymentMethod?: string): Promise<boolean>
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*