全栈项目初始化各端 CLAUDE.md 项目指南
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
fish
73
CLAUDE.md
Normal file
73
CLAUDE.md
Normal file
@@ -0,0 +1,73 @@
|
|||||||
|
# asset_helper — Claude Code 项目指南
|
||||||
|
|
||||||
|
本文件为 Claude Code（及其它 AI Agent）提供项目总览。**进入子目录工作时，请优先参考该子目录下的 `CLAUDE.md`。**
|
||||||
|
|
||||||
|
## 项目定位
|
||||||
|
|
||||||
|
`asset_helper` 是一个全栈资产管理工具，由三个独立领域组成，共享同一套后端 API：
|
||||||
|
|
||||||
|
```
|
||||||
|
asset_helper/
|
||||||
|
├── backend/ # Rust 微服务后端 + Nginx 网关 + Postgres + Redis
|
||||||
|
├── frontend/ # Web 前端（技术栈待定）
|
||||||
|
└── app/ # 移动端 / 桌面端（技术栈待定）
|
||||||
|
```
|
||||||
|
|
||||||
|
## 三端定位
|
||||||
|
|
||||||
|
| 目录 | 角色 | 技术栈 | 详细规范 |
|
||||||
|
|------|------|--------|---------|
|
||||||
|
| `backend/` | 微服务后端 + 网关 | Rust 2024 / Axum / sqlx / Nginx | [backend/CLAUDE.md](backend/CLAUDE.md) |
|
||||||
|
| `frontend/` | Web 客户端 | 待定 | [frontend/CLAUDE.md](frontend/CLAUDE.md) |
|
||||||
|
| `app/` | 移动 / 桌面客户端 | 待定 | [app/CLAUDE.md](app/CLAUDE.md) |
|
||||||
|
|
||||||
|
## 跨端契约（所有客户端必须遵守）
|
||||||
|
|
||||||
|
后端按**两类风格**定义接口，详见 [backend/CLAUDE.md](backend/CLAUDE.md#1-api-公共约定)。客户端调用时：
|
||||||
|
|
||||||
|
### 注册/业务类接口 — 包装请求/响应
|
||||||
|
|
||||||
|
请求：
|
||||||
|
```json
|
||||||
|
{ "device": <int>, "language": <int>, "data": { ... } }
|
||||||
|
```
|
||||||
|
|
||||||
|
响应：
|
||||||
|
```json
|
||||||
|
{ "success": true, "message": "...", "data": { ... } }
|
||||||
|
```
|
||||||
|
|
||||||
|
### 登录/认证类接口 — 扁平响应
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "success": true, "token": "<JWT>", "message": "..." }
|
||||||
|
```
|
||||||
|
|
||||||
|
### 公共编码（必须与后端保持一致）
|
||||||
|
|
||||||
|
**device**：`1` iOS、`2` Android、`3` Web、`4` iPad、`5` macOS、`6` Windows、`7` Linux
|
||||||
|
**language**：`1` 简中、`2` 繁中、`3` 英文
|
||||||
|
|
||||||
|
### 错误响应
|
||||||
|
|
||||||
|
HTTP 非 200 时网关统一返回 `{ "error", "message", "code" }`。
|
||||||
|
|
||||||
|
## 通用约定
|
||||||
|
|
||||||
|
- **注释、提交信息使用中文**（与后端保持一致）
|
||||||
|
- **类型定义跨端对齐**：客户端的数据模型与 backend Rust 结构体一一对应，避免字段漂移
|
||||||
|
- **时间字段**：后端写 UTC、查询按东八区返回；客户端展示如需时区转换，按需处理
|
||||||
|
- 修改跨端契约（device/language 编码、API 包装格式等）时，**必须同步更新所有四份 CLAUDE.md**
|
||||||
|
|
||||||
|
## 工作流提示
|
||||||
|
|
||||||
|
- 改后端服务：`cd backend && claude`，自动加载 [backend/CLAUDE.md](backend/CLAUDE.md)
|
||||||
|
- 改前端：`cd frontend && claude`
|
||||||
|
- 改移动端：`cd app && claude`
|
||||||
|
- 跨端联调或修改公共契约：在项目根目录启动，本文件提供总览
|
||||||
|
|
||||||
|
## 项目当前进展
|
||||||
|
|
||||||
|
- ✅ `backend/` — 用户服务（账号/邮箱 登录/注册）已搭起雏形，Nginx 网关 + Postgres + Redis 编排就绪
|
||||||
|
- ⬜ `frontend/` — 未启动
|
||||||
|
- ⬜ `app/` — 未启动
|
||||||
121
app/CLAUDE.md
Normal file
121
app/CLAUDE.md
Normal file
@@ -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. 再开发页面/组件
|
||||||
|
|
||||||
|
涉及平台差异时（如文件存储路径、相机权限），用平台判定 + 抽象层屏蔽。
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
# AGENTS.md
|
# Backend — Claude Code 项目指南
|
||||||
|
|
||||||
本文件为 AI Agent 提供项目背景、结构说明和开发规范。
|
本文件为 Claude Code（及其它 AI Agent）提供后端项目的背景、结构说明和开发规范。
|
||||||
|
|
||||||
## 项目概述
|
## 项目概述
|
||||||
|
|
||||||
130
frontend/CLAUDE.md
Normal file
130
frontend/CLAUDE.md
Normal file
@@ -0,0 +1,130 @@
|
|||||||
|
# Frontend — Claude Code 项目指南
|
||||||
|
|
||||||
|
本文件为 Claude Code（及其它 AI Agent）提供前端项目的背景、结构说明和开发规范。
|
||||||
|
|
||||||
|
## 项目状态
|
||||||
|
|
||||||
|
> **当前状态：尚未初始化代码。** 技术栈待定，目录除本文件外为空。
|
||||||
|
> 在选定技术栈后，请补全本文件中标记为「⚠️ 待补充」的章节。
|
||||||
|
|
||||||
|
## 定位
|
||||||
|
|
||||||
|
`frontend/` 是 asset_helper 的 **Web 前端**，调用后端 API（默认通过 Nginx 网关 `https://api.example.com` 暴露）。
|
||||||
|
|
||||||
|
- 与 `backend/` 通过 HTTP/JSON 交互，遵循根目录 [CLAUDE.md](../CLAUDE.md) 中定义的跨端契约
|
||||||
|
- 与 `app/`（移动/桌面端）共享后端，但 UI 实现独立
|
||||||
|
|
||||||
|
## 技术栈
|
||||||
|
|
||||||
|
> ⚠️ 待补充：选定后请填写。建议候选：
|
||||||
|
>
|
||||||
|
> | 维度 | 候选 |
|
||||||
|
> |------|------|
|
||||||
|
> | 框架 | React 18 / Vue 3 / Next.js |
|
||||||
|
> | 语言 | TypeScript（推荐，与 Rust 后端类型对齐更顺） |
|
||||||
|
> | 构建 | Vite / Next.js |
|
||||||
|
> | 状态管理 | Zustand / Pinia / React Query |
|
||||||
|
> | UI 库 | Ant Design / Element Plus / shadcn-ui |
|
||||||
|
> | HTTP 客户端 | axios / ky / fetch 封装 |
|
||||||
|
|
||||||
|
## 与后端的协作约定
|
||||||
|
|
||||||
|
以下约定来自 [backend/CLAUDE.md](../backend/CLAUDE.md)，前端调用时**必须遵守**：
|
||||||
|
|
||||||
|
### 1. 请求包装（注册/业务类接口）
|
||||||
|
|
||||||
|
```ts
|
||||||
|
interface ApiRequest<T> {
|
||||||
|
device: number; // 见下方 device 编码
|
||||||
|
language: number; // 见下方 language 编码
|
||||||
|
data: T; // 业务字段
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**device 编码（必须与 backend 保持一致）：**
|
||||||
|
- `1` = iOS
|
||||||
|
- `2` = Android
|
||||||
|
- `3` = Web ← **前端使用此值**
|
||||||
|
- `4` = iPad
|
||||||
|
- `5` = macOS
|
||||||
|
- `6` = Windows
|
||||||
|
- `7` = Linux
|
||||||
|
|
||||||
|
**language 编码：**
|
||||||
|
- `1` = 简体中文
|
||||||
|
- `2` = 繁体中文
|
||||||
|
- `3` = 英文
|
||||||
|
|
||||||
|
### 2. 响应包装
|
||||||
|
|
||||||
|
```ts
|
||||||
|
interface ApiResponse<T> {
|
||||||
|
success: boolean;
|
||||||
|
message: string;
|
||||||
|
data: T | null; // 失败时为 null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 登录/认证类接口（扁平响应）
|
||||||
|
|
||||||
|
```ts
|
||||||
|
interface LoginResponse {
|
||||||
|
success: boolean;
|
||||||
|
token: string | null; // JWT
|
||||||
|
message: string;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
JWT 存储建议：HttpOnly Cookie（CSRF 防护）或 localStorage（注意 XSS 风险），后续根据安全策略统一。
|
||||||
|
|
||||||
|
### 4. 错误响应（HTTP 非 200）
|
||||||
|
|
||||||
|
```ts
|
||||||
|
interface ErrorResponse {
|
||||||
|
error: string;
|
||||||
|
message: string;
|
||||||
|
code: number;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 代码风格
|
||||||
|
|
||||||
|
- 注释使用**中文**（与后端保持一致）
|
||||||
|
- TypeScript 类型与后端 Rust 结构体一一对齐，避免 `any`
|
||||||
|
- API 客户端集中封装在一处（如 `src/api/`），不要在组件中直接 fetch
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
|
> ⚠️ 待补充：技术栈选定后填写。常见骨架：
|
||||||
|
>
|
||||||
|
> ```
|
||||||
|
> frontend/
|
||||||
|
> ├── src/
|
||||||
|
> │ ├── api/ # API 客户端封装（device/language 注入、错误统一处理）
|
||||||
|
> │ ├── components/ # 可复用 UI 组件
|
||||||
|
> │ ├── pages/ # 路由页面
|
||||||
|
> │ ├── stores/ # 状态管理
|
||||||
|
> │ ├── types/ # 与后端对齐的类型定义
|
||||||
|
> │ └── utils/
|
||||||
|
> ├── public/
|
||||||
|
> ├── package.json
|
||||||
|
> └── vite.config.ts (或对应配置)
|
||||||
|
> ```
|
||||||
|
|
||||||
|
## 常用命令
|
||||||
|
|
||||||
|
> ⚠️ 待补充：技术栈选定后填写（如 `pnpm dev` / `pnpm build` / `pnpm test`）。
|
||||||
|
|
||||||
|
## 开发环境
|
||||||
|
|
||||||
|
- 后端网关默认监听 `localhost:80`/`443`，本地需配置 hosts 或直连 `localhost`
|
||||||
|
- 后端开发证书为自签名，浏览器需信任或开发环境关闭 HTTPS
|
||||||
|
|
||||||
|
## 扩展指南
|
||||||
|
|
||||||
|
新增页面/功能时：
|
||||||
|
1. 先在 `types/` 定义与后端对齐的类型
|
||||||
|
2. 在 `api/` 添加调用封装（务必通过统一封装注入 `device`/`language`）
|
||||||
|
3. 再开发组件/页面
|
||||||
|
|
||||||
|
发现重复逻辑时优先抽到 `utils/` 或自定义 Hook（React）/ Composable（Vue）。
|
||||||
Reference in New Issue
Block a user