# 《银河拾荒局》技术架构与开发计划

> 首发目标：8 周可审核版本；2 周内可玩 Demo。  
> 服务端等级：L2 轻服务端；不需要 L3 实时通信。  
> Demo：原生 HTML/CSS/Canvas/JavaScript，无构建依赖；统一 SDK 模拟云双写，支付/广告/榜单均明确标注为模拟。

## 1. 架构结论

```text
微信/抖音小游戏客户端
├─ Canvas 出航引擎（伪物理磁吸、对象池、结算摘要）
├─ DOM/UI 层（基地、五维资产、合约、联赛、商店）
├─ 本地缓存（只作断网缓存，不作权威资产）
└─ 平台适配器（登录、广告、支付、分享、生命周期）
              │ HTTPS + 登录态 + 请求签名
              ▼
L2 云函数/API
├─ 账号/实名/防沉迷门禁
├─ 云存档与经济账本
├─ 出航种子/结算校验/离线收益
├─ 联合合约、联赛分组/榜单/结算
├─ 支付订单、回调验签、幂等发货
├─ 广告奖励限额、分享回流计数
└─ 活动/商品/概率/经济远程配置
              │
              ▼
云数据库 + 缓存 + 对象存储 + 监控/审计
```

选择 L2 的理由：全部社交是异步贡献/榜单；没有实时 PVP、自由交易或世界聊天。真正需要服务端权威的是资产、掉落、支付和赛季，而不是每帧位置。

## 2. 客户端模块

| 模块 | 职责 | 权威性 |
|---|---|---|
| `sortie-engine` | 输入、移动、牵引尾巴、归仓、风暴、粒子、HUD | 客户端表现；结算摘要服务端复核 |
| `progression` | 五维显示、升级预览、银河资产值展示 | 服务端结果；客户端只预览 |
| `economy` | 余额显示、消耗请求、奖励展示 | 服务端账本权威 |
| `inventory` | 舰体、成员、遗物、保底显示 | 服务端权威 |
| `contracts` | 日常/联合合约进度 | 服务端计数 |
| `season` | 分组、榜单、任务、结算 | 服务端权威 |
| `commerce` | 商品展示、下单、支付状态轮询、恢复 | 服务端 + 平台回调 |
| `platform-adapter` | `wx`/`tt`/H5 的登录、广告、支付、分享 | 平台能力 |
| `telemetry` | 事件、实验桶、错误、性能 | 批量上报；不含敏感明文 |
| `save-cache` | 本地最后快照、离线只读、断线重试 | 非权威；有版本号 |

## 3. 出航引擎实现

### 3.1 伪物理，不使用全量刚体

- 废件是轻量对象 `{id,type,x,y,vx,vy,value,rarity,state}`，按固定步长更新。
- 进入磁吸半径后采用插值/弹簧轨迹靠近玩家；装入尾巴后按样条点跟随，不做逐件碰撞。
- 尾巴同屏上限 20；更长载重只计数并以粒子/计数表现，防低端机发热。
- 废件、浮字、粒子全部对象池；每帧不创建临时 DOM。
- 碰撞使用圆形距离与空间网格；不引入重型物理库。

### 3.2 时间与随机

- 服务端创建出航时返回 `sessionId, seed, startedAt, energyAfter, configVersion`。
- 客户端用种子 PRNG 生成废件序列，便于复盘；表现随机不影响权威掉落。
- 结算上传：归仓事件摘要、稀有拾取、尾巴峰值、总时长、校验哈希，不上传每帧轨迹。
- 服务端按种子和规则验证最大可得范围；异常值进入审核，不直接相信客户端余额。

### 3.3 性能预算

| 指标 | 目标 |
|---|---:|
| 首包 | ≤4 MB；其余星区/角色分包 |
| 冷启动到可操作 | 中端机 ≤2 秒；弱网优先加载玩法占位资产 |
| 帧率 | 中端机 60 FPS；低端机稳定 ≥30 FPS |
| 同屏逻辑废件 | ≤80；真实尾巴渲染 ≤20 |
| Draw calls | 玩法核心建议 ≤80/帧，尽量合批 |
| 峰值内存 | 首发目标 ≤180 MB，平台真机压测为准 |
| 单次存档 | 核心 JSON ≤64 KB；日志/账本不塞进存档 |
| 断网恢复 | 30 秒内重连不丢已归仓摘要；未确认奖励保持待结算 |

## 4. 服务端数据模型

