新增免登录/免权限/免鉴权的设备端运行时错误批量上报接口,保留系统日志: - 建表迁移 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 约定不入库)
256 lines
8.8 KiB
JavaScript
256 lines
8.8 KiB
JavaScript
'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;
|