SCSAI Metadata Synchronization and Rule Template Update System

Q: 1.1 Limitations of the Current Architecture？

| Issue | Impact | Severity | |------|------|----------| | AML files are static snapshots | Local rule templates become outdated after SCSAI server changes | P0 | | No change detection mechanism | Una

Q: 1.2 Change Scenario Analysis？

| Scenario | SCSAI Operation | Local Impact | Synchronization Strategy | |------|-----------|----------|----------| | Add object class | Create ItemType | Requires new rule templates and prompts | Aut

Q: 2.1 Overall Architecture？

┌─────────────────────────────────────────────────────────────────────────────┐ │ SCSAI 服务端 │ │ (ItemType, Property, List, Relationship, Value) │ └─────────────────────────────────────────────────────

Q: 2.2 数据流图？

┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ SCSAI 服务端 │────▶│ 变更检测层 │────▶│ 同步队列 │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ 版本对比 │ │ 任务处理

Q: 3.1 新增表结构？

#### 3.1.1 SCSAI_metadata_versions - SCSAI 元数据版本追踪 CREATE TABLE SCSAI_metadata_versions ( id INTEGER PRIMARY KEY AUTOINCREMENT, -- 对象标识 item_type_name TEXT NOT NULL, -- 对象类名称 item_type_id TEXT, -- SCS

Version: v1.0 | Created: 2026-05-29 | Status: Design Phase

1. Problem Analysis

1.1 Limitations of the Current Architecture

Issue	Impact	Severity
AML files are static snapshots	Local rule templates become outdated after SCSAI server changes	P0
No change detection mechanism	Unable to know when/what was added/modified/deleted in SCSAI	P0
No version management	Cannot track historical changes to rule templates or roll back	P1
No incremental synchronization	Requires full re-import each time; inefficient and time-consuming	P1
No conflict handling	Cannot intelligently merge conflicts between SCSAI modifications and local changes	P2

1.2 Change Scenario Analysis

Scenario	SCSAI Operation	Local Impact	Synchronization Strategy
Add object class	Create ItemType	Requires new rule templates and prompts	Auto-sync
Modify object class	Modify attributes, add fields	Requires updates to rule templates and prompts	Requires review
Delete object class	Delete ItemType	Requires marking for deletion or archiving	Requires review
Add List Value	Add Value to List	Need to update optional value list	Auto-sync
Modify List Value	Modify Value label	Need to update optional value list	Auto-sync
Delete List Value	Delete Value	Need to update optional value list	Requires review
Add Relationship	Create RelationshipType	Need to add relationship template	Auto-sync
Modify Relationship	Modify relationship attributes	Need to update relationship template	Requires review
Modify Prompt	Modified by local admin	May conflict with SCSAI changes	Conflict detection

2. System Architecture Design

2.1 Overall Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                            SCSAI 服务端                                       │
│              (ItemType, Property, List, Relationship, Value)                 │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ ① Webhook / 定时轮询
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         变更检测层 (Change Detection)                        │
├─────────────────────────────────────────────────────────────────────────────┤
│  • 元数据版本表 (SCSAI_metadata_versions)                                     │
│  • 变更队列 (sync_queue)                                                      │
│  • 变更检测算法 (detectChanges)                                               │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ ② 生成同步任务
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         增量同步层 (Incremental Sync)                        │
├─────────────────────────────────────────────────────────────────────────────┤
│  • 同步任务处理器 (processSyncQueue)                                          │
│  • 增量导入逻辑 (syncItemTypeFromSCSAI)                                        │
│  • 批量处理与重试机制                                                         │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ ③ 更新本地数据
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                       规则模板管理层 (Template Management)                    │
├─────────────────────────────────────────────────────────────────────────────┤
│  • 版本控制 (sciot_item_type_versions)                                       │
│  • 草稿/发布状态管理                                                          │
│  • 冲突检测与人工审核                                                         │
│  • 规则模板自动生成                                                           │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ ④ 通知
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         通知层 (Notification)                                │
├─────────────────────────────────────────────────────────────────────────────┤
│  • 飞书通知 (变更、冲突、失败)                                                 │
│  • 邮件通知                                                                   │
│  • 系统内通知                                                                 │
└─────────────────────────────────────────────────────────────────────────────┘

