SFT/mock-server

Mock Server 使用说明

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

启动方式

npm run mock

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

$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 进程即可恢复到初始种子状态。