KimiCodeSwitch/docs/HANDOVER-usage-billing.md

# 工作交接：账单查询功能（2026-08-01）

> 新会话续作入口：先读本文件 + `docs/USAGE-QUERY-ADAPTATION.md`（调研文档），然后按「二、下一步」继续。

## 一、当前进度总览

**已提交并发布 v0.6.4**：
- `ace9842` — feat: 新增部分套餐账单查询（v0.6.4）（26 文件 +1822/-60，含以下全部 6 个批次 + 版本号三处 0.6.4）
- 已推送 origin（git.codingplan.site）：分支 `Dev_20260801` + tag `v0.6.4`
- 已推送 GitHub（billowliu2/KimiSwitch）：tag `v0.6.4`（走 127.0.0.1:7897 代理；git 全局配置 `http.proxy` 指向它，代理关闭时 push 会报 schannel SSL 握手错误，可用 `git -c http.proxy= push` 绕过硬连 origin）
- GitHub Actions Release workflow 已触发（三平台构建 → Release draft 自动上传 msi/dmg/AppImage/deb/rpm）
- 本地 0.6.4 安装包：`src-tauri/target/release/bundle/{nsis,msi}/`

**已提交并发布 v0.6.5**：
- `feat: 优化更新检查逻辑 + 修复按量余额显示（v0.6.5）`
- 检查更新优先私有库（git.codingplan.site），8s 超时自动回退 GitHub
- 设置-关于：合并移植声明为一句、新增 cc-switch 链接（openUrl + window.open 兜底）、移除仪表盘/会话页脚重复声明
- 修复按量余额不显示：UsageFooter isPlan 判定增加配额字段（total/used）条件——余额条目（DeepSeek/StepFun/SiliconFlow/Novita/Kimi 开放平台）现在正确显示 `💰 ¥x.xx`，套餐类（有 total/used）不受影响。实测 DeepSeek 官方接口返回 200 + balance_infos
- 两仓库 main + Dev_20260801 + tag v0.6.5 已同步

**历史提交**：`12dcb17` — docs: 账单查询适配调研 + OpenCode Zen 预设补推荐链接

**工作区未提交改动**——用户硬约束：**实现完成不提交，等用户逐批测试确认后才提交**。
`git status` 实测清单（注意：`src-tauri/Cargo.toml` 现含**真实改动**——批次 4 新增 tokio 依赖行，另混有用户自己的行尾差异，提交时只保留 tokio 行）：

```
M  docs/USAGE-QUERY-ADAPTATION.md   M  src/App.tsx
M  src-tauri/Cargo.toml（含 tokio 真实改动）  M  src/components/ProviderList.tsx
M  src-tauri/src/commands.rs        M  src/components/UsageFooter.tsx
M  src-tauri/src/db.rs              M  src/config/providerPresets.ts
M  src-tauri/src/kimi_code_io.rs    M  src/hooks/useConfig.ts
M  src-tauri/src/lib.rs             M  src/i18n/en.ts
M  src-tauri/src/models.rs          M  src/i18n/zh.ts
M  src-tauri/src/pi_io.rs           M  src/types/index.ts
M  src-tauri/src/services/balance.rs / coding_plan.rs / mod.rs
?? docs/HANDOVER-usage-billing.md（本文件）
?? src-tauri/src/oauth.rs
?? src/components/UsageConfigModal.tsx
?? src/lib/usage-display.ts
```

### 批次 1：P0 `balance:kimi` + usageKinds 字段修复
- `src-tauri/src/services/balance.rs` — `query_kimi`/`parse_kimi`（`api.moonshot.cn|ai/v1/users/me/balance`，CNY/USD 消歧）+ 5 单测
- `src-tauri/src/services/mod.rs` — `UsageKind::BalanceKimi`（"balance:kimi"）、detect_provider 加 `api.moonshot.cn/.ai`
- `src/config/providerPresets.ts` — union/SUPPORTED 加 `balance:kimi`，moonshot 预设挂 usageKinds
- `src-tauri/src/models.rs` — **`usage_kinds` 加 `#[serde(rename = "usageKinds")]`**（修复历史 bug：Rust 序列化 snake_case、前端读 camelCase 导致所有账单入口不显示）

