docs: 更新文档，实现每个文件夹的REDME.md

.codegraph/daemon.pid

@@ -1,6 +1,6 @@
 {
-  "pid": 122144,
+  "pid": 17460,
   "version": "0.9.9",
   "socketPath": "\\\\.\\pipe\\codegraph-aef859f0205bacea",
-  "startedAt": 1781578435571
+  "startedAt": 1781769813327
 }

.gitignore

@@ -6,7 +6,7 @@ yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 lerna-debug.log*
-
+.codegraph/*
 node_modules
 # vite打包输出
 dist
@@ -39,3 +39,9 @@ WORKLOG.md
 *open*.json
 response_*.json
 test-server/__pycache__/
+
+/src/vite-env.d.ts.tmp.444812.865037551ae0
+
+# 自动生成的文件夹 README 文档（根目录 README.md 保留）
+/**/README.md
+!/README.md

PROJECT.md

@@ -46,80 +46,159 @@
 
     4. 窗口间通信统一通过主进程转发（或使用 MessagePort 等 Electron 支持的机制），保持窗口独立性。
 
-- 路由与导航：主窗口为单页应用，使用 React Router v7+ 管理页面切换。**遵循 QT 多窗口模型映射原则**：
+- 路由与导航：主窗口为单页应用，不使用 React Router。所有页面切换通过事件总线 + PageDispatcher 实现：
     - 叠加层（设置、公告、素材库等）→ Modal/Drawer + 事件总线驱动，主页面不卸载
-    - 页面跳转（真正的视图切换）→ React Router，需跨页保持的状态放 Provider 或 localStorage
+    - NavBar 导航项点击 → `emit(OPEN_PAGE, { target, modalType })` → PageDispatcher 按 `PAGE_MAP` 注册表渲染对应容器
+    - 每个页面路径在 `PageDispatcher.PAGE_MAP` 中注册一行（target → { component, modalType, width, height }）
+    - 需跨页保持的状态放 Provider 或 localStorage
 
 - 辅助窗口（设置、预览、导入导出等）以 Modal/Drawer 叠加在主窗口之上，不与主窗口共享 DOM，但保持在同一个 React 组件树中以确保状态一致性。
 
 # 目录结构
 
