monisuo/CLAUDE.md

# CLAUDE.md

本文件为 Claude Code（claude.ai/code）在处理本仓库中的代码时提供使用指引。始终用中文与用户沟通。


## 项目概述

模拟所 (Monisuo) — 虚拟货币模拟交易平台。全栈 monorepo，三个子系统共用一个 MySQL 数据库。

## 技能系统

执行任务前先判定复杂度：简单任务（改样式、调主题、修小bug、清理冗余）不读 brainstorming。复杂任务主动启用适用技能，扫描 .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/`）。颜色集中管理。组件过大，需要组件化，而不是堆积。
- **数据流**：`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 仅用于客户端状态。