### 批次 2：A/B/C 三阶段（OAuth + 配置面板 + NewAPI）
Rust：
- `src-tauri/src/oauth.rs`（新增）— 读 `~/.kimi-code/credentials/kimi-code.json` access_token，30s 过期缓冲，**不做 refresh**（避免与 CLI 的 refresh_token 轮换竞态）
- `src-tauri/src/models.rs` — `UsageConfig` struct（camelCase）+ `Provider.usage_config`（rename="usageConfig"）
- `src-tauri/src/services/balance.rs` — `query_newapi`/`parse_newapi`/`fetch_newapi_status`（NewAPI 中转站：`{base}/api/user/self` + Bearer accessToken + `New-Api-User` userId；`/api/status` 拉 quota_per_unit/货币符号，进程内缓存 5min；quota=0 视为无限额度）
- `src-tauri/src/services/mod.rs` — `BalanceNewapi`（"balance:newapi"，ALL=10），`query_kind` 签名加 `usage_config: Option<&UsageConfig>`
- `src-tauri/src/commands.rs` — `usage_config_key` + merge_usage_kinds 同时 merge usage_config（SQLite `usage_config:<name>`）；save 时持久化；`query_provider_usage`：usageConfig.enabled=false 拒绝、templateType=="newapi" 走 NewAPI 分支、managed 供应商读 OAuth token（api_key 优先，OAuth 兜底）
- `src-tauri/src/lib.rs` — 注册 `pub mod oauth;`
- `src-tauri/src/db.rs` / `kimi_code_io.rs` / `pi_io.rs` — Provider 构造点补 `usage_config: None`（8 处）

前端：
- `src/types/index.ts` — `UsageConfig` 接口 + `Provider.usageConfig`
- `src/components/UsageConfigModal.tsx`（新增）— 配置面板（批次 3 已改全屏）
- `src/components/UsageFooter.tsx` — 拆 compact（卡片右侧：主摘要 + `x 分钟前` + 刷新，含自动查询 interval）/ detail（底部：多档明细 + 错误/重试）；模块级缓存 + 3 并发信号量
- `src/components/ProviderList.tsx` — BarChart3 配置入口按钮；紧凑用量行嵌入按钮组、位于「切换使用」左侧（cc-switch 布局）
- `src/App.tsx` — `usageConfigProvider` 状态 + `handleSaveUsageConfig` + modal 挂载
- `src/i18n/zh.ts` / `en.ts` — 新增约 34 个 key

### 批次 3：全屏配置页面 + 超时配置
- `src/components/UsageConfigModal.tsx` — **居中弹窗 → 全屏页面**（参考 cc-switch FullScreenPanel）：`fixed inset-0 flex flex-col bg-app`，header 64px（ArrowLeft 返回 + 标题），内容 `max-w-3xl` 居中滚动，footer 固定底部；ESC 关闭但输入框聚焦时不关（isTextEditableTarget）
- 新增页面元素：**支持的变量区**（`{{baseUrl}}`/`{{apiKey}}` 脱敏 + 眼睛切换明文）、**超时时间输入**（与自动查询间隔并排两列）
- 超时接线：`UsageConfig.timeout_seconds`（models.rs camelCase）+ `types/index.ts timeoutSeconds`；`balance.rs::get_json` 及全部 `query_*`、`fetch_newapi_status`、`coding_plan` 3 函数加 `timeout: Duration` 参数；`query_kind` 从 usage_config 计算（0/None 回退 8s），`commands.rs` 无改动
- i18n：`usageTimeout`/`usageTimeoutHint`/`usageSupportedVars`/`usageBack`（zh+en）
- **测试查询体验修复**（2026-08-01 用户反馈「测试查询没有生效」）：
  - 测试结果框改为 **sticky bottom-0**（在 body 滚动容器内），始终浮在 footer 上方，点了立即可见
  - 「自动检测 + 无识别类型」短路：handleTest 前置检查 detectedKinds.length===0，直接展示 `usageUnsupportedProvider` 中文提示，不发无效请求
  - 「未识别查询类型」区改为带「切换到 NewAPI 模板」快捷按钮的 amber 提示框（替换原灰色单行）
  - 新增 i18n：`usageNoKindsHint`/`usageSwitchToNewapi`/`usageUnsupportedProvider`

