# PROJECT_STATE.md — 项目状态与交接文档

> **本文件是项目的「单点真相」（Source of Truth），任何 AI 账号 / 开发者接手项目时，请先读本文件，再读 `CHANGELOG.md` 与 `docs/api-contract.md`，即可无缝接续工作。**
>
> **维护规则（重要）**：每次对本项目做任何实质变更（新增/修改工具、改架构、改契约、修坑），必须同步更新：
> 1. `docs/CHANGELOG.md` —— 追加一条变更记录（倒序，最新在上）
> 2. 本文档 —— 更新工具清单、状态、待办与技术约定
> 3. `.workbuddy/memory/YYYY-MM-DD.md` —— 工作日志

---

## 1. 项目快照

- **名称**：tool.xpcool.com（在线工具箱）
- **形态**：纯前端 SPA，无后端、无 mock。计算与文件处理在浏览器本地完成；「在线服务」分类的工具依赖自建后端（见第 5 节）。
- **技术栈**：Vite 6 + Vue 3（`<script setup>`）+ Pinia + TypeScript（strict）+ UnoCSS + TDesign Vue Next + pnpm（**禁止换 npm/yarn**）
- **常用命令**：`pnpm dev`（开发）/ `pnpm build`（vue-tsc + vite 构建）/ `pnpm type-check`
- **客户端**：PC + 移动端 H5 响应式（`<768px` 侧边栏变抽屉）
- **构建注意**：`pnpm build` 前若 dist 目录文件过多会触发安全删除保护（阈值 50 个/次），先 `mv dist dist.bak-<ts>` 再构建，构建后把备份移走。

## 2. 当前全貌（截至 2026-08-24，共 9 分类 55 个工具）

| 分类 | 数量 | 说明 | 工具（path） |
| --- | --- | --- | --- |
| work 工作效率 | 18 | 开发编程、办公文本与文件处理 | image-compress / json-format / timestamp / base64 / jwt-parse / cron / radix-convert / hash / url-parse / translate / ocr / uuid / regex-test / case-convert / color-convert / yaml-json / word-count / zh-convert |
| dev 开发进阶 | 14 | 格式化、对比、转换与代码工具 | sql-format / text-diff / json-to-code / regex-visual / markdown-table / api-builder / gitignore-gen / code-to-image / color-namer / indent-convert / code-stats / hello-world / json-diff / env-parse |
| design 创意设计 | 3 | 渐变、占位图与字符画 | gradient-generator / placeholder-image / ascii-art |
| life 生活助手 | 13 | 日常计算、查询与决策 | image-cropper / qrcode / idcard / address-parse / unit-convert / rmb-upper / date-calc / password-gen / bmi / mortgage / bill-split / random-decision / pomodoro |
| health 健康生活 | 0 | 睡眠、饮食与身体指标 | ⬜ 待实现（批次 A） |
| study 学习办公 | 0 | 拼音标注、记忆卡片与模板 | ⬜ 待实现（批次 B） |
| travel 旅行出行 | 0 | 出行清单、时差与距离 | ⬜ 待实现（批次 C） |
| fun 趣味娱乐 | 1 | 摩斯电码等小玩具 | morse-code |
| online 在线服务 | 6 | 依赖后端接口 | exchange-rate / express-query / phone-locate / ip-info / network-test / speed-test |

## 3. 架构与关键机制（新增工具前必读）

- **工具注册表** `src/router/tools.ts` 是全站唯一数据源：分类 `toolCategories` + 工具 `tools` 数组，侧边导航/首页/路由全部自动生成。新增工具 = 建页面 + 加一条配置（path/name/desc/icon/category/component 懒加载），**禁止手改路由文件**。
- **历史记录**：`useHistory(key)`，key 约定等于路由 path，localStorage 持久化（`tool-history:<key>`），上限 10 条。
- **主题**：`stores/theme.ts`，自定义样式一律用 `var(--td-*)` 令牌，禁止硬编码颜色。
- **公共组件**：`CopyButton` / `DownloadButton` / `ErrorAlert` / `HistoryPanel` / `UploadDrop`，新页面必须复用。
- **页面样式**：`.page-wrap / .page-title / .page-desc / .tool-section / .result-area` 全局已定义；`.form-actions / .form-row / .code-block` 各页面 scoped 自建。
- **后端请求**：统一走 `src/api/client.ts`（`api.get/post`），响应契约 `{ code, message, data }`，`VITE_API_BASE` 未配置时返回「后端未接入」，页面据此降级。
- **网络测试双模式**：`network-test` 的 HTTP 检测走前端直连（受 CORS 限制），Ping / TCP / DNS 走 `POST /api/tools/network-test`（契约见第 5 节）。
- **网络测速**：`speed-test` 下载测速走流式 fetch（`GET /api/tools/speedtest/download`，三模式：后端/公网/自定义），上传测速走 `POST /api/tools/speedtest/upload`（后端计时优先），延迟测试前端多次采样。

