xsl/meida
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: xsl/meida:33624a7650785b7c631d71a3b5ec151aa83b2989
Branches Tags
xsl/meida:main
...
compare: xsl/meida:256f850a6146e49b7245b8cff1fe370f6fd514b7
Branches Tags
xsl/meida:main
3 Commits
33624a7650 ... 256f850a61
Author SHA1 Message Date
xsl 256f850a61 docs: 客户端开发交接文档（新机器开工自包含） 
客户端开发将转移到另一台机器，本文沉淀本机全部实操经验：
- 环境搭建 + CLI 构建 + 首次自动签名（Account Kit 前置，signingConfigs 现为空）
- AGC 现状：App ID 6917613748100335131 已建、包名核对一致；待办三步
  （自动签名→指纹录入→开 Account Kit 标准登录）
- 后端联调：后端在原开发机 WSL 8666 端口，两种连法（局域网直连/自建）；
  DEFAULT_BASE_URL(127.0.0.1:8000) 已过时的说明；dev-token 为主力调试通道
- ArkTS 铁律七条（新增 @Builder 按值传参不随 @State 刷新的 2488 教训）
- hdc/uitest 实测命令与坑（MSYS_NO_PATHCONV、相对路径、dumpLayout 解析法）
- 真机修过的五个坑清单 + 待办任务与开工验收基线
 2026-08-15 22:00:12 +08:00
xsl 4125769457 docs: 办理记录——AGC 应用已建（App ID 6917613748100335131），待自动签名+指纹录入 2026-08-15 21:56:39 +08:00
xsl 67d906248b docs: 前置开通清单 v2——个人开发者降级路线 
需求变更（个人主体办不了短信签名、前期无 COS 必要）：
- 登录兜底通道：短信验证码 → 邮箱验证码（个人邮箱 SMTP 授权码，
  零成本零审核；防刷参数 FR-ACC-14 原样沿用，键前缀 sms:→email:）
- 主登录通道维持华为账号：查证 Account Kit 权限分级——个人开发者
  可用标准登录（UnionID/昵称/头像），仅"一键登录取手机号"企业专属；
  我们只需 UnionID，标准登录够用
- COS 四桶 → 服务器本地磁盘（meida_data/ 四目录，上传走后端 multipart，
  下载走短期签名 URL；CosSigner Protocol 保留，回迁只换实现）
- 数据库：PG 已在 WSL 运行零费用，无需动作；明确不切 SQLite
  （retrieval 依赖 pgvector，切换=重构+能力回退）

清单从"腾讯云全家桶"收缩为两件必办：华为 AGC + 发信邮箱授权码。
登记代码侧后续任务 E1~E4（邮箱登录/本地存储驱动/FE 登录 UI/文档同步）
 2026-08-15 18:49:55 +08:00
