移除了 khhao 平台相关

2026-05-14 13:08:24 +08:00
parent d335b430e6
commit 83cb2ff1fa
56 changed files with 108 additions and 3893 deletions
@@ -19,7 +19,7 @@

 ## 2. 设计原则

- `91卡券` 作为**新的订单来源**，不复用 `agiso`、`khhao`。
+- `91卡券` 作为**新的订单来源**，不复用 `agiso`。
 - `91卡券` 不是新的履约执行器，而是外部售卖、订单输入和自动发货通道。
 - 当前项目真正的交付物仍然是 `claimUrl`。
 - 查询接口返回 `20` 的判断标准是“领取链接已生成并可发”，不是“快手最终兑换完成”。
@@ -38,7 +38,7 @@
 原因：

 - 避免与 `agiso` webhook 语义混淆；
- 避免复用 `khhao` 的后台拉单来源；
+- 避免复用历史后台拉单来源；
 - 便于后续单独做日志、排障和绑定配置。

 ## 4. 接口设计
@@ -72,7 +72,7 @@ https://5cc8-193-176-84-38.ngrok-free.app/api/v1/webhooks/agiso/trade
 https://221329.cc.cd/api/v1/webhooks/agiso/trade

 ----
-服务器  https://order.khhao.com/api/v1/webhooks/agiso/trade
+服务器  生产域名见部署配置

 调试   https://926d-193-176-84-20.ngrok-free.app/api/v1/webhooks/agiso/trade

@@ -81,4 +81,3 @@ https://221329.cc.cd/api/v1/webhooks/agiso/trade
 ==========
 https://123.207.217.176/#/home    发货
 账号  17665234375   密码 yaochao11
-
@@ -1,4 +1,8 @@

+最快解决（强制使用 HTTP/2 协议）防止clash干扰
+cloudflared tunnel --protocol http2 run --url http://localhost:80 mac-mini-tunnel
+
+

 cloudflared tunnel create mac-mini-tunnel

@@ -6,7 +6,7 @@

 - **订单来源层**
  - `agiso`：Webhook 推送型；
-  - `khhao`：账号密码登录 + 验证码识别 + Cookie 会话拉取型。
+  - `91卡券`：开放接口下单型。
 - **履约执行层**
  - 当前以内置人工发货、腾讯领取兑换等执行器为主。

@@ -17,19 +17,19 @@
 - 前端代码里根实例名显示为 `cloudtentacles`

 这个平台**不是订单数据源**，而是**订单创建后用于执行发货/兑换的外部履约平台**。  
-它和 `khhao` 的相同点只是“都需要后台登录”，但系统角色完全不同：
+它和订单来源平台的系统角色完全不同：

- `khhao`：订单来源 / 上游平台；
+- `91卡券`：订单来源 / 上游平台；
 - `cloudtentacles`：履约执行 / 下游发货平台。

-它的登录链路与 `khhao` 明显不同：
+它的登录链路独立于订单来源：

 - 不是图片验证码识别；
 - 是“账号 + 密码 + 手机号 + 短信验证码”登录；
 - 登录参数不是明文提交，而是前端先做 `MD5 + RSA-OAEP(SHA-256)` 加密；
 - 登录成功后不是 Cookie 会话，而是返回 `token`，后续通过 `Authorization` 请求头访问接口。

-因此它应当作为**履约执行器能力**接入，复用 `khhao` 的“HTTP 登录平台”经验，但不要按“来源平台”建模。
+因此它应当作为**履约执行器能力**接入，不要按“来源平台”建模。

 ---

@@ -178,7 +178,7 @@ MD5(password).toString(Hex)

 更合理的定位是：

- 订单来源 `provider/platform/shopId` 仍然来自 `agiso` / `khhao`
+- 订单来源 `provider/platform/shopId` 仍然来自 `agiso` / `91卡券`
 - `cloudtentacles` 属于**履约执行器 / 外部发货平台**

 因此它更适合进入这条链路：
@@ -207,9 +207,9 @@ MD5(password).toString(Hex)
 - 发货业务服务
 - 履约执行适配层

-## 4.3 不建议直接照抄 khhao 的原因
+## 4.3 不建议照搬来源平台的原因

-`khhao` 当前链路核心是：
+历史拉单平台链路核心是：

 - 打开登录页
 - 拉验证码图片
