122 lines
3.7 KiB
Markdown
122 lines
3.7 KiB
Markdown
# 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. 再开发页面/组件
|
||
|
||
涉及平台差异时（如文件存储路径、相机权限），用平台判定 + 抽象层屏蔽。
|