2.2 数据流图

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  SCSAI 服务端  │────▶│  变更检测层   │────▶│  同步队列     │
└──────────────┘     └──────────────┘     └──────────────┘
                            │                     │
                            ▼                     ▼
                     ┌──────────────┐     ┌──────────────┐
                     │  版本对比     │     │  任务处理     │
                     └──────────────┘     └──────────────┘
                            │                     │
                            ▼                     ▼
                     ┌──────────────┐     ┌──────────────┐
                     │  冲突检测     │     │  增量导入     │
                     └──────────────┘     └──────────────┘
                            │                     │
                            ▼                     ▼
                     ┌──────────────┐     ┌──────────────┐
                     │  人工审核     │     │  更新本地     │
                     └──────────────┘     └──────────────┘
                            │                     │
                            └──────────┬──────────┘
                                       ▼
                                ┌──────────────┐
                                │  通知用户     │
                                └──────────────┘

3. 数据库设计

3.1 新增表结构

#### 3.1.1 SCSAI_metadata_versions - SCSAI 元数据版本追踪

CREATE TABLE SCSAI_metadata_versions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    
    -- 对象标识
    item_type_name TEXT NOT NULL,              -- 对象类名称
    item_type_id TEXT,                         -- SCSAI 中的 ID
    
    -- SCSAI 版本信息
    SCSAI_config_id TEXT,                       -- SCSAI config_id（用于检测变更）
    SCSAI_modified_on TEXT,                     -- SCSAI 最后修改时间
    SCSAI_generation INTEGER,                   -- SCSAI generation（版本号）
    
    -- 本地版本信息
    local_synced_at TEXT,                      -- 本地最后同步时间
    local_version INTEGER DEFAULT 1,           -- 本地版本号
    
    -- 变更检测
    change_type TEXT DEFAULT 'NONE',           -- NONE/ADD/MODIFY/DELETE
    change_detected_at TEXT,                   -- 检测到变更的时间
    change_details TEXT,                       -- 变更详情 JSON
    
    -- 同步状态
    sync_status TEXT DEFAULT 'synced',         -- synced/pending/syncing/failed/conflict
    last_sync_error TEXT,                      -- 最后同步错误
    
    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
    updated_at TEXT DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(item_type_name)
);

CREATE INDEX idx_metadata_sync_status ON SCSAI_metadata_versions(sync_status);
CREATE INDEX idx_metadata_change_type ON SCSAI_metadata_versions(change_type);

#### 3.1.2 sync_queue - 同步任务队列

CREATE TABLE sync_queue (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    
    -- 任务标识
    task_type TEXT NOT NULL,                   -- ITEMTYPE/LIST/RELATIONSHIP/PROPERTY
    task_action TEXT NOT NULL,                 -- ADD/MODIFY/DELETE/REFRESH
    target_name TEXT NOT NULL,                 -- 目标对象名称
    target_id TEXT,                            -- 目标对象 ID
    
    -- 任务优先级
    priority INTEGER DEFAULT 5,                -- 1-10，1 最高
    
    -- 任务状态
    status TEXT DEFAULT 'pending',             -- pending/processing/done/failed/needs_review
    retry_count INTEGER DEFAULT 0,
    max_retry INTEGER DEFAULT 3,
    
    -- 任务数据
    task_data TEXT,                            -- 任务数据 JSON
    result_data TEXT,                          -- 执行结果 JSON
    error_msg TEXT,                            -- 错误信息
    
    -- 审核相关
    needs_review INTEGER DEFAULT 0,            -- 是否需要人工审核
    review_reason TEXT,                        -- 审核原因
    reviewed_by TEXT,                          -- 审核人
    reviewed_at TEXT,                          -- 审核时间
    review_action TEXT,                        -- 审核决定: approve/reject/modify
    
    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
    started_at TEXT,
    completed_at TEXT
);

CREATE INDEX idx_sync_queue_status ON sync_queue(status);
CREATE INDEX idx_sync_queue_priority ON sync_queue(priority, created_at);

#### 3.1.3 sciot_item_type_versions - 规则模板版本历史

