team/tyc-server-v2
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
tyc-server-v2/docs/toolbox_implementation.md
Mrx e29e0f4d0f f
2026-05-25 10:54:17 +08:00

6.1 KiB
Raw Permalink Blame History

天远查车询功能实现说明

功能概述

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