# CHANGELOG — 项目变更日志

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

---

## 2026-09-14 第八批：修「字太小」+ 换风格为「清晰蓝 · 卡片工作台」+ 补上 UI 库主题控制

> 用户反馈：① 界面字体、下拉与功能控件都太小；② 再换一种风格；③ UI 库（TDesign）的主题此前没有真正接上，
> 需要用主题变量控制组件的色彩与风格。
> 三者一并处理：换主色与密度（风格）→ 放大令牌与控件（太小）→ 用 `--td-comp-*` / `--td-font-*` 接管 TDesign 尺度（主题控制）。
> 构建通过（`vue-tsc --noEmit` + `vite build`，22.86s）。

### ⚠️ 本轮挖出的头号坑：`theme-mode` 选择器权重
TDesign 的浅/深色变量声明在 `:root[theme-mode='light'|'dark']`（权重 0,2,0），
而上一版我们写的是 `html[theme-mode='dark']`（0,1,1）—— 生产构建里即便我们的 CSS 排在 vendor CSS 之后，
**仍会被 UI 库的深色变量盖掉**。表现：深色下卡片/输入框用回 TDesign 自带灰（卡片 `#242424`、描边 `#ddd`）。
**修复：tokens.scss 与 tdesign-theme.scss 全部改用 `:root[theme-mode=...]`（与 TDesign 同级权重 + 后加载者胜）。**
（验证提醒：切完主题别只看 `getComputedStyle(body).backgroundColor`，它可能命中计算值缓存，需用探针元素或刷新后再读。）

### 🎨 风格：青玉编辑感 → 宝石蓝 · 卡片工作台
- 主色：青玉 `#0c7c59` → 宝石蓝 `#2563eb`（与白底 5.17:1 过 AA；深色下按钮底同色 + 白字，链接另用 `#7aa8ff`）。
- 中性色：青灰 → 蓝灰（浅 `#f4f6fb / #ffffff / #0f1729`，深 `#0b0f18 / #131926 / #e9eef8`）；
  品牌/中性/语义三级色板与 `index.html` 的 `theme-color` 同步更新。
- 形状：圆角整体放大一档（xs5 / sm7 / md10 / lg12 / xl16 / 2xl22）；
  卡片由「无框发丝线」改回「白底 + 细描边」，重新有边界感（仅列表条目分隔线仍用 `--tk-hairline`）。
- 密度：`--tk-space-9` 80→68、版心 1120→1200、顶栏 64→68、侧栏 248→268。

### 🔠 字号整体放大一档（tokens.scss）
- 旧 → 新：`12→13 / 13→14 / 14→16 / 15→17 / 17→19 / 20→22 / 26→28 / 34→36 / 44→46 / 58→52`。
- **正文基准 16px**，全站最小字号 13px（`--tk-text-xs`）。
- **工具页里残留的 11px/12px 硬编码字号一次性提升为 `var(--tk-text-xs)`**（27 个 `.vue` 文件）。

### 🧩 UI 库主题控制（tdesign-theme.scss 新增第 ③ 段，本轮核心）
TDesign 组件样式完全建立在 `--td-*` 变量之上（例如 `.t-input.t-size-l { height: var(--td-comp-size-xl) }`），
所以「控件太小」的正解是改变量，而不是逐个组件写 CSS：

| 变量分组 | TDesign 默认 | 本版 | 影响面 |
| --- | --- | --- | --- |
| `--td-comp-size-m`（默认控件） | 32px | **40px** | 输入框 / 按钮 / 下拉 / 日期选择器 |
| `--td-comp-size-xl`（large） | 40px | 48px | large 尺寸控件 |
| `--td-comp-size-xs / xxs / xxxs` | 24 / 20 / 16px | 28 / 24 / 18px | 小按钮、标签、复选框 |
| `--td-font-size-body-medium` | 14px | **16px** | 控件文字（与正文同号） |
| `--td-font-size-body-small` | 12px | 13px | 小标签、说明 |
| `--td-font-size-title-*` | 14/16/18px | 16/18/20px | 卡片标题、分组标题 |
| `--td-line-height-body-*` | 20/22/24px | 22/24/26px | **必须与字号成对改**，否则大字号被行高挤住 |
| `--td-comp-paddingTB / LR-*` | size 阶梯 | 放宽一档 | 控件内边距，避免大控件里文字贴边 |

- 只覆盖 `--td-comp-*`，**不动 `--td-size-*` 原子刻度**（图标/徽标/间距都在用它）。
- 深色中性色阶（反向，1 最深 → 14 最浅）补进 `:root[theme-mode='dark']`，避免组件在深色下退回 UI 库冷灰。
- 下拉：`--td-comp-size-m` 放大后 `.t-select-option` / `.t-dropdown__item` 行高自动跟随，仅补一条字号保险。

