全栈项目初始化各端 CLAUDE.md 项目指南

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

app/CLAUDE.md

@@ -0,0 +1,121 @@
+# App — Claude Code 项目指南
+
+本文件为 Claude Code（及其它 AI Agent）提供移动/桌面端项目的背景、结构说明和开发规范。
+
+## 项目状态
+
+> **当前状态：尚未初始化代码。** 技术栈待定，目录除本文件外为空。
+> 在选定技术栈后，请补全本文件中标记为「⚠️ 待补充」的章节。
+
+## 定位
+
+`app/` 是 asset_helper 的 **移动端/桌面端客户端**，调用后端 API（默认通过 Nginx 网关 `https://api.example.com` 暴露）。
+
+- 与 `backend/` 通过 HTTP/JSON 交互，遵循根目录 [CLAUDE.md](../CLAUDE.md) 中定义的跨端契约
+- 与 `frontend/`（Web 端）共享后端，UI 实现独立
+- 一套代码可能同时输出 iOS / Android / 桌面端，需根据运行平台动态设置 `device` 字段
+
+## 技术栈
+
+> ⚠️ 待补充：选定后请填写。建议候选：
+>
+> | 维度 | 候选 |
+> |------|------|
+> | 框架 | Flutter / React Native / Tauri |
+> | 语言 | Dart / TypeScript / Rust |
+> | 状态管理 | Riverpod / Provider / Redux Toolkit |
+> | HTTP | dio / axios / reqwest |
+> | 本地存储 | shared_preferences / AsyncStorage / tauri-plugin-store |
+
+## 与后端的协作约定
+
+以下约定来自 [backend/CLAUDE.md](../backend/CLAUDE.md)，调用时**必须遵守**。
+
+### 1. 请求包装（注册/业务类接口）
+
+```
+{
+  "device": <平台编码>,
+  "language": <语言编码>,
+  "data": { ... }
+}
+```
+
+### 2. device 编码（按运行平台动态设置）
+
+| 编码 | 平台 |
+|------|------|
+| `1` | iOS |
+| `2` | Android |
+| `3` | Web |
+| `4` | iPad |
+| `5` | macOS |
+| `6` | Windows |
+| `7` | Linux |
+
+**实现要点：** 在 HTTP 客户端的拦截器/中间件中**自动注入** `device`，根据运行时平台判定，业务代码不直接关心。
+
+### 3. language 编码
+
+- `1` = 简体中文
+- `2` = 繁体中文
+- `3` = 英文
+
+跟随系统 locale 或用户设置。
+
+### 4. 响应/错误格式
+
+详见 [frontend/CLAUDE.md](../frontend/CLAUDE.md#与后端的协作约定) 或 [backend/CLAUDE.md](../backend/CLAUDE.md)，与 Web 前端保持一致。
+
+### 5. JWT 存储
+
+- iOS：Keychain
+- Android：EncryptedSharedPreferences / Keystore
+- 桌面端：操作系统凭证存储（macOS Keychain / Windows Credential Manager / libsecret）
+
+**禁止**直接存明文文件或 SharedPreferences/UserDefaults 未加密区域。
+
+## 代码风格
+
+- 注释使用**中文**（与后端、前端保持一致）
+- 类型定义与后端 Rust 结构体一一对齐
+- HTTP 客户端集中封装，统一处理 device/language 注入、错误转换、JWT 注入
+
+## 目录结构
+
+> ⚠️ 待补充：技术栈选定后填写。常见骨架（Flutter 示例）：
+>
+> ```
+> app/
+> ├── lib/
+> │   ├── api/          # API 客户端
+> │   ├── models/       # 与后端对齐的数据模型
+> │   ├── pages/        # 页面
+> │   ├── widgets/      # 可复用组件
+> │   ├── providers/    # 状态管理
+> │   └── utils/        # device 平台判定等工具
+> ├── ios/
+> ├── android/
+> ├── pubspec.yaml
+> └── ...
+> ```
+
+## 常用命令
+
+> ⚠️ 待补充：技术栈选定后填写（如 `flutter run` / `flutter build apk`）。
+
+## 开发环境
+
+- 真机/模拟器需要能访问后端网关。本地开发可通过：
+  - iOS 模拟器：`localhost` 直连
+  - Android 模拟器：`10.0.2.2` 指代宿主机
+  - 真机：与宿主机同网段，访问宿主机 IP，或通过隧道（ngrok/frp）
+
+## 扩展指南
+
+新增功能时：
+1. 在 `models/` 定义与后端对齐的数据模型
+2. 在 `api/` 添加调用方法（通过统一封装注入 `device`/`language`/`token`）
+3. 再开发页面/组件
+
+涉及平台差异时（如文件存储路径、相机权限），用平台判定 + 抽象层屏蔽。