# CLAUDE.md

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

## Project identity

This is the HarmonyOS stage-model `entry` HAP module for **同花顺期货 (THS Futures)**, a financial futures trading app. It is NOT a complete workspace — sibling modules (`biz_common`, `biz_trade`, `biz_quote`, etc.) live alongside this directory and are consumed via `file:../...` dependencies. Always invoke builds and runs from the parent workspace, not this directory.

## Build and run commands

```bash
# Build specific targets (run from parent workspace)
devecocli build --modules entry@default
devecocli build --modules entry@ohosTest
devecocli build --modules entry@Official --build-mode release

# List connected devices/emulators
devecocli device list

# Run on device
devecocli run --module entry
```

Configured targets: `default`, `ohosTest`, `OEM`, `Official`, `forTest`.

- `oh-package-lock.json5` is autogenerated — never edit it.
- Device/ability tests (`src/ohosTest/`) require a connected device or emulator.

## Architecture overview

### App lifecycle and initialization chain

`EntryAbility` (`src/main/ets/entryability/EntryAbility.ets`) is the main `UIAbility` (singleton, launch type `singleton`). Its `onCreate` runs a carefully ordered initialization sequence:

1. Push message listener (trade daily notifications via `pushService.receiveMessage`)
2. Custom figure registration (`FigureRegistry.registerAll()`)
3. Global context initialization (multiple `ContextUtils` variants for different modules, plus `GlobalContext`, `AppUtil`)
4. Security monitor, gray test init, cloud store log init
5. HMRouter init
6. Analytics/ELK upload, UGC client, auth listener, event subscription
7. RCP HTTP header configuration
8. Future market init chain: `TabConfigManager` → `CommonIndicatorsManage` → code table → `MainContractManager` → `HQTabManager` → `FutureMarketDataManager` → `InactiveContractManager` → `DelayMarketManager` → `TradeInitializor` → `CurveStorage`
9. Ads, AI group client, font loading, want caching

`onWindowStageCreate` then branches on three conditions:
- **No network** → `loadNetworkAnomalyPage`
- **Privacy not accepted** → `loadPrivacyPage` (LauncherPage)
- **Normal** → `loadIndexPage` (the main Index page)

### Navigation and page registry

All pages must be registered in `src/main/resources/base/profile/main_pages.json`. The app uses **HMRouter** (`@hadss/hmrouter`) for navigation. The main UI uses a `Tabs` component in `Index.ets` with configurable tab sets (`IndexTabManager` via `TabManager`). On large screens (`lg` breakpoint), tabs render vertically on the left.

### Communication layer

`src/main/ets/communication/` manages long-lived TCP socket connections to the trading backend:

- **`ConnectionInitiator`** — initializes site configuration (IP/port from `Config.ets`), supports inner-network debug mode, and handles debug-tool server overrides.
- **`ServiceHandlerImpl`** — registers two connection configurations:
  - `HqConnectionConfig` (行情): authenticates via `HXAuthManager`, pipes data through `AuthJsonStructObserver`, `RealDataStructObserver`, `SidInstanceIdReceiver`
  - `CBASConnectionConfig` (analytics): separate connection for CBAS analytics with trade ELK log observer
- **`HXSocketMonitor`** — monitors socket health across app foreground/background transitions.

### Group subscription system (real-time sync)

`GroupSubManager` (from `base_mobilepush`) manages push-based data synchronization. Handlers in `src/main/ets/groupsub/business/` handle specific data domains:

- **User-scoped** (`addUserGroupHandler`): self-code lists, YYB account lists, trade settings, indicators, draw lines, AI group, SID data, function authority
- **All-user-scoped** (`addAllGroupHandler`): ad strategies, gray test, account analysis, futures companies, stock/variety storage updates, main contract changes

Each handler receives push notifications and drives local state updates.

### Service registration pattern

Services in `src/main/ets/register/` follow a singleton-then-init pattern:
- **`cbasService`** (CbasServiceRegister) — analytics/event capture with `HxCBASAgentProvider`
- **`UgcClient`** — user-generated content client
- **`ElkUploadRegister`** — error log upload
- **`SecurityMonitorInit`** — crash protection

### Tabs and page structure

The main UI has four tabs (configurable, some may be hidden):
1. **首页** (FirstPage) — `@b2c/first_page`
2. **行情** (HQPage) — `biz_market`, renders self-codes, futures quotes, option chains
3. **交易** (TradeBiz) — `biz_trade`, conditionally hidden via `HexinVersionControl.hideTrade()`
4. **发现** (DiscoverPage) — `@b2c/biz_discover`

Each tab has its own `TabManager` sub-manager. Tab visibility is controlled by `IndexTabManager` which extends `TabManager`.

### Multi-device adaptation

The module targets phone, tablet, and 2in1. Responsive breakpoints are handled through `updateBreakpoint()` (from `biz_common`) which broadcasts breakpoint changes (`sm`, `md`, `lg`). Window size changes are monitored in `EntryAbility.onWindowStageCreate`.

### Key sibling dependencies

All resolved via `file:../...` in `oh-package.json5`:
- `biz_common` — shared utilities, constants, tab management, preferences
- `biz_trade` — trading functionality, account management, notifications
- `biz_quote` — quote/chart rendering, indicators, settings
- `biz_market` — market data, HQ tabs, contracts
- `biz_option`, `biz_forecast`, `biz_indicator` — option/forecast/indicator features
- `service_push`, `service_watchlist`, `service_aigroup` — push, watchlist, AI services
- `biz_debug` — debug tools, server switching
- `@kernel/lib_communication` — TCP socket connection library
- `@kernel/theme_manager` — theming and color mode
- `@hadss/hmrouter` — route management
- `@ohos/hypium` — test framework

### Debug infrastructure

In non-release builds, a `DebugFloatingBall` overlay is created via `windowStage.createSubWindow()`. Debug pages live under `pages/debug/` and support server switching, gray test configuration, cloud storage inspection, URL modification, and memory leak monitoring.