laoyang/FamilyBook
1
0
Fork 0
Code Issues 29 Pull Requests Actions Packages Projects Releases Wiki Activity

鸿蒙端同步地址联想：地点输入下拉需带详细地址（端上原本无联想，需新建能力） #33

New Issue
Open
opened 2026-10-30 00:03:39 +00:00 by laoyang · 3 comments
laoyang commented 2026-10-30 00:03:39 +00:00
Owner
Copy Link
Copy Source

背景

网页端已实现「地址联想下拉带详细地址」（#32）。用户 2026-10-30 要求鸿蒙端同步。

现状（与网页端不同）

网页端 鸿蒙端（改前）
地址联想 有（AMap.AutoComplete，JS API） 完全没有，纯文本输入框
下拉带地址 已实现（#32） —
服务端联想接口 无（联想在浏览器端做） 无

所以"同步"实际是从无到有：端上要新建联想能力，服务端也要新建代理接口。

用户原话

在所有调用高德显示详细地址的地方，也就是当我输入一个简单地址、下拉显示详细地址时，
不能只把地点告诉我，一定要把详细地址也放在后面。
因为如果只是把地址给我，同一个地址可能有好几个，我根本不知道应该选哪一个。

已实现

服务端（commit 29b2ca0）

  • Geo::tips($kw, $limit)：调高德 /v3/assistant/inputtips，
    把三套不齐的字段归一成 name / detail(省市区+门牌) / district / address / lng / lat
  • GET /api/v1/geo/tips?kw=&limit=：GET only、要求登录（花配额的接口）
  • 过滤公交地铁线路（typecode 15xx）
  • 只看 body 里 status 而不是 HTTP 码（配额用完高德回 200 + status=0）
  • 少于 2 字不查，返回空数组而非报错

鸿蒙端（commit f4f27ce）

  • FbGeoRepo.ets：调上述接口
  • FbAddrInput.ets：候选每行两行字 —— 地名 14px 深色 + 详细地址 12px 灰，
    同名地点靠第二行区分；防抖 260ms；seq 丢过期响应
  • 接入两处：日程编辑的地点、行程节点的地点

为什么走服务端代理：高德 Web 服务 key 是服务端密钥，打进安装包等于公开
（反编译/抓包即得，配额被跑光、key 可能被封）。网页端那套 JS API key + 安全密钥
是域名白名单机制，原生端没有等价物。

为什么是 @ComponentV2 而非 @Builder：@Builder 值类型参数不参与状态观察
（SDK r/quick-rules/05-state.md），候选列表/展开态会"数据变了界面不重建"。
本项目在 FbEventChip / FbTagChip / FbCalOptionRow 上各踩过一次。

🔴 当前阻塞：缺 Web 服务类型的高德 key

现有配置里的 key（40d7ae…）是 JavaScript API 类型，调任何 Web 服务接口都返回：

{"info":"USERKEY_PLAT_NOMATCH","infocode":"10009","status":"0"}

实测 v3/place/text、v5/place/text、v3/assistant/inputtips、v3/geocode/regeo
全部同样失败。而 JS API 那条路（webapi.amap.com/maps?key=…）是 200 正常的
—— 所以网页端联想能用，但服务端调不了。

顺带发现（既存问题，与本单无关）：Geo::regeo() 一直因此失效，
Geo::cityFromPoint() 实际在走第②③级离线兜底。这不影响现有功能，但属于隐藏缺陷，
建议单开一张工单处理。

需要：去高德控制台同一个应用下「添加 Key」，服务平台选 Web服务（不是 Web端JS API），
把新 key 填进 config.php 的 amap.key。之后本单即可工作，无需改代码。

验证情况

