@yaoxiu/marketing-dsl 1.5.2 → 2.0.0

package/README.md

@@ -38,6 +38,36 @@ if (!result.valid) {
 // warnings 不阻断保存，但该提示运营，比如样式属性不在白名单里会被忽略
 ```
 
+#### 可选：校验 `{{ user.xxx }}` 用到的字段
+
+`validate` 的第二个参数是可选项，**不传时行为完全不变**。传了 `userFields` 就会检查配置里
+所有插值位置引用的 `user` 字段是否在白名单内，不在的报 **error**（附最接近的候选字段名）。
+
+```ts
+import { validate, DEFAULT_USER_FIELDS } from '@yaoxiu/marketing-dsl';
+
+const result = validate(dsl, { userFields: DEFAULT_USER_FIELDS });
+// { path: 'nodes[0].content',
+//   message: '用户信息里没有 "user.remainDay" 这个字段，是不是想写 "user.remainDays"？…' }
+```
+
+`user` 是宿主注入的登录用户信息对象，运营写错字段名（`user.expireDays` 而不是
+`user.remainDays`）运行时只会求值为空——页面上就是一处空白、倒计时归零，投到线上才发现。
+所以保存时拦一道。
+
+`DEFAULT_USER_FIELDS` 是各平台通用的那套用户字段：
+
+`shopId` / `shopName` / `collectCount` / `albbCollectCount` / `isNewUser` / `levelId` /
+`levelName` / `serviceExpireTime` / `remainDays` / `userTypeNew` / `serviceInfo`
+
+刻意排除 `sourceData`（后端原始响应整包，结构随平台漂移）和 `mcToken`（令牌，不该出现在
+运营配置里）。字段的中文说明在 `USER_FIELD_LABELS`，编辑器做提示可以直接用。
+只想单独跑这一项检查时用 `validateUserFields(dsl, fields)`。
+
+检查覆盖**全部字符串值**里的 `{{ }}`（文案 `content`、`to`、`src`、`style` 的每个值、
+动作的 `params` …），以及 `visibleWhen` 这种整串就是表达式的字段——
+正向列举「哪些字段能写插值」必漏，所以是反过来做的。
+
 #### 埋点事件名（`track` 动作的 `event`）有格式要求
 
 ```
@@ -95,8 +125,8 @@ unsubscribe();
 ```ts
 {
   ready: true,          // 数据源没回来时是 false，什么都别画
-  hasPopup: true,
-  rootStyle: { ... },
+  hasPopup: true,      // 当前视图栈里有弹窗（不是「配置里有弹窗视图」）
+  rootStyle: { ... },  // 恒 relative；弹窗铺满视口由 layerStyle 的 fixed 负责
   layers: [{
     name: 'main',
     isTop: true,
@@ -122,6 +152,46 @@ unsubscribe();
 
 父子都可点是常见排版——公告条整条点开弹窗、行末 × 关闭公告条——不阻止的话点 × 会连带触发外层，关掉的瞬间又弹出来。没有 `onClick` 的节点不要绑任何事件，让它正常冒泡到有 `onClick` 的祖先。
 
+## 运行时事件（`emit`）
+
+| 事件           | 何时抛                                       | 宿主拿它干嘛                            |
+| -------------- | -------------------------------------------- | --------------------------------------- |
+| `ready`        | 数据源全部返回                               | 知道可以画了                            |
+| `interaction`  | **一次手势 / 一个时机一条**，见下            | **上报**（曝光 / 点击 / 关闭只认它）    |
+| `track`        | 每执行一个 `track` 动作                      | 接自有埋点系统                          |
+| `navigate`     | 每执行一个 `navigate` 动作                   | 想自己接管跳转时用（core 默认已经跳了） |
+| `close`        | 物料整体关闭（点 × / 遮罩 / 倒计时 / close） | 把组件从页面上移除，并上报一条 `close`  |
+| `call`         | 每执行一个 `call` 动作                       | 宿主自己注册的方法已被调用              |
+| `open`         | 打开另一个视图                               | 调试用                                  |
+| `view-change`  | 视图栈变化                                   | 调试用                                  |
+| `state-change` | `setState` 改了状态                          | 调试用                                  |
+| `error`        | 非法 URL / 未注册数据源或方法 / 未知动作     | 排查配置问题                            |
+
+### `interaction`：动作粒度之外再来一条交互粒度
+
+`track` / `navigate` 是**动作**粒度：一次点击里配 `sequence: [track, navigate]`（先埋点再跳转）
+是标准写法，按动作上报会把点击量翻倍；`track` 还能挂在 `stage.onShow` / `onClose` 上，
+动作粒度看不出时机，一律算成点击就把曝光和关闭也计进了点击。
+
+所以在**交互**粒度上再抛一条汇总事件，一次手势 / 一个时机只有一条：
+
+```ts
+interface DslInteractionEvent {
+  trigger: 'show' | 'close' | 'action'; // 触发时机
+  reason?: string; // 仅 trigger='close'
+  track?: { event: string; params?: Record<string, unknown> }; // 多个时取第一个
+  navigate?: { url: string; target?: string }; // 多个时取第一个
+}
+```
+
+- `stage.onShow` 触发 → `{ trigger: 'show', ... }`
+- `stage.onClose` 触发 → `{ trigger: 'close', reason, ... }`
+- 点了带 `action` 的节点（含关闭按钮、tab、倒计时 `onEnd`）→ `{ trigger: 'action', ... }`
+- 没配动作的时机不抛（不制造空事件）
+
+`interaction` 是**新增**的，既有事件语义一个都没变 —— 宿主该用 `navigate` 接管跳转、
+用 `track` 接自有埋点系统的，照旧。上报侧只订 `interaction`，见下方「上报契约」。
+
 ## 安全边界
 
 这几条是设计红线，不会因为「就差一点点」而放开：
@@ -161,7 +231,8 @@ unsubscribe();
 ```
 
 上报出去就是 `{ "id": "...", "event": "close", "reason": "user-dismiss" }`，后端看到这个 `reason`
-就永久压制这条物料。注意这个信息走 **`close` 的 `reason`**，不走 `extra`——`extra` 只属于 `click`。
+就永久压制这条物料。注意这个信息走 **`close` 的 `reason`**，不是点击详情 —— 带 `trigger` 的
+点击 `extra` 只属于 `click`。
 
 ## 完整 DSL 语法
 
@@ -198,27 +269,59 @@ buildAiPrompt(); // 生成喂给 AI 的提示词
 import {
   mapRuntimeEventToReport,
   buildExposureReport,
+  buildCloseReport,
+  pickInteractionTrack,
 } from '@yaoxiu/marketing-dsl/report';
 import type { MarketingReportParams } from '@yaoxiu/marketing-dsl/report';
 
-// 宿主把物料画到页面上时主动发（曝光不由运行时事件触发，解释器不知道自己被画出来了）
+// 点击：只认 interaction，且只认 trigger='action'
+mapRuntimeEventToReport(materialId, 'interaction', {
+  trigger: 'action',
+  track: { event: 'banner_renew_click', params: { pos: 1 } },
+  navigate: { url: 'https://a.com/renew' },
+});
+// → { id, event: 'click',
+//     extra: { trigger: 'track', name: 'banner_renew_click', params: { pos: 1 },
+//              url: 'https://a.com/renew' } }
+
+// 曝光 / 关闭由宿主主动发（解释器不知道自己被画出来了，也不该替宿主决定关不关）
 buildExposureReport(materialId); // → { id, event: 'exposure' }
+buildCloseReport(materialId, { reason: 'mask' }); // → { id, event: 'close', reason: 'mask' }
 
-// 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 都不上报）
+// 运营配在 stage.onShow / onClose 里的埋点名并进这两条，不另算点击
+buildExposureReport(materialId, pickInteractionTrack(showInteraction));
+// → { id, event: 'exposure', extra: { name: 'popup_show', params: {...} } }
+
+// 动作粒度的事件一律不上报（按它们上报会重复计数）
+mapRuntimeEventToReport(materialId, 'track', payload); // → null
+mapRuntimeEventToReport(materialId, 'navigate', payload); // → null
+mapRuntimeEventToReport(materialId, 'close', payload); // → null
 ```
 
-上报载荷 `MarketingReportParams` 是**可辨识联合**：`reason` 只属于 `close`、`extra` 只属于 `click`，
-写错编译不过；不该出现的字段声明成 `?: never` 而非省略，消费方仍可直接读，不必先窄化。
+### 为什么上报只认 `interaction`
+
+按动作粒度上报会**放大点击量**，实测一个弹窗的完整生命周期（1 曝光 + 1 点击 + 1 关闭）能报出 6 条：
+
+| 重复来源                      | 原因                                |
+| ----------------------------- | ----------------------------------- |
+| `stage.onShow` 里的 `track`   | 那是曝光埋点，被算成了点击          |
+| `sequence: [track, navigate]` | 一次点击、两个动作，各报一条 → 翻倍 |
+| `stage.onClose` 里的 `track`  | 那是关闭埋点，也被算成了点击        |
+
+所以口径改成：**一次手势 = 一条 `interaction` = 至多一条上报**。
+
+| interaction.trigger | 上报                | 运营配的埋点名去哪                           |
+| ------------------- | ------------------- | -------------------------------------------- |
+| `action`            | 一条 `click`        | `extra.name`（同时有跳转则并上 `extra.url`） |
+| `show`              | 不产生（返回 null） | 由宿主并进 `exposure` 的 `extra.name`        |
+| `close`             | 不产生（返回 null） | 由宿主并进 `close` 的 `extra.name`           |
+
+`action` 里既没埋点也没跳转（比如纯 `close` / `setState`）时同样不产生上报。
+
+上报载荷 `MarketingReportParams` 是**可辨识联合**：`reason` 只属于 `close`、
+点击详情（带 `trigger` 的 `extra`）只属于 `click`，写错编译不过；`exposure` / `close` 的 `extra`
+是另一种形态（只有 `name` / `params`），装的就是上表里那些埋点名。
+不该出现的字段声明成 `?: never` 而非省略，消费方仍可直接读，不必先窄化。
 
 **给谁用**：接了后端上报的宿主（前台坑位组件），以及调试台的「上报预览」——
 预览要展示的就是真实会发给后端的 JSON，映射再写第二份，前台改了口径而调试台没跟上，预览就会骗人。

package/dist/{chunk-FKZKLCVV.js → chunk-BSJDNS6C.js}

@@ -527,6 +527,120 @@ function resolveNodeStyle(node, layout) {
   );
 }
 
+// src/user-fields.ts
+var DEFAULT_USER_FIELDS = [
+  "shopId",
+  "shopName",
+  "collectCount",
+  "albbCollectCount",
+  "isNewUser",
+  "levelId",
+  "levelName",
+  "serviceExpireTime",
+  "remainDays",
+  "userTypeNew",
+  "serviceInfo"
+];
+var USER_FIELD_LABELS = {
+  shopId: "\u5E97\u94FA ID",
+  shopName: "\u5E97\u94FA\u540D\u79F0",
+  collectCount: "\u5269\u4F59\u91C7\u96C6\u6B21\u6570",
+  albbCollectCount: "\u5269\u4F59 1688 \u91C7\u96C6\u6B21\u6570",
+  isNewUser: "\u662F\u5426\u65B0\u7528\u6237\uFF080 / 1\uFF0C\u53EF\u76F4\u63A5\u7528\u4E8E visibleWhen\uFF09",
+  levelId: "\u7248\u672C ID",
+  levelName: "\u7248\u672C\u540D\u79F0\uFF0C\u5982\u300C\u4E13\u4E1A\u7248\u300D",
+  serviceExpireTime: "\u670D\u52A1\u5230\u671F\u65F6\u95F4\uFF0C\u53EF\u76F4\u63A5\u5582\u7ED9 countdown \u7684 to",
+  remainDays: "\u670D\u52A1\u5269\u4F59\u5929\u6570",
+  userTypeNew: "\u65B0\u5546\u7528\u6237\u7C7B\u578B\uFF080 \u672A\u8BBE\u7F6E / 1 \u6709\u8D27\u6E90 / 2 \u65E0\u8D27\u6E90 / 3 \u4E24\u8005\u517C\u5907\uFF09",
+  serviceInfo: "\u5BA2\u670D\u4E0E\u793E\u7FA4\u4FE1\u606F\uFF08\u5BF9\u8C61\uFF0C\u6309\u9700\u53D6\u5B50\u5B57\u6BB5\uFF09"
+};
+var USER_FIELD_RE = /\buser\s*\.\s*([A-Za-z_$][A-Za-z0-9_$]*)/g;
+var INTERPOLATION_RE2 = /\{\{([\s\S]*?)\}\}/g;
+var RAW_EXPRESSION_KEYS = ["visibleWhen"];
+function editDistance(a, b) {
+  const prev = [];
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    let diagonal = prev[0];
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const temp = prev[j];
+      prev[j] = Math.min(
+        prev[j] + 1,
+        prev[j - 1] + 1,
+        diagonal + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+      diagonal = temp;
+    }
+  }
+  return prev[b.length];
+}
+function closestField(name, allowed) {
+  const lower = name.toLowerCase();
+  let best = "";
+  let bestScore = Infinity;
+  allowed.forEach((field) => {
+    const score = editDistance(lower, field.toLowerCase());
+    if (score < bestScore) {
+      bestScore = score;
+      best = field;
+    }
+  });
+  return bestScore <= Math.max(3, Math.ceil(name.length / 2)) ? best : "";
+}
+function collectFromExpression(source, into) {
+  USER_FIELD_RE.lastIndex = 0;
+  let matched = USER_FIELD_RE.exec(source);
+  while (matched) {
+    into.push(matched[1]);
+    matched = USER_FIELD_RE.exec(source);
+  }
+}
+function collectFromValue(value, key, into) {
+  if (RAW_EXPRESSION_KEYS.indexOf(key) > -1) {
+    collectFromExpression(value, into);
+    return;
+  }
+  INTERPOLATION_RE2.lastIndex = 0;
+  let matched = INTERPOLATION_RE2.exec(value);
+  while (matched) {
+    collectFromExpression(matched[1], into);
+    matched = INTERPOLATION_RE2.exec(value);
+  }
+}
+function validateUserFields(dsl, allowed) {
+  const issues = [];
+  const seen = [];
+  const walk = (node, path, key) => {
+    if (typeof node === "string") {
+      const names = [];
+      collectFromValue(node, key, names);
+      names.forEach((name) => {
+        if (allowed.indexOf(name) > -1) return;
+        const guess = closestField(name, allowed);
+        issues.push({
+          path,
+          message: `\u7528\u6237\u4FE1\u606F\u91CC\u6CA1\u6709 "user.${name}" \u8FD9\u4E2A\u5B57\u6BB5` + (guess ? `\uFF0C\u662F\u4E0D\u662F\u60F3\u5199 "user.${guess}"\uFF1F` : "") + `\u3002\u53EF\u7528\u5B57\u6BB5\uFF1A${allowed.join(" / ")}`
+        });
+      });
+      return;
+    }
+    if (!node || typeof node !== "object") return;
+    if (seen.indexOf(node) > -1) return;
+    seen.push(node);
+    if (Array.isArray(node)) {
+      node.forEach((item, index) => walk(item, `${path}[${index}]`, key));
+      return;
+    }
+    Object.keys(node).forEach((childKey) => {
+      const childPath = path ? `${path}.${childKey}` : childKey;
+      walk(node[childKey], childPath, childKey);
+    });
+  };
+  walk(dsl, "", "");
+  return issues;
+}
+
 // src/validate.ts
 var LENGTH_STYLE_KEYS = [
   "width",
@@ -578,7 +692,7 @@ var CLOSE_POSITIONS = [
   "bottom-center"
 ];
 var CONTAINER_TYPES = ["box", "flex"];
-function validate(dsl) {
+function validate(dsl, options) {
   const errors = [];
   const warnings = [];
   const add = (path, message) => errors.push({ path, message });
@@ -608,6 +722,11 @@ function validate(dsl) {
   viewNames.forEach((name) => {
     validateView(views[name], isMulti ? `views.${name}` : "", ctx);
   });
+  if (options && options.userFields) {
+    validateUserFields(doc, options.userFields).forEach(
+      (issue) => add(issue.path, issue.message)
+    );
+  }
   return { valid: errors.length === 0, errors, warnings };
 }
 function validateMultiView(dsl, add) {
@@ -965,4 +1084,4 @@ function formatIssues(issues) {
   return issues.map((item) => item.path ? `${item.path}: ${item.message}` : item.message).join("\n");
 }
 
-export { ACTION_TYPES, ALLOWED_STYLE_KEYS, CLOSE_POSITIONS, DSL_VERSION, NODE_TYPES, SINGLE_VIEW_NAME, TRACK_EVENT_PATTERN, check, computeParts, createTicker, evaluate, formatIssues, formatParts, interpolate, interpolateDeep, isLength, isValidEndTime, normalizeViews, parseEndTime, resolveNodeStyle, toCssStyle, toLength, validate };
+export { ACTION_TYPES, ALLOWED_STYLE_KEYS, CLOSE_POSITIONS, DEFAULT_USER_FIELDS, DSL_VERSION, NODE_TYPES, SINGLE_VIEW_NAME, TRACK_EVENT_PATTERN, USER_FIELD_LABELS, check, computeParts, createTicker, evaluate, formatIssues, formatParts, interpolate, interpolateDeep, isLength, isValidEndTime, normalizeViews, parseEndTime, resolveNodeStyle, toCssStyle, toLength, validate, validateUserFields };