meida/docs/开发任务包/README-FE批次.md

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）。