## 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` 表中添加聚水潭相关的配置项。
参考文档：[聚水潭开放平台 - 第三方授权](https://openweb.jushuitan.com/dev-doc?docType=5&docId=25)

*   **操作**：插入新记录。
    *   `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` 调用列表。
    ```php
    $data = $this->getConfigAllField([
        ..., 'jushuitan_app_key', 'jushuitan_app_secret', 'jushuitan_access_token'
    ]);
    ```

2.  **更新表单结构**：
    在 `logistics_type` 的 `radio` 组件中增加新的选项控制逻辑。
    ```php
    ->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` 分支。
    ```php
    case 3: // 聚水潭
        // 调用聚水潭查询接口
        $result = $this->queryJushuitan($expressNum);
        // 格式化返回数据
        break;
    ```

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