asset_helper/app/CLAUDE.md

App — Claude Code 项目指南

本文件为 Claude Code（及其它 AI Agent）提供移动/桌面端项目的背景、结构说明和开发规范。

项目状态

当前状态：尚未初始化代码。 技术栈待定，目录除本文件外为空。 在选定技术栈后，请补全本文件中标记为「⚠️ 待补充」的章节。

定位

app/ 是 asset_helper 的 移动端/桌面端客户端，调用后端 API（默认通过 Nginx 网关 https://api.example.com 暴露）。

• 与 backend/ 通过 HTTP/JSON 交互，遵循根目录 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，调用时必须遵守。

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 或 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. 再开发页面/组件

涉及平台差异时（如文件存储路径、相机权限），用平台判定 + 抽象层屏蔽。