liufumingren a667f1401e feat(inbox): 推送失败自动重发改为仓库级开关与重发时间范围(默认关闭)
仓库设置新增嵌套配置 `subject_config.inbox_push_retry = { enabled, window_minutes }`,
结构与「收货未入库提醒」(receiving_pending_inbound_notice)保持一致:

- `enabled`:默认 false —— 未配置、配置缺失或无法读取时一律**关闭**,需在仓库设置中显式开启
- `window_minutes`:重发时间范围,单位**分钟**,1-1440,默认 30(仅开关开启时生效)

改动:

- app/model/store.js:新增 DEFAULT_INBOX_PUSH_RETRY 与 normalizeInboxPushRetry(非法结构/非法 JSON
  回退默认;enabled 非布尔值、window_minutes 越界抛「subject_config.inbox_push_retry.window_minutes
  必须是 1-1440 的整数(分钟)」),由 normalizeSubjectConfig 统一调用
- app/service/systems/setting/warehouse.js:WAREHOUSE_SETTING_FIELDS 新增 key=inbox_push_retry
  (type=object + item_keys=[enabled, window_minutes]),供仓库设置页经 getFieldMeta 动态渲染
- app/service/inbox/message.js:retryFailedByWarehouse 逐仓读仓库设置(缺省关闭、按仓库配置的窗口
  调用 retryFailed);retryFailed 新增 warehouseId 过滤;readPushRetryConfig 读嵌套结构并兜底
  enabled=false / 30 分钟
- app/schedule/retry_inbox_push.js:注释同步为「仅处理显式开启的仓库、缺省 30 分钟」
- config/config.default.js:兜底失败时间窗 2 小时 → 30 分钟;pushRetryEnabled 保留为全局应急总闸
  (默认 true,关闭后所有仓库都不重发)

单测:test/inbox/retry_inbox_push.test.js + test/app/model/store.test.js 共 40 passing,覆盖默认关闭、
非法结构回退、flag 真值归一化、窗口 1-1440 越界、仓库开关与自定义窗口、复用原记录等场景。
2026-09-16 15:04:25 +08:00
1
2026-08-12 23:09:28 +08:00
2026-03-16 14:01:22 +08:00
2026-03-16 14:01:22 +08:00
2026-03-16 14:01:22 +08:00
2026-04-17 19:21:57 +08:00
2026-03-16 14:01:22 +08:00
1
2026-06-14 19:03:58 +08:00

奇门WMS(qimen-wms)

基于 Egg.js 的仓储管理系统(WMS),支持支持多快递平台对接、订单管理、打印、权限、配置等功能,适合中小型电商与仓储企业二次开发。

文档导航

  • 项目协作工具箱:AI_TOOLBOX.md
  • Method 路由映射说明:AI_METHOD_ROUTING.md
  • system 接口文档源:methods/system.json
  • qimen 接口文档源:methods/qimen.json
  • 配置驱动报表配置说明:docs/report-config-guide.md
  • 日报:day.log

项目目录结构

├── app/                # 业务主目录(controller, service, model, router 等)
│   ├── controller/     # 控制器(API、文档、模板、认证等)
│   ├── service/        # 业务服务(system/qimen/print 等)
│   ├── model/          # Sequelize 模型
│   ├── dict/           # 业务字典
│   ├── view/           # 前端模板
│   └── router.js       # 路由定义
├── config/             # 配置(poloapi、redis、数据库等)
├── database/           # 迁移与数据库配置
├── methods/            # 接口文档数据源(JSON)
├── script/             # 调试与文档生成脚本
├── logs/               # 日志
├── run/                # 运行时/元数据
├── test/               # 单元测试
├── app.js              # 应用入口
├── package.json        # 依赖与脚本
└── README.md           # 项目说明

文档结构

  • README.md:项目入口文档,提供整体说明与规范入口。
  • AI_TOOLBOX.md:AI/开发协作操作手册,包含脚本与工作流。
  • AI_METHOD_ROUTING.md:接口入口与 method 到代码文件的映射。
  • methods/system.json:system 接口定义(headers、groups、params、response、errors)。
  • methods/qimen.json:qimen 接口定义(按奇门协议组织)。
  • docs/report-config-guide.md:配置驱动通用报表(wms_report_definition 三段 JSON 配置、内置查询器口径)与货主定时投递说明。
  • day.log:每日工作留痕。

