# 账户边界

项目脚本可以修改项目属性，不能直接增加平台积分或钻石。界面显示的价格、余额和流水必须以平台接口结果为准。

游戏可以设计金币等软货币，但不得把软货币出售、私下交易或作为平台积分的充值替代品。所有真实付费统一使用平台积分。

# 运行时只读字段

登录玩家可以在脚本中读取以下服务端快照：

这些字段只读，不写入普通项目属性，也不能由客户端存档覆盖。充值、消费或邀请完成后运行时会刷新，无需重新加载游戏。

受邀玩家统计只计算通过当前项目邀请归因直接绑定的玩家，不递归计算二级邀请，也不暴露单个受邀玩家的明细。平台只维护服务端权威累计值和冲正结果，不计算返利比例、不生成待结算金额，也不自动发放返利；具体里程碑、领取标记和游戏内奖励由项目脚本实现。

# 消费控件与充值控件

• 消费控件：模式为 consume、价格大于 0。后端扣款成功后才执行控件收益和脚本。
• 充值控件：模式为 recharge、价格固定为 0。点击后打开屏内平台充值页，不执行控件收益。
• 历史价格为 0 的普通控件不会自动变成充值入口，必须在编辑器中显式选择充值模式。

充值完成只刷新玩家信息，不会自动再次触发消费控件，避免重复扣款。

# 两种模式的责任

两种模式都不能用本地属性写入替代被拒绝的平台交易。预览必须覆盖相同的成功、取消、余额不足、超时和重试分支。

# 来源与有效期

积分可能来自购买、签到、任务、邀请、系统奖励、作者返利、活动奖励或打赏分成；钻石可能来自订阅和创作者任务。不同批次可能有不同到期时间，消费和返还要保留批次规则。具体数量、任务和价格以当前平台界面为准。

# 付费控件事务

编辑器中的付费控件配置负责绑定控件和所需积分。成功回执到达前，不要提前发放项目属性；回执重复到达时也不能重复发奖。匿名玩家需要先登录。

# AI 创作时必须说清楚

让编辑器 AI 接入付费能力时，提供：

• 付款主体和积分价格；
• 成功后唯一的项目奖励；
• 积分不足、取消、超时和断网反馈；
• 重复点击、重试和页面刷新策略；
• 作者分成或返利是否由平台提供；
• 首充、累计消费、项目邀请里程碑及每档唯一的已领取标记；
• 直属受邀玩家累计充值/消费里程碑，以及由游戏脚本负责的返利规则和领取状态；
• 玩家可见文案和非付费替代路径。

不要要求 AI 自己实现扣积分接口，也不要把付费结果只保存在页面变量里。

# 免费游戏礼包兑换码

悬浮菜单中的“礼包”支持两类码：12 位大写英文字母码领取当前游戏的免费礼包；16 位字母数字码继续兑换平台积分或商品权益。游戏礼包不会增加平台积分、计入首充或产生作者分成。

作者通过 AI 编辑器设置名称、用途、兑换后展示文本、全体或指定平台账号、总次数和有效期，并让 AI 生成礼包码。作者管理面板仅支持查询、完整信息、领取记录和禁用/启用，不支持手工生成或编辑。兑换码由服务器随机生成，作者不能指定码值。每个账号对同一码只能领取一次；总次数设为 null 表示不限，填写数字表示所有账号合计上限。生成数量表示不同码的数量，各码独立计次。

作者在付费插件中的面板只能查看及禁用/启用自己项目的兑换码，生成通过 AI 工具完成。AI 仅能创建兑换码。指定玩家使用登录账号名（通常是邮箱），创建时后端会校验所有账号名都存在，任一不存在则整批创建失败。超级管理员可在「系统后台 → 游戏礼包兑换码」独立面板查询全站游戏码，按项目、生成者账号 ID、名称、码值和状态筛选，查看玩家兑换记录、编辑未领取且未禁用的礼包规则或切换禁用状态。生成仍只通过 AI 工具。保留生成者、创建时间、用途、现行规则和领取时快照，不另外记录管理修改历史。is_disabled 标记是否禁用，不提供删除功能；禁用不删除任何记录，重新启用不重置领取次数，已有兑换的礼包规则不能更改。福利码不得用于私下出售游戏资源，集中生成与记录用于追溯和审核。

先在付费插件填写“兑换码脚本”，保存并发布，再创建和发放对应名称的礼包码。服务端核验兑换资格与次数后，把领取时的礼包名称和脚本快照交给游戏 Worker：

const name = tools.kwargs.name
if (name !== '维护补偿' && name !== '新手礼包') {
  throw new Error('未知礼包名称')
}
player.addPro('金币', name === '维护补偿' ? 100 : 20)

兑换时会自动核对玩家已加载的兑换脚本与服务端已发布脚本的 MD5。脚本不一致或旧客户端未提供 MD5 时，礼包不会消耗次数，页面提示先保存进度再刷新网页更新游戏，之后可用同一码重试。这个检查只覆盖兑换脚本文本，不能判断脚本未变时其他游戏数据是否最新。

脚本只编写同步游戏奖励逻辑，先检查条件再修改属性，不调用联网、AI、延时或另行保存。tools.kwargs.redemptionId 是后端兑换流水 ID；运行时用它在当前存档内去重。兑换全程显示遮罩，脚本执行后先保存本地，再将同一份快照上传云端槽位 0，两处保存成功后才显示兑换文本。云存档冷却期间继续等待；存档失败可用同码重试，当前存档会跳过已执行的奖励脚本并继续保存，后端不会重复消耗次数。

这种奖励仍属于客户端游戏存档。更换设备、清空本地数据、使用其他槽位或回滚旧存档可能重新执行奖励；它不能用于平台积分、付费权益或要求严格防作弊的资产。跨设备严格幂等需要服务端原子更新奖励与云存档。

编辑器 AI 仅使用 create_game_redemption_codes 创建兑换码。奖励脚本使用统一脚本工具：先用 query_script 读取 paiditemplugin/redemptionScript，再用 edit_script 精确修改该路径。查询、编辑、禁用和查看领取记录通过后台面板按权限操作。创建或切换禁用状态立即影响服务器，脚本修改则需保存发布。

# 流水与争议

个人中心的积分详情会显示可用余额、积分批次、来源、消费、到期、打赏和活动记录。项目状态与平台流水不一致时，先保存请求时间、项目、控件和流水 ID，再排查奖励补偿；不能通过脚本“补积分”。

# 验收矩阵

• 未登录、余额不足和用户取消不发奖励；
• 正常扣费只发一次；
• 快速双击、超时重试和刷新不会重复扣费或奖励；
• 流水金额、项目和控件一致；
• 到期批次与返还行为正确；
• 移动端确认弹窗不遮挡价格与取消按钮。

下一步：作品打赏。