From 388d6058696c05cfd5892018f52120880a440524 Mon Sep 17 00:00:00 2001 From: YANG JIANKUAN Date: Sun, 11 Oct 2026 23:10:45 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E5=8F=8C=E7=AB=AF?= =?UTF-8?q?=E5=90=88=E5=85=A5=E4=B8=BB=E5=B9=B2=E4=BA=A4=E6=8E=A5=E6=96=87?= =?UTF-8?q?=E6=A1=A3=EF=BC=8C=E4=BF=AE=E6=AD=A3=20CLAUDE.md=20=E8=BF=87?= =?UTF-8?q?=E6=9C=9F=E4=BF=A1=E6=81=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - documents/双端合入主干交接文档.md：分支状态、平板/手机开发状态、合并内容、 开发规则、验证覆盖、待决事项与注意事项 - CLAUDE.md：版本 1.8.7 (87)；JDK 17 运行 / Java 1.8 编译目标；模拟器路径与 AVD 名（AeroLogic_Phone sw=394dp / AeroLogic_Tablet）；运抵长按浮层与已删除的 补充信息页；分支约定处链接交接文档 Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 25 ++-- documents/双端合入主干交接文档.md | 219 ++++++++++++++++++++++++++++++ 2 files changed, 232 insertions(+), 12 deletions(-) create mode 100644 documents/双端合入主干交接文档.md diff --git a/CLAUDE.md b/CLAUDE.md index c687f81..a537639 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,8 +5,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 项目概况 **项目名称**: AirLogistics - 航空物流信息管理系统 -**架构模式**: MVVM + 组件化 | **语言**: Kotlin 1.6.21 + Java | **版本**: 1.8.4 (versionCode 84) -**SDK**: minSdk 24 / targetSdk 30 / compileSdk 31 | **Gradle**: 7.3.3 | **JDK**: 1.8 +**架构模式**: MVVM + 组件化 | **语言**: Kotlin 1.6.21 + Java | **版本**: 1.8.7 (versionCode 87) +**SDK**: minSdk 24 / targetSdk 30 / compileSdk 31 | **Gradle**: 7.3.3 | **JDK**: 17（`mise.toml`，运行 Gradle 用）；编译目标 Java 1.8（`sourceCompatibility` / `jvmTarget`） ### 核心架构 @@ -850,7 +850,7 @@ adb logcat | grep "com.lukouguoji.aerologic" # 日志 项目需同时支持 **10 寸平板横屏** 与 **5.5 寸手机竖屏**。核心原则：**业务逻辑层完全复用，只重写布局**。 -> **分支约定（2026-10-11 起）**：手机适配分支 `feature/phone-ui-adaptation` 已合并入 `main`，此后平板与手机**只在 `main` 上同时开发**，不再区分分支。 +> **分支约定（2026-10-11 起）**：手机适配分支 `feature/phone-ui-adaptation` 已合并入 `main`，此后平板与手机**只在 `main` 上同时开发**，不再区分分支。合并时的状态、验证覆盖与待决事项见 `documents/双端合入主干交接文档.md`。 > **业务以平板为准**：主流程交互、表单/筛选项、接口入参一律与平板一致，手机端只做 UI 适配——平板底部批量按钮在手机上可改为卡片级操作或 `PhoneBottomBar` 次按钮（`subAction1Text/subAction2Text`）， > 但不得新增平板没有的查询入参（如 `likeNo`）、不得改写平板的默认查询值（如默认当天日期）、不得少平板的表单项。 > 平板新增/修改功能时，必须同步检查对应手机布局与该页全部弹框的手机变体。 @@ -1136,12 +1136,11 @@ override fun dispatchRestoreInstanceState(container: SparseArray) = 合并搜索框只分流到平板同名入参：含字母→fno、其余→wbNo； checkIn 过滤等 7 项后端缺口见问题清单 #12~#18 - 「出港运抵」主列表 + 3 个手机专属新页：`IntExpArriveActivity`（待运抵/已运抵 Tab，客户端按 - `declareStatus` 是否为空拆分数据集，卡片长按浮层：待运抵→补充、已运抵→重置+回执）、 + `declareStatus` 是否为空拆分数据集，卡片长按浮层仅已运抵：重置 / 删除申报 / 回执）、 `IntExpArriveSubOrderActivity`（分单明细，数据直接复用主列表已加载的 `haWbList`，零新增请求）、 `IntExpArriveReceiptActivity`（分单回执只读页，复用 `haWbList[].response`；主单「回执」与平板侧滑同走 - `getResponse` → 共用 `CustomsResponseActivity`）、 - `IntExpArriveSupplementActivity`（补充信息，参照 Pad 端国际进港「收发货人信息」批量应用模式， - 后端接口不存在，实机 404 已确认，见问题清单 #19）。 + `getResponse` → 共用 `CustomsResponseActivity`）。 + （原手机专属「补充信息」页 `IntExpArriveSupplementActivity` 因后端无接口（#19）已于 2026-10-09 删除。） Tab 过滤两个坑：① **RecyclerView 里 `View.GONE` 不会让 item 塌陷为 0 高度**（不同于普通 ViewGroup），必须在数据层整体 `refresh()` 过滤后的子集给 adapter，不能给 item 根节点加 visibility 绑定（实机截图验证过，见「常见编译错误速查」）；② 通过 `Intent.putExtra(Serializable)` @@ -1550,14 +1549,16 @@ Glide.with(itemView.context).load(glideUrl).into(binding.ivThumbnail) ### 双端验证命令 ```bash -~/Library/Android/sdk/emulator/emulator -list-avds # 可用：Aerologic_Phone_5.5_API31（手机，首选）、Aerologic_Tablet（平板）、Medium_Phone_API_36.1 +/opt/homebrew/share/android-commandlinetools/emulator/emulator -list-avds # 可用：AeroLogic_Phone（手机）、AeroLogic_Tablet（平板） adb -s <设备> shell wm size && adb -s <设备> shell wm density # 确认屏幕参数 -adb -s <设备> logcat -d -s BaseActivity:D # 查看形态识别结果 PHONE(sw=384dp) / TABLET(sw=800dp) +adb -s <设备> logcat -d -s BaseActivity:D # 查看形态识别结果 PHONE(sw=394dp) / TABLET(sw=800dp) adb -s <设备> exec-out screencap -p > /tmp/shot.png # 截图比对 ``` -> 手机端验证**首选 `Aerologic_Phone_5.5_API31`**：按真实交付手持机 1:1 定制——720×1440、5.51 寸（300dpi，sw=384dp）、 -> Android 12 / API 31（与 targetSdk 一致）、arm64-v8a，与实机的差异最小。`Medium_Phone_API_36.1`（1080×2400、API 36） -> 仅作兼容性参考，分辨率与系统版本都和交付机不符。 +> 手机端用 **`AeroLogic_Phone`**：按真实交付手持机 1:1 定制——720×1440、5.51 寸（292dpi，sw=394dp）、 +> Android 12 / API 31、arm64-v8a，与实机的差异最小。 +> 平板端用 **`AeroLogic_Tablet`**：1280×800、160dpi（sw=800dp）、横屏、API 31。平板模拟器没有物理按键， +> `adb shell monkey` 拉起会失败，改用 `am start -n com.lukouguoji.aerologic/com.lukouguoji.module_base.LoginActivity`。 +> 模拟器可执行文件在 Homebrew 的 android-commandlinetools 下（见上方命令），不在 `~/Library/Android/sdk`。 > 改动 `BaseActivity` / `BaseBindingActivity` / 公共组件后，**必须在平板上回归**，确认现有平板版行为不变。 diff --git a/documents/双端合入主干交接文档.md b/documents/双端合入主干交接文档.md new file mode 100644 index 0000000..0852c9c --- /dev/null +++ b/documents/双端合入主干交接文档.md @@ -0,0 +1,219 @@ +# 平板 + 5.5 寸手机合入主干后的交接 + +> 日期：2026-10-11　|　基线提交：`origin/main @ 131eb03`　|　在线版：https://claude.ai/artifact/N8cWdTcMAzk9N86NSPevTC +> +> 本文描述合并当天的状态。分支、版本号等信息如有变化，以仓库为准。 + +## 接手前先知道这几件事 + +1. **只有一条开发分支：`main`。** 手机适配分支 `feature/phone-ui-adaptation` 已于 2026-10-11 合入，平板和 5.5 寸手机以后都在 `main` 上一起开发。 +2. **业务以平板为准，手机只做界面。** 两端共用 ViewModel、接口、表单项、筛选入参和默认值；差异只能出现在布局（View）层。 +3. **同一个页面有两份同名布局**：`res/layout-sw600dp/` 是平板，`res/layout/` 是手机。改平板页面时要同时检查手机布局和这个页面的所有弹框。 +4. **有两件事等人拍板**：ULD 保存可能报 500（问题清单 #36），以及手机独有的几个界面功能留不留（见第 6 节）。 + +--- + +## 1. 仓库与分支 + +| 分支 / 位置 | 提交 | 状态 | 建议 | +|---|---|---|---| +| `origin/main` | 131eb03 | 唯一开发分支 | 以后所有开发从这里拉分支、合回这里。 | +| 本地 `main`（主 checkout `~/Development/Projects/aerologic-app`） | 871fa4c | 落后 30 个提交 | 合并是在另一个 worktree 里推送的，主 checkout 还没同步。到那个目录执行 `git pull --ff-only`。 | +| `feature/phone-ui-adaptation`（本地 + 远端） | 42647c2 | 已完整合入 | 不要再往上提交。确认无人使用后可以删除（删除远端分支前先跟团队确认）。 | +| `worktree/phone-adaptation`（仅本地） | 42647c2 | 已完整合入 | 可删除。 | +| `merge/phone-into-main`（仅本地，worktree `~/.herdr/worktrees/aerologic-app/worktree-phone-adaptation` 当前检出） | 131eb03 | 与 main 相同 | 合并时用的临时分支。可以 `git worktree remove` 这个 worktree 后删除分支。 | + +合并提交 `131eb03` 的第一父提交是原 main（`871fa4c`），第二父提交是手机分支（`42647c2`），所以 `git log --first-parent main` 仍然是平板的历史。两条线的分叉点是 `9c4588e`：分叉后 main 有 58 个平板提交，手机分支有 29 个提交，合并时共 45 个文件冲突。 + +## 2. 平板与手机的开发状态 + +**平板（10 寸横屏）** + +- 功能完整，即合并前 main 上的全部功能。 +- 合并没有改平板的业务逻辑。冲突的平板布局用三方合并放进了 `layout-sw600dp/`，内容就是 main 最新版。 +- 已有手机变体的页面：20 个 Activity 布局 + 11 个弹框布局在 `layout-sw600dp/`。 +- 其余平板页面（舱单、理货、组装、航班管理等）只有一份布局，放在 `res/layout/`，没有手机版。 + +**手机（5.5 寸竖屏）** + +- 设计稿 01~11 的 11 个入口全部完成，并已按 main 的新平板功能补齐（见第 3 节）。 +- 手机首页是 `module_p` 的 `PDAEnterActivity`，菜单是手写清单（`GjViewModel` / `GnViewModel`），按登录权限串过滤。 +- 设计参考：`documents/5.5寸手持端设计文件/`，技术方案 `documents/5.5寸手持端适配技术方案.md`。 + +### 手机已适配页面 + +| 首页入口 | 页面（Activity） | 模块 | 说明 | +|---|---|---|---| +| 国际 · 出港移库 | `IntExpMoveActivity`、`IntExpMoveEditActivity` | gjc | 详情 / 编辑与平板共用同一个 Activity，手机布局为「运单详情」样式。 | +| 国际 · 出库交接 | `IntExpOutHandoverActivity`、`IntExpOutHandoverDetailActivity` | gjc | 底部栏带「允许装机」「配运」次按钮。 | +| 国际 · 出港计重 | `GjcWeighingListActivity`、`GjcWeighingStartActivity`、`GjcWeighingRecordListActivity`、`GjcWeighingRecordDetailsActivity` | gjc | 另有手机专属 `GjcWeighingWbDetailActivity`（运单详情）。 | +| 国际 · 出港运抵 | `IntExpArriveActivity` | gjc | 手机专属 `IntExpArriveSubOrderActivity`（分单明细）、`IntExpArriveReceiptActivity`（分单回执）；主单回执用两端共用的 `CustomsResponseActivity`。 | +| 国际 · 出港查询 | `GjcQueryActivity`、`GjcQueryDetailsActivity`、`LogDetailActivity`（运单追踪） | gjc / app | | +| 国际 · 出港仓库 | `IntExpStorageUseActivity` | gjc | 平板的「勾选 + 底部批量」在手机上改为卡片四按钮：清仓 / 修改库位 / 出库 / 入库。 | +| 国际 · 进港仓库 | `IntImpStorageUseActivity`、`IntImpQueryDetailsActivity` | gjj | 接口前缀是 `IntImpStorage`，不是 `IntImpStorageUse`。 | +| 国际 · 进港查询 | `IntImpQueryActivity` | gjj | | +| 国际 · 提取出库 | `IntImpPickUpDLVActivity` | gjj | 手机专属 `IntImpPickUpDetailActivity`。 | +| 国际 · ULD 管理 | `UldListActivity`、`UldEditActivity` | app | 一套编辑布局覆盖新增 / 修改 / 详情。 | +| 国内 · 进港移库 | `GnjMoveStashListActivity` | app | 业务归属国内进港移库（DomImpMove）。手机专属 `GnjMoveStashDetailActivity`、`GnjMoveStashPhotoActivity`。 | + +手机首页还有一批旧的 PDA 竖屏入口（国际：普货收运、板箱组装、板箱过磅、进港理货；国内：出港收运、出港复磅、出港存放、进港卸机、货物转运、转运记录、事故签证、单证交接）。它们是 `module_p` 原有页面，不在这次设计稿范围内，合并没有改动，也没有验证。 + +## 3. 这次合并做了什么 + +### 冲突处理原则 + +- **布局**：平板布局取 main 最新版，三方合并进 `layout-sw600dp/`，没有冲突残留。手机布局保留原样，再逐页补上 main 新增的业务字段和操作。 +- **Bean / ViewModel**：一律取平板逻辑。手机只保留它额外需要的展示字段（如 `opUserDisplay`、统计字段）。 +- **Manifest**：取手机分支版本（屏幕方向统一为 `unspecified`），再补上 main 新增的 Activity。 + +### main 的平板功能同步到手机 + +| 页面 | 同步到手机的内容 | +|---|---| +| 出港运抵 | 卡片显示海关放行、运单类型；筛选加分单号；回执改走平板同一接口和回执页；长按菜单加「删除申报」（手机底部弹框）。 | +| 出库交接 | 卡片显示装机状态；底部栏加「允许装机」「配运」；配运弹框做了手机变体。 | +| 出港移库 | 详情和编辑改用平板的 `IntExpMoveEditActivity`，删除手机专属 `IntExpMoveDetailActivity`；卡片加「编辑」；筛选加卸货站。 | +| 出港 / 进港仓库 | 清仓弹框加备注，卡片显示清仓备注；入库、出库弹框可填件数和重量（出库弹框新做了手机变体）；进港卡片件数取 `pcLabel`。 | +| 开始计重 | ViewModel 整体取平板版本：加运单号、地磅重量、平板车、托盘信息，运抵重量按平板公式自动计算；航班日期 / 航班号 / 航程可编辑。 | +| 计重 / 计重记录 | 计重列表加「新增」按钮；计重记录加航班号筛选，卡片加「运抵申报」入口。 | +| 计重明细 | 重量与托盘自重按平板逻辑联动（和恒定），同时保留手机的输入原文处理（避免光标跳动）。 | +| 进港查询 | 筛选加出库状态。 | +| ULD | 采用平板的来源列表与 HFE 默认值；卡片显示所在港 / 位置。 | + +### 手机按平板收敛的地方（使用上能感觉到） + +- 删除了平板不传的查询入参：`likeNo`（8 位运单号模糊查询）、进港移库的航班日期 / 航班号 / 特码、出港移库的特码。 +- 恢复平板默认查询值：计重、计重记录、提取出库等页面默认查当天，首次打开常常是空列表，属于预期行为。 +- 补齐平板有而手机缺的筛选项：运抵分单号、进港查询出库状态、计重记录航班号、进港移库承运人、出港移库卸货站。 +- ULD 编辑去掉平板没有的「进港航班号」和手机额外加的必填校验（影响见 #36）。 + +## 4. 以后怎么开发 + +项目根目录的 `CLAUDE.md`「5.5 寸手持端双形态适配规范」一节是完整规范，`.claude/skills/phone-adapt/` 是手机适配流程。下面是最常用的几条。 + +### 布局双变体的硬性约束 + +- 两个变体**文件同名**：平板 `layout-sw600dp/xxx.xml`，手机 `layout/xxx.xml`。禁止用 `xxx_phone.xml` 加代码判断，那样会生成另一个 Binding 类，进页面就 `ClassCastException`。 +- 两个变体的 `` 名称和类型必须一致。 +- Kotlin 里引用的控件 id 两边都要有；只有一边有的 id 在 Binding 里是可空的，代码里要写 `binding.xxx?.`。 +- 弹框同样做双变体，并在构造参数里切换位置：`BaseDialogModel(if (DeviceUtil.isPhone()) DIALOG_TYPE_BOTTOM else DIALOG_TYPE_CENTER)`。 +- Manifest 新 Activity 的 `screenOrientation` 写 `unspecified`，由 `BaseActivity` 按设备锁方向。 + +### 平板改了一个已适配页面，标准步骤 + +1. 改平板布局（`layout-sw600dp/`）和 ViewModel。 +2. 打开同名手机布局（`layout/`），补上同样的字段、筛选项和操作入口。平板的批量按钮在手机上可以改成卡片按钮或 `PhoneBottomBar` 的次按钮（`subAction1Text` / `subAction2Text`）。 +3. 检查这个页面用到的每一个 DialogModel，新弹框要做手机变体。 +4. 手机 Tab 角标、计数这类只有手机用的额外请求，放在 `phoneExtrasEnabled` 一类的开关后面，不能改变平板的请求。 +5. 两台模拟器各走一遍，再编译 `./gradlew assembleDebug`。 + +### 手机端不能做的事 + +- 不能新增平板没有的查询入参（后端口径：手机筛选一律与平板一致，后端不认识的参数会被静默忽略）。 +- 不能改写平板的默认查询值（如默认当天）。 +- 不能少平板的表单项或校验，也不能多加平板没有的校验。 + +### 新做一个手机页面 + +按 `CLAUDE.md`「手机版页面改造步骤」：`git mv` 平板布局到 `layout-sw600dp/` → 写同名手机布局 → 优先复用 `module_base/.../ui/weight/phone/` 下的组件（`PhoneSearchBar`、`PhoneFormRow`、`PhoneBottomBar` 等）→ 到 `GjViewModel` / `GnViewModel` 加首页菜单入口（最容易忘，忘了在手机上就进不去）。 + +## 5. 已验证与未验证 + +验证环境：手机模拟器 `AeroLogic_Phone`（720×1440，API 31，sw=394dp），平板模拟器 `AeroLogic_Tablet`（1280×800，sw=800dp），连内网测试服务。 + +| 项目 | 结果 | 说明 | +|---|---|---| +| Debug 编译 | ✅ 通过 | 合并后 `assembleDebug` 成功。 | +| 手机 11 个入口主流程 | ✅ 已验证 | 列表、Tab、筛选、详情、弹框打开，无崩溃。 | +| 平板回归（已适配的页面） | ✅ 已验证 | 主要页面打开、筛选、弹框，无崩溃，布局为 main 最新版。 | +| 开始计重自动计算 | ✅ 已验证 | 地磅 500、托盘 2 个 × 18 → 运抵重量 464，与平板公式一致。新增模式头部不再显示 "null kg"。 | +| 手机新弹框（出库 / 入库 / 清仓 / 配运 / 删除申报） | ⚠️ 只打开过 | 样式和字段都确认了，没有点提交，以免改动测试数据。 | +| 所有写操作（申报、出入库、清仓、保存、移库、拍照上传） | ⚠️ 未提交验证 | 合并后没有真实提交过。建议用测试数据逐个点一次提交，平板和手机都要。 | +| 海关回执页有内容时的显示 | ❌ 未验证 | 测试数据里没有带回执的运单。 | +| ULD 管理、国内进港移库 | ❌ 只编译过 | 合并后的改动没在模拟器上点过。 | +| 手机首页旧 PDA 入口 | ❌ 未验证 | 不在本次范围。 | +| Release 包、真机（交付手持机 / 平板） | ❌ 未验证 | 只在模拟器上跑过 Debug 包。 | + +## 6. 已知问题与待决事项 + +### 需要决定 + +- **ULD 保存可能报 500（问题清单 #36）。** 后端 `saveUld` 在缺少最大装载容积 / 最大载重时返回 500。之前只有手机做了必填拦截；按「以平板为准」去掉之后，两端都可能报错。可选做法：让后端修，或者在平板加同样的必填校验（再同步到手机）。 +- **手机独有的界面功能目前保留。** 它们只在手机上发请求，不影响平板，所以合并时留下了： + - 各列表的「待 / 已」Tab，以及 Tab 角标额外发的统计请求； + - 进港移库「已移库」Tab（调用平板不用的 `searchMoved` 接口）； + - 出港运抵分单明细页、分单回执页；ULD 状态显示为「可用 / 维修」；ULD 入库时间保存时补 `00:00:00`。 + + 如果要求两端严格一致，需要逐项删除。 + +### 对用户的行为变化（属于预期） + +- 手机列表默认查当天，首次打开常常为空，要在筛选里清掉日期。 +- 手机输入 8 位运单号不再能模糊查到（去掉了 `likeNo`），和平板一致。 + +### 后端缺口（问题清单 #35~#41，待后端处理） + +- ULD 列表按 uld 搜索返回 500；`saveUld` 缺 maxVolume / maxWeight 返回 500（#36）。 +- `IntImpStorage/pageQuery` 列表过滤全部不生效。 +- 出港仓库列表与统计的口径不一致。 +- 已移库数据没有 `mawbId`，无法补传照片。 + +完整内容和每一项的后端答复在 `documents/后端接口对接问题清单.xlsx`。这份表是和后端对接的正式文档，新发现的缺口要继续记在里面。 + +### 其他待办 + +- `PhoneSearchBar` 还没接 AutoQuery 联想（`AutoQueryManager` 只接了平板组件）。 + +## 7. 容易踩的坑 + +1. **API 文档的 token 提交进了仓库。** `.mcp.json` 里写着 api-doc MCP 的 `Authorization: Bearer …`，并且已被 git 跟踪。建议轮换这个 token，改为从环境变量或本地未跟踪的配置读取。 +2. **换行符混用，没有 `.gitattributes`。** main 原有文件多为 CRLF，手机分支新建的文件是 LF。编辑时保持文件原有换行符，否则会出现整文件 diff，合并和 review 都会很难看。 +3. **没有手机变体的平板页面，在手机上会直接显示平板布局。** 给手机首页加入口前，必须先做手机布局。 +4. **后端会静默忽略不认识的参数。** 猜错参数名会得出「后端不支持」的误判。入参出参一律用 api-doc MCP 核对，流程见 `.claude/skills/phone-adapt/references/api-doc.md`。 +5. **XML 里 `??` 兜底不生效。** 网络层会把 JSON null 转成空串，`??` 只判断 null。要在 Bean 上写计算属性（如 `agentDisplay`、`opUserDisplay`）。 +6. **RecyclerView 里给 item 设 `GONE` 不会收起高度。** Tab 过滤要在数据层过滤后整体 `refresh`。 +7. **Intent 传递的 Bean 里 `@Transient` 字段会变成 null**（`checked`、`showMore` 等）。接收方要 `.map { it.copy() }`。 +8. **同页多个手机复合组件会串状态。** 新写同类组件要覆写 `dispatchSaveInstanceState` / `dispatchRestoreInstanceState`（见 CLAUDE.md）。 + +第 5~8 条在 CLAUDE.md「常见编译错误速查」里都有详细说明和修复方式。 + +## 8. 环境与工具 + +- **工具链**：Gradle 用 Java 17 运行（`mise.toml`），编译目标是 Java 1.8；当前版本 1.8.7（versionCode 87）。 +- **内网**：测试服务器在内网，模拟器要在内网环境下才能拉到数据，否则提示「接口访问失败」。测试账号向项目负责人索取（不写在文档里）。 +- **登录不保留**：冷启动后要重新登录。 +- **Debug 直达页面**：`app/src/debug/AndroidManifest.xml` 把适配页设为 exported，可以直接拉起（只在 Debug 包生效）。 +- **平板模拟器没有物理按键**，`adb shell monkey` 拉起会失败，改用 `am start`。 +- **手机模拟器**上软键盘弹出时按返回键，有时会被吞掉并退出到桌面，不是崩溃。 +- **mobile-mcp** 偶尔识别不到 `emulator-5554`，可以直接用 adb。 + +```bash +# 启动模拟器（模拟器可执行文件在 Homebrew 的 android-commandlinetools 下） +/opt/homebrew/share/android-commandlinetools/emulator/emulator -avd AeroLogic_Phone & +/opt/homebrew/share/android-commandlinetools/emulator/emulator -avd AeroLogic_Tablet & + +# 编译安装 +./gradlew assembleDebug +adb -s emulator-5554 install -r app/build/outputs/apk/debug/*.apk + +# 拉起登录页（平板没有物理键时用这个） +adb -s emulator-5556 shell am start -n com.lukouguoji.aerologic/com.lukouguoji.module_base.LoginActivity + +# 确认设备形态识别 +adb -s emulator-5554 logcat -d -s BaseActivity:D # PHONE(sw=394dp) / TABLET(sw=800dp) +``` + +## 9. 关键文件索引 + +| 文件 | 用途 | +|---|---| +| `CLAUDE.md` | 项目规范总入口，包括双形态适配规范、分支约定、常见错误速查。 | +| `CHANGELOG.md` | [Unreleased] 下「手机适配分支合入主干 · 2026-10-11」是本次合并的完整记录。 | +| `documents/后端接口对接问题清单.xlsx` | 与后端对接的正式问题清单（#1~#41）。 | +| `documents/5.5寸手持端设计文件/` | 手机设计稿（HTML）。 | +| `.claude/skills/phone-adapt/` | 手机适配流程，含 api-doc、组件、平板安全、验证等参考。 | +| `module_base/.../util/DeviceUtil.kt` | 手机 / 平板判定（sw ≥ 600dp 为平板）。 | +| `module_base/.../ui/weight/phone/` | 手机公共组件，适配器在 `PhoneWidgetKtx.kt`。 | +| `module_base/.../MyApplication.kt` | AutoSize 设计基准（手机竖屏 390×844，平板横屏 1152×720）。 | +| `module_p/.../ui/enter/gj/GjViewModel.kt`、`gn/GnViewModel.kt` | 手机首页国际 / 国内菜单清单。 | +| `app/.../HomeFragment.kt` | 平板首页菜单，手机入口的权限串和路由要以它为准。 |