Panoramic Diagnosis and Improvement Plan for Inspection System

2026-06-26 · Based on Full-Link Code Audit

I. Current Panorama: 4 Parallel Inspection Systems

BossAgents currently has 4 independent inspection/check systems, overlapping with each other, having different data sources, and employing varied scheduling methods:

1.1 AI Inspector (ai-inspector.js) — Main Inspection Engine

1.2 HealthPatrol + HealthScanner (health-patrol.js) — New Generation Scoring Engine

1.3 Compliance Patrol (compliance-inspector.js) — Early Prototype

1.4 Consistency Check (consistency-check.js) — Lightweight Tool

1.5 Various check-*.js Scripts — Scattered Tools

• check-bom-structure.js, check-template.js, check-test-parts-deps.js
• check-encoding.js, check-syntax.js, inspect-db.js, inspect-def.js, inspect-err.js, inspect-sections.js, inspect.js
• scripts/check-quality-itemtypes.js
• tools/check-multi-level-bom.js, tools/_check-v2-imports.js

Counting them, there are at least 14 independent check scripts/tools, scattered across 4 directories, with no unified entry point for invocation.

2. Core Issue Diagnosis

? P0: Four inspection systems are isolated, with inconsistent data sources

| Inspection System | SCSAI Real-time Data | sciot_import.db | Other Databases |

|---|---|---|---|

| AI Inspector | ✅ Pulls in real-time | ✅ Reads rules | — |

| HealthPatrol | ❌ Not called | ✅ Primary data source | core_runtime.db / enterprise_store.db |

| ComplianceInspector | ❌ | ❌ | aml_store.db (independent) |

| ConsistencyCheck | ❌ | ✅ | — |

Consequence: For the same ItemType (e.g., Part), AI Inspector may report "Must have Chinese label" (real-time SCSAI), while HealthScanner scores the completeness dimension (local cache), potentially leading to contradictory results.

? P1: Four inspection routes are fragmented with unclear responsibility boundaries

AI Inspector（ai-inspector.js）
├─ 规则来自 sciot_rules_v2（与 aml.js CRUD 共用）
├─ 数据来自 SCSAI API（实时）
├─ 目标：单个 ItemType / 全量对象的规则命中检查

HealthPatrol（health-patrol.js）
├─ 规则来自 EnterpriseRules（独立 enterprise_store.db）
├─ 数据来自本地 3 DB（离线）
├─ 目标：6维健康度评分 + 定性定级

ComplianceInspector（compliance-inspector.js）
├─ 规则硬编码
├─ 数据来自 aml_store.db（被遗忘的数据库）
├─ 目标：基础物料合规

ConsistencyCheck（consistency-check.js）
├─ 规则硬编码
├─ 数据来自 sciot_import.db（同集不同库）
├─ 目标：数据层完整性

? P1：数据库访问方式三套并存，混乱

| 模式 | 使用方 | 是否统一 |

|---|---|---|

| db-adapter → .prepare/.get/.all/.run/.save | consistency-check.js, enterprise-rules.js, health-scanner.js | ✅ |

| sqlite-compat → .prepare/.get/.all/.run/.save | getDb() + getSciotDb() in ai-inspector.js | ⚠️ Same name but different modules |

| Direct sql.js → new SQL.Database() + .exec() | ai-inspector.js's getSciotDb() (async sql.js path) | ❌ |

? P2: Frontend completely lacks inspection UI

• Search for ai-inspector, health-patrol, inspection results in frontend/app.js yields nothing
• Digital Employee page (DigitalStaff.vue/management page) has no inspection button or results panel
• AI Inspector's SSE streaming capability has no consumer
• Data Mart (app.js:2624-2655) has an "Inspection Records" Tab, but that's for quality management inspection (incoming inspection), not object model health patrol

? P2: AI Inspector's data model is not separated from frontend

• Inspection rules are hardcoded in ai-inspector.js (DEFAULT_MODEL_RULES + DEFAULT_INSTANCE_RULES), forming two separate systems alongside the database rules in sciot_rules_v2 table
• DEFAULT_MODEL_RULES are written to sciot_rules_v2 (initBuiltinRules()), but using INSERT OR IGNORE, requiring manual cleanup of old data when updating code rules
• The fix script's generateFixAML() hardcodes 7 types of add_property:xxx mappings; extensions require code changes

