Initial import of HEROLL source and design documents

design/gameplay-monetization/README.md

@@ -0,0 +1,23 @@
+# Heroll 玩法与商业化开发包
+
+本目录把样本实装、运行时观察与新项目建议拆开管理。开发时以 specs 下的规则表为配置与验收基线；原作商品目录只用于理解系统边界，不应直接照搬价格、商品 ID、文案或资源。
+
+## 文件导航
+
+- specs/economy-and-monetization-rules.csv：商业化总规则、配置键、埋点和验收条件。
+- specs/feature-paywall-audit.csv：功能付费墙与玩家优势审计。
+- specs/economy-resource-map.csv：资源来源、消耗、付费暴露与平衡目标。
+- specs/analytics-events.csv：玩法、广告、购买与经济流水的最小埋点集合。
+- ../../analysis/gameplay-monetization/tables/monetization-products.csv：样本声明的 397 条商品配置，供审计使用。
+- ../../analysis/gameplay-monetization/tables/gacha-actions.csv：样本 23 种抽取动作与成本。
+- ../../analysis/gameplay-monetization/tables/gameplay-commerce-callflow.csv：由 IL2CPP 元数据恢复的玩法/商业化类与方法入口。
+- ../../docs/2026-08-13_gameplay-monetization-heroll-report.md：证据、结论、设计取舍及开发落地说明。
+
+## 采用规则
+
+1. 字段 actual_evidence 或 sample_implementation 描述 Heroll 样本，不等于推荐方案。
+2. 字段 product_recommendation 或 launch_rule 才是新项目的默认实现。
+3. 所有付费结算必须由服务端或平台回执确认，并使用幂等 transaction_id。
+4. 付费、广告、随机抽取不得改变已生成但尚未向玩家揭示的骰子结果。
+5. 若团队决定采用“高还原商业模型”，仍必须保留表格中的展示时机、频控、保底和可免费获取约束。
+

design/gameplay-monetization/specs/analytics-events.csv

@@ -0,0 +1,22 @@
+"event_name","trigger","required_fields","privacy_rule","validation"
+"run_start","服务端确认体力扣除并生成 run_id 后","run_id,mode,stage,loop,energy_before,energy_after,seed_version,boosters","不记录广告 ID 或账户明文","run_id 全局唯一；体力流水恰好一条"
+"dice_roll_committed","骰子结果写入局内状态时","run_id,turn,dice_a,dice_b,is_double,position_before,position_after,rng_counter","seed 仅记录版本和审计散列，不上传可反推账户的信息","每次移动前恰好一个 committed 事件；与存档可重放一致"
+"tile_landed","棋子完成落点处理时","run_id,turn,tile_id,tile_type,reward_ids,combat_id","不记录自由文本","位置与 dice_roll_committed 对得上"
+"battle_end","战斗状态进入 PostBattle 时","run_id,battle_id,result,duration_sec,hp_ratio,rewards,revive_count","不上传设备稳定标识","奖励流水总和与 reward_grant 一致"
+"run_end","结算或合法退出时","run_id,result,stage,loop,duration_sec,reason,rewards","reason 使用枚举","每个 run_id 最终恰好一个终态"
+"economy_flow","任何资源变化时","transaction_id,resource_id,delta,balance_after,source_or_sink,reason,run_id,sku_id","sku_id 可为空；不得含平台回执全文","同 transaction_id 幂等；balance_after 不为非法负数"
+"ad_offer","广告入口展示时","placement,run_id,eligible_reason,daily_count","不写广告网络用户标识","非 eligible 状态不得出现 offer"
+"ad_start","播放器确认开始时","placement,request_id,network,daily_count","network 为枚举，不记录 ad_unit_id","必须先有同 request_id 的成功加载状态"
+"ad_complete","服务端接受完成证明时","placement,request_id,reward_transaction_id,duration_sec","不记录广告收入明细到客户端分析流","一个 request_id 最多发放一次奖励"
+"ad_fail","加载或播放失败时","placement,request_id,error_category,retryable","错误详情脱敏","失败不增加已完成次数且不扣奖励资格"
+"store_view","商店或礼包页面曝光时","surface,catalog_version,visible_skus,session_impression_count","不记录平台支付账户信息","visible_skus 必须均为当前平台 available"
+"purchase_start","玩家在确认页主动提交时","sku_id,localized_price,currency,catalog_version,offer_context","价格来自平台；不上传支付凭证","必须存在先前 purchase_confirm_view"
+"platform_purchase_result","平台返回购买状态时","sku_id,transaction_id,status,error_category","回执只发安全校验服务，不进普通分析仓","重复平台回调不重复记 success"
+"receipt_verify","服务端校验回执时","sku_id,transaction_id,result,platform,latency_ms","严禁记录原始回执、签名和账户标识","成功后才能产生 entitlement_grant 或 reward_grant"
+"entitlement_grant","永久/订阅权益发放时","transaction_id,entitlement_id,start_at,end_at,restore","时间为 UTC","恢复购买不会创建重复权益"
+"gacha_pull_start","抽取消耗确认时","pull_id,pool_id,cost_resource,cost,pity_before,probability_version","不上传可预测随机种子","先成功扣费再请求服务端结果，失败可原子回滚"
+"gacha_pull_result","服务端结果落库时","pull_id,pool_id,item_id,rarity,is_duplicate,pity_after,conversion","不含 RNG 内部状态","与概率版本、保底规则一致；pull_id 幂等"
+"offer_impression","礼包卡片达到可见阈值时","offer_id,trigger,stage,time_since_failure_sec,impression_count","不使用敏感画像字段","post_failure_disabled 时 time_since_failure_sec 小于 1800 的事件数为 0"
+"pass_xp_gain","通行证经验变化时","season_id,source,delta,xp_after,free_cap,premium_cap","不记录任务自由文本","经验上限与配置一致；购买高级轨不重置既有经验"
+"afk_claim","领取离线收益时","offline_sec,capped_sec,multiplier,rewards,quick,ad_used","不记录前后台应用列表","服务器时间决定 capped_sec；相同领取窗口只发一次"
+

