API接口

调用规则

给其它项目调用时，优先使用 /api/v1/... 路径。生产基础地址当前是 http://47.103.138.205:3000。如果配置了只读 Token，请在 Header 里传 X-Api-Token 或 Authorization: Bearer TOKEN。

curl -H "X-Api-Token: 你的Token" \
  "http://47.103.138.205:3000/api/v1/goods/list?page=1&pageSize=50"

主数据中心

所有业务看板接入前，先看这个状态接口判断哪些主数据已经归口，哪些还是待迁移或部分接入。

GET /api/v1/master-data/status

统一主数据域状态

GET /api/v1/master-data/status

万里牛商品信息

这是你要给别的模块用的核心商品信息接口，来自本地长期保存的万里牛商品主数据表。

GET /api/v1/goods/stats

商品总数、标记、停用规格统计

GET /api/v1/goods/stats

GET /api/v1/goods/categories

统一商品分类树

GET /api/v1/goods/categories

GET /api/v1/goods/list

分页商品列表，含规格摘要

GET /api/v1/goods/list?page=1&pageSize=50&keyword=NK073&category=女士内裤&goodsMark=自产

GET /api/v1/goods/disabled-fabrics

停用面料/停用规格聚合

GET /api/v1/goods/disabled-fabrics?page=1&pageSize=50&keyword=黑色

SCM商品信息

GET /api/v1/scm-goods/stats

SCM商品/规格统计

GET /api/v1/scm-goods/stats

GET /api/v1/scm-goods/categories

SCM商品分类树

GET /api/v1/scm-goods/categories

GET /api/v1/scm-goods/list

分页 SCM 商品列表

GET /api/v1/scm-goods/list?page=1&pageSize=50&keyword=TZ016&category=女士秋衣

商品SKU映射

订单同步和外部项目生成 SCM 单时，优先用这里的万里牛 SKU 到 SCM SKU 的长期映射。

GET /api/v1/goods-mapping/stats

映射总览和待处理数量

GET /api/v1/goods-mapping/stats

GET /api/v1/goods-mapping/list

映射列表

GET /api/v1/goods-mapping/list?page=1&pageSize=50&status=matched&keyword=TZ016

GET /api/v1/goods-mapping/resolve

按万里牛条码/规格解析 SCM SKU

GET /api/v1/goods-mapping/resolve?barcode=TZ016014255&goodsCode=TZ016

供应商

供应商接口会保留万里牛组别：9=自产，4/5/6/7/8=外采，并通过供应商映射解析 SCM 供应商。万里牛商品同步和 SCM 商品同步会自动沉淀两侧供应商。

GET /api/v1/suppliers/stats

供应商统计

GET /api/v1/suppliers/stats

GET /api/v1/suppliers/list

供应商/映射列表

GET /api/v1/suppliers/list?side=mapping&page=1&pageSize=50&groupKind=outsourced

GET /api/v1/suppliers/resolve

按万里牛供应商解析 SCM 供应商

GET /api/v1/suppliers/resolve?supplierName=供应商名称&groupId=4

采购订单

业务看板读取采购订单时使用这里，不再依赖订单同步页面接口。字段包含万里牛单号、供应商、SCM单号、同步状态、工单号和明细汇总。

GET /api/v1/purchase-orders/stats

采购订单统计

GET /api/v1/purchase-orders/stats

GET /api/v1/purchase-orders/list

采购订单分页列表

GET /api/v1/purchase-orders/list?page=1&pageSize=50&status=success&keyword=CG202606

GET /api/v1/purchase-orders/{id}

单据详情和 SKU 明细

GET /api/v1/purchase-orders/1

工单进度

工单进度从 SCM 单号、GD 工单、完工回填字段整理出来，供其它看板直接读取。

GET /api/v1/order-progress/stats

工单进度统计

GET /api/v1/order-progress/stats

GET /api/v1/order-progress/list

工单进度分页列表

GET /api/v1/order-progress/list?page=1&pageSize=50&status=in_progress&keyword=GD202606

GET /api/v1/order-progress/{id}/events

单据进度事件流

GET /api/v1/order-progress/1/events

库存

库存接口读取统一数据中心：库存来自万里牛库存修改时间接口，销售只保留近7天SKU日聚合，不保存销售明细。

GET /api/v1/inventory/status

库存销售指标新鲜度

GET /api/v1/inventory/status

GET /api/v1/inventory/stats

库存快照统计

GET /api/v1/inventory/stats

GET /api/v1/inventory/list

库存快照分页列表

GET /api/v1/inventory/list?page=1&pageSize=50&keyword=TZ016

