- 新增商业化模块：Stripe/Binance Pay 支付、邮箱登录、订单管理 - 新增数据模型：ReportProduct, ReportEntitlement, ReportSnapshot, PaymentEvent, EmailLoginCode - 新增 API：/api/commerce/checkout, /api/commerce/webhooks/*, /api/commerce/orders/* - 新增管理后台：订单列表、统计图表、统一 AdminHeader 组件 - 新增中间件测试：RateLimit, Auth, CORS 共 7 个测试用例 - 新增 AGENTS.md 项目代理指令文件 - 新增 REMINDER.md 商业化功能开发规范 - 修复 JWT 解析：添加 WithValidMethods 限制 HS256 - 修复 GetPayStatus：增加用户权限校验 - 更新 .gitignore 和 README.md
This commit is contained in:
gouki
@@ -0,0 +1,164 @@
|
||||
# 商业版 Web 功能说明
|
||||
|
||||
## 1. 产品目标
|
||||
|
||||
本项目是八字排盘的独立商业化 Web。免费层完整展示排盘事实，付费层提供六章深度解读。支付、用户、订单、报告快照与恢复码由 Go 服务端管理，不依赖浏览器伪造支付状态。
|
||||
|
||||
## 2. 完整业务流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[填写出生日期、时间、性别、城市] --> B[本地计算真太阳时与八字]
|
||||
B --> C[免费查看四柱、五行、大运、流年、刑冲合害、神煞]
|
||||
C --> D{是否解锁深度解读}
|
||||
D -- 否 --> E[继续查看免费排盘]
|
||||
D -- 是 --> F[Postmark 邮箱验证码登录]
|
||||
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. 报告恢复码
|
||||
|
||||
支付成功后，服务端使用加密安全随机数生成恢复码，例如：
|
||||
|
||||
```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`：一次性验证码。
|
||||
- `orders` 新增渠道、币种、服务商交易号、报告号、恢复码等字段。
|
||||
|
||||
新部署可使用 GORM AutoMigrate；已有 MySQL 数据库应在备份后执行 `server/migrations/002_commerce.sql`，不要 fresh 或 refresh 数据库。
|
||||
|
||||
## 10. 上线前仍需完成
|
||||
|
||||
- 完成香港公司 Stripe 账户审核。
|
||||
- 完成 Binance Entity/KYB 与 Binance Pay 商户审核，并确认命理数字内容属于可接受商户类别。
|
||||
- 在 Stripe 与 Binance Pay 沙箱/测试环境上传真实密钥并跑通一笔完整支付和退款。
|
||||
- 配置正式 HTTPS Webhook 地址。
|
||||
- 补充隐私政策、用户协议、退款规则、公司与客服信息。
|
||||
- 根据香港当地要求确认虚拟资产收款、税务和消费者保护义务。
|
||||
Reference in New Issue
Block a user