# ToolBox

在线开发者工具箱：JSON 格式化、文本/JSON 对比、编解码、变量名转换、二维码、时间戳、颜色转换等。

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

## 功能

| 工具 | 路径 | 说明 |
|------|------|------|
| JSON | `/json-formatter` | 格式化、压缩、转义、JSONPath 筛选、树形视图 |
| 对比 | `/comparator` | 文本行/字符 diff、JSON 结构对比 |
| 编解码 | `/encoder-decoder` | Base64、URL、Unicode、Zlib |
| 变量名 | `/variable-name` | camelCase / PascalCase / snake_case 等 |
| 二维码 | `/qr-code` | 文本生成二维码 |
| 时间戳 | `/timestamp-converter` | 秒/毫秒/纳秒与时间字符串互转 |
| 颜色 | `/color-converter` | RGB / HEX / HSL 互转 |

## 快速开始

### 前置要求

- Node.js >= 18
- npm

### 安装与运行

```bash
git clone https://git.rc707blog.top/rose_cat707/ToolBox.git
cd ToolBox
npm install
npm run dev
```

开发服务器默认 `http://localhost:3000`。

### 构建

```bash
npm run build    # 产物输出到 dist/
npm run preview  # 预览生产构建
```

### 测试

```bash
npm run test:run
```

## 环境变量

站点标题与备案号可通过环境变量配置，复制 `.env.example` 为 `.env` 后修改：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `VITE_APP_TITLE` | 站点标题（导航栏、浏览器标签） | `ToolBox` |
| `VITE_APP_ICP` | 备案号（留空则不显示） | （空） |
| `VITE_GA_MEASUREMENT_ID` | Google Analytics 测量 ID（留空禁用） | （空，不上报） |
| `VITE_JINRISHICI_SDK_URL` | 今日诗词 SDK 地址（留空禁用） | （空，不加载） |

### Docker

**构建时**指定（写入静态资源默认值）：

```bash
docker build \
  --build-arg VITE_APP_TITLE="我的工具箱" \
  --build-arg VITE_GA_MEASUREMENT_ID="G-XXXXXXXXXX" \
  -t toolbox:latest .
```

**运行时**覆盖（无需重新构建，容器启动时生成 `config.js`）：

```bash
docker run --rm -p 8080:80 \
  -e APP_TITLE="我的工具箱" \
  -e APP_ICP="" \
  -e APP_GA_MEASUREMENT_ID="" \
  toolbox:latest
```

`APP_ICP` 设为空字符串时，首页不显示备案号。

## Docker 部署

```bash
docker build -t toolbox:latest .
docker run --rm -p 8080:80 toolbox:latest
```

访问 `http://localhost:8080`。

CI 会在 push 到 main/master 时自动构建并推送镜像到 Gitea Container Registry，详见 [`.gitea/README.md`](./.gitea/README.md)。

## 项目结构

```
ToolBox/
├── src/
│   ├── views/           # 页面组件
│   ├── utils/           # 可测试的业务逻辑
│   ├── composables/     # Vue composables
│   ├── components/      # 公共组件
│   └── router/          # 路由
├── tests/               # Vitest 单元测试
├── deploy/              # Nginx 配置
├── Dockerfile
└── .gitea/workflows/    # CI 流水线
```

## 添加新工具

1. 在 `src/views/` 创建 Vue 组件
2. 在 `src/router/index.js` 添加路由
3. 在 `src/App.vue` 导航栏添加入口
4. 在 `src/views/Home.vue` 的 `tools` 数组中注册
5. 如有纯逻辑，提取到 `src/utils/` 并补充测试

## 自部署说明

- **Google Analytics**：通过 `VITE_GA_MEASUREMENT_ID` / `APP_GA_MEASUREMENT_ID` 启用；默认关闭，不向 Google 上报数据
- **今日诗词**：通过 `VITE_JINRISHICI_SDK_URL` / `APP_JINRISHICI_SDK_URL` 启用；默认关闭，不加载第三方 SDK
- **deploy.sh**：作者自用 SSH 部署脚本，内含固定远程路径，使用前请修改 `REMOTE_DIR`

## 第三方依赖

主要依赖及许可证见 [NOTICE](./NOTICE)。Font Awesome 图标需保留其版权声明。

## 贡献

欢迎提交 Issue 和 Pull Request，请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。

## 安全

发现安全漏洞请私下报告，详见 [SECURITY.md](./SECURITY.md)。

## 许可证

[MIT License](./LICENSE) © 2026 renjue