项 状态
编译 ✅ BUILD SUCCESSFUL，33 tasks（17 executed 非缓存）
验签 ✅ verify-app success
服务端解析逻辑 ✅ 19 项全通过（4 组模拟高德真实响应 + 源码一致性检查）
降级行为 ✅ key 无效时返回空数组、不 500 ⇒ 端上退化为普通文本框，手敲可保存
真机 UI ⏸ 手机已断开（hdc list targets = [Empty]），待重连后验证

验收标准

  1. 拿到 Web 服务 key 后，日程/行程的地点输入框输入 ≥2 字，下拉每行都带详细地址
  2. 同名地点可凭地址区分
  3. 选中后地名写入输入框、能正常保存
  4. 断网/接口失败时输入框仍可手敲保存

为什么单独建单

这是鸿蒙端从无到有新建地址联想能力（新增 FbGeoRepo/FbAddrInput + 服务端 geo/tips 接口），涉及 ArkTS 代码与 PHP 新接口；#32 只改网页端一个 JS 文件的渲染方式，#31 是日程编辑权限，改的文件和验收方式完全不同。

## 背景 网页端已实现「地址联想下拉带详细地址」（#32）。用户 2026-10-30 要求**鸿蒙端同步**。 ## 现状（与网页端不同） | | 网页端 | 鸿蒙端（改前） | |---|---|---| | 地址联想 | 有（`AMap.AutoComplete`，JS API） | **完全没有**，纯文本输入框 | | 下拉带地址 | 已实现（#32） | — | | 服务端联想接口 | 无（联想在浏览器端做） | 无 | 所以"同步"实际是**从无到有**：端上要新建联想能力，服务端也要新建代理接口。 ## 用户原话 > 在所有调用高德显示详细地址的地方，也就是当我输入一个简单地址、下拉显示详细地址时， > 不能只把地点告诉我，一定要把详细地址也放在后面。 > 因为如果只是把地址给我，同一个地址可能有好几个，我根本不知道应该选哪一个。 ## 已实现 ### 服务端（commit `29b2ca0`） - `Geo::tips($kw, $limit)`：调高德 `/v3/assistant/inputtips`， 把三套不齐的字段归一成 `name / detail(省市区+门牌) / district / address / lng / lat` - `GET /api/v1/geo/tips?kw=&limit=`：GET only、要求登录（花配额的接口） - 过滤公交地铁线路（`typecode` 15xx） - 只看 body 里 `status` 而不是 HTTP 码（配额用完高德回 200 + status=0） - 少于 2 字不查，返回空数组而非报错 ### 鸿蒙端（commit `f4f27ce`） - `FbGeoRepo.ets`：调上述接口 - `FbAddrInput.ets`：候选每行两行字 —— 地名 14px 深色 + 详细地址 12px 灰， 同名地点靠第二行区分；防抖 260ms；`seq` 丢过期响应 - 接入两处：日程编辑的地点、行程节点的地点 **为什么走服务端代理**：高德 Web 服务 key 是服务端密钥，打进安装包等于公开 （反编译/抓包即得，配额被跑光、key 可能被封）。网页端那套 JS API key + 安全密钥 是域名白名单机制，原生端没有等价物。 **为什么是 `@ComponentV2` 而非 `@Builder`**：`@Builder` 值类型参数不参与状态观察 （SDK `r/quick-rules/05-state.md`），候选列表/展开态会"数据变了界面不重建"。 本项目在 `FbEventChip` / `FbTagChip` / `FbCalOptionRow` 上各踩过一次。 ## 🔴 当前阻塞：缺 Web 服务类型的高德 key 现有配置里的 key（`40d7ae…`）是 **JavaScript API 类型**，调任何 Web 服务接口都返回： ```json {"info":"USERKEY_PLAT_NOMATCH","infocode":"10009","status":"0"} ``` 实测 `v3/place/text`、`v5/place/text`、`v3/assistant/inputtips`、`v3/geocode/regeo` **全部同样失败**。而 JS API 那条路（`webapi.amap.com/maps?key=…`）是 200 正常的 —— 所以网页端联想能用，但服务端调不了。 **顺带发现（既存问题，与本单无关）**：`Geo::regeo()` 一直因此失效， `Geo::cityFromPoint()` 实际在走第②③级离线兜底。这不影响现有功能，但属于隐藏缺陷， 建议单开一张工单处理。 **需要**：去高德控制台同一个应用下「添加 Key」，服务平台选 **Web服务**（不是 Web端JS API）， 把新 key 填进 `config.php` 的 `amap.key`。之后本单即可工作，无需改代码。 ## 验证情况 | 项 | 状态 | |---|---| | 编译 | ✅ `BUILD SUCCESSFUL`，33 tasks（17 executed 非缓存） | | 验签 | ✅ `verify-app success` | | 服务端解析逻辑 | ✅ 19 项全通过（4 组模拟高德真实响应 + 源码一致性检查） | | 降级行为 | ✅ key 无效时返回空数组、不 500 ⇒ 端上退化为普通文本框，手敲可保存 | | 真机 UI | ⏸ 手机已断开（`hdc list targets` = `[Empty]`），待重连后验证 | ## 验收标准 1. 拿到 Web 服务 key 后，日程/行程的地点输入框输入 ≥2 字，下拉每行都带详细地址 2. 同名地点可凭地址区分 3. 选中后地名写入输入框、能正常保存 4. 断网/接口失败时输入框仍可手敲保存 --- ### 为什么单独建单 这是鸿蒙端从无到有新建地址联想能力（新增 FbGeoRepo/FbAddrInput + 服务端 geo/tips 接口），涉及 ArkTS 代码与 PHP 新接口；#32 只改网页端一个 JS 文件的渲染方式，#31 是日程编辑权限，改的文件和验收方式完全不同。
laoyang commented 2026-10-30 00:03:56 +00:00
Author
Owner
Copy Link
Copy Source

