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:
liufumingren 2026-09-25 03:14:15 +08:00
parent 3d2291907e
commit 943c096c5a
7 changed files with 743 additions and 12 deletions

View File

@ -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&timestamp=<数字时间戳>,请求头需 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)

View 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;
};

View File

@ -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;

View 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;

View File

@ -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);
},
};

View File

@ -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&timestamp=<数字时间戳>(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&timestamp=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&timestamp=${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",

View File

@ -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)"
}
]
}
]
},