开发记录：网课系统对接上游官方售后工单完整实现
前言
本次基于个人运营的网课系统，严格根据上游官方开发者文档，独立开发完成上游售后工单对接功能。
由于系统核心文件采用 SourceGuardian 加密，无法修改内核源码、无法新增内核接口。因此本次功能全部采用 明文增量外挂式开发，不改动系统原有加密逻辑、不影响原有订单、货源同步功能，实现完整的上游工单售后闭环。
一、官方接口文档参考
全程严格按照上游提供的两个 POST 接口开发：
1. 提交工单接口
接口地址：https://admin.aceee.de/api.php?act=submitWorkOrder
- 支持：文字工单 + 单张图片上传
- 提交规范：multipart/form-data 原生表单提交
- 限制规则：文字 5-300 字、图片最大 8MB、仅支持 JPG/PNG/GIF/WEBP
- 自动校验订单状态，过滤不可提交订单
2. 查询工单接口
接口地址：https://admin.aceee.de/api.php?act=queryWorkOrder
- 根据上游返回 workId 查询工单状态
- 动态获取上游推荐轮询间隔 pollInterval
- 可同步：工单状态、客服文字回复、双方图片资源
二、开发实现需求
- 用户可在订单列表，对有效订单提交上游官方售后工单
- 支持文字问题描述 + 图片举证上传
- 提交成功自动保存上游唯一 workId 至本地数据库
- 跟随上游 pollInterval 动态轮询，不无效高频请求
- 上游回复后，自动同步文字、图片回复至前台展示
- 普通用户仅可操作自己工单，管理员可全局查看、代提交工单
- 完全遵守上游防重复提交、24小时提交次数、余额频率限制
三、项目开发限制
- 系统核心接口全部 SG 加密，禁止修改内核文件
- 不改动原有 TG 本地工单、订单结算、货源同步逻辑
- 所有新功能外置独立明文文件，增量部署、零侵入系统
四、整体架构设计
采用完全解耦外挂架构，新旧工单系统共存，互不冲突。
前端订单页面(list.php)
↓
自建明文接口(api_workorder.php)
↓
工单核心服务类(workorder.php)
↓
上游官方API服务
plaintext
模块说明
- 核心服务层（workorder.php）
自动建表、封装上游 CURL 请求、图片安全校验、图片 URL 修复、数据库读写逻辑。 - 接口控制层（api_workorder.php）
独立开发全套接口：提交工单、查询工单、工单列表、可提交订单筛选。 - 前端展示层
改造原有订单页面，保留本地 TG 工单，新增「上游官方工单」独立入口。
五、核心功能开发细节
1. 标准图文工单提交
严格遵循官方示例，不手动拼接 boundary、不自定义请求头，避免上游安全拦截。
直接使用 CURL 自动生成 multipart 表单，完美兼容图片上传。
- 使用 finfo 读取图片真实 MIME，杜绝后缀伪造
- 强制校验文字字数、图片大小、文件格式
- 自动判断订单状态，拦截已退款/已取消/未支付订单
2. 智能动态轮询机制
完全跟随上游官方规则：
- 工单状态
pending：按照 pollInterval 延时自动轮询 - 工单状态
replied：停止轮询，保存所有回复数据
极大减少无效请求，完全贴合上游接口规范。
3. 图片适配兼容（解决裂图BUG）
上游返回图片地址格式混乱（完整域名、//协议头、裸域名、相对路径），
自研 URL 归一化规则，自动统一修复：
- 自动补全协议前缀
- 自动拼接站点根路径
- 前端添加防盗链适配策略，彻底解决图片加载失败问题
4. 安全权限控制
- 普通用户：仅查看、提交个人名下工单
- 管理员(uid=1)：全站工单查看、代用户提交售后
- 后端只读数据库真实订单归属UID，不信任前端传参，杜绝越权伪造漏洞
六、测试方案
为避免频繁请求生产上游接口，采用本地 Mock 测试：
- 本地搭建 PHP 模拟服务，复刻上游所有返回场景
- 全覆盖测试：参数报错、字数拦截、图片拦截、待回复、已回复、管理员代提交
- 本地逻辑 100% 跑通后，再对接真实上游生产接口
七、部署方式
纯增量更新，无需重装系统：
- 新增两个明文核心文件
- 小幅修改三个前端明文页面
- 程序首次访问自动创建数据库，零手动操作
八、开发总结
本次在内核加密无法改动的限制下，通过「明文外挂增量开发」的思路，成功给封闭系统新增了一整套完整的上游官方售后工单系统。
全程完全对标官方开发者文档，解决了 multipart 上传拦截、动态轮询、图片URL兼容、权限安全等多个难点，最终实现了用户提交、图文反馈、上游同步、自动更新回复、管理员管理的完整业务闭环。