**验证（三批累计）**：`cargo test --lib` 46 全过、`cargo check` 干净、`tsc --noEmit` 零错误。
**最新打包产物**（批次 3 + 体验修复 已交付用户测试）：
- `D:\AIGC\KimiSwitch\src-tauri\target\release\bundle\nsis\Kimi Switch_0.6.3_x64-setup.exe`
- `D:\AIGC\KimiSwitch\src-tauri\target\release\bundle\msi\Kimi Switch_0.6.3_x64_en-US.msi`

### 批次 4（2026-08-01）：OAuth refresh + 测试查询短路修复
- **背景**：用户反馈「Kimi login 又失效」——根因是 access token 15 分钟过期且 refresh 未实现（§三.3 已拍板实现）；refresh 端点与 client_id 已从 kimi.exe 二进制实测确认（`POST https://auth.kimi.com/api/oauth/token`，client_id `17e5f671-d194-4dfb-9706-5516cb48c098`，form-encoded grant_type=refresh_token）
- `src-tauri/src/oauth.rs` — `get_valid_access_token()`：过期 → `tokio::sync::Mutex` 单 flight 锁内重读文件（CLI/其他等待者可能已刷新则直接采用）→ `refresh_credentials()` 调 token 端点 → 写回前再重读（CLI 若已轮换则采纳其 token，避免覆盖 CLI 的新 refresh_token）→ `merge_token_response()` 纯函数合并写回（保留未知字段）+ 3 个新单测
- `src-tauri/src/commands.rs` — managed 分支改为 `get_valid_access_token().await`，错误信息直接用 refresh 的具体失败原因（含 invalid_grant 时提示重新 `kimi login`）
- `src-tauri/Cargo.toml` — 新增 `tokio = { version = "1", features = ["sync"] }`（项目本无 tokio 直接依赖）
- `src/components/UsageConfigModal.tsx` — 「无识别类型短路」加 `!isManaged` 守卫（managed 走 OAuth 与 detectedKinds 无关，防误伤）
- **验证**：cargo test 48 过（+2 merge 用例）、tsc 零错误

### 批次 5（2026-08-01）：用量显示本地化 + 按钮顺序调整
- `src/lib/usage-display.ts`（新增）— `planLabel()`（five_hour→"5小时"/"5-hour"、weekly_limit→"7天"/"Weekly"，其余专名透传）+ `localizeUsageError()`（Rust 英文错误串按前缀/正则映射到 i18n，未知错误透传保留诊断信息）
- `src/components/UsageFooter.tsx` — compact/detail 的 tier 标签与错误显示接入两个 helper
- `src/components/UsageConfigModal.tsx` — 测试结果的 planName/错误同样本地化；catch（瞬时失败）统一显示 usageNetworkError
- `src/components/ProviderList.tsx` — BarChart3（配置用量查询）按钮从图标组首位移到 Activity（连通测试）与 Trash（删除）之间
- i18n 新增：`usageTier5h`/`usageTierWeekly`/`usageErrNoKey`/`usageErrDisabled`/`usageErrLoginExpired`/`usageErrNoOauth`/`usageErrNewapiCreds`（zh+en）
- **验证**：tsc 零错误（纯前端改动，Rust 未动）

