Open Mercato业务规则执行日志排查指南自动化逻辑调试方法论【免费下载链接】open-mercatoThe AI-Engineering Foundation Framework for CRM/ERP and commerce: open-source TypeScript, with multi-tenancy, RBAC, events and domain modules already decided as conventions and specs, so Cursor, Claude Code and Codex build features instead of re-deciding architecture. Start with 80% done.项目地址: https://gitcode.com/GitHub_Trending/op/open-mercatoOpen Mercato 是一个开源的 AI 工程基础框架内置业务规则引擎当订单、工单等实体发生创建、更新、状态变更时规则会自动评估条件并触发动作。一旦自动化逻辑不生效或行为怪异执行日志Execution Logs就是最直接的调试入口——它记录了每次评估的条件比对值、动作执行结果和耗时。本文给你一套从界面到 API 的完整排查方法论。为什么执行日志是自动化逻辑调试的核心 业务规则的每次评估无论条件是否命中都会生成一条日志包含 6 类关键信息信息类别排查价值规则标识ruleId / ruleName确认是哪条规则在跑上下文实体类型、实体 ID、事件类型确认规则被谁、在什么时机触发条件轨迹expected vs actual定位条件为什么不命中动作轨迹SUCCESS / FAILURE / SKIPPED定位动作为什么没生效结果SUCCESS / FAILURE / ERROR区分正常拦截与执行出错耗时executionTimeMs发现拖慢用户体验的规则 核心理念不要靠猜。条件比对值与实际值都被记录在案日志本身就是自动化逻辑的黑匣子。打开执行日志从规则列表到日志详情 3 步走第 1 步确认规则本身配置正确。进入Business Rules列表页核对三要素——实体类型Entity Type、事件类型Event Type、启用状态Enabled。三者任一不匹配规则永远不会被触发日志自然为空。第 2 步进入 Execution Logs 查看执行列表。列表按时间倒序展示每次执行的规则、实体、结果和耗时支持分页与筛选第 3 步点开单条日志的 Details 查看完整轨迹。详情页分四块Execution Summary执行时间、结果、耗时、触发者Rule / Entity Information规则类型如 GUARD、实体类型与 ID、事件类型Input Context触发时实体的原始数据快照状态、数量、金额等Output Context动作执行结果与条件评估总结果Input Context 尤其宝贵——它是案发当时的数据快照可以回答评估那一刻字段到底是什么值。四大典型症状与排查路径症状一规则该触发却没触发无日志按顺序检查规则是否处于 Enabled 状态实体类型是否精确匹配区分大小写如WorkOrder≠workorder事件类型是否正确beforeSave与afterSave、beforeCreate语义不同用一条无条件测试规则验证事件本身是否在发出。如果日志存在但conditionResult为false则进入症状二。症状二日志显示条件值不对 打开日志详情逐条对比trace.conditions中的expectedValue与actualValue字段路径写错条件构建器使用点号路径如product.quantity路径不存在时取到的是undefined时机问题beforeUpdate评估时数据尚未落库拿到的是旧值可尝试换afterUpdate数据本身不符合预期此时问题不在规则而在上游数据来源。条件构建器本身也会给出校验提示如Rule 3: Rule 1: Field path is required规则保存前就能拦截大部分路径错误症状三规则执行报 ERROR筛选resultERROR的日志重点看error字段与动作轨迹中的失败项。典型原因规则假设的字段不存在如空数组取items[0].quantity直接抛 TypeErrorWebhook 端点不可达、超时数据库结构变更后规则未同步更新。修复套路给规则补一个防御性条件如items IS_NOT_EMPTY或改用空值安全的表达式。症状四执行太慢拖累操作体验按executionTimeMs降序排列日志找出 Top 20 慢执行再看动作轨迹定位瓶颈。经验值规则类型目标耗时需要调查GUARD 10ms 100msVALIDATION 20ms 200msCALCULATION 30ms 300msACTION 100ms 1000ms慢的通常是CALL_WEBHOOK网络依赖、NOTIFY邮件服务依赖这类外部调用——优先考虑批量化或异步化。用 API 过滤器快速缩小排查范围除了界面Logs API 支持组合过滤排查效率更高。常用组合示例# 只看某条规则的失败执行按时间倒序 GET /api/business_rules/logs?ruleIdMATERIAL_CHECKresultFAILUREsorttimestamp:desc # 查某个实体上发生过的所有规则评估 GET /api/business_rules/logs?entityTypeWorkOrderentityIdwo-12345支持的过滤维度包括ruleId、entityType、entityId、eventType、result、userId、时间范围from/to支持7d相对写法、排序sort。所有端点自动按租户隔离且需要business_rules.logs.view权限——遇到 403 先联系管理员核对 RBAC 配置。统计接口还能一屏看健康度/api/business_rules/logs/stats?metricsuccessRate查看各规则成功率metricavgExecutionTime查看平均耗时趋势适合接入监控告警。日志保留与审计别忘了这两件事保留期默认保留 90 天可用环境变量BUSINESS_RULES_LOG_RETENTION_DAYS调整如设为 365 保留一年审计导出支持按规则 时间范围导出 CSV/JSONGET /api/business_rules/logs/export?formatcsv用于合规审查时能证明何时检查、检查了什么数据、谁触发、执行了什么动作。排查方法论速查清单 ✅无日志→ 查启用状态、实体/事件类型匹配、用无条件测试规则验证事件条件不命中→ 逐条对比 expected/actual 值检查字段路径与事件时机ERROR 报错→ 按错误信息归组补防御性条件或修复外部依赖性能慢→ 按耗时排序找 Top 规则优化 Webhook / 通知类动作常态化→ 监控成功率与平均耗时定期导出审计日志。延伸资料 执行日志用户指南apps/docs/docs/user-guide/business-rules/execution-logs.mdxLogs API 参考apps/docs/docs/api/business-rules/logs.mdx业务规则 API 总览apps/docs/docs/api/business-rules.mdx规则引擎框架文档apps/docs/docs/framework/business-rules/architecture.mdx规则引擎源码模块packages/core/src/modules/business_rules/本地运行后可通过git clone https://gitcode.com/GitHub_Trending/op/open-mercato获取完整仓库在Dashboard → Business Rules → Logs中开始你的第一次日志排查。【免费下载链接】open-mercatoThe AI-Engineering Foundation Framework for CRM/ERP and commerce: open-source TypeScript, with multi-tenancy, RBAC, events and domain modules already decided as conventions and specs, so Cursor, Claude Code and Codex build features instead of re-deciding architecture. Start with 80% done.项目地址: https://gitcode.com/GitHub_Trending/op/open-mercato创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考