Points Pay — 内部积分支付系统

基于内部积分体系的轻量级支付收银台系统，为业务方提供积分支付创建、用户收银台确认、异步通知、退款、对账等完整支付能力。

需配合SSO使用

系统定位

不同于微信/支付宝/Stripe 等第三方支付网关，Points Pay 基于平台自有积分体系，实现即时账本划转、异步通知业务方、完整审计追溯。

维度	第三方支付	Points Pay
结算周期	T+1 银行清算	即时账本划转
手续费	0.6%~2%	无
支付方式	钱包/银行卡	平台积分
回退	180 天拒付期	内部退款
对账	银行 T+1 文件	实时账本 vs 订单

核心设计原则：积分余额来源于账本，绝不直接修改。 所有积分变动都是 points_ledger 表中追加的行记录。

技术栈

层	技术	说明
后端	Go 1.22+ / Gin	高并发、编译型单体部署
数据库	PostgreSQL 14+	ACID 事务、行级锁、JSONB
缓存/队列	Redis 6+	幂等性 TTL、限流、通知队列
前端	React 18 + TypeScript + Vite	收银台 SPA
ORM	sqlx	结构化扫描的原始 SQL

快速开始

环境要求

• Go 1.22+
• PostgreSQL 14+
• Redis 6+
• Node.js 18+ (前端开发)

1. 克隆项目

git clone <repo-url>
cd pay

2. 配置环境变量

cp .env.example .env
# 编辑 .env，填入数据库和 Redis 连接信息

关键环境变量：

变量	说明	默认值
SERVER_PORT	服务端口	8080
DB_HOST	数据库地址	localhost
DB_PORT	数据库端口	5432
DB_USER	数据库用户	postgres
DB_PASSWORD	数据库密码	—
DB_NAME	数据库名	points_pay
REDIS_ADDR	Redis 地址	localhost:6379
JWT_SECRET	管理员 JWT 密钥	生产环境务必更换
CHECKOUT_SECRET	收银台 Token 密钥	生产环境务必更换
CHECKOUT_BASE_URL	收银台页面地址	http://localhost:5173
ORDER_EXPIRE_MINS	订单过期时间(分钟)	15

3. 初始化数据库

psql -h $DB_HOST -U $DB_USER -d $DB_NAME -f migrations/000001_init.sql

4. 启动后端

go run cmd/server/main.go

5. 启动前端（开发）

cd web
npm install
npm run dev

前端开发服务器运行在 http://localhost:5173，自动代理 API 请求到后端 :8080。

6. 健康检查

curl http://localhost:8080/health
# {"status":"ok","service":"points-pay"}

项目结构

├── cmd/server/main.go              # 入口
├── migrations/000001_init.sql      # 完整 DDL
├── internal/
│   ├── config/                     # 配置
│   ├── model/                      # 数据模型、常量、错误码
│   ├── security/                   # JWT、HMAC 签名
│   ├── middleware/                  # 认证、日志
│   ├── store/postgres/             # 数据访问层
│   └── service/                    # 业务逻辑层
├── web/                            # React 收银台
└── docs/                           # 文档
    ├── api.md                      # API 文档
    └── integration.md              # 接入文档

核心概念

支付模式

direct（直接扣减）：用户确认后立即扣减积分。适用于会员、虚拟商品等即时交付场景。

auth_capture（冻结+捕获）：先冻结积分，商户确认后正式扣减，或取消后解冻。适用于预订、押金、服务后确认等场景。

订单状态机

pending → paid → partial_refunded → refunded
pending → expired
pending → cancelled
pending → authorized → paid
pending → authorized → cancelled

账本原则

• 账本表 points_ledger 只追加（INSERT），不更新，不删除
• points_accounts.balance 是账本的缓存快照，用于快速读取
• 对账作业每日校验 balance = SUM(ledger.amount)

安全

• 商户 API：HMAC-SHA256 签名（X-Signature）+ 时间戳防重放 + Nonce（Redis）
• 收银台：JWT（15 分钟）+ Nonce 防重放 + CSRF Token
• 管理端：JWT（30 分钟）+ bcrypt + RBAC（超级管理员/操作员/查看者）
• 通知：HMAC-SHA256 签名，商户自行验签
• Web：CSP 头、X-Frame-Options: DENY、SameSite=Strict Cookie

License

Internal use.