fix: 出库交接交接状态参数名改为handoverState并完成内网验证
- 按 api-doc 接口文档修正交接状态入参 hoState → handoverState（原参数被后端 静默忽略，两个 Tab 返回同一批数据）；内网实机验证 0/1 过滤与 App 端到端链路 均生效，平板端回归无影响 - 新增《后端接口对接问题清单.xlsx》：按模块/页面/接口定义/接口地址索引的后端 对接文档，含 5 项待处理缺口（移库缺航班字段/操作人姓名/数据不回填、交接缺 交接人入参、pageQueryTotal 出参恒 0）+ 1 项已验证归档 - phone-adapt skill 新增 references/api-doc.md（api-doc MCP 核对流程 + 内网 直调验证技巧），阶段 2 改为「先查接口文档再问用户」，修正 verification.md 中「后端不认 hoState」的过时误判结论 - CLAUDE.md / CHANGELOG.md 同步走查与验证结论 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
86
.claude/skills/phone-adapt/references/api-doc.md
Normal file
86
.claude/skills/phone-adapt/references/api-doc.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# api-doc MCP：接口定义核对流程（阶段 2 必读）
|
||||
|
||||
适配页面前，**所有用到的接口都要在 api-doc（AgentFox）里核对一遍入参/出参**，
|
||||
不要靠平板代码或猜测推断参数名——出库交接就因为猜了 `hoState`（实际是 `handoverState`）
|
||||
白白折腾了一轮实机排查。
|
||||
|
||||
## 连接方式
|
||||
|
||||
项目 `.mcp.json` 已配置 `api-doc` 远程 HTTP MCP。若会话内 MCP 工具可直接调用
|
||||
（`mcp__api-doc__*`），直接用；**若工具没有注入会话**（ToolSearch 搜不到），用 curl 走
|
||||
MCP 协议手工调用，三步：
|
||||
|
||||
```bash
|
||||
URL=$(python3 -c "import json;print(json.load(open('.mcp.json'))['mcpServers']['api-doc']['url'])")
|
||||
AUTH="Authorization: $(python3 -c "import json;print(json.load(open('.mcp.json'))['mcpServers']['api-doc']['headers']['Authorization'])")"
|
||||
|
||||
# 1) initialize：从响应头 mcp-session-id 取会话 id
|
||||
curl -s -D /tmp/mcp_headers.txt -X POST "$URL" -H "$AUTH" -H "Content-Type: application/json" \
|
||||
-H "Accept: application/json, text/event-stream" \
|
||||
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude-code","version":"1.0"}}}' > /dev/null
|
||||
SID=$(grep -i 'mcp-session-id' /tmp/mcp_headers.txt | tr -d '\r' | awk '{print $2}')
|
||||
|
||||
# 2) initialized 通知（必须发，否则 tools/* 报 session 未初始化）
|
||||
curl -s -X POST "$URL" -H "$AUTH" -H "Content-Type: application/json" \
|
||||
-H "Accept: application/json, text/event-stream" -H "mcp-session-id: $SID" \
|
||||
-d '{"jsonrpc":"2.0","method":"notifications/initialized"}' > /dev/null
|
||||
|
||||
# 3) tools/call（响应是 SSE，`sed 's/^data: //'` 后按 JSON 解析）
|
||||
curl -s -X POST "$URL" -H "$AUTH" -H "Content-Type: application/json" \
|
||||
-H "Accept: application/json, text/event-stream" -H "mcp-session-id: $SID" \
|
||||
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_endpoints","arguments":{"keyword":"IntExpMove"}}}'
|
||||
```
|
||||
|
||||
## 可用工具（5 个）
|
||||
|
||||
| 工具 | 用途 |
|
||||
|------|------|
|
||||
| `get_project_overview` | 项目概览 + 模块清单（首次调用） |
|
||||
| `list_modules` | 全部模块含描述 |
|
||||
| `list_endpoints` | 单模块内接口列表（分页，`moduleId` + `cursor`） |
|
||||
| `search_endpoints` | 按关键字搜接口（`keyword` 用控制器前缀最准，如 `IntExpOutHandover`） |
|
||||
| `get_endpoint_detail` | **核心**：单接口完整契约，schema 已拍平成字段表（`endpointId`） |
|
||||
|
||||
## 核对清单（每个页面做一遍）
|
||||
|
||||
对 ViewModel 里每个 `NetApply.api.xxx` 调用：
|
||||
|
||||
1. 从 `module_base/.../http/net/Api.kt` 拿到 `@POST` 路径 → `search_endpoints` 找到接口 → `get_endpoint_detail`
|
||||
2. **入参**：前端传的每个 key 必须能在文档字段表里找到**同名字段**；找不到 = 传了也白传（后端静默忽略，不报错）
|
||||
3. **类型**：状态类字段（`moveState`/`handoverState`/`outState`）文档均为 integer，前端传 `"0"` 字符串靠
|
||||
Jackson 隐式转换（实测可用）；新代码尽量传数字
|
||||
4. **出参**：设计稿卡片/详情页的每个展示字段，都要能对上出参字段；对不上就是后端缺口
|
||||
5. **结论落两处**：
|
||||
- 后端缺口（缺入参/缺出参/数据不回填）→ 记入 `documents/后端接口对接问题清单.xlsx`
|
||||
（按「模块 → 页面 → 接口定义 → 接口地址」格式，含前端现状与期望，状态标 ⏳/🔍）
|
||||
- 前端可自行解决的（参数名写错、字段绑错）→ 直接改代码，别记成后端问题
|
||||
|
||||
## 已核对过的语义（别再猜）
|
||||
|
||||
- `IntExpOutHandover`：交接状态入参 = `handoverState`（不是 `hoState`），**2026-07-29 内网实测过滤生效**
|
||||
（传 0/1 分别返回纯净的待/已交接集合，字符串 `"0"`/`"1"` 同样被接受）；`ldId` 是**组装人**不是交接人；
|
||||
交接人姓名出参 `hoUserName`，编码 `hoId`；查询入参**没有**交接人筛选（后端缺口 #4）
|
||||
- `IntExpOutHandover/pageQueryTotal`：**出参恒 0**（任何条件下 totalPc/totalWeight/wbNumber 均为 0，
|
||||
与同条件 pageQuery 不一致，后端缺口 #6）——依赖它的 Tab 角标/底部统计显示 0 不是前端问题
|
||||
- `IntExpMove`：出参无航班字段（缺口 #1）、无操作人姓名（缺口 #2）；`opId`/`opdate`/`businessType`
|
||||
文档有定义但实测恒 null（缺口 #3）；`pageQueryTotal` 正常（与 pageQuery 口径一致，`moveState` 过滤生效）
|
||||
- `typeCode/getSpecialCodeByParam`：`flag=1` 国际，`ieFlag` 必须传空串（传 `"E"` 返回空数组）
|
||||
|
||||
## 内网直调验证技巧（比驱动 UI 快得多）
|
||||
|
||||
登录态 token 存在 SharedPreference 里，取出后可以直接 curl 后端做行为验证
|
||||
（**注意：不要把 token 打印到输出里**，落临时文件引用）：
|
||||
|
||||
```bash
|
||||
adb -s <serial> shell "run-as com.lukouguoji.aerologic cat \
|
||||
/data/data/com.lukouguoji.aerologic/shared_prefs/data.xml" \
|
||||
| grep -o '<string name="token">[^<]*' | sed 's/.*>//' > /tmp/air_token
|
||||
|
||||
curl -s -X POST "http://192.168.1.250:8093/IntExpOutHandover/pageQuery" \
|
||||
-H "Authorization: $(cat /tmp/air_token)" -H "Content-Type: application/json" \
|
||||
-d '{"pageNum":1,"pageSize":50,"handoverState":0}'
|
||||
```
|
||||
|
||||
用它做「参数是否生效」的 A/B 对比（同条件只改一个参数看 total 变化），
|
||||
再回 App UI 走一遍确认端到端链路。UI 里的滚轮日期选择器可用
|
||||
`input swipe`（慢速 500ms、每次 3 格 ≈ 396px）驱动，滑完截图校准。
|
||||
@@ -101,11 +101,14 @@ $P <serial> texts | grep -c "全选" # 用文字变化确认点击确实生效
|
||||
$P <serial> req pageQuery
|
||||
```
|
||||
|
||||
OkHttp 日志是多行 pretty JSON。看到请求体里有你的字段（如 `"hoState": "0"`）只说明客户端对了。
|
||||
OkHttp 日志是多行 pretty JSON。看到请求体里有你的字段（如 `"handoverState": "0"`）只说明客户端对了。
|
||||
**服务端是否生效要用行为验证**：切到另一个 Tab，看返回数据是否真的变了。
|
||||
|
||||
本次实测：请求正确携带 `hoState:"0"/"1"`，但两个 Tab 返回同一批数据 → 后端没做过滤。
|
||||
这种情况**必须在交付说明里如实标注**，不能让它看起来是通的。
|
||||
⚠️ 行为验证失败时**先怀疑参数名，再怀疑后端**：出库交接第一版传 `hoState`，两个 Tab 返回同一批数据，
|
||||
一度误判为「后端没做过滤」；实际是参数名错了（api-doc 里是 `handoverState`），后端对不认识的参数
|
||||
**静默忽略**。正确顺序：查 `references/api-doc.md` 核对参数名 → 用 token 直调后端做 A/B 对比
|
||||
（同条件只改一个参数看 total 变化）→ 仍不生效才定性为后端缺陷并记入
|
||||
`documents/后端接口对接问题清单.xlsx`。
|
||||
|
||||
## 无数据时怎么核对 UI
|
||||
|
||||
@@ -136,7 +139,8 @@ for i in $(seq 1 10); do adb -s <phone> shell dumpsys window | grep -m1 -oE "mRo
|
||||
```
|
||||
|
||||
平板则应首屏就是横屏（截图宽 > 高）。若手机出现横屏帧，检查该 Activity 的 Manifest
|
||||
是否漏写 `android:screenOrientation="@integer/screen_orientation"`。
|
||||
是否写成了别的值——**必须是 `android:screenOrientation="unspecified"`**（写死 `userLandscape`
|
||||
或用 `@integer/...` 资源引用都会出问题，详见 SKILL.md 阶段 4）。
|
||||
|
||||
## Pad 端回归（必做）
|
||||
|
||||
|
||||
Reference in New Issue
Block a user