worldmodel/plans/CrowdRoom/README.md

# CrowdRoom · 项目入口（README）

> **一句话定位**：**RoomPlan 版 Sketchfab + Pinterest** —— 一个让普通 iPhone 用户「扫一扫家、传上来、被别人 Remix」的众包房间扫描共享平台。

> **电梯陈述（80 字）**：CrowdRoom 用 iOS RoomPlan 把每个房间变成一份「墙/地/家具/材质」四层数据，公开数据走 CDN，私有数据走 Supabase RLS，浏览器里直接在别人的房间上换材质、换家具、发表 Remix——零下载、零安装、零专业门槛。

> **当前版本**：v0.2（2026-05-19）· 设计阶段完成，等待进入 M1 实施。

---

## 1. 它解决什么 / 不解决什么

| 维度 | Matterport | Sketchfab | Polycam | **CrowdRoom** |
|------|-----------|-----------|---------|---------------|
| **目标用户** | 房产中介、企业 | 3D 建模师、艺术家 | 测绘爱好者、个人用户 | **普通 iPhone 用户 + 装修灵感党** |
| **采集硬件** | 专业 Matterport Pro 相机（数千美元） | 用户自带任意 3D 模型文件 | iPhone LiDAR（与本平台相同） | **iPhone 12 Pro+ RoomPlan**（消费级即可） |
| **核心交互** | 全景浏览 + 标注 | 上传 / 下载 3D 模型 | 扫描 + 导出 OBJ/USDZ | **图层切换 + 浏览器换材质换家具 + Remix** |
| **数据分层** | 平面图 + 全景 | 单一 mesh / glTF 节点树 | 单一 mesh | **4 个固定逻辑层**（墙 / 地 / 家具 / 材质） |
| **Remix 模型** | ❌ 无 | 衍生作品（下载再上传） | ❌ 无 | **✅ Fork 模型**（引用 + 覆盖层，零拷贝几何） |
| **社区/隐私** | 商用账号体系 | 公开为主 | 个人为主 | **默认私有 + 端侧人脸脱敏 + CC BY-NC 默认协议** |

**CrowdRoom 不解决的事**（[`00_overview.md`](00_overview.md) §7.2 已划入 MVP 外）：

- ❌ **Android / Web 端采集**——RoomPlan 仅 iOS，且不引入 ARCore 替代
- ❌ **实时多人协同编辑**——Remix 走 fork 模型，不上 OT/CRDT
- ❌ **专业空间查询**（PostGIS、空间 SQL、跨房间索引）——P2 再考虑
- ❌ **机器人接入与 PRISM Pipeline B/C/D**——CrowdRoom 是 PRISM 的**消费级前台**，不复用其重定位 / 在线感知 / 巩固管线
- ❌ **付费墙 / 订阅 / 链接电商**——MVP 走纯免费 + UGC 路线

---

## 2. 文档导航表

CrowdRoom 的 9 份设计文档（含本 README 与 [`ROADMAP.md`](ROADMAP.md)）按编号对齐到「**总览 → 数据 → API → 客户端 → 隐私治理 → 路线图**」六层叙事。

| # | 标题 | 路径 | 一句话摘要 | 建议读者角色 |
|---|------|------|------------|-------------|
| 00 | 总览 | [`00_overview.md`](00_overview.md) | 产品定位、架构图、技术栈、与 PRISM 的复用边界、MVP 范围、5 条根级风险 | **所有人**起点 |
| 01 | 数据模型与 Storage | [`01_data_schema.md`](01_data_schema.md) | Supabase 9 张表 DDL + RLS + Storage 目录 + `layer_manifest.json` JSON Schema | 后端 / SRE / Web 工程师 |
| 02 | API 契约与转码管线 | [`02_api_contract.md`](02_api_contract.md) | 19 个端点（含 v0.2 新增 E-17/18/19）+ 40 条错误码 + 转码序列图 + Remix 覆盖层 | 后端 / iOS / Web 工程师 |
| 03 | iOS App 设计 | [`03_ios_app_plan.md`](03_ios_app_plan.md) | 5 Tab 22 页面 IA + 端侧脱敏管线 + 三段式上传 + PrivacyManifest | iOS 工程师 |
| 04 | Web 端设计 | [`04_web_app_plan.md`](04_web_app_plan.md) | Next.js + R3F + 类 ArcGIS 图层面板 + 材质/家具替换 + Remix + OG 卡片 | Web 工程师 |
| 09 | 隐私设计 | [`09_privacy.md`](09_privacy.md) | 5 原则 PR-1~5 + 13 条契约（P-1~6 + P-W-1/2/7）+ GDPR/PIPL 合规清单 | 隐私 / 法务 / PM |
| 10 | 治理与社区规则 | [`10_governance.md`](10_governance.md) | 4 治理原则 GR-1~4 + UGC 审核流程 + 4 级处罚阶梯 + CC BY-NC 默认协议 + 退场承诺 | 法务 / 运营 / PM |
| – | 路线图 | [`ROADMAP.md`](ROADMAP.md) | 4 个里程碑（M1–M4）DoR/DoD + 12 条风险登记册 + 8 条 P2 候选 | PM / 创始人 / Tech Lead |
| – | 变更日志 | [`CHANGELOG.md`](CHANGELOG.md) | Keep a Changelog 风格，记录 v0.1（初版 7 文档）→ v0.2（10 个 G 漏洞修订）→ Unreleased | 所有 reviewer |

