# dongfeng-pay

**Repository Path**: dev_cpg/dongfeng-pay

## Basic Information

- **Project Name**: dongfeng-pay
- **Description**: go语言编写的支付系统
- **Primary Language**: Go
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dongfeng-pay

> 四方聚合支付系统重构：Go + Gin + PostgreSQL + Redis + Tyk + 微信支付 API v3 Go SDK

## 概述

本仓库源自 Gitee `dev_cpg/dongfeng-pay`（Go/Beego 聚合支付系统）。在 `refactor/go-gin-v2` 分支上完整重写为现代四方支付平台：

- **应用层**：电商商城、SaaS、APP、小程序、H5
- **支付网关层**：Tyk 5.3（统一入口、安全、限流、路由）
- **支付核心业务层**：Go 1.26 + Gin + PostgreSQL（订单/收银台/退款/通知/状态机）
- **渠道适配层**：统一 `Channel` interface，7 个微信支付真实 SDK 适配器 + 支付宝/银联 mock
- **外部支付机构**：微信支付 API v3、支付宝、银联、Stripe、PayPal

## 当前版本

**v0.3.0-real-idempotency** (2026-07-21)

- 后端：Go 1.26.4 + Gin + pgx + go-redis，编译通过，E2E 验证完成
- 支付/退款幂等：基于 `Idempotency-Key` Header + Redis SETNX 缓存（24h TTL）
- 退款业务防护：merchant_refund_no 幂等 + 日次数限制（默认 5/天）+ 支付后冷静期（60s）+ 累计金额上限
- 前端：Next.js 16 + React 19 + Tailwind（国际）；Vue 3 + uni-app（国内）
- 网关：Tyk 5.3.0-dev（gateway/bin/tyk，79 MB）
- 数据库：PostgreSQL 14 表已迁移到 `192.168.1.5:5432/dongfeng_pay`
- 微信支付 SDK：wechatpay-go v0.2.21（build tag `wechat_sdk`）

详细见 `docs/audit/V0.2.0-STATUS.md` 和 `v0.3.0-idempotency.md`（Obsidian）。

### 幂等 + 退款防护

所有支付/退款接口接受标准 `Idempotency-Key` Header，同 key 重复请求只执行一次并返回首次结果：

```bash
curl -X POST http://localhost:8081/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: 1" \
  -H "Idempotency-Key: my-unique-key-001" \
  -d '{"orderId":"P...","channel":"WECHAT_JSAPI","openId":"oUp"}'
```

退款防护规则（`internal/service/refund_guard.go`）：

| 防护 | 默认值 | 说明 |
|------|--------|------|
| 同 `merchant_refund_no` 去重 | 24h TTL | Redis SETNX 锁 |
| 单订单日退款次数 | 5 次/天 | Redis INCR + 26h EXPIRE |
| 支付后冷静期 | 60s | `time.Since(PaidAt)` 检查 |
| 累计金额上限 | = 订单金额 | 内存校验 |

E2E 验证：`bash tests/e2e_idempotency.sh` → **4 PASS, 0 FAIL**。

## 目录结构

```
dongfeng-pay/
├── backend/                   # Go + Gin 后端 (cmd + internal + pkg)
│   ├── cmd/{server,issuetoken,dbtest}/
│   ├── internal/{api,domain,repository/postgres,service,channel,auth,push}/
│   ├── pkg/{domain,errors,db,cache,config,logger,httpx}/
│   └── go.mod / go.sum
├── gateway/
│   ├── tyk/                   # Tyk 5.3 submodule
│   ├── tyk.conf
│   ├── apps/dongfeng-api.json
│   ├── middleware/region_resolver.js
│   └── templates/
├── web-intl/                   # 国际前端 (Next.js 16)
├── web-domestic/               # 国内前端 (Vue 3)
├── migrations/                 # PostgreSQL 迁移
├── scripts/{build-tyk,run-tyk}.sh
├── docs/{constraints,audit,api,design}/
├── docker-compose.yml
├── Makefile
└── CHANGELOG.md
```

