@yaoxiu/marketing-dsl 1.2.0 → 1.4.0

package/README.md

@@ -38,6 +38,26 @@ if (!result.valid) {
 // warnings 不阻断保存，但该提示运营，比如样式属性不在白名单里会被忽略
 ```
 
+#### 埋点事件名（`track` 动作的 `event`）有格式要求
+
+```
+^[a-z][a-z0-9_]{2,63}$
+```
+
+小写字母开头，之后只能是小写字母、数字、下划线，总长 3~64 个字符。
+不合规是 **error，直接阻断保存**（导出为 `TRACK_EVENT_PATTERN`，编辑器可复用同一份正则做即时提示）。
+
+| ✅ 正确              | ❌ 错误              | 为什么                     |
+| -------------------- | -------------------- | -------------------------- |
+| `banner_renew_click` | `续费点击`           | 不能用中文                 |
+| `popup_show`         | `bannerRenewClick`   | 不能用驼峰 / 大写字母      |
+| `countdown_end`      | `banner-renew-click` | 不能用中划线（下划线分词） |
+| `cta_click_v2`       | `cta`（不足 3 字符） | 太短，聚合时看不出是什么   |
+
+建议命名：`坑位_业务_动作`，如 `popup_vip_renew_click`。**不做白名单**——事件名由运营自由定义，
+只统一格式；后端按前缀聚合，格式乱了就没法分组。这个名字最终会作为 `extra.name` 上报
+（见 platform-adapters 的 `base-service/marketing/README.md`「上报字段契约」）。
+
 ### 2. 渲染
 
 一般不直接用，交给框架壳。自己接的话是这样：
@@ -84,7 +104,9 @@ unsubscribe();
     onMaskClick: fn,
     layerStyle: {...}, maskStyle: {...}, scrollStyle: {...},
     stageStyle: {...}, clipStyle: {...},
-    closeButton: { key, tag, style, onClick, text },
+    // 默认图标是内联 SVG 画的两条交叉线（'×' 字符的字形偏下，肉眼可见）；
+    // 运营配了 icon 走 text，配了 image 走 img
+    closeButton: { key, tag, style, onClick, children },
     nodes: [{ key: 'main-0', tag: 'div', style: {...}, onClick: fn, children: [...] }],
   }],
   countdownEndTimes: [], // 有倒计时时运行时会自己起定时器
@@ -116,3 +138,23 @@ unsubscribe();
 ## 完整 DSL 语法
 
 见调试台的「开发文档」页，或从那里导出 markdown / AI 提示词。
+
+文档正文本身也在这个包里，走**子路径**引入——正文有几十 KB，业务侧只用运行时，
+不该背这份体积，所以它不在主入口：
+
+```ts
+import {
+  sections,
+  meta,
+  examples,
+  toMarkdown,
+  buildAiPrompt,
+} from '@yaoxiu/marketing-dsl/docs';
+
+toMarkdown(sections, meta); // 导出 .md
+buildAiPrompt(); // 生成喂给 AI 的提示词
+```
+
+章节正文是**数据**（`DocBlock` 数组）不是字符串：调试台按块渲染成页面，`toMarkdown` 导出成 markdown，
+同一份内容两边永远一致。节点类型 / 动作 / 样式白名单 / 埋点事件名正则等清单一律从解释器常量取，
+并经 `reconcileRows` 对账——解释器加了东西而文档没跟上，会在文档页面上直接标出来。