229 lines
6.1 KiB
Markdown
229 lines
6.1 KiB
Markdown
# 天远查车询功能实现说明
|
||
|
||
## 功能概述
|
||
实现了一个完整的工具查询系统，包含11个实用工具，用户可以通过首页点击工具进行查询。
|
||
|
||
## 后端实现
|
||
|
||
### 1. 配置和类型定义
|
||
|
||
#### 配置文件更新
|
||
- `config/config.go`: 添加了 `TianxingjuheConfig` 结构体和 `Tianxingjuhe` 字段
|
||
- `etc/main.yaml` 和 `etc/main.dev.yaml`: 添加了天行聚合API配置
|
||
|
||
#### 类型定义
|
||
- `types/types.go`: 添加了工具相关类型
|
||
- `ToolInfo`: 工具信息结构
|
||
- `ToolboxListResp`: 工具列表响应
|
||
- `ToolboxQueryReq`: 工具查询请求
|
||
- `ToolboxQueryResp`: 工具查询响应
|
||
|
||
### 2. 天行聚合API客户端
|
||
|
||
#### 文件结构
|
||
- `service/tianxingjuhe_sdk/client.go`: 天行聚合API客户端实现
|
||
|
||
#### 功能特性
|
||
- 支持GET和POST请求
|
||
- 自动添加API密钥
|
||
- 统一的响应处理
|
||
- 错误处理机制
|
||
|
||
### 3. 工具箱服务
|
||
|
||
#### 文件结构
|
||
- `service/toolboxService.go`: 工具箱服务核心实现
|
||
|
||
#### 工具列表（11个工具）
|
||
1. **IP地址查询** (ip-location)
|
||
- 查询IP地址归属地、运营商等信息
|
||
- 支持ipv4和ipv6
|
||
- 内网IP自动识别
|
||
|
||
2. **身份证归属地** (idcard-info)
|
||
- 查询身份证归属地、性别、出生日期等信息
|
||
- 校验身份证有效性
|
||
- 计算年龄
|
||
|
||
3. **手机号归属地** (phone-location)
|
||
- 查询手机号码归属地、运营商等信息
|
||
|
||
4. **北京时间查询** (beijing-time)
|
||
- 获取当前北京时间
|
||
- 不需要输入参数
|
||
|
||
5. **银行卡识别** (bank-card)
|
||
- 识别银行卡发卡行与卡种
|
||
|
||
6. **车牌号解析** (plate-parse)
|
||
- 解析车牌类型与归属地
|
||
|
||
7. **金额大写转换** (money-to-chinese)
|
||
- 阿拉伯数字转中文大写金额
|
||
|
||
8. **密码强度检测** (password-strength)
|
||
- 检测密码安全性并给出建议
|
||
|
||
9. **日期间隔计算** (days-between-dates)
|
||
- 计算两个日期相差的天数
|
||
|
||
10. **文件大小格式化** (file-size-format)
|
||
- 字节数转为 KB / MB / GB
|
||
|
||
11. **文本字数统计** (text-stats)
|
||
- 统计字符数、单词数、行数
|
||
|
||
### 4. API接口
|
||
|
||
#### 路由配置
|
||
- `handler/routes.go`: 添加了工具箱相关路由
|
||
- `GET /api/v1/toolbox/list`: 获取工具列表
|
||
- `POST /api/v1/toolbox/query`: 执行工具查询
|
||
|
||
#### Handler实现
|
||
- `handler/toolbox/toolboxlisthandler.go`: 工具列表接口
|
||
- `handler/toolbox/toolboxqueryhandler.go`: 工具查询接口
|
||
|
||
#### Logic实现
|
||
- `logic/toolbox/toolboxlistlogic.go`: 工具列表业务逻辑
|
||
- `logic/toolbox/toolboxquerylogic.go`: 工具查询业务逻辑
|
||
|
||
### 5. 服务上下文注册
|
||
|
||
#### 文件更新
|
||
- `svc/servicecontext.go`:
|
||
- 导入天行聚合SDK包
|
||
- 添加 `TianxingjuheService` 字段
|
||
- 初始化天行聚合客户端实例
|
||
- 注册到服务上下文
|
||
|
||
## 前端实现
|
||
|
||
### 1. 工具配置
|
||
|
||
#### 文件结构
|
||
- `config/toolboxRegistry.js`: 工具配置注册表
|
||
|
||
#### 配置内容
|
||
每个工具配置包含：
|
||
- `key`: 工具唯一标识
|
||
- `name`: 工具名称
|
||
- `desc`: 工具描述
|
||
- `icon`: 图标类名（使用carbon图标库）
|
||
- `fields`: 输入字段配置
|
||
- `validate`: 表单验证函数
|
||
- `validateMsg`: 验证失败提示信息
|
||
- `resultLabels`: 结果展示字段映射
|
||
|
||
### 2. 首页集成
|
||
|
||
#### 文件更新
|
||
- `pages/index.vue`:
|
||
- 添加了"天远查车询"卡片
|
||
- 显示所有11个工具
|
||
- 点击工具跳转到查询页面
|
||
- 添加了自定义图标样式
|
||
|
||
### 3. 工具查询页面
|
||
|
||
#### 文件结构
|
||
- `pages/toolbox/query.vue`: 工具查询页面
|
||
|
||
#### 功能特性
|
||
- 动态表单生成（支持text、digit、date、textarea等类型）
|
||
- 表单验证
|
||
- 自动查询（无需输入参数的工具）
|
||
- 结果展示
|
||
- 错误处理
|
||
- 加载状态
|
||
|
||
#### 支持的字段类型
|
||
- `text`: 普通文本输入
|
||
- `digit`: 数字输入
|
||
- `idcard`: 身份证号输入
|
||
- `date`: 日期选择器
|
||
- `textarea`: 多行文本输入
|
||
|
||
### 4. API调用
|
||
|
||
#### 文件结构
|
||
- `api/toolbox.js`: 工具箱API封装
|
||
|
||
#### 接口函数
|
||
- `postToolboxQuery(toolKey, params)`: 执行工具查询
|
||
|
||
## 使用流程
|
||
|
||
### 用户使用流程
|
||
1. 打开首页
|
||
2. 看到"天远查车询"卡片
|
||
3. 点击任意工具图标
|
||
4. 跳转到工具查询页面
|
||
5. 填写表单（如需）
|
||
6. 点击"立即查询"按钮
|
||
7. 查看查询结果
|
||
|
||
### 数据流程
|
||
1. 前端调用 `/api/v1/toolbox/list` 获取工具列表
|
||
2. 用户选择工具后调用 `/api/v1/toolbox/query` 执行查询
|
||
3. 后端根据 toolKey 分发到对应的处理函数
|
||
4. 处理函数执行查询逻辑（可能调用第三方API）
|
||
5. 返回查询结果
|
||
6. 前端展示结果
|
||
|
||
## 技术特点
|
||
|
||
### 后端特点
|
||
- 统一的工具接口设计
|
||
- 工具处理器注册表模式
|
||
- 灵活的参数传递（map[string]interface{}）
|
||
- 完善的错误处理
|
||
- 支持第三方API集成（天行聚合）
|
||
|
||
### 前端特点
|
||
- 动态表单生成
|
||
- 类型安全的TypeScript
|
||
- 响应式UI设计
|
||
- 统一的错误处理
|
||
- 良好的用户体验
|
||
|
||
## 扩展指南
|
||
|
||
### 添加新工具
|
||
|
||
#### 后端步骤
|
||
1. 在 `toolboxService.go` 中添加处理函数
|
||
2. 在 `toolProcessors` 映射中注册新工具
|
||
3. 在 `ListTools()` 方法中添加工具信息
|
||
|
||
#### 前端步骤
|
||
1. 在 `toolboxRegistry.js` 中添加工具配置
|
||
2. 定义字段配置和验证规则
|
||
3. 定义结果展示字段映射
|
||
|
||
## 注意事项
|
||
|
||
1. **API密钥管理**: 天行聚合API的密钥已配置，请在生产环境中使用真实的API密钥
|
||
2. **错误处理**: 所有工具都有完善的错误处理机制
|
||
3. **表单验证**: 前端和后端都有验证，确保数据安全
|
||
4. **性能优化**: 工具查询响应时间已优化，建议在3秒内完成
|
||
5. **用户体验**: 无需输入参数的工具会自动查询，提升用户体验
|
||
|
||
## 测试建议
|
||
|
||
1. 测试每个工具的输入验证
|
||
2. 测试错误处理（如格式错误的输入）
|
||
3. 测试网络异常情况
|
||
4. 测试边界情况（如最大长度、特殊字符等）
|
||
5. 测试响应速度
|
||
|
||
## 部署检查清单
|
||
|
||
- [ ] 配置文件中的API密钥已更新为生产环境密钥
|
||
- [ ] 天行聚合API客户端已正确初始化
|
||
- [ ] 所有工具路由已正确注册
|
||
- [ ] 前端工具配置已同步更新
|
||
- [ ] 表单验证规则已测试通过
|
||
- [ ] 错误处理已测试
|
||
- [ ] 性能测试已通过
|