| 表/集合 | 主键/关键字段 | 说明 |
|---|---|---|
| `player_profile` | `uid`、实名/年龄段、公司等级、段位、版本 | 不存身份证明文 |
| `player_save` | `uid, slot, version, data, updated_at` | 乐观锁，跨设备 |
| `wallet` | `uid, recycle_coin, gem, energy, energy_at` | 权威余额 |
| `economy_ledger` | `txn_id, uid, currency, delta, reason, ref_id, balance_after` | 只追加，不直接改历史 |
| `asset_dimension` | `uid, fleet, workshop, crew, research, relic_bonus` | 服务端重算总资产 |
| `inventory` | `uid, object_id, type, level, star, status` | 舰体/成员/遗物/模块 |
| `pity_counter` | `uid, pool_group, count, version` | 跨同类池继承 |
| `sortie_session` | `session_id, uid, seed, config_version, start/end, summary, status` | 一次出航 |
| `contract_progress` | `uid/group_id, contract_id, value, claimed` | 日常/联合合约 |
| `season_group` | `season_id, group_id, tier, member_count` | 50 人同段位组 |
| `season_score` | `season_id, group_id, uid, score, audited` | 排行源 |
| `purchase_order` | `order_id, uid, sku, expected_amount, platform_status` | 下单与查询 |
| `grant_record` | `grant_id, order_id, sku, payload_hash, granted_at` | `order_id` 唯一，防重复发货 |
| `remote_config` | `key, version, effective_at, payload, signature` | 经济/活动/商品/概率 |
| `experiment_bucket` | `uid, experiment, variant, assigned_at` | 稳定分桶 |

资产值由服务端根据对象和版本化数值表重算，客户端上传的 `assetValue` 只作为日志，不用于排行榜或分组。

## 5. API/云函数最小面

| 方法 | 接口 | 要点 |
|---|---|---|
| POST | `/session/login` | 平台 code 换 uid；实名/防沉迷门禁；下发服务器时间 |
| GET/PUT | `/save/{gameId}` | 版本号乐观锁；冲突返回服务端档和合并提示 |
| GET | `/state/bootstrap` | 钱包、资产、合约、赛季、配置版本一次获取 |
| POST | `/sortie/start` | 扣能源、生成 seed/sessionId；幂等 key |
| POST | `/sortie/finish` | 验证摘要、事务写账本/掉落/合约/赛季贡献 |
| POST | `/upgrade/preview` | 返回消耗、升级后效果与资产 +X |
| POST | `/upgrade/commit` | 原子扣费 + 升级 + 重算资产 |
| POST | `/process/start|accelerate|claim` | 服务器时间门；广告/星钻通道 |
| GET/POST | `/coop/state|contribute|claim` | 分组、有效贡献上限、幂等奖励 |
| GET/POST | `/season/board|score|claim` | 分组校验、异常审计、结算领取 |
| POST | `/commerce/order` | 校验 SKU、年龄、限购、价格和有效期 |
| POST | `/commerce/callback/{platform}` | 平台验签/验金额/验状态，幂等发货 |
| GET | `/commerce/order/{id}` | 客户端只轮询最终状态，不自行发货 |
| POST | `/ad/reward` | 场景/日限额/时序校验；平台能力允许时验凭据 |
| POST | `/share/create|visit` | 分享 ID、好友实际回流、双方限额 |

## 6. 支付与发货

```text
客户端点购买
→ 服务端校验：实名/年龄/限额、SKU、真实起止时间、账号限购
→ 服务端创建 pending 订单并返回平台参数
→ 客户端调用平台支付
→ 平台回调服务端
→ 服务端验签 + 验金额/币种/SKU/状态
→ 数据库事务：订单 paid → grant_record 唯一写入 → 资产/库存/账本更新
→ 客户端查询订单并刷新服务端状态
```

必须测试：伪造客户端成功、回调重放、回调乱序、支付成功客户端断网、重复点购买、金额/SKU 不匹配、发货事务中断、退款/撤销、限购并发。任一情况下都不能重复发货或让客户端直接加星钻。

## 7. 云存档与断网

- 最低 L1：每次升级、抽取、支付发货、赛季领奖立即提交；普通 UI 操作用 3–10 秒节流合并。
- `version` 冲突时服务端资产/账本优先；客户端不能用旧档覆盖新支付资产。
- 断网允许进入基地只读、查看本地最后快照；禁止付费、升级、抽取、赛季交付。
- 出航中断：服务器已有 `sortie_session`。重连后允许继续剩余时间，或按最后确认归仓事件结算；不能重复扣能源。
- 卸载/换机后从云端恢复五维、库存、保底、月卡、赛季、订单；双设备验证列入 P11 验收。

## 8. 反作弊与榜单

