⓪ 浅白版:整个平台,用开商场打比方(Jeff 版,5 分钟读完)

🏬 平台是什么:我们开了一座商场

HOOP Apps 平台就是一座商场。店(app)是别人开的,商场是我们的。 商场管四件事:给店面(代码放哪)、给仓库(数据放哪)、管装修换新(版本)、管开业资格(审核)。 —— 这正好就是你问的那四个问题,所以你问的框架是对的。

📸 「快照」是什么:每一版装修,拍一张永远不改的照片

店主每次改装修(改代码),我们不是在原来的墙上涂改,而是把整套新装修完整存一份, 编上号:第 1 版、第 2 版、第 3 版……存进去之后就封死,永远不再动 —— 这就是「快照」。 就像拍立得照片:拍下来就是那个样子,谁也改不了。

为什么要这样做?因为只要旧照片都在,就永远回得去。 第 3 版上线发现是坏的?把牌子指回第 2 版就完了(这就是「回滚」)—— 一秒钟,不用重做任何东西。 如果当初是在原墙上涂改,旧的样子就没了,坏了就只能哭。

🪧 live 和 staging:门口挂两块牌子

每家店门口有两块牌子: 「live」牌子指着哪一版,顾客看到的就是哪一版; 「staging」牌子指着店主正在试的新版 —— 只有店主自己、他的 AI 帮手、还有他拉进"试衣间群"的人看得到。 按一下「上线」按钮 = 把 live 牌子挪到新照片上。牌子随便挪,照片永远不动。

试的新版怎么防外人偷看?看新版要一张一小时就过期的门票(进店时我们发的), 没票的人来了,我们连"这里有个新版"都不承认(直接说"没有这东西")。

🗄️ 数据放哪:每家店有两种储物

① 顾客的带锁抽屉:顾客在店里存的东西(游戏进度、收藏),每人一个抽屉,钥匙只在顾客手上。 店主打不开 —— 他只能知道"一共有几个抽屉、总共多重",看不到里面是什么。 这一条是我们和微信不一样的地方:微信的店主翻得到顾客的数据,我们故意不给。这是 HOOP 的隐私招牌。

② 店里的公告板:店主要给所有顾客看的内容(餐厅名单、新闻栏目),写在公告板上,人人看到同一份。 店主随时能改,顾客只能看。

另外顾客在每家店里用的是假名(每家店一个不同的代号):店主永远不知道顾客真名是谁, 两家店也对不上"这是同一个人"。真名以后要经顾客自己点头才给。

🛃 上传的代码要过安检机

店主上传的每一份装修材料,进门先过安检:不许私联外网、不许夹带执行外来代码的暗门, 查出一条就整包退回(会告诉他退货原因)。太大的包(炸弹包)、想溜出自己店面偷别家东西的路径,一律拒收。

🚪 开业要审,翻新不审

新店第一次开门,要我们(管理员,只有你和你指定的人,AI 无权批)点头才对顾客可见; 开了业之后店主翻新装修,不用再排队 —— 只审"能不能开业"这一次,不卡人家做生意。

📏 每家店的额度(白纸黑字)

⚠️ 还没做完的三件(不瞒你)

① 现在任何一个 AI 帮手都能进任何一家店当店员 —— 今天店全是我们自己的,没事; 以后外面的人来开店,这条必须收紧(只有店主授权的帮手才能进)。 ② 商场最值钱的服务 —— 帮店主接上顾客的朋友关系、支付 —— 门还没开(故意的:先立规矩再开门)。 ③ 店主还没有一个好看的柜台界面,现在全靠 AI 帮手代办(界面要等下一班 TestFlight)。

① 我们对标谁,各学哪半

② 总架构(一张图)

┌─ 用户端(App)──────────────────────────────────────────────┐
│ 底栏第二格长按 → 「Apps」页(列表,本地优先缓存)               │
│   └→ 全屏壳 MiniappWebViewScreen                             │
│        ├ 先握手 POST /v1/apps/{id}/launch(影子身份+版本分流)  │
│        └ 注入 window.hoopApp 桥(init/user/storage,文档流之前)│
└──────────────────────────┬──────────────────────────────┘
                           │ 用户 JWT(app 永远拿不到)
┌─ 后端 miniapp 域(Go,独立于 games)────────────────────────┐
│ 目录 miniapps · KV miniapp_kv · 图像 miniapp_media            │
│ 版本双指针 live/staging · 留痕 miniapp_promotions · 一房一app   │
└───────┬───────────────────────────┬─────────────────────┘
   Postgres(云库)                  R2 对象存储
   目录/KV/图像账/留痕          miniapps/{app}/v{N}/index.html
                                miniapps/{app}/media/{uuid}

