From a07c497d7e95f6ca0a5a8f28fe158e9535bd61ba Mon Sep 17 00:00:00 2001
From: clz <fadinglight9291117@126.com>
Date: Thu, 30 Jul 2026 17:24:35 +0800
Subject: [PATCH] docs: rewrite project readme

---
 readme.md | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 166 insertions(+), 4 deletions(-)

diff --git a/readme.md b/readme.md
index 83f6b3d..0d3af92 100644
--- a/readme.md
+++ b/readme.md
@@ -1,6 +1,168 @@
-# 模块介绍
+# biz_firstpage
 
-## 模块功能
-手炒首页相关，宫格模块与首页卡片
+`biz_firstpage` 是期货业务首页的 Stage 模型 HAR 模块，对外包名为
+`@b2c/first_page`。模块负责首页信息流编排、行情及 AI 卡片、资讯页面、
+宫格页面和首页浮层广告，并由宿主应用提供路由、行情、广告、账户及主题等
+运行能力。
 
-##
\ No newline at end of file
+## 功能范围
+
+- 首页标题栏、背景、下拉刷新和可见性生命周期管理
+- 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` | 提供给消费方的混淆规则 |