# 《折叠快递社》技术架构与开发计划

> 目标：可玩 Demo ≤1 周、灰度版 ≤4 周、正式上线 ≤6 周；支付/存档/赛季联调与约 2 周平台审核尾项包含在总周期内。  
> 架构级别：L2 轻服务端；无强实时对战，不需要 L3 常驻同步服务。

## 1. 架构结论

交付包中的 `demo.html` 是产品链路评审原型，不是正式客户端。正式版建议使用支持微信/抖音小游戏导出的成熟 2D 引擎，游戏逻辑保持平台无关；平台登录、广告、支付、分享和存储通过 Adapter 隔离。小游戏运行环境并不等同于浏览器环境，正式包必须在各平台开发者工具和真机验证；Cocos 官方发布文档也明确说明小游戏运行时是封装环境，并提供微信小游戏发布与远程资源适配能力。[Cocos Creator 微信小游戏发布说明](https://docs.cocos.com/creator/3.3/manual/en/editor/publish/publish-wechatgame.html)

```text
微信 / 抖音客户端
  ├─ RouteBag：6×5格、拖放、五拍结算
  ├─ Meta：五维、图鉴、任务、赛季、商业化
  ├─ PlatformAdapter：login / ad / pay / share / storage
  └─ ConfigClient：版本、活动、卡池、礼包、AB
                 │ HTTPS
API / 云函数（L2）
  ├─ Auth & Profile          ├─ Economy Ledger
  ├─ Save Snapshot           ├─ Order & Grant
  ├─ Stage Settlement        ├─ Coop & Season
  ├─ Ranking Validation      └─ LiveOps Config
                 │
PostgreSQL（权威数据） + Redis（缓存/锁/榜单） + 对象存储/CDN（远程资产）
```

## 2. 客户端模块

### 2.1 RouteBag

- 固定 6×5 网格，物品形状由配置描述为格子偏移集合。
- 首局预填；拖动、单击拾取、撤销、恢复推荐布局、D21 后旋转。
- 合法性检测是纯函数：边界、占用、形状、锁定格、行标签。
- 每行生成 `Beat[]`，从上到下执行；同一输入和种子必须得到同一结果。

### 2.2 五拍状态机

`idle → packing → locked → beat_1..beat_5 → reward_pending → settled`

- fixed timestep 驱动结算，表现层不得直接写钱包。
- 后台/失焦暂停；恢复时从权威状态继续，不能按本机流逝时间偷跑单局。
- 一局只有一个 `runId`；重复结算请求返回同一结果。
- near-miss 是服务端可复核的结算状态，复行后沿用 `runId` 并增加 `attempt=1`。

### 2.3 Meta

- 五维养成与配送力为纯函数；所有界面只读同一推导结果。
- 钱包使用 append-only ledger，余额是流水聚合结果，不允许散落 `balance +=`。
- 图鉴、保底、月卡、战令、签到、合单和赛季都有独立版本字段与迁移器。
- Demo 本地存档 key 必须带 `gameId`；正式版客户端缓存不是权威来源。

## 3. 服务端职责

### 3.1 最小 API / 云函数

| 端点 | 作用 | 幂等键 |
|---|---|---|
| `POST /session/login` | 平台 code 换内部 userId | platform + openId |
| `GET /profile` | 拉取快照、配置版本、服务器时间 | — |
| `POST /save/merge` | 非经济偏好与进度合并 | revision |
| `POST /run/start` | 扣行动力、签发关卡种子 | requestId |
| `POST /run/settle` | 校验布局/种子、发奖励 | runId + attempt |
| `POST /upgrade` | 扣资源并升级五维 | requestId |
| `POST /gacha/pull` | 权威随机、保底、重复转换 | requestId |
| `POST /coop/contribute` | 合单贡献与里程碑 | runId |
| `POST /season/score` | 校验联赛积分 | runId |
| `POST /season/claim` | 结算领奖与继承 | seasonId + tier |
| `POST /order/create` | 创建待支付订单 | clientOrderId |
| `POST /pay/callback/*` | 验签、验金额、幂等发货 | platformOrderId |
| `GET /configs` | 活动/卡池/礼包/关卡下发 | configVersion |

### 3.2 权威边界

服务端权威：货币、行动力、队员/装备/核心、保底、订单、月卡、战令、赛季分、排名、限购与服务器时间。客户端可权威：音量、减少动态效果、已看教程步骤等不影响资产的偏好。

## 4. 数据模型

关键表：

- `users`：内部账号、平台映射、实名/年龄档、状态。
- `profiles`：快照 revision、五维等级、教程和章节。
- `wallet_ledger`：资源、delta、reason、reference_id、created_at；`reference_id` 唯一。
- `inventory`：asset_id、数量、等级、锁定、传承来源。
- `gacha_state`：pool_id、S/A 保底、心愿单、版本。
- `runs`：种子、布局摘要、状态、结果、attempt、settled_at。
- `orders` / `grants`：金额、商品、平台状态、发货状态；两张表都要唯一约束。
- `season_groups` / `season_scores`：50 人分组、真实/训练标识、分数、段位、结算状态。
- `coop_events` / `coop_contributions`：合单进度、个人贡献和里程碑领取。
- `liveops_configs`：开始/结束服务器时间、目标人群、版本、回滚版本。

经济流水、订单发货和赛季领奖在单事务中完成；缓存失败不得造成资产丢失或重复。

## 5. 支付与发货

客户端支付成功回调只能改变 UI 为“处理中”，不能发货。流程：

1. 服务端创建订单并签发商品快照、金额和过期时间。
2. 客户端调平台收银台。
3. 平台服务端回调到我方；验签、验 appId/用户/金额/商品/订单状态。
4. 数据库事务写 `grants`、资产流水和订单成功状态。
5. 回调重放返回成功但不重复发货；客户端轮询订单状态补偿。

抖音官方支付接入说明要求同时考虑服务端回调和订单查询，并在确认订单成功后由小游戏服务端发放道具。[抖音小游戏支付接入](https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/guide/open-ability/payment/access-process) 官方回调文档还明确要求回调验签、处理重复通知且不能以前端结果作为权益发放依据。[抖音支付结果回调](https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/server/payment/trade-system/general/order/notify-payment-result)

微信支付能力、iOS 虚拟支付、分成与资质在接入当周按微信官方文档与后台实际开放能力复核，不把历史比例写死进代码。

### 5.1 实名、年龄分档与未成年人限额

`POST /order/create` 在创建平台订单前读取服务端实名年龄档，并在事务内锁定“本自然月已成功金额 + 未决订单预占金额”。客户端传来的年龄、剩余额度和本地时间一律不可信。

| 实名年龄档 | 单笔上限 | 每自然月累计上限 | 服务端动作 |
|---|---:|---:|---|
| 未满 8 周岁 | ¥0 | ¥0 | 禁止充值，隐藏并拒绝全部真实支付入口 |
| 8 周岁至未满 16 周岁 | ¥50 | ¥200 | 超任一上限即拒单；¥68/98/128/328/648 商品不可下单 |
| 16 周岁至未满 18 周岁 | ¥100 | ¥400 | 超任一上限即拒单；¥128/328/648 商品不可下单 |
| 已满 18 周岁 | 依平台与风控 | 依平台与风控 | 仍执行实名、订单风控和平台当期规则 |

疑似未成年人账号在平台风控命中时先走人脸核验；核验失败、取消、超时或结果不一致均不得创建订单。并发下单使用用户+自然月唯一额度账本与行锁，不能靠同时发起多笔绕过累计上限；退款/撤销只在平台终态确认后回补额度。每次允许、拒绝和人脸核验结果写入合规审计日志，但不在业务日志保存人脸原始数据。

## 6. 云存档与冲突

- 登录后先拉服务端快照，客户端离线操作记录为带 UUID 的命令队列。
- 经济类命令必须联网提交；弱网可进入玩法，但结算停在 `reward_pending`，恢复网络后补交。
- 快照带 revision；只允许服务器合并白名单字段，资产冲突永远服务端优先。
- 换设备验证队员、保底、月卡、未领奖结算和赛季状态全部一致。
- 本机时钟回拨不能恢复已过期礼包或多领月卡；一切窗口使用服务器高水位时间。

## 7. 排行与反作弊

- 正式赛季只展示真实玩家；人数不足时跨服聚合，不用未标明机器人补满。
- Demo 的 49 个对手统一标“训练 AI”，仅用于演示排序状态机。
- 分数只能来自已结算 `runId`；客户端上传总分无效。
- 对布局摘要、配送力快照、关卡种子和结算帧数做合理性校验。
- 异常频率、同设备多账号、回调重放、超人类输入与资源增速进入风控队列。
- 排名缓存可重建，赛季权威分在数据库；结算任务使用分布式锁和幂等标记。

## 8. LiveOps 与配置

关卡、包裹、队员、掉落、卡池、活动、商品、AB、赛季均配置化。配置发布流程：schema 校验 → 90 天模拟 → 组合模拟 → 测试环境 → 1% → 10% → 全量；每版保留一键回滚。

配置必须包含 `startsAt` / `endsAt` 服务器时间，过期商品由服务端拒绝购买；客户端倒计时只是显示。抖音官方文档提示小游戏网络层具有平台特定并发和超时规则，平台 Adapter 必须分别做限流、重试和状态码判断。[抖音小游戏网络请求](https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/guide/basic-function/network)

## 9. 性能预算

- 首包目标：必要代码与首局资产最小化，其余远程分包；2 秒出现可操作骨架屏。
- 竖屏中端机目标 60 FPS，低端机不低于稳定 30 FPS；1% low 在真机专项记录。
- 背包判定使用整数格坐标，不用 30 个独立刚体。
- 同屏展开构装使用对象池；普通粒子、飘字和音效限制并发。
- 页面长列表虚拟化；资源按场景释放；后台暂停动画和音频。
- 网络响应压缩、ETag/版本缓存；远程资产校验 hash 后落盘。

## 10. 平台适配

| 能力 | 微信 | 抖音 | 共同抽象 |
|---|---|---|---|
| 登录 | 平台 code/openId | 平台 code/openId | `Platform.login()` |
| 激励视频 | 微信广告组件 | 抖音广告组件 | `Ads.rewarded(placement)` |
| 支付 | 当期虚拟支付能力 | 道具直购/游戏币能力 | `Pay.create(product)` |
| 分享 | 主动分享与回流参数 | 主动分享与内容入口 | `Share.intent(scene)` |
| 云服务 | 微信云/统一后端 | 抖音云托管/统一后端 | 统一 HTTPS API |

抖音官方开发文档说明平台可使用开发者工具、小游戏工程结构和云托管后端；正式工程应以当期工具链验收为准。[抖音小游戏开发指南](https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/guide/minigame/develop/)

两平台共用数值、资产、赛季和支付服务端；只调整前 10 分钟的内容节奏和素材入口，不维护两套经济。

## 11. 6 周开发计划

| 周 | 里程碑 | 验收出口 |
|---|---|---|
| W1 | 可玩 Demo：路线背包、五拍、结算、一次升级、模拟商业/联赛 | file:// 可运行；核心理解测试开始 |
| W2 | 正式客户端竖切：引擎工程、平台 Adapter、L1 登录/存档、配置框架 | 双平台开发工具可跑；跨设备存档 |
| W3 | 五维、队员/装备/核心/图鉴、任务/签到、D3 合单 | 经济流水可审计；合单幂等 |
| W4 | D7 联赛、战令、招募、广告双通道、灰度包；资质齐备后启动平台联调/预审 | 50 人分组/结算可压测；灰度 ≤4 周；审核尾项开始计时 |
| W5 | 支付沙箱/小额真机、实名防沉迷、概率、远程配置、素材 30 条；处理首轮审核反馈 | 支付重放不双发；合规清单通过；正式包提交 |
| W6 | 两平台兼容、性能、审查改稿、平台审核与发布 | 正式上线目标 ≤6 周；未获批即判 G8 未通过，不以“候审”替代上线 |

平台资质、版号/备案、支付开通和审核可能超过代码周期，是人的合规与平台关系任务，不用“代码已完成”掩盖外部前置条件。

## 12. Demo 与正式版差距

Demo 只做本地、显式模拟：模拟支付、模拟广告、训练 AI 排行、本地存档。它验证玩法因果与完整产品链路，但**不宣称**完成云存档、真人社交或服务端验单。

正式版上线前必须补齐：平台登录、L2 权威经济、服务端随机、订单验签与幂等发货、真人赛季聚合、云存档、实名防沉迷、远程活动开关、真机广告和支付联调。