## 快速开始

### 后端

```bash
cp backend/.env.example backend/.env
# 编辑 backend/.env：DATABASE_URL / REDIS_ADDR / JWT_SECRET

# 应用迁移
psql -h 192.168.1.5 -U postgres -d dongfeng_pay \
  -f migrations/000001_init_schema.up.sql
psql -h 192.168.1.5 -U postgres -d dongfeng_pay \
  -f migrations/000002_seed.up.sql

# 编译并启动
cd backend
CGO_ENABLED=0 go build -o ../bin/backend ./cmd/server
DATABASE_URL='postgres://postgres:123456@192.168.1.5:5432/dongfeng_pay?sslmode=disable' \
REDIS_ADDR=192.168.1.5:6379 \
JWT_SECRET=test-secret \
../bin/backend
# 默认监听 :8081
```

### 启用真实微信支付 SDK

```bash
WECHAT_USE_SDK=1 \
WECHAT_MCHID=<your_mch_id> \
WECHAT_APIV3_KEY=<32_byte_key> \
WECHAT_CERT_SERIAL=<serial> \
WECHAT_PRIVATE_KEY_PATH=/path/to/apiclient_key.pem \
WECHAT_NOTIFY_URL=https://your.domain/api/v1/callbacks/wechatpay \
CGO_ENABLED=0 go build -tags=wechat_sdk -o bin/backend ./cmd/server
```

### 启动 Tyk 网关

```bash
cd gateway
bash ../scripts/build-tyk.sh   # 已构建
bash ../scripts/run-tyk.sh     # 监听 :8080，代理到 :8081
```

### 前端

```bash
cd web-intl && npm install && npm run dev      # http://localhost:3000
cd web-domestic && npm install && npm run dev  # http://localhost:3001
```

### Docker Compose

```bash
docker compose up
```

## API 示例

```bash
# 创建订单
curl -X POST http://localhost:8081/api/v1/orders \
  -H "Content-Type: application/json" -H "X-Merchant-Id: 1" \
  -d '{"merchantOrderNo":"M001","amount":10000,"currency":"CNY","subject":"测试"}'

# 发起支付
curl -X POST http://localhost:8081/api/v1/payments \
  -H "Content-Type: application/json" -H "X-Merchant-Id: 1" \
  -d '{"orderId":"P...","channel":"WECHAT_JSAPI","openId":"oUpF8uN95"}'

# JWT 管理后台
TOKEN=$(./bin/issuetoken)
curl -H "Authorization: Bearer $TOKEN" http://localhost:8081/api/v1/admin/whoami
```

## 测试

```bash
cd backend
CGO_ENABLED=0 go test -count=1 ./internal/channel ./internal/service ./pkg/...

# E2E 证据
cat .omo/evidence/wave-final-integration.txt
```

## 文档

- `CHANGELOG.md` — 版本变更
- `docs/README.md` — 文档入口
- `docs/audit/V0.2.0-STATUS.md` — v0.2.0 实施报告
- `docs/audit/FINAL_REVIEW.md` — F1-F4 评审
- `docs/constraints/` — 7 份 ≤150 行的 Harness Engineering 约束
- `ISSUES.md` — 24 个 issue 跟踪表
- `tests/e2e_idempotency.sh` — 幂等 + 退款防护 E2E 集成测试
- `wiki/` — 9 份知识库文档
- Obsidian：`/Users/mac/AI_Agent/shared-knowledge/dongfeng-pay/`
  - `v0.3.0-idempotency.md` — 幂等算法设计文档

## 贡献

- 主分支：`master`（只读镜像，保留原 80+ commits）
- 重构分支：`refactor/go-gin-v2`（v0.2.0 实施）
- 提交规范：`type(scope): subject`（feat/fix/docs/refactor/test/chore）
- 约束文档：`docs/constraints/*.md` 每份 ≤150 行
- 提交前跑：`make lint && make test`

## 许可证

原项目 GPL-3.0。本重构保留原许可证。