# 商业版 Web 功能说明

## 1. 产品目标

本项目是八字排盘的独立商业化 Web。免费层完整展示排盘事实，付费层提供六章深度解读。支付、用户、订单、报告快照与恢复码由 Go 服务端管理，不依赖浏览器伪造支付状态。

## 2. 完整业务流程

```mermaid
flowchart TD
    A[填写出生日期、时间、性别、城市] --> B[在当前设备计算真太阳时与八字]
    B --> C[免费查看四柱、五行、大运、流年、刑冲合害、神煞]
    C --> D{是否同意保存本次排盘记录}
    D -- 是 --> E[服务端保存所列资料与排盘快照]
    D -- 否 --> F[只在当前页面查看，不上传免费排盘记录]
    C --> G{是否解锁深度解读}
    G -- 否 --> H[继续查看免费排盘]
    G -- 是 --> I[邮箱验证码登录并确认下单数据保存说明]
    I --> J{选择支付渠道}
    J --> K[Stripe: 4.99 USD]
    J --> L[Binance Pay: 5 USDT]
    K --> M[服务商签名 Webhook]
    L --> M
    M --> N[事务更新订单和报告权益]
    N --> O[生成随机报告恢复码]
    O --> P[保存不可变报告快照]
    P --> Q[用户凭购买邮箱和恢复码跨设备找回]
```

## 3. 免费排盘内容

八字运算在当前设备完成。用户默认不上传免费排盘资料；只有主动勾选保存选项后，姓名（如填写）、出生日期、出生时间、性别、城市和排盘快照才会发送到服务端，供授权后台人员查看。未勾选仍可免费计算，但服务端不会创建免费排盘记录。服务端验证同意版本并对公开保存接口限流。相同输入在同一算法版本下应得到相同结果；算法升级后保留已保存快照，不覆盖历史记录。

购买时会另行告知：创建订单会把报告快照和订单所需信息发送到服务端，用于生成、交付和恢复已购报告；该购买记录不依赖免费排盘保存选项。

免费层展示基础事实，不把基础数据故意藏到付费层：

- 出生城市经度与真太阳时校正。
- 年柱、月柱、日柱、时柱。
- 十神、藏干、纳音、十二长生、命宫、身宫、胎元、空亡。
- 五行力量统计。
- 起运年龄、顺逆行与交运日期。
- 十步大运时间轴。
- 十年流年/小运信息。
- 天干五合与天干相冲。
- 地支六合、三合局成员、六冲、六害与相刑。
- 22 个常见神煞，包括天乙贵人、天厨贵人、文昌贵人、禄神、羊刃、桃花、驿马、华盖、红鸾、天喜等；展示命中位置和基础说明。

刑冲合害和神煞属于基础排盘事实，免费展示；付费层提供结合命局的个性化解释、优先级和行动建议。

神煞流派版本较多，只作为辅助信息，不单独用于判断吉凶。

## 4. 付费报告

- Stripe 价格：`4.99 USD`。
- Binance Pay 价格：`5 USDT`。
- 单次购买，无订阅和自动续费。
- 六章内容：性格、事业、财富、关系、身心、大运路线。

支付成功必须经过服务商签名 Webhook。浏览器跳转页不能直接授予权益。

付费内容安全边界：支付前浏览器只接收免费排盘数据和通用锁定占位，不接收个性化六章解读；服务端确认支付后，才根据订单快照生成并保存付费报告。客户端不能通过修改遮罩、localStorage 或请求参数提前获得付费内容。

## 5. 报告恢复码

支付成功后，服务端使用加密安全随机数生成恢复码，例如：

```text
ZM-ABCD-EFGH-JKLM
```

恢复规则：

1. 必须先验证购买时的邮箱。
2. 恢复码必须属于当前邮箱账户。
3. 订单必须是已支付状态。
4. 报告权益必须仍然有效。
5. 返回购买时保存的报告快照，不重新套用可能已经变化的新算法。
6. 退款后权益会被撤销。

## 6. 支付与登录接口

### 邮箱登录

- `POST /api/auth/email/request`：通过 Postmark 发送 6 位验证码。
- `POST /api/auth/email/verify`：验证验证码并签发用户 JWT。
- 验证码 10 分钟有效、最多尝试 5 次、60 秒内不能重复发送。

### 创建支付

```http
POST /api/commerce/checkout
Authorization: Bearer <user-token>
Content-Type: application/json

{
  "provider": "stripe",
  "reportId": "ZM-0VB51FN",
  "snapshot": {
    "id": "ZM-0VB51FN",
    "result": {},
    "elements": {},
    "shensha": [],
    "sections": []
  }
}
```

服务端从商品表读取金额，客户端不能修改定价。

### Webhook

- `POST /api/commerce/webhooks/stripe`
- `POST /api/commerce/webhooks/binance-pay`

Stripe 校验 `Stripe-Signature` 与 5 分钟时间窗口；Binance Pay 使用商户证书公钥验证 RSA 签名。事件 ID 唯一保存，重复通知不会重复授予权益。

### 查询与恢复

- `GET /api/commerce/orders/:orderNo`：查询本人订单和恢复码。
- `GET /api/commerce/reports/:reportId/access`：查询本人报告权益。
- `GET /api/commerce/reports`：列出本人已购报告。
- `GET /api/commerce/reports/recover/:accessCode`：通过恢复码读取购买时快照。

## 7. 后台订单管理

访问 `/admin/orders`，可查看：

- 报告订单总数、已支付、待支付、已退款。
- Stripe 美元收入。
- 用户邮箱、报告编号、恢复码关联订单。
- Stripe 或 Binance Pay 渠道。
- 服务商订单号与交易号。
- 创建时间和支付时间。
- 按状态、渠道、订单号、邮箱、报告号筛选。

## 8. 配置

前端复制 `.env.example` 为 `.env.local`。只有明确设置 `VITE_PAYMENT_MODE=demo` 才进入演示支付；未设置时默认使用生产支付，避免线上误开模拟解锁。

后端配置见 `server/.env.example`，必须准备：

- Postmark Server Token 与已验证发件域名。
- Stripe Secret Key 与 Webhook Secret。
- Binance Pay 商户 API Key、Secret Key 与 Webhook 公钥。
- 公开 HTTPS API 域名和 Web 地址。
- 强随机 JWT 密钥和后台密码。

## 9. 数据库

新增：

- `report_products`：服务端价格。
- `report_entitlements`：付费权益。
- `report_snapshots`：购买时不可变报告快照。
- `payment_events`：Webhook 幂等记录。
- `email_login_codes`：一次性验证码。
- `bazi_chart_records`：排盘记录增加同意版本与同意时间字段；旧记录不回填为已同意。
- `orders` 新增渠道、币种、服务商交易号、报告号、恢复码等字段。

新部署可使用 GORM AutoMigrate；已有 MySQL 数据库应在备份后执行 `server/migrations/002_commerce.sql`，不要 fresh 或 refresh 数据库。

## 10. 上线前仍需完成

- 完成香港公司 Stripe 账户审核。
- 完成 Binance Entity/KYB 与 Binance Pay 商户审核，并确认命理数字内容属于可接受商户类别。
- 在 Stripe 与 Binance Pay 沙箱/测试环境上传真实密钥并跑通一笔完整支付和退款。
- 配置正式 HTTPS Webhook 地址。
- 补充隐私政策、用户协议、退款规则、公司与客服信息。
- 根据香港当地要求确认虚拟资产收款、税务和消费者保护义务。