biz_firstpage

biz_firstpage 是期货业务首页的 Stage 模型 HAR 模块，对外包名为 @b2c/first_page。模块负责首页信息流编排、行情及 AI 卡片、资讯页面、宫格页面和首页浮层广告，并由宿主应用提供路由、行情、广告、账户及主题等运行能力。

功能范围

首页标题栏、背景、下拉刷新和可见性生命周期管理
Banner、运营头图、四宫格、自定义宫格和自选行情
热点资讯、商品期权、AI 品种诊断、AI 看涨跌
AI 选期和市场排名
首页弹窗广告、悬浮球及相关状态管理
热点资讯详情页和全部宫格页
中英文文案及浅色、深色主题资源

对外接口

模块的宿主接口统一从根目录的 Index.ets 导出：

导出项	用途
`FirstPage`	首页主组件
`HotNewsPage`	热点资讯列表页
`HotNewsDetailPage`	热点资讯详情页
`GridNodeAllPage`	全部宫格页
`FirstPagePopupAdHelper`	首页弹窗广告辅助类
`AdsPopupView`	广告浮层视图
`AdFloatState`	广告悬浮状态
`SpAdsComponent`	广告组件
`PopupRecord`	弹窗记录模型
`AdsPopupHost`	广告浮层宿主
`AdsBallManager`	广告悬浮球管理器

新增需要被宿主直接使用的组件、类型或工具时，应同步从 Index.ets 导出。

目录结构

.
├── Index.ets                         # HAR 对外导出入口
├── src/main
│   ├── ets
│   │   ├── components/mainpage       # 首页主组件
│   │   ├── constants                 # AI 选期、市场排名等常量
│   │   ├── datacenter                # 首页和卡片数据获取、首页模型
│   │   ├── node
│   │   │   ├── clients               # 行情请求与订阅客户端
│   │   │   ├── datacenter            # Node 级数据获取
│   │   │   ├── helper                # Node 辅助逻辑
│   │   │   ├── model                 # 卡片数据模型
│   │   │   └── view                  # 卡片视图
│   │   ├── pages                     # 独立业务页面
│   │   ├── popup                     # 弹窗广告和悬浮球
│   │   ├── router                    # 模块路由
│   │   ├── util                      # 格式化、映射和通用工具
│   │   └── views                     # 首页公共视图
│   └── resources
│       ├── base/zh_CN/en_US           # 文案和基础资源
│       ├── light/dark                 # 主题颜色
│       └── rawfile                    # 卡片配置和静态配置
├── src/ohosTest                       # Hypium 测试模块骨架
└── doc                                # 设计审查和已知问题

宿主集成

本仓库不是可独立运行的应用工程。它以 HAR 形式集成到完整宿主项目，宿主需要：

引入 @b2c/first_page 及其业务依赖。
提供 biz_quote、主题管理，以及源码中使用的公共业务模块和系统能力。
初始化首页依赖的全局上下文、路由、行情连接、账户状态和广告服务。
创建并传入宿主维护的 FirstPageTabManager，用于通知首页 Tab 可见性。
注册 src/main/resources/base/profile/main_pages.json 中需要使用的页面。

根 oh-package.json5 中声明了当前模块的直接依赖：

{
  "dependencies": {
    "biz_quote": "file:../biz_quote",
    "@kernel/theme_manager": "1.0.2-beta.17"
  }
}

其中 biz_quote 使用相邻目录路径，实际集成时应保持宿主仓库的既有目录和依赖组织方式，不要为了单独运行本模块而补造宿主依赖。

首页卡片接入

常规首页卡片通常需要同时完成以下接线：

在 src/main/ets/datacenter/FirstPageConstant.ets 增加唯一的 KEY_*。
在首页数据模型中插入或接收对应卡片模型。
在 FirstPage.createNodeView 中增加渲染分支。
在 src/main/resources/rawfile/first_page_cards_config.json 增加服务端卡片元数据，包括 card_key、render_key、标题、跳转和接口配置。
将视图、模型、数据获取和常量分别放入现有职责目录。
为新增文案补齐 base、zh_CN 和 en_US 资源，并通过 $r('app.color.*') 使用主题颜色。

注意，项目中存在两个同名的 FirstPageConstant.ets：

datacenter/FirstPageConstant.ets：定义首页卡片 KEY_*。
util/FirstPageConstant.ets：只定义标题栏高度等 UI 常量。

不要将卡片 ID 添加到 util 目录的文件中。

市场排名的特殊接线

市场排名不完全遵循普通卡片的装载方式：

首页通过 KEY_MARKET_RANKING 直接插入和渲染卡片。
rawfile 配置键固定为 marketRanking。
MarketRankingDataFetcher 先通过 @kit.NetworkKit 获取推荐合约。
MarketRankingHqRequestClient 再通过宿主 TableRequestClient 的 4106 链路订阅行情。
4106 frame 2201、场景 qht_qihuo_sort 和 pushtime=2.5 应保持一致。
页面不可见、切换 Tab、刷新和组件销毁时必须释放订阅；TCP 重连后应使用原始 HTTP 合约列表重建订阅。
HTTP 请求与行情订阅的版本保护、合约/市场/名称顺序及 jumpToQuote() 路由参数不能被破坏。

修改此功能前请先阅读：

doc/market-ranking-known-issues.md
doc/market-ranking-ai-pick-code-review.md

资源与发布约束

用户可见文案放入 src/main/resources/{base,zh_CN,en_US}/element/string.json。
颜色放入资源文件，并按需在 light、dark qualifier 中提供主题值，避免在 ArkUI 代码中硬编码主题颜色。
提交代码时，FirstPageDebugUtil.isMarketRankingUseTestUrl 及其他测试环境开关必须保持为 false。
保持现有 biz_quote 根路径和深路径导入风格，避免无关的依赖整理。
新增公开或反射访问的符号时，检查 obfuscation-rules.txt 和 consumer-rules.txt，确保 release ArkGuard 配置完整。

验证

此 checkout 缺少 hvigorw、oh_modules、相邻的 ../biz_quote，并依赖宿主提供的多个业务模块，因此不能在仓库内独立完成可靠的构建、运行或测试。

改动应放入完整宿主工程验证，至少覆盖：

biz_firstpage HAR 的 debug 和 release 集成构建
src/ohosTest 测试模块的编译与执行
首页拉取、下拉刷新、Tab 显隐和自动刷新生命周期
浅色/深色主题及中英文资源
页面路由、广告弹窗和悬浮球
AI 选期、市场排名的 HTTP 环境与鉴权
4106 字段、标准价、订阅释放和 TCP 重连
行情列表点击后的合约、市场、名称传递及详情页跳转

文件	说明
`build-profile.json5`	HAR target、ohosTest target 和 release 混淆配置
`src/main/module.json5`	HAR 模块类型、设备类型和网络权限
`src/main/resources/rawfile/first_page_cards_config.json`	首页卡片元数据
`src/main/resources/base/profile/main_pages.json`	模块页面清单
`obfuscation-rules.txt`	本模块 release 混淆规则
`consumer-rules.txt`	提供给消费方的混淆规则

7.3 KiB Raw Blame History Unescape Escape