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

- Hooks/组件添加 useMemo 优化，减少不必要的重计算 - 简化 TokenUsageDashboard 的 Suspense 嵌套层级 - 完善 README: 技术栈、构建产物位置、架构说明
2026-01-21 20:15:34 +08:00
parent a77fcdd3dc
commit 13a873ec76
17 changed files with 944 additions and 365 deletions
--- a/src/routes/__root.tsx
+++ b/src/routes/__root.tsx
@@ -1,3 +1,13 @@
+/**
+ * 根布局组件
+ *
+ * 定义应用的 HTML 结构、全局样式和错误处理。
+ *
+ * 特性:
+ * - OpenBridge 设计系统集成 (CSS 变量主题)
+ * - TanStack Router 上下文配置
+ * - 全局错误边界和 404 处理
+ */
 import '@oicl/openbridge-webcomponents/src/palettes/variables.css'
 import type { QueryClient } from '@tanstack/react-query'
 import {
@@ -10,36 +20,44 @@ import { ErrorComponent } from '@/components/Error'
 import { NotFoundComponent } from '@/components/NotFount'
 import appCss from '@/styles.css?url'

+/** 路由上下文类型 - 包含 TanStack Query 客户端 */
 export interface RouterContext {
  queryClient: QueryClient
 }

+/**
+ * 根路由定义
+ *
+ * 配置:
+ * - head: 页面 meta 标签和样式表
+ * - shellComponent: HTML 文档结构
+ * - errorComponent: 错误边界回退
+ * - notFoundComponent: 404 页面
+ */
 export const Route = createRootRouteWithContext<RouterContext>()({
  head: () => ({
    meta: [
-      {
-        charSet: 'utf-8',
-      },
-      {
-        name: 'viewport',
-        content: 'width=device-width, initial-scale=1',
-      },
-      {
-        title: 'Token Usage Viewer',
-      },
-    ],
-    links: [
-      {
-        rel: 'stylesheet',
-        href: appCss,
-      },
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+      { title: 'Token Usage Viewer' },
    ],
+    links: [{ rel: 'stylesheet', href: appCss }],
  }),
  shellComponent: RootDocument,
  errorComponent: () => <ErrorComponent />,
  notFoundComponent: () => <NotFoundComponent />,
 })

+/**
+ * HTML 文档根结构
+ *
+ * 设置:
+ * - lang="zh-Hans": 简体中文
+ * - data-obc-theme="day": OpenBridge 默认日间主题
+ * - obc-component-size-regular: OpenBridge 标准组件尺寸
+ *
+ * @param children - 页面内容
+ */
 function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
  return (
    <html lang="zh-Hans" data-obc-theme="day">
--- a/src/routes/index.tsx
+++ b/src/routes/index.tsx
@@ -1,7 +1,12 @@
 /**
 * Token Usage Viewer 主页面
 *
- * 展示 Opus/Thinking 模型的配额使用情况仪表盘
+ * 展示 claude-opus-4-5-thinking 模型的配额使用情况仪表盘。
+ *
+ * 特性:
+ * - SSR 预加载数据（通过 loader）
+ * - 每 5 分钟自动刷新配额数据
+ * - Tauri 环境下自动设置窗口标题
 */
 import { useSuspenseQuery } from '@tanstack/react-query'
 import { createFileRoute } from '@tanstack/react-router'
@@ -11,8 +16,16 @@ import { useEffect } from 'react'
 import { TokenUsageDashboard } from '@/components/TokenUsageDashboard'
 import { orpc } from '@/orpc'

+/** 数据自动刷新间隔 (毫秒) - 5 分钟 */
+const REFETCH_INTERVAL = 5 * 60 * 1000
+
 export const Route = createFileRoute('/')({
  component: Home,
+  /**
+   * 路由加载器 - SSR 数据预取
+   *
+   * 在服务端渲染时预先获取使用量数据，确保首次渲染即有内容。
+   */
  loader: async ({ context }) => {
    await context.queryClient.ensureQueryData(
      orpc.usage.getUsage.queryOptions(),
@@ -20,13 +33,19 @@ export const Route = createFileRoute('/')({
  },
 })

+/**
+ * 首页组件
+ *
+ * 使用 useSuspenseQuery 获取并展示配额数据，
+ * 确保 data 不为空（由 loader 预取保证）。
+ */
 function Home() {
  const { data } = useSuspenseQuery({
    ...orpc.usage.getUsage.queryOptions(),
-    refetchInterval: 300000, // 每 5 分钟自动刷新
+    refetchInterval: REFETCH_INTERVAL,
  })

-  // 设置 Tauri 窗口标题
+  // Tauri 环境: 设置窗口标题
  useEffect(() => {
    if (!isTauri()) return
    getCurrentWindow().setTitle('Token Usage Viewer')