CREATE TABLE sciot_item_type_versions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    
    -- 版本标识
    item_type_name TEXT NOT NULL,
    version INTEGER NOT NULL,
    
    -- 版本来源
    version_source TEXT DEFAULT 'manual',      -- manual/auto_sync/import/rollback
    version_reason TEXT,                       -- 版本变更原因
    
    -- 版本状态
    status TEXT DEFAULT 'draft',               -- draft/published/deprecated/archived
    
    -- 快照数据
    properties_snapshot TEXT,                  -- 属性快照 JSON
    rules_snapshot TEXT,                       -- 规则快照 JSON
    prompts_snapshot TEXT,                     -- 提示词快照 JSON
    template_snapshot TEXT,                    -- 模板快照 JSON
    relationships_snapshot TEXT,               -- 关系快照 JSON
    
    -- 变更摘要
    change_summary TEXT,                       -- 变更摘要
    change_details TEXT,                       -- 详细变更 JSON
    
    -- 审核相关
    created_by TEXT DEFAULT 'system',          -- 创建者: system/admin/Username
    reviewed_by TEXT,                          -- 审核人
    reviewed_at TEXT,
    
    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
    published_at TEXT,
    
    UNIQUE(item_type_name, version)
);

CREATE INDEX idx_versions_item_type ON sciot_item_type_versions(item_type_name);
CREATE INDEX idx_versions_status ON sciot_item_type_versions(status);

#### 3.1.4 sync_conflicts - 冲突记录

CREATE TABLE sync_conflicts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    
    -- 冲突标识
    item_type_name TEXT NOT NULL,
    field_name TEXT,                           -- 冲突字段
    conflict_type TEXT NOT NULL,               -- FIELD_MODIFIED/FIELD_DELETED/RULE_MODIFIED
    
    -- SCSAI 端数据
    SCSAI_value TEXT,                           -- SCSAI 当前值 JSON
    SCSAI_modified_on TEXT,                     -- SCSAI 修改时间
    
    -- 本地数据
    local_value TEXT,                          -- 本地当前值 JSON
    local_modified_on TEXT,                    -- 本地修改时间
    local_modified_by TEXT,                    -- 本地修改人
    
    -- 解决方案
    resolution TEXT DEFAULT 'pending',         -- pending/use_SCSAI/use_local/merge/custom
    resolved_value TEXT,                       -- 解决后的值 JSON
    resolved_by TEXT,                          -- 解决人
    resolved_at TEXT,                          -- 解决时间
    
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_conflicts_resolution ON sync_conflicts(resolution);

#### 3.1.5 sync_logs - 同步日志

CREATE TABLE sync_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    
    -- 日志标识
    log_type TEXT NOT NULL,                    -- DETECT/SYNC/CONFLICT/ERROR
    log_level TEXT DEFAULT 'info',             -- debug/info/warn/error
    
    -- 日志内容
    message TEXT NOT NULL,
    details TEXT,                              -- 详细信息 JSON
    
    -- 关联对象
    item_type_name TEXT,
    task_id INTEGER,                           -- 关联 sync_queue.id
    
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_sync_logs_type ON sync_logs(log_type, created_at);

3.2 现有表扩展

#### 3.2.1 sciot_item_types 表扩展

ALTER TABLE sciot_item_types ADD COLUMN sync_status TEXT DEFAULT 'synced';
ALTER TABLE sciot_item_types ADD COLUMN SCSAI_modified_on TEXT;
ALTER TABLE sciot_item_types ADD COLUMN local_modified_on TEXT;
ALTER TABLE sciot_item_types ADD COLUMN is_deleted INTEGER DEFAULT 0;
ALTER TABLE sciot_item_types ADD COLUMN deleted_at TEXT;

#### 3.2.2 sciot_properties 表扩展

ALTER TABLE sciot_properties ADD COLUMN sync_status TEXT DEFAULT 'synced';
ALTER TABLE sciot_properties ADD COLUMN SCSAI_modified_on TEXT;
ALTER TABLE sciot_properties ADD COLUMN local_modified_on TEXT;

4. 核心算法设计

4.1 变更检测算法

/**
 * 变更检测算法
 * 
 * 输入: SCSAI 元数据快照、本地版本记录
 * 输出: 变更列表 [{ type, item, local, details }]
 */

async function detectChanges(options = {}) {
    const { 
        itemTypes = null,      // 指定检测的对象类，null 表示全部
        forceFullScan = false  // 是否强制全量扫描
    } = options;
    
    const changes = [];
    
    // 1. 从 SCSAI 获取元数据摘要
    const SCSAIMetadata = await fetchSCSAIMetadataSummary(itemTypes);
    
    // 2. 获取本地版本记录
    const localVersions = db.prepare('SELECT * FROM SCSAI_metadata_versions').all();
    const localMap = new Map(localVersions.map(v => [v.item_type_name, v]));
    
    // 3. 检测新增和修改
    for (const SCSAIItem of SCSAIMetadata) {
        const local = localMap.get(SCSAIItem.name);
        
        if (!local) {
            // 新增
            changes.push({
                type: 'ADD',
                item: SCSAIItem,
                details: { reason: 'SCSAI 新增对象类' }
            });
        } else {
            // 检测是否修改
            const isModified = await detectItemModification(SCSAIItem, local);
            if (isModified) {
                changes.push({
                    type: 'MODIFY',
                    item: SCSAIItem,
                    local: local,
                    details: isModified
                });
            }
        }
    }
    
    // 4. 检测删除
    for (const local of localVersions) {
        if (!SCSAIMetadata.find(a => a.name === local.item_type_name)) {
            changes.push({
                type: 'DELETE',
                local: local,
                details: { reason: 'SCSAI 已删除对象类' }
            });
        }
    }
    
    // 5. 写入变更检测日志
    await logChanges(changes);
    
    return changes;
}

