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)

mvn spring-boot:run                          # 开发服务，端口 5010
mvn compile                                  # 仅编译
mvn test                                     # 运行测试
mvn clean package -DskipTests                # 打包 JAR → target/monisuo-1.0.jar

Flutter 移动端/Web (flutter_monisuo/)

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/)

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

部署

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 仅用于客户端状态。