? P2: HealthPatrol is ready but lacks integration points

• enterprise-rules.js provides a complete validateType() interface, which can be integrated with AI Inspector
• health-scanner.js 6-dimensional scoring system is more structured than AI Inspector
• correction-learner.js exists but is not referenced by any code

? P3: ComplianceInspector should be deprecated or rewritten

• Depends on the parts/ecr tables in aml_store.db, which most likely do not exist
• Functionality is fully covered by AI Inspector's instance inspection

? P3: Fragmented check-*.js script management is missing

• 14 scripts have no unified entry point; most are unknown who calls them or when
• Some scripts (check-encoding.js, check-syntax.js) may have been replaced by the workflow pipeline

III. Improvement Plan (Three Phases)

Phase 0: Unify Data Access (1 day)

Goal: Eliminate DB access chaos

Before:
  ai-inspector.js ─── sqlite-compat (同步) + sql.js (异步)
  consistency-check ── db-adapter
  health-scanner ──── db-adapter
  enterprise-rules ── db-adapter

After:
  全系统统一使用 /server/db-adapter
  同步：createDatabase(path) 返回 compatible handle
  异步：createAsyncDatabase(path) 按需

具体改动：

1. Change getDb() and getSciotDb() in ai-inspector.js to uniformly call db-adapter
2. Remove lazy initialization of initSqlJsOnce() and _sqlJsReady
3. Unify getSciotDb() in consistency-check.js to point to the same database instance

Phase 1: Merge Inspection Engines (2 days)

Goal: AI Inspector absorbs HealthPatrol to unify the inspection system

Transformation Approach:

AI Inspector v5.0 ─────┬─ SCSAI API 实时检查（现有规则引擎）
                      ├─ HealthScanner 离线评分（新增集成）
                      ├─ EnterpriseRules 企业合规（新增集成）
                      └─ CorrectionLearner 学习闭环（新增集成）

关键改动：

1. Unified Rules

• DEFAULT_MODEL_RULES removed from code, changed to database initialization seed
• initBuiltinRules() upgraded to be updatable (delete old version and rewrite), supporting version numbers
• EnterpriseRules validateType() integrated as an independent dimension (does not overwrite existing rules)

1. Inspection Results Consolidation

• AI Inspector returns issues[] (rule hits), new scores{} added (6-dimensional health metrics)
• Inspection log table inspection_logs adds avg_score field
• Frontend can view both rule hits and health trend

1. Compliance Deprecation

• Delete compliance-inspector.js (fully replaced by AI Inspector instance inspection)
• Collect scattered check-*.js scripts, incorporate necessary ones into AI Inspector rule library

Phase 2: Frontend Inspection Panel (3 days)

Goal: Digital Staff page provides a complete inspection experience

New frontend components:

数字员工页面
├─ 员工列表（已有）
├─ 任务看板（已有）
└─ ? 巡检结果面板
    ├─ 报告概览：健康度总分 + 等级分布 + 趋势图
    ├─ 问题列表：按严重程度/类型/对象类分组
    │   └─ 每项：规则名、描述、自动修复按钮 / 手动处理提示
    ├─ 历史记录：过去 N 次巡检对比
    └─ 立即巡检按钮 → 调用 /api/ai-inspector/inspect-stream
  
数据集市（可选）
├─ 对象类健康度排名
├─ 规则命中统计 TOP 10
└─ 修复成功率趋势

API 新增/增强：

• GET /api/digital-staff/inspection/latest — Get the latest inspection summary
• GET /api/digital-staff/inspection/trend?days=30 — Health trend
• POST /api/digital-staff/run-inspection — Trigger inspection (DS-SYS-001 scheduling)

IV. Unified Inspection Architecture (Target State)

