lanrtop/react-phone-apps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
010abaa394
react-phone-apps/CLAUDE.md

3.8 KiB
Raw Blame History

react-phone-apps

项目蓝图

蓝图工作流规则统一维护在 @AGENTS.md 的 BLUEPRINT_MANAGED 区（跨工具单一来源，勿在此复制）。

对话开始时必须执行：

  1. 读取 .blueprint/manifest.yaml 了解项目全景和当前状态
  2. 读取 .blueprint/CONVENTIONS.md 了解完整工作流规则
  3. 遵循 AGENTS.md 中的蓝图工作流（需求→蓝图同步、复杂度决策、两阶段提交）

命令执行规则

禁止把命令输出给用户手动执行。 凡是需要运行的命令，直接用 Bash tool 自己执行。

  • pnpm install / 依赖安装 → 直接跑，根目录或子包目录均可
  • Android 构建 → 用 run_in_background: true，避免阻塞；JAVA_HOME 用 export 内联设置： 
    export JAVA_HOME="/c/Program Files/Android/Android Studio/jbr" && pnpm expo run:android --variant release
  • Windows 环境变量 → bash 语法用 export VAR=value，不用 PowerShell 的 $env:VAR
  • 只有以下情况才让用户手动操作：需要交互式登录（如 gcloud auth login）、需要输入密码、或明确的破坏性操作需确认

开发注意事项（踩坑提炼）

Android 平台

  • Modal 不用 transparent prop：transparent Modal 渲染范围被限制为父容器宽度（如侧栏 260px），FlatList pagingEnabled 等全屏功能失效。改用非透明 Modal（黑底），强制创建独立原生全屏窗口
  • Modal 内手势需额外 GestureHandlerRootView：Modal 是独立 native window，父级 RNGH 上下文无法穿透。内容最外层必须包 <GestureHandlerRootView style={{ flex: 1 }}>
  • 禁止在 Alert 回调内启动相机/相册：Alert 关闭动画期间 Activity 焦点未恢复，intent 被系统忽略。改为 UI 直接放按钮触发
  • 三星设备 Photo Picker 崩溃：用 expo-document-picker（ACTION_GET_CONTENT）替代 expo-image-picker 的相册选择
  • 手势组合用 Simultaneous + maxPointers：避免 Exclusive 导致 pinch 延迟。Pan 加 maxPointers(1) 天然分离单指/双指

Expo SDK 52 + pnpm Monorepo

  • expo 包版本用 ~（如 ~13.0.2），禁止 ^，防止 pnpm 解析到 SDK 53+ 导致 expo-module-gradle-plugin not found
  • 构建始终从 app 目录运行 pnpm expo run:android，不进 android/ 直接执行 Gradle
  • metro.config.js 必须设置 unstable_serverRoot 指向 app 目录（修复 Windows monorepo 路径解析 bug）
  • expo-image-picker v16 移除了 MediaType 枚举，mediaTypes 用字符串数组 ['images']

地图与布局

  • FoldableLayout 面板用 absolute 定位叠加在地图上方，地图 flex:1 始终满屏渲染，禁止用动画改变地图宽度（会触发 Android 地图重新布局闪白）
  • SVG 地图文件更新后须重新运行生成脚本（scripts/ 下），当前未纳入 watch 模式

数据库

  • 新增字段时先评估未来 2-3 步迭代可能需要的字段，避免反复 ALTER TABLE（初版遗漏 unit/spec/confirmed_at 导致返工）
  • 迁移脚本用 try/catch 逐步执行，单个迁移失败不阻断后续；迁移全部幂等，多次启动安全
  • 删除标记点时级联删除 items → photos 并同步删除文件系统文件，不能只删数据库行
  • 列表页禁止 N+1 查询：凡需附加统计字段（照片数、物品数等）必须在 SQL 层通过 LEFT JOIN 子查询或 GROUP BY 一次取数，禁止逐行查询（ItemList 照片数统计返工来源）

表单与组件

  • 动态数据前置：设计表单/列表骨架前，先确认 chip/下拉选项是否会变为动态数据；有则在骨架初始化时（_layout.tsx）一次性接入对应 Context/Provider，不得后补（分类 Context 后补返工来源）