feat(index): 新增客户端错误日志上报接口 uploadClientErrorLog(建表 wms_client_error_log)
新增免登录/免权限/免鉴权的设备端运行时错误批量上报接口,保留系统日志: - 建表迁移 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 约定不入库)
This commit is contained in:
parent
3d2291907e
commit
943c096c5a
@ -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
|
||||
|
||||
<!-- SERVICE_METHOD_INVENTORY:BEGIN -->
|
||||
自动生成时间: 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)
|
||||
|
||||
112
app/model/client_error_log.js
Normal file
112
app/model/client_error_log.js
Normal file
@ -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<import('sequelize').Model>} 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;
|
||||
};
|
||||
@ -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<Object>} data 上报数据。
|
||||
* @return {Promise<Object>} 统一响应结构;成功含 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;
|
||||
|
||||
255
app/service/systems/client_error_log.js
Normal file
255
app/service/systems/client_error_log.js
Normal file
@ -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<string>} 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<Object>} params.list 归一化后的上报项数组(单次最多 50 条)。
|
||||
* @return {Promise<Object>} 处理结果:
|
||||
* 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;
|
||||
@ -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);
|
||||
},
|
||||
};
|
||||
@ -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://<host>/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",
|
||||
|
||||
@ -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)"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user