### 2.1 按角色推荐阅读路径

| 角色 | 推荐顺序（3–5 步） |
|------|-------------------|
| **PM / 创始人** | [`00`](00_overview.md) → [`09`](09_privacy.md) → [`10`](10_governance.md) → [`ROADMAP`](ROADMAP.md) |
| **iOS 工程师** | [`00`](00_overview.md) → [`03`](03_ios_app_plan.md) → [`02`](02_api_contract.md) → [`09`](09_privacy.md) |
| **Web 工程师** | [`00`](00_overview.md) → [`04`](04_web_app_plan.md) → [`02`](02_api_contract.md) → [`01`](01_data_schema.md) |
| **后端 / SRE** | [`01`](01_data_schema.md) → [`02`](02_api_contract.md) → [`09`](09_privacy.md) → [`ROADMAP`](ROADMAP.md) §4 风险登记册 |
| **隐私 / 法务** | [`09`](09_privacy.md) → [`10`](10_governance.md) → [`00`](00_overview.md) §6 PRISM 边界 → [`CHANGELOG`](CHANGELOG.md) |

---

## 3. 整体架构一图（精简版）

```mermaid
graph TD
    subgraph CLIENT[客户端层]
        IOS[iOS App<br/>RoomPlan 采集 + 端侧脱敏 + 三段式上传]
        WEB[Web 前端<br/>R3F + 4 层图层 + 材质家具替换 + Remix]
    end

    subgraph BAAS[Supabase BaaS]
        AUTH[Auth<br/>Apple / Google / Email]
        DB[Postgres 9 表<br/>+ RLS + tsvector 搜索]
        STG[Storage<br/>公开 + 私有 双桶]
        EDGE[Edge Functions<br/>19 端点]
        RT[Realtime<br/>转码进度推送]
    end

    subgraph WORKER[渲染与转码层]
        TRANS[Transcode Worker<br/>USDZ → glb + Draco/Meshopt]
        ASSET[Asset Library<br/>CC0 公共素材]
    end

    CDN[CDN<br/>Cloudflare R2 + Bunny]

    IOS -- 三段式上传 --> EDGE
    IOS -- 直传 --> STG
    EDGE -- 入队 --> TRANS
    TRANS -- 写回 .glb + manifest --> STG
    TRANS -- 状态更新 --> DB
    DB -- Realtime --> IOS
    STG -- 公开资源 --> CDN
    WEB -- 列表/详情 --> DB
    WEB -- 拉 .glb --> CDN
    WEB -- 公共资产 --> ASSET
    ASSET --> CDN
```

完整版本（含每条边的编号、时序、错误码）见 [`00_overview.md`](00_overview.md) §4。

---

## 4. 关键决策亮点 Top 10

从 7 份文档的「关键决策」中提炼最具方向性的 10 条：

