# 在线工具箱（tool.xpcool.com）

纯前端在线工具站：**Vite + Vue3 + Pinia + TypeScript + UnoCSS + TDesign**。14 个常用工具，所有文件处理与计算均在浏览器本地完成，**不上传任何用户数据到服务器**。

## 功能特性

- 14 个实用工具：图片压缩/裁剪、二维码生成解析、JSON 格式化、时间戳转换、Base64 编解码、JWT 解析、Cron 表达式、进制转换、哈希计算、身份证解析、地址解析、URL 解析、图片 OCR 识别
- 左侧固定导航 + 中间内容区；PC Web 与移动端 H5 响应式适配（移动端为抽屉导航）
- 暗黑 / 浅色主题切换，选择持久化，刷新不丢失
- 每个工具独立路由、独立本地历史记录（localStorage）
- 所有文件上传支持点击选择 + 拖拽上传，图片自动缩略图回显；图片压缩支持批量、按质量/限制大小、等比缩放与 ZIP 批量下载
- 通用组件：拖拽上传、复制按钮、下载按钮、错误提示、历史记录面板
- 全部能力由浏览器原生 API、WebAssembly 与 npm 前端库实现，无任何 mock 后端接口、无 CDN 脚本引入

## 技术栈

| 类别 | 选型 |
| --- | --- |
| 构建 | Vite 6 + pnpm |
| 框架 | Vue 3（`<script setup>` 组合式 API） |
| 语言 | TypeScript（strict） |
| 状态 | Pinia |
| UI | TDesign Vue Next + tdesign-icons-vue-next |
| 样式 | UnoCSS 原子类 + SCSS（使用 TDesign 设计令牌变量） |
| 路由 | Vue Router 4（History 模式） |

工具依赖：`qrcode`、`jsqr`、`cropperjs`、`browser-image-compression`、`tesseract.js`、`cron-parser`、`spark-md5`、`jszip`（全部通过 npm 安装）。

## 快速开始

要求：Node.js ≥ 18，pnpm ≥ 8。

```bash
# 1. 安装依赖
pnpm install

# 2. 启动开发服务器（默认 http://localhost:5173）
pnpm dev

# 3. 类型检查
pnpm type-check

# 4. 生产构建（输出到 dist/）
pnpm build

# 5. 本地预览构建产物
pnpm preview
```

## 页面路由

| 路由 | 工具 |
| --- | --- |
| `/` | 首页（工具卡片导航） |
| `/image-compress` | 图片压缩 |
| `/image-cropper` | 图片裁剪 |
| `/qrcode` | 二维码生成 / 解析 |
| `/json-format` | JSON 格式化 |
| `/timestamp` | 时间戳转换 |
| `/base64` | Base64 编解码 |
| `/jwt-parse` | JWT 解析 |
| `/cron` | Cron 表达式工具 |
| `/radix-convert` | 进制转换 |
| `/hash` | 哈希计算 |
| `/idcard` | 身份证解析 |
| `/address-parse` | 地址解析 |
| `/url-parse` | URL 解析 |
| `/ocr` | 图片 OCR 识别 |

## 目录结构

```
├── index.html                  # 入口 HTML（含防闪烁主题脚本）
├── package.json
├── vite.config.ts              # Vite 配置（别名、分包）
├── unocss.config.ts            # UnoCSS 配置（快捷类）
├── tsconfig.json / tsconfig.node.json
└── src/
    ├── main.ts                 # 应用入口（TDesign 全量注册、主题初始化）
    ├── App.vue
    ├── env.d.ts
    ├── assets/styles/          # 全局样式（TDesign 令牌变量）
    ├── router/
    │   ├── index.ts            # 路由表（由注册表生成）
    │   └── tools.ts            # ★ 工具注册表（唯一数据源）
    ├── stores/theme.ts         # 主题状态（Pinia）
    ├── composables/
    │   ├── useHistory.ts       # 本地历史记录
    │   ├── useClipboard.ts     # 剪贴板复制
    │   └── useDownload.ts      # 本地文件下载
    ├── components/common/      # UploadDrop / CopyButton / DownloadButton / ErrorAlert / HistoryPanel
    ├── layout/                 # MainLayout（响应式布局）+ SideNav（侧边导航）
    ├── utils/index.ts          # 通用工具函数
    └── views/                  # 首页 + 14 个工具页面（每个工具一个目录）
```

## 部署

构建产物为纯静态文件，托管到任意静态服务器或 OSS/CDN 即可。使用 History 路由需配置回退（以 Nginx 为例）：

```nginx
location / {
  root /usr/share/nginx/html;
  index index.html;
  try_files $uri $uri/ /index.html;
}
```

## 隐私说明

所有计算均在浏览器本地完成：图片压缩/裁剪/OCR 使用本地 Canvas/WASM，哈希使用本地 Web Crypto 与 spark-md5，历史记录仅存于本机 localStorage。项目不包含任何后端接口调用，用户文件永远不会离开浏览器。

## OCR 语言包说明

OCR 的引擎代码（worker + wasm）已随 npm 依赖打包进产物；语言数据属于运行时资源，默认从官方语言包源加载（首次识别约 20MB，浏览器会缓存）。如需完全离线部署：下载 `chi_sim.traineddata.gz` 与 `eng.traineddata.gz` 放入 `public/traineddata/`，并将 `src/views/ocr/OcrView.vue` 中的 `LANG_PATH` 改为 `${window.location.origin}/traineddata`。

## 维护与扩展

新增工具、修改架构、排查问题的完整说明见 [agents.md](./agents.md)。