IM@S WORLD P名片交换地图

一个面向偶像大师系列粉丝的事务所地图、线上名片墙、名片交换和留言社区。当前仓库包含可运行的 React Web 应用与 Cloudflare Worker API。

这是非官方粉丝项目。示例数据不包含官方角色素材；正式运营前需要补充品牌与用户上传内容的授权、投诉和下架机制。

技术栈

• Web：React 19、Vite、TypeScript、MapLibre GL、Lucide
• API：Cloudflare Workers、Hono、TypeScript
• 登录：Google OpenID Connect、GitHub OAuth、Arctic
• 元数据：Cloudflare D1
• 名片图片：Cloudflare R2，通过 Worker 流式写入与读取
• 本地开发：Wrangler 本地 D1/R2 仿真

本地运行

要求 Node.js 22 和 pnpm 11.10+。

pnpm install
pnpm db:migrate
pnpm db:seed
cp apps/api/.dev.vars.example apps/api/.dev.vars
pnpm dev

• Web：http://localhost:5174
• API：http://localhost:8787
• 健康检查：http://localhost:8787/health

本仓库把 Web 固定在 5174，避免和工作区内已经使用 5173 的服务冲突。只运行某一端时可用：

pnpm --filter @imas-world/web dev
pnpm --filter @imas-world/api dev

OAuth 本地配置

在 Google Cloud Console 创建 Web OAuth client，并在 GitHub Developer Settings 创建 OAuth App。开发环境的回调地址分别是：

http://localhost:8787/api/auth/google/callback
http://localhost:8787/api/auth/github/callback

把 Client ID/Secret 写入 apps/api/.dev.vars。应用只请求 Google 的 openid profile 和 GitHub 的公开资料，不请求邮箱、仓库或写权限，也不会保存第三方 access token。

验证命令

pnpm typecheck
pnpm build

pnpm build 会构建 Web 产物，并对 Worker 执行 wrangler deploy --dry-run。D1 本地状态在 apps/api/.wrangler/ 中，不会提交到版本库。

部署前配置

1. 创建 D1 数据库和 R2 bucket，并把 apps/api/wrangler.jsonc 中的本地 D1 ID 替换为真实 ID。
2. 把 ALLOWED_ORIGIN 改成 Web 生产域名。若 Worker 经代理后无法从请求 URL 判断公开域名，再设置 PUBLIC_API_URL；Web 域名与 ALLOWED_ORIGIN 不同时设置 APP_ORIGIN。
3. 在 Google/GitHub 后台登记生产回调 https://<API 域名>/api/auth/<provider>/callback，然后设置四个 secret：

pnpm --dir apps/api exec wrangler secret put GOOGLE_CLIENT_ID
pnpm --dir apps/api exec wrangler secret put GOOGLE_CLIENT_SECRET
pnpm --dir apps/api exec wrangler secret put GITHUB_CLIENT_ID
pnpm --dir apps/api exec wrangler secret put GITHUB_CLIENT_SECRET

4. Web 和 API 最好部署在同一主域的子域名下；跨站部署使用 SameSite=None; Secure，仍可能受浏览器第三方 Cookie 策略影响。
5. 执行 wrangler d1 migrations apply imas-world --remote 和生产种子/初始化流程。
6. 部署 Worker，再给 Web 设置 VITE_API_BASE_URL 后构建部署。
7. 上线前继续补充写接口限流、图片内容审核、举报和封禁链路。

更完整的数据流、存储和扩展边界见 docs/architecture.md。