# yoe-shop-web 企业工作台接口文档

## 项目概述

## 张林的交接文档。

## 有一个问题：你记得我们写的pc接口的gateway可能会和之前的后台管理系统有冲突导致404，你得去gateway.yml文件里专门配置一下。

## 技术栈

- Vue 3.5.22
- TypeScript 5.9.3
- Element Plus 2.11.7
- Vite 6.4.1
- Axios 1.13.1

## API 文件结构

```
src/api/pc/
├── enterprise/          # 企业相关接口
│   ├── index.ts        # 企业信息、地址、发票
│   ├── order.ts        # 订单管理
│   ├── orderReturn.ts  # 售后服务
│   ├── statement.ts    # 对账单管理
│   └── invoice.ts      # 发票信息
├── organization/        # 组织管理接口
│   └── index.ts        # 部门、人员、角色
└── system/             # 系统接口
    ├── dict.ts         # 字典数据
    └── announcement.ts # 平台公告
```

---

## 一、企业账户模块

### 1.1 企业信息页面

**页面路径**: `src/views/enterprise/companyInfo/index.vue`

**API 文件**: `src/api/pc/enterprise/index.ts`

**接口列表**:

| 接口路径              | 方法 | 功能         | 函数名                       |
| --------------------- | ---- | ------------ | ---------------------------- |
| `/pc/enterprise/info` | GET  | 查询企业信息 | `getEnterpriseInfo()`        |
| `/pc/enterprise/info` | PUT  | 修改企业信息 | `updateEnterpriseInfo(data)` |

### 1.2 收货地址管理

**页面路径**: `src/views/easybuv/index.vue`

**API 文件**: `src/api/pc/enterprise/index.ts`

**接口列表**:

| 接口路径                         | 方法   | 功能             | 函数名                   |
| -------------------------------- | ------ | ---------------- | ------------------------ |
| `/pc/enterprise/address/list`    | GET    | 查询收货地址列表 | `getAddressList(params)` |
| `/pc/enterprise/address/{id}`    | GET    | 查询收货地址详情 | `getAddressInfo(id)`     |
| `/pc/enterprise/address`         | POST   | 新增收货地址     | `addAddress(data)`       |
| `/pc/enterprise/address`         | PUT    | 修改收货地址     | `updateAddress(data)`    |
| `/pc/enterprise/address/{ids}`   | DELETE | 删除收货地址     | `deleteAddress(ids)`     |
| `/pc/enterprise/address/default` | PUT    | 设置默认地址     | `setDefaultAddress(id)`  |

### 1.3 发票信息管理

**页面路径**: `src/views/enterprise/invoiceManage/index.vue`

**API 文件**: `src/api/pc/enterprise/index.ts`

**接口列表**:

| 接口路径                       | 方法   | 功能             | 函数名                   |
| ------------------------------ | ------ | ---------------- | ------------------------ |
| `/pc/enterprise/invoice/list`  | GET    | 查询发票信息列表 | `getInvoiceList(params)` |
| `/pc/enterprise/invoice/{id}`  | GET    | 查询发票详情     | `getInvoiceInfo(id)`     |
| `/pc/enterprise/invoice`       | POST   | 新增发票         | `addInvoice(data)`       |
| `/pc/enterprise/invoice`       | PUT    | 修改发票         | `updateInvoice(data)`    |
| `/pc/enterprise/invoice/{ids}` | DELETE | 删除发票         | `deleteInvoice(ids)`     |

### 1.4 专属服务人员

**API 文件**: `src/api/pc/enterprise/servicePerson.ts`

**接口列表**:

| 接口路径                            | 方法 | 功能             | 函数名                |
| ----------------------------------- | ---- | ---------------- | --------------------- |
| `/pc/enterprise/servicePerson/list` | GET  | 查询专属服务人员 | `getServicePersons()` |

---

## 二、交易管理模块

### 2.1 订单管理

**页面路径**: `src/views/order/orderManage/index.vue`

**API 文件**: `src/api/pc/enterprise/order.ts`

**接口列表**:

