lunar-mini/server

知命 / 祈福后端服务

基于 Go、Gin、GORM 的后端仓库，包含两个部署入口：

• cmd/mini：小程序接口（lunar.neatcn.com）——微信登录、生辰档案、许愿树、百科。
• cmd/web：商业版 Web（kepo.net）——邮箱验证码登录、Stripe / Binance Pay、订单权益、报告快照、管理后台与商业前端静态站点。

两侧共用 internal/ 下的配置、数据库、模型与中间件，但路由互不暴露。

功能模块

• 微信小程序登录与生辰档案。
• QQ 邮箱 SMTP 验证码登录，支持 465 隐式 TLS 或 587 STARTTLS；Postmark 可选备用。
• Stripe 4.99 USD 报告支付。
• Binance Pay 5 USDT 报告支付。
• 签名 Webhook、幂等事件、退款权益撤销。
• 随机报告恢复码与不可变报告快照。
• 用户订单与报告权益查询。
• 数据库驱动的 PC 商业版订单列表和收入统计。
• PC 商业版后台只查询 type=bazi_report，与小程序许愿等旧业务订单逻辑隔离。
• 许愿树与百科数据。

快速开始

cp .env.example .env.local
go mod download
go run ./cmd/mini   # 小程序接口
go run ./cmd/web    # 商业版 Web（本地需 ../web-commercial/dist 与 ./web 静态资源）

默认地址：http://localhost:8080。

生产部署：

• 小程序接口（doc79）：CI 构建 server-v* Release，服务器 watcher 自动拉取，Docker 容器运行。见 .gitea/docs/PULL_DEPLOY.md。
• 商业版 Web（kepo.net）：CI 构建 web-v* Release（含 cmd/web 二进制 + frontend/ 商业前端 + web/ 后台静态资源），systemd 运行。一次性配置见 .gitea/docs/PULL_DEPLOY_WEB.md。

商业前端静态文件放在服务目录的 frontend/，根路径 / 为商业站点，/admin/orders 为管理后台，/api/* 为后端接口。

测试

项目包含 HTTP API 测试，覆盖未认证拦截、Webhook 拒绝、Stripe 模拟下单、签名回调、权益发放、恢复码和快照读取。

go test ./...

本地测试配置使用 server/.env.test。如果文件包含 SMTP 凭证，必须保持 Git 忽略并限制文件权限，绝不提交到仓库。真实发信测试需显式运行 RUN_QQ_SMTP_LIVE_TEST=1 SMTP_TEST_TO=收件地址 go test ./internal/handler -run '^TestRequestEmailLoginCodeLiveQQSMTP$' -count=1；该命令会实际发送邮件。

商业支付 API

邮箱登录

• POST /api/auth/email/request
• POST /api/auth/email/verify

支付与报告

• 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/commerce/charts — 用户主动同意后保存免费排盘记录；接口限流并记录同意版本与时间。

除 Webhook 和需同意的公开排盘记录接口外，商业接口都要求 Authorization: Bearer <JWT>。

免费排盘默认不上传。创建付费订单时，报告快照会发送并保存在服务端，用于生成、交付和恢复已购报告。

管理后台

• /admin/orders — 真实订单列表。
• /admin/api/orders — 按渠道、状态、订单号、邮箱、报告号查询。
• /admin/api/orders/stats — 订单和收入统计。

后台使用 ADMIN_PASSWORD 登录并写入 HttpOnly Cookie。

支付安全

• 金额只从 report_products 读取。
• Stripe 使用 Checkout Session 和 Idempotency-Key。
• Stripe Webhook 校验 HMAC 签名与 5 分钟时间窗口。
• Binance Pay 下单使用 HMAC-SHA512。
• Binance Pay Webhook 使用商户证书 RSA 公钥验签。
• Webhook 同时校验服务商订单号、金额与币种。
• payment_events 唯一索引保证重复回调不会重复发放权益。
• 支付、事件、恢复码和权益在数据库事务中完成。
• 退款后报告权益自动撤销。

数据库

新安装由 GORM AutoMigrate 创建表。商业排盘记录新增同意版本和时间字段，服务启动时通过 AutoMigrate 增量添加；已有 MySQL 数据库应先备份再升级，不要执行数据库 fresh 或 refresh。商业表结构初始化脚本仍为：

mysql < migrations/002_commerce.sql

环境变量

完整模板见 .env.example。邮箱登录配置 QQ SMTP：

• SMTP_HOST=smtp.qq.com
• SMTP_PORT=465（或 587）
• SMTP_USERNAME：完整 QQ 邮箱地址
• SMTP_PASSWORD：QQ 邮箱生成的 SMTP 授权码，不是邮箱登录密码
• SMTP_FROM_EMAIL：发件地址。生产使用 z@kepo.net（kepo.net 已通过 QQ 域名邮箱绑定，MX 为 mxdomain.qq.com）；需在 DNS 添加 SPF 记录 v=spf1 include:spf.mail.qq.com ~all，否则 Gmail 等可能拒收或判为垃圾邮件
• SMTP_TLS_MODE=implicit（465）或 starttls（587）
• SMTP_TLS_CA_FILE：可选的自定义 CA 文件路径

QQ 邮箱需先在账户设置中开启 SMTP 服务。SMTP 配置有效时优先使用 SMTP；未配置时才尝试 Postmark。生产环境还需要：

• JWT_SECRET
• ADMIN_PASSWORD
• PUBLIC_BASE_URL
• WEB_APP_URL
• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET
• BINANCE_PAY_API_KEY
• BINANCE_PAY_SECRET_KEY
• BINANCE_PAY_WEBHOOK_PUBLIC_KEY

所有支付与邮件密钥必须通过部署环境注入，禁止提交到 Git。