OMS_H5/概要设计文档.md

# 微信小程序H5审批系统 - 概要设计文档

## 1. 项目概述

### 1.1 项目背景
开发一个运行在微信小程序WebView中的H5应用，主要用于处理审批流程，包括列表查看、详情展示和审批操作。

### 1.2 项目目标
- 提供流畅的审批流程体验
- 适配微信小程序WebView环境
- 支持移动端友好的界面设计
- 高效的接口调用和数据展示

## 2. 技术架构

### 2.1 技术栈选择
- **前端框架**: Vue 3.3.4 + TypeScript
- **构建工具**: Vite 4.4.9
- **UI组件库**: Vant 4.6.6 (专为移动端设计)
- **HTTP客户端**: Axios 1.5.0
- **路由管理**: Vue Router 4.2.4
- **状态管理**: Pinia 2.1.6
- **样式预处理器**: SCSS (Sass)
- **PDF预览**: vue-pdf-embed + pdfjs-dist

### 2.2 项目结构
```
oms_vue/
├── public/
├── src/
│   ├── api/              # API接口管理
│   │   ├── auth.ts       # 认证接口
│   │   ├── order.ts      # 订单相关接口
│   │   ├── purchase.ts   # 采购相关接口
│   │   └── todo.ts       # 待办相关接口
│   ├── router/           # 路由配置
│   ├── store/            # 状态管理
│   │   ├── auth.ts       # 认证状态
│   │   ├── order.ts      # 订单状态
│   │   └── purchase.ts   # 采购状态
│   ├── styles/           # 全局样式
│   ├── types/            # TypeScript类型定义
│   ├── utils/            # 工具函数 (http封装等)
│   ├── views/            # 页面组件
│   │   ├── Home/         # 审批中心主页 (含抽屉菜单)
│   │   ├── List/         # 订单审批列表组件
│   │   ├── Purchase/     # 采购审批列表组件
│   │   ├── Detail/       # 订单详情页面
│   │   ├── PurchaseDetail/# 采购详情页面
│   │   └── Login/        # 登录页面
│   ├── App.vue
│   └── main.ts
├── .env.development      # 开发环境配置
├── .env.production       # 生产环境配置
├── package.json
└── vite.config.ts
```

## 3. 功能模块设计

### 3.0 主页面模块（审批中心）
**功能描述**: 提供左侧抽屉菜单导航，统一管理不同类型的审批入口。

**组件位置**: `src/views/Home/index.vue`

**页面架构**:
- **顶部导航栏**: 显示当前菜单标题、菜单图标和退出按钮。
- **左侧抽屉菜单**: 展示所有审批类型的菜单项（订单审批、采购审批）。
- **内容区域**: 根据选中的菜单项动态切换显示 `List` (订单列表) 或 `Purchase` (采购列表) 组件。

**主要功能**:
- 抽屉式菜单切换审批类型。
- 统一的退出登录功能。
- 动态组件 (`<component :is="...">`) 切换列表视图。

**菜单配置**:
1. **订单审批** (icon: notes-o) -> 对应 `List` 组件
2. **采购审批** (icon: shopping-cart-o) -> 对应 `Purchase` 组件

### 3.1 订单审批列表模块
**功能描述**: 采用双Tab设计，支持查看待审批和已审批两种状态的订单列表。

**组件位置**: `src/views/List/index.vue`

**Tab设计**:
- **Tab1 - 待审批**: 展示用户需要审批的订单。支持按"订单编号"、"客户名称"搜索。
- **Tab2 - 已审批**: 展示用户已审批的历史记录。支持按"合同名称"搜索。

**数据展示**:
- **待审批**: 订单编号、项目名称、客户名称、订单金额、创建时间。
- **已审批**: 合同编号、合同名称、流程名称、发起人、审批时间、审批状态、审批意见。

**接口定义**:
- **待审批列表**: `POST /project/order/list`
- **已审批列表**: `POST /flow/completed/list`

### 3.2 订单详情页面模块
**功能描述**: 展示订单详细信息、附件、审批历史，并提供审批操作。

**组件位置**: `src/views/Detail/index.vue`
**路由**: `/detail/:id`

**主要功能**:
- **项目/订单信息**: 客户信息、金额、相关人员等。
- **产品明细**: 软件、硬件、维保产品列表。
- **附件查看**: 合同附件、配置附件等。
- **审批历史**: 展示审批流转记录。
- **审批操作**: 通过、驳回、填写意见。

**接口定义**:
- **获取详情**: `GET /project/order/h5/approve/{id}`
- **提交审批**: `POST /project/order/order/approve`

### 3.3 采购审批列表模块
**功能描述**: 采用双Tab设计，支持查看待审批和已审批的采购单。

**组件位置**: `src/views/Purchase/index.vue`

**Tab设计**:
- **Tab1 - 待审批**: 展示待审批采购单。支持按"采购单号"搜索。
- **Tab2 - 已审批**: 展示已审批采购记录。支持按"合同名称"搜索。

**接口定义**:
- **待审批列表**: `GET /sip/purchaseorder/approveList`
- **已审批列表**: `POST /flow/completed/list` (参数 `processKeyList` 包含 `purchase_order_online` 等)

