Develop (#55)

feat: optimize dashboard/search UX and simplify extension architecture Redesign Dashboard with compact tool grid and recently used tools Improve TopBar search UX with Cmd/Ctrl+K shortcut and better history navigation Reorganize project structure into src/ Migrate i18n from react-i18next to chrome.i18n Remove runtime language switch and settings page Remove HTML/Markdown conversion tools Clean up unused code, dead animations, redundant comments, and imports Improve component consistency with shadcn/ui patterns Replace hardcoded strings/colors with i18n tokens and theme tokens Add comprehensive project documentation and coding standards Fix CI artifact upload workflow and multiple TypeScript/test issues Includes various refactors, UI polish, i18n cleanup, CI improvements, and maintenance updates across the codebase.
2026-05-28 22:39:25 +08:00
parent d4c29a1bf4
commit 945780def8
200 changed files with 1557 additions and 4380 deletions
@@ -79,12 +79,12 @@ export function isSupportedImageType(mimeType: string): boolean {

 | 场景        | 导出方式                                         | 示例                              |
 | ----------- | ------------------------------------------------ | --------------------------------- |
-| 页面组件    | `export default function ComponentName()`        | `pages/Timestamp/index.tsx`       |
+| 页面组件    | `export default function ComponentName()`        | `src/pages/Timestamp/index.tsx`   |
 | 业务组件    | `const X = React.memo(...)` + `export default X` | `LiveClock.tsx`, `ResultView.tsx` |
-| UI 原子组件 | `React.forwardRef(...)` + `export { X }`         | `components/ui/button.tsx`        |
-| 工具函数    | `export function xxx()`                          | `utils/clipboard.ts`              |
-| 自定义 Hook | `export function useXxx()`                       | `utils/useStorageState.ts`        |
-| 类型/接口   | `export interface` / `export type`               | `types/storage.d.ts`              |
+| UI 原子组件 | `React.forwardRef(...)` + `export { X }`         | `src/components/ui/button.tsx`    |
+| 工具函数    | `export function xxx()`                          | `src/utils/clipboard.ts`          |
+| 自定义 Hook | `export function useXxx()`                       | `src/utils/useStorageState.ts`    |
+| 类型/接口   | `export interface` / `export type`               | `src/types/storage.d.ts`          |

 ```typescript
 // ✅ 页面组件 — default export
@@ -473,7 +473,7 @@ import ErrorBoundary from '@/components/ErrorBoundary';
 | 类型        | 命名模式                   | 示例                                                     |
 | ----------- | -------------------------- | -------------------------------------------------------- |
 | 页面目录    | PascalCase                 | `Timestamp/`, `Base64Converter/`, `StorageCleaner/`      |
-| 页面入口    | `index.tsx`                | `pages/Timestamp/index.tsx`                              |
+| 页面入口    | `index.tsx`                | `src/pages/Timestamp/index.tsx`                          |
 | 组件文件    | PascalCase `.tsx`          | `TopBar.tsx`, `LiveClock.tsx`, `ResultView.tsx`          |
 | 自定义 Hook | camelCase `.ts`            | `useTimestampConverter.ts`, `useStorageCleaner.ts`       |
 | 工具函数    | camelCase `.ts`            | `chromeStorage.ts`, `base64Converter.ts`, `clipboard.ts` |
@@ -527,12 +527,12 @@ const handleClean = useCallback(async () => { ... }, []);
 测试文件放在源代码同级的 `__tests__/` 目录下：

 ```
-utils/__tests__/jwt.test.ts
-utils/__tests__/base64Converter.test.ts
-utils/__tests__/useStorageState.test.ts
-components/__tests__/SwitchButtonGroup.test.tsx
-components/__tests__/ErrorBoundary.test.tsx
-pages/Timestamp/__tests__/index.test.tsx
+src/utils/__tests__/jwt.test.ts
+src/utils/__tests__/base64Converter.test.ts
+src/utils/__tests__/useStorageState.test.ts
+src/components/__tests__/SwitchButtonGroup.test.tsx
+src/components/__tests__/ErrorBoundary.test.tsx
+src/pages/Timestamp/__tests__/index.test.tsx
 ```

 ### 7.2 describe / it 命名
@@ -653,16 +653,16 @@ export function useTimestampConverter(): UseTimestampConverterReturn { ... }

 ### 8.2 Hook 存放位置

- **全局通用 Hook**：放在 `utils/` 目录下
+- **全局通用 Hook**：放在 `src/utils/` 目录下
 - **页面专属 Hook**：与页面组件同目录

 ```
-utils/useStorageState.ts          — Chrome Storage 状态持久化
-utils/useLazyTranslation.ts       — i18n 懒加载
-utils/useContextMenuData.ts       — 右键菜单数据
-utils/useDebounce.ts              — 防抖
-pages/Timestamp/useTimestampConverter.ts    — 页面级 Hook
-pages/StorageCleaner/useStorageCleaner.ts  — 页面级 Hook
+src/utils/useStorageState.ts          — Chrome Storage 状态持久化
+src/utils/useLazyTranslation.ts       — i18n 懒加载
+src/utils/useContextMenuData.ts       — 右键菜单数据
+src/utils/useDebounce.ts              — 防抖
+src/pages/Timestamp/useTimestampConverter.ts    — 页面级 Hook
+src/pages/StorageCleaner/useStorageCleaner.ts  — 页面级 Hook
 ```

 ---
@@ -767,7 +767,7 @@ const [themeMode, setThemeMode, isInitialized] = useStorageState(
 ### 11.1 页面组件结构

 ```
-pages/FeatureName/
+src/pages/FeatureName/
 ├── index.tsx              # 页面 UI（纯展示，使用 shadcn/ui 组件）
 ├── useFeatureName.ts      # 业务逻辑 Hook（状态管理 + 转换逻辑）
 ├── constants.ts           # 常量定义（可选）
@@ -779,20 +779,19 @@ pages/FeatureName/

 ### 11.2 目录职责

-| 目录             | 职责                                                         |
-| ---------------- | ------------------------------------------------------------ |
-| `config/`        | 应用配置（功能定义、路由映射）                               |
-| `entrypoints/`   | 扩展入口点（popup、options、sidepanel、background、content） |
-| `pages/`         | 功能页面组件（懒加载）                                       |
-| `components/`    | 可复用 UI 组件                                               |
-| `components/ui/` | shadcn/ui 基础组件（button、dialog、select 等）              |
-| `providers/`     | React Context（Router、Theme 等）                            |
-| `hooks/`         | 自定义 React Hooks                                           |
-| `utils/`         | 工具函数与服务抽象                                           |
-| `types/`         | TypeScript 类型声明                                          |
-| `lib/`           | 通用工具函数（cn、utils）                                    |
-| `i18n/`          | 国际化资源                                                   |
-| `public/`        | 静态资源                                                     |
+| 目录                 | 职责                                                         |
+| -------------------- | ------------------------------------------------------------ |
+| `src/config/`        | 应用配置（功能定义、路由映射）                               |
+| `src/entrypoints/`   | 扩展入口点（popup、options、sidepanel、background、content） |
+| `src/pages/`         | 功能页面组件（懒加载）                                       |
+| `src/components/`    | 可复用 UI 组件                                               |
+| `src/components/ui/` | shadcn/ui 基础组件（button、dialog、select 等）              |
+| `src/providers/`     | React Context（Router、Theme 等）                            |
+| `src/hooks/`         | 自定义 React Hooks                                           |
+| `src/utils/`         | 工具函数与服务抽象                                           |
+| `src/types/`         | TypeScript 类型声明                                          |
+| `src/lib/`           | 通用工具函数（cn、utils）                                    |
+| `public/`            | 静态资源                                                     |

 ---

@@ -102,7 +102,7 @@ pages/FeatureName/

 ### 代码分割

-`wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组 vendor 依赖（vendor-react、vendor-i18n、vendor-qr、vendor-dnd、vendor-markdown），无需手动配置。
+`wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组 vendor 依赖（vendor-react、vendor-i18n、vendor-qr、vendor-dnd），无需手动配置。

 ### 代码风格

@@ -13,8 +13,6 @@ concurrency:
  cancel-in-progress: true

 jobs:
-  # 💡 1. 提速核心：前置基建节点（Infrastructure Initialization）
-  # 专门负责锁死环境、同步下载并缓存 node_modules，下游节点直接满血复用！
  setup:
    name: Prepare Dependencies
    runs-on: ubuntu-latest
@@ -29,7 +27,6 @@ jobs:
        with:
          node-version: '22'

-      # 建立基于 package-lock.json 唯一哈希的缓存大闸
      - name: Cache Node Modules
        id: cache-nodemodules
        uses: actions/cache@v4
@@ -47,7 +44,6 @@ jobs:
        id: cache-info
        run: echo "key=${{ runner.os }}-node-v22-${{ hashFiles('**/package-lock.json') }}" >> $GITHUB_OUTPUT

-  # 💡 2. 静态语法质检节点（依赖前置节点完成）
  lint:
    name: Lint
    runs-on: ubuntu-latest
@@ -70,7 +66,6 @@ jobs:
      - name: Run ESLint
        run: npm run lint

-  # 💡 3. 强类型守卫节点（2秒瞬时恢复，开箱即查）
  typecheck:
    name: TypeScript Check
    runs-on: ubuntu-latest
@@ -96,7 +91,6 @@ jobs:
      - name: Run TypeScript type check
        run: npm run typecheck

-  # 💡 4. 单元测试节点（无缝运行你刚刚修复完的 setupTests.ts 套件）
  test:
    name: Unit Tests
    runs-on: ubuntu-latest
@@ -122,16 +116,12 @@ jobs:
      - name: Run tests
        run: npm run test

-  # 💡 5. 多端分布式最终编译节点（Production Matrix Compliance）
  build:
    name: Build (${{ matrix.browser }})
    runs-on: ubuntu-latest
-    # 只有当 Linter、类型大闸、Vitest 单元测试全数满分通过，才放行最终打包编译
    needs: [ lint, typecheck, test ]
    strategy:
      matrix:
-        # 💡 完美对齐 WXT 跨端架构：将 firefox 同步纳入生产编译大矩阵，
-        # 如果 firefox 编译因任何多端不兼容挂掉，CI 会立刻拉起警报，防护力拉满！
        browser: [ chrome, firefox ]
      fail-fast: false
    steps:
@@ -149,7 +139,6 @@ jobs:
          path: node_modules
          key: ${{ runner.os }}-node-v22-${{ hashFiles('**/package-lock.json') }}

-      # 💡 动态代理编译指令：完美匹配 WXT / 各类多端打包器的标准构建命令
      - name: Generate WXT types
        run: npx wxt prepare