tyc-server-v2/docs/toolbox_implementation.md

# 天远查车询功能实现说明

## 功能概述
实现了一个完整的工具查询系统，包含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客户端已正确初始化
- [ ] 所有工具路由已正确注册
- [ ] 前端工具配置已同步更新
- [ ] 表单验证规则已测试通过
- [ ] 错误处理已测试
- [ ] 性能测试已通过