From 943c096c5a25bb1b2570e3b16783309f10c8d16f Mon Sep 17 00:00:00 2001 From: liufumingren Date: Fri, 25 Sep 2026 03:14:15 +0800 Subject: [PATCH] =?UTF-8?q?feat(index):=20=E6=96=B0=E5=A2=9E=E5=AE=A2?= =?UTF-8?q?=E6=88=B7=E7=AB=AF=E9=94=99=E8=AF=AF=E6=97=A5=E5=BF=97=E4=B8=8A?= =?UTF-8?q?=E6=8A=A5=E6=8E=A5=E5=8F=A3=20uploadClientErrorLog=EF=BC=88?= =?UTF-8?q?=E5=BB=BA=E8=A1=A8=20wms=5Fclient=5Ferror=5Flog=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增免登录/免权限/免鉴权的设备端运行时错误批量上报接口,保留系统日志: - 建表迁移 database/migrations/20260925100000-create-wms-client-error-log.js(wms_client_error_log,uk_report_uuid 唯一索引幂等去重) - 新增模型 app/model/client_error_log.js 与服务 app/service/systems/client_error_log.js(三种入参形态、字段归一化与长度截断、report_uuid 幂等;bulkCreate 用 validate:false 修复时间戳注入引发的 notNull 写入失败) - systemMethods/index.js 新增 uploadClientErrorLog 出口并登记 _noNeedLogin/_noNeedRight/_noNeedAuth;_noNeedLog 由 '*' 改为显式清单 INDEX_NO_NEED_LOG_METHODS - 文档同步:methods/system.json 版本升至 0.3.190、methods/changes/system.json 新增变更记录、AI_METHOD_ROUTING.md 补充 5.9 能力速查并同步第 6 节方法清单 - 测试:32 个服务层用例与 18 个 HTTP 回归用例通过(test/ 与 test_reports/ 按 .gitignore 约定不入库) --- AI_METHOD_ROUTING.md | 29 +- app/model/client_error_log.js | 112 ++++++++ app/service/systemMethods/index.js | 54 +++- app/service/systems/client_error_log.js | 255 ++++++++++++++++++ ...60925100000-create-wms-client-error-log.js | 115 ++++++++ methods/changes/system.json | 21 ++ methods/system.json | 169 +++++++++++- 7 files changed, 743 insertions(+), 12 deletions(-) create mode 100644 app/model/client_error_log.js create mode 100644 app/service/systems/client_error_log.js create mode 100644 database/migrations/20260925100000-create-wms-client-error-log.js diff --git a/AI_METHOD_ROUTING.md b/AI_METHOD_ROUTING.md index 775f6cf..0f92ac2 100644 --- a/AI_METHOD_ROUTING.md +++ b/AI_METHOD_ROUTING.md @@ -294,6 +294,20 @@ rg "class .*Service|module.exports" app/service/qimenMethods - 数据表:wms_after_sale_type / wms_after_sale_sub_type(app/model/after_sale_type.js、after_sale_sub_type.js) - 接口文档:methods/system.json 分组「售后模块」(module=afterSale),变更记录见 methods/changes/system.json 版本 2026.09.16-after-sale-type-subtype-crud +## 5.9 index.uploadClientErrorLog(客户端错误日志上报)能力速查 + +| method | 实现文件 | 函数 | 登录 | 鉴权/权限 | +|---|---|---|---|---| +| index.uploadClientErrorLog | app/service/systemMethods/index.js → app/service/systems/client_error_log.js | uploadClientErrorLog / upload | 免登录 | 免权限、免鉴权(systemInit 声明) | + +- 语义:设备端(android/ios/web)将运行时错误日志批量上报暂存到新表 wms_client_error_log,供后台查询分析;免登录、免权限、免鉴权,保留系统日志(不在 INDEX_NO_NEED_LOG_METHODS 清单;index 模块日志口径已由通配符改为显式清单) +- 入口:POST /system?method=index.uploadClientErrorLog&v=1×tamp=<数字时间戳>,请求头需 platform/project(根 headers 已声明),无需 Authorization/token +- 入参三种形态:单条对象 / 数组 / { logs: [...] }(单次最多 50 条,超限 code=400);字段 snake_case 为主、兼容 camelCase 别名(clientType/appVersion/deviceId/osVersion/deviceModel/errorType/errorMessage/errorStack/reportUuid/clientTime);error_message 与 error_stack 至少一项有值(超长截断 5000/65535)、extra 截断 65535、字符串列宽 client_type 32 / app_version 64 / device_id 128 / os_version 64 / device_model 128 / error_type 64 / report_uuid 64 超出截断;client_time 支持毫秒/秒时间戳与日期字符串(非法存 null,仅参考) +- 幂等:report_uuid 唯一索引 uk_report_uuid;重复上报 duplicated +1、静默成功不产生重复行;客户端未传时服务端生成 srv-{uuid}(此时不保证幂等);created_at/updated_at 由 Sequelize 统一取服务器时间 +- 出参:成功 { flag:'success', code:200, message:'上报成功', success:true, total, accepted, duplicated, rejected, rejected_reasons(≤10 条,每条 { index, reason }), timestamp };失败 400/500 为 HTTP 200 + { flag:'failure', code, message, timestamp } +- 表结构:wms_client_error_log(迁移 database/migrations/20260925100000-create-wms-client-error-log.js、模型 app/model/client_error_log.js);索引 uk_report_uuid(唯一)、idx_created_at、idx_client_type_app_version、idx_device_id +- 接口文档:methods/system.json 分组「基础模块」(module=index),变更记录见 methods/changes/system.json 版本 `2026.09.25-index-upload-client-error-log` + ## method结束 ## 6. 全量 Service Method 能力清单(自动扫描) @@ -305,10 +319,11 @@ rg "class .*Service|module.exports" app/service/qimenMethods - 临时清单输出:temp/tmp-service-method-inventory.md -自动生成时间: 2026-09-23T17:34:46.974Z +自动生成时间: 2026-09-24T13:58:51.474Z +(2026-09-25 手动补录:systemMethods/index.js 新增 uploadClientErrorLog、新增 systems/client_error_log.js;生成脚本 tmp-gen-service-method-inventory.cjs 不在仓库,待补齐脚本后重扫) 扫描范围: app/service/**/*.js -文件数: 219 +文件数: 220 - app/service/api.js (1) - callMethod @@ -412,8 +427,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - getFrontConfigService, getByDomain, getInfo, getCert, saveInfo, saveCert, setDomain, getDomain, checkDomain - app/service/systemMethods/inbox.js (14) - group, message, v2, after_sales, bindCode, groupList, groupQuickList, groupMembers, groupDisable, groupUpdate, groupReset, groupMessages, retry, reply -- app/service/systemMethods/index.js (59) - - fastWhereTree, loadStores, loadWarehouses, loadExpressInterfaces, getCOSUploadConfig, getImages, uploadSuccessNotify, recognizeLicensePlate, ReferenceFile, getMessageDetail, test, getI18nMessage, putI18nCollect, extractModule, tryAutoTranslateNewKeys, searchSpace, searchSpaces, listInterfaceTypes, getLocationTypeList, getQimenAppList, getExpressList, getExpressProductTypeList, getPlatformList, getPrintPlatformList, ensureShopPrintPlatformExists, buildShopPrintPlatformInclude, getShopList, requestPddWaybillSearch, requestPddStdTemplates, requestTbWaybillSearch, requestTbCainiaoStdTemplates, requestPolyStdTemplates, getShopExpressList, getCainiaoStfTemplates, normalizeTemplatePlatformCode, normalizeTemplateExpressCode, getExpressPlatformFieldName, getTemplateAllowedExpressCodeSet, filterPrintPlatformTemplateResponseData, getPrintPlatformTemplateCacheKey, requestPrintPlatformTemplateList, resolvePddTemplateWpCodeCandidates, requestPddTemplateSourceList, getPrintPlatformTemplateList, isPlatformOauthReservationDuplicateError, getPlatformOauthReservationCodePrefix, hasPlatformOauthReservationCodePrefix, normalizePlatformOauthReservationCode, generatePlatformOauthReservationCode, createPlatformOauthReservation, getPlatformOauthLink, listenPlatformOauthBind, loginToIm, polyapiAuthorizeUrl, toOrder, getWorkbenchBindCode, LoginWorkbenchByCode, queryUserByToken, parseWechatBadgeCode +- app/service/systemMethods/index.js (60) + - fastWhereTree, loadStores, loadWarehouses, loadExpressInterfaces, getCOSUploadConfig, getImages, uploadSuccessNotify, recognizeLicensePlate, ReferenceFile, getMessageDetail, test, getI18nMessage, putI18nCollect, extractModule, tryAutoTranslateNewKeys, searchSpace, searchSpaces, listInterfaceTypes, getLocationTypeList, getQimenAppList, getExpressList, getExpressProductTypeList, getPlatformList, getPrintPlatformList, ensureShopPrintPlatformExists, buildShopPrintPlatformInclude, getShopList, requestPddWaybillSearch, requestPddStdTemplates, requestTbWaybillSearch, requestTbCainiaoStdTemplates, requestPolyStdTemplates, getShopExpressList, getCainiaoStfTemplates, normalizeTemplatePlatformCode, normalizeTemplateExpressCode, getExpressPlatformFieldName, getTemplateAllowedExpressCodeSet, filterPrintPlatformTemplateResponseData, getPrintPlatformTemplateCacheKey, requestPrintPlatformTemplateList, resolvePddTemplateWpCodeCandidates, requestPddTemplateSourceList, getPrintPlatformTemplateList, isPlatformOauthReservationDuplicateError, getPlatformOauthReservationCodePrefix, hasPlatformOauthReservationCodePrefix, normalizePlatformOauthReservationCode, generatePlatformOauthReservationCode, createPlatformOauthReservation, getPlatformOauthLink, listenPlatformOauthBind, loginToIm, polyapiAuthorizeUrl, toOrder, getWorkbenchBindCode, LoginWorkbenchByCode, queryUserByToken, parseWechatBadgeCode, uploadClientErrorLog - app/service/systemMethods/order/archiveOrder.js (2) - list, detail - app/service/systemMethods/order/base.js (56) @@ -558,6 +573,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - list, detail, create, update, setOsd, _findCameraForControl, _assertPtzSuccess, ptzControl, ptzStop, ptzPresetGoto, ptzPresetSet, delete - app/service/systems/cameraServer.js (5) - list, detail, create, update, delete +- app/service/systems/client_error_log.js (5) + - _pick, _toText, _parseClientTime, _normalizeItem, upload - app/service/systems/comboGoods.js (15) - fetchStockInfoMap, buildSimpleNotation, buildNameNotation, validateItems, getTargetStoreIdFromMap, checkCustomCodeUniqueForCreate, checkCustomCodeUniqueForUpdate, list, buildListWhere, create, update, delete, search, searchByIdOrCode, enrichComboList - app/service/systems/delivery_order.js (56) @@ -738,8 +755,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods - toOrder, list, detail, export, buildWaybillExportFile - app/service/systems/wechat.js (35) - getAuthUrl, getAccountInfoSync, resolveWechatApp, loginByCode, getMyLoginCode, bindUser, buildBindResult, bindByEmployee, getUserAgreementText, getUserAgreement, setUserAgreement, findWarehouseWechatApp, findLatestAgreementVersion, getAgreementVersion, cleanupUnusedAgreementVersions, pushLoginCode, queryauth, wxaauth, resolveBodyMedia, resolveMediaValue, downloadFromUrl, resolveMediaFilename, registerMiniprogram, updateInfo, buildHeadimgKey, uploadHeadimg, getTemplateList, hasFuncScope, buildAuthorizerPatch, getAuthorizerInfo, commit, submitAudit, buildTrialQrCodeKey, getTrialQRCode, userList -- app/service/systems/workbench.js (73) - - list, detail, create, update, delete, bindCamera, business, _loadPackCtx, _countWaveOrders, _countWaveOrdersCached, SUM, _sumWaveItemsTotal, _sumWaveItemsTotalCached, _getWaveOrderIds, Set, _buildPackChangeSummary, _writePackOperationLog, _updateOrderPackStatus, _packOrder, resolvePackTaskEndTime, _finishPack, _resetPackOsd, _sendWeight, _writeWeighOpLog, _aggregateWaveItems, _fetchWaveItemsSummary, _fetchOrderItemsDetail, _queryOrder, generatePackCtxKey, getWorkbenchPackCtxCacheKey, getWorkbenchBindClientCacheKey, getWorkbenchBindCodeCacheKey, getWorkbenchTokenCacheKey, generateRandomChars, generateWorkbenchToken, generateWorkbenchLoginCode, normalizeWorkbenchBindCode, generateUniqueWorkbenchLoginCode, createUniqueWorkbenchClientCode, createUniqueWorkbenchBindCode, buildWorkbenchBindState, getWorkbenchBindRemainingSeconds, setWorkbenchBindState, createWorkbenchBindSession, refreshWorkbenchBindCode, formatWorkbenchBindData, waitForWorkbenchBindComplete, getWorkbenchBindCode, formatWorkbenchTokenInfo, listWorkbenchMembers, listCurrentPackTasks, buildCurrentPackingInfo, invalidateWorkbenchTokenCacheByWorkbenchId, buildWorkbenchTokenInfo, bindWorkbench, getWorkbenchInfoByToken, _round2, _formatPackCountTime, buildWorkbenchPackCountTimeRange, getWorkbenchCountByToken, loginWorkbenchByCode, resetLoginCode, clearExpiredWorkbenchTokens, resolveWorkbenchContext, resolveWorkbenchByToken, packOrderByToken, finishPackByToken, sendWeightByToken, queryOrderByToken, normalizeWorkbenchMemberIds, _finishAllPackTasksByMemberLogout, removeWorkbenchMember, bindWorkbenchMember +- app/service/systems/workbench.js (75) + - list, detail, create, update, delete, bindCamera, business, _loadPackCtx, _countWaveOrders, _countWaveOrdersCached, SUM, _sumWaveItemsTotal, _sumWaveItemsTotalCached, _getWaveOrderIds, Set, _buildPackChangeSummary, _writePackOperationLog, _updateOrderPackStatus, _packOrder, resolvePackTaskEndTime, _finishPack, _resetPackOsd, _sendWeight, _writeWeighOpLog, _aggregateWaveItems, _fetchWaveItemsSummary, _fetchOrderItemsDetail, _countCurrentPackMembers, _getBigGroupPackCoefficient, _queryOrder, generatePackCtxKey, getWorkbenchPackCtxCacheKey, getWorkbenchBindClientCacheKey, getWorkbenchBindCodeCacheKey, getWorkbenchTokenCacheKey, generateRandomChars, generateWorkbenchToken, generateWorkbenchLoginCode, normalizeWorkbenchBindCode, generateUniqueWorkbenchLoginCode, createUniqueWorkbenchClientCode, createUniqueWorkbenchBindCode, buildWorkbenchBindState, getWorkbenchBindRemainingSeconds, setWorkbenchBindState, createWorkbenchBindSession, refreshWorkbenchBindCode, formatWorkbenchBindData, waitForWorkbenchBindComplete, getWorkbenchBindCode, formatWorkbenchTokenInfo, listWorkbenchMembers, listCurrentPackTasks, buildCurrentPackingInfo, invalidateWorkbenchTokenCacheByWorkbenchId, buildWorkbenchTokenInfo, bindWorkbench, getWorkbenchInfoByToken, _round2, _formatPackCountTime, buildWorkbenchPackCountTimeRange, getWorkbenchCountByToken, loginWorkbenchByCode, resetLoginCode, clearExpiredWorkbenchTokens, resolveWorkbenchContext, resolveWorkbenchByToken, packOrderByToken, finishPackByToken, sendWeightByToken, queryOrderByToken, normalizeWorkbenchMemberIds, _finishAllPackTasksByMemberLogout, removeWorkbenchMember, bindWorkbenchMember - app/service/warehouse.js (7) - resolveWarehouseMethod, getWarehouseMethodService, dispatchWarehouseMethod, validateWarehouseParams, parseJsonBody, normalizeSignFields, processRequest - app/service/warehouseMethods/inbox.js (2) diff --git a/app/model/client_error_log.js b/app/model/client_error_log.js new file mode 100644 index 0000000..516b329 --- /dev/null +++ b/app/model/client_error_log.js @@ -0,0 +1,112 @@ +'use strict'; + +/** + * 客户端错误日志暂存表模型(wms_client_error_log)。 + * + * Android/iOS/Web 等设备端通过 index.uploadClientErrorLog 上报的运行时错误日志暂存, + * 仅做数据落库供人工/后台查询分析;report_uuid 唯一索引承担幂等去重(重复上报静默成功)。 + * created_at/updated_at 由 Sequelize 时间戳统一取服务器当前时间,不采信客户端时间。 + * + * @param {import('egg').Application} app Egg 应用实例。 + * @return {import('sequelize').ModelCtor} Sequelize 模型。 + */ +module.exports = app => { + const { BIGINT, STRING, DATE, TEXT } = app.Sequelize; + + const ClientErrorLog = app.model.define('client_error_log', { + id: { + type: BIGINT(20).UNSIGNED, + primaryKey: true, + autoIncrement: true, + comment: '主键ID', + }, + client_type: { + type: STRING(32), + allowNull: false, + defaultValue: '', + comment: '客户端类型:android/ios/web 等', + }, + app_version: { + type: STRING(64), + allowNull: false, + defaultValue: '', + comment: '客户端版本号', + }, + device_id: { + type: STRING(128), + allowNull: false, + defaultValue: '', + comment: '设备唯一标识', + }, + os_version: { + type: STRING(64), + allowNull: false, + defaultValue: '', + comment: '操作系统版本', + }, + device_model: { + type: STRING(128), + allowNull: false, + defaultValue: '', + comment: '设备型号', + }, + error_type: { + type: STRING(64), + allowNull: false, + defaultValue: '', + comment: '错误类型/等级', + }, + error_message: { + type: TEXT, + allowNull: true, + comment: '错误信息(服务端截断上限 5000 字符)', + }, + error_stack: { + type: TEXT('medium'), + allowNull: true, + comment: '错误堆栈(服务端截断上限 65535 字符)', + }, + extra: { + type: TEXT, + allowNull: true, + comment: '附加上下文(JSON 字符串,服务端截断上限 65535 字符)', + }, + report_uuid: { + type: STRING(64), + allowNull: false, + defaultValue: '', + comment: '客户端上报幂等ID(唯一索引,重复上报静默成功)', + }, + client_time: { + type: DATE, + allowNull: true, + comment: '客户端错误发生时间(仅参考,不作为记录时间)', + }, + created_at: { + type: DATE, + allowNull: false, + comment: '服务端写入时间(统一取服务器当前时间)', + }, + updated_at: { + type: DATE, + allowNull: false, + comment: '更新时间', + }, + }, { + tableName: 'wms_client_error_log', + underscored: true, + timestamps: true, + createdAt: 'created_at', + updatedAt: 'updated_at', + paranoid: false, + comment: '客户端错误日志暂存表(设备端运行时错误上报暂存)', + indexes: [ + { name: 'uk_report_uuid', unique: true, fields: [ 'report_uuid' ] }, + { name: 'idx_created_at', fields: [ 'created_at' ] }, + { name: 'idx_client_type_app_version', fields: [ 'client_type', 'app_version' ] }, + { name: 'idx_device_id', fields: [ 'device_id' ] }, + ], + }); + + return ClientErrorLog; +}; diff --git a/app/service/systemMethods/index.js b/app/service/systemMethods/index.js index 1f63bc3..ad9f0ba 100644 --- a/app/service/systemMethods/index.js +++ b/app/service/systemMethods/index.js @@ -1044,6 +1044,16 @@ function formatTbWaybillSearchResponse(responseData, expressNameMap = {}) { }; } +/** + * index 模块免系统日志方法清单(显式登记)。 + * + * 历史口径:index 模块全部方法免系统日志(_noNeedLog='*')。 + * uploadClientErrorLog 为公共上报接口,要求免登录但保留系统日志, + * 因此将通配符改为显式清单:本清单之外的新方法默认记录系统日志, + * 新增方法如需免日志须在此登记。 + */ +const INDEX_NO_NEED_LOG_METHODS = 'fastWhereTree,loadStores,loadWarehouses,loadExpressInterfaces,getCOSUploadConfig,getImages,uploadSuccessNotify,recognizeLicensePlate,ReferenceFile,getMessageDetail,test,getI18nMessage,putI18nCollect,extractModule,tryAutoTranslateNewKeys,searchSpace,searchSpaces,listInterfaceTypes,getLocationTypeList,getQimenAppList,getExpressList,getExpressProductTypeList,getPlatformList,getPrintPlatformList,ensureShopPrintPlatformExists,buildShopPrintPlatformInclude,getShopList,requestPddWaybillSearch,requestPddStdTemplates,requestTbWaybillSearch,requestTbCainiaoStdTemplates,requestPolyStdTemplates,getShopExpressList,getCainiaoStfTemplates,normalizeTemplatePlatformCode,normalizeTemplateExpressCode,getExpressPlatformFieldName,getTemplateAllowedExpressCodeSet,filterPrintPlatformTemplateResponseData,getPrintPlatformTemplateCacheKey,requestPrintPlatformTemplateList,resolvePddTemplateWpCodeCandidates,requestPddTemplateSourceList,getPrintPlatformTemplateList,isPlatformOauthReservationDuplicateError,getPlatformOauthReservationCodePrefix,hasPlatformOauthReservationCodePrefix,normalizePlatformOauthReservationCode,generatePlatformOauthReservationCode,createPlatformOauthReservation,getPlatformOauthLink,listenPlatformOauthBind,loginToIm,polyapiAuthorizeUrl,toOrder,getWorkbenchBindCode,LoginWorkbenchByCode,queryUserByToken,parseWechatBadgeCode,queryUserByWechatBadge'; + class indexService extends MainService { /** * 初始化基础方法的免登录、免权限、免鉴权和免日志配置。 @@ -1052,10 +1062,10 @@ class indexService extends MainService { */ constructor(ctx) { super(ctx); - const _noNeedLogin = 'getI18nMessage,putI18nCollect,test,getCainiaoStfTemplates,polyapiAuthorizeUrl,getWorkbenchBindCode,LoginWorkbenchByCode,queryUserByToken'; - const _noNeedRight = 'loginToIm,getI18nMessage,putI18nCollect,fastWhereTree,loadStores,loadWarehouses,loadExpressInterfaces,getImages,getCOSUploadConfig,uploadSuccessNotify,getMessageDetail,searchSpace,searchSpaces,listInterfaceTypes,getLocationTypeList,getQimenAppList,getExpressList,getExpressProductTypeList,getPlatformList,getPrintPlatformList,getPlatformOauthLink,listenPlatformOauthBind,recognizeLicensePlate,getCainiaoStfTemplates,getPrintPlatformTemplateList,polyapiAuthorizeUrl,toOrder,getWorkbenchBindCode,LoginWorkbenchByCode,queryUserByToken'; - const _noNeedLog = '*'; - const _noNeedAuth = 'loginToIm,getI18nMessage,putI18nCollect,fastWhereTree,loadStores,loadWarehouses,loadExpressInterfaces,getImages,getMessageDetail,searchSpace,searchSpaces,listInterfaceTypes,getLocationTypeList,getQimenAppList,getExpressList,getExpressProductTypeList,getPlatformList,getPrintPlatformList,getPlatformOauthLink,listenPlatformOauthBind,recognizeLicensePlate,test,getCainiaoStfTemplates,getPrintPlatformTemplateList,polyapiAuthorizeUrl,toOrder,getWorkbenchBindCode,LoginWorkbenchByCode,queryUserByToken'; + const _noNeedLogin = 'getI18nMessage,putI18nCollect,test,getCainiaoStfTemplates,polyapiAuthorizeUrl,getWorkbenchBindCode,LoginWorkbenchByCode,queryUserByToken,uploadClientErrorLog'; + const _noNeedRight = 'loginToIm,getI18nMessage,putI18nCollect,fastWhereTree,loadStores,loadWarehouses,loadExpressInterfaces,getImages,getCOSUploadConfig,uploadSuccessNotify,getMessageDetail,searchSpace,searchSpaces,listInterfaceTypes,getLocationTypeList,getQimenAppList,getExpressList,getExpressProductTypeList,getPlatformList,getPrintPlatformList,getPlatformOauthLink,listenPlatformOauthBind,recognizeLicensePlate,getCainiaoStfTemplates,getPrintPlatformTemplateList,polyapiAuthorizeUrl,toOrder,getWorkbenchBindCode,LoginWorkbenchByCode,queryUserByToken,uploadClientErrorLog'; + const _noNeedLog = INDEX_NO_NEED_LOG_METHODS; + const _noNeedAuth = 'loginToIm,getI18nMessage,putI18nCollect,fastWhereTree,loadStores,loadWarehouses,loadExpressInterfaces,getImages,getMessageDetail,searchSpace,searchSpaces,listInterfaceTypes,getLocationTypeList,getQimenAppList,getExpressList,getExpressProductTypeList,getPlatformList,getPrintPlatformList,getPlatformOauthLink,listenPlatformOauthBind,recognizeLicensePlate,test,getCainiaoStfTemplates,getPrintPlatformTemplateList,polyapiAuthorizeUrl,toOrder,getWorkbenchBindCode,LoginWorkbenchByCode,queryUserByToken,uploadClientErrorLog'; this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth); } async fastWhereTree(data) { @@ -3537,5 +3547,41 @@ class indexService extends MainService { code: 200, }); } + + /** + * 上报客户端错误日志(免登录、免权限、免鉴权,保留系统日志)。 + * + * 入参支持三种形态: + * - 单条对象:{ client_type, app_version, device_id, ..., error_message/error_stack 至少一项 } + * - 数组:[ item1, item2, ... ](单次最多 50 条) + * - 包裹对象:{ logs: [ ... ] } + * 字段命名兼容 snake_case 与 camelCase,report_uuid 重复上报静默成功。 + * + * @param {Object|Array} data 上报数据。 + * @return {Promise} 统一响应结构;成功含 total/accepted/duplicated/rejected 统计, + * 参数错误返回 code=400,写入失败返回 code=500。 + */ + async uploadClientErrorLog(data) { + const { service } = this; + // 方法层只做入参形状解构,字段校验、截断与落库逻辑统一在 systems.clientErrorLog 处理 + const list = Array.isArray(data) + ? data + : Array.isArray(data && data.logs) + ? data.logs + : (data && typeof data === 'object' ? [ data ] : []); + + try { + const result = await service.systems.clientErrorLog.upload({ list }); + if (result && result.success) { + return this.success(result.message || '上报成功', { ...result }); + } + + return this.fail(result && result.message ? result.message : '上报失败', { + code: (result && result.code) || 500, + }); + } catch (error) { + return this.fail(`客户端错误日志上报失败: ${error.message}`, { code: 500 }); + } + } } module.exports = indexService; diff --git a/app/service/systems/client_error_log.js b/app/service/systems/client_error_log.js new file mode 100644 index 0000000..8096a0f --- /dev/null +++ b/app/service/systems/client_error_log.js @@ -0,0 +1,255 @@ +'use strict'; + +const Service = require('egg').Service; +const crypto = require('crypto'); + +/** 单次批量上报最大条数 */ +const MAX_BATCH_SIZE = 50; + +/** error_message 单条最大长度(超出截断) */ +const ERROR_MESSAGE_MAX_LENGTH = 5000; + +/** error_stack 单条最大长度(超出截断) */ +const ERROR_STACK_MAX_LENGTH = 65535; + +/** extra 单条最大长度(超出截断) */ +const EXTRA_MAX_LENGTH = 65535; + +/** 字符串字段最大长度(与 wms_client_error_log 表结构列宽对齐) */ +const STRING_FIELD_LIMITS = Object.freeze({ + client_type: 32, + app_version: 64, + device_id: 128, + os_version: 64, + device_model: 128, + error_type: 64, + report_uuid: 64, +}); + +/** + * 客户端错误日志服务层。 + * + * 职责:接收 index.uploadClientErrorLog 转交的原始上报数据(数组), + * 完成字段归一化、必填校验、长度截断、report_uuid 幂等去重与批量落库; + * 所有写入失败均返回友好结果对象,不向上抛出未捕获异常。 + */ +class ClientErrorLogService extends Service { + /** + * 从上报项中按候选字段名提取首个非空值(兼容 snake_case 与 camelCase 两种入参命名)。 + * + * @param {Object} item 上报项。 + * @param {Array} keys 候选字段名(按优先级排序)。 + * @return {*} 命中的字段值;未命中返回 undefined。 + */ + _pick(item, keys) { + for (const key of keys) { + if (Object.prototype.hasOwnProperty.call(item, key) && item[key] !== null && item[key] !== undefined) { + return item[key]; + } + } + + return undefined; + } + + /** + * 将任意值转换为去除首尾空白并截断到指定长度的字符串。 + * + * @param {*} value 原始值。 + * @param {number} maxLength 最大长度。 + * @return {string} 转换后的字符串。 + */ + _toText(value, maxLength) { + if (value === null || value === undefined) { + return ''; + } + + const text = String(value).trim(); + return text.length > maxLength ? text.slice(0, maxLength) : text; + } + + /** + * 解析客户端时间:支持毫秒/秒时间戳与日期字符串,解析失败返回 null。 + * + * @param {*} value 客户端时间原始值。 + * @return {Date|null} 解析出的日期;无法解析返回 null。 + */ + _parseClientTime(value) { + if (value === null || value === undefined || value === '') { + return null; + } + + let parsed = null; + + if (typeof value === 'number') { + // 13 位以上视为毫秒,其余视为秒 + parsed = new Date(value >= 1e12 ? value : value * 1000); + } else { + const text = String(value).trim(); + if (/^\d{10,16}$/.test(text)) { + const number = Number(text); + parsed = new Date(number >= 1e12 ? number : number * 1000); + } else { + parsed = new Date(text); + } + } + + if (Number.isNaN(parsed.getTime())) { + return null; + } + + return parsed; + } + + /** + * 归一化单条上报项,输出可落库字段或拒绝原因。 + * + * @param {*} raw 原始上报项。 + * @return {Object} { row } 归一化成功;{ error } 校验失败(附原因文案)。 + */ + _normalizeItem(raw) { + if (!raw || typeof raw !== 'object' || Array.isArray(raw)) { + return { error: '日志项必须为对象' }; + } + + const errorMessage = this._toText( + this._pick(raw, [ 'error_message', 'errorMessage' ]), + ERROR_MESSAGE_MAX_LENGTH + ); + const errorStack = this._toText( + this._pick(raw, [ 'error_stack', 'errorStack' ]), + ERROR_STACK_MAX_LENGTH + ); + + // 必填校验:error_message 与 error_stack 至少一项有值 + if (!errorMessage && !errorStack) { + return { error: 'error_message 与 error_stack 至少填写一项' }; + } + + const extraRaw = this._pick(raw, [ 'extra' ]); + let extra = ''; + if (extraRaw !== null && extraRaw !== undefined) { + if (typeof extraRaw === 'string') { + extra = extraRaw.slice(0, EXTRA_MAX_LENGTH); + } else { + try { + extra = JSON.stringify(extraRaw); + } catch (error) { + extra = ''; + } + + if (extra.length > EXTRA_MAX_LENGTH) { + extra = extra.slice(0, EXTRA_MAX_LENGTH); + } + } + } + + let reportUuid = this._toText( + this._pick(raw, [ 'report_uuid', 'reportUuid' ]), + STRING_FIELD_LIMITS.report_uuid + ); + // 客户端未生成 uuid 时由服务端补齐,保证唯一索引可用(此时不做幂等去重) + if (!reportUuid) { + reportUuid = `srv-${crypto.randomUUID()}`; + } + + return { + row: { + client_type: this._toText(this._pick(raw, [ 'client_type', 'clientType' ]), STRING_FIELD_LIMITS.client_type), + app_version: this._toText(this._pick(raw, [ 'app_version', 'appVersion' ]), STRING_FIELD_LIMITS.app_version), + device_id: this._toText(this._pick(raw, [ 'device_id', 'deviceId' ]), STRING_FIELD_LIMITS.device_id), + os_version: this._toText(this._pick(raw, [ 'os_version', 'osVersion' ]), STRING_FIELD_LIMITS.os_version), + device_model: this._toText(this._pick(raw, [ 'device_model', 'deviceModel' ]), STRING_FIELD_LIMITS.device_model), + error_type: this._toText(this._pick(raw, [ 'error_type', 'errorType' ]), STRING_FIELD_LIMITS.error_type), + error_message: errorMessage, + error_stack: errorStack, + extra, + report_uuid: reportUuid, + client_time: this._parseClientTime(this._pick(raw, [ 'client_time', 'clientTime' ])), + }, + }; + } + + /** + * 批量上报客户端错误日志(幂等写入,report_uuid 重复时静默成功)。 + * + * @param {Object} params 入参(由方法层解构传入)。 + * @param {Array} params.list 归一化后的上报项数组(单次最多 50 条)。 + * @return {Promise} 处理结果: + * success=true 时含 total/accepted/duplicated/rejected/rejected_reasons 统计; + * success=false 时含 message/code(校验失败或写入失败)。 + */ + async upload({ list }) { + const { ctx } = this; + + if (!Array.isArray(list) || list.length === 0) { + return { success: false, message: '缺少上报日志数据', code: 400 }; + } + + if (list.length > MAX_BATCH_SIZE) { + return { success: false, message: `单次最多上报 ${MAX_BATCH_SIZE} 条日志`, code: 400 }; + } + + const rows = []; + const rejectedReasons = []; + list.forEach((item, index) => { + const normalized = this._normalizeItem(item); + if (normalized.error) { + rejectedReasons.push({ index, reason: normalized.error }); + } else { + rows.push(normalized.row); + } + }); + + if (rows.length === 0) { + return { success: false, message: '没有可入库的有效日志', code: 400, rejected: rejectedReasons.length }; + } + + // 幂等去重:查询已存在的 report_uuid,重复项静默成功、不产生重复行 + let existingUuids = []; + try { + const uuids = rows.map(row => row.report_uuid); + const existingRows = await ctx.model.ClientErrorLog.findAll({ + where: { report_uuid: uuids }, + attributes: [ 'report_uuid' ], + raw: true, + }); + existingUuids = existingRows.map(item => item.report_uuid); + } catch (error) { + ctx.logger.error(`[clientErrorLog] 查询已有 report_uuid 失败: ${error.message}`); + return { success: false, message: '日志上报失败,请稍后重试', code: 500 }; + } + + const newRows = rows.filter(row => !existingUuids.includes(row.report_uuid)); + const duplicatedCount = rows.length - newRows.length; + + let insertedCount = 0; + if (newRows.length > 0) { + try { + // created_at/updated_at 由 Sequelize 时间戳统一取服务器当前时间,不采信客户端时间。 + // 注意:Sequelize v6 的 bulkCreate 在实例校验(validate)之后才注入时间戳, + // 模型显式声明 created_at/updated_at 且 allowNull:false 时,validate:true 会触发 + // notNull Violation,导致所有有效上报写入失败;字段类型/必填/长度校验已由本服务层 + // _normalizeItem 完整保证(字符串归一化 + 长度截断 + client_time 解析), + // 故此处关闭模型级校验,与项目中其他 bulkCreate 调用(默认 validate:false)保持一致。 + await ctx.model.ClientErrorLog.bulkCreate(newRows, { validate: false }); + insertedCount = newRows.length; + } catch (error) { + ctx.logger.error(`[clientErrorLog] 批量写入失败: ${error.message}`); + return { success: false, message: '日志写入失败,请稍后重试', code: 500 }; + } + } + + return { + success: true, + message: '上报成功', + code: 200, + total: list.length, + accepted: insertedCount, + duplicated: duplicatedCount, + rejected: rejectedReasons.length, + rejected_reasons: rejectedReasons.slice(0, 10), + }; + } +} + +module.exports = ClientErrorLogService; diff --git a/database/migrations/20260925100000-create-wms-client-error-log.js b/database/migrations/20260925100000-create-wms-client-error-log.js new file mode 100644 index 0000000..b498b4d --- /dev/null +++ b/database/migrations/20260925100000-create-wms-client-error-log.js @@ -0,0 +1,115 @@ +'use strict'; + +/** + * 创建客户端错误日志暂存表 wms_client_error_log。 + * + * 背景:Android/iOS/Web 等设备端将运行时错误日志上报到服务端暂存, + * 供人工/后台查询分析跟踪 bug。接口入口 index.uploadClientErrorLog + * (免登录、免权限、免鉴权,保留系统日志)。 + * + * 字段:客户端类型/版本、设备标识、系统版本/型号、错误类型、错误信息与堆栈、 + * 附加上下文 extra、report_uuid(客户端生成,唯一索引幂等去重)、 + * client_time(客户端发生时间,仅参考)、created_at(服务端写入时间)。 + * + * 索引:idx_created_at、idx_client_type_app_version、idx_device_id、uk_report_uuid(唯一)。 + */ + +const TABLE_NAME = 'wms_client_error_log'; + +module.exports = { + // eslint-disable-next-line no-unused-vars + async up(queryInterface, Sequelize) { + const { BIGINT, STRING, DATE, TEXT } = Sequelize; + await queryInterface.createTable(TABLE_NAME, { + id: { + type: BIGINT(20).UNSIGNED, + primaryKey: true, + autoIncrement: true, + allowNull: false, + comment: '主键ID', + }, + client_type: { + type: STRING(32), + allowNull: false, + defaultValue: '', + comment: '客户端类型:android/ios/web 等', + }, + app_version: { + type: STRING(64), + allowNull: false, + defaultValue: '', + comment: '客户端版本号', + }, + device_id: { + type: STRING(128), + allowNull: false, + defaultValue: '', + comment: '设备唯一标识', + }, + os_version: { + type: STRING(64), + allowNull: false, + defaultValue: '', + comment: '操作系统版本', + }, + device_model: { + type: STRING(128), + allowNull: false, + defaultValue: '', + comment: '设备型号', + }, + error_type: { + type: STRING(64), + allowNull: false, + defaultValue: '', + comment: '错误类型/等级', + }, + error_message: { + type: TEXT, + allowNull: true, + comment: '错误信息(服务端截断上限 5000 字符)', + }, + error_stack: { + type: TEXT('medium'), + allowNull: true, + comment: '错误堆栈(服务端截断上限 65535 字符)', + }, + extra: { + type: TEXT, + allowNull: true, + comment: '附加上下文(JSON 字符串,服务端截断上限 65535 字符)', + }, + report_uuid: { + type: STRING(64), + allowNull: false, + defaultValue: '', + comment: '客户端上报幂等ID(唯一索引,重复上报静默成功)', + }, + client_time: { + type: DATE, + allowNull: true, + comment: '客户端错误发生时间(仅参考,不作为记录时间)', + }, + created_at: { + type: DATE, + allowNull: false, + comment: '服务端写入时间(统一取服务器当前时间)', + }, + updated_at: { + type: DATE, + allowNull: false, + comment: '更新时间', + }, + }); + + await queryInterface.addIndex(TABLE_NAME, [ 'created_at' ], { name: 'idx_created_at' }); + await queryInterface.addIndex(TABLE_NAME, [ 'client_type', 'app_version' ], { name: 'idx_client_type_app_version' }); + await queryInterface.addIndex(TABLE_NAME, [ 'device_id' ], { name: 'idx_device_id' }); + await queryInterface.addIndex(TABLE_NAME, [ 'report_uuid' ], { name: 'uk_report_uuid', unique: true }); + }, + + // eslint-disable-next-line no-unused-vars + async down(queryInterface, Sequelize) { + await queryInterface.dropTable(TABLE_NAME); + }, +}; diff --git a/methods/changes/system.json b/methods/changes/system.json index 1a0070f..79232f3 100644 --- a/methods/changes/system.json +++ b/methods/changes/system.json @@ -1,4 +1,25 @@ [ + { + "version": "2026.09.25-index-upload-client-error-log", + "date": "2026-09-25", + "type": "added", + "summary": "新增客户端错误日志上报接口 index.uploadClientErrorLog(免登录、免权限、免鉴权,保留系统日志):设备端运行时错误批量上报暂存到新表 wms_client_error_log。入参支持单条对象/数组/{ logs: [...] } 三种形态、单次最多 50 条;snake_case 为主并兼容 camelCase 别名;error_message/error_stack 至少一项有值(超长截断 5000/65535),extra 截断 65535;report_uuid 唯一索引幂等去重(重复静默成功,duplicated +1),缺失时服务端生成 srv-{uuid};client_time 仅参考(非法存 null)。成功返回 code=200 + total/accepted/duplicated/rejected/rejected_reasons(≤10) 统计;方法级错误 HTTP 200 + flag=failure(code=400/500)。配套迁移 database/migrations/20260925100000-create-wms-client-error-log.js、模型 app/model/client_error_log.js、服务 app/service/systems/client_error_log.js。", + "methods": [ + "index.uploadClientErrorLog" + ], + "notes": [ + "变更类型:added(新增 method + 新增表);影响范围:methods/system.json 的 index(基础模块)分组 28 → 29 条,根版本 0.3.189 → 0.3.190、updatedAt 2026-09-24 → 2026-09-25;methods/changes/system.json 新增本条(插入数组首位)。", + "入口与鉴权:POST /system?method=index.uploadClientErrorLog&v=1×tamp=<数字时间戳>(controller.home.system 统一入口);请求头需 platform、project(根 headers 已声明枚举),无 Authorization/token;方法已登记 _noNeedLogin/_noNeedRight/_noNeedAuth,且不在 INDEX_NO_NEED_LOG_METHODS 清单 → 保留系统日志(index 模块日志口径已由通配改为显式清单)。", + "入参归一化口径(代码为准):三种形态三选一(单条对象 / 数组 / { logs: [...] },单次最多 50 条,超限 code=400);字段按 snake_case 读取并兼容 camelCase 别名(clientType/appVersion/deviceId/osVersion/deviceModel/errorType/errorMessage/errorStack/reportUuid/clientTime);字符串字段超宽截断:client_type 32、app_version 64、device_id 128、os_version 64、device_model 128、error_type 64、report_uuid 64;error_message 截断 5000、error_stack 截断 65535(两者至少一项有值,否则该条 rejected);extra 支持对象(JSON.stringify 后截断 65535);client_time 支持毫秒/秒时间戳(≥1e12 视为毫秒)与日期字符串,非法解析存 null。", + "幂等语义:report_uuid 唯一索引 uk_report_uuid —— 写入前先查已有 uuid,重复项 duplicated +1 且不再写入(静默成功);客户端未传 report_uuid 时服务端生成 srv-{uuid},此时不做幂等去重、不保证幂等;created_at/updated_at 由 Sequelize 统一取服务器时间,不采信 client_time。", + "表结构:wms_client_error_log —— id BIGINT(20) UNSIGNED 自增主键;client_type/app_version/device_id/os_version/device_model/error_type/report_uuid 为 STRING(32/64/128/64/128/64/64,NOT NULL DEFAULT '');error_message TEXT、error_stack MEDIUMTEXT、extra TEXT 可空;client_time/created_at/updated_at DATE(created_at/updated_at NOT NULL);索引 uk_report_uuid(唯一)、idx_created_at、idx_client_type_app_version、idx_device_id。", + "出参(成功):{ flag:'success', code:200, message:'上报成功', success:true, total, accepted, duplicated, rejected, rejected_reasons(≤10 条,每条 { index, reason }), timestamp };失败(400/500):HTTP 200 + { flag:'failure', code, message, timestamp }。", + "客户端接入示例(无需 token,仅需公共头 platform/project 与 query method/v/timestamp):curl -X POST 'https:///system?method=index.uploadClientErrorLog&v=1×tamp=1764000000' -H 'platform: app' -H 'project: wms' -H 'Content-Type: application/json' -d '{\"client_type\":\"android\",\"app_version\":\"1.2.3\",\"device_id\":\"dev-001\",\"os_version\":\"Android 14\",\"device_model\":\"Pixel 8\",\"error_type\":\"crash\",\"error_message\":\"NullPointerException\",\"error_stack\":\"...\",\"report_uuid\":\"uuid-2026-001\",\"client_time\":1763999999000}';Kotlin(OkHttp) 伪代码:RequestBody.create(MediaType.parse(\"application/json\"), JSONObject().apply{put(\"client_type\",\"android\");put(\"error_message\",\"...\");put(\"report_uuid\", UUID.randomUUID().toString())}.toString()),Request.Builder().url(\"$base/system?method=index.uploadClientErrorLog&v=1×tamp=${System.currentTimeMillis()/1000}\").header(\"platform\",\"app\").header(\"project\",\"wms\").post(body).build() —— 客户端应在本地生成 report_uuid 以保证重试幂等。", + "前端/客户端是否需适配:是(仅客户端接入层)。既有 /system 前端无改动;android/ios/web 端需按上述示例补齐 platform/project 头与 method/v/timestamp query,并自行生成并持久化 report_uuid 以利用幂等;无 token 校验,无需改造登录态链路。", + "维护源口径(遗留事项):methods/system.json 的维护源为库表(wms_api_method_doc + wms_method_doc_meta,导出脚本 script/method-doc-export.cjs)。本次仅按 docs/api-doc-update-workflow.md 走 npm run doc:api:update 直接写 JSON,未连接数据库、未写库(遵循「只修改文档」红线,与 2026-09-24 变更记录口径一致)。后续需由维护者决定是否以 method-doc-create 将该方法入库并重新导出,否则下次执行 method-doc-export.cjs 会用库表重建 system.json 而丢失本条。", + "发布顺序:迁移(20260925100000-create-wms-client-error-log)先于代码发布;迁移为纯建表、无回填,先迁移无风险。" + ] + }, { "version": "2026.09.24-big-group-pack-coefficient-desc", "date": "2026-09-24", diff --git a/methods/system.json b/methods/system.json index 3e1e57b..d8bd118 100644 --- a/methods/system.json +++ b/methods/system.json @@ -1,8 +1,8 @@ { "module": "system", "description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内", - "version": "0.3.183", - "updatedAt": "2026-09-24", + "version": "0.3.190", + "updatedAt": "2026-09-25", "headers": [ { "name": "platform", @@ -2409,6 +2409,171 @@ "message": "查询失败(数据库异常,message 为具体错误信息)" } ] + }, + { + "method": "index.uploadClientErrorLog", + "description": "上报客户端错误日志(免登录、免权限、免鉴权,保留系统日志):设备端将运行时错误日志批量上报到服务端暂存表 wms_client_error_log。入参支持三种形态——单条对象、数组、{ logs: [...] },单次最多 50 条;字段命名兼容 snake_case 与 camelCase 别名。error_message 与 error_stack 至少一项有值(超长分别截断 5000 / 65535 字符),extra 超长截断 65535;report_uuid 幂等去重(重复上报静默成功,duplicated +1、不产生重复行;缺失时服务端生成 srv-{uuid} 且不保证幂等);client_time 仅参考(毫秒/秒时间戳或日期字符串,非法值存 null)。成功返回 flag=success、code=200 与 total/accepted/duplicated/rejected/rejected_reasons 统计;方法级错误按 /system 惯例为 HTTP 200 + flag=failure(code=400/500)。", + "isNeedAuth": false, + "isNeedLogin": false, + "headers": [], + "params": [ + { + "name": "client_type", + "type": "string", + "required": false, + "source": "body", + "description": "客户端类型:android/ios/web 等;表宽 STRING(32),超出截断;兼容 camelCase 别名 clientType" + }, + { + "name": "app_version", + "type": "string", + "required": false, + "source": "body", + "description": "客户端版本号;表宽 STRING(64),超出截断;别名 appVersion" + }, + { + "name": "device_id", + "type": "string", + "required": false, + "source": "body", + "description": "设备唯一标识;表宽 STRING(128),超出截断;别名 deviceId" + }, + { + "name": "os_version", + "type": "string", + "required": false, + "source": "body", + "description": "操作系统版本;表宽 STRING(64),超出截断;别名 osVersion" + }, + { + "name": "device_model", + "type": "string", + "required": false, + "source": "body", + "description": "设备型号;表宽 STRING(128),超出截断;别名 deviceModel" + }, + { + "name": "error_type", + "type": "string", + "required": false, + "source": "body", + "description": "错误类型/等级;表宽 STRING(64),超出截断;别名 errorType" + }, + { + "name": "error_message", + "type": "string", + "required": false, + "source": "body", + "description": "错误信息;与 error_stack 至少一项有值,超长截断至 5000 字符;别名 errorMessage" + }, + { + "name": "error_stack", + "type": "string", + "required": false, + "source": "body", + "description": "错误堆栈;与 error_message 至少一项有值,超长截断至 65535 字符;别名 errorStack" + }, + { + "name": "extra", + "type": "string", + "required": false, + "source": "body", + "description": "附加上下文;字符串或对象(对象序列化为 JSON 字符串),超长截断至 65535 字符" + }, + { + "name": "report_uuid", + "type": "string", + "required": false, + "source": "body", + "description": "客户端上报幂等ID(唯一索引 uk_report_uuid);表宽 STRING(64),超出截断;重复上报静默成功(duplicated +1,不产生重复行);缺失时服务端生成 srv-{uuid},此时不保证幂等;别名 reportUuid" + }, + { + "name": "client_time", + "type": "string", + "required": false, + "source": "body", + "description": "客户端错误发生时间(仅参考,不作为记录时间):毫秒/秒时间戳或日期字符串,非法值存 null;别名 clientTime" + }, + { + "name": "logs", + "type": "array", + "required": false, + "source": "body", + "description": "包裹形态 { logs: [...] } 的上报条目数组,单次最多 50 条;与「单条对象」「数组」三种形态三选一" + } + ], + "response": [ + { + "name": "flag", + "type": "string", + "required": true, + "description": "结果标记:success" + }, + { + "name": "code", + "type": "number", + "required": true, + "description": "业务码:200 成功;400 入参形状错误/空数据/超 50 条/全部条目无效;500 查询或写入失败(方法级错误仍为 HTTP 200)" + }, + { + "name": "message", + "type": "string", + "required": true, + "description": "提示文案:成功为「上报成功」" + }, + { + "name": "success", + "type": "boolean", + "required": true, + "description": "服务处理结果标记:true 表示成功(400/500 失败响应无此字段)" + }, + { + "name": "total", + "type": "number", + "required": true, + "description": "本次上报条数" + }, + { + "name": "accepted", + "type": "number", + "required": true, + "description": "新入库条数" + }, + { + "name": "duplicated", + "type": "number", + "required": true, + "description": "幂等去重条数(report_uuid 已存在,静默成功、不产生重复行)" + }, + { + "name": "rejected", + "type": "number", + "required": true, + "description": "校验失败条数" + }, + { + "name": "rejected_reasons", + "type": "array", + "required": false, + "description": "拒绝明细(最多返回 10 条),每条含 index(0 起条目下标)与 reason(原因文案)" + }, + { + "name": "timestamp", + "type": "number", + "required": true, + "description": "服务端响应时间戳(秒)" + } + ], + "errors": [ + { + "code": 400, + "message": "入参形状错误(非对象/数组且无 logs 键)、缺少上报日志数据(空数组)、单次超过 50 条、全部条目无效(error_message 与 error_stack 均无值);HTTP 200 + flag=failure,body 仅含 flag/code/message/timestamp" + }, + { + "code": 500, + "message": "查询已有 report_uuid 失败或批量写入失败(HTTP 200 + flag=failure,body 仅含 flag/code/message/timestamp)" + } + ] } ] },