| 接口路径                           | 方法   | 功能             | 函数名                       |
| ---------------------------------- | ------ | ---------------- | ---------------------------- |
| `/pc/enterprise/order/list`        | GET    | 查询订单列表     | `getOrderList(params)`       |
| `/pc/enterprise/order/statusStats` | GET    | 查询订单状态统计 | `getOrderStatusStats()`      |
| `/pc/enterprise/order/{id}`        | GET    | 查询订单详情     | `getOrderInfo(id)`           |
| `/pc/enterprise/order/products`    | GET    | 查询订单商品明细 | `getOrderProducts(orderIds)` |
| `/pc/enterprise/order/cancel`      | PUT    | 取消订单         | `cancelOrder(data)`          |
| `/pc/enterprise/order/checkStatus` | PUT    | 审核订单         | `checkOrderStatus(data)`     |
| `/pc/enterprise/order/{ids}`       | DELETE | 删除订单         | `deleteOrder(ids)`           |

### 2.2 售后服务

**页面路径**: `src/views/order/afterSale/index.vue`

**API 文件**: `src/api/pc/enterprise/orderReturn.ts`

**接口列表**:

| 接口路径                           | 方法   | 功能             | 函数名                       |
| ---------------------------------- | ------ | ---------------- | ---------------------------- |
| `/pc/enterprise/orderReturn/list`  | GET    | 查询售后申请列表 | `getOrderReturnList(params)` |
| `/pc/enterprise/orderReturn/{id}`  | GET    | 查询售后详情     | `getOrderReturnInfo(id)`     |
| `/pc/enterprise/orderReturn`       | POST   | 新增售后申请     | `addOrderReturn(data)`       |
| `/pc/enterprise/orderReturn`       | PUT    | 修改售后申请     | `updateOrderReturn(data)`    |
| `/pc/enterprise/orderReturn/{ids}` | DELETE | 删除售后申请     | `deleteOrderReturn(ids)`     |

---

## 三、组织管理模块

### 3.1 部门管理

**页面路径**: `src/views/organization/deptManage/index.vue`

**API 文件**: `src/api/pc/organization/index.ts`

**接口列表**:

| 接口路径                      | 方法   | 功能         | 函数名                |
| ----------------------------- | ------ | ------------ | --------------------- |
| `/pc/organization/dept/tree`  | GET    | 查询部门树   | `getDeptTree()`       |
| `/pc/organization/dept/list`  | GET    | 查询部门列表 | `getDeptList(params)` |
| `/pc/organization/dept/{id}`  | GET    | 查询部门详情 | `getDeptInfo(id)`     |
| `/pc/organization/dept`       | POST   | 新增部门     | `addDept(data)`       |
| `/pc/organization/dept`       | PUT    | 修改部门     | `updateDept(data)`    |
| `/pc/organization/dept/{ids}` | DELETE | 删除部门     | `deleteDept(ids)`     |

### 3.2 人员管理

**页面路径**: `src/views/organization/staffManage/index.vue`

**API 文件**: `src/api/pc/organization/index.ts`

**接口列表**:

| 接口路径                           | 方法   | 功能             | 函数名                   |
| ---------------------------------- | ------ | ---------------- | ------------------------ |
| `/pc/organization/contact/current` | GET    | 获取当前用户信息 | `getCurrentUserInfo()`   |
| `/pc/organization/contact/list`    | GET    | 查询联系人列表   | `getContactList(params)` |
| `/pc/organization/contact/{id}`    | GET    | 查询联系人详情   | `getContactInfo(id)`     |
| `/pc/organization/contact`         | POST   | 新增联系人       | `addContact(data)`       |
| `/pc/organization/contact`         | PUT    | 修改联系人       | `updateContact(data)`    |
| `/pc/organization/contact/{ids}`   | DELETE | 删除联系人       | `deleteContact(ids)`     |

### 3.3 角色管理

**页面路径**: `src/views/organization/roleManage/index.vue`

**API 文件**: `src/api/pc/organization/index.ts`

**接口列表**:

| 接口路径                      | 方法   | 功能         | 函数名                |
| ----------------------------- | ------ | ------------ | --------------------- |
| `/pc/organization/role/list`  | GET    | 查询角色列表 | `getRoleList(params)` |
| `/pc/organization/role/{id}`  | GET    | 查询角色详情 | `getRoleInfo(id)`     |
| `/pc/organization/role`       | POST   | 新增角色     | `addRole(data)`       |
| `/pc/organization/role`       | PUT    | 修改角色     | `updateRole(data)`    |
| `/pc/organization/role/{ids}` | DELETE | 删除角色     | `deleteRole(ids)`     |

---

## 四、对账管理模块

### 4.1 对账单管理

**页面路径**: `src/views/reconciliation/billManage/index.vue`

**API 文件**: `src/api/pc/enterprise/statement.ts`

**接口列表**:

