From 807857618f1c1a8d7b50ed92e816d20e38817140 Mon Sep 17 00:00:00 2001 From: fish Date: Sat, 25 Apr 2026 22:05:35 +0800 Subject: [PATCH] =?UTF-8?q?=E5=85=A8=E6=A0=88=E9=A1=B9=E7=9B=AE=E5=88=9D?= =?UTF-8?q?=E5=A7=8B=E5=8C=96=E5=90=84=E7=AB=AF=20CLAUDE.md=20=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 73 +++++++++++++++++ app/CLAUDE.md | 121 ++++++++++++++++++++++++++++ backend/{AGENTS.md => CLAUDE.md} | 4 +- frontend/CLAUDE.md | 130 +++++++++++++++++++++++++++++++ 4 files changed, 326 insertions(+), 2 deletions(-) create mode 100644 CLAUDE.md create mode 100644 app/CLAUDE.md rename backend/{AGENTS.md => CLAUDE.md} (98%) create mode 100644 frontend/CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0415dc6 --- /dev/null +++ b/CLAUDE.md @@ -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": , "language": , "data": { ... } } +``` + +响应： +```json +{ "success": true, "message": "...", "data": { ... } } +``` + +### 登录/认证类接口 — 扁平响应 + +```json +{ "success": true, "token": "", "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/` — 未启动 diff --git a/app/CLAUDE.md b/app/CLAUDE.md new file mode 100644 index 0000000..99b2e9f --- /dev/null +++ b/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. 再开发页面/组件 + +涉及平台差异时（如文件存储路径、相机权限），用平台判定 + 抽象层屏蔽。 diff --git a/backend/AGENTS.md b/backend/CLAUDE.md similarity index 98% rename from backend/AGENTS.md rename to backend/CLAUDE.md index c8eaa4e..c188197 100644 --- a/backend/AGENTS.md +++ b/backend/CLAUDE.md @@ -1,6 +1,6 @@ -# AGENTS.md +# Backend — Claude Code 项目指南 -本文件为 AI Agent 提供项目背景、结构说明和开发规范。 +本文件为 Claude Code（及其它 AI Agent）提供后端项目的背景、结构说明和开发规范。 ## 项目概述 diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md new file mode 100644 index 0000000..ca7fc7a --- /dev/null +++ b/frontend/CLAUDE.md @@ -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 { + 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 { + 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）。