1. **9 张表，不 7 张**——拆出独立 [`room_versions`](01_data_schema.md) 表承载转码异步状态、Remix 父锁定、重传不破坏旧链接（[`01_data_schema.md`](01_data_schema.md) §1 D1）。
2. **材质是逻辑层，不是 SQL 行**——4 层中只有「墙/地/家具」入 `layers` 表，「材质」在 [`layer_manifest.json`](01_data_schema.md) 内嵌 `slots[]`，一次拉取即可完整渲染（D4）。
3. **Remix = 引用 + 覆盖层，不深拷贝几何**——同一房间衍生 N 个 Remix 不复制 1–10 MB `.glb`，浏览器实时合成（[`02_api_contract.md`](02_api_contract.md) §4 D-A4）。
4. **三段式上传，不走 Edge Function 中转**——客户端 → Edge 拿 presigned → 直传 Storage → Edge 回调，避开 4 MB body 限制与冷启动计费爆炸（D-A2）。
5. **端侧脱敏不可降级**——人脸 `CIGaussianBlur` 必须在 iPhone 离开 App 进程前完成，服务端永不二次检测人脸（[`09_privacy.md`](09_privacy.md) §1 PR-1 + iOS-X1）。
6. **位置永远城市级 5 km 网格**——不收原始 lat/lon、不存 GPS 精确坐标，地理标签只是 `location_label` 字符串（PR-2 + [`01_data_schema.md`](01_data_schema.md) §3.2 G-10）。
7. **默认私有，发布显式**——`rooms.visibility` 默认 `private`，用户必须主动勾选「公开」才进入发现流，零误公开（PR-4）。
8. **父硬删 → 快照转移到 Remix，不连坐删除**——CrowdRoom 站队 GitHub fork 模型，不站队小红书「删笔记 = 删评论」（[`10_governance.md`](10_governance.md) §4 P-W-3 + GR-4）。
9. **MVP 全 CC0 公共资产库**——平台默认协议 CC BY-NC 4.0，但公共素材库严格只接 CC0；P1 起开放 CC-BY 走审核流水（[`10_governance.md`](10_governance.md) §4 P-W-4 + §8）。
10. **退场承诺：公开数据 CC0 镜像永久可访问**——若产品下线，所有 `visibility=public` 房间作为 CC0 镜像移交非盈利机构，对照 Reddit/Flickr「关张归零」形成差异化合规底色（[`10_governance.md`](10_governance.md) §10）。

---

## 5. 从这里开始（5 分钟入门）

> 目标：让一个新人在 5 分钟内对 CrowdRoom **是什么**与**该读什么**形成准确直觉。

1. **读 [`00_overview.md`](00_overview.md) §1–§2**（约 2 分钟）—— 拿到产品定位 + 目标用户画像。
2. **看本 README §3 架构图 + §4 Top 10 决策**（约 2 分钟）—— 一图 + 十条线索建立技术骨架。
3. **跳到自己角色对应的文档**（约 1 分钟入门，深入按需）—— 参考上方 §2.1 角色阅读路径表。

读完这 3 步后，你应能回答：
- ✅ CrowdRoom 和 Matterport / Sketchfab / Polycam 的本质区别是什么
- ✅ 数据从 iPhone 出来后经过哪几跳到达浏览器
- ✅ 4 个图层是哪 4 个、为什么材质是逻辑层
- ✅ 我作为 \<某角色\> 接手要先看哪 3 篇

---

## 6. 联系与贡献

- **项目方邮箱**（占位）：`team@crowdroom.example`
- **隐私 / DPO**（占位）：`privacy@crowdroom.example`（[`09_privacy.md`](09_privacy.md) §9 SDK 风险清单中引用）
- **滥用举报**（占位）：`abuse@crowdroom.example`（[`10_governance.md`](10_governance.md) §2.2 举报流程入口）
- **下线归档接收方**（待定）：Internet Archive / 某非盈利艺术机构（[`10_governance.md`](10_governance.md) §10）

### 6.1 文档变更 PR 流程（占位）

1. 任何对设计文档的修改必须以 PR 形式提交，且在 [`CHANGELOG.md`](CHANGELOG.md) 的 `[Unreleased]` 区块追加一行（Added / Changed / Fixed / Removed / Security 之一）。
2. 涉及 [`09_privacy.md`](09_privacy.md) 或 [`10_governance.md`](10_governance.md) 的修改，须 DPO + 法务双签。
3. 涉及 [`01_data_schema.md`](01_data_schema.md) 的字段语义变更，须 后端 + iOS + Web 三方签字（避免单方面破坏契约）。
4. 涉及 [`02_api_contract.md`](02_api_contract.md) 的错误码新增 / 修改，须保证向后兼容（不复用旧编号、不改旧语义）。

---

**文档版本**：v0.2 · 2026-05-19
**维护者**：CrowdRoom 设计组
**下一步阅读**：[`ROADMAP.md`](ROADMAP.md) —— 看 M1 MVP 8 周怎么落地。