xpcool/tool.xpcool.com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1ff576c704
tool.xpcool.com/docs/PROJECT_STATE.md
夏犀麟 954b9e9d8a
All checks were successful
Build and Deploy (tool.xpcool.com) / build-and-deploy (push) Successful in 1m1s
Details
feat(router): 新增多个工具分类和路由配置 
- 添加 TerminalIcon, GitBranchIcon, ApiIcon, BrushIcon, SoundIcon,
Table1Icon, LogoGithubIcon, ContrastIcon, Edit2Icon, ChartBarIcon,
EarthIcon, GitMergeIcon, SettingIcon, CurrencyExchangeIcon, MobileIcon,
WifiIcon, RocketIcon 等图标导入
- 新增 dev, design, health, study, travel, fun, online 七个工具分类
- 添加 SQL格式化、文本对比、JSON转代码、渐变生成器、占位图生成、
ASCII艺术、摩斯电码、正则可视化、Markdown表格、API构建器、
Gitignore生成器、代码转图片、颜色命名器、缩进转换、代码统计、
Hello World大全、JSON对比、环境变量解析、汇率换算、快递查询、
手机号归属地、IP信息查询、网络测试、网络测速等多个工具路由配置
- 新增 .env.example 配置文件模板
- 创建 docs/api-contract.md 后端接口契约文档
- 新增 api-builder 和 ascii-art 工具页面组件
- 更新 agents.md 添加接手必读指引和维护约定
- 创建 CHANGELOG.md 变更日志文档和工作日志记录
2026-08-24 22:11:12 +08:00

7.3 KiB
Raw Blame History

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