关封进仓手机端开发计划
本文件是正式开发用的纯净指导版，只覆盖关封进仓首期。接口字段级契约、模拟数据细节、壳自动更新调试记录不在本页展开，避免开发依据分散和过期。
Review 结论
可以进入正式开发
Scenario、DB 设计、手机端 PRD、状态机、API 能力和原型已能支撑关封进仓最小闭环。无需等待全业务一次性完成。
先做“现场进仓主线”
首期聚焦仓库内部人员：登录、工作台、进仓入口、叫车、卸车、理货、打印桩脚牌、入库复核、异常只读和主管处理。
后端必须走 G1 API
手机端不得直接新增独立
/mobile/** 控制器作为主线，也不得在前端拼 SQL。所有业务调用通过 G1 注册 API 进入存储过程或 G1 能力。
接口细节只维护一处
字段级参数、返回 JSON 和实际表名统一维护在 API 契约页。本页只定义开发顺序、边界、验收和协作口径。
原型优先于 API DTO
现阶段手机端原型准确度高于 API 数据结构。若 UI 与接口返回难以匹配，优先调整 API 契约和 callback JSON，不用数据结构反推页面。
页面跳转要有移动端动效
常用页面切换需要轻量滑动、淡入、底部弹层等过渡效果；不能做成生硬瞬切，也不能用花哨动画影响现场操作效率。
范围边界
| 类别 | 本期纳入 | 本期不纳入 |
|---|---|---|
| 业务范围 | 关封出口进仓现场作业，从待叫车车辆进入现场，到卸车、理货、打印桩脚牌、可选入库复核和异常处理。 | 统一装箱出运、装车提离、进口分拨拆箱、库内盘点、移库、车载机指令。 |
| 用户范围 | 内部仓库人员：理货员、叉车工、仓库管理员、现场主管。入口和按钮由后端权限返回。 | 客户、货代、司机自助手机端。客户协同继续放在 Web 门户。 |
| 前端范围 | Vue 移动端页面、G1 API client、原型视觉还原、页面跳转动效、状态驱动按钮、扫码/拍照/打印占位能力、APK 壳内 Web 自动更新。 | 重新设计一套风格、自由改动原型结构、在前端推导业务状态、在前端拼写数据库逻辑。 |
| 后端范围 | G1 API 注册、业务库 p_ 过程、必要 callback_js 格式化、测试数据 seed/reset 过程、PC 端共享领域动作。 |
绕过 G1 的新后端体系、全量 Swagger、全部业务线接口、真实外部报文对接。 |
关封进仓首期的“完成”只表示现场进仓链路跑通，不表示关封出口全流程完成。装箱、送港、收费、报文发送等后续仍按后续计划展开。
依据文件
| 依据 | 采用口径 | 开发使用方式 |
|---|---|---|
| Scenario | scenarios/scenario_catalog.html 为当前展示入口；关封进仓以送货受理、叫车、卸车、理货、打印桩脚牌、入库复核、异常为主线。 |
用于定义验收路径和业务动作，不直接照搬旧编号作为接口名。 |
| DB 设计 | local-docs/NewDB/业务仓库一体化模拟业务数据.html 为当前 DB 设计和模拟数据口径。 |
用于确认实际表名、字段关系和测试数据，不从 design-docs/sigpl_docs/NewDB 读取本地生成设计。 |
| 手机端 PRD | 04_手机端页面清单.md 和 09_手机端页面级PRD_全量上线.md 确认进仓作业入口、叫车、卸车、理货、入库复核和异常规则。 |
用于页面结构、按钮、状态拦截、照片/扫码/打印行为。 |
| 状态机与 API 能力 | 19、20、21 文档确认领域动作、读写分离、不裸 CRUD、车辆名额释放规则。 |
采用领域动作思想，但接口形态改为 G1 openApi 注册调用，不采用文档里的候选 /mobile/** 路径。 |
| 手机端原型 | mobile-hifi-v0.1 下原型是 UI 结构和视觉基线。 |
前端实现按原型还原，去除浏览器原型外壳和手机模拟器装饰，只保留真实 App 屏幕内容；原型未显式覆盖的页面切换按常见移动端过渡补齐。 |
| 截图对比页 | local-docs/mobile-ui-comparison/prototype-vs-actual.html 记录原型和当前 APP 的并排截图差异。 |
每次 UI 对齐和可见页面修改后，优先更新截图并复核差异是否收敛。 |
| API 契约页 | notes/20260715_gf_inbound_mobile_api_contract.html 是接口字段级开发依据。 |
前端开发请求/响应、后端过程签名、返回 JSON 以该页为准。 |
原型 / API / DB 优先级
| 冲突场景 | 处理原则 | 需要确认的边界 |
|---|---|---|
| 原型 UI 与当前 API 返回结构不匹配 | 以原型页面结构、信息层级和交互形态为准，调整 API 契约、存储过程返回字段或 callback_js 输出 JSON。 | 不因为现有 DTO 字段分组、命名或层级不顺手，就改变页面布局。 |
| API 数据结构导致页面越做越不像原型 | 先回到原型截图和 HTML/CSS/SVG 抽取真实 UI 需求，再重写前端 view model 和 API 返回 JSON，使其服务页面。 | 调试字段、联调状态、技术指标不得直接进入正式页面；必要时放入隐藏诊断入口。 |
| 接口契约发现不合理 | 可直接更新 API 契约页、callback_js 格式化口径和 p_mobile_* 过程草稿，保持前端可消费 JSON 清晰稳定。 |
若只是返回格式、字段别名、数组层级、状态按钮表达方式，不需要停下来确认。 |
| 发现数据库表结构或核心关系不合理 | 先记录问题、涉及表名、影响页面和替代方案，再和用户确认；未经确认不修改 DB 设计、物理表或既有核心关系。 | 涉及新增/删除字段、改变主外键、改变状态字段语义、拆表/合表、影响 PC/G1 页面时，必须确认。 |
开发顺序调整为：先按原型还原页面视觉骨架和交互层级，再定义该页面需要的前端 view model，最后让 G1 API 返回这个 view model。数据库只作为事实模型来源，不直接决定手机端 UI 形态。
技术口径
- 移动端使用 Vue 作为核心，Android 壳只承载 WebView、全屏、自动更新 APK、扫码/拍照/打印等必要原生桥接。
- Web 内容自动更新，只有壳能力变化才需要用户安装新版 APK。业务功能优先通过 Web 包迭代。
- Vue 页面跳转必须有移动端常用过渡：一级/二级页面前进用横向滑入，返回用反向滑出；底部选择器/操作确认用底部上滑；同页状态刷新用轻量淡入或局部过渡。动效时长控制在约 160-260ms，尊重系统减少动态效果设置。
- 业务 API 统一调用
/openApi/execAPI.do?domain=g1_sipgl&api=<api_id>；文件上传沿用 G1 开放上传能力。 - G1 API 以
sv_c_url_api注册为准。写入类优先使用type=3存储过程 API，首参UUID由 G1 注入。 - 存储过程返回能力不足时，允许在 G1 API 回调层使用小段 JS 格式化为前端需要的 JSON，但业务校验和状态变更仍在后端完成。
- API 返回 JSON 是手机端 view model，不要求机械暴露数据库表结构；字段分组、列表摘要、按钮能力和阻断原因应服务原型页面。
- 所有写接口必须有幂等键或等价幂等策略，返回
nextActions、blockingReasons、最新状态和动作记录 ID。 - 前端只按后端返回的状态和按钮能力展示，不自行推导可操作性；扫码也必须带入口和动作上下文交给后端判断。
- 照片、打印、异常、暂停是公共能力。业务动作只引用照片路径/照片组和打印任务结果，不把二进制上传塞进业务过程。
业务闭环
登录与工作台用户、仓库、角色、入口权限
进仓入口作业中列表、待叫车数、异常数
叫下一车锁定候选、确认库门、取消/超时
扫码卸车上下文校验、车牌确认、开始/完成卸车
理货入库测量、做关、库位、残损、照片
打印桩脚牌完成单票入库，生成库存识别对象
入库复核按规则启用，客户标签与桩脚牌核对
异常管理异常只读、暂停确认、监护确认、解冻
车辆作业单元释放规则固定：本港进仓只在本车辆作业单元下全部应卸货对象完成卸车后触发释放重算。后续理货、打印桩脚牌、入库复核不占用进仓叫车名额。
交付线
| 交付线 | 职责 | 主要产物 |
|---|---|---|
| 移动端前端 | 按原型实现真实 App 页面，封装 G1 API 调用、登录态、错误提示、按钮状态、页面跳转动效、扫码/拍照/打印占位。 | Vue 页面、路由过渡、状态管理、API client、原型样式迁移、APK Web 包发布。 |
| 手机端后端接口 | 把移动端需要的查询和动作注册成 G1 API，输出稳定 JSON，隐藏存储过程返回格式限制。 | G1 API 配置、参数表、callback_js、接口验收样例。 |
| 领域动作存储过程 | 实现叫车、卸车、理货、打印、复核、暂停、冻结、解冻等状态流转、幂等、动作记录和表级写入。 | 业务库 p_ / p_mobile_ 过程、只读验证 SQL、必要 PC 共用动作。 |
| 后台模拟数据 | 生成可重复跑的关封进仓样例，覆盖普通、异常、锁定、照片缺失、复核冻结等场景。 | p_mock_gf_inbound_seed_case、p_mock_gf_inbound_reset_case、测试数据清单。 |
| 文档和验收 | 保持计划、API 契约、变更记录一致，确保开发过程不依赖聊天记忆。 | 本计划、API 契约页、验收脚本、截图和变更记录。 |
开发顺序
| 阶段 | 目标 | 完成标准 |
|---|---|---|
| 0. 基线收口 | 确认原型截图基线、页面 view model、API 契约、G1 注册方式、统一 JSON 返回、幂等字段、模拟数据范围。 | 接口契约页不再有明显过时路径；至少一个 G1 API 可返回前端需要的 JSON；截图对比页能作为 UI 验收入口。 |
| 1. App 基础骨架 | 登录页先按原型还原视觉骨架，再接入 G1 登录/上下文，建立路由、路由过渡、API client、统一错误提示和更新检查。 | 手机安装后可全屏打开；Web 自动更新可用；登录页截图与原型差异收敛；登录进入工作台不再生硬瞬切。 |
| 2. 工作台与进仓入口 | 展示进仓作业入口、作业中车辆卡片、待叫车数、异常数、扫码按钮和叫下一车按钮。 | 页面结构、卡片密度、按钮文案和图标按原型；数据来自 G1 API；无权限时按钮隐藏或禁用。 |
| 3. 叫车闭环 | 跑通叫下一车、候选锁定、库门选择、确认叫车、取消/超时释放、更改库门。 | 弱网重复点击不重复推进；确认后车辆作业单元进入作业中。 |
| 4. 卸车闭环 | 跑通扫码上下文校验、车牌确认、开始卸车、协助/监护/暂停、完成卸车和释放重算。 | 完成卸车后返回入口，后端可判断车辆名额是否释放。 |
| 5. 理货与打印 | 实现理货详情、测量、做关、库位、残损、照片摘要、打印桩脚牌。 | 打印桩脚牌后单票进入入库完成；满足规则时进入待复核。 |
| 6. 入库复核 | 实现复核入口、一对一连续扫码、复核完成、扫错冻结或异常。 | 复核完成只记录复核结果，不改变入库完成时间，不影响叫车名额。 |
| 7. 异常与主管处理 | 实现异常只读列表、暂停确认、大件监护确认、解冻列表/详情/确认。 | 普通作业页只显示阻断和提示，处理动作进入管理入口或 Web。 |
| 8. 联调验收 | 用同一批模拟数据从 PC/seed 开始跑完整关封进仓链路，并更新原型/实际截图对比。 | 手机端、G1 网页端、数据库状态、动作记录、照片/打印占位和异常记录可互相印证；截图差异只剩已确认的实现限制。 |
功能拆分
| 模块 | 前端页面 | 后端能力 | 关键验收 |
|---|---|---|---|
| 登录与上下文 | 登录、仓库/角色上下文、工作台。 | 用户、仓库、角色、权限、入口统计。 | 不同角色看到不同入口和按钮；登录失败提示明确。 |
| 进仓入口 | 作业中列表、叫下一车、卸货扫码、理货扫码、入库复核扫码、异常入口。 | 入口 DTO、车辆作业单元列表、扫码上下文、异常摘要。 | 不展示完整待叫车队列；普通操作员不能挑车、跳车。 |
| 叫车 | 叫车确认弹窗、库门选择、更改库门。 | 锁定候选、确认叫车、取消/超时释放、更改库门。 | 锁定超时不可确认；确认后占用名额；取消后回待叫车。 |
| 卸车 | 扫码进入、车牌确认、卸车页、照片摘要、特殊处理入口、完成卸车。 | 卸车任务 DTO、开始卸车、协助登记、大件监护、暂停申请、完成卸车。 | 未完成卸车不能进入理货；完成卸车触发释放重算。 |
| 理货入库 | 理货主页面、测量录入、做关数据、库位选择、残损记录、打印桩脚牌。 | 理货详情、保存测量/做关/库位/残损、照片要求、打印桩脚牌。 | 打印桩脚牌是单票入库完成标志；没有单独“理货完成”按钮。 |
| 入库复核 | 复核页、一对一扫码、照片摘要、复核完成。 | 开始复核、扫码复核、完成复核、扫错冻结。 | 只对启用复核且有客户标签的本港进仓开放；进口分拨不进入本期。 |
| 异常管理 | 异常只读列表、主管处理列表、处理详情。 | 异常/暂停查询、确认暂停、恢复/解冻、异常关闭。 | 异常处理有权限控制、原因必填、动作留痕。 |
模拟数据
- 模拟数据只能使用测试前缀，必须支持一键 reset，不和真实客户数据混淆。
- 首批至少准备：待叫车、叫车确认中、作业中待卸车、卸车中、卸车完成待理货、理货中、已打印待复核、复核冻结。
- 必须覆盖普通货、大件货、需要做关、不需要做关、库位不足、照片缺失、车牌不一致、标签不匹配。
- seed 过程只生成可进入流程的数据，不替代真实动作过程直接改到最终状态。
- reset 过程必须只清理测试前缀数据，并保留执行日志或返回清理数量。
验收标准
| 验收项 | 通过标准 |
|---|---|
| 前端 | 手机真机全屏运行；页面不带原型模拟器壳；视觉、布局、图标、按钮文案、信息层级和原型一致；页面前进/返回、底部弹层、同页状态切换有自然轻量动效；按钮状态由后端返回驱动。 |
| 接口 | 所有业务调用走 G1 API；请求参数和返回 JSON 与 API 契约页一致；返回 JSON 是面向原型页面的 view model，错误和阻断原因可直接展示。 |
| 状态 | 叫车、卸车、理货、打印、复核、异常处理均由后端推进状态并写动作记录。 |
| 幂等 | 重复点击确认叫车、完成卸车、打印桩脚牌、复核完成时，不重复生成副作用。 |
| 数据 | 同一测试单可在手机端完成链路，也可在 G1 网页端查到主对象状态、动作记录、桩脚牌、库存和异常记录。 |
| 设计冲突 | API 返回结构不合理时允许直接调整 API 契约和 callback JSON；数据库结构或核心关系不合理时，必须先形成问题说明并经用户确认。 |
| 发布 | 普通 Web 迭代可通过内容自动更新生效；只有新增原生能力时才发布新版 APK。 |
已清理内容
本页不再保留以下过时或容易误导开发的内容。
- 不再把独立
/mobile/**URL 作为正式接口形态；它们只属于远端设计文档里的候选能力口径。 - 不再在开发计划页维护完整接口参数表，避免和 API 契约页重复并发生版本漂移。
- 不再把进口分拨拆箱、装箱出仓、装车提离、库内盘点、移库、车载机列入首期实施范围。
- 不再记录 Android 壳自动更新调试过程。壳能力已经稳定，后续只按发布策略维护。
- 不再把旧 Scenario Markdown 中的历史编号当作最终开发任务编号；开发以当前业务动作和 API 契约为准。
- 不再保留“前端自行判断扫码类型、业务状态、下一步动作”的描述；这些全部由后端返回。