douba_shop/.trae/documents/PLAN.md

2. 物流查询接口配置功能分析与实施计划

本计划旨在分析 /admin/setting/third_party 路由的实现原理，并指导如何将物流查询接口配置替换为 聚水潭 (Jushuitan)。

2.1 现有实现分析

1. 路由与控制器：

   • 前端路由 /admin/setting/third_party 对应后端接口 config/edit_new_build/third。
   • 控制器方法：app/controller/admin/v1/system/config/SystemConfig.php 中的 getNewFormBuild。
   • 核心逻辑：调用 app/services/system/config/SystemConfigServices.php 中的 thirdPartyFormBuild 方法构建表单。

2. 配置存储：

   • 所有配置项存储在数据库表 eb_system_config 中。
   • logistics_type 字段控制当前使用的物流查询服务商。
   • 配置项的参数也存储在该表中。

3. 业务逻辑消费：

   • 物流查询逻辑位于 app/services/other/ExpressServices.php 的 query 方法。

2.2 实施步骤

步骤 1：数据库配置添加

需要在 eb_system_config 表中添加聚水潭相关的配置项。 参考文档：聚水潭开放平台 - 第三方授权

• 操作：插入新记录。
  • jushuitan_app_key: 应用 App Key
  • jushuitan_app_secret: 应用 App Secret
  • jushuitan_access_token: 访问令牌 (Access Token)
• 更新：修改 logistics_type 的 parameter 字段，增加选项 3=聚水潭。

步骤 2：后端表单构建修改

修改 app/services/system/config/SystemConfigServices.php 文件。

1. 引入新字段： 在 thirdPartyFormBuild 方法中，将新字段名加入 getConfigAllField 调用列表。

   $data = $this->getConfigAllField([
       ..., 'jushuitan_app_key', 'jushuitan_app_secret', 'jushuitan_access_token'
   ]);
   

2. 更新表单结构： 在 logistics_type 的 radio 组件中增加新的选项控制逻辑。

   ->option('物流查询', [
       Build::radio('logistics_type', ...)->control(3, [
           Build::input('jushuitan_app_key', ...)->info('聚水潭 App Key'),
           Build::input('jushuitan_app_secret', ...)->info('聚水潭 App Secret'),
           Build::input('jushuitan_access_token', ...)->info('聚水潭 Access Token (或通过授权接口自动获取)')
       ])->options(...)
   ])
   

步骤 3：业务逻辑实现

修改 app/services/other/ExpressServices.php 文件。

1. 扩展查询逻辑： 在 query 方法的 switch 语句中增加 case 3 分支。

   case 3: // 聚水潭
       // 调用聚水潭查询接口
       $result = $this->queryJushuitan($expressNum);
       // 格式化返回数据
       break;
   

2. 实现具体查询方法： 添加 queryJushuitan 私有方法。

   • 签名生成：根据聚水潭文档规则生成 sign。
   • 接口调用：发送 HTTP POST 请求到聚水潭 API (如 https://openapi.jushuitan.com/open/logistics/trace/search，具体以文档为准)。
   • 数据解析：解析返回的 JSON 数据，提取物流轨迹信息。