@thinkingai/ae-cli 1.0.28 → 6.0.16

package/skills/ae-generate-tracking-plan/references/business-dimension-mapping.md

@@ -0,0 +1,425 @@
+# Business Dimension → Event/Property Mapping Table
+
+> **Terminology**: 业务维度 = business dimension | 收入模型 = revenue model | 核心循环 = core gameplay loop | 功能入口 = functional entry | 货币体系 = currency system | 注入事件 = injected events | 事件显示名 = event display name | 必带属性 = required properties | IAA = In-App Advertising (ad monetization) | IAP = In-App Purchase | 硬货币 = hard currency (premium, e.g. diamonds) | 软货币 = soft currency (earnable, e.g. gold) | 广告场景 = ad scene | 内购物品 = IAP item | platform = client / server / both
+
+> Used during Phase 1 Draft generation to auto-inject corresponding events and properties based on
+> business dimension information collected in Phase 0.
+> This file is an internal reference for the skill; Claude reads it when generating the draft.
+
+---
+
+## 一、Revenue Model → Required Events
+
+| 收入模型 | 注入事件 | 事件显示名 | platform | 必带属性 |
+|---|---|---|---|---|
+| `IAA` | `ad_show` | 广告展示 | client | `ad_type`、`ad_placement`、`is_filled` |
+| `IAA` | `ad_click` | 广告点击 | client | `ad_type`、`ad_placement`、`ad_network` |
+| `IAA` | `ad_reward_get` | 激励广告奖励领取 | client | `ad_type`、`ad_placement`、`reward_type`、`reward_amount` |
+| `IAP` | `payment` | 支付成功 | server | `order_id`、`pay_amount`、`currency_type`、`payment_name`、`payment_type` |
+| `IAP` | `payment_fail` | 支付失败 | server | `order_id`、`fail_reason`、`payment_name` |
+| `mixed` | 同 IAA + IAP 所有事件 | | | |
+| `subscription` | `subscription_start` | 订阅开始 | server | `subscription_id`、`plan_name`、`start_time` |
+| `subscription` | `subscription_renew` | 订阅续费 | server | `subscription_id`、`renew_amount`、`currency_type` |
+| `subscription` | `subscription_cancel` | 订阅取消 | server | `subscription_id`、`cancel_time`、`cancel_reason` |
+| `commission` | `order_create` | 订单创建 | server | `order_id`、`order_amount`、`commission_rate` |
+| `commission` | `order_paid` | 订单支付 | server | `order_id`、`pay_amount`、`commission_amount` |
+| `commission` | `commission_settled` | 佣金结算 | server | `settlement_id`、`commission_amount`、`settle_time` |
+
+---
+
+## 二、核心玩法循环 → 事件序列
+
+解析 `core_loop` 描述，提取动作节点，映射为事件。
+
+### 动作动词 → 事件名映射
+
+| 动作动词 | 事件名 | 说明 |
+|---|---|---|
+| 刷/打/通关 | `stage_start` / `stage_complete` / `stage_fail` | 关卡类玩法 |
+| 获得/获取/得到 | `token_get` / `item_get` / `hero_get` | 资源/道具/角色获取 |
+| 消耗/使用/花费 | `token_consume` / `item_consume` | 资源/道具消耗 |
+| 购买/商城 | `shop_open` / `shop_buy` | 商城相关 |
+| 抽卡/召唤/招募 | `gacha_draw` / `recruit_draw` | 随机抽取类玩法 |
+| 战斗/PVP/竞技 | `battle_start` / `battle_end` / `battle_result` | 战斗结算 |
+| 任务/委托 | `task_accept` / `task_complete` | 任务系统 |
+| 升级/提升 | `level_up` / `vip_levelup` | 成长系统 |
+| 注册/登录/登出 | `register` / `login` / `logout` | 生命周期 |
+
+### 示例解析
+
+**输入**："玩家反复刷关卡获得金币，用金币抽卡获取角色"
+
+**解析结果**：
+
+```
+节点1: 刷关卡 → stage_start / stage_complete / stage_fail
+节点2: 获得金币 → token_get (token_type=gold, source=关卡)
+节点3: 抽卡 → gacha_draw (pool_type, draw_count)
+节点4: 获取角色 → hero_get (hero_id, hero_star)
+```
+
+---
+
+## 三、功能入口 → 模块事件组
+
+| 功能入口 | 事件名 | 显示名 | platform | 典型属性 |
+|---|---|---|---|---|
+| 关卡 | `stage_start` | 关卡开始 | client | `stage_id`、`stage_type`、`difficulty` |
+| 关卡 | `stage_complete` | 关卡完成 | server | `stage_id`、`star_rating`、`score` |
+| 关卡 | `stage_fail` | 关卡失败 | server | `stage_id`、`fail_reason` |
+| 抽卡 | `gacha_draw` | 抽卡 | server | `pool_type`、`draw_count`、`cost_amount` |
+| 抽卡 | `hero_get` | 获得英雄 | server | `hero_id`、`hero_star`、`source` |
+| 商城 | `shop_open` | 打开商城 | client | `shop_type` |
+| 商城 | `shop_buy` | 商城购买 | server | `item_id`、`item_num`、`pay_amount`、`token_balance` |
+| 公会 | `guild_join` | 加入公会 | server | `guild_id`、`guild_name` |
+| 公会 | `guild_donate` | 公会捐献 | server | `donate_type`、`donate_amount` |
+| 公会 | `guild_boss_start` | 公会BOSS战开始 | server | `guild_id`、`boss_id` |
+| 排行榜 | `rank_view` | 查看排行榜 | client | `rank_type`、`rank_id` |
+| 排行榜 | `rank_refresh` | 刷新排行 | client | `rank_type` |
+| 排行榜 | `rank_click` | 点击排行项 | client | `rank_type`、`target_id` |
+| 任务 | `task_accept` | 接受任务 | server | `task_id`、`task_type` |
+| 任务 | `task_complete` | 完成任务 | server | `task_id`、`reward_amount` |
+| 任务 | `task_reward_claim` | 领取任务奖励 | server | `task_id`、`reward_type` |
+| 成就 | `achieve_unlock` | 解锁成就 | server | `achieve_id`、`achieve_name` |
+| 成就 | `achieve_reward_claim` | 领取成就奖励 | server | `achieve_id`、`reward_amount` |
+| 签到 | `daily_sign` | 每日签到 | server | `sign_day`、`consecutive_days` |
+| 签到 | `sign_reward_claim` | 领取签到奖励 | server | `reward_type`、`reward_amount` |
+
+---
+
+## 四、货币体系 → 属性设计
+
+### 货币类型枚举
+
+| token_type | 显示名 | 说明 |
+|---|---|---|
+| `diamond` | 钻石 | 硬货币（付费） |
+| `gold` | 金币 | 软货币（免费） |
+| `energy` | 体力 | 限流资源 |
+| `power` | 体力/能量 | 通用限流资源 |
+| `alliance_point` | 联盟积分 | 公会货币 |
+| `honor` | 荣誉 | 竞技货币 |
+| `star_point` | 星芒 | 赛季货币 |
+
+### 货币相关事件
+
+| 事件名 | 显示名 | 使用场景 |
+|---|---|---|
+| `token_get` | 获得货币 | 任何获得虚拟货币的场景 |
+| `token_consume` | 消耗货币 | 任何消耗虚拟货币的场景 |
+
+### 货币事件属性
+
+```json
+// token_get / token_consume 通用属性
+{
+  "token_type": "diamond",    // 货币类型（枚举见上）
+  "token_amount": 100,        // 本次变动数量
+  "token_balance": 5000,      // 变动后余额
+  "source": "关卡奖励",        // 来源（仅 token_get）
+  "consume_type": "抽卡"      // 消耗用途（仅 token_consume）
+}
+```
+
+---
+
+## 五、事件 platform 判定规则
+
+> **使用场景**：注入标准事件（一～四章）之外的自定义事件时，按本表判定 platform；或在 Phase 1.3 Step 3 注入前用于校验注入事件的 platform 是否合理。
+
+| 事件类型 | platform |
+|---|---|
+| 用户 UI 交互（点击/浏览/打开页面） | `client` |
+| 客户端状态变化（关卡开始/结束） | `client` |
+| 资源/货币变动（获取/消耗） | `server` |
+| 支付相关（支付/充值） | `server` |
+| 业务数据落库（订单/任务完成/成就解锁） | `server` |
+| 需要服务端验证（防刷/校验） | `server` |
+| 两端均需（登录/登出） | `both` |
+| SDK 自动采集事件 | `client` |
+
+---
+
+## 六、广告场景详细配置
+
+### 广告类型枚举
+
+| ad_type | 显示名 |
+|---|---|
+| `rewarded` | 激励视频 |
+| `interstitial` | 插屏广告 |
+| `banner` | 横幅广告 |
+| `splash` | 开屏广告 |
+| `native` | 原生广告 |
+
+### IAA 模式自动注入事件
+
+```json
+[
+  {
+    "event_name": "ad_show",
+    "display_name": "广告展示",
+    "platform": "client",
+    "event_tag": "广告",
+    "prop_names": ["ad_type", "ad_placement", "ad_network", "is_filled", "ecpm"],
+    "source": "business_dimension"
+  },
+  {
+    "event_name": "ad_click",
+    "display_name": "广告点击",
+    "platform": "client",
+    "event_tag": "广告",
+    "prop_names": ["ad_type", "ad_placement", "ad_network"],
+    "source": "business_dimension"
+  },
+  {
+    "event_name": "ad_reward_get",
+    "display_name": "激励广告奖励领取",
+    "platform": "client",
+    "event_tag": "广告",
+    "prop_names": ["ad_type", "ad_placement", "reward_type", "reward_amount"],
+    "source": "business_dimension"
+  }
+]
+```
+
+---
+
+## 七、用户属性补充建议（按收入模型）
+
+| 收入模型 | 建议添加的用户属性 |
+|---|---|
+| IAA | `total_ad_watch_count`（累计看广告次数）、`total_ad_revenue`（累计广告收入，单位：美分） |
+| IAP | `total_pay_amount`（累计付费金额）、`first_pay_time`（首次付费时间）、`last_pay_time`（最近付费时间） |
+| `subscription` | `subscription_status`（订阅状态）、`subscription_plan`（订阅计划）、`subscription_expire_time`（订阅到期时间） |
+| `mixed` | 以上都要 |
+
+---
+
+## 八、品类专用事件模块
+
+> 根据应用类型/游戏品类，自动注入对应模块的事件组。
+> 品类由 Phase 0 的 `meta.scenario` 或用户描述推断。
+
+### 8.1 游戏类 — 通用基础模块（所有游戏必选）
+
+**用户生命周期**：
+
+| 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|
+| `new_device` | 设备激活 | client | `channel` |
+| `register` | 用户注册 | server | `register_type` |
+| `login` | 用户登录 | both | `account_id` |
+| `logout` | 用户登出 | both | `session_duration` |
+
+**成长模块**：
+
+| 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|
+| `create_role` | 创建角色 | server | `role_id`、`role_name`、`server_id` |
+| `guide_complete` | 完成新手引导 | client | `guide_id`、`guide_step` |
+| `level_up` | 升级 | server | `level`、`level_before` |
+| `vip_levelup` | VIP升级 | server | `vip_level` |
+
+### 8.2 游戏类 — 按品类
+
+#### 8.2.1 卡牌/RPG/放置/Roguelike
+
+| 模块 | 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|---|
+| 战斗 | `battle_start` | 战斗开始 | client | `battle_type`、`hero_info` |
+| 战斗 | `battle_end` | 战斗结束 | server | `battle_type`、`battle_result`、`hero_info` |
+| 战斗 | `mopping_up` | 扫荡 | server | `stage_id`、`mop_count` |
+| 养成 | `hero_get` | 获得英雄 | server | `hero_id`、`hero_star`、`source` |
+| 养成 | `hero_levelup` | 英雄升级 | server | `hero_id`、`level` |
+| 抽卡 | `gacha_draw` | 抽卡 | server | `pool_type`、`draw_count`、`cost_amount` |
+| 资源 | `token_get` | 获得货币 | server | `token_type`、`token_amount`、`source` |
+| 资源 | `token_consume` | 消耗货币 | server | `token_type`、`token_amount`、`consume_type` |
+| 任务 | `task_complete` | 完成任务 | server | `task_id`、`reward_amount` |
+| 社交 | `guild_join` | 加入公会 | server | `guild_id` |
+
+#### 8.2.2 SLG 策略类
+
+| 模块 | 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|---|
+| 建筑 | `building_build` | 建造建筑 | server | `building_type`、`level` |
+| 建筑 | `building_upgrade` | 升级建筑 | server | `building_id`、`level` |
+| 资源 | `resource_gather_start` | 开始采集 | client | `resource_type` |
+| 资源 | `resource_gather_finish` | 完成采集 | server | `resource_type`、`amount` |
+| 战斗 | `battle_start` | 战斗开始 | client | `battle_type`、`troop_info` |
+| 战斗 | `battle_result` | 战斗结果 | server | `battle_type`、`result`、`damage` |
+| 联盟 | `alliance_create` | 创建联盟 | server | `alliance_id`、`alliance_name` |
+| 联盟 | `alliance_join` | 加入联盟 | server | `alliance_id` |
+
+#### 8.2.3 MMO
+
+| 模块 | 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|---|
+| 副本 | `dungeon_enter` | 进入副本 | client | `dungeon_type`、`difficulty` |
+| 副本 | `dungeon_complete` | 完成副本 | server | `dungeon_type`、`result` |
+| 装备 | `equip_forge` | 装备打造 | server | `equip_type`、`cost` |
+| 交易 | `trade_sell` | 挂售物品 | server | `item_id`、`price` |
+| 交易 | `trade_buy` | 购买物品 | server | `item_id`、`price` |
+
+#### 8.2.4 休闲/超休闲/Slots
+
+| 模块 | 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|---|
+| 关卡 | `level_start` | 关卡开始 | client | `level_id` |
+| 关卡 | `level_win` | 关卡胜利 | server | `level_id`、`score` |
+| 关卡 | `level_fail` | 关卡失败 | server | `level_id`、`fail_reason` |
+| 关卡 | `level_restart` | 重新开始 | client | `level_id` |
+| 复活 | `revive_show` | 复活弹窗展示 | client | `level_id` |
+| 复活 | `revive_use` | 使用复活 | client | `ad_type`、`level_id` |
+| Slots | `spin_start` | 老虎机开始 | client | `bet_amount` |
+| Slots | `spin_result` | 老虎机结果 | server | `win_amount`、`is_big_win` |
+
+#### 8.2.5 短剧/内容类产品
+
+| 模块 | 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|---|
+| 内容播放 | `playlet_start` | 短剧开始 | client | `playlet_id`、`episode` |
+| 内容播放 | `playlet_end` | 短剧结束 | server | `playlet_id`、`duration` |
+| 广告 | `reward_ad_show` | 激励广告展示 | client | `ad_placement`、`ecpm` |
+| 奖励 | `coin_get` | 获得代币 | server | `coin_amount`、`source` |
+| 抽奖 | `lottery_draw` | 抽奖 | server | `lottery_type`、`prize` |
+| 提现 | `withdraw_apply` | 申请提现 | server | `amount` |
+
+### 8.3 非游戏类
+
+#### 8.3.1 电商
+
+| 模块 | 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|---|
+| 发现 | `home_feed_expose` | 首页推荐曝光 | client | `feed_type` |
+| 发现 | `search_submit` | 搜索提交 | client | `keyword` |
+| 商品 | `commodity_detail` | 商品详情页 | client | `commodity_id`、`price` |
+| 商品 | `add_cart` | 加入购物车 | client | `commodity_id`、`quantity` |
+| 订单 | `submit_order` | 提交订单 | server | `order_id`、`total_amount` |
+| 订单 | `pay_order` | 支付订单 | server | `order_id`、`pay_amount` |
+| 售后 | `apply_return` | 申请退货 | server | `order_id`、`reason` |
+
+#### 8.3.2 在线教育
+
+| 模块 | 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|---|
+| 引导 | `consent_privacy_accept` | 隐私授权 | client | - |
+| 课程 | `course_detail_view` | 课程详情页 | client | `course_id` |
+| 课程 | `course_start` | 开始学习 | client | `course_id`、`lesson_id` |
+| 课程 | `video_play_complete` | 视频播放完成 | server | `course_id`、`duration` |
+| 报名 | `enroll_course_free` | 免费报名 | server | `course_id` |
+| 报名 | `payment_success` | 支付成功 | server | `course_id`、`pay_amount` |
+| 测验 | `quiz_submit` | 提交测验 | server | `quiz_id`、`score` |
+
+#### 8.3.3 社交类
+
+| 模块 | 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|---|
+| 内容 | `post_publish` | 发布动态 | server | `content_type` |
+| 互动 | `post_like` | 点赞 | client | `post_id` |
+| 互动 | `post_comment` | 评论 | client | `post_id`、`comment` |
+| 关系 | `follow` | 关注 | client | `target_user_id` |
+| 直播 | `live_gift_send` | 送礼物 | server | `gift_type`、`gift_count` |
+
+#### 8.3.4 工具类（剪辑/视频）
+
+| 模块 | 事件名 | 显示名 | platform | 必带属性 |
+|---|---|---|---|---|
+| 创作 | `project_create` | 创建项目 | client | `project_type` |
+| 创作 | `use_function` | 使用功能 | client | `function_name`、`is_first_use` |
+| 素材 | `watch_video` | 观看视频 | client | `video_id`、`duration` |
+| 导出 | `project_export` | 导出项目 | client | `export_format` |
+
+---
+
+## 九、对象与对象组使用规范
+
+### 核心区分
+
+| 类型 | JSON 结构 | 适用场景 | 关系 |
+|---|---|---|---|
+| `object`（对象） | `{"key":"val"}` | 当前装备、出战英雄、地址信息 | 一对一 |
+| `array_row`（对象组） | `[{"key":"val"}]` | 背包物品、阵容列表、排行榜 | 一对多 |
+
+**简单判断：数据是 `{...}` 用 `object`，是 `[{...}]` 用 `array_row`。**
+
+### 对象（object）使用场景
+
+适用于**单个复合实体**，即一个属性里包含多个子属性，但实体本身只有一个：
+
+| 属性名 | 适用场景 | 典型子属性 |
+|---|---|---|
+| `equip_info` | 当前装备详情 | `equip_id`、`equip_name`、`equip_level`、`equip_quality` |
+| `hero_info` | 当前出战英雄（只有一个时） | `hero_id`、`hero_name`、`hero_level` |
+| `address_info` | 收货地址 | `province`、`city`、`district`、`detail` |
+
+### 对象书写格式
+
+在埋点方案中：
+1. **父属性行**：属性名填 `xxx_info`，类型填 `对象`
+2. **子属性行**：属性名填 `xxx_info.child_name`，类型填子属性实际类型
+3. 必须提供取值样例：`{"item_id":"001","item_num":5}`
+
+### 对象组（array_row）使用场景
+
+适用于**多个同类复合实体**，须满足三条件：
+
+1. 一个事件属性中有多个同类实体需记录（如多艘舰船、多件物品）
+2. 每个实体需记录 ≥2 个属性（否则用 `array_string` 列表即可）
+3. 实体数量不固定（固定为 1 个时用 `object`）
+
+| 对象组名 | 适用场景 | 典型子属性 |
+|---|---|---|
+| `hero_info` / `ship_info` / `fleet_info` | 出战阵容、角色明细 | `id`、`level`、`star`、`power` |
+| `get_item_info` | 获得物品明细 | `item_id`、`item_num` |
+| `cost_item_info` | 消耗物品明细 | `item_id`、`item_num` |
+| `rank_info` | 排行榜信息 | `id`、`rank`、`score` |
+| `hero_info` | 战斗阵容 | `hero_id`、`hero_level`、`troop_type` |
+
+### 对象组书写格式
+
+在埋点方案中：
+1. **父属性行**：属性名填 `xxx_info`，类型填 `对象组`
+2. **子属性行**：属性名填 `xxx_info.child_name`，类型填子属性实际类型
+3. 必须提供取值样例：`[{"item_id":"001","item_num":5}]`
+
+---
+
+## 十、属性类型规范
+
+| 类型 | JSON 类型 | 取值样例 | 适用场景 |
+|---|---|---|---|
+| 文本 | String | `"上海"` | 名称、渠道、ID（非纯数值时） |
+| 数值 | Number | `123`、`1.23` | 金额、等级、时长、纯数值 ID |
+| 布尔 | Boolean | `true`、`false` | 是否首次、是否付费 |
+| 时间 | String | `"2024-01-01 00:00:00"` | 注册时间、首充时间 |
+| 列表 | Array | `["a","1"]` | 标签列表、技能列表 |
+| 对象 | Object | `{"item_name":"碎片","item_num":5}` | 单个复合实体 |
+| 对象组 | Array(Object) | `[{"id":"001","num":5}]` | 多个同类复合实体 |
+
+**ID 类属性类型选择**：
+- ID 先后关系与数值大小正相关（如关卡 ID 1,2,3...）→ 数值
+- ID 含非数值字符或无序 → 文本
+- 不确定时 → 文本（更安全）
+
+---
+
+## 十一、模板事件增删规则
+
+### 保留条件（不可删除）
+
+- SDK 预置事件（`ta_app_*`）
+- 充值流程事件（`init_order`、`payment`、`payment_fail`）
+- 资源经济事件（`token_get`、`token_consume`）
+
+### 新增条件（满足任一即必须新增）
+
+1. **功能入口原则**：产品主界面有独立入口的功能模块，模板未覆盖 → 必须新增
+2. **收入模型原则**：收入模型要求的事件模板未覆盖 → 必须新增（见第一章）
+3. **高频行为原则**：产品研究发现的高频用户行为模板未覆盖 → 建议新增
+
+### 新增事件最低要求
+
+- 必须有 ≥2 个自定义属性
+- 必须标注事件标签（模块归属）和采集端
+- 命名符合 snake_case

