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