design/gameplay-monetization/specs/economy-and-monetization-rules.csv

@@ -0,0 +1,18 @@
+"rule_id","system","sample_implementation","launch_rule","dev_config","required_telemetry","acceptance_criteria"
+"MON-001","骰子与局内随机","样本存在好地块、开局装备、回合点数、首领防御和监狱脱出等付费或广告道具","已经生成的骰子结果不可付费重掷或暗改；辅助道具只在开局前选用，单局每类最多 1 个，均有免费获取路径","commerce.allow_midroll_offer=false; run_booster.max_per_type=1","run_booster_offer; run_booster_use; dice_roll_committed","同一 seed 和输入在付费与非付费账户上得到相同骰子序列；掷骰动画开始后不出现购买弹窗"
+"MON-002","体力","样本每局消耗 5，10 分钟恢复 1，上限 40，VIP 增加 20 上限","失败重试不重复扣体力；首日给予至少 12 局体验量；付费只加速，不封锁主线结局","energy.cost_per_run=5; energy.regen_sec=600; energy.base_cap=40; energy.retry_grace_sec=120","energy_flow; run_start; run_abort; energy_cap_reached","断线或 120 秒内技术性退出可恢复扣除；自然恢复时间由服务端时间计算"
+"MON-003","奖励广告","样本商品表含 22 条 AD_WATCH 行，运行时奖励广告已加载","仅设置结算加倍、每日免费体力、AFK 加速、商店免费刷新四类自愿入口；启动版本每日完整奖励最多 6 次","ad.rewarded.daily_cap=6; ad.rewarded.cooldown_sec=30; ad.rewarded.placements=result_double,energy,afk,shop_refresh","ad_offer; ad_start; ad_complete; ad_fail; reward_grant","关闭广告不损失原基础奖励；失败时不扣次数；奖励发放幂等且可补发"
+"MON-004","插屏广告","样本含插屏管理与去广告商品，运行时插屏库存已加载","只允许在返回大厅后的自然断点展示；至少完成 3 局且间隔 10 分钟；失败结算、首局、购买前后和教学期禁用","ad.interstitial.min_runs=3; ad.interstitial.cooldown_sec=600; ad.interstitial.tutorial_disabled=true","interstitial_eligible; interstitial_show; interstitial_close; session_run_count","任何局内、战斗、骰子结果和失败页面均不弹插屏；频控跨重启保存"
+"MON-005","去广告","样本存在 1.99 美元配置的 remove_interstitial_package 与 forceAdRemove 道具","一次性去除强制插屏；奖励广告入口保留且完全自愿；商品描述必须明确不移除奖励广告","entitlement.remove_forced_ads=lifetime","purchase_start; purchase_success; entitlement_grant; ad_suppressed","跨设备恢复购买后立即生效；拥有权益的账户 100% 不触发插屏请求"
+"MON-006","抽卡与保底","样本 23 个抽取动作，其中 7 个广告、1 个免费；装备保底 20/50，坐骑保底 400","公开每档概率、重复品转换和保底规则；保底进度服务端保存且跨卡池规则明确；首次上线不设置超过 80 抽的大保底","gacha.probability_version=v1; gacha.pity_hard_cap<=80; gacha.server_authoritative=true","gacha_view; gacha_pull_start; gacha_pull_result; pity_change; duplicate_convert","概率表和客户端展示一致；模拟至少 1000 万抽后误差在统计置信区间内；断线不会重复扣款"
+"MON-007","通行证","样本 normal pass 含日/周/挑战任务、免费与高级经验上限，并声明多个 pass 商品","首发只保留免费轨和一个高级轨；赛季 28 天；高级奖励以外观、便利和可追赶资源为主，不售 premium-plus","pass.duration_days=28; pass.premium_tiers=1; pass.catchup_week=3","pass_xp_gain; pass_tier_unlock; pass_purchase; pass_reward_claim","赛季最后 7 天提供任务追赶；未领取奖励在赛季结束后自动邮件补发"
+"MON-008","每日购买奖励","样本表按购买点数 0/1/2/4/7/10/13 累进发奖","首发移除按当日消费额累进的额外奖励，改为非付费日常活跃里程碑","daily_spend_ladder.enabled=false; daily_activity_track.enabled=true","daily_activity_progress; daily_activity_claim","不出现要求继续消费才能保住进度的 UI；所有日常奖励可由玩法完成"
+"MON-009","阶段/失败触发礼包","样本声明大量 stage-clear 与 trigger 商品族","礼包只在成功通关后的大厅庆祝区展示，每个里程碑最多一次；失败后 30 分钟内不展示付费挽回弹窗","offer.post_failure_disabled=true; offer.stage_clear.max_impressions=1; offer.cooldown_sec=1800","offer_eligible; offer_impression; offer_dismiss; offer_purchase","连续失败不会提高价格、缩短倒计时或改变概率；关闭一次后本里程碑不再弹"
+"MON-010","角色/装备/宠物/遗物/坐骑","样本现金商品可直接投向装备、宠物、遗物、坐骑等战力系统，部分价格配置最高 119.99 美元","所有战斗属性均可稳定免费获得；付费只缩短时间；同赛季付费加速形成的有效战力差控制在 15% 内","power.paid_advantage_cap=0.15; power.exclusive_paid_stats=false","power_snapshot; item_source; progression_velocity; payer_cohort","无现金专属战斗词条；免费玩家在一个赛季内可达成全部关键玩法门槛"
+"MON-011","价格梯度","样本现金配置 343 条，0.99–119.99 美元，中位数 8.99 美元","首发 SKU 不超过 12 个；建议档位 0.99/2.99/4.99/9.99/19.99/49.99，暂不启用 99.99 或 119.99","store.launch_sku_cap=12; store.price_ceiling_usd=49.99","store_view; sku_impression; purchase_start; purchase_success; purchase_fail","商店首屏不超过 6 个付费 CTA；价格从平台本地化接口读取，不硬编码"
+"MON-012","订阅/VIP","样本声明 subscription/VIP 商品，并可增加体力上限","首发最多一个月卡；权益为每日货币、去插屏与便利，不提供现金专属关卡、伤害或掉率","subscription.max_plans=1; subscription.combat_bonus=0","subscription_view; subscribe; renew; cancel; entitlement_expire","过期后只停止未来权益，不回收已领取资产；取消路径在两次点击内可达"
+"MON-013","猪猪存钱罐与累积价值","元数据存在 PigBankView 和购买入口","首发关闭；若后续开启，只累积展示价值，不截留玩家本应获得的基础掉落，且无损失倒计时","piggy_bank.enabled=false","piggy_accumulate; piggy_view; piggy_purchase","关闭功能不改变基础掉落；不得用即将清空的威胁推动购买"
+"MON-014","AFK 收益","样本离线收益最长 1440 分钟，快速 AFK 360 分钟，每日 3 次，消耗 15 体力，广告快速 AFK 每日 1 次","保留 24 小时上限；广告加速每日 1 次；快速收益不可同时收取体力和现金","afk.max_min=1440; afk.quick_min=360; afk.ad_daily_cap=1; afk.cash_cost_enabled=false","afk_open; afk_claim; afk_quick_claim; afk_multiplier","服务器重算离线时长；修改本机时间不能增加收益；显示领取前的确定数值"
+"MON-015","交易与回执","样本使用 Unity IAP/Google Play Billing，当前 Google Play Games 会话有多项商品 unavailable","商品可用性与目录版本分离；服务端校验回执、发货幂等、支持恢复购买与延迟订单","purchase.receipt_server_verify=true; purchase.idempotency_key=platform_transaction_id","purchase_start; platform_result; receipt_verify; grant_result; restore_purchase","重复回调只发一次货；网络恢复后可重试；不可用商品隐藏而不是显示可点击空壳"
+"MON-016","随机与价格披露","样本资源表可恢复保底，但客户端是否完整展示无法由本轮确认","所有概率、保底剩余、价格、有效期、内容物和重复品规则在确认付款前可见","compliance.prepurchase_disclosure=true","disclosure_open; purchase_confirm_view; gacha_probability_view","QA 截图可证明每个随机付费入口在付款前两步内可达概率页"
+

