lunar-mini/web-commercial/Fetures.md

商业版 Web 功能说明

1. 产品目标

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

2. 完整业务流程

flowchart TD
    A[填写出生日期、时间、性别、城市] --> B[本地计算真太阳时与八字]
    B --> C[免费查看四柱、五行、大运、流年、刑冲合害、神煞]
    C --> D{是否解锁深度解读}
    D -- 否 --> E[继续查看免费排盘]
    D -- 是 --> F[QQ 邮箱 SMTP 验证码登录]
    F --> G{选择支付渠道}
    G --> H[Stripe: 4.99 USD]
    G --> I[Binance Pay: 5 USDT]
    H --> J[服务商签名 Webhook]
    I --> J
    J --> K[事务更新订单和报告权益]
    K --> L[生成随机报告恢复码]
    L --> M[保存不可变报告快照]
    M --> N[用户凭购买邮箱和恢复码跨设备找回]

3. 免费排盘内容

每次排盘都会向服务端保存一份免费快照，记录出生参数、报告编号和计算结果版本，避免用户重复排盘后无法追踪历史。相同输入在同一算法版本下应得到相同结果；算法升级后保留旧快照，不覆盖历史记录。

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

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

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

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

4. 付费报告

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

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

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

5. 报告恢复码

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

ZM-ABCD-EFGH-JKLM

恢复规则：

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

6. 支付与登录接口

邮箱登录

• POST /api/auth/email/request：优先通过 QQ SMTP（TLS）发送 6 位验证码；未配置 SMTP 时可使用 Postmark 备用通道。
• POST /api/auth/email/verify：验证验证码并签发用户 JWT。
• 验证码 10 分钟有效、最多尝试 5 次、60 秒内不能重复发送。

创建支付

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，邮箱登录可配置：

• QQ SMTP 主机、端口、完整邮箱地址与 SMTP 授权码；授权码通过环境变量或本地忽略的密钥文件注入，不提交到 Git。
• 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：一次性验证码。
• orders 新增渠道、币种、服务商交易号、报告号、恢复码等字段。

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

10. 上线前仍需完成

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