feat(server): 商业化支付与订单系统 + Harness 改进

- 新增商业化模块：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
2026-09-19 18:57:23 +00:00
parent 241a04496b
commit deb32f8fab
52 changed files with 5419 additions and 339 deletions
@@ -1,114 +1,105 @@
-# 祈福小助手后端服务
+# 知命 / 祈福后端服务

-基于 Go + Gin + Inertia.js 的后端服务。
+基于 Go、Gin、GORM 的统一后端，提供微信小程序能力、商业版八字报告、邮箱登录、支付、订单权益和管理后台。

 ## 功能模块

- **用户模块** — 微信登录、资料修改、授权管理
- **支付模块** — 微信支付集成、订单管理
- **许愿树** — 许愿发布、付费许愿、机器人自动许愿
- **百科/历史上的今天** — 百科条目后台维护；从中文维基百科同步 366 天「历史上的今天」数据，定时刷新
- **管理后台** — 基于 Inertia.js 的前后端分离管理界面
-
-## 技术栈
-
- **后端**: Go 1.22 + Gin + GORM
- **前端**: Inertia.js + React/Vue（待选择）
- **数据库**: MySQL
- **缓存**: Redis
+- 微信小程序登录与生辰档案。
+- Postmark 邮箱验证码登录。
+- Stripe `4.99 USD` 报告支付。
+- Binance Pay `5 USDT` 报告支付。
+- 签名 Webhook、幂等事件、退款权益撤销。
+- 随机报告恢复码与不可变报告快照。
+- 用户订单与报告权益查询。
+- 数据库驱动的 PC 商业版订单列表和收入统计。
+- PC 商业版后台只查询 `type=bazi_report`，与小程序许愿等旧业务订单逻辑隔离。
+- 许愿树与百科数据。

 ## 快速开始

-### 开发环境
-
 ```bash
-# 安装依赖
+cp .env.example .env.local
 go mod download
-
-# 启动开发服务器
-./scripts/dev.sh
+go run ./cmd
 ```

-### 生产构建
+默认地址：`http://localhost:8080`。
+
+生产部署可使用 systemd 直接运行二进制，商业前端静态文件放在服务目录的 `frontend/`，根路径 `/` 为商业站点，`/admin/orders` 为管理后台，`/api/*` 为后端接口。这样无需 Docker 或 Nginx，适合小内存服务器；Cloudflare 可在边缘终结 HTTPS 并回源到 80 端口。
+
+## 测试
+
+项目包含 HTTP API 测试，覆盖未认证拦截、Webhook 拒绝、Stripe 模拟下单、签名回调、权益发放、恢复码和快照读取。

 ```bash
-# 构建
-./scripts/build.sh
-
-# 运行
-./bin/lunar-server
+go test ./...
 ```

-## 项目结构
+测试环境文件为本地 `server/.env.test`，不提交任何真实密钥。

-```
-server/
-├── cmd/              # 入口文件
-│   └── main.go
-├── internal/         # 内部包
-│   ├── config/       # 配置
-│   ├── handler/      # 处理器
-│   ├── middleware/   # 中间件
-│   ├── model/        # 数据模型
-│   └── service/      # 业务逻辑
-├── web/              # Inertia.js 前端
-│   ├── src/
-│   └── public/
-├── migrations/       # 数据库迁移
-├── scripts/          # 脚本
-└── go.mod
-```
+## 商业支付 API

-## API 接口
+### 邮箱登录

-### 用户接口
+- `POST /api/auth/email/request`
+- `POST /api/auth/email/verify`

- `POST /api/user/login` — 用户登录
- `POST /api/user/logout` — 用户登出
- `GET /api/user/profile` — 获取用户资料
- `PUT /api/user/profile` — 更新用户资料
- `POST /api/user/auth` — 微信授权
+### 支付与报告

