react-phone-apps/.blueprint/rules.md

项目私有规则

本文件由梦核分析 + 用户确认后生成，Claude 每次对话开始时读取并合并应用。 规则格式与 CONVENTIONS 自动推荐规则库相同，优先级高于全局规则。 来源：2026-07-04 梦核分析，基于 40 条复盘笔记 + 跨项目返工数据。

规则列表

P01 — Android 画布/地图叠加面板必须用 absolute 定位

• 触发条件：在地图、画布、SVG 可缩放视图上叠加侧边/底部面板
• 自动动作：确认面板用 position: absolute 覆盖；严禁通过 Animated.timing / LayoutAnimation 改变父容器 flex 宽高——会触发底层视图重新布局，Android 上出现闪白/黑块
• confidence: 0.90
• evidence_count: 3
• derived_from: FoldableLayout 3 轮返工（4e1d922→cea2a5d→3dbc6f0），JS 线程宽度动画两次都有 Android 渲染问题，absolute 定位彻底解决

P02 — 选图统一用 expo-document-picker，禁用 expo-image-picker

• 触发条件：需要从相册选取图片
• 自动动作：直接使用 expo-document-picker（ACTION_GET_CONTENT）；发现代码中引用 expo-image-picker 时提示替换
• confidence: 0.92
• evidence_count: 3
• derived_from: 摄像头任务 3 轮返工（expo-image-picker SDK52 API 废弃 + 三星 Photo Picker 系统崩溃），expo-document-picker 彻底绕开

P03 — 全屏预览 Modal 不用 transparent prop

• 触发条件：实现全屏照片预览、全屏地图等需要覆盖整个屏幕的 Modal
• 自动动作：去掉 transparent prop 改为非透明黑底；FlatList pagingEnabled 改为手势驱动单张渲染
• confidence: 0.88
• evidence_count: 2
• derived_from: MarkerPhotoPanel 返工（transparent Modal 渲染范围被限制为父容器宽度，FlatList 分页宽度异常）

P04 — 列表页禁止 N+1 查询

• 触发条件：列表组件需要展示每行的统计数据（照片数、物品数、数量合计等）
• 自动动作：在 SQL 层通过 LEFT JOIN 子查询或 GROUP BY 一次聚合取数；发现逐行查询时标记需重构
• confidence: 0.80
• evidence_count: 1
• derived_from: ItemList 照片数统计 N+1 查询，O(n) 查库，内容量增大后有性能风险（2026-04-11 复盘）

P05 — 动态数据前置：表单骨架初始化前先确认数据源

• 触发条件：设计表单组件 / 列表筛选 chip / 下拉选择器
• 自动动作：先问"这些选项/分类将来是否动态？"；有动态数据则在 _layout.tsx 根布局一次性接入对应 Context/Provider，不得在组件层后补
• confidence: 0.80
• evidence_count: 2
• derived_from: ItemFields 分类 chip 3 轮返工（硬编码→动态 CategoriesContext 后补）+ Expo 骨架 2 轮返工（CategoriesProvider 初版未加）