⚠️ 更正：commit 里写的工单号是 #36，实际应为 #33

我在提交时凭记忆写了 laoyang/FamilyBook#36，但本单实际建出来是 #33。
两个 commit 的 message 里都是错的编号：

仓库 commit message 里的错误引用
FamilyBook 29b2ca0 laoyang/FamilyBook#36
FamilyBook_harmonyos f4f27ce laoyang/FamilyBook#36

这两笔提交是干本单的，不是 #36（该号不存在）。 留此说明以便日后追查能对上。

按项目规则 commit 一旦推送就不改写历史（避免 force push 破坏他处引用），
所以用评论补正，而不是 amend + 强推。

顺带：本次工作的一个过程教训

写代码时我把改动落在了 Windows 侧的仓库副本，而编译在 WSL 里跑 ——
于是第一次 BUILD SUCCESSFUL 是假的（编译的是旧代码：

=== 改动清单 ===          ← git status 为空！
> hvigor BUILD SUCCESSFUL in 1 s 552 ms
33 tasks in total: 14 executed, 19 up-to-date

git status 空 + 1.5 秒 + 19 个 up-to-date，三个信号同时出现才是破绽。
真把改动同步到 WSL 后，立刻暴出 5 个真实错误：

  1. arkts-no-untyped-obj-literals（FbGeoRepo.ets:50,52）——
    ArkTS 不接受无类型对象字面量，const opts = {...} 必须显式标 FbApiOptions
  2. Module 'Types' has no exported member 'isEventWritable' ×2 ——
    更严重：我从 Windows 侧覆盖了 WSL 的 Types.ets，而 Windows 那份是旧版
    （#31 的改动只在 WSL 提交并推送过），把 isEventWritable 冲掉了。
    用 git checkout HEAD -- <file> 恢复后重新插入 FbGeoTip 才修好。

⇒ 教训：改动必须直接写在 WSL，不要"先改 Windows 再同步"；
跨环境复制单文件会静默覆盖掉另一侧独有的改动。