package/skills/ae-generate-tracking-plan/references/te-api.md

@@ -0,0 +1,100 @@
+# AE Backend API (internal reference)
+
+> **Terminology**: 认证 = authentication | Token = bearer token from localStorage `ACCESS_TOKEN` | 端点 = endpoint | 抓包 = traffic capture | 埋点方案 = tracking plan | 上传 = upload | 删除 = delete | 查询 = query/fetch
+
+> This file is the implementation basis for `src/client.ts`, maintained for internal contributors.
+> **Skill body should not reference this document** — skill users interact via CLI commands and do not need to know underlying endpoints.
+> xlsx format contract is in `xlsx-schema.md`, not here.
+
+Capture environment: `https://web-ta-demo.thinkingdata.cn`. If endpoints change, re-run the
+chrome-devtools capture flow from `docs/superpowers/plans/2026-04-15-ae-tracking-skill.md` Task 3.
+
+## 认证
+
+### Token
+- localStorage key：`ACCESS_TOKEN`
+- 存储形态：**JSON 编码字符串**（带双引号），使用前须 `replace(/^["']|["']$/g, '')`
+
+### 两种传 token 方式（按端点区分）
+- **GET/JSON 类接口**：Header `authorization: bearer <token>`（全小写）
+- **Excel 上传接口**：**form field `access_token`**，裸 UUID，**不用** Authorization header
+
+## 响应统一包装
+
+```json
+{ "return_code": 0, "return_message": "success", "showStackMessage": false, "data": ... }
+```
+- `return_code === 0` 为成功；非 0 抛错，取 `return_message`
+- 某些端点（如 `excel-save` / 空项目 `query`）成功时无 `data`
+
+## 端点
+
+### 1. GET `/v1/ta/bury/manage/program/query`
+
+获取项目唯一的埋点方案。
+
+- Query：`projectId` 必填 number
+- Header：`authorization: bearer <token>`
+- Response `data` 结构（事件池 / 事件属性池 / 公共属性 / 用户属性）：
+
+```jsonc
+{
+  "projectId": 1603,
+  "events": [
+    { "eventName": "...", "displayName": "...", "eventDesc": "...", "eventTag": "...",
+      "props": ["prop_name", "parent.child"], "propInfosOnEvent": [{"name":"...","hasReported":false}] }
+  ],
+  "eventProps": [ { "name": "...", "displayName": "...", "type": "string", "desc": "..." } ],
+  "commonEventProps": [ /* 同 eventProps */ ],
+  "userProps": [
+    { "name": "...", "displayName": "...", "type": "datetime",
+      "propTag": "时间类", "updateType": "user_setOnce" }
+  ]
+}
+```
+
+空项目：`data` 不存在，直接 `{ return_code: 0, return_message: "success" }`。
+
+### 2. GET `/v1/ta/bury/manage/program/delete?projectId=<id>`
+
+一次清空整个项目的方案（事件 / 事件属性 / 公共属性 / 用户属性）。
+
+### 3. POST `/v1/ta/bury/manage/program/excel-save`
+
+批量上传 xlsx。
+
+- Content-Type：`multipart/form-data`
+- Form fields（全必填）：
+  - `file` — xlsx 二进制
+  - `projectId` — 文本
+  - `access_token` — 文本，裸 UUID
+- **无** Authorization header
+- Response：`{ return_code: 0, return_message: "success" }`（无 data）
+
+**合并语义**：对事件走 **merge-by-name**（同名不覆盖、新名新增）。若要完全替换，
+必须先调 `delete` 端点清空再上传。
+
+## 类型枚举（AE 后端接受值）
+
+### PropType（事件属性 / 公共属性 / 用户属性 `type` 字段）
+| canonical | 说明 |
+|---|---|
+| `string` | 文本 |
+| `number` | 数值 |
+| `bool` | 布尔 |
+| `datetime` | 日期时间 |
+| `object` | 对象（单对象，含子属性） |
+| `array_row` | 对象数组（允许 `父名.子名` 嵌套子属性） |
+| `array_string` | 字符串数组 |
+
+### UpdateType（用户属性 `updateType` 字段）
+| canonical | 语义 |
+|---|---|
+| `user_set` | 覆盖赋值 |
+| `user_setOnce` | 仅首次赋值 |
+| `user_add` | 数值累加 |
+
+## v2（暂未实现）
+
+- UI「逐个添加」通向单事件 CRUD 接口（`POST /v1/ta/bury/manage/event/*` 族），v1 走 excel-save 统一入口
+- 列项目、校验错误响应等见 plan 文档的"未抓端点"清单