design/gameplay-monetization/specs/economy-resource-map.csv

@@ -0,0 +1,14 @@
+"resource_id","resource","sample_source","sample_sink","paid_exposure","launch_balance_target","hard_guardrail"
+"RES-001","金币 gold","战斗、棋盘、AFK、日常与商品包","日常商店、成长升级与刷新","现金包和礼包可间接提供","保持 3–5 个持续消耗口；中期日净产出约为关键升级需求的 20–30%","不允许因付费跳过全部核心成长；大额流水必须带 source/sink reason"
+"RES-002","钻石 dia","成就、日常、活动、少量局内上限与现金购买","抽卡、体力、局内辅助和商店","核心付费货币；样本存在每日局内获得上限 100","免费周收入至少覆盖 10 抽或等价目标；局内可得上限在 UI 明示","付费钻与赠送钻分账；退款不产生负库存死锁"
+"RES-003","体力 energy","自然恢复、广告、活动、钻石与包","开始主线/快速 AFK；样本每局 5","付费可补充但不作为唯一玩法入口","基础上限 40；10 分钟/1；技术退出宽限；睡眠 8 小时后至少可玩 8 局"
+"RES-004","遗物灵魂 relic_soul","重复品转换、玩法奖励与包","遗物/高级遗物抽取或定向兑换","可被礼包加速","设置确定性商店，连续 14 天活跃可定向一个关键遗物","重复转换价值固定；保底和货币不可赛季清零"
+"RES-005","药水战斗票 potionBattleTicket","自然/活动/商店；样本上限 10、每小时恢复 1","药水战斗玩法","可由包补充","每日自然产出覆盖基础任务，活动奖励提供额外次数","到上限提醒；恢复计时由服务端维护"
+"RES-006","突袭票 raid_ticket","日常、活动、广告与包","Raid 入场","广告和现金包可增加","免费玩家每日可完成全部基础 Raid 奖励门槛","不同时收取体力和票券；赛季任务不要求付费次数"
+"RES-007","突袭币 raid_coin","Raid 结算、任务","Raid 商店定向兑换","付费只通过额外次数间接加速","每周可定向至少一个成长目标","商店轮换前展示剩余时间；核心目标不只随机出现"
+"RES-008","命运币 destiny_coin","命运玩法、活动","命运成长/商店","样本商品族可提供","与赛季任务绑定但保留稳定免费来源","不售现金专属节点；赛季结束提供兑换缓冲期"
+"RES-009","坐骑活动票 mount_event_ticket","活动、任务、包","坐骑抽取；样本坐骑保底 400","现金礼包可加速","若保留随机抽取，硬保底下调至不超过 80；提供定向碎片","概率、剩余保底和过期规则始终可见"
+"RES-010","宠物抽卡券 petGachaTicket","活动、任务、通行证与包","宠物抽取","现金商品密集","免费月收入覆盖一个明确保底周期的至少 50%，其余可由定向兑换补齐","无现金专属宠物战斗技能；重复品有保底价值"
+"RES-011","局内辅助道具 600–604","任务、成就、免费商店；样本也支持钻石/广告/商品","开局前消耗以提供防御、脱出、奖励或成长便利","样本有直接付费与广告入口","作为可选构筑资源，不成为默认难度补丁","不在已知坏结果后售卖；排行榜模式禁用；每类单局最多 1"
+"RES-012","通行证经验 pass_xp","日/周/挑战任务、循环通关；样本普通玩法经验上限 200、高级 400","解锁免费/高级轨奖励","购买高级轨提升可领范围","活跃玩家 70% 赛季时长可完成；最后一周可追赶","不得通过购买经验成为唯一完成方式；赛季结束自动补发已解锁项"
+

