全新的 ui，soybean admin

2026-07-17 09:35:32 +08:00
parent e59d9c72ee
commit 1da6d72544
501 changed files with 11790 additions and 22638 deletions
@@ -7,6 +7,11 @@
 - [docker-compose.yml](file://docker-compose.yml)
 - [backend/package.json](file://backend/package.json)
 - [frontend/package.json](file://frontend/package.json)
+- [frontend_v2/package.json](file://frontend_v2/package.json)
+- [frontend_v2/pnpm-workspace.yaml](file://frontend_v2/pnpm-workspace.yaml)
+- [frontend_v2/tsconfig.json](file://frontend_v2/tsconfig.json)
+- [frontend_v2/vite.config.ts](file://frontend_v2/vite.config.ts)
+- [frontend_v2/uno.config.ts](file://frontend_v2/uno.config.ts)
 - [backend/src/app.js](file://backend/src/app.js)
 - [backend/src/config/env.js](file://backend/src/config/env.js)
 - [backend/src/config/loadEnv.js](file://backend/src/config/loadEnv.js)
@@ -19,6 +24,13 @@
 - [backend/src/models/index.js](file://backend/src/models/index.js)
 </cite>

+## 更新摘要
+**变更内容**
+- 新增 frontend_v2 前端架构支持，采用 pnpm workspaces 和 TypeScript 配置
+- 更新开发工作流以适配新的包结构和工具链
+- 增强前端构建系统和类型安全支持
+- 优化多包管理和依赖共享机制
+
 ## 目录
 1. [简介](#简介)
 2. [项目结构](#项目结构)
@@ -34,8 +46,10 @@
 ## 简介
 本指南面向首次接触项目的开发者，帮助你在最短时间内完成环境准备、依赖安装、数据库初始化、环境变量配置以及本地或容器化启动。文档同时提供 Docker Compose 的完整部署流程，并给出常见问题的排查建议与基础使用示例，涵盖添加品牌、创建型号、进行 OTA 更新的关键操作路径。

+**更新** 新增了 frontend_v2 现代化前端架构的支持，采用 pnpm workspaces 管理多包项目，TypeScript 提供类型安全，UnoCSS 实现原子化样式，Vite 提供极速开发体验。
+
 ## 项目结构
-项目采用前后端分离架构，后端为 Node.js + Express，前端为 Vue 3 + Vite，通过 Nginx 提供静态资源与反向代理。整体通过 Docker Compose 编排，后端容器暴露 8000 端口，前端容器暴露 80 端口并通过宿主端口映射对外提供服务。
+项目采用前后端分离架构，后端为 Node.js + Express，前端支持两种架构：传统 Vue 3 + Vite (frontend) 和现代化多包架构 (frontend_v2)，通过 Nginx 提供静态资源与反向代理。整体通过 Docker Compose 编排，后端容器暴露 8000 端口，前端容器暴露 80 端口并通过宿主端口映射对外提供服务。

 ```mermaid
 graph TB
@@ -54,26 +68,32 @@ REDIS["Redis"]
 end
 subgraph "前端服务"
 FRONTEND["Nginx Alpine"]
+FRONTEND_V2["frontend_v2<br/>pnpm workspaces + TypeScript"]
 end
 FE_PORT --> FRONTEND
+FE_PORT --> FRONTEND_V2
 BE_PORT --> BACKEND
 DATA_VOL -. 存储OTA升级包 .-> BACKEND
 FRONTEND --> |"反向代理 /api"| BACKEND
+FRONTEND_V2 --> |"反向代理 /api"| BACKEND
 BACKEND --> DB
 BACKEND --> REDIS
 NET --- BACKEND
 NET --- FRONTEND
+NET --- FRONTEND_V2
 ```

-图表来源
+**图表来源**
 - [docker-compose.yml:7-46](file://docker-compose.yml#L7-L46)
 - [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
 - [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
+- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)

-章节来源
+**章节来源**
 - [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
 - [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
 - [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
+- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)

 ## 核心组件
 - 后端入口与启动
@@ -84,8 +104,10 @@ NET --- FRONTEND
  - 路由集中注册，包含认证、品牌、型号、OTA、分享码日志、用户与仪表盘等模块；模型层定义了品牌、型号、OTA、分享码日志与系统用户等实体。
 - 日志与监控
  - 使用 winston 输出到控制台与文件；提供健康检查接口便于外部探活。
+- **新增** frontend_v2 现代化前端架构
+  - 基于 pnpm workspaces 的多包管理，支持 TypeScript 类型安全，UnoCSS 原子化样式，Vite 极速构建。

-章节来源
+**章节来源**
 - [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
 - [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
 - [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
@@ -94,6 +116,7 @@ NET --- FRONTEND
 - [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
 - [backend/src/routes/index.js:1-13](file://backend/src/routes/index.js#L1-L13)
 - [backend/src/models/index.js:1-8](file://backend/src/models/index.js#L1-L8)
+- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)

 ## 架构总览
 下图展示了从浏览器到后端 API 的典型请求链路，以及后端与数据库、缓存之间的交互。
@@ -115,7 +138,7 @@ B-->>F : "返回 JSON 响应"
 F-->>U : "返回响应"
 ```

-图表来源
+**图表来源**
 - [docker-compose.yml:13-38](file://docker-compose.yml#L13-L38)
 - [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
 - [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
@@ -131,12 +154,17 @@ F-->>U : "返回响应"
 - 本地安装（非容器）
  - 后端：在 backend 目录安装依赖并启动。
  - 前端：在 frontend 目录安装依赖并启动，开发服务器默认端口为 3000，/api 代理至后端 8083。
+  - **新增** frontend_v2：在项目根目录使用 pnpm install 安装所有包，支持多包开发和独立构建。
 - 容器安装
  - 使用 Docker Compose 一键编排，后端镜像基于 node:22-alpine，前端镜像基于 nginx:alpine，构建完成后自动启动。

-章节来源
+**更新** frontend_v2 采用现代化的多包架构，支持更好的代码复用和类型安全。
+
+**章节来源**
 - [backend/package.json:1-29](file://backend/package.json#L1-L29)
 - [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
+- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
+- [frontend_v2/pnpm-workspace.yaml:1-20](file://frontend_v2/pnpm-workspace.yaml#L1-L20)
 - [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
 - [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
 - [DEPLOY.md:259-269](file://DEPLOY.md#L259-L269)
@@ -155,7 +183,7 @@ F-->>U : "返回响应"
 - 加载机制
  - 后端启动前统一从根目录加载 .env；Docker 部署时由 compose env_file 注入，容器内不再读取本地 .env 文件。

-章节来源
+**章节来源**
 - [DEPLOY.md:190-204](file://DEPLOY.md#L190-L204)
 - [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
 - [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
@@ -167,7 +195,7 @@ F-->>U : "返回响应"
 - 连接参数
  - 默认连接 localhost:3306，数据库名与凭据可通过环境变量覆盖。

-章节来源
+**章节来源**
 - [backend/src/app.js:42-57](file://backend/src/app.js#L42-L57)
 - [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)

@@ -177,7 +205,7 @@ F-->>U : "返回响应"
 - 日志
  - 控制台与文件双通道输出，日志目录位于后端 src 下 logs。

-章节来源
+**章节来源**
 - [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
 - [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)

@@ -187,7 +215,7 @@ F-->>U : "返回响应"
 - 模型
  - 品牌、型号、OTA、分享码日志、系统用户等实体定义。

-章节来源
+**章节来源**
 - [backend/src/routes/index.js:1-13](file://backend/src/routes/index.js#L1-L13)
 - [backend/src/models/index.js:1-8](file://backend/src/models/index.js#L1-L8)

@@ -195,18 +223,24 @@ F-->>U : "返回响应"
 - 本地开发
  - 后端：在 backend 目录执行启动脚本，默认监听 8083。
  - 前端：在 frontend 目录执行启动脚本，默认监听 3000，/api 代理至 8083。
+  - **新增** frontend_v2：在项目根目录执行 pnpm dev 启动开发服务器，支持热重载和类型检查。
 - 容器化
  - 使用 docker compose up -d 启动；前端通过 8082 访问，后端通过 8083 访问；健康检查接口 /health 返回健康状态。
 - 健康检查
  - 访问 http://localhost:8083/health 验证后端是否正常运行。

-章节来源
+**更新** frontend_v2 提供更强大的开发体验，包括 TypeScript 类型检查、UnoCSS 原子化样式和更快的构建速度。
+
+**章节来源**
 - [backend/src/app.js:22-38](file://backend/src/app.js#L22-L38)
+- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
+- [frontend_v2/vite.config.ts:1-50](file://frontend_v2/vite.config.ts#L1-L50)
 - [DEPLOY.md:104-119](file://DEPLOY.md#L104-L119)

 ### Docker 容器化部署流程
 - 本地构建前端
  - 在 frontend 目录执行构建，产物生成于 dist。
+  - **新增** frontend_v2：在项目根目录执行 pnpm build 构建所有包，产物生成于各包的 dist 目录。
 - 上传到服务器
  - 使用上传脚本或手动 rsync 上传前端 dist、nginx.conf、后端源码与 docker-compose.yml。
 - 服务器构建与启动
@@ -214,9 +248,12 @@ F-->>U : "返回响应"
 - 验证
  - 使用 docker compose ps 与 docker compose logs -f backend 检查状态与日志；使用 curl http://localhost:8083/health 进行健康检查。

-章节来源
+**更新** frontend_v2 支持更灵活的构建策略，可以单独构建特定包或全量构建。
+
+**章节来源**
 - [DEPLOY.md:49-119](file://DEPLOY.md#L49-L119)
 - [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
+- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)

 ### 基本使用示例
 - 添加第一个品牌
@@ -228,10 +265,30 @@ F-->>U : "返回响应"
 - 注意事项
  - OTA 升级包存储目录需与后端容器挂载一致；S3 配置按需调整。

-章节来源
+**章节来源**
 - [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
 - [DEPLOY.md:206-223](file://DEPLOY.md#L206-L223)

+### frontend_v2 现代化前端架构
+- 项目结构
+  - 采用 pnpm workspaces 管理多个子包，每个包可独立开发和测试。
+  - 支持 TypeScript 类型安全，提供更好的开发体验和代码质量保障。
+  - 集成 UnoCSS 原子化样式框架，提升样式开发效率。
+- 包管理
+  - packages 目录下包含多个功能包：alova（API 客户端）、axios（HTTP 客户端）、color（颜色处理）、hooks（自定义钩子）、materials（UI 组件）、scripts（构建脚本）、uno-preset（样式预设）、utils（工具函数）。
+- 开发工作流
+  - 支持增量构建和热重载，开发体验更佳。
+  - 类型检查和 ESLint 规则确保代码质量。
+  - 支持按需加载和代码分割，优化打包体积。
+
+**新增** frontend_v2 提供了更现代化、类型安全的开发体验，适合大型项目和团队协作。
+
+**章节来源**
+- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
+- [frontend_v2/pnpm-workspace.yaml:1-20](file://frontend_v2/pnpm-workspace.yaml#L1-L20)
+- [frontend_v2/tsconfig.json:1-50](file://frontend_v2/tsconfig.json#L1-L50)
+- [frontend_v2/uno.config.ts:1-50](file://frontend_v2/uno.config.ts#L1-L50)
+
 ## 依赖关系分析
 后端应用的依赖关系如下所示：

@@ -246,7 +303,7 @@ APP --> MODELS["backend/src/models/index.js"]
 APP --> LOADENV["backend/src/config/loadEnv.js"]
 ```

-图表来源
+**图表来源**
 - [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
 - [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
 - [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
@@ -256,16 +313,55 @@ APP --> LOADENV["backend/src/config/loadEnv.js"]
 - [backend/src/models/index.js:1-8](file://backend/src/models/index.js#L1-L8)
 - [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)

+**新增** frontend_v2 的依赖关系更加模块化，支持更好的代码复用和维护。
+
+```mermaid
+graph TB
+subgraph "frontend_v2 主包"
+MAIN["package.json"] --> WORKSPACE["pnpm-workspace.yaml"]
+MAIN --> TS_CONFIG["tsconfig.json"]
+MAIN --> VITE_CONFIG["vite.config.ts"]
+MAIN --> UNO_CONFIG["uno.config.ts"]
+end
+subgraph "子包"
+ALOVA["packages/alova"]
+AXIOS["packages/axios"]
+COLOR["packages/color"]
+HOOKS["packages/hooks"]
+MATERIALS["packages/materials"]
+SCRIPTS["packages/scripts"]
+UNOPRESET["packages/uno-preset"]
+UTILS["packages/utils"]
+end
+WORKSPACE --> ALOVA
+WORKSPACE --> AXIOS
+WORKSPACE --> COLOR
+WORKSPACE --> HOOKS
+WORKSPACE --> MATERIALS
+WORKSPACE --> SCRIPTS
+WORKSPACE --> UNOPRESET
+WORKSPACE --> UTILS
+```
+
+**图表来源**
+- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
+- [frontend_v2/pnpm-workspace.yaml:1-20](file://frontend_v2/pnpm-workspace.yaml#L1-L20)
+- [frontend_v2/tsconfig.json:1-50](file://frontend_v2/tsconfig.json#L1-L50)
+- [frontend_v2/vite.config.ts:1-50](file://frontend_v2/vite.config.ts#L1-L50)
+- [frontend_v2/uno.config.ts:1-50](file://frontend_v2/uno.config.ts#L1-L50)
+
 ## 性能注意事项
 - 日志轮转：服务日志最大大小与保留文件数已在 compose 中配置，避免日志过大影响磁盘。
 - 端口映射：前端与后端端口映射需与 Nginx 代理配置保持一致，避免代理失败导致性能下降。
 - 缓存命中：合理设置 Redis 参数与数据库连接池，提升查询性能。
 - 构建优化：前端构建产物仅需上传，避免重复构建；后端镜像使用 pnpm 与只读依赖锁文件，保证构建一致性。
+- **新增** frontend_v2 性能优化：支持增量构建、代码分割和按需加载，显著提升开发体验和构建速度。

-章节来源
+**章节来源**
 - [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
 - [frontend/Dockerfile:1-32](file://frontend/Dockerfile#L1-L32)
 - [backend/Dockerfile:1-20](file://backend/Dockerfile#L1-L20)
+- [frontend_v2/vite.config.ts:1-50](file://frontend_v2/vite.config.ts#L1-L50)

 ## 故障排除指南
 - 前端页面空白
@@ -278,20 +374,37 @@ APP --> LOADENV["backend/src/config/loadEnv.js"]
  - 重新创建后端容器以加载新环境变量。
 - 停止服务
  - 使用 docker compose down 停止所有服务。
+- **新增** frontend_v2 常见问题
+  - pnpm 版本过低：确保使用 pnpm v8+ 以支持 workspaces。
+  - TypeScript 类型错误：检查 tsconfig.json 配置和类型定义。
+  - 构建失败：清理 node_modules 后重新安装依赖。
+  - 开发服务器无法启动：检查端口占用和配置文件语法。

-章节来源
+**章节来源**
 - [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)
+- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)
+- [frontend_v2/tsconfig.json:1-50](file://frontend_v2/tsconfig.json#L1-L50)

 ## 结论
 通过本指南，你可以快速完成环境准备、依赖安装、数据库初始化与容器化部署，并掌握常见问题的排查方法。建议在正式环境中完善安全配置（如 JWT 密钥、管理员密码、S3 权限等），并结合日志与健康检查持续监控系统运行状态。

+**更新** frontend_v2 的引入为项目带来了更现代化的开发体验，包括类型安全、更好的包管理和更快的构建速度，适合长期维护和团队协作。
+
 ## 附录
 - 本地开发命令参考
  - 后端：在 backend 目录执行启动脚本，默认监听 8083。
  - 前端：在 frontend 目录执行启动脚本，默认监听 3000，/api 代理至 8083。
+  - **新增** frontend_v2：在项目根目录执行 pnpm dev 启动开发服务器，支持热重载和类型检查。
 - 健康检查
  - 访问 http://localhost:8083/health 获取后端健康状态。
+- **新增** frontend_v2 常用命令
+  - 安装依赖：pnpm install
+  - 开发模式：pnpm dev
+  - 构建生产版本：pnpm build
+  - 类型检查：pnpm type-check
+  - 代码格式化：pnpm format

-章节来源
+**章节来源**
 - [DEPLOY.md:259-269](file://DEPLOY.md#L259-L269)
- [backend/src/app.js:31-38](file://backend/src/app.js#L31-L38)
+- [backend/src/app.js:31-38](file://backend/src/app.js#L31-L38)
+- [frontend_v2/package.json:1-50](file://frontend_v2/package.json#L1-L50)