Karlcarlo
c9a98f342c
添加大量图片、字体、音频等静态资源文件，包括用户界面图片、模板文件和安装界面素材 添加系统版本配置文件(.version)和常量定义文件(.constant) 更新供应商依赖文件，包括Symfony VarDumper组件和相关许可证文件 添加验证码配置文件(captcha.php)和.gitignore规则
74 lines
3.1 KiB
Markdown
74 lines
3.1 KiB
Markdown
|
||
## 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 数据，提取物流轨迹信息。
|