## ⚠️ 更正：commit 里写的工单号是 #36，实际应为 #33 我在提交时凭记忆写了 `laoyang/FamilyBook#36`，但本单实际建出来是 **#33**。 两个 commit 的 message 里都是错的编号： | 仓库 | commit | message 里的错误引用 | |---|---|---| | `FamilyBook` | `29b2ca0` | `laoyang/FamilyBook#36` | | `FamilyBook_harmonyos` | `f4f27ce` | `laoyang/FamilyBook#36` | **这两笔提交是干本单的，不是 #36（该号不存在）。** 留此说明以便日后追查能对上。 按项目规则 commit 一旦推送就不改写历史（避免 force push 破坏他处引用）， 所以用评论补正，而不是 amend + 强推。 ## 顺带：本次工作的一个过程教训 写代码时我把改动落在了 **Windows 侧的仓库副本**，而编译在 **WSL** 里跑 —— 于是第一次 `BUILD SUCCESSFUL` 是**假的**（编译的是旧代码： ``` === 改动清单 === ← git status 为空！ > hvigor BUILD SUCCESSFUL in 1 s 552 ms 33 tasks in total: 14 executed, 19 up-to-date ``` `git status` 空 + 1.5 秒 + 19 个 up-to-date，三个信号同时出现才是破绽。 真把改动同步到 WSL 后，立刻暴出 **5 个真实错误**： 1. `arkts-no-untyped-obj-literals`（`FbGeoRepo.ets:50,52`）—— ArkTS 不接受无类型对象字面量，`const opts = {...}` 必须显式标 `FbApiOptions` 2. `Module 'Types' has no exported member 'isEventWritable'` ×2 —— 更严重：我从 Windows 侧覆盖了 WSL 的 `Types.ets`，而 Windows 那份是旧版 （#31 的改动只在 WSL 提交并推送过），把 `isEventWritable` 冲掉了。 用 `git checkout HEAD -- <file>` 恢复后重新插入 `FbGeoTip` 才修好。 ⇒ 教训：**改动必须直接写在 WSL**，不要"先改 Windows 再同步"； 跨环境复制单文件会静默覆盖掉另一侧独有的改动。
laoyang commented 2026-10-30 00:12:47 +00:00
Author
Owner
Copy Link
Copy Source

已按指示改用鸿蒙自带 Map Kit（不再走高德）

用户指示：「端侧不用高德，用鸿蒙自带的接口。」

commit：

  • 鸿蒙端 7bc26dd
  • 服务端 73c84c1（移除已无用的高德代理接口）

改成了什么

用 @kit.MapKit 的 site.queryAutoComplete()（花瓣地图地点自动补全）。

const params: site.QueryAutoCompleteParams = { query: q };
const res: site.QueryAutoCompleteResult = await site.queryAutoComplete(params);
// res.sites: Array<Site>
//   Site.name          地点名
//   Site.formatAddress 详细地址 ← SDK 注释原文 "Formatted detailed address of a place"
//   Site.location      经纬度

formatAddress 正好是用户要的那个「作为参考的详细地址」。缺失时（纯行政区划条目）
用 locality + streetName + streetNumber 兜底，再不行留空（端上整行不画，不留空灰线）。

这个改动顺带解决了原方案两个问题

  1. 高德 Web 服务 key 是服务端密钥，本不该出现在客户端；
  2. 线上那个 key 实际是 JS API 类型，调 Web 服务接口一直返回
    USERKEY_PLAT_NOMATCH (10009) —— 也就是说原方案在功能上根本跑不起来。

现在端上不需要任何外部 key，也不需要我们自己的服务端接口与配额。

服务端清理

/api/v1/geo/tips 与 Geo::tips() / TIPS_URL 一并删除（共 -192 行）。
删前确认过：网页端 addr_suggest.js 零引用（它走浏览器端 JS API），
只在端上那版代码里用过。

验证：/api/v1/geo/tips 现返回 404；/api/v1/calendar/books 仍 401（鉴权正常）。