/**
 * 检测单个对象类是否被修改
 */
async function detectItemModification(SCSAIItem, local) {
    // 快速检测：比较 config_id 和 modified_on
    if (SCSAIItem.config_id !== local.SCSAI_config_id ||
        SCSAIItem.modified_on !== local.SCSAI_modified_on) {
        
        // 详细对比
        const details = await compareItemDetails(SCSAIItem.name);
        return details;
    }
    
    return null; // 无变更
}

/**
 * 详细对比对象类属性
 */
async function compareItemDetails(itemTypeName) {
    // 从 SCSAI 获取完整属性
    const SCSAIProps = await fetchSCSAIItemProperties(itemTypeName);
    
    // 从本地获取属性
    const localProps = db.prepare(
        'SELECT * FROM sciot_properties WHERE item_type_name = ?'
    ).all(itemTypeName);
    
    const changes = {
        addedProperties: [],
        modifiedProperties: [],
        deletedProperties: [],
        listValueChanged: [],
        relationshipChanged: []
    };
    
    const localMap = new Map(localProps.map(p => [p.name, p]));
    const SCSAIMap = new Map(SCSAIProps.map(p => [p.name, p]));
    
    // 检测新增和修改的属性
    for (const SCSAIProp of SCSAIProps) {
        const localProp = localMap.get(SCSAIProp.name);
        
        if (!localProp) {
            changes.addedProperties.push(SCSAIProp.name);
        } else {
            // 对比属性是否修改
            const propDiff = compareProperty(SCSAIProp, localProp);
            if (propDiff) {
                changes.modifiedProperties.push({
                    name: SCSAIProp.name,
                    changes: propDiff
                });
            }
        }
    }
    
    // 检测删除的属性
    for (const localProp of localProps) {
        if (!SCSAIMap.has(localProp.name)) {
            changes.deletedProperties.push(localProp.name);
        }
    }
    
    // 如果有任何变更，返回详情
    const hasChanges = changes.addedProperties.length > 0 ||
                       changes.modifiedProperties.length > 0 ||
                       changes.deletedProperties.length > 0;
    
    return hasChanges ? changes : null;
}

4.2 增量同步算法

/**
 * 增量同步处理器
 */
async function processSyncQueue(options = {}) {
    const {
        batchSize = 10,
        dryRun = false  // 试运行，不实际执行
    } = options;
    
    // 获取待处理任务
    const tasks = db.prepare(`
        SELECT * FROM sync_queue 
        WHERE status = 'pending' 
        ORDER BY priority ASC, created_at ASC 
        LIMIT ?
    `).all(batchSize);
    
    const results = [];
    
    for (const task of tasks) {
        try {
            // 标记为处理中
            if (!dryRun) {
                db.prepare("UPDATE sync_queue SET status = 'processing', started_at = ? WHERE id = ?")
                  .run(new Date().toISOString(), task.id);
            }
            
            // 执行任务
            let result;
            switch (task.task_type) {
                case 'ITEMTYPE':
                    result = await syncItemType(task);
                    break;
                case 'LIST':
                    result = await syncList(task);
                    break;
                case 'RELATIONSHIP':
                    result = await syncRelationship(task);
                    break;
                case 'PROPERTY':
                    result = await syncProperty(task);
                    break;
            }
            
            // 标记完成
            if (!dryRun) {
                db.prepare(`
                    UPDATE sync_queue 
                    SET status = 'done', completed_at = ?, result_data = ? 
                    WHERE id = ?
                `).run(new Date().toISOString(), JSON.stringify(result), task.id);
            }
            
            results.push({ task, result, success: true });
            
        } catch (error) {
            // 标记失败
            if (!dryRun) {
                db.prepare(`
                    UPDATE sync_queue 
                    SET status = 'failed', error_msg = ?, retry_count = retry_count + 1 
                    WHERE id = ?
                `).run(error.message, task.id);
            }
            
            results.push({ task, error: error.message, success: false });
        }
    }
    
    return results;
}

