# 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` 导出。

## 目录结构

```text
.
├── 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 形式集成到完整宿主项目，宿主需要：

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

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

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

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

## 首页卡片接入

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

1. 在 `src/main/ets/datacenter/FirstPageConstant.ets` 增加唯一的 `KEY_*`。
2. 在首页数据模型中插入或接收对应卡片模型。
3. 在 `FirstPage.createNodeView` 中增加渲染分支。
4. 在 `src/main/resources/rawfile/first_page_cards_config.json` 增加服务端卡片
   元数据，包括 `card_key`、`render_key`、标题、跳转和接口配置。
5. 将视图、模型、数据获取和常量分别放入现有职责目录。
6. 为新增文案补齐 `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` | 提供给消费方的混淆规则 |