# 卡密平台

**Repository Path**: F2T/card-platform

## Basic Information

- **Project Name**: 卡密平台
- **Description**: 卡密平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-14
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 通用卡密平台（多商户版 · 纯 H5 网页）

在线支付自动发卡密的销售平台，支持**平台自营 + 多商户入驻**双模式，UI 参考 16688 亮色电商蓝风格。包含三大模块：

- **H5 用户端**（Vue3 + Vant4）：商品浏览、货源广场、店铺主页、登录、下单支付、查看卡密、商家入驻申请
- **管理后台**（Vue3 + Element Plus + ECharts）：平台管理员管全局（商户审核/分类/商品/卡密/订单/管理员），商户账号只管本店数据
- **FastAPI 后端**（Python + SQLAlchemy 2.0 异步）：RESTful API、支付回调、自动发卡、多商户数据隔离

## ✨ 功能特性

| 模块 | 功能 |
| :--- | :--- |
| 用户端 | 手机验证码登录（未注册自动注册）、密码登录、分类浏览、商品详情（含店铺信息）、货源广场、店铺主页、下单、模拟支付、订单列表/详情、我的卡密（一键复制）、**商家入驻申请** |
| 平台后台 | 管理员登录（超管/普通/商户三种角色）、数据看板（今日订单/收入、在营商户数、近 7 日趋势、销量 TOP5）、**商户管理（入驻审核/新建/编辑/停用，通过审核时自动建商户后台账号）**、分类管理、商品管理（可按商户筛选/指派归属）、卡密管理、订单管理（含商户列）、管理员管理 |
| 商户后台 | 独立登录，仅可见/操作**本店**商品、卡密、订单与看板；隐藏商户/分类/管理员等平台菜单；停用店铺后禁止登录 |
| 后端 | 下单锁卡（并发安全）、支付回调幂等发卡 + **渠道一致性校验**、超时订单自动释放、验证码**一次性失效**、后台登录限流、JWT 双端鉴权、多商户数据范围隔离（`admin_scope`）、演示数据自动初始化（2 商户 + 平台自营商品） |
| 卡密 | 系统随机生成（去混淆字符集 XXXX-XXXX-XXXX-XXXX）或文本批量导入，支持有效期天数 |

## 🏬 多商户模型

```
Merchant（商户）status: 0待审核 / 1营业中 / 2停用
  ├── Product.merchant_id → 商品归属（NULL = 平台自营）
  ├── Admin.merchant_id   → 商户后台账号（NULL = 平台管理员）
  └── Order.merchant_id / merchant_name → 下单时商户快照
```

- 用户端「我的 → 商家入驻」提交申请 → 平台超管在「商户管理」审核 → 通过时创建商户后台账号
- 商户账号登录同一后台（/admin/），菜单与数据自动按店铺裁剪
- 商户被停用后：其账号无法登录后台，商品无法下单

## 📁 目录结构

```text
card-platform/
├── backend/                 # FastAPI 后端
│   ├── app/
│   │   ├── main.py          # 入口（建表、轻量迁移、初始超管、演示数据、超时任务）
│   │   ├── core/            # config / database / security
│   │   ├── models/          # SQLAlchemy 模型（含 Merchant）
│   │   ├── schemas/         # Pydantic 模型
│   │   ├── api/v1/          # auth / products / orders / merchant / admin
│   │   └── services/        # 卡密订单核心逻辑、短信、支付
│   └── tests/test_smoke.py  # 端到端冒烟测试（含多商户隔离用例）
├── h5-frontend/             # H5 用户端 (Vue3 + Vant)
├── admin-frontend/          # 管理后台 (Vue3 + Element Plus)
├── nginx/                   # 生产环境统一入口配置
├── docker-compose.yml       # 容器编排（MySQL + Redis + 后端 + 双前端 + Nginx）
└── .env.example             # 环境变量模板
```

## 🚀 本地快速启动（开发模式）

无需 MySQL/Redis：后端默认 SQLite，缓存自动降级为内存；短信与支付默认 mock。

### 1. 启动后端（端口 8000）