/**
 * 同步单个 ItemType
 */
async function syncItemType(task) {
    const itemTypeName = task.target_name;
    
    switch (task.task_action) {
        case 'ADD':
            return await importItemTypeFromSCSAI(itemTypeName);
            
        case 'MODIFY':
            // 检测冲突
            const conflict = await detectConflict(itemTypeName);
            if (conflict) {
                // 标记需要审核
                db.prepare(`
                    UPDATE sync_queue 
                    SET needs_review = 1, review_reason = ? 
                    WHERE id = ?
                `).run(JSON.stringify(conflict), task.id);
                return { needsReview: true, conflict };
            }
            return await updateItemTypeFromSCSAI(itemTypeName);
            
        case 'DELETE':
            // 软删除
            return await markItemTypeDeleted(itemTypeName);
    }
}

4.3 冲突检测算法

/**
 * 冲突检测
 * 
 * 场景：SCSAI 修改了 ItemType，但本地管理员也修改了规则模板
 */
async function detectConflict(itemTypeName) {
    // 获取本地修改记录
    const localMods = db.prepare(`
        SELECT * FROM sciot_item_type_versions 
        WHERE item_type_name = ? AND version_source = 'manual' AND status = 'published'
        ORDER BY version DESC LIMIT 1
    `).get(itemTypeName);
    
    if (!localMods) {
        return null; // 无本地修改，无冲突
    }
    
    // 获取上次同步时间
    const syncRecord = db.prepare(`
        SELECT * FROM SCSAI_metadata_versions WHERE item_type_name = ?
    `).get(itemTypeName);
    
    // 如果本地修改时间晚于上次同步时间，可能冲突
    if (localMods.created_at > syncRecord.local_synced_at) {
        // 详细对比
        const SCSAIProps = await fetchSCSAIItemProperties(itemTypeName);
        const localProps = db.prepare(
            'SELECT * FROM sciot_properties WHERE item_type_name = ?'
        ).all(itemTypeName);
        
        const conflicts = findPropertyConflicts(SCSAIProps, localProps);
        
        if (conflicts.length > 0) {
            // 记录冲突
            for (const c of conflicts) {
                db.prepare(`
                    INSERT INTO sync_conflicts 
                    (item_type_name, field_name, conflict_type, SCSAI_value, local_value)
                    VALUES (?, ?, ?, ?, ?)
                `).run(itemTypeName, c.field, c.type, JSON.stringify(c.SCSAI), JSON.stringify(c.local));
            }
            
            return { itemTypeName, conflicts };
        }
    }
    
    return null;
}

5. API 设计

5.1 变更检测 API

POST /api/meta/detect-changes
  请求体: { itemTypes?: string[], forceFullScan?: boolean }
  响应: { changes: Change[], summary: { added, modified, deleted } }

GET /api/meta/sync-status
  响应: { lastSyncTime, pendingTasks, recentChanges }

5.2 同步任务 API

POST /api/meta/sync/start
  请求体: { taskIds?: number[], autoSync?: boolean }
  响应: { taskId, status }

GET /api/meta/sync/queue
  查询参数: { status?: string, limit?: number }
  响应: { tasks: SyncTask[], total }

POST /api/meta/sync/process
  请求体: { batchSize?: number, dryRun?: boolean }
  响应: { results: SyncResult[] }

POST /api/meta/sync/retry/:taskId
  响应: { success, message }

5.3 版本管理 API

GET /api/meta/versions/:itemTypeName
  响应: { versions: Version[], current: Version }

POST /api/meta/versions/publish
  请求体: { itemTypeName: string, version: number }
  响应: { success, publishedVersion }

POST /api/meta/versions/rollback
  请求体: { itemTypeName: string, targetVersion: number }
  响应: { success, currentVersion }

5.4 冲突处理 API

GET /api/meta/conflicts
  查询参数: { resolution?: string }
  响应: { conflicts: Conflict[] }

POST /api/meta/conflicts/:id/resolve
  请求体: { resolution: 'use_SCSAI'|'use_local'|'merge', customValue?: any }
  响应: { success, resolvedValue }

6. 定时任务设计

6.1 任务调度配置