- 排行只取服务端 `season_score`，它只由已验 `sortie/finish`、合约和加工结算增量产生。
- 单局最大回收、稀有件数、事件时间间隔、每日贡献有规则上限；超界先标审核，不静默吞资产。
- 同段位分组以赛季开始前服务端资产快照与活跃度为准，赛中付费不会换组。
- 测试阶段的机器人必须标“训练数据”；商业正式榜只显示真人，不制造虚假社交压力。
- 后台提供异常贡献、订单/发货不一致、货币负值、保底跳变、配置版本错配告警。

## 9. 远程配置与 LiveOps

以下全部版本化、可灰度、可回滚：

- 星区密度、掉落、伪随机保底、局时、载重减速。
- source/sink、升级曲线、能源恢复、广告日限额。
- SKU 内容、真实起止时间、限购、免费路径文案。
- 联赛起止、分组、贡献软上限、升降段、奖励。
- 埋点 schema、实验桶与功能开关。

发布纪律：一次只改一个商业变量；经济配置需模拟器和审批人签字；商品到期由服务端状态决定，不依赖客户端倒计时。

## 10. 合规前置

### 中国大陆

- 公开联网运营前确认版号/出版审批、小游戏/应用备案、软件著作权、ICP/运营主体等当期要求；国家新闻出版署许可服务页面的公开时限口径不能当作项目保证工期。[国家新闻出版署审批服务](https://www.nppa.gov.cn/bsfw/xksx/cbfxl/wlcbfwspsx/202210/t20221013_600725.html)
- 全用户实名并接入国家防沉迷系统；未成年人仅允许在现行规定时段游戏。[国家新闻出版署 2021 通知](https://www.nppa.gov.cn/xxfb/tzgs/202108/t20210830_666285.html)
- <8 岁禁付费；8–15 岁单次 ≤¥50/月 ≤¥200；16–17 岁单次 ≤¥100/月 ≤¥400。[国家新闻出版署付费限额](https://www.nppa.gov.cn/xxfb/zcfg/gfxwj/201911/t20191119_4503.html)
- 抽取概率、保底、重复转化在购买前就近公示；未成年人默认关闭付费随机入口。
- 消费确认页写人民币金额、道具/服务、限购、到期、理性消费与客服/退款；交易日志至少按法规/平台要求保存。

### 平台

- 微信/抖音支付分成、iOS 虚拟支付、广告奖励凭据、分享能力以提审时官方后台/合同为准，本文不写死分成。
- 广告必须用户主动；插屏仅自然断点。禁止“必须分享到不同群才能继续”。
- 上线前由发行/法务做一次当期规则核验；本文不是法律意见。

## 11. 8 周计划

| 周 | 目标 | 可验收输出 |
|---|---|---|
| W1 | 核心磁吸/尾巴/归仓、输入、对象池；三套素材镜头 | 真机 60 FPS 玩法；3 秒可读性测试 |
| W2 | 结算、五维升级、唯一资产、首轮 UI；裸玩法埋点 | 可玩 Demo；首局/二局测试，不接商业化 |
| W3 | 星区表、资源经济、离线航线、成员/遗物、L1 云存档 | 3 日闭环；双设备恢复 |
| W4 | L2 出航校验、账本、联合合约；30 天模拟器校准 | 客户端改币/改分被拒；合作双账号 |
| W5 | 联赛分组/榜单/结算、后台配置、异常审核 | 50 账号压测；赛季时间加速演练 |
| W6 | 商店、首充/月卡/战令、支付沙箱与幂等发货 | 断网/重放/重复下单测试全过 |
| W7 | 实名防沉迷、概率/价格/限购、广告/分享、全量埋点 | 合规清单与数据看板；只在测试环境开放 |
| W8 | 分包/性能/弱网/兼容/无障碍、提审包、应急预案 | 上线候选；支付/赛季回滚演练 |

版号/备案/平台审核是并行外部关键路径，不能用“开发完成”代替；若外部资质未完成，只能继续做无真实 IAP 的内测/素材测试。

## 12. Demo 与正式版差距

| 能力 | 本交付 Demo | 正式版必须补齐 |
|---|---|---|
| 存档 | 浏览器 localStorage + 统一 SDK 的 H5 云双写模拟 | 真实平台登录、云数据库、乐观锁、双设备 |
| 结算 | 本地规则 | 服务端种子、摘要校验、账本事务 |
| 排行 | 静态测试对手，明确 Demo | 真人分组、服务端榜、异常审核、结算 |
| 商店 | 模拟领取，不发起支付 | 订单/平台回调/验签/幂等发货/退款 |
| 广告 | 2 秒模拟 | 平台激励视频、完播判断、场景日限额 |
| 内容 | 1 星区、5 维升级、少量对象 | 6 星区、30 天表、2 赛季、8 成员/6 舰体 |
| 合规 | 文案和门禁占位 | 资质、实名、防沉迷、适龄、平台审核 |