+> 每个文件夹下均有 `README.md` 说明该目录的职责与代码边界（自动生成，不进 Git）。
+
 ```md
-├── electron/ # Electron 主进程
-│ ├── main.ts # 入口：窗口创建 / IPC 注册 / 生命周期
-│ ├── preload.ts # 预加载脚本（contextBridge）
-│ └── main/
-│ ├── updater.ts # 自定义更新（API 版本检查 + OSS 下载 + NSIS 安装）
-│ ├── logger.ts # 主进程日志核心（JSON Lines 写入 / 轮转 / 清理）
-│ ├── log-ipc.ts # 渲染进程日志 IPC 通道接收
-│ ├── net-request.ts # Electron net.request 的 axios 风格封装
-│ ├── menu/index.ts # 系统菜单
-│ └── utils/ # 平台判断 / 图标路径
-├── src/ # 渲染进程（React 19 SPA）
-│ ├── main.tsx # React 挂载点 + 全局错误捕获
-│ ├── App.tsx # 根组件（路由 + 登录弹窗）
-│ ├── components/ # 可复用组件（按职责分三层）
-│ │ ├── providers/ # 状态管理（App/Theme/SettingsProvider）
-│ │ ├── shell/ # 应用外壳（Layout/PageDispatcher/navbar/）
-│ │ └── ui/ # 通用 UI 原子（FloatingPanel/LegalTextModal）
-│ ├── hooks/ # 自定义 Hooks（业务逻辑封装）
+├── electron/                      # Electron 主进程 + 预加载
+│ ├── main.ts                      # 入口编排：窗口创建 / IPC 注册 / 生命周期
+│ ├── preload.ts                   # contextBridge：向渲染进程暴露安全 API
+│ ├── electron-env.d.ts            # 类型声明（APP_ROOT、Window 扩展）
+│ └── main/                        # 主进程核心模块
+│ │ ├── load-env.ts                # .env.{mode} + .env.local 加载器
+│ │ ├── logger.ts                  # 日志核心：JSON Lines / 每日轮转 / 批量冲刷
+│ │ ├── log-ipc.ts                 # 渲染进程日志 → 主进程日志桥接
+│ │ ├── net-request.ts             # Electron net.request 的 axios 风格封装
+│ │ ├── safe-storage-ipc.ts        # safeStorage 加密/解密 IPC handler
+│ │ ├── storage-ipc.ts             # 沙箱文件存储 IPC handler（heixiu-data/）
+│ │ ├── updater.ts                 # 自动更新：自定义 Provider + 平台 Updater
+│ │ ├── menu/index.ts              # 系统菜单（macOS Edit / Win 无菜单）
+│ │ └── utils/                     # 平台判断 / 图标路径
+│ └── preload/                     # 预加载脚本（contextBridge 桥接层）
+│   ├── device.ts                  # 硬件指纹采集（wmic/powershell | ioreg/sysctl）
+│   └── device_service.ts          # 设备信息缓存层（机器码/IP/MAC）
+├── src/                           # 渲染进程（React 19 + Vite + TypeScript）
+│ ├── main.tsx                     # React 挂载 + Provider 嵌套 + 全局错误捕获
+│ ├── App.tsx                      # 根组件：叠加层编排（登录/设置/页面调度）
+│ ├── vite-env.d.ts                # Vite 类型声明
+│ ├── components/                  # 通用组件层
+│ │ ├── providers/                 # 全局 Context Provider
+│ │ │ ├── AppProvider.tsx          # 认证状态（login/logout/Token 刷新）
+│ │ │ ├── ThemeProvider.tsx        # 亮/暗主题切换 + antd ConfigProvider
+│ │ │ └── SettingsProvider.tsx     # 本地持久化设置（存储路径等）
+│ │ ├── shell/                     # 应用外壳
+│ │ │ ├── Layout.tsx               # 全高 flex 列布局壳
+│ │ │ ├── PageDispatcher.tsx       # 通用页面调度器（Modal/Drawer/FloatingPanel）
+│ │ │ └── navbar/                  # 导航栏（nav-config → NavBar → NavItem）
+│ │ └── ui/                        # 通用 UI 原子组件
+│ │   ├── FloatingPanel.tsx        # 可拖拽非模态浮动面板
+│ │   └── LegalTextModal.tsx       # 法律/协议文本 Modal
+│ ├── hooks/                       # 自定义 Hooks
+│ │ ├── use-async.ts               # 通用异步基础设施（竞态/取消/门控）
+│ │ ├── use-api.ts                 # 业务 API Hooks（Banner/模型/任务/账户/财务）
+│ │ └── use-updater.ts             # 更新状态机（单例 IPC 监听）
+│ ├── infrastructure/              # 基础设施层
+│ │ └── storage/                   # 本地加密数据库（sql.js + safeStorage + IPC）
+│ │   ├── db-core.ts               # sql.js WASM 初始化 + 通用 CRUD
+│ │   ├── db-encrypt.ts            # 序列化 → safeStorage 加密 → IPC 写磁盘
+│ │   ├── schema.ts                # 6 张业务表 DDL（含索引）
+│ │   ├── task-store.ts            # 任务记录本地 CRUD
+│ │   ├── order-store.ts           # 订单记录本地 CRUD（充值 + VIP）
+│ │   ├── param-store.ts           # 参数历史快照（每模型最多 20 条）
+│ │   ├── media-store.ts           # 媒体缓存元数据管理
+│ │   ├── media-loader.ts          # 媒体下载与三级缓存策略
+│ │   ├── settings-store.ts        # 应用设置 key-value 存储
+│ │   ├── sync-manager.ts          # 分页同步游标管理
+│ │   ├── user-scope.ts            # 用户作用域隔离（JWT user_id）
+│ │   ├── ipc-file.ts              # 渲染进程端文件操作桥接
+│ │   └── index.ts                 # 统一入口：init/clear/stats
 │ ├── pages/                       # 业务页面（按功能模块组织）
-│ │ ├── home/ # 首页（panels/ features/ controls/ hooks/）
-│ │ ├── auth/ # 认证模块（登录/注册/忘记密码/修改密码）
-│ │ ├── settings/ # 设置面板（sections/）
-│ │ └── panels/ # NavBar 触发的面板页（Account/Billing/WechatWork）
-│ ├── router/index.tsx # HashRouter 路由配置
-│ ├── services/ # HTTP 请求封装
-│ │ ├── request.ts # Axios 封装 + 拦截器 + Token 刷新
-│ │ ├── types.ts # 自定义错误类型（RequestError / RefreshError）
-│ │ ├── auth-token.ts # refresh_token 管理
-│ │ └── modules/ # API 模块（auth / announcement）
+│ │ ├── auth/                      # 认证模块
+│ │ │ ├── index.tsx                # LoginPage Modal（登录/注册 Tabs）
+│ │ │ ├── components/              # 表单组件（LoginForm/RegisterForm/FormField/改密/忘记密码）
+│ │ │ ├── config/                  # 字段配置（login-fields/register-fields）+ 校验函数库
+│ │ │ └── hooks/                   # use-auth-state（偏好）/ use-sms-cooldown（短信冷却）
+│ │ ├── home/                      # 首页主工作区
+│ │ │ ├── HomePage.tsx             # 首页入口
+│ │ │ ├── HomeContent.tsx          # 三列可拖拽面板 + HomeContext.Provider
+│ │ │ ├── HomeContext.tsx          # 共享状态（选中模型/任务/分页）
+│ │ │ ├── panels/                  # 三列面板容器（Left/Center/Right）
+│ │ │ ├── features/                # 功能模块（Banner/ModelSelector/ModelInputForm/TaskHistory/OutputPreview）
+│ │ │ ├── controls/                # Widget 控件体系（12 种 Qt→React 映射 + WIDGET_MAP）
+│ │ │ └── hooks/                   # useModelUI（param_schema → UIFieldConfig）
+│ │ ├── panels/                    # NavBar 触发的功能面板页
+│ │ │ ├── AccountInfo.tsx          # 账户信息（用户/积分/套餐/统计）
+│ │ │ ├── BillingInfo.tsx          # 财务信息（余额 + 账单流水）
+│ │ │ ├── OrdersPage.tsx           # 订单明细（充值/VIP 双 Tab + 轮询）
+│ │ │ ├── RechargePage.tsx         # 积分充值（预设/自定义金额 + 支付追踪）
+│ │ │ ├── VipPage.tsx              # VIP 开通（激活码/套餐选购/权益预览）
+│ │ │ └── WechatWorkPage.tsx       # 企业微信二维码
+│ │ └── settings/                  # 设置页面
+│ │   ├── SettingsPage.tsx         # 设置 Modal 主页面
+│ │   └── sections/                # 6 个设置分区（主题/系统/更新/路径/密码/数据）
+│ ├── services/                    # 服务层（HTTP 请求封装）
+│ │ ├── request.ts                 # Axios 实例：拦截器 + Token 注入 + 401 刷新队列
+│ │ ├── auth-token.ts              # Token 生命周期（refresh_token 持久化/主动刷新）
+│ │ ├── auth-persistence.ts        # 登录表单偏好（用户名回填/记住密码/自动登录）
+│ │ ├── types.ts                   # 通用 API 类型（ApiResponse/RequestError/RefreshError）
+│ │ ├── cache/                     # 客户端缓存
+│ │ │ └── model-cache.ts           # 模型列表加密本地缓存
+│ │ └── modules/                   # API 模块（按业务域拆分）
+│ │   ├── auth.ts                  # 认证 API（登录/注册/刷新/用户/改密/短信）
+│ │   ├── models.ts                # 模型 API + 分类常量
+│ │   ├── task.ts                  # 任务 API（CRUD + 批量状态 + CSV + 轮询常量）
+│ │   ├── banner.ts                # Banner/轮播图 API
+│ │   ├── billing.ts               # 财务 API（余额/账单/导出）
+│ │   ├── payments.ts              # 支付 API（订单 CRUD + 状态映射）
+│ │   ├── vip-api.ts               # VIP API（激活/等级/订单）
+│ │   └── announcement.ts          # 公告 API + 类型标签颜色
 │ ├── theme/                       # 主题系统
-│ │ ├── tokens.ts # 设计令牌
-│ │ └── globals.css # Tailwind + 全局样式
-│ └── utils/ # 纯函数工具
-│ ├── event-bus.ts # 事件总线（on / off / emit + 日志钩子）
-│ ├── logger.ts # 渲染进程日志器（IPC 转发 / DEV 控制台）
-│ ├── ipc.ts # 安全 IPC 守卫（safeIpcOn / send / invoke）
-│ ├── platform.ts # 平台判定
-│ └── device.ts # 设备 ID 生成
+│ │ ├── tokens.ts                  # TypeScript 设计令牌
+│ │ ├── tokens.css                 # CSS 设计令牌（Tailwind @theme + CSS 变量亮/暗）
+│ │ ├── antd-theme.ts              # Ant Design ConfigProvider 主题配置（亮/暗）
+│ │ ├── transitions.css            # 主题切换过渡（View Transitions API + CSS fallback）
+│ │ ├── base.css                   # 全局重置（盒模型/滚动条/聚焦环/拖拽区域）
+│ │ └── globals.css                # 入口文件（按序导入以上 CSS）
+│ └── utils/                       # 渲染进程工具函数
+│   ├── event-bus.ts               # 事件总线（on/off/emit + 日志审计钩子）
+│   ├── ipc.ts                     # IPC 安全守卫（hasIpc → safeIpcOn/send/invoke）
+│   ├── logger.ts                  # 渲染进程日志（IPC 转发 | DEV 控制台）
+│   ├── platform.ts                # 平台判定（isMacOS/isWindows/isLinux）
+│   ├── device.ts                  # 设备 ID 生成与持久化（UUID v4）
+│   ├── safe-storage.ts            # 加密 localStorage 封装（safeStorage 桥接）
+│   ├── logo.ts                    # Logo 资产 URL 解析
+│   ├── pricing.ts                 # 成本计算（Python 六种定价模式移植）
+│   ├── enum-resolver.ts           # 枚举外观模式（7 模块标签/颜色统一解析）
+│   ├── display.ts                 # 金额/日期格式化
+│   └── type.ts                    # Nullable<T> 类型别名
 ├── shared/                        # 主进程 & 渲染进程共享
-│ ├── types/ # 类型定义（API / IPC / update / logging）
-│ ├── constants/ # 常量（IPC 通道 / version / app）
-│ └── utils/ # 共享工具
-│ ├── index.ts # debounce / throttle / compareVersions
-│ └── sanitize.ts # 日志脱敏工具（ID / 邮箱 / 手机 / 名称）
-├── scripts/ # 构建脚本
-│ ├── build.mjs # 构建总管
-│ ├── clean.mjs # 清理产物
-│ ├── upload-oss.mjs # OSS 上传
-│ ├── publish-release.mjs # 发布到 API
-│ └── generate-update-info.mjs # 生成更新元信息
+│ ├── constants/
+│ │ ├── app.ts                     # 应用名称/版本类型/窗口标题
+│ │ ├── ipc-channels.ts            # 全部 IPC 通道名称（三类命名空间）
+│ │ └── version.ts                 # 从 package.json 读取版本号
+│ ├── types/
+│ │ ├── index.ts                   # 通用类型（Platform/Theme/Edition/Update/Window）
+│ │ └── logging.ts                 # 日志类型（LogLevel/LogCategory/LogEntry）
+│ └── utils/
+│   ├── index.ts                   # 纯工具函数（debounce/throttle/compareVersions/deepClone）
+│   └── sanitize.ts                # 日志脱敏（token/密码/邮箱/手机/ID/金额）
+├── scripts/                       # 构建与发布脚本
+│ ├── clean.mjs                    # 清理构建产物
+│ ├── generate-update-info.mjs     # 生成 update-info.json（SHA512 + CHANGELOG）
+│ ├── upload-oss.mjs               # 上传安装包到阿里云 OSS
+│ └── publish-release.mjs          # 发布版本到后端 API
+├── build.mjs                      # electron-builder 构建总管
+├── vite.config.ts                 # Vite 构建配置
 ├── package.json                   # 含 electron-builder 打包配置
-├── vite.config.ts
-├── tsconfig.json
-└── tailwind.config.ts
+└── pnpm-workspace.yaml
 ```
 
 # 多窗口与平台判定
 
