admin/docs/www/tech-stack.md

# 乐笙-Luxsin 产品官网 技术栈文档

## 项目概述

乐笙（Luxsin）产品官网，采用前后端分离架构。前端官网页面内容大部分由后台管理平台灵活配置，实现 CMS 级别的内容管理能力。

官网 CMS 管理功能并入现有的 **dashboard** 项目（耳机品牌与型号管理平台），共享同一套后端 API 和数据库，不再单独维护 admin 和 server。

## 架构总览

```
用户浏览器 ──→ Nuxt 4 SPA (www/web) ──→ Dashboard API (Express + Drizzle) ──→ MySQL (audio)
管理员浏览器 ──→ soybean-admin (dashboard/frontend) ──→ Dashboard API (Express + Drizzle) ──→ MySQL (audio)
```

- **Web 前端**（www/web）：面向用户的产品展示官网（SPA）
- **管理后台**（dashboard/frontend）：soybean-admin，新增「官网管理」菜单模块
- **API 服务**（dashboard/backend）：Express + TypeScript + Drizzle ORM，统一提供数据接口
- **数据库**：MySQL（复用现有 `audio` 数据库）

## 目录结构

```
www/
└── web/          # 前端官网（Nuxt 4）

dashboard/
├── backend/      # 统一 API 服务（Express + TypeScript + Drizzle + MySQL）
│   └── src/
│       ├── routes/www/   # 官网 CMS 接口 /api/www/*
│       ├── schemas/      # Drizzle 表定义
│       ├── services/
│       ├── middleware/
│       └── ...
├── frontend/     # 管理后台（soybean-admin，含官网内容管理）
└── ...

docs/
├── official/     # 官网相关文档
└── dashboard/    # dashboard 相关文档
```

---

## Web 前端 (`web/`)

| 技术 | 版本 | 说明 |
|------|------|------|
| Nuxt 4 | 4.5+ | 应用框架，SPA 模式，文件路由、自动导入、`app/` 源码目录规范 |
| Vue 3 | 3.5+ | UI 框架，Composition API + `<script setup>` |
| TypeScript | 5.x | 全量类型安全 |
| UnoCSS | 66+ | 原子化 CSS 引擎（presetWind3），与 Admin 统一 |
| Pinia | 4.x | 状态管理 |
| @nuxtjs/i18n | 10.x | 国际化（中英双语，自动检测 `i18n/locales/`） |
| ofetch | 内置 | HTTP 请求（Nuxt 内置） |
| @vueuse/nuxt | 14.x | 常用组合式工具函数（自动导入） |
| vue-router | 5.x | 路由（Nuxt 内置，history 模式） |
| Vite | 8.x | 构建工具（Nuxt 内置） |
| pnpm | 11.x | 包管理器 |

### 目录规范（Nuxt 4）

Nuxt 4 引入 `app/` 源码目录，将应用代码与项目根配置分离：

```
web/
├── app/              # 源码目录
│   ├── app.vue       # 入口
│   ├── assets/       # 静态资源
│   ├── components/   # 自动导入组件
│   ├── composables/  # 自动导入组合式函数
│   ├── layouts/      # 布局
│   ├── middleware/   # 路由中间件
│   ├── pages/        # 文件路由
│   ├── plugins/      # 插件
│   └── stores/       # Pinia 状态仓库
├── i18n/locales/     # 国际化语言文件（@nuxtjs/i18n v10 自动检测）
├── public/           # 公共静态资源
├── server/           # Nitro 服务端代码
├── nuxt.config.ts
└── uno.config.ts
```

### 设计原则

- SPA 模式渲染，通过 API 获取后台配置的内容数据
- 组件化开发，页面由可配置的区块（Section）组合而成
- 中英双语支持，路由级别的语言切换（中文默认无前缀，英文 `/en` 前缀）
- 响应式设计，适配桌面端和移动端
- 预留 SSR/SSG 升级能力（Nuxt 可无缝切换渲染模式）

---

## 管理后台（dashboard/frontend）

复用现有 dashboard 项目的 soybean-admin 前端，新增「官网管理」菜单模块。

