MapPoster Online

在线地图海报生成器，基于 OpenStreetMap / Protomaps 数据生成复古风格地图图片。

Filetree

• 开始动手前先查看 FILETREE.md，快速了解当前仓库的文件职责与目录结构
• 当需要判断某个文件应该改哪里时，优先参考 FILETREE.md，再深入阅读目标文件
• FILETREE.md 是自动维护文件；新增、重命名、删除或明显改变文件职责后，应同步更新

技术栈

• 构建: Vite 7 + Bun
• 前端: React 19 + TypeScript
• 样式: Tailwind CSS v4 (@tailwindcss/vite)
• UI: Radix UI + lucide-react
• 地图: @mapbox/vector-tile + pbf + proj4
• WASM: Rust (wasm-pack) 用于地图渲染
• i18n: @inlang/paraglide-js
• 缓存: IndexedDB (idb)

目录结构

src/
├── components/
│   ├── ui/           # Radix UI 封装组件 (button, card, dialog...)
│   └── *.tsx         # 业务组件
├── lib/
│   ├── utils.ts      # cn() 工具函数
│   └── types.ts      # 共享类型
├── services/         # 数据服务 (地图 API、POI)
├── hooks/           # React hooks
├── pkg/             # WASM 编译产物 (自动生成)
├── paraglide/       # i18n 消息 (自动生成)
├── worker.ts        # Web Worker 入口
└── index.css        # Tailwind v4 配置 + CSS 变量主题

常用命令

bun dev            # 启动开发服务器
bun build          # 构建生产版本
bun build:wasm     # 构建 WASM (需先 cd wasm)
bun lint           # 代码检查
bun preview        # 预览构建产物

React 组件规范

1. 样式: 使用 cn() 组合类名

   import { cn } from '@/lib/utils'
   <div className={cn("base-class", condition && "conditional")} />

2. UI 组件: 基于 Radix UI，在 components/ui/ 中封装
3. 组件导入路径: 使用 @/ 别名指向 src/

Tailwind CSS v4

• 配置在 src/index.css 中，使用 CSS-first 方式
• 自定义颜色通过 CSS 变量定义 (--background, --primary 等)
• 暗色模式: .dark 类 + @custom-variant dark

@theme inline {
  --color-background: var(--background);
  --color-primary: var(--primary);
  /* ... */
}

WASM 初始化

import init, { init_panic_hook } from './pkg/wasm'

// App 入口处调用一次
useEffect(() => {
  init().then(() => init_panic_hook())
}, [])

注意: 必须配合 vite-plugin-wasm 和 vite-plugin-top-level-await

测试注意事项

• WASM 测试: init() 必须在测试 setup 中 mock，避免真实加载 .wasm 文件
• Worker 测试: 使用 runInWorker() 的模块需 mock Worker 环境
• IndexedDB: idb 缓存层需在测试中用 fake-indexeddb 替代
• 渲染输出: WASM 最终产出为 canvas/图片，断言时用视觉快照（snapshot）而非 DOM

特殊约定

1. 并行数据获取: mapDataService 内部有轮询机制，多请求可命中不同镜像站
2. Web Worker: 使用 runInWorker() 辅助函数，协议 { id, type, data }
3. Transferable: 大数据用 Transferable[] 传递避免拷贝
4. 渲染流程: 主线程协调 → Worker 并行处理 → WASM 最终渲染
5. LOD 模式: simplified / detailed 影响地图细节级别

i18n

• 消息源: messages/*.json
• 编译后: src/paraglide/messages.js
• 使用: import * as m from '@/paraglide/messages'
• 动态语言: setLocale() / getLocale() from @/paraglide/runtime

Skills

Claude 在处理对应任务前，必须先读取相关 SKILL.md，再动手写代码。

各 Skill 适用场景说明

frontend-design — 适用于：

• 新增或改造 src/components/ 下的任何组件
• 调整地图海报的视觉风格、排版、配色
• 复古风格 UI 的实现（与本项目主题高度相关）

webapp-testing — 适用于：

• 测试 WASM 渲染流程（init → Worker → 输出）
• 验证 mapDataService 的并行请求和镜像轮询逻辑
• 测试 Web Worker 消息协议 { id, type, data } 的正确性
• 验证 Transferable 大数据传输不出现拷贝或内存泄漏

web-artifacts-builder — 适用于：

• 快速原型验证某个地图渲染参数的效果
• 独立演示某个 UI 组件（不依赖完整构建链）
• 调试 LOD 模式（simplified / detailed）的视觉差异