111 lines
6.1 KiB
Markdown
111 lines
6.1 KiB
Markdown
# CLAUDE.md
|
||
|
||
本文件为 Claude Code（claude.ai/code）在处理本仓库中的代码时提供使用指引。始终用中文与用户沟通。
|
||
|
||
|
||
## 项目概述
|
||
|
||
模拟所 (Monisuo) — 虚拟货币模拟交易平台。全栈 monorepo，三个子系统共用一个 MySQL 数据库。
|
||
|
||
## 技能系统
|
||
|
||
当处理任务时，先扫描 `.agents/skills/` 目录下是否有相关技能。如果技能可能适用，先用 Read 工具读取对应的 `SKILL.md`，然后严格遵循其指引执行。技能优先级高于默认行为，但低于用户的显式指令。
|
||
|
||
## 构建与运行命令
|
||
|
||
### Java 后端 (Maven, Java 8, Spring Boot 2.2.4)
|
||
```bash
|
||
mvn spring-boot:run # 开发服务，端口 5010
|
||
mvn compile # 仅编译
|
||
mvn test # 运行测试
|
||
mvn clean package -DskipTests # 打包 JAR → target/monisuo-1.0.jar
|
||
```
|
||
|
||
### Flutter 移动端/Web (`flutter_monisuo/`)
|
||
```bash
|
||
cd flutter_monisuo
|
||
flutter pub get # 安装依赖
|
||
flutter run -d chrome # 开发 (Web)
|
||
flutter run -d android # 开发 (Android)
|
||
flutter analyze # 代码检查
|
||
flutter test # 运行测试
|
||
flutter build web --release --dart-define=ENV=prod # 生产 Web 构建 → build/web/
|
||
flutter build apk --release --dart-define=ENV=prod # 生产 APK 构建 → build/app/outputs/
|
||
```
|
||
通过 `--dart-define=ENV=prod|dev` 切换环境，API 地址自动切换。
|
||
|
||
### Vue 管理后台 (`monisuo-admin/`)
|
||
```bash
|
||
cd monisuo-admin
|
||
pnpm install # 安装依赖（需 pnpm >=10, node >=22.15）
|
||
pnpm dev # Vite 开发服务
|
||
pnpm build # 生产构建（vue-tsc + vite）→ dist/
|
||
pnpm lint / pnpm lint:fix # 代码检查，使用 @antfu/eslint-config
|
||
```
|
||
|
||
### 部署
|
||
```bash
|
||
deploy/build_local.sh # 本地构建 Flutter + Admin
|
||
deploy/deploy_server.sh # 完整服务器部署（前端同步 + Maven 构建 + JAR 重启）
|
||
deploy/deploy_server.sh frontend # 仅部署前端
|
||
deploy/deploy_server.sh backend # 仅部署后端
|
||
```
|
||
服务器：`8.155.172.147`，后端端口 `5010`。Flutter Web → `/www/wwwroot/monisuo-h5/`，管理后台 → `/www/wwwroot/monisuo-admin/`。
|
||
|
||
## 架构
|
||
|
||
### 后端 (`src/main/java/com/it/rattan/`)
|
||
分层架构：**Controller → Service → Mapper → Entity**。
|
||
- JWT 认证：`TokenFilter` + `UserContext`（ThreadLocal）。接口前缀：`/api/`（用户端）、`/admin/`（管理端）。
|
||
- 统一响应封装：`Result<T>`（code/msg/data），`PageResult` 分页。
|
||
- `GlobalExceptionHandler` 全局异常处理，BCrypt 密码加密。
|
||
- `bean-searcher` 动态查询构建，用于管理端列表接口。
|
||
- 数据库：MySQL（`monisuo`），ORM 用 MyBatis-Plus。建表脚本 `sql/init.sql`（11 张表）。
|
||
|
||
### Flutter 应用 (`flutter_monisuo/lib/`)
|
||
- **状态管理**：Provider（ChangeNotifier）— `providers/` 消费 `data/services/`，底层调用 `core/network/DioClient`。
|
||
- **主题样式**：前端禁止硬编码，新设计统一维护到theme目录的定义中,并尽可能复用设计主题。
|
||
- **UI**：shadcn_ui + 自定义主题系统（`core/theme/`）。颜色集中管理在 `AppColorScheme`，组件过大，需要组件化，而不是堆积。
|
||
- **数据流**：`data/services/`（API 调用）→ `providers/`（状态）→ `ui/pages/`（视图）。
|
||
- 页面：auth、home、market、trade、asset、mine、orders、onboarding。
|
||
|
||
### Vue 管理后台 (`monisuo-admin/src/`)
|
||
- **路由**：基于文件系统的路由，`unplugin-vue-router`（`pages/` 目录）。路由层有鉴权守卫。
|
||
- **状态管理**：Pinia（auth、theme）+ TanStack Vue Query（服务端状态）。
|
||
- **HTTP**：Axixos 通过 `composables/use-axios.ts` 封装。Vite 代理 `/api` → `localhost:5010`（去除前缀）。
|
||
- **UI**：shadcn-vue 组件在 `components/ui/`（自动注册，已排除 tsconfig）。
|
||
- **自动导入**：Vue composables、stores、constants 通过 `unplugin-auto-import` 自动导入。
|
||
- **代码检查**：ESLint 9 flat config + `@antfu/eslint-config`。Pre-commit 钩子通过 `simple-git-hooks` + `lint-staged`。
|
||
|
||
### 核心业务领域
|
||
双账户体系：
|
||
- **资金账户** (`account_fund`)：与用户 1:1，USDT 余额，用于充提。充值需管理员审批。
|
||
- **交易账户** (`account_trade`)：与用户 1:N（每币种一个），持有币种数量和加权平均成本价。
|
||
- 资金流转：充值 → 资金账户 → 划转至交易账户(USDT) → 买卖币种。所有操作记录在 `account_flow`。
|
||
- 盈亏计算：`(持仓数量 × 当前价格) - (持仓数量 × 平均成本价)`。
|
||
- 详细流程图见 `ACCOUNT_SYSTEM_DESIGN.md`。
|
||
|
||
### 数据库核心表
|
||
`sys_user`、`sys_admin`、`coin`（`price_type`: 1=实时, 2=管理定价）、`account_fund`、`account_trade`（唯一索引 `user_id+coin_code`）、`order_trade`、`order_fund`（充提订单，状态驱动的审批流）、`account_flow`、`sys_config`、`user_favorite`、`cold_wallet`。
|
||
|
||
|
||
## 代码规范
|
||
|
||
### Git 提交
|
||
Conventional Commits 格式：`feat(module): 描述`、`fix(module): 描述`、`chore(scope): 描述`。提交正文可用中文。
|
||
|
||
### Flutter 代码规范
|
||
- 遵循 Effective Dart 规范，提交前运行 `flutter analyze`。
|
||
- 使用 `AppSpacing`、`AppRadius`、`AppColorScheme` 主题常量，禁止硬编码颜色。
|
||
- 修改主题/UI 时不要改动业务逻辑/API/Provider 层。
|
||
|
||
### Java 代码规范
|
||
- 使用 Lombok 简化代码，MyBatis-Plus `LambdaUpdateWrapper` 做更新操作。
|
||
- 所有涉及资金变动的方法必须加 `@Transactional(rollbackFor = Exception.class)`。
|
||
- RESTful API 设计，Swagger 文档（springfox 2.9.2）。
|
||
|
||
### 管理后台代码规范
|
||
- TypeScript strict 模式，lint 规则强制 `<script lang="ts">`。
|
||
- shadcn-vue 组件自动管理，不要手动编辑 `components/ui/`。
|
||
- 用 TanStack Vue Query 做数据请求，Pinia 仅用于客户端状态。
|