-- windowManager.ts 负责统一创建 BrowserWindow，根据环境变量/参数加载不同入口（如 src/main/index.html 或
-  src/sub/settings/index.html）。
+- 窗口管理由 `electron/main.ts` 统一负责：`createMainWindow()` 创建主窗口，`BrowserWindow` 通过 `contextIsolation: true` + `nodeIntegration: false` 运行沙箱化渲染进程。辅助窗口通过 `RENDERER_TO_MAIN.OPEN_SUB_WINDOW` IPC 通道按需创建。
 
-- src/utils/platform.ts 提供 isMacOS、isWindows 等函数（基于 navigator.userAgent 或 preload 暴露的 process.platform）。在主进程的
-  electron/main/utils/platform.ts 中直接使用 Node.js API。
+- 平台判定双端各有一份：`electron/main/utils/platform.ts`（主进程，直接使用 `process.platform`）和 `src/utils/platform.ts`（渲染进程，优先 `process.platform`，降级 `navigator.userAgent`）。
 
-- 打包配置 (package.json build 字段) 须针对平台设置不同的图标、签名策略、安装包格式。
+- 打包配置 (`package.json` build 字段) 须针对平台设置不同的图标、签名策略、安装包格式。
 
 # 代码风格
 
@@ -208,8 +287,7 @@
 
 # 样式与主题
 
