mdy/openbridge-token-usage-viewer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

refactor: 优化代码结构，添加中文注释，完善 README 文档

Browse Source 
- Hooks/组件添加 useMemo 优化，减少不必要的重计算
- 简化 TokenUsageDashboard 的 Suspense 嵌套层级
- 完善 README: 技术栈、构建产物位置、架构说明
This commit is contained in:
MAO Dongyang
2026-01-21 20:15:34 +08:00
parent a77fcdd3dc
commit 13a873ec76
17 changed files with 944 additions and 365 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
README.md
View File

@@ -6,27 +6,50 @@
## 功能特点
- **实时配额监控**: 显示 4 个账户的 Claude Opus 4.5 (Thinking) 模型配额使用情况
- **可视化仪表盘**: Apple Health 风格的圆环进度指示器
- **实时配额监控**: 显示最多 4 个账户的 Claude Opus 4.5 (Thinking) 模型配额使用情况
- **可视化仪表盘**: Apple Health 风格的圆环进度指示器，颜色根据剩余配额自动变化
- **智能告警系统**:
- 当配额剩余 < 20% 时显示警告 (Warning)
- 当配额剩余 < 5% 时显示紧急告警 (Alarm)
- **主题切换**: 支持白天/夜间模式切换
- **主题切换**: 支持白天/夜间模式切换，OpenBridge 设计系统主题
- **自动刷新**: 配额数据每 5 分钟自动刷新
- **倒计时显示**: 显示配额重置剩余时间
- **SSR 支持**: 服务端渲染，首屏即有数据
## 技术栈
| 层级 | 技术 |
### 核心框架
| 层级 | 技术 | 版本 |
|------|------|------|
| 前端框架 | React | 19.2 |
| 路由 | TanStack Router | 1.151 |
| 状态管理 | TanStack Query | 5.90 |
| SSR 框架 | TanStack Start | 1.151 |
| RPC 通信 | ORPC (类型安全契约优先) | 1.13 |
| UI 组件 | OpenBridge Web Components | 0.0.17 |
| 样式 | Tailwind CSS | v4 |
| 桌面壳 | Tauri | v2.9 |
| 运行时 | Bun | 1.3.6 |
### 后端 & 数据
| 技术 | 说明 |
|------|------|
| 前端框架 | React 19 + TanStack Router |
| UI 组件 | OpenBridge Web Components |
| 状态管理 | TanStack Query |
| 样式 | Tailwind CSS v4 |
| RPC 通信 | ORPC (类型安全) |
| 桌面壳 | Tauri v2 |
| 运行时 | Bun |
| 构建 | Vite + Turbo |
| SQLite | Bun 内置驱动 (bun:sqlite)，无需额外安装 |
| Drizzle ORM | 类型安全 ORM，支持迁移 |
| Nitro | 服务端框架 (bun preset) |
| Zod | 运行时类型验证 |
### 构建工具
| 技术 | 说明 |
|------|------|
| Vite | 开发服务器 + 构建 |
| Turbo | 任务并行化 |
| Effect | 函数式构建脚本 |
| Biome | 代码格式化 + Lint |
| React Compiler | 自动优化，无需手动 memo |
## 快速开始
@@ -53,13 +76,19 @@ bun run dev # Tauri 桌面应用 + Web
### 构建
```bash
bun run build:vite # 构建 Web 版本
bun run build:vite # 构建 Web 版本 (输出到 .output/)
bun run build # 构建 Tauri 桌面安装包
```
构建产物位置：
- **MSI 安装包**: `src-tauri/target/release/bundle/msi/app-desktop_0.1.0_x64_en-US.msi`
- **NSIS 安装包**: `src-tauri/target/release/bundle/nsis/app-desktop_0.1.0_x64-setup.exe`
### 构建产物位置
| 类型 | 路径 |
|------|------|
| **Vite Web 构建** | `.output/` |
| **Sidecar 二进制** | `src-tauri/binaries/app-<target>` |
| **MSI 安装包** | `src-tauri/target/release/bundle/msi/app-desktop_0.1.0_x64_en-US.msi` |
| **NSIS 安装包** | `src-tauri/target/release/bundle/nsis/app-desktop_0.1.0_x64-setup.exe` |
| **macOS DMG** | `src-tauri/target/release/bundle/dmg/app-desktop_0.1.0_aarch64.dmg` |
## 配置
@@ -92,15 +121,129 @@ TOKEN_USAGE_URL=http://your-server:8318/usage
## 常用命令
### 开发
| 命令 | 说明 |
|------|------|
| `bun dev` | 启动 Tauri + Vite 开发服务器 |
| `bun dev:vite` | 仅启动 Vite 开发服务器 |
| `bun dev` | 启动 Tauri + Vite 开发服务器 (并行) |
| `bun dev:vite` | 仅启动 Vite 开发服务器 (http://localhost:3000) |
| `bun dev:tauri` | 仅启动 Tauri (需先启动 Vite) |
| `bun build` | 完整构建 (Tauri 桌面应用) |
| `bun build:vite` | 仅构建 Web 版本 |
| `bun db:studio` | 打开 Drizzle Studio 数据库管理界面 |
### 构建
| 命令 | 说明 |
|------|------|
| `bun build` | 完整构建 (Vite → 编译 → Tauri 打包) |
| `bun build:vite` | 仅构建 Web 版本 (输出到 .output/) |
| `bun build:compile` | 编译 Sidecar 二进制 (使用 build.ts) |
| `bun build:tauri` | 构建 Tauri 桌面安装包 |
### 代码质量
| 命令 | 说明 |
|------|------|
| `bun typecheck` | TypeScript 类型检查 |
| `bun fix` | 自动修复格式和 Lint 问题 |
| `bun fix` | 自动修复格式和 Lint 问题 (Biome) |
### 数据库
| 命令 | 说明 |
|------|------|
| `bun db:init` | 初始化 SQLite 数据库 |
| `bun db:generate` | 从 schema 生成迁移文件 |
| `bun db:migrate` | 执行数据库迁移 |
| `bun db:studio` | 打开 Drizzle Studio |
## 项目结构
```
├── src/
│ ├── components/ # React 组件
│ │ ├── HealthRing.tsx # 圆环进度指示器 (Apple Health 风格)
│ │ ├── TokenUsageDashboard.tsx # 主仪表盘 (告警+主题+圆环)
│ │ ├── Error.tsx # 错误边界回退组件
│ │ └── NotFount.tsx # 404 页面
│ │
│ ├── hooks/ # React Hooks
│ │ ├── useCountdown.ts # 倒计时 Hook (useMemo 优化)
│ │ └── useTheme.ts # OpenBridge 主题切换 Hook
│ │
│ ├── orpc/ # ORPC RPC 层
│ │ ├── contracts/ # 契约定义 (Zod schema)
│ │ │ └── usage.ts # 使用量查询契约
│ │ ├── handlers/ # 服务端处理器
│ │ │ └── usage.ts # 获取配额数据+存储历史
│ │ ├── middlewares/ # ORPC 中间件
│ │ │ └── db.ts # 数据库连接 Provider
│ │ ├── client.ts # 同构客户端 (SSR/CSR 自动切换)
│ │ ├── contract.ts # 契约聚合
│ │ ├── router.ts # 路由组合
│ │ ├── server.ts # 服务端实例
│ │ └── types.ts # 类型导出
│ │
│ ├── routes/ # TanStack Router 文件路由
│ │ ├── __root.tsx # 根布局 (OpenBridge 主题集成)
│ │ ├── index.tsx # 首页 (SSR 预取+自动刷新)
│ │ └── api/rpc.$.ts # ORPC HTTP 端点
│ │
│ ├── db/ # 数据库层
│ │ ├── schema/ # Drizzle Schema
│ │ │ └── usage-history.ts # 使用量历史表
│ │ └── index.ts # 数据库连接 (SQLite WAL)
│ │
│ ├── lib/ # 工具函数
│ ├── env.ts # 环境变量验证 (t3-env)
│ └── router.tsx # 路由配置
│
├── src-tauri/ # Tauri 桌面应用
│ ├── src/
│ │ ├── lib.rs # Tauri 入口
│ │ └── sidecar.rs # Sidecar 进程管理
│ ├── binaries/ # 编译后的 sidecar 二进制
│ └── tauri.conf.json # Tauri 配置
│
├── build.ts # 跨平台构建脚本 (Effect 框架)
├── vite.config.ts # Vite 配置
├── drizzle.config.ts # Drizzle ORM 配置
└── .output/ # Vite 构建输出
```
## 架构说明
### ORPC 同构客户端
ORPC 客户端根据运行环境自动选择最优调用方式:
- **SSR (服务端)**: 直接调用 router 处理器，零网络开销
- **CSR (客户端)**: 通过 `/api/rpc` 端点进行 HTTP 调用
```tsx
// 使用 TanStack Query
const { data } = useSuspenseQuery(orpc.usage.getUsage.queryOptions())
```
### Tauri Sidecar
应用采用 Sidecar 架构:
1. **Tauri 壳**: 提供原生窗口和系统集成
2. **Bun 服务端**: 编译为独立可执行文件，处理 SSR 和 API 请求
3. **通信**: Tauri WebView 通过 localhost:3000 与 Sidecar 通信
### 数据流
```
Token API (http://10.0.1.1:8318/usage)
↓
ORPC Handler (usage.ts)
↓
SQLite (data/app.db) ← 历史记录存储
↓
TanStack Query Cache
↓
React Components (TokenUsageDashboard)
```
## 故障排除
@@ -188,34 +331,6 @@ taskkill /F /PID <PID>
2. 重新安装新的 MSI
3. 确保安装目录有写入权限
## 项目结构
```
├── src/
│ ├── components/
│ │ ├── HealthRing.tsx # 圆环进度指示器
│ │ ├── TokenUsageDashboard.tsx # 主仪表盘
│ │ └── ...
│ ├── hooks/
│ │ └── useTheme.ts # 主题切换 Hook
│ ├── orpc/
│ │ ├── contracts/usage.ts # API 契约
│ │ └── handlers/usage.ts # 数据获取逻辑
│ ├── routes/
│ │ ├── __root.tsx # 根布局
│ │ └── index.tsx # 首页
│ └── env.ts # 环境变量配置
│
├── src-tauri/ # Tauri 桌面应用
│ ├── src/
│ │ ├── lib.rs # Tauri 入口
│ │ └── sidecar.rs # Sidecar 管理
│ ├── binaries/ # 编译后的 sidecar
│ └── tauri.conf.json # Tauri 配置
│
└── .output/ # Vite 构建输出
```
## 许可证
MIT