ae-tracking 0.1.0

package/dist/src/xlsx/write.js

@@ -0,0 +1,251 @@
+import ExcelJS from 'exceljs';
+// Canonical → Chinese type mapping
+const PROP_TYPE_TO_CHINESE = {
+    'string': '文本',
+    'number': '数值',
+    'bool': '布尔',
+    'datetime': '时间',
+    'array_row': '对象组',
+    'array_string': '列表',
+};
+// EventPlatform → xlsx value
+const PLATFORM_TO_XLSX = {
+    'client': 'client',
+    'server': 'server',
+    'both': 'client,server',
+};
+const VALID_PROP_TYPES = new Set(['string', 'number', 'bool', 'datetime', 'array_row', 'array_string']);
+const VALID_UPDATE_TYPES = new Set(['user_set', 'user_setOnce', 'user_add']);
+const SNAKE_CASE_RE = /^[a-z][a-z0-9_]*$/;
+const PROP_NAME_RE = /^[a-zA-Z#][a-zA-Z0-9_.]*$/;
+export function validateDraft(d) {
+    const errors = [];
+    // Validate event names
+    const eventNames = new Set();
+    for (const evt of d.events) {
+        if (!SNAKE_CASE_RE.test(evt.event_name)) {
+            errors.push(`Event name "${evt.event_name}" does not match snake_case pattern`);
+        }
+        if (eventNames.has(evt.event_name)) {
+            errors.push(`Duplicate event_name: "${evt.event_name}"`);
+        }
+        eventNames.add(evt.event_name);
+    }
+    // Validate event_properties
+    const eventPropNames = new Set();
+    const arrayRowProps = new Set(d.event_properties.filter(p => p.type === 'array_row').map(p => p.name));
+    for (const prop of d.event_properties) {
+        if (!PROP_NAME_RE.test(prop.name)) {
+            errors.push(`Event property name "${prop.name}" has invalid characters`);
+        }
+        // Allow nested: parent.child where parent is array_row
+        if (prop.name.includes('.')) {
+            const parent = prop.name.split('.')[0];
+            if (!arrayRowProps.has(parent)) {
+                errors.push(`Nested property "${prop.name}" references non-array_row parent "${parent}"`);
+            }
+        }
+        if (!VALID_PROP_TYPES.has(prop.type)) {
+            errors.push(`Event property "${prop.name}" has invalid type: "${prop.type}"`);
+        }
+        if (eventPropNames.has(prop.name)) {
+            errors.push(`Duplicate event property name: "${prop.name}"`);
+        }
+        eventPropNames.add(prop.name);
+    }
+    // Validate common_event_properties
+    const commonPropNames = new Set();
+    for (const prop of d.common_event_properties) {
+        if (!VALID_PROP_TYPES.has(prop.type)) {
+            errors.push(`Common event property "${prop.name}" has invalid type: "${prop.type}"`);
+        }
+        if (commonPropNames.has(prop.name)) {
+            errors.push(`Duplicate common event property name: "${prop.name}"`);
+        }
+        commonPropNames.add(prop.name);
+    }
+    // Validate user_properties
+    const userPropNames = new Set();
+    for (const prop of d.user_properties) {
+        if (!VALID_PROP_TYPES.has(prop.type)) {
+            errors.push(`User property "${prop.name}" has invalid type: "${prop.type}"`);
+        }
+        if (prop.update_type && !VALID_UPDATE_TYPES.has(prop.update_type)) {
+            errors.push(`User property "${prop.name}" has invalid update_type: "${prop.update_type}"`);
+        }
+        if (userPropNames.has(prop.name)) {
+            errors.push(`Duplicate user property name: "${prop.name}"`);
+        }
+        userPropNames.add(prop.name);
+    }
+    // Validate event.prop_names reference existing event_properties
+    for (const evt of d.events) {
+        for (const propName of evt.prop_names) {
+            if (!eventPropNames.has(propName)) {
+                errors.push(`Event "${evt.event_name}" references unknown event property "${propName}"`);
+            }
+        }
+    }
+    // === 新增规则 ===
+    // 规则 1: 显示名必须唯一（同一属性池内）
+    // event_properties 池内显示名唯一
+    const eventDisplayNames = new Map();
+    for (const prop of d.event_properties) {
+        if (prop.display_name) {
+            const names = eventDisplayNames.get(prop.display_name) || [];
+            names.push(prop.name);
+            eventDisplayNames.set(prop.display_name, names);
+        }
+    }
+    for (const [displayName, names] of eventDisplayNames) {
+        if (names.length > 1) {
+            errors.push(`Display name "${displayName}" is used by multiple event properties: ${names.join(', ')}`);
+        }
+    }
+    // common_event_properties 池内显示名唯一
+    const commonDisplayNames = new Map();
+    for (const prop of d.common_event_properties) {
+        if (prop.display_name) {
+            const names = commonDisplayNames.get(prop.display_name) || [];
+            names.push(prop.name);
+            commonDisplayNames.set(prop.display_name, names);
+        }
+    }
+    for (const [displayName, names] of commonDisplayNames) {
+        if (names.length > 1) {
+            errors.push(`Display name "${displayName}" is used by multiple common properties: ${names.join(', ')}`);
+        }
+    }
+    // user_properties 池内显示名唯一
+    const userDisplayNames = new Map();
+    for (const prop of d.user_properties) {
+        if (prop.display_name) {
+            const names = userDisplayNames.get(prop.display_name) || [];
+            names.push(prop.name);
+            userDisplayNames.set(prop.display_name, names);
+        }
+    }
+    for (const [displayName, names] of userDisplayNames) {
+        if (names.length > 1) {
+            errors.push(`Display name "${displayName}" is used by multiple user properties: ${names.join(', ')}`);
+        }
+    }
+    // 规则 2: 对象组子属性必须一致
+    // 收集每个 array_row 的所有子属性
+    const arrayRowChildren = new Map();
+    for (const prop of d.event_properties) {
+        if (prop.type === 'array_row') {
+            arrayRowChildren.set(prop.name, new Set());
+        }
+    }
+    for (const prop of d.event_properties) {
+        if (prop.name.includes('.')) {
+            const parent = prop.name.split('.')[0];
+            const children = arrayRowChildren.get(parent);
+            if (children) {
+                children.add(prop.name);
+            }
+        }
+    }
+    // 检查每个事件引用的 array_row 子属性是否一致
+    for (const evt of d.events) {
+        for (const arrayRow of arrayRowProps) {
+            if (evt.prop_names.includes(arrayRow)) {
+                const eventChildren = evt.prop_names.filter(p => p.startsWith(arrayRow + '.'));
+                const expectedChildren = arrayRowChildren.get(arrayRow);
+                if (expectedChildren && eventChildren.length > 0) {
+                    // 检查是否包含所有子属性
+                    for (const child of expectedChildren) {
+                        if (!eventChildren.includes(child)) {
+                            errors.push(`Event "${evt.event_name}" uses "${arrayRow}" but missing child "${child}"`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`Draft validation failed:\n${errors.map(e => '  - ' + e).join('\n')}`);
+    }
+}
+export async function writeDraftXlsx(d, outPath) {
+    validateDraft(d);
+    const workbook = new ExcelJS.Workbook();
+    // === Sheet: #事件数据 ===
+    // Columns: 事件名, 事件显示名, 事件说明, 事件标签, 采集端, 属性名, 属性显示名, 属性类型, 属性说明
+    const eventSheet = workbook.addWorksheet('#事件数据');
+    eventSheet.addRow(['事件名（必填）', '事件显示名', '事件说明', '事件标签', '采集端', '属性名（必填）', '属性显示名', '属性类型（必填）', '属性说明']);
+    // Build a prop map for quick lookup
+    const propByName = new Map(d.event_properties.map(p => [p.name, p]));
+    // AE 后端规则：同一事件跨多行时，事件名列（A-D）必须合并单元格，否则判重拒收。
+    // 用 ExcelJS 的 mergeCells 实现；property-less 事件仍写一行，不合并。
+    for (const evt of d.events) {
+        const startRow = eventSheet.rowCount + 1;
+        const platformStr = evt.platform ? PLATFORM_TO_XLSX[evt.platform] : '';
+        if (evt.prop_names.length === 0) {
+            eventSheet.addRow([
+                evt.event_name,
+                evt.display_name ?? '',
+                evt.event_desc ?? '',
+                evt.event_tag ?? '',
+                platformStr,
+                '', '', '', '',
+            ]);
+        }
+        else {
+            for (const propName of evt.prop_names) {
+                const prop = propByName.get(propName);
+                eventSheet.addRow([
+                    evt.event_name,
+                    evt.display_name ?? '',
+                    evt.event_desc ?? '',
+                    evt.event_tag ?? '',
+                    platformStr,
+                    prop?.name ?? propName,
+                    prop?.display_name ?? '',
+                    prop ? PROP_TYPE_TO_CHINESE[prop.type] : '',
+                    prop?.desc ?? '',
+                ]);
+            }
+            const endRow = eventSheet.rowCount;
+            if (endRow > startRow) {
+                // Merge columns A-E across all rows of this event
+                for (const col of ['A', 'B', 'C', 'D', 'E']) {
+                    eventSheet.mergeCells(`${col}${startRow}:${col}${endRow}`);
+                }
+            }
+        }
+    }
+    // === Sheet: #公共事件属性 ===
+    // Columns: 属性名, 属性显示名, 属性类型, 属性说明
+    const commonSheet = workbook.addWorksheet('#公共事件属性');
+    commonSheet.addRow(['属性名（必填）', '属性显示名', '属性类型（必填）', '属性说明']);
+    for (const prop of d.common_event_properties) {
+        commonSheet.addRow([
+            prop.name,
+            prop.display_name ?? '',
+            PROP_TYPE_TO_CHINESE[prop.type],
+            prop.desc ?? '',
+        ]);
+    }
+    // === Sheet: #用户数据 ===
+    // Columns: 属性名, 属性显示名, 属性类型, 更新方式, 属性说明, 属性标签
+    const userSheet = workbook.addWorksheet('#用户数据');
+    userSheet.addRow(['属性名（必填）', '属性显示名', '属性类型（必填）', '更新方式', '属性说明', '属性标签']);
+    for (const prop of d.user_properties) {
+        userSheet.addRow([
+            prop.name,
+            prop.display_name ?? '',
+            PROP_TYPE_TO_CHINESE[prop.type],
+            prop.update_type ?? 'user_set', // 默认 user_set
+            prop.desc ?? '',
+            prop.prop_tag ?? '',
+        ]);
+    }
+    // #用户ID体系 — AE 后端要求此 sheet 至少有 #account_id 和 #distinct_id 两行数据。
+    const userIdSheet = workbook.addWorksheet('#用户ID体系');
+    userIdSheet.addRow(['属性名', '属性显示名', '属性说明', '赋值说明']);
+    userIdSheet.addRow(['#account_id', '账户ID', '系统属性', `设置为${d.meta.user_identity?.account_id_field ?? '账号ID'}`]);
+    userIdSheet.addRow(['#distinct_id', '访客ID', '系统属性', 'SDK自动生成或设备相关ID']);
+    await workbook.xlsx.writeFile(outPath);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "ae-tracking",
+  "version": "0.1.0",
+  "description": "AE (AgenticEngine) tracking-plan agent with Claude Code skills",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "ae-tracking": "dist/bin/ae-tracking.js"
+  },
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/",
+    "skills/",
+    "wiki/te-docs/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/bin/ae-tracking.js",
+    "prepublishOnly": "npm run build && npm test",
+    "postinstall": "node dist/scripts/postinstall.js || true",
+    "test": "npm run build && vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "exceljs": "^4.4.0",
+    "undici": "^6.19.0",
+    "xlsx": "^0.18.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "execa": "^9.6.1",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}