@yaoxiu/marketing-dsl 1.4.0 → 1.5.0

package/README.md

@@ -158,3 +158,45 @@ buildAiPrompt(); // 生成喂给 AI 的提示词
 章节正文是**数据**（`DocBlock` 数组）不是字符串：调试台按块渲染成页面，`toMarkdown` 导出成 markdown，
 同一份内容两边永远一致。节点类型 / 动作 / 样式白名单 / 埋点事件名正则等清单一律从解释器常量取，
 并经 `reconcileRows` 对账——解释器加了东西而文档没跟上，会在文档页面上直接标出来。
+
+---
+
+## 上报契约（`/report` 子路径）
+
+物料的曝光 / 点击 / 关闭要如实上报给后端。**「运行时事件 → 上报载荷」这一步的映射是纯函数，
+放在这个包的 `/report` 子路径里**，前台（`move-front`）与后台调试台（`moveback-front`）共用同一份：
+
+```ts
+import {
+  mapRuntimeEventToReport,
+  buildExposureReport,
+} from '@yaoxiu/marketing-dsl/report';
+import type { MarketingReportParams } from '@yaoxiu/marketing-dsl/report';
+
+// 宿主把物料画到页面上时主动发（曝光不由运行时事件触发，解释器不知道自己被画出来了）
+buildExposureReport(materialId); // → { id, event: 'exposure' }
+
+// runtime 的 emit 事件直接喂进来，返回 null 表示这个事件不产生上报
+mapRuntimeEventToReport(materialId, 'track', {
+  event: 'banner_renew_click',
+  params: { pos: 1 },
+});
+// → { id, event: 'click', extra: { trigger: 'track', name: 'banner_renew_click', params: { pos: 1 } } }
+mapRuntimeEventToReport(materialId, 'navigate', { url: 'https://a.com' });
+// → { id, event: 'click', extra: { trigger: 'navigate', url: 'https://a.com' } }
+mapRuntimeEventToReport(materialId, 'close', { reason: 'mask' });
+// → { id, event: 'close', reason: 'mask' }
+mapRuntimeEventToReport(materialId, 'call', payload); // → null（call / error / state-change / view-change / ready / open 都不上报）
+```
+
+上报载荷 `MarketingReportParams` 是**可辨识联合**：`reason` 只属于 `close`、`extra` 只属于 `click`，
+写错编译不过；不该出现的字段声明成 `?: never` 而非省略，消费方仍可直接读，不必先窄化。
+
+**给谁用**：接了后端上报的宿主（前台坑位组件），以及调试台的「上报预览」——
+预览要展示的就是真实会发给后端的 JSON，映射再写第二份，前台改了口径而调试台没跟上，预览就会骗人。
+
+**为什么不在主入口**：主入口的身份是「DSL 解释器」，上报是**可选的附加约定**，
+只有接了上报的宿主才需要。主入口不 re-export，边界才清楚，只用解释器的消费方也不背这份代码。
+包根同样有一个物理 `report/` 转发垫片，理由与 `docs/` 一致（webpack 4 不认 `exports`）。
+
+契约字段的完整说明（后端视角）见 `move-front` 仓库的 `docs/marketing/README.md`。

