# FE 批次·多 Agent 协作规程（第五批 F1~F4）

> 版本：v1.3 ｜ 2026-08-15 ｜ 适用：**鸿蒙 FE 批次（F1~F4）**——仓库是 Windows 侧 `G:\meida`（本仓库），工程在 `app/`。后端仓库的规程（v1.2）仍适用其后端任务，不适用本批。
> **每个 agent 开工前必须先读本文件，再读自己的任务文档。**

## 1. 环境操作手册（纯 Windows，无 WSL）

| 任务 | worktree | 分支 |
| --- | --- | --- |
| F1 | `G:\meida-app-f1` | `task/f1-fe` |
| F2 | `G:\meida-app-f2` | `task/f2-fe` |
| F3 | `G:\meida-app-f3` | `task/f3-fe` |
| F4 | `G:\meida-app-f4` | `task/f4-fe` |

- 读写文件：Read/Write/Edit 工具直接用 Windows 路径（如 `G:\meida-app-f1\app\entry\src\main\ets\pages\...`）
- **构建门禁（唯一验收命令）**：
  ```
  cd G:/meida-app-f1/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
  ```
  （把 f1 换成你的编号；`BUILD SUCCESSFUL` = 通过。未签名 WARN 正常忽略。）

## 2. 冲突隔离铁律

1. **只改自己任务文档允许的文件**。`app/entry/src/main/ets/core/**`、`module.json5`、`main_pages.json`、`app/README.md`、`oh-package*.json5`、`hvigor*` 全部禁改（core 已就绪，路由已全注册）。
2. **页面间跳转一律 `router.pushUrl({ url: 'pages/XxxPage' })`**，**禁止 import 其它页面文件**——七个页面都已注册，按路径跳不需要 import，这是本批零冲突的根本。
3. 组件复用：在自己页面文件内声明 `@Component`；确实通用的放 `ets/components/<你的任务名>/`（如 `components/f2/`），**目录名带任务前缀**。
4. 不引任何第三方 ohpm 包；不动 resources（字符串/颜色硬编码，i18n 后置）。
5. 提交：构建绿后**单次提交**（信息格式见任务文档），禁止 push、禁止切分支。

## 3. ArkTS 严格模式铁律（协调者实测踩坑，违反必炸编译）

1. **泛型调用必须显式类型参数**：`ApiClient.post<void>(...)`、`ApiClient.get<MyResp>(...)`——裸 `post(...)` 直接报 `arkts-no-inferred-generic-params`
2. **请求体用具型 Record 字面量**：`const req: Record<string, Object> = { 'k': v }`——不允许 interface→Record 强转（无索引签名）、不允许内联对象类型 `{a:string}(...)` 做泛型参数
3. **wire 响应类型用具名 interface**（文件内声明，字段名对齐后端 JSON），`resp.result as ApiEnvelope<T>` 之后再 `data` 层转具体类型
4. **throw 只抛 ApiError**：catch 里 `if (e instanceof ApiError) throw e`，未知异常包 `new ApiError(50000, '请求失败，请检查网络', '请稍后重试')`
5. **对象字面量必须有具名声明的对应类型**（Record/接口/class 皆可，裸字面量赋 var 会报错）；async 逻辑放**具名方法**而不是复杂箭头链（泛型推断限制）
6. UI 惯例：`@Entry @Component struct XxxPage`、`@State` 状态、`aboutToAppear` 里 async 初始化（用 `.then` 或 fire-and-forget + `@State` 驱动刷新）、异常只 catch `ApiError` 展示 `e.message + e.hint`

## 4. 后端 API 速查（baseUrl 默认 `http://127.0.0.1:8000`，信封 `{code,message,data,hint}`）

- 登录：`POST /api/v1/auth/dev-token` `{device_key}` → `{access_token,refresh_token,expires_in,refresh_expires_in,user_id}`（AuthStore 已封装）
- 配额：`GET /api/v1/quota?quota_key=agent_chat|tryon|...` → `{quota_key,used,limit_value,bonus_granted,remaining,reset_at}`
- 流水：`GET /api/v1/quota/ledger?limit=20` → `[{tx_id,delta,tx_type,status,quota_key,balance_after,created_at}]`
- 对话：`POST /api/v1/agent/chat` `{message}` → `{reply,provider,model,prompt_id,prompt_version,call_id,usage{tokens_in,tokens_out,tokens_cached,latency_ms,cost_cents},quota_remaining}`
- 任务：`GET /api/v1/tasks/{id}` → `{task_id,status,progress,stage_text,...}`（status: PENDING/RUNNING/SUCCEEDED/FAILED）
- 报告：`POST /api/v1/reports` `{questionnaire:{...},photo_object_key,request_key?}` → `{report_id,task_id,status,version}`；`GET /api/v1/reports/{id}` → `{report_id,status,version,result{vision,diagnosis,copy,validation},created_at,completed_at}`；`POST /api/v1/reports/{id}/regenerate` `{request_key?}`
- diagnosis 结构：`{dimensions:[{number,key,name_cn,value,confidence,source,evidence,rule_hits,status}]（恒 32 项）, coverage:{basic_full,total}}`；copy：`{summary,sections:[{title,paragraphs[]}],model,...}`；validation：`{passed,degraded?,checks{pejorative,absolute,consistency}}`
- 常见错误码：40100 未登录 / 40301 额度用尽（文案已无价格字样）/ 40920 本期报告已生成 / 60003 AI 服务今日上限 / 50003 配置异常

## 5. 运行验证说明（agent 不做）

构建绿即可提交；真机/模拟器运行由用户在 DevEco Studio 里做（连本机后端：模拟器 127.0.0.1 直连，真机改登录页 baseUrl 为开发机局域网 IP）。