// config/sync-schedule.js
module.exports = {
    // 变更检测
    changeDetection: {
        enabled: true,
        cron: '*/30 * * * *',  // 每 30 分钟
        options: {
            itemTypes: null,      // null = All
            forceFullScan: false
        }
    },
    
    // 自动同步
    autoSync: {
        enabled: true,
        cron: '*/5 * * * *',     // 每 5 分钟处理队列
        options: {
            batchSize: 10,
            autoSyncAdd: true,    // 自动同步新增
            autoSyncModify: false, // 修改需要审核
            autoSyncDelete: false  // 删除需要审核
        }
    },
    
    // 版本清理
    versionCleanup: {
        enabled: true,
        cron: '0 2 * * 0',       // 每周日凌晨 2 点
        options: {
            keepVersions: 10,     // 保留最近 10 个版本
            archiveOldVersions: true
        }
    },
    
    // 通知
    notification: {
        onConflict: true,
        onSyncComplete: true,
        onSyncFailure: true,
        channels: ['feishu', 'system']
    }
};

6.2 定时任务实现

// server/services/sync-scheduler.js
const cron = require('node-cron');
const config = require('../config/sync-schedule');

class SyncScheduler {
    constructor() {
        this.jobs = [];
    }
    
    start() {
        // 变更检测任务
        if (config.changeDetection.enabled) {
            const job = cron.schedule(config.changeDetection.cron, async () => {
                console.log('[SyncScheduler] 开始变更检测...');
                try {
                    const result = await detectChanges(config.changeDetection.options);
                    await this.handleDetectionResult(result);
                } catch (e) {
                    console.error('[SyncScheduler] 变更检测失败:', e);
                }
            });
            this.jobs.push(job);
        }
        
        // 自动同步任务
        if (config.autoSync.enabled) {
            const job = cron.schedule(config.autoSync.cron, async () => {
                console.log('[SyncScheduler] 开始处理同步队列...');
                try {
                    const result = await processSyncQueue(config.autoSync.options);
                    await this.handleSyncResult(result);
                } catch (e) {
                    console.error('[SyncScheduler] 同步处理失败:', e);
                }
            });
            this.jobs.push(job);
        }
        
        console.log('[SyncScheduler] 定时任务已启动');
    }
    
    stop() {
        for (const job of this.jobs) {
            job.stop();
        }
        console.log('[SyncScheduler] 定时任务已停止');
    }
    
    async handleDetectionResult(result) {
        // 将变更写入同步队列
        for (const change of result.changes) {
            const priority = change.type === 'DELETE' ? 3 : 
                            change.type === 'ADD' ? 5 : 7;
            
            db.prepare(`
                INSERT INTO sync_queue 
                (task_type, task_action, target_name, priority, task_data)
                VALUES ('ITEMTYPE', ?, ?, ?, ?)
            `).run(change.type, change.item?.name || change.local?.item_type_name, 
                   priority, JSON.stringify(change));
        }
        
        // 发送通知
        if (result.changes.length > 0 && config.notification.onSyncComplete) {
            await sendNotification({
                type: 'changes_detected',
                data: result
            });
        }
    }
}

module.exports = new SyncScheduler();

7. 管理界面设计

7.1 同步状态面板

┌─────────────────────────────────────────────────────────────────┐
│  同步状态                                                        │
├─────────────────────────────────────────────────────────────────┤
│  最后同步: 2026-05-29 14:30:00                                   │
│  待处理任务: 5                                                   │
│  今日变更: 新增 2, 修改 3, 删除 0                                 │
│                                                                  │
│  [立即检测变更]  [处理同步队列]  [查看日志]                        │
└─────────────────────────────────────────────────────────────────┘

7.2 同步队列管理

┌─────────────────────────────────────────────────────────────────┐
│  同步队列                                                        │
├─────────────────────────────────────────────────────────────────┤
│  筛选: [All] [待处理] [处理中] [已完成] [失败] [需审核]          │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ ⚠️ MODIFY Project (需审核)                                │  │
│  │    原因: 本地规则模板已修改，与 SCSAI 变更冲突               │  │
│  │    [View details] [使用SCSAI版本] [保留本地版本] [合并]          │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ ✓ ADD NewItemType (待处理)                                │  │
│  │    检测时间: 2026-05-29 14:25:00                           │  │
│  │    [立即同步] [View details]                                   │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

7.3 版本历史查看