### 3.4 采购详情页面模块
**功能描述**: 展示采购单详细信息和产品列表，支持审批操作。

**组件位置**: `src/views/PurchaseDetail/index.vue`
**路由**: `/purchase-detail/:id` (id为采购单号 purchaseNo)

**页面架构**:
- **Tab1 - 订单信息**: 采购单号、供应商、金额、付款方式、仓库等基本信息。
- **Tab2 - 采购列表**: 采购产品明细（型号、描述、数量、单价、小计）。
- **底部操作栏**: 审批通过/驳回按钮。

**接口定义**:
- **获取详情**: `GET /sip/purchaseorder/code/{purchaseNo}`
- **提交审批**: `POST /flow/todo/approve`
- **审批历史**: `POST /flow/completed/all/list`

## 4. 数据接口规范

### 4.1 通用响应格式
```typescript
interface ApiResponse<T> {
  code: number;      // 0 表示成功
  msg: string | null;
  rows: T;           // 列表数据通常在这里 (注意：部分接口可能在 data 字段)
  total?: number;    // 分页总数
}
```

### 4.2 核心API接口

#### 4.2.1 认证 (Auth)
- `POST /login`: 用户登录 (FormData: username, password, rememberMe)

#### 4.2.2 订单 (Order)
- `POST /project/order/list`: 获取待审批订单列表
  - 参数: `approve="approve"`, `page`, `pageSize`, `keyword`
- `POST /flow/completed/list`: 获取已审批订单列表
  - 参数: `page`, `pageSize`, `businessName`, `processKeyList`
- `GET /project/order/h5/approve/{id}`: 获取订单详情
- `POST /project/order/order/approve`: 提交订单审批
  - 参数: `todoId`, `approveStatus`, `approveOpinion`, `variables`, `taxRateData`

#### 4.2.3 采购 (Purchase)
- `GET /sip/purchaseorder/approveList`: 获取采购待审批列表
  - 参数: `page`, `pageSize`, `keyword`
- `POST /flow/completed/list`: 获取采购已审批列表 (复用流程接口)
  - 参数: `processKeyList` (如 `['purchase_order_online']`)
- `GET /sip/purchaseorder/code/{purchaseNo}`: 获取采购详情
- `POST /flow/todo/approve`: 提交采购审批 (注意与订单审批接口不同)
- `POST /flow/completed/all/list`: 获取采购审批历史

## 5. 数据模型 (TypeScript Types)

### 5.1 订单相关
```typescript
// 订单信息
interface Order {
  id: number;
  orderCode: string;
  projectName: string;
  customerName: string;
  shipmentAmount: number;
  orderStatus: '0' | '1' | '2';
  // ... 其他字段
}

// 订单详情响应
interface OrderDetailResponse {
  projectOrderInfo: Order & {
    contractFileList: AttachmentFile[];
    softwareProjectProductInfoList: ProductInfo[];
    hardwareProjectProductInfoList: ProductInfo[];
    // ...
  };
  approveLog: ApprovalRecord[];
  user: UserInfo;
}
```

### 5.2 采购相关
```typescript
// 采购单列表项
interface Purchase {
  id: number;
  purchaseNo: string;
  approveStatus: string;
  vendorName: string;
  ownerName: string;
  totalAmount: number;
  createTime: string;
}

// 采购详情
interface PurchaseDetail {
  id: number;
  purchaseNo: string;
  purchaserName: string;
  warehouseName: string;
  payMethod: string;
  omsPurchaseOrderItemList: PurchaseOrderItem[];
  // ...
}

// 采购产品项
interface PurchaseOrderItem {
  productCode: string;
  productModel: string;
  productDescription: string;
  quantity: number;
  price: number;
}
```

## 6. 部署与环境

### 6.1 环境变量
- `VITE_API_BASE_URL`: 后端API地址
- `VITE_FILE_BASE_URL`: 文件服务器地址 (用于图片/PDF预览)

### 6.2 微信小程序适配
- 使用 `viewport` meta 标签禁止缩放。
- 检测 `window.__wxjs_environment` 识别环境。
- 使用 `@vant/touch-emulator` 在桌面端调试触摸事件。

## 7. 更新日志

### v1.4 - 2026-01-06 (Current)
**文档同步更新**
- 根据实际代码库结构和API实现更新了概要设计文档。
- 明确了订单审批与采购审批使用不同的提交接口。
- 完善了采购模块的接口定义和数据模型描述。
- 确认了项目采用 Vue 3.3 + Vite 4.4 + Vant 4.6 技术栈。

### v1.3 - 2025-12-01
**功能完善：实现采购详情页面**
- 独立实现采购详情页面 `PurchaseDetail`。
- 对接采购详情接口和状态管理。

### v1.2 - 2025-12-01
**功能实现：对接采购审批接口**
- 实现采购待审批列表。
- 预留已审批列表对接逻辑。

### v1.1 - 2025-12-01
**架构优化：添加左侧抽屉菜单**
- 重构 `Home` 页面，引入抽屉菜单切换 "订单审批" 和 "采购审批"。