编译验证

> hvigor BUILD SUCCESSFUL in 9 s 109 ms
33 tasks in total: 17 executed, 16 up-to-date

验签：verify-app success。

⚠️ 中途踩到一个真错并修正：StreetNumber 的字段是 streetName / streetNumber，
我第一版凭印象写成 street / number，编译直接报
Property 'street' does not exist on type 'StreetNumber'。
教训：字段名一律以 @hms.core.map.site.d.ts 声明文件为准，不靠记忆。

🔴 一个待真机确认的前提：MapKit 需要 AGC 开通

声明文件里 queryAutoComplete 明确会抛这两个错误码：

1002600003  App authentication failed
1002600004  The Map permission is not enabled

这说明 MapKit 不是纯本地能力，需要：

  1. AGC 里有对应应用（当前 profile 是 issuer: app_gallery / app-feature: hos_normal_app，
    属 AGC 签发的标准调试证书，应用应该已在 AGC 里）；
  2. 在 AGC 控制台为这个应用开通 Map Kit 服务。

第 2 点我这边无法确认也无法操作（要登录 AGC 控制台）。

我已经把这两种情况都做了降级处理：认证失败/未开通 ⇒ 返回空候选 ⇒
输入框退化为普通文本框，手敲照常保存，不会崩、不会卡。但要真正看到下拉候选，
需要 Map Kit 服务已开通。

验证状态

项 状态
编译 ✅ 33 tasks（17 executed，非缓存）
验签 ✅ verify-app success
服务端接口移除 ✅ 404，其它接口不受影响
真机 UI ⏸ 手机已断开（hdc list targets = [Empty]）
MapKit 认证 ⏸ 需真机 + AGC 开通才能确认

下一步

  1. 手机重新连上后我装包验证：先看会不会报 1002600003/1002600004；
  2. 若报 1002600004 ⇒ 需要你在 AGC 控制台给这个应用开通 Map Kit；
  3. 开通后下拉应显示「地名 + 详细地址」两行。