┌─────────────────────────────────────────────────────────────────┐
│  Part 版本历史                                                   │
├─────────────────────────────────────────────────────────────────┤
│  当前版本: v15 (已发布)                                          │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ v15 (当前) | 2026-05-29 | admin | 已发布                   │  │
│  │    变更: 新增属性 material_grade                           │  │
│  │    [View details] [回滚到此版本]                                │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ v14 | 2026-05-28 | system | 已发布                         │  │
│  │    变更: 同步 SCSAI 修改                                     │  │
│  │    [View details] [回滚到此版本]                                │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

8. 实施计划

8.1 阶段划分

| 阶段 | 任务 | 工作量 | 优先级 | 依赖 |

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

Total Effort: Approximately 9.5 days

8.2 Detailed Task Breakdown

#### Phase 1: Infrastructure (2 days)

Task 1.1: Create Database Tables

File: scripts/create-sync-tables.js
Contents:
Create SCSAI_metadata_versions table
Create sync_queue table
Create sync_logs table
Extend existing table fields
Verification: Tables created successfully, indexes effective

Task 1.2: Implement Change Detection Algorithm

File: server/services/change-detector.js
Functions:
detectChanges() - Main entry point
detectItemModification() - Single item detection
compareItemDetails() - Detailed comparison
compareProperty() - Property Comparison
Validation: Correctly detects additions/modifications/deletions

Task 1.3: Change Detection API

File: server/routes/meta-sync.router.js
Endpoints:
POST /api/meta/detect-changes
GET /api/meta/sync-status
Validation: API returns correct change list

#### Phase 2: Synchronization Engine (2 days)

Task 2.1: Incremental Sync Engine

File: server/services/incremental-sync.js
Functions:
processSyncQueue() - Queue processing
syncItemType() - ItemType synchronization
syncList() - List synchronization
syncRelationship() - Relationship synchronization
importItemTypeFromSCSAI() - Import from SCSAI
updateItemTypeFromSCSAI() - Update from SCSAI
markItemTypeDeleted() - Mark as deleted
Validation: Correctly handles various sync tasks

Task 2.2: Sync Task API

File: server/routes/meta-sync.router.js
Endpoints:
POST /api/meta/sync/start
GET /api/meta/sync/queue
POST /api/meta/sync/process
POST /api/meta/sync/retry/:taskId
Validation: API correctly manages synchronization tasks

#### Phase 3: Versioning and Conflict Resolution (3 days)

Task 3.1: Version Management Mechanism

File: server/services/version-manager.js
Functions:
createVersion() - Create a new version
publishVersion() - Publish a version
rollbackVersion() - Rollback a version
archiveOldVersions() - Archive old versions
Database: Create sciot_item_type_versions table
Validation: Version creation, publishing, and rollback function correctly

Task 3.2: Conflict Detection Algorithm

File: server/services/conflict-detector.js
Functions:
detectConflict() - Detect conflicts
findPropertyConflicts() - Find property conflicts
findRuleConflicts() - Find rule conflicts
Database: Create sync_conflicts table
Verification: Can correctly detect conflicts

Task 3.3: Conflict Resolution API

File: server/routes/meta-sync.router.js
Endpoints:
GET /api/meta/conflicts
POST /api/meta/conflicts/:id/resolve
Verification: Can properly handle conflicts

#### Phase 4: Scheduling & Notification (1 day)

Task 4.1: Scheduled Task Scheduling

File: server/services/sync-scheduler.js
Configuration: config/sync-schedule.js
Tasks:
Change Detection Scheduled Task
Sync Queue Processing Scheduled Task
Version Cleanup Scheduled Task
Verification: Scheduled tasks execute normally

Task 4.2: Notification Integration

File: server/services/sync-notifier.js
Channels:
Lark Notification
In-System Notification
Events:
Change Detection Completed
Sync Completed
Sync Failed
Conflict Requires Review
Verification: Notifications are sent normally

#### Phase 5: Interface & Documentation (2.5 days)

Task 5.1: Sync Status Dashboard

File: src/views/MetaSync.vue (New)
Components:
Sync Status Overview
Quick Action Buttons
Recent Changes List
Verification: Interface displays normally

Task 5.2: Sync Queue Management

File: src/views/MetaSync.vue
Components:
Task List
Task Filtering
Task Details
Review Actions
Verification: Able to manage synchronization tasks

Task 5.3: Version History View

File: src/views/MetaSync.vue
Components:
Version List
Version Details
Rollback Operation
Verification: Able to view and manage versions

Task 5.4: Documentation Writing

