# sass-platform

**Repository Path**: zhaoxiang520/sass-platform

## Basic Information

- **Project Name**: sass-platform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-13
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# platform-refactor 前端（Nuxt 4）

基于 Nuxt 4 官方脚手架的前端项目，用于平台重构阶段的基础应用骨架。本系统是一个企业级ERP平台的前端应用，提供全面的业务管理功能，包括用户权限管理、订单处理、仓储管理、质量检测等模块。

## 技术栈

- Nuxt 4 - 基于Vue 3的全栈框架
- Vue 3 - 渐进式JavaScript框架
- TypeScript - 类型安全的JavaScript超集
- @nuxt/ui - 美观的UI组件库
- @nuxt/image - 优化的图片处理
- @nuxt/hints - 开发提示工具
- Zod - TypeScript优先的模式声明和验证库
- TailwindCSS - 实用优先的CSS框架

## 项目架构

本系统采用前后端分离架构，前端基于Nuxt 4框架开发，通过RESTful API与后端进行数据交互。系统使用组合式API模式，通过composables封装业务逻辑，实现代码复用和逻辑分离。

### 核心功能模块

1. **系统管理**
   - 用户管理：用户账号创建、编辑、权限分配
   - 权限组管理：角色权限配置、权限规则管理
   - 菜单管理：动态菜单配置、路由管理

2. **业务管理**
   - 合作伙伴管理：供应商、客户信息维护
   - 订单管理：订单创建、审批、跟踪
   - 采购管理：采购单处理、审批流程

3. **仓储管理**
   - 库存查询：实时库存状态查看
   - 库存操作：出入库记录、库存调整
   - 成品入库：生产成品批量入库
   - 操作日志：库存变动记录追踪

4. **质量管理**
   - 化验报告管理：产品质量检测记录

## 目录结构

```text
.
├─app/                  # 应用主目录
│  ├─app.vue            # 应用根组件，挂载布局和页面
│  ├─app.config.ts      # 应用级配置（如 UI、应用名称等）
│  ├─error.vue          # 全局错误页
│  ├─layouts/           # 页面布局
│  │  ├─auth.vue        # 认证相关页面布局
│  │  └─default.vue     # 默认应用布局
│  ├─components/        # 通用组件
│  │  ├─AppAreaCascader.vue  # 地区级联选择器
│  │  ├─AppFooter.vue        # 应用底部组件
│  │  ├─AppHeader.vue        # 应用头部组件
│  │  └─AppTabBar.vue        # 标签栏组件
│  ├─pages/             # 页面路由（文件即路由）
│  │  ├─auth-groups/     # 权限组管理页面
│  │  ├─index.vue        # 首页
│  │  ├─login.vue        # 登录页面
│  │  ├─machining/       # 加工相关页面
│  │  ├─menus/           # 菜单管理页面
│  │  ├─orders/          # 订单管理页面
│  │  ├─partners/        # 合作伙伴管理页面
│  │  ├─purchases/       # 采购管理页面
│  │  ├─quality/         # 质量管理页面
│  │  ├─users/           # 用户管理页面
│  │  └─warehouse/       # 仓储管理页面
│  ├─composables/        # 组合式函数
│  │  ├─useApi.ts        # API请求封装
│  │  ├─useAreaSelector.ts # 地区选择逻辑
│  │  ├─useAuth.ts       # 认证与权限管理
│  │  ├─useAuthToken.ts  # Token处理
│  │  ├─useSystemConfig.ts # 系统配置
│  │  └─useTabs.ts       # 标签页管理
│  ├─middleware/         # 路由中间件
│  │  ├─auth.global.ts   # 全局认证中间件
│  │  └─menu-guard.global.ts # 菜单权限中间件
│  └─plugins/            # 插件
│     └─auth.client.ts   # 客户端认证插件
├─public/               # 静态资源
│  ├─favicon.ico        # 网站图标
│  └─robots.txt         # 爬虫配置
├─docs/                 # 项目文档
│  ├─api文档.md          # API接口文档
│  └─menu-routes.md     # 菜单路由对照说明
├─nuxt.config.ts        # Nuxt 配置（模块、特性开关等）
├─tsconfig.json         # TypeScript 配置
├─package.json          # 项目脚本与依赖
└─pnpm-lock.yaml        # pnpm 依赖锁定文件
```

## 环境要求

- Node.js：建议使用与 Nuxt 4 官方兼容的 LTS 版本
- 包管理工具：pnpm / npm / yarn / bun（推荐 pnpm，与仓库内 `pnpm-lock.yaml` 对齐）

## 安装依赖

