开发文档

一、技术架构

• 框架：ThinkPHP 8 多应用（topthink/framework、think-orm、think-multi-app、think-view），轻量结构（不依赖更多扩展）；PHP 8.0+（推荐 8.1）/ MySQL 5.7+；
• 定位：这是一套白标代理站 —— 站点自己不做商品与开通，全部调用上游星聚授权中心的开放 API（/api/open/*）：拉商品、建订单、查订单、退款；代理预充余额按量扣费；
• 收款：后台三选一 —— ①自有易支付 ②平台代收（走上游）③手动收款；
• 目录：app/admin（后台 7 个控制器）、app/index（前台 6 个控制器）、app/service（上游接口封装等服务层）。

二、目录结构

程序根/
├── public/index.php      # Web 入口
├── app/
│   ├── admin/            # 后台（商品/订单/设置/收款配置）
│   ├── index/            # 前台（首页/下单/查单/用户中心）
│   └── service/          # 服务层（上游开放 API 调用、签名、订单同步）
├── config/               # 配置（app/cache/database/log/middleware/route/session/view）
├── route/app.php         # 路由
├── .env.example          # 环境示例（复制为 .env）
└── xj_panel.php          # 授权验证 / 在线更新维护页

三、数据库

• 表前缀 as_，只有 5 张表（轻量）：
• as_setting：站点与上游配置（上游地址、AppID/Secret、收款方式、站点品牌等）；
• as_user：会员（站点用户）；as_admin：后台账号；
• as_order：订单（含上游订单号、支付状态、发货状态）；
• as_api_log：上游接口调用日志（排查对接问题看这里）。

四、关键机制

4.1 上游对接（核心）

所有上游请求都在 app/service/ 里封装：带 appid + timestamp + sign 请求 /api/open/*，接口返回统一 JSON。要换上游/改协议，只动服务层，别散落到控制器。上游密钥在后台「开放 API」设置里（as_setting）。

4.2 下单与回调

流程：前台下单 → 写 as_order → 调上游建单 → 收款（三种模式）→ 支付成功回调 → 调上游完成发货并同步订单状态。回调地址在后台可查，配置易支付时记得填 notify_url / return_url。

4.3 白标

站点名称、Logo、客服、公告都在后台设置里，前台模板在 app/index/view/，替换成自己的品牌即可。

五、二次开发指引

• 加页面：app/index/controller/ + app/index/view/；
• 加后台功能：app/admin/controller/ + app/admin/view/，菜单在后台配置里加；
• 改上游调用：app/service/（统一入口 + 日志表 as_api_log 便于对照）；
• 注意：站点本地不存商品与卡密（都来自上游），修改价格只影响本站售价（as_order 里存快照），不要试图在本地发货。

六、授权与在线更新

xj_panel.php 支持验证授权与在线更新；授权码在根目录 xj_auth.php。更新会保留 config/、.env，覆盖程序文件，二开前先备份。