tool.xpcool.com/docs/CHANGELOG.md

CHANGELOG — 项目变更日志

记录每次请求/变更，倒序排列（最新在上）。 与 docs/PROJECT_STATE.md 配合使用：本文件回答「改了什么」，状态文档回答「现在是什么样」。

---

2026-09-14 第六批：视觉重设计 + 中英日韩四语言 + 昼夜主题 + 服务端接口对接

依据 design-taste-frontend 技能（BRIEF INFERENCE / 单一强调色 / 形状一致性 / 反 AI-slop 清单）重建全站视觉体系， 并一次性补齐多语言、主题切换与 5 个已上线服务端接口的对接。构建通过（vue-tsc --noEmit + vite build，33.88s）。

🎨 视觉体系重建（令牌 → TDesign 桥接，60+ 页面自动生效）

• 新增 src/assets/styles/tokens.scss：全站唯一视觉真相源。冷调石板灰中性色阶 + 青玉 Jade 单一强调色 （浅色 #0c7c59 对比 5.19:1 / 深色 #3fc79b 对比 8.85:1，均过 WCAG AA）；统一圆角规范 （xs4/sm6/md8/lg10/xl14/2xl20/pill999）、8px 间距节奏、字号阶梯、z-index 分层规范、动效曲线与时长； 按语言切换的字体栈（html[lang^='zh'|'ja'|'ko'|'en']，注意必须前缀匹配，lang 写的是完整标签）。
• 新增 src/assets/styles/tdesign-theme.scss：把 --tk-* 映射到 --td-*，重定义品牌色阶、语义色阶、 完整冷调灰阶（--td-gray-color-1..14，浅深共用）、圆角、阴影、滚动条。收益：60+ 未改动的工具页 零成本继承新配色与圆角，这是本次能低风险铺开全站的关键。
• 重写 index.scss：每页只过渡颜色（不碰 transform/布局）、统一 :focus-visible 焦点环、 .skip-to-content、滚动条 background-clip: content-box、标题字重 650 + letter-spacing:-0.02em、 prefers-reduced-motion 降级。
• 新增 src/directives/reveal.ts：v-reveal 滚动进入动效（全局单例 IntersectionObserver，传数字做错峰）。
• unocss.config.ts shortcuts 全部改为令牌驱动，panel 补上内边距（此前 ApiStatus/RandomString/Hash 等 新建页出现内容贴边）——注意页面 scoped 样式（.block[data-v-*]）权重高于该快捷类。

🧭 布局外壳重构

• MainLayout.vue 完全重写：毛玻璃 sticky 顶栏（backdrop-filter: blur(14px) saturate(180%)）+ 三区布局， 品牌区改用 TDesign AppIcon 而非手绘 SVG，全站唯一一处渐变（青玉 → #2fb98d）。
• 新增 CommandPalette.vue 命令面板（⌘K / Ctrl+K，按 UA 显示对应提示）：Teleport 到 body、 扁平结果列表 + 分类标签、↑↓/Enter/Esc 键盘导航、鼠标 hover 同步高亮、打开时锁 body 滚动。
• SideNav.vue 重写：内联筛选框、可折叠分组（tool-nav-collapsed 持久化）、活动态青玉底纹 + 左侧 2px 指示条、nav-dot 标记需联网工具。
• 新增 LocaleSwitch.vue（显示 ZH/EN/JA/KO 而非国旗，避免语言与国家绑定歧义）、 ThemeSwitch.vue（三态，图标显示实际生效的 mode、菜单勾选用户偏好 preference）。

🌏 多语言（中/英/日/韩）

• 引入 vue-i18n 11.4.10（legacy: false + globalInjection: true），基线语言 zh-CN。
• 新增 src/i18n/index.ts（SUPPORTED_LOCALES / normalizeLocale() / resolveInitialLocale() / applyLocaleToDocument() / setAppLocale()）、src/i18n/helpers.ts（toolName/toolDesc/categoryLabel/tOr 等带中文兜底的取词助手）、src/stores/locale.ts。
• 四份完整语言包 src/i18n/locales/{zh-CN,en-US,ja-JP,ko-KR}.ts：app / nav / palette / theme / locale / home / category / tool（58 个工具名与描述全译） / page / pending / common。
• 新增 src/components/common/BackendPending.vue：用中性信息态（非 t-alert 错误色）如实说明 「前端已就绪、后端接口尚未上线」，不伪装成可用。
• index.html 重写防闪烁内联脚本（同步执行，解析主题 auto + 语言归一化），与 theme store、i18n index 三处逻辑必须同步；theme-mode 属性 + 明暗两套 theme-color meta。

