# Mock Server 使用说明

本目录提供“凡荣e链前端”管理后台的本地 Mock 后端,用于在真实后端不可用时进行前端联调与演示。
所有接口路径、请求/响应字段严格对齐 `swagger_project_scfs_2026-07-09_14-15-23.json` 及项目前端
实际调用代码(`src/api/*.js`),核心业务规则(登录锁定、状态流转、余额扣减、发票匹配/结算等)均
为真实本地状态维护,而非纯占位透传。

## 启动方式

```bash
npm run mock
```

默认监听端口 `8888`,可通过环境变量 `MOCK_PORT` 覆盖:

```bash
$env:MOCK_PORT=9000; npm run mock   # PowerShell
```

## 与前端配合使用

项目 `.env.development` 中 `VITE_API_BASE_URL` 默认已指向 `http://localhost:8888`,因此本地开发
`npm run dev` 默认即请求本 Mock Server,无需任何额外配置。

若需切换到真实后端,或临时切换回 Mock:登录页右上角齿轮图标 →「接口地址设置」弹窗,填入目标地址
(如真实后端地址或 `http://localhost:8888`)并保存即可,浏览器刷新后立即生效,无需重新构建。

## 测试账号

| 用户名 | 密码 | 角色 |
| --- | --- | --- |
| admin | Admin@123 | 系统管理员(全权限) |

短信验证码登录/操作场景下,万能验证码 `123456` 始终有效;真实生成的验证码会打印在 Mock Server 控制台。

## 目录结构

```
mock-server/
├── index.js               # 入口:装配全部路由、CORS、Cookie 解析、全局错误处理
├── state.js                # 全局内存态:accessToken/refreshToken/短验码/登录失败计数等
├── middleware/
│   └── requireAuth.js      # 鉴权中间件:校验 Authorization: Bearer <accessToken>
├── utils/
│   ├── response.js         # 统一 {code, message, data} 响应封装
│   ├── pagination.js       # 分页工具
│   └── id.js               # 各实体独立自增数字 id 生成器
├── db/                      # 各模块种子数据(内存数组,进程重启后重置)
│   └── seed*.js
└── routes/                  # 各模块路由(Express Router)
    └── *.js
```

## 已知简化点 / 未文档化项

以下内容在真实后端 Swagger 中缺失或语义不明确,Mock 按前端实际调用代码/《缺失的后端接口.md》中登记
的权变方案实现,如后续真实后端契约变更,需同步调整:

- `POST /api/payment/query-credit-quota`:响应结构完全未文档化,Mock 自行假设为
  `{ accountNo, creditLimit, usedAmount, availableAmount }`。
- `POST /api/original-order/export`:响应结构未文档化,Mock 沿用项目既有 `{ fileData: base64 }` 约定,
  返回一段占位内容,仅用于打通下载流程,不代表真实 Excel 内容。
- `original-order/page` 仅支持 `originalOrderNo` 过滤;`summary-order/page` 仅支持 `orderNo` 过滤;
  均不支持按渠道/日期范围/汇总订单编号等条件过滤(与真实后端能力一致)。
- 商户模块无 `detail`/审批接口,前端“查看/编辑”依赖路由带参,审批用启用/停用状态切换代替。
- 发票取消匹配(`unmatch`)按发票级别 `settleStatus !== 'UNSETTLED'` 时禁止操作(简化判断,未按明细粒度校验)。
- 商户/发票/支付/贷款申请等模块的 `id` 统一为数字自增,`loanApplicationId`/`merchantNo`/`invoiceNo` 等
  业务编号为字符串,两者并存,前端各处按实际使用字段区分。
- `dict-management/dict-type/*`(字典类型管理):2026-07-31 起已按最新 swagger
  (`swagger_project_scfs_2026-07-31_09-25-57.json`,`dict_management` 分组)核对确认分页/创建/
  编辑/删除全部 4 个接口的真实路径与字段,`dictCategory` 取值 `NORMAL`/`CASCADE`,`status` 取值
  `ENABLED`/`DISABLED`,本 mock 已同步调整,不再是前端占位契约。
- `dict-management/dict-item/*`、`dict-management/dict-items/*`(字典项管理):2026-07-31 起已按
  最新 swagger 核对确认全部 6 个接口的真实路径与字段(`dict-items/list`/`dict-items/tree`/
  `dict-items/children` 三个只读接口 + `dict-item/create`/`update`/`delete`),本 mock 已同步调整。
  **注意**:`dict-items/list`/`dict-items/tree` 实测会返回 `id`/`sortOrder`(swagger 未完整声明该
  字段,以实测为准),`DictItemTree.vue` 已按此直接支持对已存在字典项的修改/删除/子级新增,mock
  同步在这两个接口的响应里附带 `id`,详见《缺失的后端接口.md》Part 14.2 的更新记录。

## 数据重置

Mock 数据全部保存在内存中,重启 `npm run mock` 进程即可恢复到初始种子状态。