harmony-crash-analysis-report/future_entry_demo/CLAUDE.md

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

# 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.