chore: initial commit — import worldmodel workspace (plans/, research/)

2026-05-20 21:43:57 +08:00
commit bec8a9a4a3
98 changed files with 44128 additions and 0 deletions
@@ -0,0 +1,202 @@
+# CrowdRoom · 总览（v0.1）
+
+> **一句话定义**：CrowdRoom 是「**RoomPlan 版的 Sketchfab + Pinterest**」——人人用 iPhone 扫一个房间，传到云端就有可在浏览器里 360° 把玩、分层切换、换家具换材质、Remix 再创作的 3D 房间社区。
+
+本章是 CrowdRoom 的总览，与既有 [`plans/PRISM/00_overview.md`](../PRISM/00_overview.md) 对齐：PRISM 是「机器人空间记忆操作系统」，CrowdRoom 是它的**消费级前台与数据入口**——把"专业机器人技术栈"和"普通用户的手机"用一个社区粘合起来。
+
+---
+
+## 1. 产品定位
+
+| 维度 | 描述 |
+|------|------|
+| 一句话 | "RoomPlan 版的 Sketchfab + Pinterest"：扫房 → 上传 → 共享 → Remix |
+| 内容形态 | 一个房间 = 一份 RoomPlan 源文件（`.usdz` + JSON）+ 服务端转码出的 `.glb` + 4 层可切换图层 |
+| 核心动作 | **Scan → Upload → View → Toggle Layers → Remix → Share** |
+| 区别于 Sketchfab | 不是任意 3D 模型库，而是**结构化的真实房间**（带语义：墙/地/家具/材质） |
+| 区别于 Polycam 社区 | Polycam 偏个人云盘，CrowdRoom 偏**公共内容流 + Remix 文化** |
+| 区别于 ArcGIS | 不做专业 GIS 查询，**只做"分层显示/隐藏/替换"这种消费级图层操作** |
+
+CrowdRoom 不和 PRISM 抢机器人场景，它解决的是「**怎么让 RoomPlan 数据从一个人的相册变成一个生态**」的问题。
+
+---
+
+## 2. 目标用户画像
+
+| 画像 | 标签 | 典型行为 | 核心诉求 |
+|------|------|----------|----------|
+| **A · 扫房爱好者**（Scanner） | 极客、博主、Polycam 老用户、租房博主 | 周末扫家、扫民宿、扫展览，上传炫技 | 上传顺、出图快、获赞获关注 |
+| **B · 灵感党**（Browser） | 室内设计学生、装修业主、ins/小红书图源党 | 不扫，只逛；收藏好看的房间作灵感板 | 浏览流畅、能搜风格、能收藏分组 |
+| **C · Remixer**（创作者） | 设计爱好者、3D 玩家、UGC 创作者 | 拿别人扫的房间，换墙纸/换沙发/隐藏家具发"我的版本" | 操作低门槛、能版本对比、能 fork |
+
+三类用户构成**采集 → 消费 → 再创作**的内容飞轮，对应 [`plans/iphone/iphone_simplified_plan.md`](../iphone/iphone_simplified_plan.md) 里"个人验证用 RoomPlan"的轻量场景，但把生产者从 1 人扩到 N 人。
+
+---
+
+## 3. 核心用户故事（MVP 范围内 8 条）
+
+| # | As a | I want to | So that |
+|---|------|-----------|---------|
+| US-1 | 扫房爱好者 | 在 iOS App 里调用 RoomPlan 扫完房间一键上传 | 不用导出 USDZ 再手动传 |
+| US-2 | 扫房爱好者 | 上传时给房间打标签（户型 / 风格 / 城市）并选择公开/私有 | 控制我作品的可见性与隐私 |
+| US-3 | 灵感党 | 在浏览器里 360° 旋转、缩放、走进一个房间 | 不装 App 就能看 |
+| US-4 | 灵感党 | 用复选框开关 **墙 / 地板 / 家具 / 材质** 四个图层 | 像 ArcGIS 那样按需查看结构或装饰 |
+| US-5 | Remixer | 把家具图层里的某件家具替换为公共资产库里的另一件 | 不重新建模就能做"装修方案" |
+| US-6 | Remixer | 把墙面/地面材质换成公共材质库里的另一种 | 快速试色 / 试材质 |
+| US-7 | 任何用户 | 给一个房间点赞、评论、收藏到画板 | 形成社区互动 |
+| US-8 | 扫房爱好者 | 上传前由 App 自动模糊照片中的人脸/身份证/品牌 logo | 默认隐私安全，不用我手工检查 |
+
+> 故意**不包含**的 user stories：实时多人协同编辑、复杂 BIM/CAD 出图、专业 GIS 空间查询、跨房间拼接成楼层——见 §7 非目标。
+
+---
+
+## 4. 总体架构图
+
+```mermaid
+graph TD
+    subgraph CLIENT["客户端层"]
+        IOS["iOS App<br/>(RoomPlan SDK 采集 + 上传客户端)<br/>Swift / SwiftUI"]
+        WEB["Web 前端<br/>(浏览/分层/Remix)<br/>React + R3F + Three.js"]
+    end
+
+    subgraph BAAS["Supabase BaaS 层"]
+        AUTH["Auth<br/>邮箱/Apple/Google 登录<br/>JWT 下发"]
+        DB["Postgres<br/>rooms / layers / remixes /<br/>comments / likes 表"]
+        STG["Storage<br/>原始 .usdz + JSON<br/>+ 转码后 .glb"]
+        EDGE["Edge Functions<br/>上传回调 / 隐私脱敏触发 /<br/>排行榜聚合"]
+    end
+
+    subgraph WORKER["渲染与转码层"]
+        TRANS["Transcode Worker<br/>(USDZ → glTF/.glb +<br/>Draco/Meshopt 压缩)<br/>容器化 Node/Python"]
+        ASSET["Asset Library<br/>公共家具 .glb +<br/>PBR 材质贴图"]
+    end
+
+    subgraph CDN["分发层"]
+        EDGECDN["CDN<br/>(Cloudflare R2 / Bunny)<br/>直发 .glb 与缩略图"]
+    end
+
+    IOS -- "1. POST 上传 USDZ+JSON" --> STG
+    IOS -- "登录" --> AUTH
+    STG -- "2. 触发" --> EDGE
+    EDGE -- "3. 入队转码任务" --> TRANS
+    TRANS -- "4. 写回 .glb + layer manifest" --> STG
+    TRANS -- "5. 更新 status" --> DB
+    STG -- "公开资源" --> EDGECDN
+
+    WEB -- "查列表/详情" --> DB
+    WEB -- "登录" --> AUTH
+    WEB -- "拉 .glb / 贴图" --> EDGECDN
+    WEB -- "查公共素材" --> ASSET
+    ASSET --> EDGECDN
+```
+
+**关键说明**：
+- iOS App 是**唯一采集入口**（RoomPlan 仅 iOS）；Web 端只消费、不采集
+- BaaS（Supabase）= Auth + Postgres + Storage + Edge Functions 一站式，避免自建后端
+- Transcode Worker 与 Asset Library 是「服务器渲染/转码」的承载者，对应用户原话里的"服务器渲染"
+- CDN 直发 `.glb`，Web 端实际渲染发生在**浏览器** GPU（Three.js），服务端不做实时渲染——这是消费级路线的关键性价比决策
+
+---
+
+## 5. 技术栈选型表
+
+| 层 | 推荐 | 备选 | 一行理由 |
+|----|------|------|---------|
+| 移动端语言 | **Swift + SwiftUI + RoomPlan** | Flutter + 原生桥接 | RoomPlan 是纯 iOS API，原生 Swift 最薄 |
+| Web 框架 | **React + Vite + TypeScript** | Next.js / SvelteKit | React 生态最厚，与 R3F 无缝 |
+| 3D 渲染库 | **Three.js + React-Three-Fiber + drei** | Babylon.js / PlayCanvas | R3F 让"图层切换/换家具"用 React 组件思维直接表达 |
+| BaaS | **Supabase** | Firebase / Appwrite | 开源、Postgres 底座、便于后续平滑迁移到自建 |
+| 对象存储 | **Supabase Storage**（小流量）→ **Cloudflare R2**（量大后） | AWS S3 / Backblaze B2 | R2 零出口费，国内外访问都还行 |
+| CDN | **Cloudflare** | Bunny.net / 阿里云 CDN | 与 R2 同栈、免费额度大 |
+| 转码 Worker | **Node + `gltf-transform` + USD CLI**，跑在 **Fly.io / Railway 容器** | AWS Lambda（冷启动慢，pass） | gltf-transform 做 Draco/Meshopt 压缩成熟；USD CLI 解 `.usdz` |
+| 公共资产库 | **Google `<model-viewer>` Asset Pack + 自建 PBR 库** | Sketchfab API | 起步用免费 CC0 素材，避开版权 |
+| CI/CD | **GitHub Actions**（iOS 走 fastlane → TestFlight；Web 走 Vercel） | GitLab CI | 学习成本低、与 Supabase 集成方便 |
+| 监控 | **Sentry + Supabase Logs** | Datadog | 个人/早期项目够用 |
+
+> 该表只列**MVP 默认选项**；具体表结构、API 端点、转码流水线细节由后续子任务（`01_data_schema.md` / `02_api_contract.md`）展开。
+
+---
+
+## 6. 与 PRISM 的关系：复用与边界
+
+### 6.1 一句话定位
+
+> CrowdRoom = **PRISM 的"消费级前台 + 数据入口"**。
+> PRISM 解决"机器人怎么记住一个房间"，CrowdRoom 解决"普通用户怎么把房间贡献出来、怎么消费别人的房间"。
+> 两者共享同一份"RoomPlan → 结构化空间"的数据约定，但**生命周期、SLA、安全模型完全不同**。
+
+### 6.2 复用点（CrowdRoom 直接受益于 PRISM 的既有设计）
+
+| # | 复用项 | 来源 | 用法 |
+|---|--------|------|------|
+| R1 | **RoomPlan 数据格式约定**（USDZ + JSON 双文件，墙/门窗/家具/尺寸字段） | [`plans/iphone/data_format_specification.md`](../iphone/data_format_specification.md) §2-§3 | CrowdRoom iOS App 直接采用同一份 JSON Schema，避免双标 |
+| R2 | **RoomPlan 精度边界与扫描最佳实践** | [`plans/iphone/roomplan_accuracy_and_cad_export.md`](../iphone/roomplan_accuracy_and_cad_export.md) §1, §4.1 | 用于 App 内的扫描引导提示（"慢速移动 0.3 m/s""清理杂物"）和精度免责声明 |
+| R3 | **导出转换链 USDZ ↔ glTF/DXF** | [`plans/iphone/roomplan_accuracy_and_cad_export.md`](../iphone/roomplan_accuracy_and_cad_export.md) §3 | Transcode Worker 复用其 Python/Swift 思路，CrowdRoom 只取 USDZ → glTF 一条 |
+| R4 | **L3/L4 节点 + 属性的语义抽象**（房间是 L3、家具是 L4、`category/attributes/material`） | [`plans/PRISM/03_data_schema.md`](../PRISM/03_data_schema.md) §3.2 | CrowdRoom 的"分层 = L1/L2/L3/L4 的简化映射"：墙/地→L2 度量，家具→L4 语义节点；4 层图层是 PRISM 四层的**降维投影** |
+| R5 | **简易方案的快速验证路径**（一人一机一周跑通） | [`plans/iphone/iphone_simplified_plan.md`](../iphone/iphone_simplified_plan.md) §五 | 直接借作 CrowdRoom MVP 的扫描端工时基线 |
+
+### 6.3 暂不引入的 PRISM 特性（边界）
+
+| 不引入 | 理由 | 何时再考虑 |
+|--------|------|-----------|
+| **Pipeline B 重定位** ([`05_pipeline_B_relocalization.md`](../PRISM/05_pipeline_B_relocalization.md)) | CrowdRoom 没有"机器人上线"的概念，无需 CLIP+ICP 握手 | 若未来做 AR Quicklook 多次访问对齐才需要 |
+| **Pipeline C 在线感知** ([`06_pipeline_C_online_perception.md`](../PRISM/06_pipeline_C_online_perception.md)) | ZED 2i 不在消费端硬件清单里 | 永久不引入（消费级路线决策） |
+| **Pipeline D 巩固 / Delta 差异记忆** ([`07_pipeline_D_consolidation.md`](../PRISM/07_pipeline_D_consolidation.md)) | 用户每次扫描视为**独立作品**而非同一空间的更新 | 若做"扫描日记/同一房间历史对比"功能再启用 |
+| **KeyframeEvidence、Anchor、Delta 字段** ([`plans/PRISM/03_data_schema.md`](../PRISM/03_data_schema.md) §3.2.1) | 这些是为机器人翻案与巩固设计的，与社区浏览无关 | 永久不引入 |
+| **Neo4j / Cypher 查询** | 消费级查询用 Postgres 全文索引足够 | 若引入"空间 SQL"（P2）再讨论 |
+| **PostGIS / 专业空间查询、LOD、楼层拼接** | 用户已明确划入 P2/未来 | 当单房间日活上 10 万级、用户主动要"按城市/按户型查询"才上 |
+
+> **原则**：CrowdRoom 是 PRISM 的**只写入口 + 只读消费**；它产出的数据可被 PRISM 后续 import 作为先验地图源（"普通用户贡献先验"是诱人的长期愿景，但**不在 MVP 范围内**）。
+
+---
+
+## 7. MVP 范围与非目标
+
+### 7.1 MVP 8 周内能交付（围绕 §3 的 8 条 user stories）
+
+| 模块 | 交付物 |
+|------|--------|
+| iOS App（TestFlight） | RoomPlan 采集 + USDZ/JSON 导出 + 上传 + 标签 + 隐私脱敏（人脸模糊） |
+| Web 前端 | 列表页 / 详情页 / R3F 渲染器 / 4 层图层切换 / 公共素材替换 / 评论点赞 |
+| Supabase 后端 | Auth、`rooms / layers / remixes / comments / likes / assets` 7 张核心表、Storage 桶、上传回调 Edge Function |
+| Transcode Worker | USDZ → `.glb`（Draco 压缩） + 生成 `layer_manifest.json`（4 层引用） |
+| 公共资产库 | ≥ 30 件家具 `.glb` + ≥ 20 种 PBR 材质（CC0 来源） |
+| 内容审核 | 上传时静态规则 + 人工 review 队列（暂不做 AI 审核） |
+
+### 7.2 明确不做（MVP 外）
+
+- ❌ Android / Web 端采集（RoomPlan 仅 iOS，**且不引入 Android ARCore 替代**——避免数据双标）
+- ❌ 实时多人协同编辑（Remix 走 fork 模型，不走 OT/CRDT）
+- ❌ 空间 SQL / 任意自定义图层 / PostGIS 查询（P2）
+- ❌ LOD、楼层拼接、跨房间空间索引（P2）
+- ❌ 商品化（链接到电商）、付费墙、订阅
+- ❌ 机器人接入 / PRISM Pipeline B-D 任何一项
+- ❌ 自训练 3D 基础模型（家具识别一律用 RoomPlan 内置语义 + 公共资产匹配）
+
+---
+
+## 8. 风险与开放问题（≤ 5 条）
+
+| # | 风险 / 开放问题 | 当前判断 | 待后续子任务回答 |
+|---|----------------|---------|-----------------|
+| RK-1 | **RoomPlan 仅 iOS 且需 LiDAR**（iPhone 12 Pro+） | 接受为前提，等同于早期 Polycam 的市场范围；不做 Android 替代 | 是否在 Web 端也开放"上传第三方 USDZ"作为 PC 用户入口？ |
+| RK-2 | **`.usdz` 在 Web 端兼容性差**（Three.js 无原生 USDZ loader） | 服务端强制转 `.glb`，Web 端**只见 glTF** | 转码失败率、`.usdz` 中嵌入纹理/动画的边界由 [`02_transcode_pipeline.md`](02_transcode_pipeline.md)（待建）回答 |
+| RK-3 | **UGC 内容审核**：色情、违法建筑、他人住宅未授权扫描 | MVP 走"上传时声明 + 举报下架 + 人工 review"；不上 AI 审核 | 法律边界（中国大陆 vs 海外）、举报响应 SLA 由 `10_governance.md`（待建）回答 |
+| RK-4 | **隐私脱敏**：纹理里可能包含人脸、身份证、品牌 logo、镜子里的人 | 默认开启端侧 Vision 人脸检测 + 高斯模糊；镜面区域参考 PRISM `no_update_zone` 思想做警告 | 脱敏算法细节、用户能否关闭、是否服务端二次扫描由 `01_data_schema.md` + `09_privacy.md`（待建）回答 |
+| RK-5 | **存储与带宽成本**：单个房间 `.usdz` 5–50 MB，`.glb` 压后 1–10 MB；千用户日活即可烧光免费额度 | MVP 用 Supabase 免费额度 + Cloudflare R2 零出口费；设单用户上传配额 | 配额数值、冷热分层策略、缩略图分级由 `02_transcode_pipeline.md` 回答 |
+
+---
+
+## 9. 下一章预告
+
+| 子任务 | 待产出 | 关注问题 |
+|--------|--------|---------|
+| `01_data_schema.md` | Supabase 7 张表 DDL、`layer_manifest.json` Schema、与 PRISM L1-L4 的字段映射 | RK-4 隐私字段、§6 R4 复用怎么落 |
+| `02_api_contract.md` | REST/PostgREST + Edge Function 端点表 | 上传协议、转码回调、Remix fork API |
+| `03_ios_app_plan.md` | iOS App 模块拆解 + 隐私脱敏实现 | US-1, US-2, US-8 |
+| `04_web_app_plan.md` | Web 前端组件树 + R3F 图层渲染策略 | US-3~US-7 |
+
+---
+
+**章节版本**：v0.1 · 草案
+**关键收获**：CrowdRoom 是 PRISM 的消费级前台；走 Supabase + Three.js + iOS-RoomPlan 的三件套路线；MVP 8 周覆盖 8 条核心 user stories；专业 GIS 与 PRISM Pipeline B/C/D 明确划在 MVP 之外。