docs: rewrite project readme
This commit is contained in:
@@ -1,6 +1,168 @@
|
|||||||
# 模块介绍
|
# 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` | 提供给消费方的混淆规则 |
|
||||||
|
|||||||
Reference in New Issue
Block a user