@ats-cx/cx-core 0.1.0

package/dist/normalize/log.js

@@ -0,0 +1,143 @@
+import { resolve } from "node:path";
+/**
+ * 统一把各种日志返回结构整理成一个标准格式。
+ *
+ * 当前兼容三种输入：
+ * - 直接是数组
+ * - `{ data: { result: [...] } }`
+ * - `{ result: [...] }`
+ *
+ * 这样无论是线上 APM 原始返回，还是离线导出的局部样本，都能直接喂进分析器。
+ */
+export function normalizeLogEnvelope(raw, sourcePath = "") {
+    const rawRecord = raw;
+    const dataResult = rawRecord?.data?.result;
+    const items = Array.isArray(raw)
+        ? raw
+        : Array.isArray(dataResult)
+            ? dataResult
+            : Array.isArray(rawRecord?.result)
+                ? rawRecord.result
+                : [];
+    const events = items
+        .map((item, index) => normalizeEvent(item, index))
+        .sort((left, right) => {
+        if (left.sessionId !== right.sessionId) {
+            return left.sessionId.localeCompare(right.sessionId);
+        }
+        if (left.logTimestamp !== right.logTimestamp) {
+            return left.logTimestamp - right.logTimestamp;
+        }
+        return left.originalIndex - right.originalIndex;
+    });
+    return {
+        generatedAt: new Date().toISOString(),
+        sourcePath: sourcePath ? resolve(sourcePath) : "",
+        eventCount: events.length,
+        sessions: groupEventsBySession(events),
+        events,
+    };
+}
+/**
+ * 规范化单条日志事件。
+ * 这里会做三件事：
+ * - 解析 data_extra / extra_data
+ * - 统一 eventName / sessionId / projectId 等字段
+ * - 从 page_url 中提取 route 和 query
+ */
+function normalizeEvent(item, originalIndex) {
+    const payload = parseJsonField(item.data_extra) || parseJsonField(item.extra_data) || {};
+    const routeInfo = parseRoute(String(item.page_url || item.pageUrl || ""));
+    return {
+        originalIndex,
+        eventName: String(item.data_name || payload.name || item.name || "unknown"),
+        logTime: String(item.log_time || item.logTime || ""),
+        logTimestamp: parseTimestamp(item.log_time || item.logTime),
+        receivedTime: String(item.received_time || item.receivedTime || ""),
+        receivedTimestamp: parseTimestamp(item.received_time || item.receivedTime),
+        sessionId: String(item.session_id || item.sessionId || "unknown-session"),
+        projectId: String(item.project_id || item.projectId || ""),
+        userId: String(item.user_id || item.userId || ""),
+        type: String(item.type || ""),
+        subType: String(item.sub_type || item.subType || ""),
+        pageUrl: String(item.page_url || item.pageUrl || ""),
+        route: routeInfo.route,
+        query: routeInfo.query,
+        payload,
+        device: {
+            osType: String(item.os_type || item.osType || ""),
+            deviceType: String(item.device_type || item.deviceType || ""),
+            host: String(item.host || ""),
+            agentVersion: String(item.agent_version || item.agentVersion || ""),
+            terminalId: String(item.terminal_id || item.terminalId || ""),
+        },
+        raw: item,
+    };
+}
+/**
+ * 安全解析 JSON 字符串，失败则返回 null。
+ */
+function parseJsonField(value) {
+    if (!value || typeof value !== "string") {
+        return null;
+    }
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 把日志时间字符串转成时间戳，后续用于排序和计算间隔秒数。
+ */
+function parseTimestamp(value) {
+    const parsed = Date.parse(String(value ?? ""));
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+/**
+ * 从 page_url 中拆出路由和查询参数。
+ * 例如：
+ * `/cxeditor/index.html?virtualProjectGuid=1#/photobook`
+ * 会变成：
+ * - route = /photobook
+ * - query.virtualProjectGuid = 1
+ */
+function parseRoute(pageUrl) {
+    if (!pageUrl) {
+        return { route: "", query: {} };
+    }
+    try {
+        const url = new URL(pageUrl, "https://diagnostic.local");
+        return {
+            route: url.hash ? url.hash.slice(1) : url.pathname,
+            query: Object.fromEntries(url.searchParams.entries()),
+        };
+    }
+    catch {
+        return { route: "", query: {} };
+    }
+}
+/**
+ * 按 session 聚合事件。
+ * 诊断系统最终不是分析单条日志，而是分析一次“用户操作会话”。
+ */
+function groupEventsBySession(events) {
+    const sessionMap = {};
+    for (const event of events) {
+        if (!sessionMap[event.sessionId]) {
+            sessionMap[event.sessionId] = [];
+        }
+        sessionMap[event.sessionId].push(event);
+    }
+    return Object.entries(sessionMap).map(([sessionId, sessionEvents]) => ({
+        sessionId,
+        projectId: sessionEvents[0]?.projectId || "",
+        userId: sessionEvents[0]?.userId || "",
+        startedAt: sessionEvents[0]?.logTime || "",
+        endedAt: sessionEvents[sessionEvents.length - 1]?.logTime || "",
+        eventCount: sessionEvents.length,
+        events: sessionEvents,
+    }));
+}
+//# sourceMappingURL=log.js.map

package/dist/normalize/project.d.ts

@@ -0,0 +1,18 @@
+import type { NormalizedProject } from "../types.js";
+/**
+ * 把 project.json 规范化成适合诊断与检索的结构。
+ *
+ * 原始 project.json 更像编辑器运行态数据，不适合直接分析：
+ * - 页面分散在多个集合里，例如 pages / cover / frontFlysheet
+ * - 元素结构深、字段不统一
+ * - 日志里经常只给 elementId 或 sheetIndex
+ *
+ * 这个函数会把它压平为：
+ * - projectMeta
+ * - pages
+ * - elements
+ * - elementIndex
+ *
+ * 这样日志分析阶段就能快速把 event payload 反查到具体页面和元素。
+ */
+export declare function normalizeProjectSnapshot(rawSnapshot: unknown, sourcePath?: string): NormalizedProject;

package/dist/normalize/project.js

@@ -0,0 +1,254 @@
+import { resolve } from "node:path";
+/**
+ * 把 project.json 规范化成适合诊断与检索的结构。
+ *
+ * 原始 project.json 更像编辑器运行态数据，不适合直接分析：
+ * - 页面分散在多个集合里，例如 pages / cover / frontFlysheet
+ * - 元素结构深、字段不统一
+ * - 日志里经常只给 elementId 或 sheetIndex
+ *
+ * 这个函数会把它压平为：
+ * - projectMeta
+ * - pages
+ * - elements
+ * - elementIndex
+ *
+ * 这样日志分析阶段就能快速把 event payload 反查到具体页面和元素。
+ */
+export function normalizeProjectSnapshot(rawSnapshot, sourcePath = "") {
+    const root = rawSnapshot.project ? rawSnapshot : { project: rawSnapshot };
+    const project = (root.project || {});
+    const images = normalizeImages(root.images || []);
+    const imageIndex = Object.fromEntries(images.flatMap((image) => buildImageKeys(image).map((key) => [key, image])));
+    const pageNodes = collectPageNodes(project);
+    const pages = [];
+    const elements = [];
+    const elementIndex = {};
+    const elementTypeCounts = {};
+    for (let pageOrder = 0; pageOrder < pageNodes.length; pageOrder += 1) {
+        const pageNode = pageNodes[pageOrder];
+        const page = normalizePage(pageNode, pageOrder);
+        pages.push(page);
+        for (let elementOrder = 0; elementOrder < pageNode.node.elements.length; elementOrder += 1) {
+            const rawElement = pageNode.node.elements[elementOrder];
+            const element = normalizeElement(rawElement, page, elementOrder, imageIndex);
+            elements.push(element);
+            elementIndex[element.lookupKey] = element;
+            if (element.id) {
+                elementIndex[element.id] = element;
+            }
+            if (element.oriElementId) {
+                elementIndex[element.oriElementId] = element;
+            }
+            elementTypeCounts[element.type] = (elementTypeCounts[element.type] || 0) + 1;
+        }
+    }
+    return {
+        generatedAt: new Date().toISOString(),
+        sourcePath: sourcePath ? resolve(sourcePath) : "",
+        projectMeta: buildProjectMeta(project),
+        imageCount: images.length,
+        pageCount: pages.length,
+        elementCount: elements.length,
+        pageCollectionCounts: countBy(pages, (page) => page.collectionName),
+        elementTypeCounts,
+        pages,
+        elements,
+        elementIndex,
+        images,
+    };
+}
+/**
+ * 组装项目元信息。
+ *
+ * 除了保留 guid/version 等稳定字段，也把 `project.spec` 保留到
+ * `projectMeta.spec`，这样报告里既能看到完整规格信息，也不会污染顶层元字段。
+ */
+function buildProjectMeta(project) {
+    return {
+        guid: project.guid || null,
+        version: project.version || null,
+        clientId: project.clientId || null,
+        createdDate: project.createdDate || null,
+        updatedDate: project.updatedDate || null,
+        spuVersion: project.spuVersion || null,
+        applyBookThemeId: project.applyBookThemeId || null,
+        isFlexProject: Boolean(project.isFlexProject),
+        spec: normalizeProjectSpec(project.spec),
+    };
+}
+/**
+ * 复制 project.spec，避免后续调用方意外持有原始引用。
+ */
+function normalizeProjectSpec(spec) {
+    if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+        return {};
+    }
+    return { ...spec };
+}
+/**
+ * 提取图片基础信息。
+ * 当前只保留诊断里最常用的字段，后续如果需要做图像尺寸异常或上传链路分析，再继续扩展。
+ */
+function normalizeImages(rawImages) {
+    return rawImages.map((image) => ({
+        guid: image.guid || null,
+        encImgId: image.encImgId || null,
+        name: image.name || null,
+        width: numberOrNull(image.width),
+        height: numberOrNull(image.height),
+        uploadTime: image.uploadTime || null,
+    }));
+}
+/**
+ * 图片通常既可以通过 guid，也可以通过 encImgId 被元素引用，因此这里同时建立两套索引键。
+ */
+function buildImageKeys(image) {
+    return [image.guid, image.encImgId].filter(Boolean);
+}
+/**
+ * 遍历整个 project 对象，找到所有含有 `elements` 数组的节点，把它们都视作“页面”。
+ *
+ * 这里故意不只盯着 `project.pages`：
+ * - cover
+ * - frontFlysheet
+ * - backFlysheet
+ * - 其他特殊 page-like 结构
+ *
+ * 都可能携带 elements。
+ */
+function collectPageNodes(project) {
+    const pages = [];
+    function walk(node, pathName) {
+        if (!node) {
+            return;
+        }
+        if (Array.isArray(node)) {
+            node.forEach((item, index) => walk(item, `${pathName}[${index}]`));
+            return;
+        }
+        if (typeof node !== "object") {
+            return;
+        }
+        const record = node;
+        if (Array.isArray(record.elements)) {
+            pages.push({ node: record, path: pathName });
+            return;
+        }
+        for (const [key, value] of Object.entries(record)) {
+            walk(value, pathName ? `${pathName}.${key}` : key);
+        }
+    }
+    walk(project, "project");
+    return pages;
+}
+/**
+ * 规范化页面节点，补出 collectionName / collectionIndex 这种诊断场景很常用的信息。
+ * 例如 `project.pages[4]` 会拆成：
+ * - collectionName = pages
+ * - collectionIndex = 4
+ */
+function normalizePage(pageNode, pageOrder) {
+    const match = /\.([A-Za-z_][\w$]*)\[(\d+)\]$/.exec(pageNode.path);
+    return {
+        id: pageNode.node.id || null,
+        type: pageNode.node.type || null,
+        path: pageNode.path,
+        order: pageOrder,
+        collectionName: match ? match[1] : inferCollectionName(pageNode.path),
+        collectionIndex: match ? Number(match[2]) : pageOrder,
+        width: numberOrNull(pageNode.node.width),
+        height: numberOrNull(pageNode.node.height),
+        elementCount: Array.isArray(pageNode.node.elements) ? pageNode.node.elements.length : 0,
+        elementTypes: countBy(pageNode.node.elements || [], (element) => element.type || "Unknown"),
+    };
+}
+/**
+ * 在路径无法直接命中数组下标时，尽量给一个兜底的集合名。
+ */
+function inferCollectionName(pagePath) {
+    const parts = pagePath.split(".");
+    return parts.length >= 2 ? parts[parts.length - 1] : "unknown";
+}
+/**
+ * 把元素压平为诊断友好的结构。
+ *
+ * 重点保留三类信息：
+ * - 定位信息：元素在哪一页、元素顺序、查找键
+ * - 几何信息：x/y/width/height/rot 等
+ * - 裁剪和图片引用：crop / imageRef / imageName
+ *
+ * 这些字段足以支撑：
+ * - 日志事件反查元素
+ * - 历史版本 diff
+ * - LLM 描述“哪个元素发生了什么变化”
+ */
+function normalizeElement(rawElement, page, elementOrder, imageIndex) {
+    const imageRef = rawElement.encImgId ||
+        rawElement.imageid ||
+        rawElement.imageId ||
+        rawElement.backgroundId ||
+        rawElement.decorationResourceId ||
+        null;
+    const image = imageRef ? imageIndex[imageRef] || null : null;
+    const lookupKey = rawElement.id ||
+        rawElement.oriElementId ||
+        `${page.path}.elements[${elementOrder}]`;
+    return {
+        lookupKey,
+        id: rawElement.id || null,
+        oriElementId: rawElement.oriElementId || null,
+        type: rawElement.type || "Unknown",
+        pageId: page.id,
+        pagePath: page.path,
+        pageOrder: page.order,
+        pageCollection: page.collectionName,
+        pageCollectionIndex: page.collectionIndex,
+        elementOrder,
+        imageRef,
+        imageName: image ? image.name : null,
+        geometry: pickDefined(rawElement, ["x", "y", "width", "height", "rot", "imgRot", "pw", "ph", "px", "py"]),
+        crop: pickDefined(rawElement, ["cropLUX", "cropLUY", "cropRLX", "cropRLY"]),
+        meta: pickDefined(rawElement, [
+            "border",
+            "dep",
+            "style",
+            "graphicObjType",
+            "designObjType",
+            "backgroundId",
+            "decorationResourceType",
+            "decorationResourceId",
+            "craftType",
+        ]),
+    };
+}
+/**
+ * 从原始对象里只挑出“有值”的字段，避免规范化后的 JSON 充满 null。
+ */
+function pickDefined(source, keys) {
+    const result = {};
+    for (const key of keys) {
+        if (source[key] !== undefined && source[key] !== null && source[key] !== "") {
+            result[key] = source[key];
+        }
+    }
+    return result;
+}
+/**
+ * 通用计数器，用于页面类型、元素类型等基础统计。
+ */
+function countBy(items, iteratee) {
+    const counts = {};
+    for (const item of items) {
+        const key = iteratee(item) || "unknown";
+        counts[key] = (counts[key] || 0) + 1;
+    }
+    return counts;
+}
+/**
+ * 只保留 number，否则返回 null，避免把字符串数字误认为可信几何字段。
+ */
+function numberOrNull(value) {
+    return typeof value === "number" ? value : null;
+}
+//# sourceMappingURL=project.js.map

package/dist/providers/log-provider.d.ts

@@ -0,0 +1,27 @@
+import type { ApmClientDeps, FlushRecord } from "../apm/client.js";
+import type { ApmProviderState } from "../apm/config-state.js";
+import type { LogEnvelope, ResolvedConfig } from "../types.js";
+export interface LogProvenance {
+    source: "apm" | "file";
+    fetchedAt: string;
+    request?: {
+        url: string;
+        body: Record<string, unknown>;
+    };
+    file?: string;
+    meta?: unknown;
+    total?: number;
+    fetched?: number;
+    pagesFetched?: number;
+    warnings: string[];
+    flush: FlushRecord;
+}
+export interface LogFetchResult {
+    normalized: LogEnvelope;
+    provenance: LogProvenance;
+}
+export interface LogProvider {
+    fetch(projectId: string): Promise<LogFetchResult>;
+}
+export declare function createLogProvider(logSource: ResolvedConfig["logSource"], apmProvider: ResolvedConfig["apmProvider"], deps?: ApmClientDeps, apmProviderState?: ApmProviderState | null): LogProvider;
+export declare function createFileLogProvider(path: string): LogProvider;

package/dist/providers/log-provider.js

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createApmClient } from "../apm/client.js";
+import { createApmConfigError, isApmConfigured } from "../apm/config-state.js";
+import { ApmRequestError } from "../apm/errors.js";
+import { normalizeLogEnvelope } from "../normalize/log.js";
+export function createLogProvider(logSource, apmProvider, deps = {}, apmProviderState = null) {
+    if (logSource.type === "file") {
+        return createFileLogProvider(logSource.path);
+    }
+    return {
+        async fetch(projectId) {
+            if (!apmProvider) {
+                if (!isApmConfigured(apmProviderState)) {
+                    throw createApmConfigError(apmProviderState);
+                }
+                throw new ApmRequestError("invalid_config", { message: "apm 配置状态与 provider 不一致" });
+            }
+            const result = await createApmClient(apmProvider, deps).query({
+                type: apmProvider.runPreset.type,
+                project: projectId,
+                from: apmProvider.runPreset.log_time_start || undefined,
+                app: apmProvider.defaults.app_id,
+                bizline: apmProvider.defaults.bizline_id,
+                order: "ASC",
+            });
+            return {
+                normalized: normalizeLogEnvelope({ result: result.rows }),
+                provenance: {
+                    source: "apm",
+                    fetchedAt: new Date().toISOString(),
+                    request: result.request,
+                    total: result.total,
+                    fetched: result.rows.length,
+                    pagesFetched: result.pagesFetched,
+                    warnings: result.warnings,
+                    flush: result.flush,
+                },
+            };
+        },
+    };
+}
+export function createFileLogProvider(path) {
+    const file = resolve(path);
+    return {
+        async fetch() {
+            const raw = JSON.parse(readFileSync(file, "utf8"));
+            const hasMeta = typeof raw === "object" && raw !== null && !Array.isArray(raw) && Object.prototype.hasOwnProperty.call(raw, "meta");
+            return {
+                normalized: normalizeLogEnvelope(raw, file),
+                provenance: {
+                    source: "file",
+                    fetchedAt: new Date().toISOString(),
+                    file,
+                    ...(hasMeta ? { meta: raw.meta } : {}),
+                    warnings: [],
+                    flush: { attempted: false },
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=log-provider.js.map

package/dist/providers/project-provider.d.ts

@@ -0,0 +1,10 @@
+export interface ProjectSnapshotVersion {
+    version: string;
+    filePath: string;
+    data: unknown;
+}
+export interface ProjectProvider {
+    loadHistory(projectId: string): Promise<ProjectSnapshotVersion[]>;
+}
+/** 本地目录实现：`<projectHistoryDir>/<projectId>/*.json`，按文件名排序即版本序。 */
+export declare function createProjectProvider(projectHistoryDir: string): ProjectProvider;

package/dist/providers/project-provider.js

@@ -0,0 +1,22 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** 本地目录实现：`<projectHistoryDir>/<projectId>/*.json`，按文件名排序即版本序。 */
+export function createProjectProvider(projectHistoryDir) {
+    return {
+        async loadHistory(projectId) {
+            const dir = join(projectHistoryDir, projectId);
+            if (!existsSync(dir)) {
+                return [];
+            }
+            return readdirSync(dir)
+                .filter(name => name.endsWith(".json"))
+                .sort()
+                .map(name => ({
+                version: name.replace(/\.json$/, ""),
+                filePath: join(dir, name),
+                data: JSON.parse(readFileSync(join(dir, name), "utf8")),
+            }));
+        },
+    };
+}
+//# sourceMappingURL=project-provider.js.map

package/dist/providers/remote-project-provider.d.ts

@@ -0,0 +1,28 @@
+import type { DbClient } from "../db/client.js";
+export interface ProjectPullEntry {
+    projectId: string;
+    /** 本次实际落盘的文件数，恒等于 `files.length`（`files` 内无重复路径）。 */
+    snapshotCount: number;
+    files: string[];
+    /** 单条记录落盘失败的原因（数据坏、CREATE_TIME 无效等），其余记录照常写入。 */
+    failures: string[];
+}
+export interface RemoteProjectPullResult {
+    projects: ProjectPullEntry[];
+    warnings: string[];
+}
+export interface RemoteProjectProvider {
+    /** 每个 id 拉最新一条（最新一秒里 UIDPK 最大、即最后写入的那条）。 */
+    pullLatest(projectIds: string[]): Promise<RemoteProjectPullResult>;
+    /** 每个 id 拉全量历史，按 CREATE_TIME 升序。 */
+    pullHistory(projectIds: string[]): Promise<RemoteProjectPullResult>;
+}
+/**
+ * 远端快照拉取：查 DB → 转 JSON → 落盘 `<projectHistoryDir>/<projectId>/<projectId>_<时间>.json`
+ * （同秒的第 2 条起带 `_02` 序号后缀，见 planSnapshots）。
+ *
+ * 逐 projectId 循环执行单项目 SQL（不用 CTE + ROW_NUMBER）：不依赖 MySQL 8，错误定位到单 id；
+ * pull 的 id 数量极小，N 次往返可忽略。
+ * 连接 / SQL 错误一律向上抛（由调用方转 exit 1），只有「查到 0 条」与「单条记录坏数据」降级为警告 / 失败记录。
+ */
+export declare function createRemoteProjectProvider(client: DbClient, projectHistoryDir: string): RemoteProjectProvider;