## 已按指示改用鸿蒙自带 Map Kit（不再走高德） 用户指示：「端侧不用高德，用鸿蒙自带的接口。」 commit： - 鸿蒙端 `7bc26dd` - 服务端 `73c84c1`（移除已无用的高德代理接口） ### 改成了什么 用 `@kit.MapKit` 的 **`site.queryAutoComplete()`**（花瓣地图地点自动补全）。 ```ts const params: site.QueryAutoCompleteParams = { query: q }; const res: site.QueryAutoCompleteResult = await site.queryAutoComplete(params); // res.sites: Array<Site> // Site.name 地点名 // Site.formatAddress 详细地址 ← SDK 注释原文 "Formatted detailed address of a place" // Site.location 经纬度 ``` `formatAddress` 正好是用户要的那个「作为参考的详细地址」。缺失时（纯行政区划条目） 用 `locality + streetName + streetNumber` 兜底，再不行留空（端上整行不画，不留空灰线）。 ### 这个改动顺带解决了原方案两个问题 1. 高德 Web 服务 key 是服务端密钥，本不该出现在客户端； 2. 线上那个 key 实际是 **JS API 类型**，调 Web 服务接口一直返回 `USERKEY_PLAT_NOMATCH (10009)` —— 也就是说原方案在功能上根本跑不起来。 现在端上**不需要任何外部 key**，也不需要我们自己的服务端接口与配额。 ### 服务端清理 `/api/v1/geo/tips` 与 `Geo::tips()` / `TIPS_URL` 一并删除（共 -192 行）。 删前确认过：网页端 `addr_suggest.js` 零引用（它走浏览器端 JS API）， 只在端上那版代码里用过。 验证：`/api/v1/geo/tips` 现返回 **404**；`/api/v1/calendar/books` 仍 401（鉴权正常）。 ### 编译验证 ``` > hvigor BUILD SUCCESSFUL in 9 s 109 ms 33 tasks in total: 17 executed, 16 up-to-date ``` 验签：`verify-app success`。 ⚠️ 中途踩到一个真错并修正：`StreetNumber` 的字段是 **`streetName` / `streetNumber`**， 我第一版凭印象写成 `street` / `number`，编译直接报 `Property 'street' does not exist on type 'StreetNumber'`。 教训：字段名一律以 `@hms.core.map.site.d.ts` 声明文件为准，不靠记忆。 ### 🔴 一个待真机确认的前提：MapKit 需要 AGC 开通 声明文件里 `queryAutoComplete` 明确会抛这两个错误码： ``` 1002600003 App authentication failed 1002600004 The Map permission is not enabled ``` 这说明 MapKit **不是纯本地能力**，需要： 1. AGC 里有对应应用（当前 profile 是 `issuer: app_gallery` / `app-feature: hos_normal_app`， 属 AGC 签发的标准调试证书，应用应该已在 AGC 里）； 2. **在 AGC 控制台为这个应用开通 Map Kit 服务**。 第 2 点我这边无法确认也无法操作（要登录 AGC 控制台）。 **我已经把这两种情况都做了降级处理**：认证失败/未开通 ⇒ 返回空候选 ⇒ 输入框退化为普通文本框，手敲照常保存，不会崩、不会卡。但要真正看到下拉候选， 需要 Map Kit 服务已开通。 ### 验证状态 | 项 | 状态 | |---|---| | 编译 | ✅ 33 tasks（17 executed，非缓存） | | 验签 | ✅ `verify-app success` | | 服务端接口移除 | ✅ 404，其它接口不受影响 | | 真机 UI | ⏸ **手机已断开**（`hdc list targets` = `[Empty]`） | | MapKit 认证 | ⏸ 需真机 + AGC 开通才能确认 | ### 下一步 1. 手机重新连上后我装包验证：先看会不会报 `1002600003/1002600004`； 2. 若报 1002600004 ⇒ 需要你在 AGC 控制台给这个应用开通 Map Kit； 3. 开通后下拉应显示「地名 + 详细地址」两行。
laoyang commented 2026-11-01 01:40:08 +00:00
Author
Owner
Copy Link
Copy Source

🔴 需要你在 AGC 做两步（2026-11-01 排查更新）

用户 2026-11-01：「33 这个工单不好使，输入信息时没有弹出任何联想。
当时我记得你说这个跟鸿蒙系统有关系，需要我申请什么东西才行，是吧？怎么操作？」

对，要申请。而且光开通服务还不够 —— 我这次查到还漏了一步代码配置，已经补上了。

一、我这边已改好的（不用你动）

entry/src/main/module.json5 原来没有 Map Kit 需要的 metadata。官方文档要求：

"module": {
  "metadata": [
    { "name": "client_id", "value": "<AGC 应用的 Client ID>" }
  ]
}

只在 AGC 打开地图服务开关、不配这里，照样报
1002600004 The Map permission is not enabled ——
官方错误码表里"可能原因"第 2 条就是「client_id 未配置」。

commit 9616881 已经把这个结构加好了，value 现在是占位
REPLACE_WITH_AGC_CLIENT_ID，等你的 Client ID 填进去。
已验证产物里确实带上了这段 metadata。

二、需要你做的两件事

① 在 AGC 开通「地图服务」

  1. 打开 https://developer.huawei.com/consumer/cn/service/josp/agc/index.html 并登录
  2. 顶部「我的项目」→ 选中家书所在的那个项目
  3. 左侧菜单「API 管理」（有的界面叫「API 服务」）
  4. 找到 地图服务 / Map Kit，把开关打开

