API 与数据规范

API 入口与鉴权

• token 为随机串存表（非 JWT），支持主动踢下线、多点登录开关、过期滑动续期。
• 平台域与租户域 token 完全隔离；平台管理员进入站点后台是签发临时租户域 token（带审计）。
• 应用路由自动挂前缀：C 端 /api/app/{key}/...、站点后台 /adminapi/app/{key}/...。

响应结构与错误码

• 分页：入参 page（1 起）、size（默认 15，上限 100）；出参 { list, total }。
• 金额出参一律转元字符串（如 "12.50"），入库与计算全程 int 分。
• 支付 / 资产 / 授权类写接口以业务单号天然幂等；其余写接口可选 Idempotency-Key 头——60 秒内携带同一 key 的重复请求直接返回首次执行结果，不会重复执行。
• URL 不带版本号：私有化部署端到端同版发布，破坏性变更走框架大版本。

业务交易类型注册

应用要收钱，唯一正确姿势是注册交易类型并实现结果回调，绝不自建支付流程：

• handler 实现 TradeHandlerInterface 的 onPaid / onRefunded / onClosed 三个回调。
• onPaid 在交易置已付的事务提交之后执行；失败自动进重试队列（5 次退避），必须幂等。
• allow_ways 声明允许的支付方式集合；virtual_goods: true 的类型在 iOS 端自动切换虚拟支付。
• 内核自带 recharge（余额充值）类型，allow_ways 排除 balance——禁止余额买余额。

MySQL 5.7 / 8.0 双兼容红线

框架承诺同一套迁移在 MySQL 5.7 与 8.0+ 上行为一致。以下红线由 php webman db:lint 静态扫描强制——打包扩展前跑一遍，不通过就改到通过：

• 字符集 utf8mb4，collation 统一 utf8mb4_general_ci；禁止 `utf8mb4_0900_ai_ci`（最常见的兼容事故源）。
• 禁用 8.0-only 特性：窗口函数、CTE、JSON_TABLE、REGEXP_REPLACE、降序索引、不可见索引、CHECK 约束。
• JSON 列可用（5.7.8+）；需索引的 JSON 路径用生成列 + 索引。
• 表 / 列名避开 8.0 保留字：rank、groups、function、row、system、lateral 等。
• 时间一律 int 时间戳（字段名 *_time），避免 TIMESTAMP 类型；迁移显式指定 sql_mode。
• InnoDB + ROW_FORMAT=DYNAMIC；varchar 索引长度按 5.7 严格侧设计。

通用表规范

• 表前缀 {{prefix}} 占位（默认 tf_）；迁移中的 INSERT 一律 INSERT IGNORE 或按唯一键 upsert——迁移必须幂等可重跑。
• 主键 bigint unsigned AUTO_INCREMENT；金额 int（分）；状态 tinyint + 常量类；软删 delete_time int NULL。
• 业务表必备列：site_id（SiteScoped）、create_time、update_time；组合索引以 site_id 打头。
• 应用业务表前缀 {{prefix}}app_{key}_；插件表 {{prefix}}addon_{key}_。