WMS_MAIN/app/service/systems/client_error_log.js
liufumingren 943c096c5a 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 约定不入库)
2026-09-25 03:14:15 +08:00

256 lines
8.8 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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