-### 支付接口
+- `POST /api/commerce/checkout` — 创建 Stripe 或 Binance Pay 订单。
+- `POST /api/commerce/webhooks/stripe` — Stripe 签名通知。
+- `POST /api/commerce/webhooks/binance-pay` — Binance Pay 签名通知。
+- `GET /api/commerce/orders/:orderNo` — 查询本人订单。
+- `GET /api/commerce/reports/:reportId/access` — 查询报告权益。
+- `GET /api/commerce/reports` — 本人已购报告。
+- `GET /api/commerce/reports/recover/:accessCode` — 使用恢复码读取购买时快照。

- `POST /api/pay/create` — 创建订单
- `POST /api/pay/notify` — 支付回调
- `GET /api/pay/status/:orderId` — 查询支付状态
+除 Webhook 外，商业接口都要求 `Authorization: Bearer <JWT>`。

-### 订单接口
+## 管理后台

- `GET /api/order/list` — 订单列表
- `GET /api/order/detail/:id` — 订单详情
- `POST /api/order/cancel/:id` — 取消订单
+- `/admin/orders` — 真实订单列表。
+- `/admin/api/orders` — 按渠道、状态、订单号、邮箱、报告号查询。
+- `/admin/api/orders/stats` — 订单和收入统计。

-### 许愿接口
+后台使用 `ADMIN_PASSWORD` 登录并写入 HttpOnly Cookie。

- `GET /api/wish/tree` — 获取许愿树
- `POST /api/wish/create` — 创建许愿
- `GET /api/wish/list` — 许愿列表
- `DELETE /api/wish/:id` — 删除许愿
+## 支付安全

-### 百科接口
-
- `GET /api/wiki/entries` — 百科条目列表（支持 category/keyword 过滤）
- `GET /api/wiki/on-this-day?month=&day=` — 历史上的今天（大事记/出生/逝世/节假日习俗）
-
-### 管理后台接口（/admin，需管理员认证）
-
- `GET/POST /admin/api/wiki/entries` — 百科条目列表/新增
- `PUT/DELETE /admin/api/wiki/entries/:id` — 更新/删除条目
- `GET /admin/api/wiki/sync-status` — 维基同步状态
- `POST /admin/api/wiki/sync` — 手动触发全量同步
-
-## 环境变量
-
-参考 `.env.local` 文件配置。维基同步相关：
-
- `WIKI_SYNC_INTERVAL_DAYS` — 自动同步间隔（天），默认 7
- `WIKI_SYNC_HOUR` — 自动同步执行的小时点（0-23），默认 4
-
-同步策略：服务启动时若数据缺失自动补齐；之后每天在指定小时点检查，距上次成功超过间隔天数才全量刷新（共 366 页，只抓中文版）。
+- 金额只从 `report_products` 读取。
+- Stripe 使用 Checkout Session 和 `Idempotency-Key`。
+- Stripe Webhook 校验 HMAC 签名与 5 分钟时间窗口。
+- Binance Pay 下单使用 HMAC-SHA512。
+- Binance Pay Webhook 使用商户证书 RSA 公钥验签。
+- Webhook 同时校验服务商订单号、金额与币种。
+- `payment_events` 唯一索引保证重复回调不会重复发放权益。
+- 支付、事件、恢复码和权益在数据库事务中完成。
+- 退款后报告权益自动撤销。

 ## 数据库

-执行 `migrations/001_init.sql` 初始化数据库。
+新安装由 GORM AutoMigrate 创建表。已有 MySQL 数据库先备份，再单独执行：
+
+```bash
+mysql < migrations/002_commerce.sql
+```
+
+不要执行数据库 fresh 或 refresh。
+
+## 环境变量
+
+完整模板见 `.env.example`。生产环境至少需要：
+
+- `JWT_SECRET`
+- `ADMIN_PASSWORD`
+- `PUBLIC_BASE_URL`
+- `WEB_APP_URL`
+- `POSTMARK_SERVER_TOKEN`
+- `POSTMARK_FROM_EMAIL`
+- `STRIPE_SECRET_KEY`
+- `STRIPE_WEBHOOK_SECRET`
+- `BINANCE_PAY_API_KEY`
+- `BINANCE_PAY_SECRET_KEY`
+- `BINANCE_PAY_WEBHOOK_PUBLIC_KEY`
+
+所有支付与邮件密钥必须通过部署环境注入，禁止提交到 Git。