```bash
cd backend
pip install -r requirements.txt
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```

启动时自动建表并执行轻量迁移（为旧库补充商户相关列）、创建超管 `admin / admin123456`、写入演示数据：3 个分类、2 个商户（星辰数卡 / 极光软件源）+ 平台自营共 6 个商品与卡密。

API 文档：<http://127.0.0.1:8000/api/docs>

### 2. 启动 H5 用户端（端口 5173）

```bash
cd h5-frontend
npm install
npm run dev
```

访问 <http://localhost:5173>，登录验证码固定为 `8888`（任意未注册手机号自动注册）。

### 3. 启动管理后台（端口 5174）

```bash
cd admin-frontend
npm install
npm run dev
```

访问 <http://localhost:5174/admin/>。

### 4. 运行冒烟测试

```bash
cd backend
python tests/test_smoke.py
```

覆盖完整业务流：注册登录 → 浏览（含商户）→ 下单锁库存 → 支付发卡 → 渠道校验 → 查看卡密 → 取消释放库存 → 后台生成/导入卡密 → 订单查询 → **商户数据隔离 / 跨店操作拒绝 / 入驻申请与审核**。

## 🐳 生产部署（Docker Compose）

```bash
cp .env.example .env         # 修改 SECRET_KEY、FIRST_ADMIN_PASSWORD、SMS_MOCK=false、PAY_MOCK=false
docker compose up -d --build
```

Nginx 统一入口：`/` → H5、`/admin/` → 后台、`/api/` → FastAPI。
HTTPS：将证书放入 `nginx/ssl/` 并按 `nginx/nginx.conf` 注释启用 443 server。

> 切换到 MySQL 需安装 `asyncmy`（已在 requirements.txt），连接串见 `.env.example`。

## 💳 支付接入说明

`PAY_MOCK=true` 时使用模拟支付：下单后前端确认即触发发卡，用于演示与测试。
`PAY_MOCK=false` 时，用户端 `/orders/{no}/pay` 仅接受 mock 渠道且会被拒绝——真实渠道必须由支付平台异步通知验签后调用 `card_service.pay_and_deliver()`。

生产接入真实渠道（`app/services/pay_service.py` 预留了接口骨架）：

- **微信 H5 支付**：微信支付 API v3，需商户号 + APIv3 密钥 + 商户证书，下单返回 `h5_url` 唤起微信客户端，回调验签后调用发卡
- **支付宝手机网站支付**：`alipay.trade.page.pay`（RSA2），配置应用私钥与支付宝公钥，异步通知验签后同样调用发卡函数

发卡逻辑天然幂等（已支付订单直接返回），支付回调重复通知安全。

## 🔒 安全设计

- 密码 bcrypt 存储；JWT（HS256，7 天）区分 user/admin 角色，双端令牌互不通用
- **多商户隔离**：商户账号仅能读写本店商品/卡密/订单，跨店访问统一 404；商户管理/分类/管理员接口仅平台角色可用
- **支付渠道校验**：非 mock 渠道禁止前端直接触发发卡，防免费领取卡密
- **验证码一次性**：验证通过立即作废，防重放
- **后台登录限流**：IP + 用户名双维度滑动窗口限流，防口令爆破
- 下单锁定卡密采用条件更新（仅 `status=0` 可锁），并发安全防超卖
- 超时订单不可支付发卡（含 mock 渠道），杜绝与释放任务的竞态
- 卡密仅订单归属人与对应管理员可见；已售卡密不可作废；删除有售记录的商品自动下架

## 📋 默认账号

| 端 | 账号 | 凭证 | 说明 |
| :--- | :--- | :--- | :--- |
| H5 用户 | 任意手机号 | 验证码 `8888`（mock） | 未注册自动注册 |
| 平台后台 | admin | admin123456 | 超级管理员 |
| 商户后台 | merchant_xc | merchant123456 | 演示商户「星辰数卡」 |

> ⚠️ 生产部署前请通过 `.env` 修改 `FIRST_ADMIN_PASSWORD` 与 `SECRET_KEY`，并尽快修改演示商户账号密码。