From e4d66a2ac09912c9ff914c1d8043ccec225759fb Mon Sep 17 00:00:00 2001 From: YoungestSongMo <2130460579@qq.com> Date: Mon, 22 Jun 2026 09:42:29 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= =?UTF-8?q?=EF=BC=8C=E5=AE=9E=E7=8E=B0=E6=AF=8F=E4=B8=AA=E6=96=87=E4=BB=B6?= =?UTF-8?q?=E5=A4=B9=E7=9A=84REDME.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .codegraph/daemon.pid | 4 +- .gitignore | 8 +- PROJECT.md | 206 +++++++++++++++++++++++++++++------------- TODO.md | 1 + 4 files changed, 152 insertions(+), 67 deletions(-) diff --git a/.codegraph/daemon.pid b/.codegraph/daemon.pid index 15da5d8..6258f3a 100644 --- a/.codegraph/daemon.pid +++ b/.codegraph/daemon.pid @@ -1,6 +1,6 @@ { - "pid": 122144, + "pid": 17460, "version": "0.9.9", "socketPath": "\\\\.\\pipe\\codegraph-aef859f0205bacea", - "startedAt": 1781578435571 + "startedAt": 1781769813327 } diff --git a/.gitignore b/.gitignore index 0896f7e..ce1d510 100644 --- a/.gitignore +++ b/.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 diff --git a/PROJECT.md b/PROJECT.md index 9f7495c..ce25bca 100644 --- a/PROJECT.md +++ b/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（业务逻辑封装） -│ ├── 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） -│ ├── 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 生成 -├── 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 # 生成更新元信息 -├── package.json # 含 electron-builder 打包配置 -├── vite.config.ts -├── tsconfig.json -└── tailwind.config.ts +├── 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/ # 业务页面（按功能模块组织） +│ │ ├── 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 # 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 类型别名 +├── shared/ # 主进程 & 渲染进程共享 +│ ├── 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 打包配置 +└── 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，确保三处一致。 diff --git a/TODO.md b/TODO.md index 672d8be..c49560d 100644 --- a/TODO.md +++ b/TODO.md @@ -71,6 +71,7 @@ ### 文档 +- [x] 文件夹 README 文档（37 个文件夹全部覆盖，不进 Git） - [ ] API 接口文档（Swagger / 手动维护） - [ ] 组件文档（Storybook） - [ ] 用户操作手册