### 批次 6（2026-08-01）：测试查询「无结果」根因修复
- **根因**：`App.tsx` 顶层 `if (loading || !config) return <loading 页>`——`handleTest` 先 `onSave` → `void save()` → `setLoading(true)` → App 整树换成 loading 页 → **modal 被卸载**；查询结果回来后 setState 打到已卸载实例（无效），save 结束 modal 全新重挂载（testResult=null）。自配置面板引入即存在，任何「先保存再查询」的路径都中招。
- `src/hooks/useConfig.ts` — `refresh`/`save` 加 `{ silent?: boolean }` 选项：silent 时不翻 loading 页（不 setLoading）
- `src/App.tsx` — `handleSaveUsageConfig` 改为 `return save({ silent: true })`；error 分支重试按钮 `onClick={refresh}` 改箭头包装（MouseEvent 会当 opts 传入）
- `src/components/UsageConfigModal.tsx` — `onSave` 类型改 `Promise<void> | void`；`handleTest` **await onSave 完成后再 invoke 查询**（保证后端读到同一份配置）
- `src/components/ProviderList.tsx` — **managed（OAuth 登录托管）供应商置顶**：组件内 `[...providers].sort()` 稳定排序，仅展示层，不改 config.toml/SQLite 存储顺序
- **验证**：tsc 零错误

## 二、下一步

1. **等用户测批次 3 的包**（重点：卡片图表图标 → 全屏配置页 → 变量区/超时输入 → 测试查询 → 保存后紧凑行刷新）。用户反馈优先处理。
2. **用户确认后才 `git commit`**（建议拆 3 个 commit 对应批次 1/2/3，提交信息中文 + scope 前缀；排除 `src-tauri/Cargo.toml` 行尾改动）。
3. 后续候选（均待用户拍板，见 §三）：OAuth refresh、NewAPI 面板自动探测、自定义 JS 提取器模板（P3）。

## 三、悬而未决（用户已知情，待决定）

1. **OpenCode Go 账单查询**：~~已实测全部端点 404（`/zen/go/v1/usages`、`/api/usage`、`/api/billing` 等 12+ 路径），cc-switch 源码也不支持 → 结论：无公开 API，不可查~~。**2026-08 推翻**：`GET https://opencode.ai/zen/go/v1/usage`（Bearer + 显式浏览器 UA，否则 Cloudflare 1010 拦截 403）实测 200，已实现为 `plan:opencode_go`（滚动 5h / 周 / 月三窗口）。
2. **Kimi login 配 API key**：可以，代码已支持（api_key 优先于 OAuth）。但 managed 供应商编辑页隐藏 key 输入框（`ProviderEdit.tsx:301` `{!provider.managed && ...}`）。选项：① 用户新建 kimi-coding 预设供应商填 key；② 改 UI 让 managed 显示可选 key 输入。
3. **OAuth refresh**：**已实现**（批次 4）。过期自动用 refresh_token 换新并写回凭据文件；单 flight 锁 + 写回前重读防 CLI 竞态。已知边界：若 access token 未过期但被服务端吊销（罕见），401 不会触发重读重试——暂不处理。
4. **NewAPI 面板自动探测**：打开配置面板时探测 `{base}/api/status` 含 `quota_per_unit` → 自动预选 NewAPI 模板。已提议，未确认。

## 四、关键环境信息

- 项目：`D:\AIGC\KimiSwitch`（Tauri 2 + React 18 + TS + Tailwind + Rust/rusqlite/reqwest），分支 `Dev_20260801`
- 参考项目：`D:\AIGC\cc-switch`（MIT，账单查询功能源头；全屏面板参考其 `src/components/common/FullScreenPanel.tsx`）
- 构建：`npm run tauri-build`（前后端一起，产出 msi+nsis）；`cargo test --lib`（src-tauri 下）；`npx tsc --noEmit`
- 提交信息风格：中文 + scope 前缀（`docs:`/`build:`/`fix:`/`feat:`）
- 用户 NewAPI 站点：`https://ai.codingplan.site`（quota_per_unit=500000，符号 ¤）；Access Token 需网页后台生成（sk- 推理 key 查不了 `/api/user/self`，实测 401）