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

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