# TopUpCycle

**Repository Path**: os_2026/top-up-cycle

## Basic Information

- **Project Name**: TopUpCycle
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-30
- **Last Updated**: 2026-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

![TopUpCycle 话费权益管理系统](docs/images/topupcycle-cover.png)

# TopUpCycle · 话费权益管理系统

将营销活动、在线购买、月度话费券领取和充值管理集中在一套系统中。**后台与 API 共用 PHP 站点，购买页和领取页由后台生成，独立部署。**

[快速安装](#快速安装) · [界面预览](#界面预览) · [源码修改](#源码修改) · [构建与打包](#构建与打包) · [升级维护](#升级维护) · [发行版下载](https://gitee.com/os_2026/top-up-cycle/releases)

> 封面为 AI 生成的系统概念插画。下方为用户提供的管理界面截图（通过 AI 去除红框标注）；页面细节以当前版本为准。

## 系统介绍

TopUpCycle 适用于按营销活动销售话费权益、按月发放话费券并管理充值结果的业务。活动售价、券面额、赠送月份和领取规则在后台设置，购买与领取页面从 API 获取活动配置。

| 模块 | 主要功能 |
| --- | --- |
| 数据总览 | 支付金额、订单数量、领取与充值表现、支付趋势和地区分布 |
| 营销活动 | 配置活动权益、购买域名和负责人，查看活动统计 |
| 订单管理 | 查看支付订单、支付状态、设备与地区信息，详情和操作菜单，按需开启自动刷新 |
| 话费券与充值 | 月度券领取、充值状态同步、失败原因查看和管理员重新充值 |
| 域名与支付通道 | 管理购买/领取域名及支付通道配置 |
| 管理员与日志 | 超级管理员、链接管理员权限及操作记录 |
| 前端生成 | 按登记域名导出购买页/领取页 ZIP，附 API 配置与伪静态 |

买家领取失败后可以再次领取；管理员重新充值时，买家端同步显示充值中或充值成功。充值服务商的详细失败原因用于总后台排查。链接管理员按分配范围查看活动和订单。

### 技术与部署结构

| 层 | 技术 / 目录 | 部署方式 |
| --- | --- | --- |
| 管理后台 | React 19、TypeScript、Ant Design 6 · `apps/admin` | 构建后由 PHP 站点提供页面 |
| API | Laravel 12、Sanctum、PHP 8.3 · `services/api` | 与后台共用一份程序和数据库 |
| 购买前端 | React、TypeScript、Vite · `apps/purchase-web` | 后台生成静态包，部署到购买域名 |
| 领取前端 | React、TypeScript、Vite · `apps/receive-web` | 后台生成静态包，部署到领取域名 |
| 运行环境 | Nginx、MySQL、数据库队列、systemd | 宝塔管理网站，常驻队列处理充值任务 |

```text
买家 → 购买网站 ──┐
买家 → 领取网站 ──┼── HTTPS API → 数据库 / 支付与充值服务
管理员 → 后台 ───┘                 ↕
                              常驻充值队列
```

后台域名与 API 域名绑定到同一个 PHP 站点。购买/领取网站直接请求正式 API，无需添加 `/api` 反向代理。后台登记域名后，API 按登记信息允许公开接口跨域。

## 界面预览

### 订单管理

![TopUpCycle 订单管理实际界面](docs/images/order-management-clean.png)

订单列表集中展示订单、活动、支付方式、时间和设备信息。统计面板默认收起；自动刷新需要每次进入页面手动开启，离开页面后停止。

### 后台生成独立前端

在“系统设置 → 前端生成与部署”选择已启用的购买/领取域名，下载可直接部署的静态 ZIP。购买页展示活动和支付入口，领取页展示月度权益及充值状态。

## 快速安装

### 1. 准备服务器

- 已安装 **Linux 宝塔面板**，服务器使用 systemd，并通过 root 进入宝塔终端。
- 将后台域名、API 域名解析到这台服务器；本方案填写两个不同域名。
- 在宝塔“设置 → API 接口”开启接口，允许安装脚本使用的本机请求 IP，并准备 API 密钥。
- 自动安装缺失环境时，`/www` 至少有 8GB 可用空间；安装 MySQL 8.4 要求至少 2GB 内存，建议 4GB 以上。

### 2. 执行一条命令

```bash
curl -fL --proto '=https' --proto-redir '=https' \
  'https://gitee.com/os_2026/top-up-cycle/raw/master/install.sh?release=v2026.10.02.4' \
  -o /tmp/topupcycle-install.sh && bash /tmp/topupcycle-install.sh
```

入口下载安装包并校验 SHA256，通过后解压并开始交互安装。

| 输入项 | 如何填写 |
| --- | --- |
| 后台 / API 域名 | 仅填写域名，不带 `https://` 和路径 |
| 新项目名称 | 默认 `topupcycle`，创建 `/www/wwwroot/项目名`；不能使用已有目录 |
| 新数据库名称 / 账号 | 将创建的新数据库及账号，**不是 MySQL root 账号** |
| 新数据库密码 | 隐藏输入，至少 12 位；留空自动生成 |
| 宝塔 API 地址 | 面板协议、主机和端口，不填写安全入口路径 |
| 面板 CA 文件 | 自签证书时填写可信 CA 路径，否则回车 |
| 宝塔 API 密钥 | 隐藏输入，仅用于本次安装，不保存到项目 |
| 超级管理员邮箱 / 密码 | 安装时创建；没有固定默认管理员密码 |

本机面板地址可使用 `http://127.0.0.1:端口`；远程面板使用 HTTPS。脚本不会关闭证书校验。

### 3. 脚本会完成什么

1. 选择系统 Python 3 或宝塔 Python；缺失时通过系统包管理器安装。
2. 认证宝塔 API，检查现有环境。
3. 缺少 Nginx、MySQL、PHP 8.3 时调用宝塔官方安装器，默认安装 Nginx 1.30、MySQL 8.4、PHP 8.3，补充 fileinfo 并检查 PHP 扩展。
4. 创建项目目录、新数据库和账号，以及绑定后台/API 两个域名的 PHP 网站。
5. 写入伪静态及生产配置，初始化数据库和管理员。
6. 创建并启动 systemd 常驻充值队列。

已有组件会复用；已有数据库不会自动升级，已有 PHP 不会重装。遇到 Apache、非宝塔环境、组件目录损坏或扩展加载失败时，会停止并给出原因。安装包包含 PHP 生产依赖和前端成品，**部署服务器不需要 Composer 或 Node**。

### 4. 安装后配置

1. 在宝塔给后台与 API 域名申请 HTTPS 证书，并启用 HTTPS。
2. 登录后台，配置支付通道、充值服务商及活动权益。
3. 登记购买域名、领取域名，绑定购买活动并启用域名。
4. 在“前端生成与部署”分别导出购买/领取 ZIP。
5. 为购买/领取域名创建静态网站，上传 ZIP 中的页面资源，申请 HTTPS，复制后台或包内提供的伪静态。

静态前端伪静态：

```nginx
location / {
    try_files $uri $uri/ /index.html;
}
```

`README.txt`、`nginx-rewrite.txt` 是说明文件，无需上传。修改活动无需重新打包页面；更换 API 地址时重新生成前端包。

完整部署细节见 [宝塔与独立前端部署说明](deploy/DISTRIBUTED.md)。

## 源码修改

```text
apps/
  admin/          管理后台界面
  purchase-web/   购买页
  receive-web/    领取页
services/api/
  app/            业务逻辑、控制器、支付与充值适配
  config/         配置
  database/       数据库迁移
  routes/         路由与安装命令
  resources/      默认资源与构建后的前端导出模板
  public/         PHP 入口与构建后的后台
deploy/           构建、安装、打包工具
docs/             文档与图片
```

### 开发环境

开发机需要 PHP 8.3、Composer、Node.js（满足项目 Vite 6 要求，建议 Node 22）及 Python 3。前端依赖按各自锁文件安装：

```bash
git clone https://gitee.com/os_2026/top-up-cycle.git
cd top-up-cycle
npm ci --prefix apps/admin
npm ci --prefix apps/purchase-web
npm ci --prefix apps/receive-web
cd services/api
composer install
cp .env.example .env
```

填写开发数据库等配置后，在 `services/api` 执行 `php artisan key:generate` 和 `php artisan migrate`。开发数据库与生产数据库分别配置。

| 要修改的内容 | 修改位置 | 修改后的操作 |
| --- | --- | --- |
| 后台布局、菜单、文字 | `apps/admin/src` | 重新构建后台 |
| 购买页样式与交互 | `apps/purchase-web/src` | 重新构建，后台重新生成购买包 |
| 领取页样式与交互 | `apps/receive-web/src` | 重新构建，后台重新生成领取包 |
| API 或业务规则 | `services/api/app`、`routes` | 更新 PHP 文件，按需清理缓存和重启队列 |
| 活动售价、面额、月份 | 后台营销活动配置 | 保存后页面通过 API 读取 |

购买/领取导出包使用 `config.js` 配置正式 API 地址，不要把商户密钥放入前端代码。详细修改记录见 [开发记录](docs/DEVELOPMENT_LOG.md)。

## 构建与打包

### 1. 构建三套前端

在仓库根目录执行：

```bash
node deploy/build-distributed.mjs
```

构建产物：

- 后台：`services/api/public/sites/admin`，资源路径为 `/sites/admin/`。
- 购买模板：`services/api/resources/frontend-templates/purchase`。
- 领取模板：`services/api/resources/frontend-templates/receive`。

### 2. 准备 PHP 生产依赖

在干净的发布工作目录中执行：

```bash
cd services/api
composer install --no-dev --optimize-autoloader
cd ../..
```

### 3. 生成完整安装包

使用一个新的版本号，例如：

```bash
python3 deploy/package-release.py --version 2026.10.02.3 --notes docs/RELEASE-v2026.10.02.3.md
```

输出目录 `release/v2026.10.02.3/` 包含：

| 文件 | 用途 |
| --- | --- |
| `TopUpCycle-install-20261001-2-bt-distributed.zip` | 程序、生产依赖、后台成品和前端模板 |
| `installer.py` | 固定版本下载入口，内嵌安装 ZIP 的 SHA256 |
| `install.sh` | Python 环境选择与入口校验 |
| `SHA256SUMS` | 安装 ZIP 的摘要 |

打包工具只收集指定程序目录，不收集 `.env`、运行日志、storage 数据、数据库备份和 Git 历史。已有同版本输出目录时停止，不覆盖旧包。

### 4. 上传发行版

1. 将源码提交到 Gitee。
2. 创建对应标签的发行版，例如 `v2026.10.02.3`，上传本版本安装 ZIP。
3. 将同次打包生成的 `installer.py`、`install.sh`、`SHA256SUMS`、`update.json` 同步到仓库根目录。
4. 确认公开入口和附件可下载，附件 SHA256 与入口一致。

已有发行版使用固定包与固定摘要；后续修改发布新版本，不替换旧版本同名附件。当前入口指向 `v2026.10.02.4`。如果发布到自己的仓库，还需要调整 `deploy/install.sh` 中的仓库地址。

## 升级维护

总管理员可在 **系统设置 → 系统更新** 检查 Gitee 发行版并确认一键升级。新安装自动启用升级服务，现有服务器需先安装一次服务，见 [升级服务说明](docs/SYSTEM-UPDATE.md)。升级前备份数据库和程序，保留生产配置；独立购买/领取页升级后重新生成部署。完整安装脚本仍仅用于新安装。

一键安装器用于**新安装**。已有系统更新时，先备份数据库、生产 `.env` 与站点配置，再按对应版本更新说明覆盖程序文件。

- 保留原 `APP_KEY`、数据库配置和生产凭据。
- 数据库结构有变化时，按版本说明执行迁移。
- 更新后台构建产物；若购买/领取模板变化，重新导出并部署静态前端。
- 在 `services/api` 清理并重建配置/路由缓存；更新队列业务代码后重启对应 `topupcycle-项目名` 服务。
- 新建网站与数据库异常时，先检查宝塔已有资源和 `installation-state.json`，避免重复创建。

常见问题与处理：

| 问题 | 处理 |
| --- | --- |
| 宝塔 API 认证失败 | 确认已启用 API、白名单、地址与密钥 |
| 提示目标目录已存在 | 使用新项目名；旧系统按升级流程处理 |
| PHP zip 加载失败 | 在宝塔 PHP 8.3 修复 zip/libzip，不能仅靠页面配置解决 |
| 买家页面读不到活动 | 检查域名是否登记启用、购买域名是否绑定活动、API HTTPS 和跨域配置 |
| 充值长期处理中 | 检查队列服务、服务商返回及失败任务；核对上游结果后处理 |
| 记录为代理 IP | 直接访问 API 或按真实代理来源配置 IP 传递；旧日志无法自动恢复 |

## 当前发布状态

源码与 `v2026.10.02.4` 安装附件公开发布，升级信息由 update.json 提供。前端成品已完成生产构建。**完整安装、宝塔接口兼容性与线上支付/充值仍需在目标 Linux 服务器验证**，具体支持范围以部署说明为准。

参考：[宝塔官方软件安装命令](https://www.bt.cn/bbs/thread-154861-1-1.html) · [宝塔 fileinfo 安装说明](https://www.bt.cn/bbs/thread-146215-1-1.html)

## v2026.10.01.1 更新内容

新增 Gitee 检测更新、一键升级、升级前备份与失败日志；修复统一后台 Session 报错及发行包权限。见 [发行说明](docs/RELEASE-2026.10.01.1.md)。

## v2026.10.01 更新内容

新增投诉对话、人工退款记录和手机号查询；优化售后页导航、表单按钮及手机列表，修复独立前端更新时 API 地址丢失。

详见 [发行说明](docs/releases/v2026.10.01.md)。完整安装包已包含新迁移、后台成品和最新购买/领取页模板。

## v2026.10.01.2 安装优化

新增保存信息与断点续装，失败后修复并按回车继续，退出后执行 `bash /var/lib/topupcycle-installer/resume.sh`。临时凭据仅 root 可读，完成后清除。修复已有 Nginx/PHP 服务重复启动失败。见 [续装说明](docs/INSTALL-RESUME.md)。

## v2026.10.02 活动支付通道切换

链接管理员可在自己负责的营销活动中切换启用的支付通道，切换需要确认且记录操作日志。切换不修改已有订单，仅对新订单生效。弹窗展示全部活动近7天的通道实际成功率及样本数，同时单列加10个百分点的参考值（上限100%），无样本显示暂无数据。支付通道配置与活动权益仍由超级管理员管理。

## v2026.10.02.1 混合通道轮询

营销活动可使用单通道或混合轮询，混合模式可选择并排列至少2条启用通道。新订单按活动内顺序轮流使用，例如 ID4 → ID5 → ID4；保存后从第一项开始，停用或不支持支付方式的通道会跳过。替换需确认，成功显示替换成功。暂无样本显示“暂无数据，酌情考虑”。升级包含轮询字段迁移，后台一键升级自动执行。

## v2026.10.02.2 通道界面精简

活动卡片通道信息独立一行，操作按钮统一对齐。替换弹窗仅展示通道、支付方式和实际支付成功率，移除参考值、订单数及底部说明。混合轮询及替换确认保持可用。

## 收银台反代

支付通道可独立开启自己的 HTTPS 收银台入口、编辑上游来源和路径规则；默认关闭，首次使用需部署代理服务和独立域名。参见 [部署与使用说明](docs/CHECKOUT-PROXY.md)。