### 🧱 外壳、首页与公共组件（跟随新尺度）
- `MainLayout`：顶栏 68px、命令面板入口 44px、图标按钮 40px、内容区留白 32/48/72、移动端抽屉宽 300。
- `SideNav`：筛选框 42px、导航项 padding 9/12（行高约 43px）、图标 19px、活动指示条 3×18px。
- `HomeView`：hero 标题 52px、搜索底线 60px、工具索引行 padding 20px、服务端卡片图标 38px + 轻投影。
- 公共组件：`CommandPalette`（搜索行 64px、结果项 58px、kbd 22px）、`UploadDrop`（拖拽区加大、
  缩略图 56px、删除按钮热区 36px）、`AppBrand`（标记 36px）、`ThemeSwitch` / `LocaleSwitch`（40px 高）、
  `HistoryPanel`（条目最小高 48px、操作按钮热区撑大）。
- `unocss.config.ts` 的 `panel`（改实描边 + 更大内边距）、`code-block`（14px）、`hint-text`（13px）跟随放大。

---

## 2026-09-14 第七批：界面改版 →「更松弛的编辑感」

> 用户反馈对现有主题界面仍不满意，经方向选择后定为**编辑感（Editorial）**：
> 加大留白与字号反差，卡片几乎无边框，靠排版与呼吸感建立层次。
> 依据 `design-taste-frontend` 技能执行，旋钮 `DESIGN_VARIANCE 6` / `MOTION_INTENSITY 3` / `VISUAL_DENSITY 3`。
> 构建通过（`vue-tsc --noEmit` + `vite build`，32.17s）。

### 🎯 本轮解决的三个真实问题
1. **首页 hero 超标**：eyebrow + 标题 + 描述 + 搜索框 + 文字链接共 5 个文字元素（超过 hero 上限 4），
   且 eyebrow 是模板化开场 → **删掉 eyebrow 与重复的 hero 链接**（服务端专区入口已在下方，同意图不出现两次）。
2. **58 张卡片长得一模一样**：全部 14px 圆角 + 1px 描边 + 绿底图标，重复得没有节奏
   → 改为**发丝线索引行**（像书末索引），图标常态中性灰、hover 才上主色。
3. **层次全靠边框与底纹堆出来**，排版本身承担的信息层级偏弱
   → 标题 58px / 说明 17px 拉开反差，分区之间改用 80px 留白而非横线。

### 🧱 令牌层（tokens.scss）
- 新增 `--tk-hairline`（浅 `#e7ecea` / 深 `#232b29`）：内容容器与条目分隔线用它；
  **功能控件仍用 `--tk-border`**，两类不要互换。
- 新增排版令牌：`--tk-text-5xl`(58px)、`--tk-leading-display/title/body`、
  `--tk-track-display/title`、`--tk-font-display`。其中展示字体显式等于系统字体族 ——
  中文环境下可用的展示字体就是系统字体本身，引入网络 CJK 展示字体要多付 2MB+ 首屏成本。
- `--tk-space-9`(80px) 专用于分区之间；`--tk-header-h` 60 → 64。
- 移除未使用的 `--tk-track-caps`（不在 CJK 场景下用宽字距）。

### 📐 全局排版与容器（index.scss / unocss.config.ts / tdesign-theme.scss）
- `.page-title` → `clamp(26px, 3vw, 34px)` + 字重 640；`.page-desc` → 15px / 1.75 / `max-width: 62ch`；
  `.tool-section` 间距 16 → 32px；新增 `.section-heading` 与 `.rule`。
- `t-card` / UnoCSS `panel`：**圆角 → 2xl、描边 → 发丝线、内边距放大一档**（`p-5 md:p-7`、
  `.t-card .t-card__body` 24/32，窄屏在 `@media (max-width: 767px)` 收回）。
- 滚动条 10 → 8px；`.reveal` 位移 14 → 10px（编辑感入场要「不动声色」）。

### 🏠 首页重写（HomeView.vue）
- 抬头区：58px 左对齐标题 + 一句说明 + **底线式搜索框**（聚焦时底线加粗为 2px，
  用 `box-shadow` 叠加避免 `border-width` 变化引起 1px 位移；输入框自身不画焦点环）。
- 事实条去掉全部边框与底纹，数字直接摊在纸面上。
- 服务端专区保留青玉底纹（全站唯一），是分区层级的锚点。
- 分类目录 = 标题 + 数量注记 + 说明 + 发丝线索引网格（列间距 52px，避免两栏读串行）。

### 🧭 外壳（MainLayout / SideNav / AppBrand）
- 侧栏**去掉底色块与右侧竖线**，与正文落在同一张纸面上；hover 改用 `--tk-surface`
  （浅色下更亮、深色下也更亮，两种主题都是同一种「抬起」方向）。
- 侧栏筛选框改为底线式；内容区留白 28/28/56 → **40/48/88**；页脚改左右分列 + 发丝线。
- 品牌图标**去掉全站唯一渐变**，改实色小方块（渐变会把视线从标题上拽走），
  品牌辨识度改由字重与字距承担。

### ♻️ 顺带修复
- `HistoryPanel.vue` 此前混用硬编码的 `--td-*` 与写死的 `border-radius: 6px`，
  违反「样式一律用 `--tk-*`」的硬规则，且每条历史都套一个描边盒子；已改为 `--tk-*` 令牌 + 发丝线分行。
- 清理 4 份语言包中已失效的 `home.eyebrow` / `home.ctaPrimary` / `home.ctaSecondary`。

---

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