biz_firstpage/AGENTS.md

AGENTS.md

Repository

• This is the HarmonyOS stage-mode HAR @b2c/first_page (biz_firstpage), not a host app. The host supplies several hoisted dependencies and runtime services.
• There is no standalone build: hvigorw, oh_modules, and the sibling ../biz_quote dependency are absent here. Do not add undeclared host dependencies or claim build/test success; verify ArkTS changes by inspection and in the host project.
• Load the arkts-grammar-standards skill before modifying .ets files.

Wiring

• The public package entrypoint is root Index.ets; export new host-facing symbols there.
• FirstPage.createNodeView dispatches feed cards by FirstPageConstant.KEY_*. A new feed card needs its key, component, and dispatch branch; card metadata is normally read from src/main/resources/rawfile/first_page_cards_config.json.
• market-ranking is a special feed card under src/main/ets/market-ranking/, inserted with KEY_MARKET_RANKING and rendered directly by FirstPage. Its config key is marketRanking, loaded by FirstPageCardsConfigLoader.

Market Ranking

• MarketRankingDataFetcher first fetches the recommended contract list over @kit.NetworkKit; MarketRankingHqRequestClient then subscribes those contracts through the host TableRequestClient/4106 infrastructure. Do not replace either path with mock data or a second quote client.
• MarketRankingConstant.ets is currently shared by UI, HTTP, and HQ code: TAB_METRICS/PERIOD_RANGES contain labels, HTTP parameters, and 4106 field IDs. Changing order, IDs, or child-tab semantics affects both request paths; update them together and consult doc/market-ranking-known-issues.md before refactoring.
• HQ requests use 4106, frame 2201, scenario qht_qihuo_sort, and pushtime=2.5; subscriptions must be released on page invisibility, Tab changes, refresh, and component destruction. TCP reconnect rebuilds the subscription from the original HTTP contract list.
• The component guards asynchronous HTTP and quote callbacks with request/subscription versions; preserve those guards when changing refresh or Tab behavior. Row clicks use host jumpToQuote() and must preserve contract, market, and name list ordering.
• Market-ranking host integration still requires validation of 4106 field IDs, standard-price fields, HTTP environment/auth, lifecycle/reconnect behavior, and quote-page routing; see doc/market-ranking-known-issues.md.

Conventions

• Use $r('app.color.*') and the light/dark resource qualifiers for colors; do not hardcode theme colors. Put user-facing strings in src/main/resources/{base,zh_CN,en_US}/element/string.json.
• FirstPageDebugUtil.isMarketRankingUseTestUrl and other test URL switches default to false; leave them disabled in commits.
• Two files are named FirstPageConstant.ets: datacenter/FirstPageConstant.ets holds KEY_* card-dispatch constants, while util/FirstPageConstant.ets only exports TITLE_BAR_HEIGHT. Import the correct one.
• biz_quote is imported both from its package root and deep paths; preserve the existing import style when touching quote code.
• Release builds enable ArkGuard through build-profile.json5; keep obfuscation-rules.txt and consumer-rules.txt in mind when adding public or reflective symbols.