GET /api/v1/inventory/center

其他项目统一取数接口

GET /api/v1/inventory/center?page=1&pageSize=200&keyword=BX130
GET /api/v1/inventory/center?page=1&pageSize=50&group=product

灾备备份

主数据中心的核心数据在生产数据库里。每次生产部署前会短暂停止主容器并自动做强一致数据库备份，也可以手动执行备份；恢复流程见仓库文档 docs/disaster-recovery.md。

RUN npm run backup:production

服务器远程生成数据库备份

npm run backup:production

RUN npm run backup:production -- --download

生成远程备份并下载到本机

npm run backup:production -- --download

RUN BACKUP_STOP_CONTAINER=1 npm run backup:production

短暂停容器后生成强一致备份

BACKUP_STOP_CONTAINER=1 npm run backup:production

GET /api/v1/backups/status

查看最近数据库备份状态

GET /api/v1/backups/status

GET /api/v1/master-data/health

主数据健康总览

GET /api/v1/master-data/health

GET /api/v1/security/api-token/status

API Token 配置状态

GET /api/v1/security/api-token/status

GET /api/ops/status

运维状态聚合：版本、备份、恢复演练、Token、映射写保护、补填任务

GET /api/ops/status

RUN npm run backup:production:offsite

npm run backup:production:offsite

RUN npm run backup:restore-drill

用本机异地备份做恢复演练

npm run backup:restore-drill

运维任务/审计

主数据中心使用这些内部接口展示任务运行、巡检历史、权限分层和关键写操作审计。同源页面可读，外部调用需要 API Token；写操作需要管理密码。

GET /api/tasks/status

统一任务中心

GET /api/tasks/status

GET /api/tasks/runs

任务运行记录

GET /api/tasks/runs?limit=50&type=goods_sync

GET /api/tasks/run

任务详情和关联审计

GET /api/tasks/run?runId=goods_sync-...
说明：兼容旧采购同步 sync_logs 运行记录。

POST /api/tasks/run

统一重跑任务

POST /api/tasks/run
Header: X-Admin-Password: 管理密码
{"type":"goods_sync","params":{"maxPages":1}}

POST /api/tasks/cancel

请求取消运行中任务

POST /api/tasks/cancel
Header: X-Admin-Password: 管理密码
{"runId":"goods_sync-..."}

GET /api/ops/history

运维巡检历史快照

GET /api/ops/history?limit=50

GET /api/ops/trends

备份/恢复演练/主键缺失/任务异常趋势

GET /api/ops/trends?limit=48

GET /api/audit/summary

关键主数据表审计摘要

GET /api/audit/summary

GET /api/audit/events

人工写操作审计事件

GET /api/audit/events?limit=80&entityType=goods_sku_mapping

GET /api/security/permissions

API 权限分层矩阵

GET /api/security/permissions

GET /api/goods-mapping/conflicts

映射冲突工作台数据

GET /api/goods-mapping/conflicts?sampleSize=8

POST /api/goods-mapping/conflicts/action

冲突桶批量处理

POST /api/goods-mapping/conflicts/action
Header: X-Admin-Password: 管理密码
{"action":"ignore","bucket":"stopped","limit":50}

维护类接口

这些接口会触发同步、写入或刷新数据，需要管理密码，给内部维护使用，不建议其它业务模块直接调用。

POST /api/goods-sync/trigger

POST /api/goods-sync/trigger
Header: X-Admin-Password: 管理密码
{"fullSync":true,"pageSize":50}

POST /api/scm-goods-sync/trigger

POST /api/scm-goods-sync/trigger
Header: X-Admin-Password: 管理密码
{"pageSize":50}

POST /api/goods-mapping/refresh

POST /api/goods-mapping/refresh

POST /api/suppliers/v1/mapping/refresh

POST /api/suppliers/v1/mapping/refresh
Header: X-Admin-Password: 管理密码

POST /api/suppliers/v1/import-goods-suppliers

POST /api/suppliers/v1/import-goods-suppliers
Header: X-Admin-Password: 管理密码

POST /api/suppliers/v1/import-scm-goods-suppliers

POST /api/suppliers/v1/import-scm-goods-suppliers
Header: X-Admin-Password: 管理密码

POST /api/inventory/v1/import

POST /api/inventory/v1/import
Header: X-Admin-Password: 管理密码
{"source":"optimization_dashboard","replaceSource":true,"rows":[]}

RUN npm run inventory:import-optimization

npm run inventory:import-optimization

RUN npm run api-token:configure

npm run api-token:configure