File: docs/meta-sync-system.md
Contents:
System Architecture Description
API Documentation
User Guide
Troubleshooting

9. Risks and Mitigation

Risk	Impact	Probability	Mitigation Measures
SCSAI API instability	Synchronization failure	Medium	Retry mechanism, fallback to manual sync
High volume of concurrent changes	Queue backlog	Low	Batch processing, priority queue
Frequent conflicts	High manual review workload	Medium	Smart merge strategy, auto-resolve simple conflicts
Version data bloat	Storage pressure	Low	Regular archiving, compress old versions
Scheduled task conflicts	Data inconsistency	Low	Distributed lock, task mutual exclusion

10. Acceptance Criteria

10.1 Functional Acceptance

[ ] Able to detect new ItemTypes in SCSAI and sync automatically
[ ] Able to detect modified attributes in SCSAI and generate sync tasks
[ ] Able to detect deleted ItemTypes in SCSAI and mark for deletion
[ ] Can detect List value changes and update the list of selectable values
[ ] Can detect conflicts between local modifications and SCSAI changes
[ ] Can review conflicts via the management interface
[ ] Can view version history and roll back
[ ] Scheduled tasks execute normally
[ ] Notifications are sent normally

10.2 Performance Acceptance

[ ] Change detection response time
[ ] Single ItemType synchronization time
[ ] Batch synchronization of 100 tasks
[ ] Version rollback time

10.3 Reliability Acceptance

[ ] Can automatically retry after synchronization failure
[ ] Mark as failed after 3 retries
[ ] Conflicts do not cause data loss
[ ] Version rollback can restore to the correct state

Appendix A: Example Configuration File

// config/sync-config.js
module.exports = {
    // SCSAI 连接
    SCSAI: {
        serverUrl: 'https://ylxt.chat/scplm',
        database: 'SCPLM',
        timeout: 30000
    },
    
    // 变更检测
    detection: {
        enabled: true,
        mode: 'scheduled',        // scheduled | webhook | manual
        cron: '*/30 * * * *',
        webhookSecret: 'xxx'
    },
    
    // 同步策略
    sync: {
        autoSyncAdd: true,
        autoSyncModify: false,
        autoSyncDelete: false,
        batchSize: 10,
        maxRetry: 3,
        retryDelay: 5000
    },
    
    // 版本管理
    version: {
        keepVersions: 10,
        autoArchive: true,
        archiveAfterDays: 30
    },
    
    // 通知
    notification: {
        enabled: true,
        channels: ['feishu', 'system'],
        feishu: {
            webhook: 'https://open.feishu.cn/xxx',
            secret: 'xxx'
        },
        onConflict: true,
        onSyncComplete: true,
        onSyncFailure: true
    }
};

附录 B: 错误码定义

| 错误码 | 含义 | 处理建议 |

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

| SYNC_001 | SCSAI connection failed | Check network and configuration |

| SYNC_002 | SCSAI authentication failed | Check username and password |

| SYNC_003 | Metadata parsing failed | Check SCSAI version compatibility |

| SYNC_004 | Local database write failed | Check disk space and permissions |

| SYNC_005 | Conflict detection failed | Check version record integrity |

| SYNC_006 | Version rollback failed | Check if the target version exists |

| SYNC_007 | Notification sending failed | Check notification configuration |

SCSAI Metadata Synchronization and Rule Template Update System

SCSAI Metadata Synchronization and Rule Template Update System

1. Problem Analysis

1.1 Limitations of the Current Architecture

1.2 Change Scenario Analysis

2. System Architecture Design

2.1 Overall Architecture

2.2 数据流图

3. 数据库设计

3.1 新增表结构

3.2 现有表扩展

4. 核心算法设计

4.1 变更检测算法

4.2 增量同步算法

4.3 冲突检测算法

5. API 设计

5.1 变更检测 API

5.2 同步任务 API

5.3 版本管理 API

5.4 冲突处理 API

6. 定时任务设计

6.1 任务调度配置

6.2 定时任务实现

7. 管理界面设计

7.1 同步状态面板

7.2 同步队列管理

7.3 版本历史查看

8. 实施计划

8.1 阶段划分

8.2 Detailed Task Breakdown

9. Risks and Mitigation

10. Acceptance Criteria

10.1 Functional Acceptance

10.2 Performance Acceptance

10.3 Reliability Acceptance

Appendix A: Example Configuration File

附录 B: 错误码定义

Try 左帮右臂 Industrial Agent — your digital workforce

Login

Apply for Free Access