-- 优先使用 Tailwind 工具类 完成布局与常规样式，自定义设计令牌应映射为 Tailwind 扩展（在 tailwind.config.ts 中配置
-  theme.extend）。
+- 优先使用 Tailwind 工具类完成布局与常规样式。自定义设计令牌在 `src/theme/tokens.css` 的 `@theme` 块中定义（Tailwind v4 语法），自动生成 `bg-primary-500`、`text-secondary` 等工具类。
 
 - Ant Design 组件样式通过 ConfigProvider 的 theme 属性覆盖，确保与 Tailwind 主题令牌同步。
   `ConfigProvider` 同时配置 `locale={zhCN}` 实现全局中文（分页器"条/页"等无需逐个组件设置）。
@@ -329,4 +407,4 @@ set UPDATE_API_URL=http://127.0.0.1:8000 && .\release\0.0.3\win-unpacked\船长
 
 - 新增窗口时，需同步说明窗口入口、预加载脚本、主进程创建逻辑及 IPC 通道注册。
 
-- 修改主题令牌时，需同步更新 tokens.ts、tailwind.config.ts 及 antd-theme.ts，确保三处一致。
+- 修改主题令牌时，需同步更新 tokens.ts、tokens.css 及 antd-theme.ts，确保三处一致。

TODO.md

@@ -71,6 +71,7 @@
 
 ### 文档
 
+- [x] 文件夹 README 文档（37 个文件夹全部覆盖，不进 Git）
 - [ ] API 接口文档（Swagger / 手动维护）
 - [ ] 组件文档（Storybook）
 - [ ] 用户操作手册