design/gameplay-monetization/specs/feature-paywall-audit.csv

@@ -0,0 +1,16 @@
+"audit_id","feature","sample_evidence","payer_advantage","design_risk","launch_decision","guardrail"
+"PAY-001","首领防御/闪避","商品与道具表存在首领防御类消耗品","直接降低局内失败概率","高：将挑战结果与付费绑定","仅作为可游玩获得的开局道具，首发不直接现金售卖","单局最多 1 个；使用前显示效果；不在失败瞬间推销"
+"PAY-002","监狱脱出","商品表存在监狱脱出道具","跳过负面棋盘事件","高：付费消除随机惩罚","改为任务、成就和免费商店货币来源","触发监狱后不得弹现金购买；可使用既有库存"
+"PAY-003","好地块保证","钻石、广告与商品配置存在 good tile 相关条目","改变落点收益分布","高：可能破坏骰子公平感","只允许开局前选择一次性护符，效果改为提升下一次奖励而非改写落点","不得重算已提交骰子；效果记录进 run seed 日志"
+"PAY-004","开局装备","商品配置存在 start gear 相关条目","缩短成型时间并影响战力","中高","作为赛前构筑槽位；可通过局外升级解锁，不现金独占","付费获取速度优势不超过一个赛季 15% 有效战力差"
+"PAY-005","回合/循环点数","商品配置存在 loop point 相关条目","加快进度、提前触发成长","中高","转为周常可得的便利消耗品，不在排行榜模式生效","排行榜、首通与竞速模式自动禁用"
+"PAY-006","体力购买","样本可用钻石购买 15/50 体力并有广告补充","增加可玩次数","中","保留自然恢复、活动补给和每日广告；失败重试宽限","不销售永久体力伤害；活动门票与主线体力不双重收费"
+"PAY-007","装备/宠物/遗物/坐骑抽取","样本含多条抽取及现金加速商品","长期战力与收集进度提升","高","可保留但所有战力有免费确定性路径；现金主要售外观与时间","公布概率/保底；重复品可兑换目标；无付费专属属性"
+"PAY-008","通行证","样本含 normal、raid、mount 等 pass 商品族","资源密度与收集速度提升","中高：多 pass 叠加造成订阅疲劳","首发合并为一个 28 天通行证","一个高级轨；奖励可追赶；不要求购买第二张玩法通行证"
+"PAY-009","订阅/VIP","样本含 subscription/VIP，VIP 增加体力上限","持续便利与资源收益","中","首发仅一个月卡","无伤害/暴击/掉率加成；可随时取消；权益写清"
+"PAY-010","阶段通关礼包","商品目录存在大量 stage clear/trigger 家族","里程碑时提供高价值加速","中高：高频弹窗与锚定定价","成功后大厅卡片展示，不自动遮挡结算","每里程碑一次曝光；无损失倒计时；不在失败后出现"
+"PAY-011","每日购买奖励","配置以 0/1/2/4/7/10/13 购买点累进","刺激当日追加消费","高：诱发沉没成本与冲动消费","不采用，改为每日活跃奖励","进度只由玩法行为积累；不显示消费缺口"
+"PAY-012","插屏与去广告","样本含插屏管理、频控入口和去广告商品","付费改善体验但不增加战力","中","允许自然断点插屏并提供一次性去插屏","教学期禁用；3 局/10 分钟频控；奖励广告不受影响"
+"PAY-013","AFK 快速领取","样本可消耗体力并可看广告快速领取","缩短等待时间","低中","保留每日一次广告加速，不现金收费","预览确定收益；不同时消耗体力和现金；本机改时无效"
+"PAY-014","复活","BoardController 元数据存在 UseRevive，实际价格与触发规则未由方法体确认","可能直接延长单局并保留构筑","高","每日首次可用免费资源；付费币复活只限非排行榜 PvE 且每局一次","失败后只显示已有资源复活，不弹现金包；复活不改变已结算掉落"
+