package/skills/ae-generate-tracking-plan/references/xlsx-schema.md

@@ -0,0 +1,152 @@
+# AE Tracking Plan xlsx Format Contract (internal reference)
+
+> **Terminology**: 格式契约 = format contract | 必填列 = required column | 合并单元格 = merged cells | 表头 = header | Sheet 名 = sheet name | 数据静默不落库 = data silently discarded | 采集端 = platform/collection side | 事件数据 = event data | 公共事件属性 = super property | 用户数据 = user data | 用户ID体系 = ID mapping rule
+
+> `src/xlsx/{read,write}.ts` implementation basis. **Skill does NOT read this document.**
+
+官方模板：`tracking-plan-template/TE官方模板_dataTrackSample.xlsx`（从 AE 后台
+`/downloads/zh/dataTrackSample.xlsx` 下载）。所有字段规则以此模板为准，行业模板
+（电商/卡牌/社交/阅读）做读取兼容，不做 writer 适配。
+
+---
+
+## 写 xlsx 必须遵守的 3 条硬规则（端到端验证过）
+
+以下任一违反 → `excel-save` 返回 `return_code=0 success`，但**数据静默不落库**：
+
+### 规则 1. 必填列 header 带 `（必填）` 后缀
+- `事件名（必填）`、`属性名（必填）`、`属性类型（必填）`
+- 没有 `（必填）`，后端会丢弃整张 sheet 的数据
+
+### 规则 2. `#事件数据` 的事件字段列（A-D）跨多行必须**合并单元格**
+- 同一事件有多个属性时，A-D 列在 row N 到 row M 之间用 `mergeCells('A{N}:A{M}')` 合并
+- 否则后端按行级字符串匹配，报错 `事件名重复`
+- 官方模板就是合并单元格，SheetJS 读出来 row2+ 的 event 字段为 `null`（这是合并单元格的副作用）
+
+### 规则 3. 工作簿必须存在 `#用户ID体系` sheet
+- 即使只写一行 header 也行（内容可以全空）
+- 缺失整张 sheet → 后端丢弃整份方案
+
+---
+
+## Sheet 清单
+
+工作簿的 `#` 前缀 sheet 是数据 sheet，AE 后端只读这几张；其它（`接入必知`、
+`数据类型设计原则` 等）是说明文档，**写 xlsx 时不需要生成**。
+
+| Sheet | 含义 | 写 xlsx 策略 |
+|---|---|---|
+| `#事件数据` | 事件 × 属性展开（见规则 2） | 生成并合并 A-D 列 |
+| `#公共事件属性` | 公共属性定义 | 逐行生成 |
+| `#用户数据` | 用户属性定义（含更新方式） | 逐行生成 |
+| `#用户ID体系` | 系统预置属性说明 | **仅写 header 占位**（见规则 3） |
+
+### `#事件数据` 列定义（A→I）
+
+| 列 | 列名 | 必填 | 对应字段 |
+|---|---|---|---|
+| A | `事件名（必填）` | ✅ | `eventName` / `Event.event_name` |
+| B | `事件显示名` | 否 | `displayName` |
+| C | `事件说明` | 否 | `eventDesc` |
+| D | `事件标签` | 否 | `eventTag` |
+| E | `采集端` | 否 | `platform`（见下） |
+| F | `属性名（必填）` | ✅ | 属性 `name`（允许 `父.子`） |
+| G | `属性显示名` | 否 | 属性 `displayName` |
+| H | `属性类型（必填）` | ✅ | 类型中文值，见类型表 |
+| I | `属性说明` | 否 | 属性 `desc` |
+
+**采集端列（E）的值**：
+| `platform` 值 | xlsx 写入值 |
+|---|---|
+| `client` | `client` |
+| `server` | `server` |
+| `both` | `client,server` |
+| `undefined` | （留空） |
+
+**行语义**：一行一对 `(event, property)`。同一事件多属性时，A-E 按事件字段填写，F-I 按属性变化，
+A-E 在 writer 里用 `mergeCells` 合并。
+
+**property-less 事件**（罕见）：仍写一行，A-D 填事件字段，E-H 全空。AE 接受，
+但不推荐——建议至少给一个有语义的属性（例如 `user_logout` 加 `session_duration_ms`）。
+
+### `#公共事件属性` 列定义（A→D）
+
+| 列 | 列名 | 必填 |
+|---|---|---|
+| A | `属性名（必填）` | ✅ |
+| B | `属性显示名` | 否 |
+| C | `属性类型（必填）` | ✅ |
+| D | `属性说明` | 否 |
+
+### `#用户数据` 列定义（A→F）
+
+| 列 | 列名 | 必填 |
+|---|---|---|
+| A | `属性名（必填）` | ✅ |
+| B | `属性显示名` | 否 |
+| C | `属性类型（必填）` | ✅ |
+| D | `更新方式` | 否（默认视为 `user_set`） |
+| E | `属性说明` | 否 |
+| F | `属性标签` | 否 |
+
+**D 列直接填英文 canonical 值**：`user_set` / `user_setOnce` / `user_add`，不翻译中文。
+
+---
+
+## 类型枚举
+
+### PropType（xlsx 中文值 ↔ canonical）
+
+| canonical（draft.json） | xlsx 写入值 | xlsx 读取可接受值（含行业 alias） |
+|---|---|---|
+| `string` | `文本` | `文本` / `字符串` |
+| `number` | `数值` | `数值` |
+| `bool` | `布尔` | `布尔` |
+| `datetime` | `时间` | `时间` |
+| `object` | `对象` | `对象` |
+| `array_row` | `对象组` | `对象组` |
+| `array_string` | `列表` | `列表` |
+
+Writer 方向统一用第二列（官方中文正式名），不输出 alias。
+Reader 方向对 alias / 未知值做 fallback 并打 stderr warning。
+
+### UpdateType（用户属性 `更新方式`）
+
+| canonical | 语义 |
+|---|---|
+| `user_set` | 覆盖赋值（默认） |
+| `user_setOnce` | 仅首次赋值 |
+| `user_add` | 数值累加 |
+
+xlsx 里填写英文 canonical 值本身，不翻译。
+
+官方文档提及 `user_append`（字符串数组追加），样本中无实例，暂不实现。
+
+---
+
+## Reader 兼容规则（从 xlsx → Draft）
+
+- `.claude` 之外工作簿里只读 `#` 前缀 sheet
+- header 规范化：strip `（必填）` / `(必填)` 后缀，把 `名称` 归一化为 `名`
+- `#事件数据` 合并单元格读出来是 null → 用"继承上一行 event_name"策略还原
+- 属性列空、类型列空、prose / instruction 行 → skip
+- 行业模板额外前置列（`事件模块` / `属性分类`）通过 header 名查找，忽略不识别的列
+
+### 行业模板已知差异（只读取，不写入）
+
+| 模板 | 额外列 | 类型 alias | 其它 |
+|---|---|---|---|
+| 卡牌游戏 | `事件模块` / `属性分类` | `字符串` | 部分类型列空 |
+| 电商 | 部分 header 为空字符串（WPS 生成副作用） | — | 按列位置推断 |
+| 社交聊天 | `事件模块` / `属性分类` | `数量` | `更新方式` 含多行注释 |
+| 阅读类 | `事件模块` / `属性分类` | `字符串` | 同上 |
+
+写 xlsx 时**不**生成这些行业扩展列，统一输出官方 schema。
+
+---
+
+## 开放问题（记一下，不影响 v1）
+
+1. ~~AE 后端是否区分 `object`（单对象）与 `array_row`（对象数组）~~ —— 已确认：AE 支持，wiki/te-docs/raw/preparations-before-data-ingestion.md 明确区分两种类型
+2. `user_append` updateType 是否真的可用 —— 待构造测试
+3. 严格错误码 —— 所有校验失败目前都是 `return_code=0 success` + 静默丢弃，无法从响应区分成功/失败；UI 上传才显示错误文案