更新 wiki

2026-07-17 17:17:22 +08:00
parent 1da6d72544
commit d292c23dc0
159 changed files with 2918 additions and 2735 deletions
@@ -1,6 +1,6 @@
 schema_version: 1
 module_path: ""
-title: Luxsin Audio Dashboard 全栈工程
+title: Audio Dashboard 全栈项目根（前后端 + 部署编排）
 scope: []
 source_files: []
 depends_on: []
@@ -0,0 +1 @@
+Node.js 22 (Alpine) + Express + Sequelize + Redis + Meilisearch + AWS S3；前端 Vite + Vue3 + Naive UI + UnoCSS + Alova；容器编排使用 Docker Compose，Nginx 托管静态资源。
@@ -0,0 +1,6 @@
+仓库为 monorepo 根目录，按职责拆分为三个顶层子工程：
+- `backend/`：Express + Sequelize 后端，入口 `src/app.js`，按领域分层组织——`config/` 加载数据库、Redis、日志等运行时配置；`models/` 定义 Sequelize 模型并通过 `index.js` 统一导出；`routes/` 暴露 REST 接口；`services/` 封装外部依赖（Curve 客户端、S3/OSS 存储、Meilisearch、OTA 存储、用户初始化）；`middleware/` 提供鉴权与请求体大小限制；`validators/` 使用 zod 校验入参；`utils/` 集中 JWT 与密码工具。
+- `frontend/`：基于 Vite + Vue3 + Naive UI 的管理后台，包含 `packages/` 下的内部 pnpm workspace 子包（alova、axios、hooks、materials、scripts、uno-preset、utils），业务路由与页面位于 `src/views/`，状态由 Pinia store 管理，API 调用集中在 `src/service/api`。
+- `autoeq/`：存放历史测量数据 CSV/TXT 与生成脚本，作为离线参考数据集。
+
+部署层由根级 `docker-compose.yml` 编排两个服务：`backend` 基于 `backend/Dockerfile` 构建 Node 镜像，`frontend` 直接使用 `nginx:alpine` 挂载 `frontend/dist` 静态资源，两者共享 `audio-network` 网络并通过 `/api` 反向代理通信；宿主机卷 `/data/projects/source` 用于 X9 OTA 升级包持久化。本地开发可通过 `pnpm --dir frontend build && ./scripts/upload.sh all` 一键构建并上传至服务器。
@@ -0,0 +1 @@
+音频设备曲线与 OTA 升级管理后台，采用 Node.js 后端 + Vue3 前端双包结构，通过 Docker Compose 编排 Nginx 与 API 服务。
@@ -0,0 +1 @@
+首次部署需在服务器 `/data/project/dashboard/` 创建 `.env`（参考 `.env.example`），然后执行 `./scripts/upload.sh all` 上传前端 dist、后端源码与 compose 文件，再在服务器上运行 `docker compose build --no-cache backend && docker compose up -d`。本地非 Docker 开发时，根目录 `.env` 中设置 `PORT=8083`，分别启动 `cd backend && pnpm start` 与 `cd frontend && pnpm dev`。
@@ -0,0 +1,5 @@
+- 后端按领域分层：每个实体对应独立的 `models/<Entity>.js`、`routes/<entity>.js`、`validators/<entity>.js`，并在 `models/index.js` 中统一注册关联。
+- 环境变量通过 `backend/src/config/loadEnv.js` 集中加载，所有模块从该配置对象读取而非直接访问 `process.env`。
+- 对外响应统一经 `backend/src/utils/response.js` 包装，保持 `{ code, message, data }` 一致结构。
+- 前端 API 调用集中在 `frontend/src/service/api/*.ts`，通过统一的 `frontend/src/service/request/` 封装的 alova 实例发起请求。
+- Docker 部署时容器内端口固定为 8000，宿主机映射到 8083，Nginx 将 `/api` 反向代理到 `http://backend:8000`。
@@ -0,0 +1,66 @@
+---
+kind: build_system
+name: Docker Compose 编排与多阶段构建部署
+category: build_system
+scope:
+    - '**'
+source_files:
+    - docker-compose.yml
+    - backend/Dockerfile
+    - frontend/Dockerfile
+    - scripts/upload.sh
+    - DEPLOY.md
+    - backend/package.json
+    - frontend/package.json
+    - frontend/vite.config.js
+    - frontend_v2/package.json
+---
+
+## 构建系统概览
+
+本项目采用 Docker Compose 作为统一的编排与部署方案，将前端（Nginx 静态站点）与后端（Node.js API）打包为两个容器服务，通过 .env 文件集中注入运行时配置。
+
+### 核心工具链
+- 包管理: pnpm v11.5.2（通过 packageManager 字段锁定版本）
+- 前端构建: Vite 6 + Vue3，输出到 frontend/dist/
+- 后端运行: Node.js 22 Alpine 镜像，直接执行 src/app.js
+- 容器编排: docker-compose.yml 定义 backend、frontend 两个服务
+- 部署脚本: scripts/upload.sh 基于 rsync 同步代码到远程服务器
+
+### 构建流程
+
+前端（frontend）：
+- 本地 pnpm build 生成静态资源至 dist/
+- Dockerfile 使用多阶段构建：node:18-alpine 构建 → nginx:alpine 托管
+- 生产环境通过 Nginx 提供静态文件，并将 /api 反向代理到后端
+
+后端（backend）：
+- Dockerfile 基于 node:22-alpine，仅安装 --prod 依赖
+- 入口为 src/app.js，监听端口 8000（由 compose 覆盖）
+- 支持本地开发 pnpm dev（nodemon 热重载）
+
+前端_v2（Soybean Admin 模板）：
+- 独立的 pnpm workspace 工程，包含 packages/ 共享模块
+- 使用 TypeScript + UnoCSS + NaiveUI，构建命令 vite build --mode prod
+- 当前未集成到主部署流程，属于独立演进分支
+
+### 部署架构
+客户端 → Nginx(8082) → /api → backend:8000 (Node.js)
+                    ↘ 静态文件 ← frontend/dist/
+
+环境变量统一通过根目录 .env 注入（数据库、JWT、S3、Redis、OTA 等）
+OTA 升级包通过卷挂载 /data/projects/source 持久化
+日志使用 json-file 驱动，限制单文件 10MB、最多 5 个文件
+
+### 发布流程
+1. 本地构建前端：cd frontend && pnpm build
+2. 上传代码：./scripts/upload.sh all（rsync 同步 dist、src、compose）
+3. 服务器构建并启动：docker compose build --no-cache backend && docker compose up -d
+
+也可分别更新：仅前端 restart frontend，仅后端 build backend && up backend。
+
+### 开发者约定
+- 所有构建产物不提交 Git（dist/、node_modules/ 在 .gitignore）
+- 依赖锁定文件 pnpm-lock.yaml 必须随源码一起上传
+- 环境变量 .env 仅在服务器维护，不纳入版本控制
+- 修改 compose 后需重新上传 docker-compose.yml 并重启服务
@@ -1,9 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/shared_packages/http_clients
-title: HTTP 客户端抽象层（Alova & Axios 双实现）
-scope:
-    - frontend_v2/packages/alova/
-    - frontend_v2/packages/axios/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-Alova 3.5.1（含 `alova/vue`、`alova/fetch`、`alova/client` 插件）与 Axios 1.16.0 + `axios-retry` 4.5.0；参数序列化使用 `qs` 6.15.1，ID 生成来自 `@sa/utils` 的 `nanoid`。
@@ -1,5 +0,0 @@
-本模块由两个并列的独立 npm 包组成，分别以 `@sa/alova` 和 `@sa/axios` 暴露：
- `packages/alova/src/index.ts` 通过 `createAlova` + `alova/client.createServerTokenAuthentication` 组合出带自动 token 刷新能力的实例；`beforeRequest` 挂接用户 `onRequest`，`responded` 中调用 `isBackendSuccess` / `transformBackendResponse` 判定业务成功并转换数据，失败则抛出带 `BACKEND_ERROR_CODE` 的错误。
- `packages/axios/src/index.ts` 基于 `axios.create` 构建，内部用 `axios-retry` 注入重试，在 request interceptor 中生成 `REQUEST_ID_KEY` 并通过 `AbortController` 收集待取消请求，在 response interceptor 中执行 `transformResponse`、`isBackendSuccess` 判断与 `onError` 回调；同时导出 `createRequest`（Promise 风格）与 `createFlatRequest`（返回 `{ data, error, response }` 扁平结构）两种调用形态。
- 配置与类型解耦：`options.ts` 负责合并默认选项与 axios 基础配置（10s 超时、`application/json`、`qs.stringify` 序列化、`validateStatus=isHttpSuccess`），`shared.ts` 提供 `isHttpSuccess`、`transformBlobToJson`、`transformArrayBufferToJson` 等共享工具，`type.ts` 定义 `RequestOption`、`RequestInstance`、`FlatRequestInstance` 等对外契约。
- 依赖方向单向：两包均只依赖 `@sa/utils`（用于 `nanoid`），不互相引用；`alova` 子包额外通过 `src/fetch.ts`、`src/client.ts`、`src/mock.ts` 将 `alova/fetch`、`alova/client`、`@alova/mock` 重新导出，作为可选扩展入口。
@@ -1 +0,0 @@
-为前端提供 Alova 与 Axios 两套可插拔的 HTTP 客户端封装，统一注入鉴权刷新、后端响应校验、错误处理与请求取消等横切能力。
@@ -1,4 +0,0 @@
- 对外暴露的工厂函数（`createAlovaRequest`、`createRequest`、`createFlatRequest`）均采用泛型 `<ResponseData, ApiData, State>` 三参形式，使底层响应类型、业务 API 类型与实例状态类型可独立推导。
- 通过 `RequestOption` / `RequestOptions` 钩子对象注入横切逻辑：`onRequest` 修饰请求头、`isBackendSuccess` 判定业务成功、`onError` 统一错误处理、`transform`/`transformBackendResponse` 做数据转换，保持核心流程不变而行为可插拔。
- 业务错误统一包装为带 `code = BACKEND_ERROR_CODE` 的错误对象，并在拦截器/`responded` 中主动 `throw` 或 `reject`，让上层仅凭 code 即可区分网络错误与后端业务错误。
- 默认配置通过独立的 `createDefaultOptions` / `createAxiosConfig` 工厂合并，所有可覆盖项先赋默认值再 `Object.assign(options)`，避免 undefined 覆盖。
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/shared_packages/build_scripts
-title: Soybean Admin CLI 构建脚本包
-scope:
-    - frontend_v2/packages/scripts/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-tsx + cac(命令行解析) + c12(配置加载) + execa(子进程) + bumpp(版本管理) + @soybeanjs/changelog(变更日志) + enquirer(交互式提示) + picomatch(路径匹配) + rimraf(删除)。
@@ -1,5 +0,0 @@
-单包可执行 CLI，入口为 `bin.ts`（shebang 通过 tsx 直接运行），加载 `src/index.ts` 中的 `setupCli()`；基于 `cac` 注册 7 个子命令（cleanup / update-pkg / git-commit / git-commit-verify / changelog / release / gen-route），每个子命令对应 `src/commands/` 下的独立文件并通过 `index.ts` 统一 re-export。
-
-配置层使用 `c12` 的 `loadConfig({ name: 'soybean' })` 从项目根目录或 `package.json#soybean` 合并默认值，由 `src/config/index.ts` 的 `loadCliOptions` 暴露给各命令消费。
-
-共享能力集中在 `src/shared/index.ts`（如 `execCommand` 包装 execa）和 `src/types/index.ts`（定义 CliOption、Lang 等类型），`locales` 提供多语言文案。依赖方向单向：`bin → index → commands/* ← config/shared/types/locales`，命令之间互不引用，仅通过 CLI 选项聚合参数。
@@ -1 +0,0 @@
-提供 @sa/scripts 命令行工具，封装清理、依赖升级、Conventional Commits 校验与生成、Changelog 生成、版本发布及路由代码生成等开发辅助命令。
@@ -1 +0,0 @@
-安装后通过 `pnpm sa <command>` 调用；CLI 全局配置键名为 `soybean`，可从项目根 `soybean.config.*` 文件或 `package.json#soybean` 注入覆盖默认值。
@@ -1,3 +0,0 @@
- 每个子命令拆分为 `src/commands/<name>.ts` 单一职责文件，再通过 `src/commands/index.ts` 集中 re-export，主入口以对象字面量 `{ desc, action }` 形式注册到 cac。
- 所有外部命令执行统一走 `src/shared/index.ts` 的 `execCommand` 包装器，避免在各命令中直接 import execa。
- CLI 行为的可变部分一律经 `loadCliOptions()` 从 c12 配置源加载，命令函数只消费返回的 options 对象，不在内部硬编码路径或 glob。
@@ -1,10 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/shared_packages/ui_kit
-title: UI 基础共享包（颜色、物料与 UnoCSS 预设）
-scope:
-    - frontend_v2/packages/color/
-    - frontend_v2/packages/materials/
-    - frontend_v2/packages/uno-preset/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-Vue 3 + TypeScript；颜色计算使用 `colord@2.9.3`；滚动条基于 `simplebar-vue@2.4.2`；样式采用 CSS Modules（经 `typed-css-modules` 生成类型）；UnoCSS 自定义 Preset 通过 `@unocss/core` 的 `Preset<Theme>` 接口扩展。
@@ -1,5 +0,0 @@
-本模块由三个独立的 pnpm workspace 子包组成，彼此无相互依赖，统一通过 `typesVersions` + `exports` 将源码路径映射给消费者：
- `@sa/color`：以 `src/constant/palette.ts` 中的 Tailwind 风格色板数据为根基，`src/shared/colord.ts` 封装 `colord` 库做颜色转换，`src/palette/antd.ts` 与 `recommend.ts` 分别实现 Ant Design 算法与推荐色阶生成，对外暴露 `getColorPalette` / `getPaletteColorByNumber` 等工具函数。
- `@sa/materials`：纯 Vue 3 组件集合，按功能拆分为 `libs/admin-layout`（后台布局容器，导出常量 `LAYOUT_MAX_Z_INDEX`、`LAYOUT_SCROLL_EL_ID`）、`libs/page-tab`（按钮/Chrome/滑块三种标签页实现）和 `libs/simple-scrollbar`（基于 `simplebar-vue` 的滚动条封装），所有组件通过 `src/index.ts` 统一再导出，并附带 `typed-css-modules` 生成的 `.css.d.ts` 类型文件。
- `@sa/uno-preset`：零运行时依赖，仅导出 `presetSoybeanAdmin()` 工厂函数，在 `shortcuts` 中集中定义 flex/absolute/fixed 等常用组合类名，供 UnoCSS 配置引入。
-依赖方向单向向下：color → colord/@sa/utils；materials → @sa/utils/simplebar-vue；uno-preset 无运行时依赖。
@@ -1 +0,0 @@
-聚合项目级颜色系统、通用 Vue 物料组件以及 UnoCSS 自定义预设，为上层应用提供一致的视觉与布局能力。
@@ -1,4 +0,0 @@
- 每个子包均通过 `package.json` 的 `typesVersions` 将 `*` 映射到 `./src/*`，使消费者能直接 import 子路径而无需编译产物。
- 子包入口 `src/index.ts` 仅做 re-export 聚合，不承载业务逻辑，保持单一职责。
- 颜色相关 API 同时支持 `recommended` 布尔开关，在内部切换 Ant Design 算法与推荐色阶两条分支。
- Material 组件目录遵循 `index.vue` + `index.module.css` + `shared.ts` 的固定结构，并通过同名 `index.ts` 统一导出。
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/shared_packages
-title: Soybean Admin 前端共享包集合
-scope:
-    - frontend_v2/packages/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-pnpm workspace 多包管理；TypeScript 全量使用；Vue 3 生态（simplebar-vue、alova 3、axios 1.x）；colord 统一颜色运算；localforage + crypto-js 提供持久化与加密原语。
@@ -1,5 +0,0 @@
-本目录是 frontend_v2 的 monorepo packages，所有子包通过 workspace:* 相互依赖并由顶层 pnpm/npm workspace 统一版本管理（各包版本号同步为 2.2.0）。
- 依赖分层：@sa/utils 作为最底层纯函数库被 alova、axios、color、hooks、materials 共同引用；@sa/axios 在 hooks 之上提供请求封装；alova 与 axios 并列提供双实现，由上层应用按需选择。
- 发布契约：每个包均声明 typesVersions + exports 字段，将 src/index.ts 映射到包根导出，并暴露如 alova 的多入口（./fetch、./client、./mock），保证 IDE 类型推导与 tree-shaking 一致。
- 构建/运行解耦：@sa/scripts 仅作为 devDependency 暴露 bin 命令 sa，不参与运行时依赖，由项目根或子应用直接调用，避免污染业务包体积。
- UI 层组合：@sa/color 与 @sa/uno-preset 分别输出颜色计算与 UnoCSS 自定义预设，@sa/materials 基于它们提供 Vue 组件，三者共同构成视觉系统。
@@ -1 +0,0 @@
-以 @sa/* 命名空间聚合 HTTP 客户端、UI 物料、运行时 Hook、颜色与样式预设及 CLI 脚本等可复用前端基础能力。
@@ -1,3 +0,0 @@
- 所有包统一采用 @sa/<scope> 命名空间，版本号随主工程同步递增
- 每个包同时声明 typesVersions 与 exports，src/index.ts 作为默认入口，复杂包按功能拆分多入口
- 运行时包之间通过 workspace:* 引用内部依赖，禁止硬编码版本号
@@ -1,9 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/shared_packages/runtime_helpers
-title: 运行时辅助包（Hooks 与工具函数）
-scope:
-    - frontend_v2/packages/hooks/
-    - frontend_v2/packages/utils/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-Vue 3 Composition API（仅 hooks 包使用）；加密使用 crypto-js AES，深拷贝使用 klona，ID 生成使用 nanoid v5，持久化存储使用 localforage（支持 localstorage / indexedDB / webSQL 三种驱动）。
@@ -1,4 +0,0 @@
-本模块由两个独立的 pnpm workspace 子包组成：
- `@sa/hooks`：基于 Vue 3 Composition API 的 Hook 集合，通过 `src/index.ts` 统一导出 `useBoolean`、`useLoading`、`useCountDown`、`useContext`、`useSvgIconRender`、`useTable`；其中 `use-request` 是对上层 `@sa/axios` 的薄封装，将 `createFlatRequest` 返回的 Promise 转为 `{ loading, data, error }` 响应式对象并复用内部 `useLoading`；`use-table` 则组合 `useLoading` 与 `useBoolean`，提供分页/列显隐/空态等表格通用逻辑。
- `@sa/utils`：无框架依赖的工具库，通过 `src/index.ts` 聚合导出 `crypto`（基于 crypto-js 的 AES 类）、`storage`（基于 localforage 的 createLocalforage 与原生 localStorage/sessionStorage 的 createStorage）、`nanoid`、`klona`。
-依赖方向单向：`@sa/hooks` 依赖 `@sa/utils` 与 `@sa/axios`，`@sa/utils` 不反向依赖 hooks，二者均通过 package.json 的 `exports` + `typesVersions` 指向 `src/*`，以 TS 源码形式被上层消费。
@@ -1 +0,0 @@
-为前端应用提供可复用的 Vue 组合式 Hook 与通用工具函数，封装请求、表格、状态、加密与持久化等运行时能力。
@@ -1,4 +0,0 @@
- 每个功能按文件拆分并以默认导出暴露，再通过 `src/index.ts` 集中 re-export，对外只暴露 barrel 入口。
- Hook 返回值遵循统一的 `{ loading, data, error }` 或 `{ loading, bool }` 结构，并通过内部 `useLoading` / `useBoolean` 管理状态。
- 工具函数采用工厂模式（如 `createStorage`、`createLocalforage`、`Crypto` class），通过泛型 `<T extends object>` 在调用处推导键类型，实现类型安全的 set/get/remove。
- JSON 序列化读写一律包裹 try/catch，解析失败时返回 null 而非抛出异常，保证上层调用安全。
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2
-title: Soybean Admin 前端应用（Vite + Vue3 多包工程）
-scope:
-    - frontend_v2/
-source_files: []
-depends_on: []
-related_to: []
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/ui_framework/hooks
-title: Vue 组合式 Hooks 库
-scope:
-    - frontend_v2/src/hooks/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-Vue 3 Composition API + TypeScript；表格基于 `naive-ui` 的 `TableColumn` 类型；图表使用按需引入的 `echarts/core` + `CanvasRenderer`；第三方能力来自 `@sa/hooks`（`useLoading`、`useCountDown`、`useBoolean`、`useTable`、`useSvgIconRender`）与 `@vueuse/core`（`useElementSize`）。
@@ -1,5 +0,0 @@
-模块按职责分为两个子目录：
- `common/`：通用能力，不依赖具体业务状态。`table.ts` 基于 `@sa/hooks` 的 `useTable` 二次封装出 `useNaiveTable` / `useNaivePaginatedTable` / `useTableOperate`，并内置列显隐控制（`getColumnChecks`/`getColumns`）与分页参数联动；`echarts.ts` 通过 `effectScope` 管理生命周期，监听 `useElementSize` 尺寸变化与主题切换，统一注册 ECharts 组件与渲染器后暴露 `useEcharts`；`form.ts` 集中定义正则规则与 Naive UI 表单校验辅助；`router.ts` 在 setup 与非 setup 上下文间切换 `vue-router` 实例，提供 `toLogin`/`redirectFromLogin` 等登录流方法；`icon.ts` 仅是对 `@sa/hooks` 中 `useSvgIconRender` 的薄包装。
- `business/`：面向业务场景。`auth.ts` 读取 `@/store/modules/auth` 中的按钮权限做 `hasAuth` 判断；`captcha.ts` 组合 `useLoading` + `useCountDown` 实现验证码倒计时与手机号校验。
-
-依赖方向：hooks 内部可访问 store（`themeStore`、`appStore`、`authStore`）、国际化 `$t`、全局消息 `window.$message` 以及 `@sa/*` 工具包，但不被 store 或 API 层反向依赖，属于纯消费层。
@@ -1 +0,0 @@
-为前端应用提供通用与业务相关的 Vue3 组合式函数，封装表格、图表、表单、路由及认证等跨页面复用逻辑。
@@ -1,5 +0,0 @@
- 所有需要响应式副作用的 hook 都通过 `const scope = effectScope()` 包裹 watch，并在 `onScopeDispose` 中调用 `scope.stop()` 清理，避免悬挂监听。
- 对外暴露的 ref 优先使用 `shallowRef`，仅在需要深度响应时回退到 `ref`，以减少大型对象（如 ECharts 实例、表格数据）的开销。
- 用户提示统一走 `window.$message?.success/error` 与 `@/locales` 的 `$t` 进行 i18n 文案输出，不在 hook 内硬编码字符串。
- 对可选回调采用解构默认值形式（如 `onRender = instance => {...}`），使 hook 具备开箱即用的默认行为同时允许覆盖。
- 针对 Naive UI 的类型（`FormInst`、`TableColumn`、`PaginationProps`）全部以泛型参数透传，保持 hook 与具体业务数据类型的解耦。
@@ -1,11 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/ui_framework
-title: Vue3 前端应用 UI 框架层
-scope:
-    - frontend_v2/src/components/
-    - frontend_v2/src/layouts/
-    - frontend_v2/src/hooks/
-    - frontend_v2/src/plugins/
-source_files: []
-depends_on: []
-related_to: []
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/ui_framework/components
-title: 业务与通用 UI 组件库
-scope:
-    - frontend_v2/src/components/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-Vue 3 `<script setup lang="ts">` + TypeScript；UI 框架 Naive UI（`NButton/NTooltip/NPopover/NCheckbox/NPopconfirm` 等）；图标系统同时支持 Iconify（`@iconify/vue`）与本地 SVG Symbol（通过 `VITE_ICON_LOCAL_PREFIX` 环境变量拼接 `#prefix-name`）；拖拽使用 `vue-draggable-plus`；样式合并使用 `tailwind-merge`。
@@ -1,5 +0,0 @@
-按使用场景划分为三个子目录：
- `common/`：应用级容器与全局能力注入（如 `app-provider.vue` 通过嵌套 `NLoadingBarProvider/NDialogProvider/NNotificationProvider/NMessageProvider` 将 Naive UI 的全局方法挂载到 `window.$*`），以及主题切换、全屏、语言切换等横切功能。
- `custom/`：基础原子组件（`svg-icon`、`button-icon`、`better-scroll`、`count-to`、`soybean-avatar`、`wave-bg`、`look-forward`），对外暴露稳定 props，内部组合 Naive UI 与第三方库（`@iconify/vue`、`vue-draggable-plus`）。
- `advanced/`：面向复杂业务场景的组合型组件（`table-column-setting`、`table-header-operation`），依赖 `custom/` 中的原子组件。
-依赖方向严格自底向上：`advanced` → `custom` → `common`，各组件之间不互相引用，仅通过 props / slots / defineModel 通信；样式统一走 Tailwind 类名，无独立 CSS。
@@ -1 +0,0 @@
-基于 Vue 3 + Naive UI + Tailwind 的页面级与通用 UI 组件集合，提供布局容器、图标、表格列配置等可复用视图单元。
@@ -1,5 +0,0 @@
- 所有组件均使用 `<script setup lang="ts">` 语法，并通过 `defineOptions({ name: 'xxx' })` 显式声明组件名。
- 需要透传属性的组件在 `defineOptions` 中设置 `inheritAttrs: false`，再手动用 `v-bind="$attrs"` 或 computed 包装后绑定。
- Props 采用 TypeScript interface 定义 + `withDefaults(defineProps<Props>(), {...})` 形式，并在接口注释中说明每个 prop 的用途。
- 样式全部使用 Tailwind 原子类（如 `h-[36px] text-icon bg-container`），组件 `<style>` 块保持为空，仅在必要时通过 `!important` 覆盖。
- 国际化文案统一通过 `@/locales` 导出的 `$t` 函数配合 i18n key 访问，避免硬编码字符串。
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/ui_framework/layouts
-title: 后台管理布局与主题抽屉
-scope:
-    - frontend_v2/src/layouts/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-Vue 3 `<script setup>` + TypeScript；UI 骨架来自 `@sa/materials` 的 `AdminLayout`，抽屉/标签页等交互使用 Naive UI（NDrawer、NTabs、NTab）；菜单上下文通过 `@sa/hooks` 的 `useContext` 封装 provide/inject。
@@ -1,6 +0,0 @@
-目录按职责分层：
- `base-layout/index.vue` 作为主布局，基于 `@sa/materials` 的 `AdminLayout`，通过 slot 注入 GlobalHeader、GlobalTab、GlobalSider、GlobalMenu、GlobalContent、GlobalFooter 和 ThemeDrawer；根据 `themeStore.layout.mode`（vertical / horizontal / vertical-mix / vertical-hybrid-header-first / top-hybrid-sidebar-first / top-hybrid-header-first）动态计算 header/sider/tab/footer 的可见性与宽度。
- `blank-layout/index.vue` 是极简壳，仅渲染 `GlobalContent`，用于登录页等无需框架装饰的场景。
- `modules/` 下每个 `global-*` 组件对应一个布局槽位或功能块，其中 `global-menu/index.vue` 使用 `<component :is="activeMenu">` 按模式路由到 `modules/` 下的具体菜单实现（vertical-menu、horizontal-menu、vertical-mix-menu、top-hybrid-*-first 等），并通过 `context/index.ts` 暴露 `provideMixMenuContext/useMixMenuContext` 共享一级/二级/子级菜单状态与选中逻辑。
- `theme-drawer/index.vue` 以 Naive UI Drawer + Tabs 组织 Appearance/Layout/General/Preset 四个设置面板，底部挂载 `config-operation.vue` 统一导出配置。
-依赖方向：布局 → modules → store/hooks/@elegant-router/@sa/*，模块之间仅通过 provide/inject 上下文通信，无循环引用。
@@ -1 +0,0 @@
-提供 BaseLayout/BlankLayout 两种页面外壳，组合全局 Header/Sider/Tab/Content/Footer 等模块，并内置可切换多菜单模式的侧边导航与主题设置抽屉。
@@ -1,4 +0,0 @@
- 每个布局/模块根组件都通过 `defineOptions({ name: '...' })` 显式声明组件名，便于调试与 KeepAlive 缓存。
- 布局行为与样式由 `themeStore` 与 `appStore` 驱动，模板中通过 computed 将 store 值映射为 props（如 headerProps、siderWidth），避免在模板中写分支逻辑。
- 菜单模式采用 Record<Component> 映射表 + `<component :is="...">` 动态选择实现，新增模式只需在 map 中注册对应组件。
- 跨组件共享的状态（如 mix 菜单层级）集中在 `modules/global-menu/context/index.ts`，通过 `provideMixMenuContext/useMixMenuContext` 对外暴露，而非直接 import store。
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/ui_framework/plugins
-title: 应用全局插件与初始化
-scope:
-    - frontend_v2/src/plugins/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-Vue 3 + Naive UI（用于更新通知按钮）、NProgress（页面级进度条）、@iconify/vue（离线图标资源）、dayjs（时间库扩展）、UnoCSS（原子类样式）。
@@ -1,8 +0,0 @@
-本模块以「每个文件一个 `setupXxx` 函数」的扁平结构组织，由 `index.ts` 统一 re-export，供应用入口按顺序调用完成启动装配：
- `assets.ts`：副作用型入口，负责注入 SVG 图标注册器、UnoCSS 与全局样式。
- `loading.ts`：在 DOM 挂载前通过 `innerHTML` 注入带主题色 CSS 变量与 Logo 的占屏 Loading 界面。
- `nprogress.ts`：配置 NProgress 并将其挂载到 `window.NProgress` 暴露给路由守卫使用。
- `iconify.ts`：根据 `VITE_ICONIFY_URL` 环境变量配置离线 Iconify API Provider。
- `dayjs.ts`：扩展 `localeData` 并通过 `locales/dayjs` 同步 Dayjs 本地化。
- `app.ts`：提供 `setupAppErrorHandle`（覆盖 `app.config.errorHandler`）与 `setupAppVersionNotification`（轮询 `index.html?time=` 中的 buildTime meta 标签，结合 `VITE_AUTOMATICALLY_DETECT_UPDATE` 与 `PROD` 环境决定是否提示刷新）。
-依赖方向单向向外：仅依赖 `@/locales`、`@/utils/*`、`@/constants/app` 及第三方库，不反向依赖业务代码。
@@ -1 +0,0 @@
-集中注册并初始化 Vue 应用所需的全局能力，包括加载动画、NProgress、Iconify、Dayjs、错误处理与版本更新通知等。
@@ -1,3 +0,0 @@
- 每个插件文件只导出一个命名函数 `setupXxx`，由外部按顺序调用完成初始化，避免在模块顶层执行副作用。
- 插件内部通过 `import.meta.env.VITE_*` 读取构建期开关与环境变量，而非运行时配置对象。
- 对外暴露的全局能力（如 NProgress）统一挂载到 `window` 上，作为跨模块共享的全局单例。
@@ -1,6 +0,0 @@
-本模块是 Vue3 应用的 UI 基础设施层，按职责拆分为四层并通过依赖关系串联：
- `plugins/` 在应用启动时通过 `app.use()` 注册全局能力（NProgress、Iconify、Dayjs、loading、错误处理等），为其余三层提供运行时支撑。
- `hooks/` 作为纯逻辑层被 `components/` 与 `layouts/` 共同消费，封装表格、图表、表单、路由、认证等跨页面复用逻辑，避免重复实现。
- `layouts/` 基于 BaseLayout/BlankLayout 组合 global-header/global-sider/global-tab/global-content/global-footer 等模块，并内嵌 theme-drawer 用于动态切换布局模式与主题；其内部菜单模块通过 context 共享状态，同时可切换 vertical/horizontal/top-hybrid/vertical-mix 多种导航模式。
- `components/` 按 common/custom/advanced 分层组织，common 提供系统级通用容器（AppProvider、DarkModeContainer、ExceptionBase 等），custom 封装业务定制组件，advanced 聚焦复杂交互（表格列设置、表头操作）。
-整体由 `plugins/index.ts` 统一装配，hooks 被 layouts 与 components 双向引用，形成「插件 → hooks → 布局 → 组件」的单向依赖链。
@@ -1 +0,0 @@
-聚合组件、布局、组合式函数与全局插件，为后台管理系统提供统一的视图渲染、主题切换与交互能力。
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell
-title: 前端应用外壳（App Shell）
-scope:
-    - frontend_v2/src/
-source_files: []
-depends_on: []
-related_to: []
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/business_views
-title: 业务视图层（views）
-scope:
-    - frontend_v2/src/views/
-source_files: []
-depends_on: []
-related_to: []
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/business_views/builtin_pages
-title: 内置页面（登录、异常与 iframe 壳）
-scope:
-    - frontend_v2/src/views/_builtin/
-source_files: []
-depends_on: []
-related_to: []
@@ -1,5 +0,0 @@
-本模块是路由层直接挂载的“壳”视图，不承载业务逻辑，仅组合全局组件与 store：
- `login/index.vue` 作为登录总入口，通过 `moduleMap: Record<UnionKey.LoginModule, LoginModule>` 将 `pwd-login / code-login / register / reset-pwd / bind-wechat` 五个子模块以动态 `<component :is>` + `Transition` 渲染，背景色由 `useThemeStore` 主题色计算得出；
- `403/404/500/index.vue` 均为空壳，统一委托给全局 `<ExceptionBase type="...">` 组件，遵循“零实现、只传参”的约定；
- `iframe-page/[url].vue` 使用 Vue Router 动态路由参数 `url` 作为 props 注入原生 `<iframe>`，用于嵌入外部系统。
-依赖方向单向向外：仅消费 `@/store/modules/*`、`@/hooks/common/form`、`@/constants/app` 与全局 UI 组件，不反向引用业务 views。
@@ -1 +0,0 @@
-提供框架级内置页面：多模式登录入口、403/404/500 异常页以及动态 URL 的 iframe 容器。
@@ -1,4 +0,0 @@
- 异常页采用“空 script + 单行 ExceptionBase 调用”的极简壳模式，仅通过 props 传递错误码。
- 登录子模块统一在 `<script setup>` 顶部用 `defineOptions({ name })` 显式声明组件名，便于调试与动态组件解析。
- 表单类子模块统一通过 `useNaiveForm()` 获取 `formRef/validate`，并以 `computed` 返回基于 `useFormRules()` 的规则对象，再绑定到 `NForm`。
- 所有文案通过 `$t('page.login.*')` 国际化 key 访问，禁止硬编码字符串。
@@ -1,9 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/business_views/share_code_and_home
-title: 分享码日志与首页仪表盘
-scope:
-    - frontend_v2/src/views/share-code/
-    - frontend_v2/src/views/home/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-Vue 3 `<script setup>` + TypeScript；UI 组件库 Naive UI（NCard/NTable/NForm/NModal 等）；JSON 可视化使用 `vue-json-pretty`；图标统一走 SvgIcon 包装（mdi / ant-design / carbon 等 iconify 集合）。
@@ -1,4 +0,0 @@
-本模块由两个并列的视图组成，均基于 Vue 3 `<script setup>` + TypeScript：
- `views/home/index.vue` 作为首页聚合页，通过 `quickLinks` 静态配置驱动 NGrid 卡片导航至各业务路由（如 `headphone_brand`、`share-code_log`），并调用 `fetchGetDashboardToday` 拉取当日型号与 OTA 列表；其子组件位于 `modules/` 下（`header-banner`、`card-data`、`line-chart`、`pie-chart`、`creativity-banner`、`project-news`），目前仅 `index.vue` 被实际使用，其余为模板占位。
- `views/share-code/log/index.vue` 是独立的分享码日志查询页，封装了搜索表单（MAC/分享码/动作/IP/时间范围）、分页参数、NDataTable 列定义（含 `render` 函数动态渲染 NTag/NButton）以及一个弹出式 JSON 查看器（`vue-json-pretty`）用于展示 `eq_data` 快照。
-依赖方向单向向外：视图层仅依赖 `@/service/api` 中的 API 函数、`@/store/modules/auth` 获取用户信息、`@/hooks/common/router` 做路由跳转，以及共享工具 `formatDateTime`（来自 `upgrade/shared`）。两个页面之间无直接耦合，通过路由 key 间接关联。
@@ -1 +0,0 @@
-提供分享码使用日志的查询展示以及 CMS 首页的快捷入口、今日新增型号/OTA 统计等概览能力。
@@ -1,4 +0,0 @@
- 每个 .vue 文件顶部通过 `defineOptions({ name: '...' })` 显式声明组件名，便于调试与路由元信息匹配。
- 数据加载采用统一的 `loading` ref + `onMounted` 触发模式，请求形参通过 `buildQueryParams` 或内联对象构造，空值一律转为 `undefined` 以省略查询参数。
- 表格列定义集中放在 `columns: DataTableColumns<T>[]` 常量中，使用 `render(row)` 配合 `h()` 函数动态渲染 NTag/NButton 等 Naive UI 组件。
- 对外部 JSON 字段（如 `eq_data`）统一用 `safeParseJson` 安全解析后再交给第三方展示组件，避免字符串/非对象类型导致崩溃。
@@ -1 +0,0 @@
-本目录是前端路由注册后直接映射的页面根目录，子目录即路由路径：`_builtin/` 放置框架级页面（登录、403/404/500、iframe 壳），其余以业务域命名（headphone、upgrade、share-code/log、system/users、toolbox/luxsin-controller、home）。各子模块内部遵循统一结构——顶层 `index.vue` 作为路由容器，复杂页面再拆出 `modules/`、`components/`、`composables/` 子目录；`upgrade/` 与 `headphone/` 还通过共享的 `shared.ts` / 组合式函数在视图间复用状态与工具方法。
@@ -1 +0,0 @@
-按业务域划分的前端页面集合，为登录、异常、耳机管理、OTA 升级、分享码日志与首页等场景提供 Vue 单文件组件入口。
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/business_views/headphone_management
-title: 耳机型号与品牌管理视图
-scope:
-    - frontend_v2/src/views/headphone/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-Vue 3 `<script setup>` + TypeScript，Naive UI（NDataTable/NModal/NForm 等），图标使用自定义 SvgIcon 组件（mdi 命名空间）。
@@ -1,5 +0,0 @@
-模块按业务实体拆分为两个并列子目录：`brand/index.vue` 负责品牌增删改查，`model/` 负责型号主流程。
- `model/index.vue` 作为组合式入口，通过 `<script setup>` 引入 `composables/useModelList.ts` 暴露的 `useModelList` 组合函数，集中持有分页、排序、搜索表单、选中行等状态，并编排各弹窗组件（`ModelFormDialog`、`PushViewDialog`、`EqCacheDialog`、`CsvViewerDialog`、`PushProgressDialog`）的可见性与数据绑定。
- `composables/useModelList.ts` 是纯逻辑层，封装对 `@/service/api` 中 `fetchGetModels`、`fetchGetBrands` 的调用，统一处理远端分页/排序/搜索参数映射与结果回填，向上仅暴露响应式状态与方法，不直接依赖 UI 组件。
- `components/` 下的五个对话框均为无头展示型子组件，通过 `v-model:show` + props 接收数据，内部再按需调用 API（如 `fetchGetModelMeilisearch`、`fetchGetModelMeasurement`），与父级通过事件回调刷新列表。
- 依赖方向单向：`index.vue → composables → @/service/api`；UI 组件之间无互相引用，全部由父级挂载。
@@ -1 +0,0 @@
-提供耳机品牌 CRUD 与型号列表、搜索、批量推送至搜索引擎、查看 Meilisearch 文档、EQ 缓存及频响 CSV 的后台管理页面。
@@ -1,5 +0,0 @@
- 所有异步 API 调用统一采用 `{ data, error } = await fetchXxx(...)` 解构模式，并以 `if (!error && data)` 分支更新状态，错误时回退到空数组或零计数。
- 删除等破坏性操作一律先通过 `window.$dialog.warning` 二次确认，成功后用 `window.$message.success` 反馈，失败则静默或提示。
- 表格列定义使用 Naive UI 的 `render(row)` 配合 `h()` 函数动态渲染按钮、标签、复制图标等复杂单元格内容。
- 品牌选择器统一采用 `NAutoComplete` + computed 过滤 `brandOptions` 的方式实现本地自动补全，并在输入为空时返回完整选项列表。
- 弹窗组件统一通过 `v-model:show` 双向绑定可见性，并通过 props 传入标题、加载态、模型 ID 等上下文数据，保持父级单一职责。
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/business_views/upgrade_management
-title: 设备 OTA 升级管理视图
-scope:
-    - frontend_v2/src/views/upgrade/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-Vue 3 `<script setup>` + TypeScript，Naive UI 组件库（NForm/NDataTable/NModal/NUpload 等），图标使用项目内 SvgIcon（mdi 系列）。
@@ -1 +0,0 @@
-本模块由三个独立路由级 Vue SFC 组成：`ota/index.vue`（OTA 版本主表，内嵌黑名单/定向设备两个子弹窗）、`blacklist/index.vue`（黑名单独立管理页）、`ota-target-device/index.vue`（定向设备独立管理页）。三者通过同级 `shared.ts` 共享常量（`DEVICE_MODEL_OPTIONS`、`PACKAGE_UPLOAD_MODELS`、`MAC_PATTERN`）与工具函数（`formatDateTime`、`formatOtaLabel`、`OtaOption` 类型），形成“共享配置 + 多页面复用”的轻量结构。所有 API 调用均走 `@/service/api` 导出的 `fetch*` 方法，采用 `{ data, error }` 解构的错误处理约定；UI 基于 Naive UI 的 NCard/NForm/NDataTable/NModal/NPagination 组合，列表统一使用 `skip/limit` 分页参数并通过 `data.items` / `data.total` 回填。依赖方向单向：views → shared.ts → @/service/api，无跨 view 直接引用。
@@ -1 +0,0 @@
-提供 OTA 版本、黑名单与定向升级设备的增删改查页面，并支持按型号上传升级包。
@@ -1,6 +0,0 @@
- API 调用统一返回 `{ data, error }` 对象，通过 `!error && data` 分支赋值，失败时清空 tableData 并将 itemCount 置 0。
- 表单校验使用 Naive UI FormRules，必填字段配合自定义 validator（如 MAC_PATTERN.test）返回 new Error 提示，触发事件为 `['blur', 'input']`。
- 列表页遵循固定骨架：searchForm + pagination reactive 状态、loadData/handleSearch/handleReset/handlePageChange/handlePageSizeChange 成对出现、onMounted 中加载下拉选项与首屏数据。
- 删除操作一律通过 window.$dialog.warning 二次确认，成功后 window.$message.success 提示并刷新列表。
- 时间字段统一经 shared.ts 的 formatDateTime 格式化后再渲染到表格列。
- 设备型号枚举集中定义在 shared.ts 的 DEVICE_MODEL_OPTIONS，各页面通过 computed 将其映射为 SelectOption 供 NSelect 使用。
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/framework_layers/service
-title: HTTP 请求封装与业务 API 层
-scope:
-    - frontend_v2/src/service/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-基于团队内部 `@sa/axios` 提供的 `createFlatRequest` / `createRequest` 构建 Axios 实例，利用 `BACKEND_ERROR_CODE` 统一区分网络错误与后端业务错误；Dashboard 后端约定 code=1 为成功、code=2 为“无数据”仍视为成功。
@@ -1,4 +0,0 @@
-模块分为两层：
- `request/`：基础设施层。`index.ts` 通过 `createFlatRequest` 创建主 `request` 实例（baseURL 由 `getServiceBaseURL` 根据环境变量与 `VITE_HTTP_PROXY` 决定），并额外导出一个仅用于演示的 `demoRequest`；`shared.ts` 提供 `getAuthorization`、`handleExpiredRequest`、`showErrorMsg` 等跨实例共享逻辑；`type.ts` 定义 `RequestInstanceState`。
- `api/`：业务层。每个文件对应一个后端子域（auth、brand、dashboard、ota、blacklist、user、model 等），内部只 import `../request` 暴露的 `request`，以 `fetchXxx` 命名函数包装具体 URL 与方法，并通过泛型参数标注返回类型（如 `Api.Auth.LoginResult`）。
-依赖方向单向：`api/*` → `request/index.ts` → `request/shared.ts` + `@sa/axios` + `@/store/modules/auth` + `@/utils/storage`，API 层不直接访问 store 或 storage。
@@ -1 +0,0 @@
-基于 @sa/axios 封装统一的 HTTP 客户端，集中处理鉴权、错误提示与 Token 刷新，并按业务域组织前端 API 调用函数。
@@ -1,5 +0,0 @@
- API 函数统一使用 `fetchXxx` 前缀命名，并在 JSDoc 中描述参数语义。
- 所有请求通过 `request<T>()` 调用，返回值用 TypeScript 泛型标注为 `Api.*` 命名空间下的响应类型，而非裸接口。
- 鉴权头在 `onRequest` 拦截器中统一注入 `Authorization: Bearer <token>`，业务 API 不再自行拼接 token。
- 错误码策略通过环境变量 `VITE_SERVICE_LOGOUT_CODES`、`VITE_SERVICE_MODAL_LOGOUT_CODES`、`VITE_SERVICE_EXPIRED_TOKEN_CODES` 配置，按逗号分隔字符串解析，避免硬编码。
- 重复的错误消息通过 `errMsgStack` 去重，配合 `beforeunload` 监听实现弹窗式强制登出。
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/framework_layers/store
-title: Pinia 应用状态管理（Setup Store 模式）
-scope:
-    - frontend_v2/src/store/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-Pinia（setup store 风格）+ VueUse（`useBreakpoints`/`useEventListener`/`useBoolean`/`useNow` 等组合式 API）+ `@sa/hooks` 中的 `useLoading`/`useBoolean` 复用；状态持久化统一走 `@/utils/storage` 封装的 `localStg`。
@@ -1,12 +0,0 @@
-模块以 `src/store/index.ts` 为入口，通过 `setupStore(app)` 创建 Pinia 实例并注册自定义插件 `resetSetupStore`；该插件在 `store.use()` 阶段拦截所有使用 setup 语法定义的 store，为其注入 `$reset` 方法，实现按默认快照恢复状态。
-
-业务 store 按领域拆分为 `modules/{app,auth,route,tab,theme}` 五个子目录，每个 store 独立一个 `index.ts`，并在同目录下提供 `shared.ts` 存放纯函数工具（如路由过滤、Tab 计算、主题 token 生成），遵循「逻辑 + 纯函数」的解耦约定。
-
-依赖方向：
- `app` 作为协调层，聚合 `route`、`tab`、`theme` 三个 store，监听断点变化联动布局与侧边栏。
- `auth` 负责登录态与用户信息，登出时级联调用 `tabStore.cacheTabs` 与 `routeStore.resetStore`。
- `route` 是动态路由的核心，维护 constant/auth 两类路由表，并通过 `router.addRoute/removeRoute` 直接操作 Vue Router。
- `tab` 管理多标签页，读写 `localStg('globalTabs')` 做持久化，删除 tab 时主动调用 `routeStore.resetRouteCache` 清理缓存。
- `theme` 通过 computed 派生 NaiveUI theme 与 CSS 变量，并在 `beforeunload` 中持久化设置。
-
-跨模块通信全部通过互相 `useXxxStore()` 引用完成，无中央事件总线或回调注册机制。
@@ -1 +0,0 @@
-基于 Pinia setup store 模式的全局状态中心，统一管理应用、认证、路由、标签页与主题等核心模块。
@@ -1,5 +0,0 @@
- 所有 store 均通过 `defineStore(SetupStoreId.Xxx, () => {...})` 的 setup 语法定义，store id 集中来自 `@/enum` 的 `SetupStoreId` 枚举。
- 每个 store 目录配套一个同名 `shared.ts`，将无副作用的纯函数（路由过滤、Tab 计算、主题 token 生成等）抽离到其中，供 store 与其他模块复用。
- 需要副作用的响应式监听统一放在 `effectScope().run(() => { ... })` 中，并在 `onScopeDispose` 里调用 `scope.stop()` 释放资源。
- 跨 store 协作通过互相 `useXxxStore()` 引入后直接调用对方方法完成，而非通过事件或回调注册。
- 浏览器生命周期数据（主题设置、全局 Tab、mixSiderFixed 等）统一在 `window 'beforeunload'` 事件中通过 `localStg.set` 持久化。
@@ -1,8 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/framework_layers/router
-title: Vue Router 路由与守卫层
-scope:
-    - frontend_v2/src/router/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-vue-router 4 + @elegant-router/vue 与 @elegant-router/types，使用 `layout.blank`/`layout.base` 布局约定与 `$` 分隔符的单级路由语法。
@@ -1,7 +0,0 @@
-模块按职责拆分为四个子目录：
- `elegant/`：由 elegant-router 代码生成（带 `Generated by elegant-router` 注释），`routes.ts` 导出 `generatedRoutes` 常量路由树，`transform.ts` 提供 `transformElegantRoutesToVueRoutes` 将 `layout.xxx$view.yyy` 字符串组件名解析为实际 Vue 组件并处理单级路由拆分、props 注入与默认重定向；`imports.ts` 暴露 `layouts`/`views` 映射。
- `routes/builtin.ts`：定义 `ROOT_ROUTE`（重定向到 `VITE_ROUTE_HOME`）与 `not-found` 兜底路由，并通过 `createBuiltinVueRoutes()` 调用 transform 产出初始 Vue 路由表。
- `guard/`：`index.ts` 聚合三个守卫——`progress.ts`（NProgress）、`route.ts`（核心鉴权）、`title.ts`（文档标题），统一由 `createRouterGuard` 注册。
- `index.ts`：根据 `VITE_ROUTER_HISTORY_MODE`（hash/history/memory）+ `VITE_BASE_URL` 创建 `vue-router` 实例，挂载 builtin routes 后调用 `setupRouter(app)` 完成 `app.use(router)`、注册守卫并等待 `router.isReady()`。
-
-依赖方向：`index.ts` → `routes/builtin` + `guard/index`；`guard/route.ts` 通过 `useRouteStore` 触发 `initConstantRoute` / `initAuthRoute` 实现懒加载动态路由，并在未初始化时拦截 `not-found` 重定向回原路径；`getRouteName` 来自 `elegant/transform` 以支持 login redirect query 的 name 反查。
@@ -1 +0,0 @@
-基于 vue-router 与 elegant-router 构建应用路由，负责历史模式选择、静态/动态路由转换及登录鉴权、进度条、文档标题等全局守卫。
@@ -1,5 +0,0 @@
- 所有路由元信息统一放在 `meta` 字段中，通过 `constant`、`hideInMenu`、`roles`、`keepAlive`、`href`、`order`、`icon`、`i18nKey` 等键描述访问控制与 UI 行为。
- 组件引用采用 `layout.xxx$view.yyy` 字符串命名约定，由 `transform.ts` 在运行时解析为实际组件，避免直接 import 视图文件。
- 路由名称与路径的双向查找通过 `elegant/transform.ts` 导出的 `getRoutePath` / `getRouteName` 完成，禁止手写 path/name 映射。
- 需要登录的路由标记为 `constant: false`（即非 constant 路由），守卫据此判断是否需要鉴权流程。
- 守卫函数以 `createXxxGuard(router)` 形式暴露，由 `createRouterGuard` 统一组装注册，新增守卫只需追加一行调用。
@@ -1,10 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/framework_layers
-title: 前端应用框架层（路由/状态/服务）
-scope:
-    - frontend_v2/src/router/
-    - frontend_v2/src/store/
-    - frontend_v2/src/service/
-source_files: []
-depends_on: []
-related_to: []
@@ -1 +0,0 @@
-三层以「认证态」为中心形成单向依赖链：service/request 在拦截器中读取 localStg 的 token 并注入 Authorization 头，遇到过期或登出码时调用 store/modules/auth 的 resetStore；auth store 登录成功后持久化 token/userInfo 并触发 routeStore.resetStore 与 tabStore.cacheTabs；router/guard/route.ts 在 beforeEach 中根据 isInitConstantRoute/isInitAuthRoute 与 authStore.isLogin 决定是否需要初始化静态/动态路由、重定向到 login 或 403。store 内部各模块通过 Setup Store 模式互相引用（auth 引用 route/tab，route 维护路由元信息），service/api 仅暴露业务函数供 store 与页面组件消费，router 不直接调 service，而是通过 store 间接驱动数据加载，从而保证路由层无副作用、状态层统一协调、网络层集中处理鉴权与错误。
@@ -1 +0,0 @@
-为应用提供基于 vue-router、Pinia 与 @sa/axios 的路由守卫、全局状态与 HTTP 请求三大基础能力，并通过认证态串联三者。
@@ -1,3 +0,0 @@
- 所有跨层共享的运行时状态（token、userInfo、lastLoginUserId）统一通过 utils/storage 的 localStg 存取，避免分散的 localStorage 调用
- Store 采用 Pinia setup store 模式，模块间通过 useXxxStore() 互相引用，禁止在 store 之外直接操作响应式变量
- HTTP 错误与用户提示集中在 service/request 的 onError/onBackendFail 中处理，业务 API 只返回 { data, error } 结构
@@ -1,14 +0,0 @@
-schema_version: 1
-module_path: frontend_v2/app_shell/shared_infra
-title: 应用共享基础设施（主题、样式、常量、枚举、国际化与类型）
-scope:
-    - frontend_v2/src/theme/
-    - frontend_v2/src/styles/
-    - frontend_v2/src/constants/
-    - frontend_v2/src/enum/
-    - frontend_v2/src/locales/
-    - frontend_v2/src/typings/
-    - frontend_v2/src/utils/
-source_files: []
-depends_on: []
-related_to: []
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`Node.js 22 (Alpine) + Express + Sequelize + Redis + Meilisearch + AWS S3；前端 Vite + Vue3 + Naive UI + UnoCSS + Alova；容器编排使用 Docker Compose，Nginx 托管静态资源。`
				`@@ -0,0 +1 @@`
				`音频设备曲线与 OTA 升级管理后台，采用 Node.js 后端 + Vue3 前端双包结构，通过 Docker Compose 编排 Nginx 与 API 服务。`
				`@@ -0,0 +1 @@`
				首次部署需在服务器 `/data/project/dashboard/` 创建 `.env`（参考 `.env.example`），然后执行 `./scripts/upload.sh all` 上传前端 dist、后端源码与 compose 文件，再在服务器上运行 `docker compose build --no-cache backend && docker compose up -d`。本地非 Docker 开发时，根目录 `.env` 中设置 `PORT=8083`，分别启动 `cd backend && pnpm start` 与 `cd frontend && pnpm dev`。
				`@@ -1 +0,0 @@`
				Alova 3.5.1（含 `alova/vue`、`alova/fetch`、`alova/client` 插件）与 Axios 1.16.0 + `axios-retry` 4.5.0；参数序列化使用 `qs` 6.15.1，ID 生成来自 `@sa/utils` 的 `nanoid`。
				`@@ -1 +0,0 @@`
				`为前端提供 Alova 与 Axios 两套可插拔的 HTTP 客户端封装，统一注入鉴权刷新、后端响应校验、错误处理与请求取消等横切能力。`
				`@@ -1 +0,0 @@`
				`tsx + cac(命令行解析) + c12(配置加载) + execa(子进程) + bumpp(版本管理) + @soybeanjs/changelog(变更日志) + enquirer(交互式提示) + picomatch(路径匹配) + rimraf(删除)。`
				`@@ -1 +0,0 @@`
				`提供 @sa/scripts 命令行工具，封装清理、依赖升级、Conventional Commits 校验与生成、Changelog 生成、版本发布及路由代码生成等开发辅助命令。`
				`@@ -1 +0,0 @@`
				安装后通过 `pnpm sa <command>` 调用；CLI 全局配置键名为 `soybean`，可从项目根 `soybean.config.*` 文件或 `package.json#soybean` 注入覆盖默认值。
				`@@ -1 +0,0 @@`
				Vue 3 + TypeScript；颜色计算使用 `colord@2.9.3`；滚动条基于 `simplebar-vue@2.4.2`；样式采用 CSS Modules（经 `typed-css-modules` 生成类型）；UnoCSS 自定义 Preset 通过 `@unocss/core` 的 `Preset<Theme>` 接口扩展。
				`@@ -1 +0,0 @@`
				`聚合项目级颜色系统、通用 Vue 物料组件以及 UnoCSS 自定义预设，为上层应用提供一致的视觉与布局能力。`