Ichino/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Development Commands

# Run the app (launches on connected device)
flutter run

# Run analyzer
flutter analyze

# Run tests
flutter test

# Run a single test file
flutter test test/widget_test.dart

# Build release artifacts
flutter build apk --release          # Android
flutter build windows --release      # Windows
flutter build macos --release        # macOS
flutter build linux --release        # Linux
flutter build ios --release --no-codesign   # iOS（无证书时只验证可编译）

# Check for outdated dependencies
flutter pub outdated

# Upgrade dependencies
flutter pub upgrade --major-versions

Architecture

This is a Flutter app (Android / iOS / Windows / macOS / Linux) that serves as a QR-code-based login client for the maimai DX arcade game network.

Code Layout

lib/
├── main.dart                # 入口：main() + MyApp（MaterialApp）
├── pages/
│   ├── login_page.dart      # 登录页（QR 粘贴 / 图片识别）
│   ├── home_page.dart       # 主页骨架（底部导航 + 各 tab）
│   ├── settings_page.dart   # Title Server / 机器参数配置
│   └── ...                  # 各功能页（ticket / best50 / 风险操作等）
├── widgets/
│   ├── cooldown_mixin.dart  # CooldownMixin：登录后冷却倒计时
│   ├── step_progress.dart   # RiskStep + StepProgressCard
│   ├── app_card.dart        # AppCard / SectionTitle / AutoLogoutToggle
│   ├── app_notice.dart      # AppNotice + context.showSnack
│   └── best50_poster.dart   # B50 成绩图
└── services/
    ├── api_service.dart     # Aime 登录 API 客户端
    ├── title_api_service.dart # 游戏服务器传输层（加解密 / 会话 / 各 Api）
    ├── user_all_payload_builder.dart # UpsertUserAll 组装与各补丁
    ├── api_log.dart         # 传输层调试日志（仅 debug）
    └── ...

Key Design Decisions

• Risk-flow scaffolding is shared: the feature pages (ticket / unlock music / collectibles / travel partner / number patch / map traverse / kaleidx / risk hub) all use CooldownMixin, RiskStep, StepProgressCard, AppCard, AppNotice and AutoLogoutToggle instead of copy-pasting the same timer / step / banner / card code. Keep new pages on these primitives.
• QR decoding is native-only: services/qr_service.dart calls the dev.naominet.ichino/qr_scanner MethodChannel, implemented by Android's MainActivity and iOS's SceneDelegate. Desktop has no handler, so image-based QR scanning is mobile-only.
• Auth flow: ApiService.login() takes a QR code token (last 64 chars), builds a SHA-256 key from chipID + JST-timestamp + chimeSalt, and POSTs JSON to the configured Aime URL. A successful response has errorID: 0 and returns userID + token.
• Title server transport: TitleApiService derives the URL path from MD5(apiName + salt + obfuscateParam), JSON → ZLib → AES-CBC encodes/decodes, and keeps the JSESSIONID cookie. getUserPreview and every other API go through the same _callApi helper.
• Timestamp is JST (UTC+9) for Aime key derivation, formatted yyMMddHHmmss.

Notable Dependencies

• http — API calls
• crypto — MD5 URL hash + SHA-256 Aime key
• pointycastle / archive — AES-CBC + ZLib for the title-server wire format
• image_picker — picking QR images from the device gallery
• shared_preferences — persisted TitleServerConfig
• share_plus — exporting the B50 PNG