@@ -441,7 +441,7 @@ platforms: {

 ## 6.2 持久化来源配置

-建议和 `khhao` 一样，先用数据文件落地，不急着进数据库。
+建议先用数据文件落地，不急着进数据库。

 建议文件：

@@ -563,7 +563,7 @@ POST /api/v1/admin/platforms/cloudtentacles/validate-session

 ## 8. 后台 UI 设计建议

-第一版 UI 不需要太复杂，但应与 `khhao` 分开，避免把“订单来源配置”和“履约平台配置”混在一起。
+第一版 UI 不需要太复杂，应避免把“订单来源配置”和“履约平台配置”混在一起。

 建议在“平台配置”页新增独立区块，归类到“履约平台”分组：

@@ -606,7 +606,7 @@ POST /api/v1/admin/platforms/cloudtentacles/validate-session

 注意：

- 不要把这个平台和 `khhao` 放在同一张混合表单里；
+- 不要把这个平台和订单来源放在同一张混合表单里；
 - 页面上要明确区分：
  - 订单来源平台
  - 履约执行平台
@@ -656,7 +656,7 @@ POST /api/v1/admin/platforms/cloudtentacles/validate-session

 也就是说：

- `agiso/khhao` 决定“订单从哪里来”
+- `agiso/91卡券` 决定“订单从哪里来”
 - `cloudtentacles` 决定“订单怎么发出去”

 ---
@@ -717,12 +717,12 @@ POST /api/v1/admin/platforms/cloudtentacles/validate-session

 最重要的不是把接口先堆进去，而是先把结构定对：

- `khhao` 型平台：验证码图片 + Cookie
+- 历史拉单型平台：验证码图片 + Cookie
 - `cloudtentacles` 型平台：短信码 + RSA 加密 + token

 二者都属于“后台登录型平台”，但在系统分层上不同：

- `khhao`：来源层
+- `91卡券`：来源层
 - `cloudtentacles`：履约层

 因此第一版推荐结论是：
@@ -1,403 +0,0 @@
-# khhao 新数据来源接入设计
-
-## 1. 背景
-
-当前系统的订单来源只有 `agiso`，核心模式是：
-
- 上游通过 webhook 推送订单事件；
- 后端按 `provider + platform + shopId + platformOrderId` 幂等落库；
- 命中履约绑定后生成任务、领取链接、自动发货等后续流程。
-
-现在需要新增一个来源：`admin.khhao.com` 这一套已开发好的平台后台。
-
-和 `agiso` 的差异是：
-
- **不是 webhook 推送**，而是**账号密码登录 + 验证码识别 + Cookie 会话查询**；
- 订单数据来自平台接口查询；
- 初期目标是先完成**登录能力**与**订单查询能力**，再决定是否做定时拉取/增量同步。
-
-## 2. 已确认事实（来自 `2026-05-02` 的 HAR）
-
-HAR 文件：`/Users/yml/Desktop/抓包/登陆.har`
-
-已确认接口链路：
-
-1. 打开登录页  
-   `GET https://admin.khhao.com/c/login/index.php`
-
-2. 获取验证码图片  
-   `GET https://admin.khhao.com/verify_img.php`
-
-3. 提交登录表单  
-   `POST https://admin.khhao.com/c/login/index.php`  
-   表单字段：
-   - `username`
-   - `password`
-   - `img_code`
-
-4. 登录成功响应  
-   ```json
-   {"errcode":0,"msg":"登陆成功","url":"/c/payOrder/index.php"}
-   ```
-
-5. 查询订单列表  
-   `GET https://admin.khhao.com/c/payOrder/get.php?page=1&limit=50`
-
-6. 当前 HAR 中，登录依赖 `PHPSESSID` Cookie 维持会话。
-
-订单列表响应里已看到这些关键字段：
-
- `ordersn`：外部订单号
- `pingtai` / `pingtaiName`：平台标识/平台名
- `shopid` / `shopName`：店铺
- `goodid` / `goodName`：商品
- `sku`：SKU
- `fee`：成交金额
- `chengben` / `lirun`：成本/利润
- `num`：数量
- `status` / `statusName`：订单状态
- `addtime`：下单/录入时间
-
-## 3. 设计目标
-
-### 3.1 MVP 目标
-
-先做最小可用能力：
-
-1. 后端可通过账号密码自动登录 khhao；
-2. 自动拉取验证码图片，并用现有 `ddddocr` 识别；
-3. 登录成功后带 Cookie 调用订单查询接口；
-4. 能按统一结构把 khhao 订单转换为内部订单模型；
-5. 提供一个**手动查询 / 手动同步**入口，先不直接接入自动履约主流程。
-
-### 3.2 第二阶段目标
-
-1. 支持按时间窗口或页码批量拉取订单；
-2. 增加定时轮询同步；
-3. 将 khhao 订单正式纳入现有订单履约流程；
-4. 视需要增加远端订单详情接口接入。
-
-## 4. 关键设计决策
-
-## 4.1 新来源标识
-
-建议：
-
- `provider = 'khhao'`
- `platform = 由返回字段映射`
-
-原因：
-
- 现有系统已经以 `provider/platform` 作为来源分层；
- khhao 本身更像“聚合后台/运营后台”，其下可能有多个平台；
- 后续如果 `pingtai=3` 代表快手、还有其它平台，也可以继续扩展。
-
-建议先做一个映射表，例如：
-
- `3 -> kuaishou`
- 未识别值 -> `unknown`
-
-同时把原始 `pingtai`、`pingtaiName` 放进 `raw_payload_json` 保留证据。
-
-## 4.2 接入模式
-
-`agiso` 是 **push**；`khhao` 应设计成 **pull**。
-
-因此不要强行塞进 `webhook-service`，而是单独建立：
-
- 登录会话服务
- 验证码识别服务
- 订单查询服务
- 订单转换/同步服务
-
-## 4.3 会话管理
-
-建议优先采用 **纯 HTTP + Cookie Jar**，不引入浏览器自动化。
-
-原因：
-
- HAR 显示登录流程很简单，没有前端加密、签名或复杂跳转；
- 验证码是普通图片；
- 登录后查询接口是标准 XHR；
- 用 HTTP 实现更稳定，也更适合服务端定时任务。
-
-只有在后续发现以下情况时，再退回浏览器方案：
-
- 服务端校验动态前端字段；
- 有 JS 生成签名；
- Cookie/会话依赖浏览器行为；
- 验证码识别成功但仍反复登录失败。
-
-## 4.4 OCR 复用
-
-现有 OCR 子服务已经使用：
-
- `apps/backend/subservices/ocr-worker`
- `ddddocr>=1.6.1`
-
-因此不需要新增 OCR 技术栈，只需要把 khhao 验证码图片作为图片字节传给现有 OCR 能力即可。
-
-建议新增一个更通用的方法，而不是继续绑定在 “Tencent” 语义上：
-
- 现状：`recognizeTencentCaptcha`
- 建议新增：`recognizeImageCaptcha`
-
-然后：
-
- 腾讯验证码继续走原接口或复用通用接口；
- khhao 登录验证码直接走通用接口。
-
-## 5. 推荐模块拆分
-
-建议新增目录：
-
-`apps/backend/src/services/platforms/khhao/`
-
-建议模块：
-
-### 5.1 `captcha-service.js`
-
-职责：
-
- 请求 `/verify_img.php`
- 读取图片字节
- 调 OCR
- 返回识别结果与调试信息
-
-建议返回：
-
- `captchaText`
- `imageBase64`（仅调试阶段可选）
- `cookieHeaders`
-
-### 5.2 `session-service.js`
-
-职责：
-
- 初始化 Cookie 容器；
- 访问登录页，拿到初始 `PHPSESSID`；
- 获取验证码并识别；
- 提交登录表单；
- 校验登录响应；
- 返回已登录会话对象。
-
-建议会话对象：
-
- `baseUrl`
- `cookieHeader`
- `cookieMap`
- `loggedInAt`
-
-### 5.3 `order-query-service.js`
-
-职责：
-
- 调用 `/c/payOrder/get.php`
- 支持分页参数：`page`、`limit`
- 后续支持筛选参数（如果继续抓到更多接口）
- 返回原始平台订单列表
-
-### 5.4 `order-mapper-service.js`
-
-职责：
-
- 将 khhao 原始订单映射成内部统一订单结构；
- 归一化金额、数量、状态、平台、店铺、SKU；
- 产出可供 `order-service` 或新同步服务消费的对象。
-
-建议映射：
-
- `platformOrderId <- ordersn`
- `shopId <- shopid`
- `shopName <- shopName`
- `totalAmount <- fee`（转分）
- `items[0].skuCode <- sku`
- `items[0].skuName <- goodName`
- `items[0].quantity <- num`
- `rawPayload <- 原始整条记录`
-
-注意：
-
- 当前列表接口一条记录看起来像“一单一商品”，但不能假设永远如此；
- 第一版可以先按单商品映射；
- 如果后续发现有多商品订单，再调整内部映射。
-
-### 5.5 `order-sync-service.js`
-
-职责：
-
- 批量查询 khhao 订单；
- 调 `order-mapper-service` 转换；
- 调内部订单 upsert；
- 记录同步结果、失败原因、游标信息。
-
-这里建议不要直接复用 `upsertOrderFromWebhook(event)`，因为它的命名和语义绑定 webhook。
-
-更合理的演进方向：
-
- 抽一个来源无关的方法，例如 `upsertOrderFromSource(event)`；
- `webhook-service` 继续只负责 webhook 解析；
- `khhao` 同步服务直接调用来源无关的 upsert。
-
-## 6. 配置设计
-
-## 6.1 运行时配置
-
-建议在：
-
- `apps/backend/config/default.cjs`
- `apps/backend/src/types/runtime-config.js`
- `apps/backend/src/config/runtime.js`
-
-增加：
-
-```js
-platforms: {
-  khhao: {
-    baseUrl: 'https://admin.khhao.com',
-    timeoutMs: 5000,
-    loginPath: '/c/login/index.php',
-    captchaPath: '/verify_img.php',
-    orderListPath: '/c/payOrder/get.php',
-  },
-}
-```
-
-## 6.2 凭据配置
-
-不建议把账号密码直接写进仓库文档或默认配置。
-
-建议通过以下方式之一管理：
-
-1. 环境变量；
-2. `apps/backend/data/khhao-sources.json`；
-3. 后台平台配置页维护。
-
-建议结构：
-
-```json
-{
-  "sources": [
-    {
-      "sourceKey": "khhao-main",
-      "enabled": true,
-      "baseUrl": "https://admin.khhao.com",
-      "username": "******",
-      "password": "******",
-      "defaultPlatform": "kuaishou"
-    }
-  ]
-}
-```
-
-第一阶段最省成本的方案：**本地文件 + 环境变量覆盖**。
-
-## 7. 与现有系统的衔接方式
-
-## 7.1 第一阶段：只做手动查询/同步
-
-建议新增后台接口，例如：
-
- `POST /api/v1/admin/platform-config/khhao/test-login`
- `POST /api/v1/admin/platform-config/khhao/query-orders`
- `POST /api/v1/admin/platform-config/khhao/sync-orders`
-
-这样好处是：
-
- 不会影响现有 `agiso` 主链路；
- 可以先验证 OCR、登录、Cookie、字段映射；
- 便于比对真实订单数据。
-
-## 7.2 第二阶段：纳入统一订单流程
-
-当字段映射稳定后，再把 khhao 同步数据接到统一订单主链路：
-
- 来源查询 -> 订单映射 -> 通用 upsert -> 履约绑定 -> 任务生成
-
-这一步需要补充：
-
- khhao 订单状态到内部 `orderStatus/payStatus` 的映射；
- 去重与增量同步策略；
- 同一来源重复登录的频率控制；
- 同步审计日志。
-
-## 8. 状态映射建议
-
-当前 HAR 仅看到：
-
- `status = 2` => `已发货`
- `status = 0` => `未打款`
-
-第一阶段不要写死太多业务含义，建议：
-
-### 内部订单状态
-
- `status=0` -> `created`
- `status=2` -> `delivered`
- 未知值 -> `unknown`
-
-### 内部支付状态
-
- `status=0` -> `unpaid`
- `status=2` -> `paid`
- 未知值 -> `unknown`
-
-但这只是 **初版推断**，最终要以更多样本验证。
-
-## 9. 风险点
-
-1. **验证码识别率**
-   - `ddddocr` 大概率可用，但识别失败需要自动重试；
-   - 建议单次登录允许 `2~3` 次验证码重试。
-
-2. **登录态过期**
-   - 需要判断何时复用 Cookie，何时重新登录；
-   - 第一阶段可以每次查询都重新登录，先求稳定。
-
-3. **订单列表不是详情接口**
-   - 当前拿到的是列表接口，不排除存在订单详情页/详情接口；
-   - 第一版先以列表字段落库；
-   - 如果后续履约需要更多字段，再补抓详情接口。
-
-4. **平台字段含义未完全确认**
-   - `pingtai=3` 目前只从样本推断是快手；
-   - 需要再抓几个平台样本确认映射表。
-
-5. **同步边界**
-   - khhao 是拉取式来源，必须明确增量条件；
-   - 第一版建议按 `page/limit` 手动同步，先不做自动游标。
-
-## 10. 推荐实施顺序
-
-### 阶段 A：打通基础能力
-
-1. 增加 khhao 配置结构；
-2. 增加通用图片 OCR 能力；
-3. 实现登录 + Cookie 会话；
-4. 实现订单列表查询；
-5. 增加后台“测试登录 / 查询订单”接口。
-
-### 阶段 B：打通内部模型
-
-1. 实现 khhao -> 内部订单映射；
-2. 提炼 webhook 无关的通用 order upsert；
-3. 增加手动同步接口；
-4. 在后台展示同步结果。
-
-### 阶段 C：进入自动履约
-
-1. 增量同步；
-2. 定时任务；
-3. 状态回补；
-4. 接入履约绑定、任务生成、消息通知。
-
-## 11. 本次设计结论
-
-结论很明确：
-
- khhao 不应该按 `agiso webhook` 思路接；
- 应该作为一个新的 **pull 型来源** 单独建接入层；
- OCR 直接复用现有 `ddddocr` 子服务；
- 第一阶段先做**手动查询/同步**最稳；
- 等字段、状态、平台映射稳定后，再接入统一履约主流程。
-