# 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 确认存在）