94 lines
3.5 KiB
Markdown
94 lines
3.5 KiB
Markdown
# 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`
|
||
- 跨端联调或修改公共契约：在项目根目录启动，本文件提供总览
|
||
|
||
## 部署
|
||
|
||
项目使用根目录的两份 docker compose 文件做整体编排，**不再使用各子目录下的独立 compose**：
|
||
|
||
| 文件 | 用途 | 启动命令 |
|
||
|------|------|---------|
|
||
| [docker-compose.yml](docker-compose.yml) | 正式环境 | `docker compose up -d --build` |
|
||
| [docker-compose.dev.yml](docker-compose.dev.yml) | 测试/开发环境 | `docker compose -f docker-compose.dev.yml up -d --build` |
|
||
|
||
**首次部署：**
|
||
1. `cp .env.example .env`
|
||
2. 填入 `JWT_SECRET`、`POSTGRES_PASSWORD`（正式环境必需）
|
||
3. 执行上方启动命令
|
||
|
||
**核心差异：**
|
||
- 正式：仅暴露网关 80/443、前端 20080；数据卷 `user-postgres-data` / `user-redis-data`
|
||
- 测试：全部端口暴露便于调试；网关 18080/18443、前端 18888；数据卷加 `-dev` 后缀，与正式完全隔离
|
||
- 两套环境可同机并存
|
||
|
||
## 项目当前进展
|
||
|
||
- ✅ `backend/` — 用户服务（账号/邮箱 登录/注册）已搭起雏形，Nginx 网关 + Postgres + Redis 编排就绪
|
||
- ✅ 全栈一键编排（根目录 docker-compose.yml / docker-compose.dev.yml）
|
||
- ⬜ `frontend/` — 未启动
|
||
- ⬜ `app/` — 未启动
|