快速开始

npm install
npm run dev

默认访问地址:http://localhost:6060/

运行命令

  • npm run dev:本地开发
  • npm start:启动生产服务
  • npm stop:停止生产服务
  • npm run lint:代码风格检查
  • npm test:单元测试

主要依赖

  • egg.js 3.x
  • egg-sequelize、egg-mysql、egg-redis
  • egg-jwt、egg-cors、egg-view-ejs
  • fast-xml-parser、cos-js-sdk-v5、qiniu-js、soap

接口入口

  • GET /:健康检查
  • POST /qimen:奇门接口
  • POST /system:system 统一入口
  • POST /api/v1:旧版 API
  • POST /api/v2:新版 API
  • GET /template/xml/:id:打印模板
  • GET|POST /auth/printSetting/:code:打印台设置

API 文档与调试

  • GET /api/docs:默认文档页
  • GET /api/docs/:docName:按文档名查看(如 system、qimen)
  • GET /api/docs/:docName/raw:查看原始 JSON

文档页能力:

  • 分组折叠与 method 搜索
  • 全局 Authorization 设置
  • 全局业务 Header(如 platform、project)设置
  • 方法级在线 POST 调试

接口文档联动维护(强制)

当出现以下任一变更时,必须同步更新 methods 下对应文档:

  1. 新增接口 method
  2. 修改接口参数(新增/删除/重命名/必填变化)
  3. 修改公共 Header(如 platform、project、Authorization)
  4. 修改响应结构或错误码

建议流程:

  1. 先完成代码改动(controller/service/model)
  2. 按 docs/api-doc-update-workflow.md 复制固定 spec 到 temp/,默认通过 npm run doc:api:update -- --spec=... 写入 methods/*.json
  3. system 参数改动后可先执行:
node .\script\tmp-struct-system-params.cjs
  1. 先执行:
npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run
  1. 确认无误后执行正式写入,再补充自动提取无法覆盖的信息(description/response/errors/枚举约束)

配置说明

  • 主要配置文件在 config/(如 config.default.js、config.local.js、poloapi.js)
  • 数据库、Redis、平台配置在对应配置文件中维护
  • 敏感信息不要提交到仓库

功能模块

  • 多快递平台对接(快手/PolyAPI 等)
  • 订单管理与履约
  • 打印与打印台管理
  • 仓库/门店管理
  • 权限与角色管理
  • Excel 表格生成、导入与解析

Excel 服务能力

系统已提供服务类:app/service/systems/excel.js,可通过 ctx.service.systems.excel 调用。

支持能力:

  • 生成单 sheet / 多 sheet Excel
  • 按 columns + rows 输出表格
  • 输出 Buffer、写入本地文件、直接作为下载响应返回
  • 解析 .xlsx / .xls 文件内容为 JSON
  • 自动处理空表头、重复表头

常用方法:

  • generateBuffer(options):生成 Excel 二进制内容
  • writeFile(filePath, options):写入本地文件
  • sendFile({ filename, sheets }):HTTP 下载输出
  • parseBuffer(buffer, options):解析上传后的文件流
  • parseFile(filePath, options):解析本地 Excel 文件

示例:

const buffer = await ctx.service.systems.excel.generateBuffer({
  sheets: [
    {
      name: '入库单',
      columns: [
        { header: '单号', key: 'order_no', width: 20 },
        { header: '货主', key: 'owner_name', width: 18 },
      ],
      rows: [
        { order_no: 'RK20260404001', owner_name: '测试货主' },
      ],
    },
  ],
});

const parsed = await ctx.service.systems.excel.parseFile('D:/tmp/demo.xlsx');

常见问题

  • 启动端口默认 6060,可在配置中调整
  • 数据库/Redis 连接失败优先检查 config/config.local.js
  • 接口路由映射可查阅 AI_METHOD_ROUTING.md

日报维护

  • 日报统一记录在 day.log
  • 每次更新日报内容时,需同步更新 day.log

参考

Description
No description provided
Readme 65 MiB
Languages
JavaScript 99.8%