| 技术 | 版本 | 说明 |
|------|------|------|
| soybean-admin | v2.2.0 | 管理后台 UI 框架 |
| Vue 3 | 3.5+ | UI 框架 |
| Vite | 8.x | 构建工具 |
| Naive UI | 2.44+ | UI 组件库 |
| UnoCSS | 66+ | 原子化 CSS |
| Pinia | 3.x | 状态管理 |
| vue-router | 5.x | 路由（history 模式） |
| vue-i18n | 11.x | 国际化 |
| TypeScript | 6.x | 类型安全 |
| pnpm | 10.5+ | 包管理器（workspace） |

### 新增功能模块（官网管理）

- 官网页面内容管理（Banner、产品、新闻、FAQ 等）
- 页面区块的增删改查与排序
- 媒体资源管理（图片、视频）
- 官网系统配置管理

---

## 后端 API 服务（dashboard/backend）

| 技术 | 说明 |
|------|------|
| Express 4 | Web 框架（保留现有） |
| TypeScript | 全量类型安全（从 JS 迁移） |
| Drizzle ORM | 类型安全 ORM，替代原 Sequelize |
| MySQL (mysql2) | 数据库（复用现有 `audio` 库） |
| Zod | 请求参数校验与类型推导 |
| tsx | TypeScript 运行/开发热重载 |
| pnpm | 包管理器 |

### API 路由规划

| 前缀 | 用途 | 鉴权 |
|------|------|------|
| `/api/www/*` | 官网前台接口（供 Nuxt 4 消费） | 公开访问 |
| `/api/admin/www/*` | 官网 CMS 管理接口（供 dashboard 前端消费） | JWT 鉴权 |
| `/api/*`（其他） | 现有 dashboard 业务接口 | JWT 鉴权 |

### API 设计原则

- RESTful 风格
- 统一响应格式：`{ code, data, message }`
- 与 soybean-admin 约定成功码 `0000`
- 前台接口公开，管理接口需 JWT 鉴权

---

## 数据库

| 项目 | 说明 |
|------|------|
| 数据库 | MySQL（复用现有 `audio` 库） |
| ORM | Drizzle ORM（mysql2 驱动） |
| 迁移 | drizzle-kit（Schema 变更自动生成迁移文件） |
| 命名规范 | 表名 snake_case，字段名 snake_case |
| 字符集 | utf8mb4 |

---

## 开发环境要求

| 工具 | 版本要求 |
|------|----------|
| Node.js | >= 20.19.0 |
| pnpm | >= 10.5.0 |
| MySQL | >= 8.0 |
| TypeScript | >= 5.x |

---

## 项目管理

两个独立项目，各自管理：

| 项目 | 路径 | 说明 |
|------|------|------|
| www | `www/` | 官网前端（Nuxt 4），独立 pnpm 项目 |
| dashboard | `dashboard/` | 管理后台 + API 服务，pnpm workspace（frontend + backend） |

---

## 部署方案（待定）

| 模块 | 候选方案 |
|------|----------|
| Web 前端（www/web） | Vercel / Cloudflare Pages / Nginx 静态托管 |
| 管理后台（dashboard/frontend） | Nginx 静态托管（现有方案） |
| API 服务（dashboard/backend） | Docker 容器（现有方案，端口 8083） |
| 数据库 | 现有 MySQL 实例 |

---

## 技术选型理由

### 为什么选 Nuxt 4（SPA 模式）？

- 与 dashboard 管理后台统一 Vue 生态，降低团队学习和维护成本
- `app/` 目录规范让项目结构更清晰，配置与源码分离
- 文件路由 + 自动导入提升开发效率
- 未来可无缝升级 SSR/SSG，无需重构
- @nuxtjs/i18n v10 提供更简洁的配置（自动检测 locale 文件）

### 为什么复用 dashboard 而非独立建 admin + server？

- dashboard 前端本身就是 soybean-admin，无需重复搭建
- 共享用户体系和权限管理，运营人员一个后台管理所有业务
- 减少项目数量，降低部署和维护成本
- 数据库统一为 MySQL，避免多数据源复杂度

### 为什么从 Sequelize 迁移到 Drizzle ORM？

- 类型安全，Schema 即类型定义，与 TypeScript 深度集成
- SQL-like API，学习成本低，性能透明
- 内置 drizzle-kit 迁移工具，版本化管理数据库变更（替代 `sequelize.sync()`）
- 轻量无依赖，不锁定数据库连接方案

### 为什么保留 Express 而非换 Hono？

- dashboard 后端已有大量 Express 路由和中间件，迁移 ORM 已足够
- Express 生态成熟，团队熟悉
- 避免同时迁移框架 + ORM + 语言，降低风险