```bash
# 推荐
pnpm install

# 其他
npm install
yarn install
bun install
```

## 本地开发

启动开发服务器（默认端口 `http://localhost:3000`）：

```bash
# 推荐
pnpm dev

# 其他
npm run dev
yarn dev
bun run dev
```

## 构建与预览

构建生产包：

```bash
pnpm build
# 或 npm run build / yarn build / bun run build
```

本地预览生产包：

```bash
pnpm preview
# 或 npm run preview / yarn preview / bun run preview
```

## 静态站点生成

如果需要生成静态站点：

```bash
pnpm generate
# 或 npm run generate / yarn generate / bun run generate
```

## 开发约定

- 使用 TypeScript 开发，保持类型安全。
- 优先使用 `@nuxt/ui` 提供的组件构建界面。
- 修改 Nuxt 配置时，请同步在本 README 的「技术栈」或「目录结构」中进行补充说明。
- API调用统一使用`useApi` composable，确保请求拦截和错误处理的一致性。
- 表单验证使用Zod库，保持前后端验证规则的一致性。
- 页面路由遵循约定优于配置原则，使用文件系统路由。
- 组件命名采用PascalCase，文件名与组件名保持一致。
- 提交代码前请确保通过TypeScript类型检查和ESLint代码规范检查。

## 认证与权限

系统采用基于Token的认证机制，通过`useAuth` composable管理用户认证状态和权限数据。权限控制分为两个层面：

1. **路由级权限**：通过全局中间件`auth.global.ts`和`menu-guard.global.ts`控制页面访问权限。
2. **组件级权限**：通过`useAuth`提供的`permissions`状态控制页面内特定功能的显示与操作权限。

## API配置

系统API基础地址通过Nuxt运行时配置进行管理，当前配置为：
```typescript
runtimeConfig: {
  public: {
    apiBase: "https://erp-api.njyltc.cn",
  },
}
```

## 业务模块说明

### 菜单管理

- 路由入口：`/menus/list`
- 主要功能：
  - 左侧菜单树 + 右侧详情表单布局，支持单选、层级展示与滚动。
  - 新增 / 编辑 / 删除菜单，区分目录、前端路由、后端接口三种类型。
  - 在弹窗中使用 `UForm + zod` 做表单校验，动态控制 `router/url/method/component` 字段。
  - 集成 Iconify lucide 图标库选择器，支持预览和快速搜索常用图标。
- 后端接口：`/api/protected/menus` 系列（列表、新增、编辑、删除）。

### 用户管理

- 路由入口：`/users/list`
- 主要功能：
  - 使用 `UTable + UPagination` 展示用户列表，字段包括账号、昵称、权限、状态、IP、时间等。
  - 新增 / 编辑 / 删除用户，表单基于 `UForm + zod` 校验，编辑时禁用账号输入框。
  - 在列表中通过 `USwitch` 切换用户状态，并调用 `/api/protected/user/status`，带防抖和 toast 提示。
  - 从 `/api/protected/auth-groups/list` 加载权限组，在列表中将 `roles` 映射为角色名称。
  - 在新增/编辑弹窗中提供“所属权限组”多选，提交时附带 `group_id` 数组。
- 后端接口：`/api/protected/user` 系列（列表、新增、编辑、删除、状态切换）以及 `/api/protected/auth-groups/list`。

### 权限组管理

- 路由入口：`/auth-groups/list`
- 主要功能：
  - 使用 `UTable` 展示权限组列表（名称、描述、状态），支持分页与刷新。
  - 新增 / 编辑 / 删除权限组，在弹窗中编辑组名称和描述。
  - 在列表中通过 `USwitch` 切换权限组启用状态，对应 `/api/protected/auth-groups/status` 接口。
  - 通过「配置权限」弹窗查看并勾选权限规则，使用 `UTree + Checkbox` 展示菜单树，勾选结果通过 `/api/protected/auth-groups/rules/{id}` 保存。
- 后端接口：`/api/protected/auth-groups` 系列（列表、新增、编辑、删除、状态切换、权限规则）。

### 仓库操作日志

- 路由入口：`/warehouse/stock-movements`
- 主要功能：
  - 使用 `UTable + UPagination` 展示仓库货物操作日志，支持分页浏览。
  - 顶部提供仓库编码、产品编码、业务类型、时间范围等查询条件，支持组合筛选。
  - 支持单条删除仓库操作日志记录，删除前弹出确认弹窗，并在操作成功后通过 toast 反馈结果。
- 后端接口：`GET /api/protected/warehouse/stock-movements`（列表查询）、`DELETE /api/protected/warehouse/{id}`（删除指定日志）。