③ 开发者旅程(Jeff 2026-08-13 原话 = 产品流程定案)

④ 目录与身份

功能

平台的「账本」:有哪些 app、归谁、什么状态。用户打开 app 的那一刻,拿到的是影子身份 —— app 永远不知道你是现实中的谁。

操作

用户侧:Apps 页(GET /v1/apps,只列 active)→ 点开 → POST /v1/apps/{id}/launch
launch 返回:{ app_id, app_user_id: "a_…", sdk_version, capabilities:[], entry_url(按身份分流好版本) }
draft 状态的 app:owner / AI 分身可打开(真机测试),其他人 404 当不存在

代码

⑤ 数据库(HOOP 云开发第一块 —— 微信云数据库的位置)

功能

每个 app × 每个影子用户,一个 KV 命名空间。小开发者/AI 造的 app 零服务器就能有"记忆"(收藏、进度、用户内容)。

操作(app 里的代码就这么写)

await hoopApp.storage.set('fav', 'Penang');   // 存
const v = await hoopApp.storage.get('fav');    // 取 → "Penang"
await hoopApp.storage.set('fav', null);        // 删

代码

生产实测:写→读回 / 换人读同键=null(隔离)/ 删→null,四路全过。

⑥ 图像库

功能

每个 app 独立媒体库:传图 → 拿永久地址 → app 里 <img> 直接用。

操作

上传:POST /v1/dev/apps/{id}/media   (body=图片字节, Content-Type: image/*)
      → { id, url:"/miniapp-media/{app}/{id}", mime, size }
列表:GET  /v1/dev/apps/{id}/media
直出:GET  /miniapp-media/{app}/{mid}   (公开,无鉴权头 —— WebView 里的 img 用)

代码

⑦ 代码上传与版本管理(live / staging 双指针)

功能

「修改的时候不影响线上」:每次上传产出一个不可变版本快照,库里两个整数决定谁看哪版。 上线/回退 = 改一个整数,零文件搬运、天然原子。这套双指针与游戏平台同构(games 000205 先行验证过)。

操作

传代码:POST /v1/dev/apps/{id}/code (body=index.html)
        → staging_version = max(live, staging)+1   ← 版本号服务器发,客户端不数
自己试:launch 自动把 owner 指到 staging 版
上线:  POST /v1/dev/apps/{id}/promote
        → live = staging;留痕(谁/何时/从几到几);首次上线自动 draft→active(=上架)
直出:  GET /miniapp-code/{app}/v{N}/   (immutable:版本内容永不变)

代码与判据

⑧ App 工作房(「在群里测」)

功能

一个 app 挂一间工作房;房里所有成员自动看到测试版 —— 名单不是名单,是房间成员本身,进人出人可见范围自动跟(不另建内测名单表,那种表必然和房间漂)。

操作

绑房:POST /v1/dev/apps/{id}/workroom {conversation_id}   (空串=解绑)
规则:必须是工作房 + 本人建的;一房一 app(唯一索引 uniq_miniapps_workroom 兜底)

⚠️ 复盘 🔴#3:games 的绑房还查「房里除系统消息一条正文都没有」(必须新房),Apps 这边我漏抄了 —— 见 ⑫。

⑨ 用户端(App 里长什么样)

⚠️ App 侧改动等下一班 TestFlight;后端全部即时生效。

⑩ SDK 能力面(window.hoopApp)—— 「扶持」的落点

⑪ 隐私闸(和微信最大的不同,品牌线)

• 默认影子身份:app 天生不知道你是谁;游戏/小程序影子分域,拼不上是数学事实
• 关系链 API 全过 is_shadowed 闸:暗影好友绝不出现在任何 app 的任何返回里
• 六度只给数字不给路径:路径就是社交图,给了就回不了头
• 真名/头像 = consent 记录在案(谁/何时/同意了什么,000189/000193 现成)

⑫ 复盘:不完善清单(按危险排序,诚实的)

🔍 2026-08-19 全包审计(Jeff 派题:「审计我们的小程序 Apps 平台的代码」)

⑬ 路线图(Jeff 2026-08-15 定框架重排:托盘 = 定规矩 + 定空间)

相关:MINIAPP_PLATFORM.md(判据与拍板过程)· GAME_STAGING.md(双轨先行者,含 8 条评审)· GAME_PLATFORM_SPEC.md(影子身份)· GAME_KIT.md(烘焙库模式)· DEVELOPER_PLATFORM.md(审核分成)。 本页由架构线维护;改了实现记得回来改这页 —— 图纸最坏的状态不是没有,是看起来像真相。