asset_helper/CLAUDE.md

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
frontend/	Web 客户端	待定	frontend/CLAUDE.md
app/	移动 / 桌面客户端	待定	app/CLAUDE.md

跨端契约（所有客户端必须遵守）

后端按两类风格定义接口，详见 backend/CLAUDE.md。客户端调用时：

注册/业务类接口 — 包装请求/响应

请求：

{ "device": <int>, "language": <int>, "data": { ... } }

响应：

{ "success": true, "message": "...", "data": { ... } }

登录/认证类接口 — 扁平响应

{ "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
• 改前端：cd frontend && claude
• 改移动端：cd app && claude
• 跨端联调或修改公共契约：在项目根目录启动，本文件提供总览

部署

项目使用根目录的两份 docker compose 文件做整体编排，不再使用各子目录下的独立 compose：

文件	用途	启动命令
docker-compose.yml	正式环境	docker compose up -d --build
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/ — 未启动