From dde6f2c269ed57690a93bdd2320c8367c20e6580 Mon Sep 17 00:00:00 2001 From: yml2213 Date: Fri, 24 Jul 2026 15:17:22 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20README=20=E9=83=A8?= =?UTF-8?q?=E7=BD=B2=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 179 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ac5d40d --- /dev/null +++ b/README.md @@ -0,0 +1,179 @@ +# 游戏皮肤分销管理系统 + +基于 Go + React 的游戏皮肤分销管理平台，支持分销商管理、订单追踪、上游皮肤源头对接。 + +## 技术栈 + +| 层级 | 技术 | +|------|------| +| 后端 | Go 1.26 + Gin + GORM | +| 数据库 | PostgreSQL 16 | +| 前端 | React 19 + TypeScript + Ant Design | +| 构建 | Vite + Docker Compose | +| 反向代理 | Caddy | + +## 本地开发 + +### 环境要求 + +- Go 1.26+ +- Node.js 22+ +- Docker（用于自动启动 PostgreSQL 开发容器） + +### 快速启动 + +```bash +# 1. 复制配置文件 +cp .env.example .env +# 按需修改 .env 中的密钥 + +# 2. 一键启动（后端 + 前端 + PostgreSQL） +make dev +# 或直接 +./start.sh +``` + +启动后： +- 前端：`http://localhost:5173` +- 后端：`http://localhost:8080` +- 默认管理员：`admin` / `admin123` + +按 `Ctrl+C` 停止所有服务。 + +### 手动启动 + +```bash +# 安装依赖 +make install + +# 分别启动 +make backend # 后端 :8080 +make frontend # 前端 :5173 +``` + +## Docker 生产部署 + +### 配置 + +```bash +cp .env.example .env +# 编辑 .env，确保以下变量已配置： +# JWT_SECRET — 生产环境务必修改 +# OPEN_API_KEY — 皮肤源头对接 API Key +# OPEN_API_SECRET — 签名密钥 +# DATABASE_URL — PostgreSQL 连接，容器内主机名为 postgres +``` + +> 国内服务器可在 `.env` 中取消 `GOPROXY`、`ALPINE_MIRROR`、`NPM_REGISTRY` 等镜像加速源的注释。 + +### 启动服务 + +```bash +# 构建并启动全部服务（PostgreSQL + 后端 + Caddy） +make docker-up +# 或 +docker compose up -d --build +``` + +服务端口： +- `:80` — 前端页面 + API（Caddy 统一入口） +- `:8080` — 后端 API（直接访问，调试用） + +### 常用命令 + +```bash +make docker-logs # 查看日志 +make docker-ps # 查看容器状态 +make docker-down # 停止并移除 +``` + +### 自定义域名 + +修改 `Caddyfile` 中的域名 `skin.khhao.com` 为你的域名，重新构建即可。 + +## 环境变量 + +| 变量 | 说明 | 默认值 | +|------|------|--------| +| `PORT` | 后端端口 | `8080` | +| `JWT_SECRET` | JWT 签名密钥 | 开发默认值 | +| `DATABASE_URL` | PostgreSQL 连接串 | 本地开发默认值 | +| `GIN_MODE` | Gin 运行模式 | `debug` | +| `OPEN_API_KEY` | 开放接口 ApiKey | 需修改 | +| `OPEN_API_SECRET` | 开放接口签名密钥 | 需修改 | +| `OPEN_SIGN_SKEW` | 签名时间戳偏差（秒） | `300` | +| `OPEN_API_DEBUG` | 开放接口调试日志 | debug 模式默认开启 | +| `LOG_FILE` | 日志文件路径 | `logs/app.log` | + +## 开放接口（皮肤源头对接） + +上游皮肤源头系统通过以下接口对接，需携带签名头 `X-Api-Key`、`X-Timestamp`、`X-Nonce`、`X-Sign`。 + +### 1. 查询订单（发货前置） + +``` +GET /api/open/v1/orders/:order_no +``` + +返回订单状态、商品信息、是否可发货。 + +### 2. 发货结果通知 + +``` +POST /api/open/v1/orders/ship-notify +``` + +上游发货完成后推送结果，请求体： + +```json +{ + "order_no": "O202607241200000012", + "ship_status": "success", + "provider_order_no": "上游单号", + "shipped_at": "2026-07-24T16:00:00+08:00", + "fail_reason": "", + "game_channel": "IOS-微信", + "game_uid": "550e8400-e29b-41d4-a716-446655440000", + "role_name": "玩家名", + "pay_score": 100 +} +``` + +| 字段 | 必填 | 说明 | +|------|------|------| +| `order_no` | 是 | 系统订单号 | +| `ship_status` | 是 | `success` / `failed` / `processing` | +| `provider_order_no` | 否 | 上游单号 | +| `shipped_at` | 否 | 发货时间，RFC3339 格式 | +| `fail_reason` | 否 | 失败原因 | +| `game_channel` | 否 | 账号区服（安卓/IOS-微信/QQ） | +| `game_uid` | 否 | 游戏角色 UUID | +| `role_name` | 否 | 角色名 | +| `pay_score` | 否 | 消耗积分 | + +## 管理端 + +管理员登录后可访问商品管理、订单管理、用户管理、发货日志等功能。后台默认地址 `/`。 + +## 目录结构 + +``` +├── backend/ +│ ├── cmd/server/main.go # 入口 +│ └── internal/ +│ ├── config/ # 配置加载 +│ ├── handler/ # HTTP 处理器 +│ ├── middleware/ # JWT 认证、签名验证 +│ ├── model/ # 数据模型 +│ ├── pkg/ # 工具包 +│ ├── router/ # 路由 +│ └── service/ # 业务逻辑 +├── frontend/src/ +│ ├── api/ # API 调用 +│ ├── pages/ # 页面组件 +│ ├── layouts/ # 布局 +│ └── types/ # 类型定义 +├── docker-compose.yml # 容器编排 +├── Makefile # 常用命令 +└── start.sh # 开发一键启动 +```