## 4. 待办（按批推进，见 docs/tool-ideas.md 第三部分）

- **批次 A 健康生活（12）**：睡眠周期计算 / 喝水提醒 / 体脂率估算 / 卡路里估算 / 预产期计算 / 房贷提前还款 / 生理周期记录 / 运动配速计算 / BMI 对比表 / 热量平衡 / 理想体重 / 步数时长换算
- **批次 B 学习办公（10）**：汉字拼音标注（pinyin-pro 已依赖）/ 单词记忆卡 / 随机口算题 / 乘法表练习 / 请假条生成器 / 会议纪要模板 / 邮件模板 / 公文格式助手 / 学习计划表 / 名言摘抄本
- **批次 C 旅行出行（6）**：行李清单 / 机票折扣速算 / 签证材料清单 / 地图距离估算（Haversine）/ 时差换算 / 小费计算器
- **批次 D 创意设计补全（9）**：阴影生成器 / 圆角生成器 / 调色板生成 / 颜色对比度检查 / 像素画编辑器 / 纹理生成器 / 文字效果生成 / Emoji 放大镜 / 图片九宫格切图
- **批次 E 趣味娱乐补全（14）**：加密暗号机 / Emoji 密文 / 藏头诗生成 / 绕口令生成器 / 塔罗牌占卜 / 星座运势 / 名字评分 / 电子木鱼 / 猜成语小游戏 / 音效合成器 / 节日倒计时 / 情侣默契问答 / 名言警句生成 / 骰子塔

## 5. 后端契约（用户正在开发后端服务）

- 契约文档：`docs/api-contract.md`（7 个接口：exchange-rate / express-query / phone-locate / ip-info / network-test / speedtest-download / speedtest-upload）
- 前端已按契约类型化，后端按文档实现即可直接对接，**前端零改动**。
- 接入方式：复制 `.env.example` 为 `.env`，填 `VITE_API_BASE`。

## 6. 技术约定与坑（跨会话必须记住）

- **TDesign 图标**：引用前先在 `node_modules/tdesign-icons-vue-next/esm/components/` 确认存在（如 `PaletteIcon` 不存在，只有 `Palette1Icon`）。
- **Vue 模板 attribute**：内嵌字符串不能直接写 `\"`（HTML 解析器会把 `"` 当属性结束符导致编译错误），字符串常量移到 `<script>` 定义。
- **`in` 运算符**：`k in obj` 中 obj 需先断言为 `Record<string, unknown>`，否则 strict 模式 TS2638/TS18048。
- **构建安全删除保护**：`pnpm build` 清理 dist 会触发沙箱批量删除拦截（>50 文件），先 `mv dist dist.bak-<ts>` 再构建。
- **大整数**：进制转换等工具禁用 `parseInt/Number`，用 BigInt 逐位解析（现有 radix-convert 已实现）。
- **暗黑模式**：所有颜色用 `--td-*` 令牌；canvas 绘制注意主题切换（尽量用令牌色或中性色）。

## 7. 给下一个 AI 的接手清单

1. 读本文件（状态全貌）→ `CHANGELOG.md`（最近的变更）→ `docs/api-contract.md`（后端契约）
2. 运行 `pnpm type-check` 确认基线
3. 如需继续实现工具：从第 4 节待办批次挑一批，按 `docs/tool-ideas.md` 的工具描述实现
4. 完成后：更新 CHANGELOG.md + 本文件 + `.workbuddy/memory/YYYY-MM-DD.md`