② 把「应用」的 Client ID 给我

  1. 同一个项目里 → 左侧「项目设置」→「常规」
  2. 页面往下找「应用」区域，那一栏里有 Client ID
  3. ⚠️ 要「应用」的 Client ID，不是「项目」的 Client ID —— 官方专门提醒过这两个容易看错
  4. 把那串值发我（形如一串数字，或 数字-数字）

拿到之后我替换掉占位值、重新编译装机验证。

三、顺便确认一下：签名已经是手动签名的调试证书 ✅

Map Kit 不支持自动签名。我查了当前工程的 build-profile.json5：

certpath : /home/yongquan/code/cert/familybook/familybook.yangyq.net.debug.cer
profile  : .../familybook.yangyq.net.debug.p7b
signAlg  : SHA256withECDSA

是手动配置的调试证书，这一条已经满足，不用改。

四、还有一项要你确认：证书指纹

AGC →「项目设置」→「常规」→「应用」区域 → 找
SHA256 证书/公钥指纹 → 点「添加公钥指纹（HarmonyOS API 9 及以上）」，
选当前用的这张调试证书的指纹，确认。

⚠️ 如果那里已经有这张证书的指纹，就不用再加（我们之前装包成功过，
说明证书本身在 AGC 是登记的；但指纹这一项需要你顺眼看一眼）。

五、配置生效的坑（官方明确写了）

配置完成后由于鉴权缓存，可能还是无法马上显示，须清除缓存或者将设备的
系统时间往后调 1 天，才能立刻生效。

所以填好 Client ID 装包后如果仍没候选，别急着怀疑代码 ——
先把手机系统时间往后调一天再试（或者在应用管理里清掉家书的缓存）。

六、如果上面都做了还是没有

那就要看真机日志里的具体错误码了。请把手机连上电脑，我来抓：

错误码 含义 下一步
1002600003 应用认证失败 AGC 的 Client ID 与证书不匹配，重新核对
1002600004 没开通地图服务权限 上面 ①② 没做完，或 client_id 还没填
1002600006/07 超配额 / 超 QPS 免费额度用尽，需在线提单
1002603001 查不到结果 正常，换个更常见的词再试（如"星巴克"）

代码侧已经把这几类全部降级处理：任何失败都返回空候选，输入框退化成普通文本框，
手敲照常保存 —— 不会崩、不会卡。

当前的验证状态

项 状态
代码改用 Map Kit（不再走高德 / 不走服务端代理） ✅ 已提交（7bc26dd）
module.json5 的 client_id metadata ✅ 已加占位（9616881），等你给值
编译 ✅ BUILD SUCCESSFUL，33 tasks（27 executed）
签名方式（需手动签名） ✅ 已是手动调试证书
AGC 开通地图服务 ⏸ 等你在 AGC 操作
AGC 应用 Client ID ⏸ 等你提供
真机 UI ⏸ 手机未连接（hdc list targets = [Empty]）

你完成 ①② 并把 Client ID 告我，我立刻接上并做真机验证。