| 接口路径                               | 方法 | 功能               | 函数名                            |
| -------------------------------------- | ---- | ------------------ | --------------------------------- |
| `/pc/enterprise/statement/list`        | GET  | 查询对账单列表     | `getStatementList(params)`        |
| `/pc/enterprise/statement/{id}`        | GET  | 查询对账单详情     | `getStatementInfo(id)`            |
| `/pc/enterprise/statement/details`     | GET  | 查询对账单明细列表 | `getStatementDetails(params)`     |
| `/pc/enterprise/statement/confirm`     | PUT  | 确认对账单         | `confirmStatement(data)`          |
| `/pc/enterprise/statement/reject`      | PUT  | 驳回对账单         | `rejectStatement(data)`           |
| `/pc/enterprise/statementDetail/list`  | GET  | 查询对账单明细     | `getStatementDetailList(params)`  |
| `/pc/enterprise/statementProduct/list` | GET  | 查询对账单商品列表 | `getStatementProductList(params)` |
| `/pc/enterprise/statementInvoice/list` | GET  | 查询对账单发票列表 | `getStatementInvoiceList(params)` |

**对账状态说明**:

| 状态值 | 状态名称 | 说明                         |
| ------ | -------- | ---------------------------- |
| 0      | 待确认   | 后台生成对账单，等待企业确认 |
| 1      | 待对账   | 企业可以点击确认按钮         |
| 2      | 已对账   | 对账完成，按钮禁用           |
| 3      | 驳回     | 对账被驳回                   |
| 4      | 作废     | 对账单作废                   |

### 4.2 开票管理

**页面路径**: `src/views/reconciliation/invoiceManage/index.vue`

**API 文件**: `src/api/pc/enterprise/statement.ts`

**接口列表**: 同对账单管理接口

---

## 五、系统功能模块

### 5.1 字典数据

**API 文件**: `src/api/pc/system/dict.ts`

**接口列表**:

| 接口路径                   | 方法 | 功能                     | 函数名                    |
| -------------------------- | ---- | ------------------------ | ------------------------- |
| `/pc/dict/type/{dictType}` | GET  | 根据字典类型查询字典数据 | `getDictByType(dictType)` |

**常用字典类型**:

- `statement_status` - 对账状态
- `invoice_issuance_status` - 开票状态
- `payment_status` - 支付状态

### 5.2 平台公告

**API 文件**: `src/api/pc/system/announcement.ts`

**接口列表**:

| 接口路径                | 方法 | 功能             | 函数名                        |
| ----------------------- | ---- | ---------------- | ----------------------------- |
| `/pc/announcement/list` | GET  | 查询平台公告列表 | `getAnnouncementList(params)` |
| `/pc/announcement/{id}` | GET  | 查询平台公告详情 | `getAnnouncementInfo(id)`     |

---

## 六、后端控制器说明

### 6.1 对账单控制器

**后端文件**: `yoe-core/ruoyi-modules/ruoyi-bill/src/main/java/org/dromara/bill/pc/controller/PcStatementOrderController.java`

**权限控制**:

- PC 端用户只能查询自己企业的对账单
- 只允许查询状态为 1(待对账)、2(已对账)、3(驳回) 的对账单
- 不允许查询状态为 0(待确认)、4(作废) 的对账单

**核心方法**:

- `list()` - 查询对账单列表（带权限过滤）
- `getInfo()` - 查询对账单详情（验证企业权限）
- `confirm()` - 确认对账单（将状态从 1 改为 2）
- `reject()` - 驳回对账单（将状态改为 3）

---

## 七、开发环境配置

### 7.1 环境变量

**开发环境** (`.env.development`):

```
VITE_APP_BASE_API=/dev-api
VITE_APP_CONTEXT_PATH=/
```

**代理配置** (`vite.config.ts`):

```typescript
proxy: {
  '/dev-api': {
    target: 'http://localhost:8080',
    changeOrigin: true,
    rewrite: (path) => path.replace(/^\/dev-api/, '')
  }
}
```

### 7.2 启动命令

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build:prod
```

---

## 八、注意事项

1. **接口前缀**: 所有 PC 端接口都以 `/pc` 开头
2. **权限控制**: 后端会根据登录用户的企业 ID 自动过滤数据
3. **状态管理**: 对账状态、开票状态、支付状态都通过字典管理
4. **错误处理**: 统一使用 Element Plus 的 `ElMessage` 显示错误信息
5. **数据刷新**: 操作成功后会自动刷新列表数据

---

## 九、常见问题