package/dist/report/index.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+// src/report/map.ts
+function buildExposureReport(id) {
+  if (!id) return null;
+  return { id, event: "exposure" };
+}
+function mapRuntimeEventToReport(id, event, payload) {
+  if (!id) return null;
+  switch (event) {
+    case "track": {
+      const data = payload != null ? payload : {};
+      return {
+        id,
+        event: "click",
+        extra: { trigger: "track", name: data.event, params: data.params }
+      };
+    }
+    case "navigate": {
+      const data = payload != null ? payload : {};
+      return {
+        id,
+        event: "click",
+        extra: { trigger: "navigate", url: data.url }
+      };
+    }
+    case "close": {
+      const data = payload != null ? payload : {};
+      return {
+        id,
+        event: "close",
+        reason: data.reason
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+exports.buildExposureReport = buildExposureReport;
+exports.mapRuntimeEventToReport = mapRuntimeEventToReport;

package/dist/report/index.d.cts

@@ -0,0 +1,150 @@
+import { E as RuntimeEventName } from '../types-BgUaJUAu.cjs';
+
+/**
+ * 营销物料上报载荷类型（上报契约的唯一数据源）。
+ *
+ * 契约正文见仓库 `docs/marketing/README.md` 的「接口契约 · 上报事件」一节，
+ * 本文件是它的类型化表达，前台（platform-adapters / ui-vue2）与后台调试台共用同一份。
+ *
+ * 【为什么在 core 包里】调试台不装 platform-adapters，两边唯一的共同载体就是这个已发布的 npm 包。
+ * 但它是**可选的附加约定**，走子路径 `@yaoxiu/marketing-dsl/report` 独立入口，
+ * 主入口不 re-export —— 主入口的身份仍然只是「DSL 解释器」，不该知道上报契约的存在。
+ */
+/**
+ * 上报事件类型：曝光 / 点击 / 关闭
+ *
+ * 这是**物料生命周期**的固定三值枚举，由前端写死，不受运营配置影响：
+ * - `exposure` 曝光：物料渲染到页面时，每条一次
+ * - `click` 点击：用户点了物料里任何带动作的元素
+ * - `close` 关闭：用户关掉了这条物料
+ */
+type MarketingReportEvent = 'exposure' | 'click' | 'close';
+/**
+ * 点击上报的附加信息（**只在 `event='click'` 时有值**）
+ *
+ * 运营在 DSL 里自定义的埋点名 / 参数一律放这里，
+ * **不要塞进 `reason`** —— `reason` 的语义被「关闭原因」独占。
+ */
+interface MarketingClickExtra {
+    /** 点击来源：`track` = 运营配的埋点动作；`navigate` = 跳转动作 */
+    trigger: 'track' | 'navigate';
+    /** `trigger='track'` 时：运营在配置里写的埋点名 */
+    name?: string;
+    /** `trigger='navigate'` 时：跳转目标地址 */
+    url?: string;
+    /** 运营在配置里写的自定义参数，原样透传 */
+    params?: Record<string, unknown>;
+}
+/** 曝光上报入参：只有 id */
+interface MarketingExposureReportParams {
+    /** 物料 id，取自 `MarketingMaterial.id` */
+    id: string;
+    /** 事件类型 */
+    event: 'exposure';
+    /** 曝光事件无关闭原因 */
+    reason?: never;
+    /** 曝光事件无点击附加信息 */
+    extra?: never;
+}
+/** 关闭上报入参：可带关闭原因 */
+interface MarketingCloseReportParams {
+    /** 物料 id */
+    id: string;
+    /** 事件类型 */
+    event: 'close';
+    /**
+     * 关闭原因，取自解释器抛出的 close reason：
+     * `close-button`（点 ×）/ `mask`（点遮罩）/ `countdown-end`（倒计时归零自动关）/
+     * `action`（配置里 close 动作未写 reason 的默认值）/ 运营自定义值。
+     */
+    reason?: string;
+    /** 关闭事件无点击附加信息 */
+    extra?: never;
+}
+/** 点击上报入参：必须带 extra 说明点了什么 */
+interface MarketingClickReportParams {
+    /** 物料 id */
+    id: string;
+    /** 事件类型 */
+    event: 'click';
+    /** 点击事件不写关闭原因 */
+    reason?: never;
+    /** 点击详情，见 {@link MarketingClickExtra} */
+    extra: MarketingClickExtra;
+}
+/**
+ * 上报物料事件的入参（可辨识联合，按 `event` 区分）
+ *
+ * 用联合而非「三个可选字段」是为了把契约写进类型里：`reason` 只配 `close`、
+ * `extra` 只配 `click`，写错直接编译不过。不该出现的字段声明成 `?: never`
+ * 而不是省略，这样消费方（formatter / 上报层 / 调试台预览）仍能直接读
+ * `params.reason`、`params.extra`，无需先做类型窄化 —— 约束留在调用侧，消费侧照旧好写。
+ */
+type MarketingReportParams = MarketingExposureReportParams | MarketingCloseReportParams | MarketingClickReportParams;
+
+/**
+ * 「DSL 运行时事件 → 上报载荷」的映射（纯函数，无副作用、无框架依赖）。
+ *
+ * 前台坑位组件与后台调试台的「上报预览」共用这一份：
+ * 调试台要展示的就是**真实会发给后端的 JSON**，映射有第二份实现，
+ * 前台改了口径而调试台忘了改，调试台就会骗人。
+ */
+
+/**
+ * 会产生上报的运行时事件及其载荷。
+ *
+ * 字段一律可选：宿主（Vue 组件的 `$event`、调试台的手工构造）拿到的载荷未必齐全，
+ * 缺字段是允许的，不该在映射这一步炸掉。
+ */
+interface MarketingReportableEventPayloads {
+    /** 埋点动作：`event` 是运营配的埋点名，`params` 是自定义参数 */
+    track: {
+        event?: string;
+        params?: Record<string, unknown>;
+    };
+    /** 跳转动作：`url` 是目标地址（跳转本身由渲染壳完成，这里只记一笔） */
+    navigate: {
+        url?: string;
+        target?: string;
+    };
+    /** 关闭：`reason` 是关闭原因 */
+    close: {
+        reason?: string;
+    };
+}
+/** 会产生上报的运行时事件名 */
+type MarketingReportableEventName = keyof MarketingReportableEventPayloads;
+/**
+ * 事件名 → 载荷类型。
+ *
+ * 不产生上报的事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）
+ * 载荷为 `unknown`：调用方照常传，映射返回 `null`。
+ */
+type MarketingRuntimeEventPayload<K extends RuntimeEventName> = K extends MarketingReportableEventName ? MarketingReportableEventPayloads[K] : unknown;
+/**
+ * 曝光上报载荷。
+ *
+ * 单独一个函数是因为曝光**不由运行时事件触发** —— 它是宿主把物料渲染到页面上时主动发的，
+ * 解释器根本不知道自己被画出来了。
+ *
+ * @param id 物料 id，为空（未取到物料）时返回 `null`，不产生上报
+ * @returns 上报载荷，或 `null`
+ */
+declare function buildExposureReport(id: string | undefined | null): MarketingExposureReportParams | null;
+/**
+ * 把一个 DSL 运行时事件映射成上报载荷。
+ *
+ * 口径（与 `docs/marketing/README.md` 的契约一一对应）：
+ * - `track` → `click`，`extra = { trigger: 'track', name, params }`
+ * - `navigate` → `click`，`extra = { trigger: 'navigate', url }`
+ * - `close` → `close`，带 `reason`
+ * - 其余事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）不产生上报
+ *
+ * @param id 物料 id，为空时返回 `null`（拿不到 id 的上报对后端没有意义）
+ * @param event 运行时事件名
+ * @param payload 事件载荷，可缺省
+ * @returns 上报载荷，或 `null`（该事件不产生上报）
+ */
+declare function mapRuntimeEventToReport<K extends RuntimeEventName>(id: string | undefined | null, event: K, payload?: MarketingRuntimeEventPayload<K>): MarketingReportParams | null;
+
+export { type MarketingClickExtra, type MarketingClickReportParams, type MarketingCloseReportParams, type MarketingExposureReportParams, type MarketingReportEvent, type MarketingReportParams, type MarketingReportableEventName, type MarketingReportableEventPayloads, type MarketingRuntimeEventPayload, buildExposureReport, mapRuntimeEventToReport };

package/dist/report/index.d.ts

@@ -0,0 +1,150 @@
+import { E as RuntimeEventName } from '../types-BgUaJUAu.js';
+
+/**
+ * 营销物料上报载荷类型（上报契约的唯一数据源）。
+ *
+ * 契约正文见仓库 `docs/marketing/README.md` 的「接口契约 · 上报事件」一节，
+ * 本文件是它的类型化表达，前台（platform-adapters / ui-vue2）与后台调试台共用同一份。
+ *
+ * 【为什么在 core 包里】调试台不装 platform-adapters，两边唯一的共同载体就是这个已发布的 npm 包。
+ * 但它是**可选的附加约定**，走子路径 `@yaoxiu/marketing-dsl/report` 独立入口，
+ * 主入口不 re-export —— 主入口的身份仍然只是「DSL 解释器」，不该知道上报契约的存在。
+ */
+/**
+ * 上报事件类型：曝光 / 点击 / 关闭
+ *
+ * 这是**物料生命周期**的固定三值枚举，由前端写死，不受运营配置影响：
+ * - `exposure` 曝光：物料渲染到页面时，每条一次
+ * - `click` 点击：用户点了物料里任何带动作的元素
+ * - `close` 关闭：用户关掉了这条物料
+ */
+type MarketingReportEvent = 'exposure' | 'click' | 'close';
+/**
+ * 点击上报的附加信息（**只在 `event='click'` 时有值**）
+ *
+ * 运营在 DSL 里自定义的埋点名 / 参数一律放这里，
+ * **不要塞进 `reason`** —— `reason` 的语义被「关闭原因」独占。
+ */
+interface MarketingClickExtra {
+    /** 点击来源：`track` = 运营配的埋点动作；`navigate` = 跳转动作 */
+    trigger: 'track' | 'navigate';
+    /** `trigger='track'` 时：运营在配置里写的埋点名 */
+    name?: string;
+    /** `trigger='navigate'` 时：跳转目标地址 */
+    url?: string;
+    /** 运营在配置里写的自定义参数，原样透传 */
+    params?: Record<string, unknown>;
+}
+/** 曝光上报入参：只有 id */
+interface MarketingExposureReportParams {
+    /** 物料 id，取自 `MarketingMaterial.id` */
+    id: string;
+    /** 事件类型 */
+    event: 'exposure';
+    /** 曝光事件无关闭原因 */
+    reason?: never;
+    /** 曝光事件无点击附加信息 */
+    extra?: never;
+}
+/** 关闭上报入参：可带关闭原因 */
+interface MarketingCloseReportParams {
+    /** 物料 id */
+    id: string;
+    /** 事件类型 */
+    event: 'close';
+    /**
+     * 关闭原因，取自解释器抛出的 close reason：
+     * `close-button`（点 ×）/ `mask`（点遮罩）/ `countdown-end`（倒计时归零自动关）/
+     * `action`（配置里 close 动作未写 reason 的默认值）/ 运营自定义值。
+     */
+    reason?: string;
+    /** 关闭事件无点击附加信息 */
+    extra?: never;
+}
+/** 点击上报入参：必须带 extra 说明点了什么 */
+interface MarketingClickReportParams {
+    /** 物料 id */
+    id: string;
+    /** 事件类型 */
+    event: 'click';
+    /** 点击事件不写关闭原因 */
+    reason?: never;
+    /** 点击详情，见 {@link MarketingClickExtra} */
+    extra: MarketingClickExtra;
+}
+/**
+ * 上报物料事件的入参（可辨识联合，按 `event` 区分）
+ *
+ * 用联合而非「三个可选字段」是为了把契约写进类型里：`reason` 只配 `close`、
+ * `extra` 只配 `click`，写错直接编译不过。不该出现的字段声明成 `?: never`
+ * 而不是省略，这样消费方（formatter / 上报层 / 调试台预览）仍能直接读
+ * `params.reason`、`params.extra`，无需先做类型窄化 —— 约束留在调用侧，消费侧照旧好写。
+ */
+type MarketingReportParams = MarketingExposureReportParams | MarketingCloseReportParams | MarketingClickReportParams;
+
+/**
+ * 「DSL 运行时事件 → 上报载荷」的映射（纯函数，无副作用、无框架依赖）。
+ *
+ * 前台坑位组件与后台调试台的「上报预览」共用这一份：
+ * 调试台要展示的就是**真实会发给后端的 JSON**，映射有第二份实现，
+ * 前台改了口径而调试台忘了改，调试台就会骗人。
+ */
+
+/**
+ * 会产生上报的运行时事件及其载荷。
+ *
+ * 字段一律可选：宿主（Vue 组件的 `$event`、调试台的手工构造）拿到的载荷未必齐全，
+ * 缺字段是允许的，不该在映射这一步炸掉。
+ */
+interface MarketingReportableEventPayloads {
+    /** 埋点动作：`event` 是运营配的埋点名，`params` 是自定义参数 */
+    track: {
+        event?: string;
+        params?: Record<string, unknown>;
+    };
+    /** 跳转动作：`url` 是目标地址（跳转本身由渲染壳完成，这里只记一笔） */
+    navigate: {
+        url?: string;
+        target?: string;
+    };
+    /** 关闭：`reason` 是关闭原因 */
+    close: {
+        reason?: string;
+    };
+}
+/** 会产生上报的运行时事件名 */
+type MarketingReportableEventName = keyof MarketingReportableEventPayloads;
+/**
+ * 事件名 → 载荷类型。
+ *
+ * 不产生上报的事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）
+ * 载荷为 `unknown`：调用方照常传，映射返回 `null`。
+ */
+type MarketingRuntimeEventPayload<K extends RuntimeEventName> = K extends MarketingReportableEventName ? MarketingReportableEventPayloads[K] : unknown;
+/**
+ * 曝光上报载荷。
+ *
+ * 单独一个函数是因为曝光**不由运行时事件触发** —— 它是宿主把物料渲染到页面上时主动发的，
+ * 解释器根本不知道自己被画出来了。
+ *
+ * @param id 物料 id，为空（未取到物料）时返回 `null`，不产生上报
+ * @returns 上报载荷，或 `null`
+ */
+declare function buildExposureReport(id: string | undefined | null): MarketingExposureReportParams | null;
+/**
+ * 把一个 DSL 运行时事件映射成上报载荷。
+ *
+ * 口径（与 `docs/marketing/README.md` 的契约一一对应）：
+ * - `track` → `click`，`extra = { trigger: 'track', name, params }`
+ * - `navigate` → `click`，`extra = { trigger: 'navigate', url }`
+ * - `close` → `close`，带 `reason`
+ * - 其余事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）不产生上报
+ *
+ * @param id 物料 id，为空时返回 `null`（拿不到 id 的上报对后端没有意义）
+ * @param event 运行时事件名
+ * @param payload 事件载荷，可缺省
+ * @returns 上报载荷，或 `null`（该事件不产生上报）
+ */
+declare function mapRuntimeEventToReport<K extends RuntimeEventName>(id: string | undefined | null, event: K, payload?: MarketingRuntimeEventPayload<K>): MarketingReportParams | null;
+
+export { type MarketingClickExtra, type MarketingClickReportParams, type MarketingCloseReportParams, type MarketingExposureReportParams, type MarketingReportEvent, type MarketingReportParams, type MarketingReportableEventName, type MarketingReportableEventPayloads, type MarketingRuntimeEventPayload, buildExposureReport, mapRuntimeEventToReport };

package/dist/report/index.js

@@ -0,0 +1,38 @@
+// src/report/map.ts
+function buildExposureReport(id) {
+  if (!id) return null;
+  return { id, event: "exposure" };
+}
+function mapRuntimeEventToReport(id, event, payload) {
+  if (!id) return null;
+  switch (event) {
+    case "track": {
+      const data = payload != null ? payload : {};
+      return {
+        id,
+        event: "click",
+        extra: { trigger: "track", name: data.event, params: data.params }
+      };
+    }
+    case "navigate": {
+      const data = payload != null ? payload : {};
+      return {
+        id,
+        event: "click",
+        extra: { trigger: "navigate", url: data.url }
+      };
+    }
+    case "close": {
+      const data = payload != null ? payload : {};
+      return {
+        id,
+        event: "close",
+        reason: data.reason
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+export { buildExposureReport, mapRuntimeEventToReport };

package/docs/package.json

@@ -0,0 +1,7 @@
+{
+  "//": "webpack 4 兼容垫片。它用的 enhanced-resolve 4 不认 package.json 的 exports 字段，会把 `@yaoxiu/marketing-dsl/docs` 当成物理路径去找。这个目录就是那个物理路径，靠 main/module/types 把它转发到真正的产物上。消费方（后台 moveback-front）因此可以照常写 `@yaoxiu/marketing-dsl/docs`，不必伸进 dist 里做深路径引入。webpack 5 / Vite / Node 走的仍是根 package.json 的 exports，不经过这里。删掉它之前先确认没有 webpack 4 的消费方。",
+  "main": "../dist/docs/index.cjs",
+  "module": "../dist/docs/index.js",
+  "types": "../dist/docs/index.d.ts",
+  "sideEffects": false
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaoxiu/marketing-dsl",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "description": "营销弹窗 DSL 解释器核心，纯逻辑无框架依赖",
   "license": "MIT",
@@ -21,10 +21,17 @@
       "types": "./dist/docs/index.d.ts",
       "import": "./dist/docs/index.js",
       "require": "./dist/docs/index.cjs"
+    },
+    "./report": {
+      "types": "./dist/report/index.d.ts",
+      "import": "./dist/report/index.js",
+      "require": "./dist/report/index.cjs"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "report"
   ],
   "dependencies": {},
   "devDependencies": {},

package/report/package.json

@@ -0,0 +1,7 @@
+{
+  "//": "webpack 4 兼容垫片。它用的 enhanced-resolve 4 不认 package.json 的 exports 字段，会把 `@yaoxiu/marketing-dsl/report` 当成物理路径去找。这个目录就是那个物理路径，靠 main/module/types 把它转发到真正的产物上。消费方（后台 moveback-front 的调试台「上报预览」）因此可以照常写 `@yaoxiu/marketing-dsl/report`，不必伸进 dist 里做深路径引入。webpack 5 / Vite / Node 走的仍是根 package.json 的 exports，不经过这里。删掉它之前先确认没有 webpack 4 的消费方。",
+  "main": "../dist/report/index.cjs",
+  "module": "../dist/report/index.js",
+  "types": "../dist/report/index.d.ts",
+  "sideEffects": false
+}