🔌 服务端接口对接（service.xpcool.com /api/service/open/tools/*）

• 新增 src/api/openTools.ts：接口元数据（OPEN_TOOL_ENDPOINTS，供「接口状态」页探测）与调用函数 共用同一份路径定义，避免改路径忘了改探测列表。5 个接口实测线上 全部 HTTP 200。
• src/api/client.ts 重写：BASE_URL 回落到 https://service.xpcool.com（不建 .env 也能用）； 新增 AbortController 超时（10s）、describeStatus() 状态码中文翻译（404 → 「接口尚未上线」）、 区分超时与网络不可达。
• 改造 6 个页面接入真实后端（均为「本机 / 服务端」双模式，默认本机、不自动打网络请求）：
  • ip-info：服务端识别的来源 IP + 内网判定，另附本机环境（时区/语言/平台/屏幕/UA）。 后端不返回归属地，界面如实说明，不做前端猜测。
  • uuid：本机 RFC 4122 v4 / 服务端 GoFrame guid，服务端模式并发 n 次（接口一次只返一个）。
  • random-string（新工具）：本机 Web Crypto（已注明取模偏置量级约 2^-26）/ 服务端 crypto/rand， 长度 1-128，服务端模式数量上限压到 10。
  • api-status（新工具）：串行探测 5 个接口（并发会干扰延迟读数）， performance.now() 计时、500ms 封顶刻度条、状态点承载真实语义、窄屏表格转卡片。
  • hash：新增「同时用服务端计算 MD5」开关（默认关闭——算哈希是高频纯本地动作， 不该每次点击都多一次网络往返），做两端口径对比，比对统一折小写。
  • timestamp：新增服务端时钟卡片，偏移量基于 Unix 秒（与时区无关）并补偿半个往返耗时， 误差上界 rtt/2；偏差 > 2s 提示本机时钟可能不准。
• 未实现接口的工具页（exchange-rate / express-query / phone-locate / network-test / speed-test） 统一改用 <BackendPending />，去掉「后端未就绪就禁用按钮」的旧逻辑。

🧹 修复

• 空分类渲染缺陷：health / study / travel 三个分类无任何工具，却仍渲染出空区块与空标题。 现分类精简为 6 个（work / dev / design / life / fun / online），groupedTools() 过滤空分组。
• SideNav.vue 在 <script setup> 末尾 import（ESM 提升但不规范）、IpInfoView.vue 漏 onBeforeUnmount 导入、HomeView.vue 从 @/api/openTools 错误导入 SUPPORTED_LOCALES —— 均已修正。

📄 备案号

• 新增 src/config.ts 集中管理站点级常量，页脚展示 黔ICP备2026003933号 并链接工信部核验入口 （备案号单列一行——它是监管信息，不与产品承诺混在同一组）。
• ⚠️ 该值必须与主站 xpcool.com 的 src/config.ts 的 SITE.icp 保持一致，换号时两处一起改。

📚 文档

• docs/api-contract.md 按线上实际部署重写：旧版是一份 /api/tools/* 的待实现清单，与实际不符。 现明确区分「已实现 5 个」（含请求/响应字段、错误语义、前端封装函数名）与「待实现 5 个」。
• .env.example 补充默认基址说明；docs/PROJECT_STATE.md 同步更新。

2026-08-24 第五批：删除 5 个工具（60 → 55）

🗑 删除工具（页面目录 + 注册条目 + 相关契约全部清除）

• code-minify 代码压缩美化（dev）
• lucky-wheel 抽奖转盘（fun）
• slogan-generator 文案生成器（fun）
• weather 天气预报（online）—— api-contract 第 1 节一并删除
• stock-quote 股票行情（online）—— api-contract 第 4 节一并删除

🧹 清理

• tools.ts 删除对应条目及无引用图标（StarIcon / SmileIcon / EditIcon / CloudyDayIcon；ChartIcon 因 word-count 仍使用而保留）
• api-contract.md 接口一览更新为 7 个：exchange-rate / express-query / phone-locate / ip-info / network-test / speedtest-download / speedtest-upload
• 删除方式备忘：项目内 rm 触发沙箱 trash 保护（genie-trash 失败），改用 mv 到系统临时目录（$TMPDIR/tool-deleted-*）实现移除

2026-08-24 第四批：网络测速工具（59 → 60）

🆕 新增工具

• speed-test 网络测速（online 分类，图标 RocketIcon）：
  • 下载测速：流式读取计时（后端测速源 / 公网源 / 自定义 URL 三模式），实时进度与峰值速度，5/10/25/50MB
  • 上传测速：生成随机数据上传，后端计时优先（POST /api/tools/speedtest/upload），1/5/10MB
  • 延迟测试：5/10 次 RTT 采样，平均/最小/最大/抖动 + 等级
• 契约新增第 8 节：下载测速返回随机二进制流（带 Content-Length）、上传测速返回 {bytes, duration_ms, speed_mbps}
• src/api/client.ts 导出 BASE_URL（测速工具直接拼流式地址）

2026-08-24 第三批：网络测试工具 + 上下文无缝切换机制

🆕 新增工具

• network-test 网络测试（online 分类）：HTTP 站点检测（前端直连，测 DNS/TTFB/状态/大小）+ Ping / TCP 端口 / DNS 解析（后端模式），后端契约见 api-contract.md 第 7 节

🏗 机制

• 新增 docs/PROJECT_STATE.md：项目状态与交接文档（单点真相），新账号 AI 接手必读
• 新增 docs/CHANGELOG.md：本文件，每次变更必记录
• AGENTS.md 顶部新增「接手必读」指引，指向上述两份文档与 api-contract.md —— 实现跨 CodeBuddy 账号无缝接续
• 约定：任何后续变更必须同步更新 CHANGELOG.md / PROJECT_STATE.md / 工作日志

2026-08-24 第二批：分类重构 + 后端预留机制 + 编程工具全系（40 → 58）

🏗 分类

• 分类重构为 9 个：新增 health 健康生活 / study 学习办公 / travel 旅行出行 / online 在线服务（后端预留）

🆕 后端预留（6）

• src/api/client.ts 统一 API 客户端（VITE_API_BASE 配置，未配置降级提示，统一响应 {code,message,data}）
• docs/api-contract.md 接口契约文档（weather / exchange-rate / express-query / stock-quote / phone-locate / ip-info）
• 6 个预留页面骨架（UI 完整、字段按契约类型化），.env.example 提供配置模板

🆕 编程工具（12）

• code-minify（JS/CSS/HTML 压缩美化）、regex-visual（正则结构树）、markdown-table、api-builder（fetch/curl）、gitignore-gen、code-to-image（canvas 高亮卡片）、color-namer（148 色表）、indent-convert、code-stats（30+ 语言注释规则）、hello-world（33 语言）、json-diff（路径级）、env-parse

🐛 修复

• Vue 模板 attribute 内 \" 导致编译错误 → 字符串常量移到 script
• json-diff k in b 类型收窄 → 断言为 Record

2026-08-24 第一批：趣味分类与工具（31 → 40）

🏗 分类

• 新增 dev 开发进阶 / design 创意设计 / fun 趣味娱乐

🆕 工具（9）

• dev：sql-format（手写分词 SQL 格式化）、text-diff（LCS 行级 diff）、json-to-code（JSON → TS/Go/Python）
• design：gradient-generator（linear/radial/conic + 12 预设）、placeholder-image（PNG/SVG 占位图）、ascii-art（图片转字符画）
• fun：morse-code（中文走 pinyin-pro + Web Audio 电报声）、lucky-wheel（canvas 转盘动画）、slogan-generator（5 类文案库）

📄 文档

• 新增 docs/tool-ideas.md 工具创意库（现状 + 未来创意 + 进度台账）

🐛 修复

• PaletteIcon 不存在 → 改用 ViewModuleIcon（图标引用前需在 node_modules 确认存在）