┌─────────────────────────────────────────────────────┐
│                  数字员工调度器                       │
│            (Cron / 手动 / 事件触发)                  │
└────────────────────┬────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────┐
│              UnifiedInspectionEngine                 │
│  (ai-inspector.js 升级，吸收三套引擎)                 │
├──────────────────────────────────────────────────────┤
│  ┌────────────────────┐  ┌────────────────────────┐ │
│  │ 规则引擎 (Rules)    │  │ 评分引擎 (Scorer)      │ │
│  │ • sciot_rules_v2   │  │ • HealthScanner 6维    │ │
│  │ • 硬编码内置规则    │  │ • EnterpriseRules 校验  │ │
│  │ • 用户自定义规则    │  │ • 行业模板基准          │ │
│  └────────┬───────────┘  └────────┬───────────────┘ │
│           │                       │                  │
│  ┌────────▼───────────────────────▼───────────────┐  │
│  │          修复引擎 (Fixer)                       │  │
│  │  • AML 自动修复     • LLM 诊断修复              │  │
│  │  • Correction Learner 学习                      │  │
│  └────────────────────┬───────────────────────────┘  │
│                       │                              │
│  ┌────────────────────▼───────────────────────────┐  │
│  │          审计日志 + 趋势存储                     │  │
│  │  inspection_logs + inspection_issues            │  │
│  └────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────┘
           │                    │
           ▼                    ▼
     SCSAI API(实时)     本地 DB(离线评分)

数据流

触发巡检
  │
  ├─ scope=model（对象模型）
  │   ├─ 从 SCSAI 获取全部 ItemType
  │   ├─ 逐 ItemType 检查规则命中（规则引擎）
  │   ├─ 逐 ItemType 计算 6 维评分（评分引擎）
  │   └─ 结果合并：issues[] + scores{}
  │
  ├─ scope=instance（业务实例）
  │   ├─ 从 SCSAI 获取指定 ItemType 的实例
  │   ├─ 逐实例检查规则命中（规则引擎）
  │   └─ 统计每个 ItemType 的问题分布
  │
  └─ scope=all（全量巡检，< 30分钟）
      ├─ 模型巡检 + 核心业务类型实例巡检
      └─ 生成综合报告

结果存储 → 前端数字员工面板展示

五、配置一站式调度改造

Digital Staff DS-SYS-001（系统运维师）的 runOnce() 方法当前固定调用 consistencyCheck()，需要改为调用 Unified Inspection Engine：

// Before (staff-manager.js 中 DS-SYS-001)
async runStaffOnce(ctx) {
  const { db } = ctx;
  const result = consistencyCheck(db);
  return { ...result, descriptions: ['数据库完整性检查'] };
}

// After
async runStaffOnce(ctx) {
  const result = await unifiedInspection.run({
    scope: 'all',
    mode: 'quick',       // 定时巡检用 quick 模式
    priority: 'P1',
    checkConsistency: true,  // 保留原一致性检查
  });
  return result;
}

六、待确认事项

| 问题 | 建议 |

|---|---|

| Should HealthPatrol continue to be promoted | Recommended to merge into AI Inspector, retaining its 6-dimensional scoring + EnterpriseRules |

| compliance-inspector.js can be deleted? | Yes, functionality completely overlaps |

| **How to clean up 18 check-*.js files | Audit individually: delete/merge/keep independent |

| Front-end inspection panel priority | Phase 2, recommended after the Digital Employee page stabilizes |

| **SCSAI certification confusion** | ai-inspector.js has its own auth logic (getAuthUser/getAuthPass), not interoperable with SCSAI-auth.js, needs unification |

7. Summary

| Rating | Findings |

|---|---|

| ? P0 | 4 parallel inspection systems, inconsistent data sources, results may conflict |

| ? P1 | 3 database access modes coexist, representing architectural debt |

| ? P2 | All inspection engines (including HealthPatrol) lack a front-end UI, meaning they are unused |

| ? P2 | EnterpriseRules + HealthScanner + CorrectionLearner trio is written but in "zombie code" state |

| ? P3 | compliance-inspector.js should be deprecated, 14 check-*.js files should be cleaned up |

Recommended priority: Phase 0 (unify DB access, 1 day) → Phase 1 (merge engines, 2 days) → Phase 2 (front-end panel, 3 days)