开发指南
项目结构
两个应用、共享包与平台组合根的真实目录。
MuseMVP 是 pnpm workspace。apps/web 和 apps/web-cloudflare 各自拥有完整页面副本；共享工厂、类型、纯函数和环境 schema 放在 packages/*，不抽成共享页面包。
目录与职责
| 入口 | 职责 |
|---|---|
apps/web/src/app、src/modules | Vercel/Docker 的路由、UI 与功能编排 |
apps/web-cloudflare/src/app、src/modules | Workers 的完整页面副本 |
每个应用的 src/server | 平台组合根：数据库、邮件、存储和运行时依赖 |
每个应用的 src/backend/database | 绑定包查询与本应用 schema/driver 的包装层 |
每个应用的 src/backend/auth、src/backend/api | Better Auth 与 Hono 的应用接线 |
每个应用的 src/env | 从包级 ./env 组合的环境 schema 与启动校验 |
每个应用的 content/、source.config.ts | 文档、博客、法律页和更新日志 MDX 源码 |
packages/db | Postgres/D1 schema、迁移、查询函数；查询第一个参数为 db |
packages/auth、api、billing、mail、storage | 领域工厂与可复用实现 |
packages/config、i18n、ui、shared | 配置、双语消息、UI 与纯函数 |
packages/cli、testing、tsconfig、vitest-config | 初始化、测试与工具链 |
tests/unit、tests/api、tests/e2e | 逻辑、HTTP 契约与浏览器旅程 |
apps/web 用 Postgres 连接池与 S3 兼容存储；apps/web-cloudflare 用 D1 DB、R2 R2_BUCKET 和 Cloudflare Email Sending。平台差异留在组合根，不加运行时连接策略开关。
扩展链路
packages/db 查询 → 应用 database 包装 → modules/<feature>/lib → Hono routes → api-client → UI
包不能导入 @/；应用内部使用 @/*，包之间使用 @musemvp/*。模块和组件不直接访问数据库。校验在表单/路由边界使用 Zod，mutation 后保留 TanStack Query 缓存失效。
页面副本对齐
pnpm apps:parity
pnpm apps:parity --write默认命令只检查；--write 将 apps/web 同步到 apps/web-cloudflare，使用前检查 diff。平台文件（src/server、src/env、数据库 schema 包装、部署配置等）不会覆盖。不要手工修改生成的 .source/ 或 cloudflare-env.d.ts。
选定平台后可以裁剪另一应用，但必须同时调整根脚本、workspace、测试与文档；不能只删目录就假定所有命令仍可用。