### 当前库存

- 路由入口：`/warehouse/inventory`
- 主要功能：
  - 使用 `UTable` 展示当前库存列表，字段包括仓库编码、产品编码、产品分类、当前库存数量、单位、最后变动时间等。
  - 顶部提供刷新按钮，支持手动重新拉取库存数据。
  - 列表区域采用固定高度内部滚动，保持与其他业务页一致的布局体验。
- 后端接口：`GET /api/protected/warehouse/inventory`（查询当前库存）。

### 订单管理

- 路由入口：`/orders/list`
- 主要功能：
  - 使用 `UTable + UPagination` 展示订单列表，支持按订单编号、客户ID、操作人、审批状态等条件筛选。
  - 支持删除订单操作，在删除前弹出确认弹窗，并在操作成功后通过 toast 反馈结果。
  - 提供订单审批弹窗，可对订单执行通过 / 驳回操作并填写审批备注，审批结果提交到后端。
- 后端接口：`GET /api/protected/orders`（订单列表）、`DELETE /api/protected/orders/{id}`（删除订单）、`PUT /api/protected/orders/approve/{id}`（订单审批）。

### 采购管理

- 路由入口：`/purchases/list`
- 主要功能：
  - 使用 `UTable + UPagination` 展示采购单列表，支持按采购单号、供应商、状态等条件筛选。
  - 新增 / 编辑 / 删除采购单，支持添加多个采购项目。
  - 提供采购审批弹窗，可对采购单执行通过 / 驳回操作并填写审批备注。
- 后端接口：`/api/protected/purchases` 系列（列表、新增、编辑、删除、审批）。

### 合作伙伴管理

- 路由入口：`/partners/list`
- 主要功能：
  - 使用 `UTable + UPagination` 展示合作伙伴列表，支持按编码、名称、类型等条件筛选。
  - 新增 / 编辑 / 删除合作伙伴，支持详细信息维护。
  - 支持查看合作伙伴详情页面（动态路由 `/partners/[code]`）。
- 后端接口：`/api/protected/partners` 系列（列表、新增、编辑、删除、详情）。

### 质量管理

- 路由入口：`/quality/list`
- 主要功能：
  - 使用 `UTable + UPagination` 展示化验报告列表，支持按报告编号、产品、时间等条件筛选。
  - 新增 / 编辑 / 删除化验报告，支持上传检测数据和结果。
  - 提供化验报告复核功能，确保检测数据的准确性。
- 后端接口：`/api/protected/quality` 系列（列表、新增、编辑、删除、复核）。

### 库存操作

- 路由入口：`/warehouse/operations`
- 主要功能：
  - 支持多种库存操作类型：手工入库、手工出库、成品入库、原料出库等。
  - 使用表单录入操作信息，包括仓库、产品、数量、操作类型等。
  - 操作记录自动同步到库存系统，并生成操作日志。
- 后端接口：`/api/protected/warehouse/operations`（操作记录）。

### 成品入库

- 路由入口：`/warehouse/prod-item`
- 主要功能：
  - 根据生产单批量生成成品入库记录。
  - 支持查看生产单详情，关联生产数据与库存数据。
  - 提供成品入库确认和调整功能。
- 后端接口：`/api/protected/warehouse/prod-item`（成品入库记录）。

## 更新日志

### 2025-12-08 关键问题修复

#### 🐛 页面刷新标题英文问题修复
- **问题现象**：页面刷新时浏览器标题显示为英文"Nuxt App"
- **修复方案**：在 [`app/app.config.ts`](app/app.config.ts:1) 中配置中文应用标题
- **影响范围**：全局页面标题显示
- **修复结果**：页面刷新时标题正确显示为中文应用名称

#### 🐛 Token过期无限循环问题修复
- **问题现象**：Token过期后系统进入无限循环重试状态，页面无法正常加载
- **根本原因**：认证中间件未正确处理Token过期的重定向逻辑
- **修复方案**：优化 [`app/middleware/auth.global.ts`](app/middleware/auth.global.ts:1) 中的错误处理，Token过期时直接重定向到登录页
- **关键改动**：
  - [`app/middleware/auth.global.ts`](app/middleware/auth.global.ts:1) - 添加重定向保护逻辑
  - [`app/composables/useAuth.ts`](app/composables/useAuth.ts:1) - 改进认证状态管理
  - [`app/plugins/auth.client.ts`](app/plugins/auth.client.ts:1) - 优化客户端认证初始化
- **影响范围**：用户认证流程、页面访问控制
- **修复结果**：Token过期后能够正确重定向到登录页，无无限循环现象