新增 app/schedule/retry_inbox_push.js:每 3 分钟扫描「push_status=3 且失败时间在 2 小时内」的
出站消息并重推(config.inbox.pushRetryWindowMs / pushRetryLimit,单轮默认 20 条、硬上限 200),
成功即停、失败下一轮继续、超出窗口不再补推;worker 单进程执行 + app._inboxPushRetryRunning
重入锁,scanned>0 才写日志。
- inbox.message 新增 retryFailed():按 created_at ASC 逐条串行重推(先补更接近窗口边界的),
缺 warehouse_id/group_id/group_name/content 的记录跳过并告警,retry_count 递增仅作观测
- inbox.message 新增 _repush():复用原记录重推(reuse_message_id),ext_id 剥离 sys:ack: 前缀,
有用户信息走 ai_reply、系统通知走 system;重推期间不改记录状态,进程中断时下一轮仍能扫到
- processor.writeOutboundReply 支持 reuse_message_id:重推时跳过按 sys:ack:{ext_id} 查建记录,
推送结果回写到原记录本身,修复系统通知(sys:notice:*)重推会另建记录、原记录状态永远停留在
失败/待推送的问题;状态回写由 ext_id 改为按记录 id(对既有调用路径等价)
- 手动重推 retry() 改走 _repush,入参与响应文案不变,methods/system.json 无需变更
失败主因是桥接离线(回调 HTTP 200 但 body code=503:wx offline / qiwe offline),属可自愈的
临时故障;此前仅支持人工单条重推,生产已积压 2441 条未送达的客户回信与系统通知。
单测 test/inbox/retry_inbox_push.test.js 18 例(纯 mock,覆盖调度配置/重入/异常兜底/扫描条件/
窗口与上限/复用原记录/跳过与容错);AI_METHOD_ROUTING.md 方法清单已刷新(inbox/message.js 7 → 9)。
奇门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:旧版 APIPOST /api/v2:新版 APIGET /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 下对应文档:
- 新增接口 method
- 修改接口参数(新增/删除/重命名/必填变化)
- 修改公共 Header(如
platform、project、Authorization) - 修改响应结构或错误码
建议流程:
- 先完成代码改动(controller/service/model)
- 按 docs/api-doc-update-workflow.md 复制固定 spec 到
temp/,默认通过npm run doc:api:update -- --spec=...写入methods/*.json - system 参数改动后可先执行:
node .\script\tmp-struct-system-params.cjs
- 先执行:
npm run doc:api:update -- --spec=temp/api-doc-update.json --dry-run
- 确认无误后执行正式写入,再补充自动提取无法覆盖的信息(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
参考
- Egg.js 官方文档:https://v3.eggjs.org/
Description
Languages
JavaScript
99.8%