## 🔴 需要你在 AGC 做两步（2026-11-01 排查更新） 用户 2026-11-01：「33 这个工单不好使，输入信息时没有弹出任何联想。 当时我记得你说这个跟鸿蒙系统有关系，需要我申请什么东西才行，是吧？怎么操作？」 对，要申请。而且**光开通服务还不够** —— 我这次查到还**漏了一步代码配置**，已经补上了。 ### 一、我这边已改好的（不用你动） `entry/src/main/module.json5` 原来**没有** Map Kit 需要的 metadata。官方文档要求： ```json5 "module": { "metadata": [ { "name": "client_id", "value": "<AGC 应用的 Client ID>" } ] } ``` 只在 AGC 打开地图服务开关、不配这里，照样报 `1002600004 The Map permission is not enabled` —— 官方错误码表里"可能原因"第 2 条就是「client_id 未配置」。 commit `9616881` 已经把这个结构加好了，`value` 现在是占位 `REPLACE_WITH_AGC_CLIENT_ID`，等你的 Client ID 填进去。 已验证产物里确实带上了这段 metadata。 ### 二、需要你做的两件事 #### ① 在 AGC 开通「地图服务」 1. 打开 https://developer.huawei.com/consumer/cn/service/josp/agc/index.html 并登录 2. 顶部「我的项目」→ 选中家书所在的那个**项目** 3. 左侧菜单「API 管理」（有的界面叫「API 服务」） 4. 找到 **地图服务 / Map Kit**，把开关**打开** #### ② 把「应用」的 Client ID 给我 1. 同一个项目里 → 左侧「项目设置」→「常规」 2. 页面往下找「应用」区域，那一栏里有 **Client ID** 3. ⚠️ **要「应用」的 Client ID，不是「项目」的 Client ID** —— 官方专门提醒过这两个容易看错 4. 把那串值发我（形如一串数字，或 `数字-数字`） 拿到之后我替换掉占位值、重新编译装机验证。 ### 三、顺便确认一下：签名已经是手动签名的调试证书 ✅ Map Kit **不支持自动签名**。我查了当前工程的 `build-profile.json5`： ``` certpath : /home/yongquan/code/cert/familybook/familybook.yangyq.net.debug.cer profile : .../familybook.yangyq.net.debug.p7b signAlg : SHA256withECDSA ``` 是手动配置的调试证书，这一条已经满足，不用改。 ### 四、还有一项要你确认：证书指纹 AGC →「项目设置」→「常规」→「应用」区域 → 找 **SHA256 证书/公钥指纹** → 点「添加公钥指纹（HarmonyOS API 9 及以上）」， 选当前用的这张调试证书的指纹，确认。 ⚠️ 如果那里**已经有**这张证书的指纹，就不用再加（我们之前装包成功过， 说明证书本身在 AGC 是登记的；但指纹这一项需要你顺眼看一眼）。 ### 五、配置生效的坑（官方明确写了） > 配置完成后由于鉴权缓存，可能还是无法马上显示，须**清除缓存**或者将设备的 > **系统时间往后调 1 天**，才能立刻生效。 所以填好 Client ID 装包后如果仍没候选，别急着怀疑代码 —— 先把手机系统时间往后调一天再试（或者在应用管理里清掉家书的缓存）。 ### 六、如果上面都做了还是没有 那就要看真机日志里的**具体错误码**了。请把手机连上电脑，我来抓： | 错误码 | 含义 | 下一步 | |---|---|---| | `1002600003` | 应用认证失败 | AGC 的 Client ID 与证书不匹配，重新核对 | | `1002600004` | 没开通地图服务权限 | 上面 ①② 没做完，或 client_id 还没填 | | `1002600006/07` | 超配额 / 超 QPS | 免费额度用尽，需在线提单 | | `1002603001` | 查不到结果 | **正常**，换个更常见的词再试（如"星巴克"） | 代码侧已经把这几类全部降级处理：任何失败都返回空候选，输入框退化成普通文本框， 手敲照常保存 —— 不会崩、不会卡。 ### 当前的验证状态 | 项 | 状态 | |---|---| | 代码改用 Map Kit（不再走高德 / 不走服务端代理） | ✅ 已提交（`7bc26dd`） | | `module.json5` 的 client_id metadata | ✅ 已加占位（`9616881`），等你给值 | | 编译 | ✅ BUILD SUCCESSFUL，33 tasks（27 executed） | | 签名方式（需手动签名） | ✅ 已是手动调试证书 | | AGC 开通地图服务 | ⏸ **等你在 AGC 操作** | | AGC 应用 Client ID | ⏸ **等你提供** | | 真机 UI | ⏸ 手机未连接（`hdc list targets` = `[Empty]`） | 你完成 ①② 并把 Client ID 告我，我立刻接上并做真机验证。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
terminal/harmony
term-hm
 terminal/web
term-web
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
laoyang (老杨)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: laoyang/FamilyBook#33