2 changed files with 283 additions and 54 deletions
Expand all files Collapse all files
docs/前置开通清单-云资源与资质.md
+111 -54
View File
@@ -1,85 +1,140 @@
# 前置开通清单：云资源与资质（本机开发期间并行办理）
# 前置开通清单：云资源与资质（个人开发者版 v2）
> 创建日期：2026-08-14 ｜ 性质：**行动清单**（照着办，办完打勾）
> 创建日期：2026-08-14 ｜ **v2 修订：2026-08-15（需求变更：个人开发者主体降级路线）**
>
> **为什么有这份清单**：开发策略是"本机开发完成、腾讯云部署放最后"。但以下三项**有审核周期或属于边开发边对接的配置**，必须现在启动，否则会在 Sprint 0 出口（双登录通道）和 Sprint 4（真机联调）反向卡住开发进度。
> 它们只是"开通 + 拿到凭证"，**不涉及任何应用部署**，成本接近零。
> **v2 变更原因**：App 为个人开发，腾讯云短信签名需要企业/个人主体资质材料，办不下来；前期用户量小，COS 对象存储暂无必要。整体策略从"腾讯云全家桶"降级为"**华为 AGC + 一个发信邮箱**"，其余全部本机/本地承载。
>
> **不在本清单内的**（避免混淆范围）：
> - CVM/TKE、CLB、域名 + HTTPS、CDN 全量、CLS、压测 —— 全部归 Phase 5 部署
> - 真实环境红线验证（临时桶 2 小时实测、AI 标识元数据经 CDN 存活、天御误杀率）—— 归 Sprint 1/5 的专项验证任务
> - 本机开发的一切（PG/Redis/GPU/LLM 调用）—— 不需要任何云资源
> **v2 三项需求变更**：
> 1. **登录兜底通道：短信验证码 → 邮箱验证码**（个人邮箱 SMTP 授权码即可，零成本、零审核）
> 2. **主登录通道维持华为账号登录**（已查证：个人开发者可用"标准登录"，见 §1）
> 3. **对象存储：COS 四桶 → 服务器本地磁盘**（文件存后端 data 目录，后端生成访问 URL）
>
> **数据库说明**（原清单本就不含云数据库）：PostgreSQL 16 已运行在 WSL 内，零云依赖、零费用，**无需任何动作**。不切 SQLite 的理由见 §4。
---
## 1. 腾讯云账号 + 实名 + 短信签名/模板审核 🔴 最先办（有审核周期）
## 0. 总览：现在真正要办的外部事项只剩两件
**对应**：`T-P1-12b/12c`、`TD-32`（短信是 V1 登录兜底通道，且是被刷时唯一直接现金损失项）
| # | 事项 | 成本 | 审核周期 | 状态 |
| --- | --- | --- | --- | --- |
| A | 华为开发者账号 + AGC 创建应用 + 开通 Account Kit | 免费 | 实名认证 1~3 天 | ⬜ |
| B | 一个发信邮箱的 SMTP 授权码（QQ/163/Gmail 均可） | 免费 | 即时（5 分钟） | ⬜ |
**已从清单移除**（原 v1 的 §1、§2 整节）：腾讯云账号/实名/短信套餐包/短信签名/验证码模板/CAM 子账号/COS 四桶 —— 全部后移到"有真实用户量、需要公网部署"时再评估（见 §5）。
---
## 1. 华为开发者后台 + Account Kit 🔴 主登录通道（唯一必办外部事项）
**对应**：`T-P1-12/13`（华为账号登录）、用户系统 §2.1。
**个人开发者可用性结论（2026-08 查证）**：Account Kit 权限分级——
| 能力 | 个人开发者 |
| --- | --- |
| **华为账号标准登录**（获取 UnionID / 昵称 / 头像） | ✅ 可用 |
| 静默登录（自动授权） | ✅ 可用 |
| 一键登录（获取手机号）+ UnionID | ❌ 仅企业 |
| 获取收货地址等高级权限 | ❌ 仅企业 |
我们只需要 UnionID 做账号映射（`id_user_identity`，后端 `packages/identity/huawei.py` 已实现），**标准登录完全够用，不需要手机号**。
| # | 事项 | 要点 | 完成 |
| --- | --- | --- | :---: |
| 1.1 | 注册腾讯云账号 + 实名认证 | 主体资质决定短信签名审核难度，个人主体限制多；按实际情况选，若可走企业主体优先 | ⬜ |
| 1.2 | 购买国内短信套餐包 | 最小档即可（验证码短信一条几分钱），目的是拿到发送资格 | ⬜ |
| 1.3 | **申请短信签名** | 签名内容与主体资质材料一致（App 名称/公司名等，以腾讯云审核要求为准）；**审核有周期，被驳回按驳回原因补材料重提** | ⬜ |
| 1.4 | 申请验证码模板 | 登录验证码类型；模板变量只留 `{1}`（验证码），不含营销语 | ⬜ |
| 1.5 | 创建子账号 + CAM 最小授权 | 只授 SMS 与 COS 相关权限；**不用主账号密钥** | ⬜ |
| 1.6 | SecretId/SecretKey 落位 | **只写后端仓库 `.env`**（已 gitignore + CI 双密钥扫描）；文档仓库 `reference/` 禁止出现密钥 | ⬜ |
| 1.1 | 注册华为开发者账号（个人类型） | 身份证实名认证；审核 1~3 天 | ⬜ |
| 1.2 | AGC 创建应用 | 包名用最终包名 `com.xiangsilian.app`（上架后难改）；拿到 App ID | ⬜ |
| 1.3 | 开通 Account Kit | AGC「我的项目 → 添加服务」，选华为账号（标准登录即可，**不要**申请"获取手机号"权限——那是企业专属，申请必拒） | ⬜ |
| 1.4 | **证书指纹录入** | 调试证书 SHA256 必须配到 AGC（DevEco Studio 自动签名后，在 AGC「应用信息 → 证书指纹」处粘贴），否则真机拉不起授权页 | ⬜ |
| 1.5 | 发布证书指纹 | 上架时再办（发布证书申请时一并录入 AGC）——**注意漏配的表现是"调试包登录正常、发布包登录失败"** | ⬜ 后置 |
| 1.6 | Push Kit | 继续后置（通知授权默认关闭，`TD-17`），联调期再开 | ⬜ 后置 |
**验收**：用测试手机号在腾讯云控制台试发一条模板短信，能收到。
**开发对接参数**（实现 `T-P1-12c` 防刷时按此配置，源：`FR-ACC-14`）：同号 60s 内 1 条、1 小时 ≤5、24h ≤10；同 IP 24h ≤20；同设备 24h ≤10。
**验收**：用调试证书签名的 App 能拉起华为授权登录页，授权后拿到 UnionID 并映射到 `id_user_identity`。
---
## 2. COS 四桶创建 🔴 一并办（空桶成本 ≈ 0）
## 2. 邮箱验证码（兜底登录通道，替代原短信方案）🟡 5 分钟办完
**对应**：`T-P1-04`（开通部分）、`TD-03`、`T-P1-27`（直传联调时再对细节）
**对应**：`T-P1-12b/12c` 需求改写（原短信任务 → 邮箱任务）、`FR-ACC-14`。
**方案**：任一个人邮箱开启 SMTP 服务拿"授权码"，后端用它发验证码邮件。
| # | 事项 | 要点 | 完成 |
| --- | --- | --- | :---: |
| 2.1 | 确定地域 | **四桶 + 未来的 CVM/CDN 同地域**（内网直连、免流量费）；定了就不要换 | ⬜ |
| 2.2 | 创建 `meida-temp` | 临时桶：**生命周期规则 = 2 小时清理**（`CR-02` 人脸原图不落盘的兜底，上线红线）；私有读写 | ⬜ |
| 2.3 | 创建 `meida-user` | 用户内容桶：私有读写（结果图走预签名 URL，`NFR-SEC-02`） | ⬜ |
| 2.4 | 创建 `meida-kb` | 知识素材桶（白底图等） | ⬜ |
| 2.5 | 创建 `meida-report` | 报告产物桶（长图等） | ⬜ |
| 2.6 | 顺手做一次 2 小时实测 | 往 `meida-temp` 传一个文件，2 小时后确认被自动清理 —— **这正是 Sprint 0 出口条件之一**，今天办今天验，别留到上线前 | ⬜ |
| 2.7 | 记录四桶名称与地域 | 归档到团队可见处；后端 `.env` 后续按此填 | ⬜ |
| 2.1 | 选一个发信邮箱 | 推荐 QQ 邮箱或 163（国内到达率高、授权码机制成熟）；Gmail 也行但国内服务器投递慢 | ⬜ |
| 2.2 | 开启 SMTP 拿授权码 | QQ：设置 → 账号 → 开启 SMTP 服务 → 生成授权码；163 同理 | ⬜ |
| 2.3 | 授权码落位 | **只写后端仓库 `.env`**（已 gitignore）：`SMTP_HOST` / `SMTP_PORT(465)` / `SMTP_USER` / `SMTP_PASS`（授权码）/ `MAIL_FROM` | ⬜ |
**暂不需要做**：CORS 跨域、直传预签名策略 —— 等 `T-P1-27` 开发时边联调边配。
**量级评估**：个人邮箱 SMTP 每日发信上限约百封级（QQ/163），验证码场景（每用户登录 1~2 封）前期绰绰有余；日发信超限或到达率不稳时，再换免费档邮件 API（Resend/SendGrid/阿里邮件推送），代码侧只是换一个 `EmailSender` 实现。
**防刷参数不变**（`FR-ACC-14` 原样沿用，键前缀从 `sms:` 改 `email:`）：同邮箱 60s 内 1 条、1 小时 ≤5、24h ≤10；同 IP 24h ≤20；同设备 24h ≤10。
**验收**：后端 `.env` 配好后，向自己的另一个邮箱发一封验证码邮件，能收到。
---
## 3. 华为开发者后台（应用 + 证书指纹双套配置）🟡 本周内
## 3. 文件存储：服务器本地磁盘（替代 COS 四桶）—— 无需办理，代码侧改造
**对应**：`T-P1-12/13`（华为账号登录）、用户系统 §2.1；`T-P0-17`（端侧骨架）的前置
| # | 事项 | 要点 | 完成 |
| --- | --- | --- | :---: |
| 3.1 | AGC 创建应用 | 包名定为最终包名（上架后难改）；拿到 App ID | ⬜ |
| 3.2 | 申请/确认调试证书与发布证书 | **两套都要** | ⬜ |
| 3.3 | **证书指纹双套录入** | 调试证书与发布证书的 SHA256 指纹**都要**配到 AGC；**漏配发布指纹的表现是"调试包登录正常、发布包登录失败"**，这种错最晚才暴露 | ⬜ |
| 3.4 | 开通 Account Kit | 华为账号授权登录（UnionID/OpenID 映射 `id_user_identity`） | ⬜ |
| 3.5 | Push Kit 可后置 | 通知授权默认关闭（`TD-17`），Sprint 0 不阻塞，联调期再开 | ⬜ |
**验收**：用调试证书签名的 App 能拉起华为授权登录页（发布通道的验证归 Phase 5）。
---
## 4. 办理顺序与完成标志
**方案**：四桶变四个本地目录，上传走后端、下载 URL 由后端签发：
```
今天 ：1.1 → 1.2 → 1.3（短信签名审核周期最长，最先提交）
：2.1 → 2.2~2.5（半小时的事）→ 2.6 挂着等 2 小时
本周内 ：3.1 ~ 3.4（AGC 配置）
签名审核通过后 ：1.4 模板 → 1.5/1.6 密钥落位 → 控制台试发验收
/home/xsl/meida_data/
├── temp/ # 用户原图：2 小时定时清理（CR-02，celery beat 已有 io 队列可挂）
├── user/ # 用户内容
├── kb/ # 知识素材（白底图等）
└── report/ # 报告产物（长图等）
```
**整体完成标志**（三条全绿即本清单关闭）：
- [ ] 测试手机号收到验证码短信
- [ ] 四桶就位且 `meida-temp` 实测 2 小时清理生效
- [ ] 调试证书 App 拉起华为授权页
- **上传**：客户端 `POST /api/v1/storage/upload`（multipart，带鉴权）——不再"直传+预签名"，应用服务器中转；前期流量小，无压力
- **下载**：后端签发短期带签名 URL（复用现有 `CosSigner` Protocol 的位置换 `LocalStorageDriver` 实现，业务代码零改动）
- **回迁路径**：`CosSigner` Protocol 保留，未来用户量上来切回 COS 只需换实现 + 搬数据，业务代码不动
> 办理过程中的凭证（App ID、SdkId、签名 ID、桶名/地域等非机密信息）建议登记到本文末尾的"办理记录"表；**密钥类一律只进后端 `.env`**。
**v1 骨架不受影响**：FE 当前照片键本来就是模拟的（`report_photo/{userId}/{随机}.jpg`），本地驱动下这些键直接对应 `meida_data/` 下的文件路径，行为一致。
---
## 4. 数据库：无需任何动作（且不建议切 SQLite）
- PostgreSQL 16 + pgvector **已经在 WSL 内运行**，承载全部迁移（0001~0006）与 32 维检索，零云依赖、零费用
- **不切 SQLite**：检索域（`packages/retrieval`）依赖 pgvector 做向量近邻搜索，SQLite 无等价物——切换等于大重构 + 检索能力回退成暴力扫描；而本机 PG 不产生任何费用，切了没有任何收益
- 真要减负的时机是公网部署时：CVM 自托管 PG 或云数据库，到时再议
---
## 5. 移除/后移项汇总（对照 v1）
| 原 v1 清单项 | 处置 | 理由 |
| --- | --- | --- |
| 腾讯云账号 + 实名认证 | **移除** | 随短信/COS 整体暂缓 |
| 短信套餐包 / 签名 / 模板 | **移除，需求变更为邮箱验证码**（§2） | 个人主体办不下签名 |
| 子账号 + CAM 最小授权 | 后移 Phase 5 | 腾讯云暂缓后无对象可授权 |
| COS 四桶 + temp 桶 2 小时生命周期实测 | **后移，需求变更为本地磁盘**（§3） | 前期用户量小；2 小时清理改 celery 定时任务 |
| AGC 应用 / 证书指纹 / Account Kit | **保留**（§1，唯一必办） | 华为账号是主登录通道 |
| Push Kit | 保留后置 | 不变 |
---
## 6. 需求变更引发的代码任务（后续排期，不在本清单内办）
| 任务 | 内容 | 影响面 |
| --- | --- | --- |
| E1 后端：邮箱登录 | `sms_login.py` → `email_login.py`：`SmsSender` Protocol → `EmailSender`（SMTP 实现 + `FakeEmailSender`）；手机号正则 → 邮箱正则；`union_id` 前缀 `"phone:"` → `"email:"`；Redis 键 `sms:*` → `email:*`；路由与错误码文案同步 | `packages/identity`，设计上零耦合华为通道，改动封闭 |
| E2 后端：本地存储驱动 | `QcloudCosSigner` → `LocalStorageDriver`（同 Protocol）；新增 multipart 上传端点；temp 目录 2 小时清理任务挂 celery beat | `packages/storage` |
| E3 FE：登录页邮箱输入 | 登录页手机号输入框 → 邮箱输入框 + 验证码（当前 FE 只有 dev-token 调试登录，正式登录 UI 本就是待办） | `pages/LoginPage` |
| E4 文档同步 | Sprint 执行计划 v1.1 / 开发任务拆解 v1.5 中 `T-P1-12b/12c`（短信）、`T-P1-04/27`（COS）的任务表述按本变更改写 | `docs/` |
---
## 办理顺序与完成标志
```
今天 ：2.1 → 2.2 → 2.3（邮箱授权码，5 分钟）
今天 ：1.1（华为开发者注册提交，等审核 1~3 天）
审核通过后：1.2 → 1.3 → 1.4（AGC 应用 + Account Kit + 调试指纹）
```
**整体完成标志**（两条全绿即本清单关闭）：
- [ ] 调试证书 App 拉起华为授权页，拿到 UnionID
- [ ] 测试邮箱收到验证码邮件
---
@@ -87,4 +142,6 @@
| 日期 | 事项 | 结果 / 备注 |
| --- | --- | --- |
| 2026-08-15 | 1.2 AGC 创建应用 | ✅ App ID `6917613748100335131`，包名 `com.xiangsilian.app`（与工程 `AppScope/app.json5` 核对一致）。App ID 无需写入代码，登记备查（后续接 Push Kit 时才用于 module.json5 的 client_id 配置） |
| 2026-08-15 | 工程签名现状核查 | ⚠️ `build-profile.json5` 的 signingConfigs 为空（从未做过 IDE 自动签名，CLI 构建均为 unsigned 包）。**开通 Account Kit 前必须先做自动签名**：DevEco Studio → File → Project Structure → Signing Configs → 勾选 Automatically generate signature（需登录华为开发者账号）→ 生成调试证书后提取 SHA256 指纹录入 AGC |
| | | |
docs/客户端开发交接-新机器.md
+172
View File
@@ -0,0 +1,172 @@
# 客户端开发交接文档（新机器）
> 创建：2026-08-15 ｜ 用途：**客户端（鸿蒙 FE）开发转移到另一台机器**，本文自包含开工所需的一切。
> 上游文档：`docs/开发任务包/README-FE批次.md`（FE 协作规程与 API 速查）、`docs/本地联调指南.md`（后端起停）、`docs/前置开通清单-云资源与资质.md`（AGC 与外部资源）。
---
## 0. 一句话现状
FE 骨架已完成并通过真机验证的闭环：**dev-token 登录 → 首页配额/对话 → 报告创建（校验/提交/轮询）→ 结果页 32 维渲染 → 40920"本期已生成"对话框**。全部代码在 `main` 分支，直接 clone 即得。
| 仓库 | 地址 | 内容 |
| --- | --- | --- |
| 主仓库 | `https://git.xiangsilian.com/xsl/meida.git` | 文档 + 客户端工程（`app/`） |
| 后端仓库 | `https://git.xiangsilian.com/xsl/meida_backend.git` | FastAPI 后端（原开发机 WSL 运行中） |
---
## 1. 新机器环境搭建
### 1.1 装软件
1. **DevEco Studio**（含 HarmonyOS SDK，API 6.1.1(24)）——默认装到 `C:\Program Files\Huawei\DevEco Studio\`
2. 手机开启**开发者模式 + USB 调试**（设置 → 关于 → 连点版本号 → 开发者选项）
### 1.2 拿代码 + 用 DevEco 打开
```bash
git clone https://git.xiangsilian.com/xsl/meida.git
# 用 DevEco 打开 meida/app 工程（File → Open）
```
### 1.3 首次必做：自动签名（Account Kit 的前置）
工程当前 `build-profile.json5` 的 `signingConfigs` 为空（历史包都是 unsigned）。
**DevEco Studio → File → Project Structure → Signing Configs → 勾选 "Automatically generate signature"**，登录华为开发者账号生成调试证书。没做这步，华为账号授权页拉不起来。
### 1.4 CLI 构建（可选，配了 IDE 签名后 CLI 包也会带签名）
```bash
cd <repo>/app
export DEVECO_SDK_HOME="C:/Program Files/Huawei/DevEco Studio/sdk"
"C:/Program Files/Huawei/DevEco Studio/tools/node/node.exe" \
"C:/Program Files/Huawei/DevEco Studio/tools/hvigor/bin/hvigorw.js" \
--mode module -p module=entry@default assembleHap --analyze=false --daemon=false
# BUILD SUCCESSFUL 即通过；产物 app/entry/build/default/outputs/default/
```
路径按新机器实际安装位置调整。"No signingConfigs" WARN 在未配签名时正常。
---
## 2. AGC / 华为侧配置
**已完成**：AGC 应用已创建——**App ID `6917613748100335131`**，包名 `com.xiangsilian.app`（与工程 `app/AppScope/app.json5` 一致）。App ID **不需要**写进代码（Account Kit 靠签名证书+包名识别应用）。
**待办三步**（详见前置开通清单 §1）：
| # | 事项 | 位置 |
| --- | --- | --- |
| 1 | 自动签名生成调试证书 | DevEco（§1.3，做完告诉我/记录指纹） |
| 2 | 调试证书 SHA256 指纹录入 AGC | AGC「我的项目 → 应用信息 → 证书指纹」 |
| 3 | 开通 Account Kit（**标准登录**即可，别申请"获取手机号"权限——企业专属，申请必拒） | AGC「我的项目 → 添加服务」 |
个人开发者权限边界：标准登录（UnionID/昵称/头像）✅；一键登录（手机号）❌ 企业专属。我们只需要 UnionID。
---
## 3. 后端联调（重点：后端不在新机器上）
后端跑在**原开发机**的 WSL（Ubuntu-22.04 `/home/xsl/meida_backend`），端口 **8666**（不是 8000）。两种连法：
| 方案 | 做法 | 适用 |
| --- | --- | --- |
| A. 连原机后端 | 新机器与原机同局域网；App 登录页输入 `http://<原机局域网IP>:8666`；原机需后端监听 0.0.0.0 + Windows 防火墙放行 8666 | 最快，推荐 |
| B. 新机器自建后端 | clone `meida_backend`，按 `docs/本地联调指南.md` 起（需 WSL + PG + Redis + .env 密钥） | 需要独立调试后端时 |
**baseUrl 机制**：FE 登录页有"服务器地址"输入框，输一次持久化（preferences）。代码里 `core/AuthStore.ets` 的 `DEFAULT_BASE_URL = 'http://127.0.0.1:8000'` 已过时，**实际一律用登录页输入 8666**；真机别用 127.0.0.1（那是手机自己）。
**联调期登录通道**：`POST /api/v1/auth/dev-token`，请求体 `{"device_key": "<任意字符串>"}`，无需华为/短信——FE 已封装（AuthStore.loginByDevToken），是主力调试通道。
---
## 4. 工程结构与已完成内容
```
app/entry/src/main/ets/
├── core/
│ ├── ApiClient.ets # 信封解析（非200 HTTP 也先验 {code,...} 信封形状再判成败）
│ ├── ApiTypes.ets # ApiError（唯一可抛异常类型）
│ └── AuthStore.ets # 双令牌持久化 + dev-token 登录（postWithoutAuth 通道）
├── pages/
│ ├── LoginPage # 地址输入 + dev-token 登录
│ ├── HomePage # 配额卡片 + 报告入口
│ ├── ChatPage # AI 对话（F4）
│ ├── ReportCreatePage # 问卷六字段 + 校验 + 提交 + 轮询（F3）
│ ├── ReportResultPage # 32 维渲染 + 重新生成（F3）
│ └── ProfilePage / TaskCenterPage（F1/F2）
└── components/f2 f3 f4/ # TaskPollingPanel（任务轮询）、ReportTypes 等公共件
```
路由注册在 `entry/src/main/resources/base/profile/main_pages.json`（新页面必须登记）。
**真机修过的坑（别回退）**：
1. dev-token 登录必须走 `postWithoutAuth`（带鉴权的 post 会因未登录自拦 40100）
2. ApiClient 非 200 HTTP 状态（409/429 等）body 仍是统一信封，先验信封形状再判成败——业务错误 40920/40301/42910 靠这条透传
3. DatePicker 默认折叠成"修改 ▼"（展开态半屏，会把必填项和提交键挤出视野）
4. 轮询成功自动跳转有兜底："查看报告"按钮 + replaceUrl().catch
5. 表单校验三件套：汇总条点名缺失字段 + 自动滚动到首个错误 + 字段级红字（@Builder $$ 传参，见 §5.7）
---
## 5. ArkTS 严格模式铁律（实测踩坑，违反必炸编译/运行）
1. **泛型调用必须显式类型参数**：`ApiClient.post<void>(...)`——裸 `post(...)` 报 `arkts-no-inferred-generic-params`
2. **请求体用具型 Record 字面量**：`const req: Record<string, Object> = { 'k': v }`；禁止 interface→Record 强转、禁止内联对象类型做泛型参数
3. **wire 响应类型用具名 interface**，字段名对齐后端 JSON
4. **throw 只抛 ApiError**；未知异常包 `new ApiError(50000, '请求失败，请检查网络', '请稍后重试')`
5. **对象字面量必须有具名类型**；async 逻辑放具名方法（箭头链泛型推断受限）
6. `router` 从 `@kit.ArkUI` 导入（`@ohos.router` 编译不过）
7. **@Builder 按值传参不随 @State 刷新**（2026-08-15 新踩）：`@Builder f(label: string, err: string)` 的 err 永远停在初始值；必须 `$$` 按引用传参——`@Builder f($$: FieldLabelParams)` + 调用传对象字面量 `{ label: '...', err: this.xxxErr, ... }`
---
## 6. 真机调试工具箱（实测命令与坑）
```bash
HDC="C:/Program Files/Huawei/DevEco Studio/sdk/default/openharmony/toolchains/hdc.exe"
"$HDC" list targets # 看设备
"$HDC" -t <target> shell aa start -a EntryAbility -b com.xiangsilian.app # 拉起 App
cd <产物目录> && "$HDC" -t <t> install -r entry-default-*.hap # 装（本地路径必须相对！绝对路径会被拼错）
# UI 注入（自动化验证主力）
"$HDC" -t <t> shell uitest uiInput click <x> <y>
"$HDC" -t <t> shell uitest uiInput inputText <x> <y> <文本> # 偶发 Invalid parameters 时改用：
"$HDC" -t <t> shell uitest uiInput text <文本> # 输入到已聚焦输入框
"$HDC" -t <t> shell uitest uiInput keyEvent Back # 收键盘
"$HDC" -t <t> shell uitest uiInput swipe <x1> <y1> <x2> <y2> 600 # 滚动=上滑
# 布局dump + 截图（拿坐标/验证UI状态）
MSYS_NO_PATHCONV=1 "$HDC" -t <t> shell uitest dumpLayout -p /data/local/tmp/layout.json
MSYS_NO_PATHCONV=1 "$HDC" -t <t> file recv /data/local/tmp/layout.json layout.json # recv 到当前目录
MSYS_NO_PATHCONV=1 "$HDC" -t <t> shell snapshot_display -f /data/local/tmp/shot.jpeg
```
**坑**：
- Git Bash 会把 `/data/...` 改写成 `C:/Program Files/Git/data/...`——所有带设备路径的命令前加 `MSYS_NO_PATHCONV=1`
- `install` 的本地路径必须 cd 到目录后用相对路径，绝对路径会被 hdc 拼接错
- dumpLayout 是 JSON，用 python 解析 `attributes.bounds`（格式 `[x1,y1][x2,y2]`）取中心点坐标再注入点击
- 键盘没收回时 dump 里会混入输入法节点，先 `keyEvent Back`
---
## 7. 待办任务（优先级序）
| # | 任务 | 前置 | 说明 |
| --- | --- | --- | --- |
| 1 | **FE 华为账号登录接入** | §2 三步完成 | `@kit.AccountKit` 的 AuthorizationButton / createAuthorizationCredential 拿 id_token → `POST /api/v1/auth/huawei`，请求体 `{"id_token": "<JWT>"}`，返回与 dev-token 相同的双令牌结构。后端已就绪（OIDC 验签 + UnionID 映射 `id_user_identity`，`packages/identity/huawei.py` + `apps/api/routers/auth.py:124`） |
| 2 | FE 邮箱验证码登录 UI | 后端 E1（邮箱登录，原机做） | 输入邮箱→发码→验码；接口形态参照原 `/auth/sms/send|verify`（键名以 E1 实现为准） |
| 3 | 真实照片上传 | 后端 E2（本地存储驱动） | 报告页"照片（模拟）"改真实上传；接口以 E2 实现为准 |
| 4 | 已知体验债 | 无 | 轮询完成自动跳转在部分场景仍依赖兜底按钮（@Builder 传函数真机失效的深层原因未根治）；AppStorage 重启丢 lastReportId 时 40920 对话框无"查看报告"入口 |
---
## 8. 新机器开工验收基线（先复现，再开发）
1. clone 后 CLI 构建 `BUILD SUCCESSFUL`
2. 自动签名配置成功，装机跑起 App
3. 原机后端 8666 可达（方案 A）→ 登录页输地址 + dev-token 登录成功
4. 走通一次报告流（新用户周期内可完整生成；已生成过则 40920 对话框属正常）