# 小程序危化品证上传 H5 迁移设计 日期:2026-10-17 状态:2026-10-17 按用户最新反馈进行第三次校准;详情改为独立页面并删除票根/顶部特殊区。此前“详情面板 + 票根”的验证结论已失效,完成证据以本轮更新后的 `2026-10-17-mp-pl-plan-cert-delivery.md` 为准。 ## 1. 目标与边界 在小程序「运输管理」下新增「危化品证上传」,通过已有 WebView 容器访问独立移动端 H5。迁移 Web 同名功能,唯一明确删除的业务功能是导出;桌面表格、列头筛选及弹窗按移动端交互转换。 - 不修改 Web 页面、Web 上传弹窗、共享业务规则和既有后端行为。 - 不修改其他页面发现的问题,只在独立问题文档记录与交付时报告。 - 不增加业务表或字段。新增移动菜单及其角色祖先绑定 SQL 放在 `docs/sql/`,不因前一项客户菜单的授权而自动执行本次 SQL。 - 保留现有工作区的未提交改动;开始编码前确定工作区选择,不能用重置或覆盖方式清理。 ## 2. 已核对的功能来源 | 项目 | 依据 | | --- | --- | | 列表、五个 Tab、批量操作、权限、详情入口 | `web-admin/src/views/pl/plan-cert/index.vue` | | 全部列头筛选字段 | `web-admin/src/views/pl/plan-cert/columnFilterDefs.ts` | | 证书上传及保存载荷 | `web-admin/src/components/business/pl-plan-cert-upload-dialog/index.vue` | | 危化属性、证书槽位、齐备确认提示 | `web-admin/src/composables/usePlToxicProductCertCheck.ts` | | Tab 参数和状态枚举 | `web-admin/src/utils/pl-display.ts` | | 列表、详情、证书 PATCH 接口 | `web-admin/src/api/pl/index.ts` | | 移动布局、运输卡片参考 | `web-admin/src/views/m/pl/plan/index.vue`、`web-admin/src/views/m/pl/plan/detail.vue` | | 最近迁移经验、附件引用及上传中检查 | `web-admin/src/views/m/crm/customer/` | | 入口鉴权与 WebView 接入约定 | `docs/web-admin-mp-webview-modules.md` | 模式选型:工作台 WebView style-align 列表(标准绿顶栏 + 状态 Tab + 三栏筛选 + expense-card)+独立路由 Tab 详情+发票夹附件。详情仅保留普通绿顶栏,不使用票根、Hero 或记录摘要等顶部特殊区。移动视觉以 `docs/miniprogram-ui-spec-sanqiang.md` §12、OpenSpec「工作台 WebView 业务页」和 `bak/mobile-ui/shanxia-mp-crm-pl-cert-style-align-demo.html` 为唯一权威,不照搬桌面宽表,也不沿用旧 `cert-*` 密集工具条。 ## 3. 方案选择 推荐列表 `/m/pl/plan-cert` + 独立详情 `/m/pl/plan-cert/:id`,复用 API、纯业务规则及现有移动基础组件。列表只能通过路由进入详情;详情必须支持直达、刷新、浏览器/小程序返回与路由参数切换。 另两种方案不采用:直接嵌入 Web 页会保留宽表和桌面弹窗;修改共享 Web 页面适配移动会扩大回归范围并违反不修改 Web 的要求。 ## 4. 页面和交互 ### 4.1 列表与 Tab 顶部复用 `mp-wv-header`:返回工作台、17px 固定标题,以及标题下方的五个胶囊状态 Tab(仍在绿顶栏内);不显示副标题、独立“搜索”按钮或检索框。Tab 顺序: 1. 未上传证书(默认)。 2. 全部。 3. 入库单。 4. 出库单。 5. 直销单。 Tab 不能改成下拉选择。窄屏允许 Tab 区域横滑;绿顶栏内选中态为白底绿字,未选为半透明白边白字;页面整体不能横向溢出。点击后重置页码与选中项,保留无冲突筛选;过期请求不能覆盖新 Tab 的结果。绿顶栏下方为单个胶囊检索框(提交键触发搜索),再紧贴三栏筛选。 查询语义必须与当前 Web 一致: - 所有 Tab 均附带 `hasHazardProduct=1`。 - 未上传证书:`certUploadStatus=incomplete` 且 `hazardCertReady=0`,不是简单地检查是否存在任意附件。 - 全部:不增加单据类型和证书状态限定。 - 其他三个 Tab 分别使用 `planType=inbound/outbound/direct`。 - 默认跟进状态集合不含 `cancelled`,允许用户在筛选中明确选择已取消。 - Tab 优先于冲突的单据类型、齐备状态筛选;保持后端的默认排序。 列表使用备用金式 `expense-card` 和可展开段次/产品信息。卡片与左右边界保留约 12px 间距;「共 N 条计划 · 已加载 M 条」汇总放在卡片列表之后。卡片须具备 `ec-top`、副信息、灰底 KV、时间 meta、虚线操作底栏;勾选框在标题左侧,浅底语义状态标签在右侧,每卡最多一个实心主色按钮(上传证书)。列表展开按段次分区:装货段次(1 段)与送货段次(可多段),各段展示客户、时间、地址、合同与产品摘要;不展示计划附件(附件改在详情查看)。合同可进入移动只读详情。 ### 4.2 搜索、筛选与加载 列表自上而下固定为「绿顶栏(标题 + 状态 Tab)→ 检索框 → 三栏筛选 → 卡片 → 条数汇总」,不得在 Tab 下方堆叠日期 Chip 和“筛选/刷新/重置”工具条。三栏固定为: 1. 日期:全部日期、今天、明天、昨天、本周,可直接下拉选择。 2. 齐备状态:全部、未齐备、已齐备,可直接下拉选择;与默认“未上传证书”Tab 冲突时 Tab 语义优先。 3. 更多:打开底部筛选 Sheet;存在额外条件时显示红点。 “更多”集中承载 Web 列头筛选,并同时提供 Chip、模糊检索、日期/日期时间、日期区间和数值区间;底栏仅“重置/确定”。保留关键词查询、自定义日期、筛选重置和分页加载;刷新通过重新提交搜索或重试错误完成,不保留独立密集工具条: - 计划编号、计划日期、送货时间、单据类型、归属公司、跟进状态、证书齐备。 - 车牌、人员、跟进人、装货客户、送货客户、装送地址/时间。 - 合同、产品名称、规格、单位、计划量、实际量。 - 保留对应枚举多选、动态可选值、日期范围、数值比较及可用排序能力。动态可选值请求保留当前查询上下文。 - 装送客户合并查询、合同侧别和配对行过滤遵循 Web 工具函数,不能仅查询到计划后无差别展示不相关的匹配段次。 空结果、加载中、加载失败、无权限状态分别提示;加载更多失败不跳过页码;重复点击操作期间禁止再次提交。 ### 4.3 计划详情 采用独立页面 `/m/pl/plan-cert/:id`,由页面自己从 `route.params.id` 读取计划、权限和关联数据。顶部只使用普通 `mp-wv-header`(返回 + 固定标题“危化品证详情”),不显示票根、Hero、计划号副标题或状态等顶部特殊区;计划号、状态和齐备信息下沉到正文信息卡。顶栏后直接展示“基础信息 / 运输与段次 / 证书与附件”Tab,每个 Tab 下使用字段上标签下值的信息卡。详情范围对齐 Web `PlPlanViewDialog`,包括完整装送段次、产品/数量、运输、证书、附件、运费、备注及其原有可查看关联信息。 详情必须支持链接直达和刷新;非法或无权 ID 展示独立页面错误态;关联计划跳转更新当前路由参数并重新加载。上传、齐备、取消齐备成功后原位刷新详情,返回列表后列表重新请求,不能依赖列表父组件的 ref 或弹层开关。 复用已有移动展示工具,但不能直接导航到具有新增计划、复制计划、作废、安排运输等额外业务操作的通用运输详情而改变本菜单的操作边界。详情主要操作提供本菜单有权限且当前状态允许的上传、齐备和取消齐备。 进一步核对 `PlPlanViewDialog` 后确认:Web 本菜单的详情还会根据 `usePlPlanArrangeActions` 的结果提供「复制给司机」「复制给现场」「复制磅单二维码」及司机/现场链接。这些属于现有详情功能,移动迁移必须保留并沿用相同显示条件,不能误当成导出删除;可放入详情“更多”操作区。列表与详情操作成功后均重新读取服务器状态。 ### 4.4 上传证书 - 打开时重新获取计划详情,按现有逻辑读取 CRM 产品危化属性。 - 易制毒展示购买证、运输证;易制爆展示合法证明;按共享 `getRequiredCertSlots` 规则处理已有数据,不自行覆盖历史属性。 - 每个产品一张分组卡,字段标题在上,附件宫格在下。 - 继续使用已有 `AttachmentUploadField` 的上传、预览、下载与删除能力,但在本模块内将触发项和文件项覆盖为发票夹式 72×72 宫格:图片缩略填充,非图片显示扩展名与文件名,删除为右上角角标,末位虚线“+”添加;不得保留管理端 140×96 主形态。 - 支持预览、下载、移除,与既有移动附件交互一致;只读状态不显示编辑入口。 - 文件选中即上传到既有附件服务;业务保存仅发送产品 ID 和三个逗号分隔 URL 字段,不发送 Base64、不修改计划其他字段。 - 有上传进行中时阻止保存。保存失败保留已填写内容,可重试;取消不提交业务记录。 - 沿用 Web 允许稍后补附件的规则,不把所有槽位非空作为保存或人工齐备的强制条件。 ### 4.5 齐备操作与权限 - 单条及多选批量「证书齐备」「取消齐备」均保留;批量确认说明实际可操作条数,跳过不符合状态的项目,并报告成功、失败及跳过数量。 - 已归档(`archiveStatus=archived`)或已取消(`followStatus=cancelled`)不能上传或改齐备。 - 只有含危化产品的计划可操作齐备;已齐备只允许取消,未齐备只允许标记。 - 使用既有 `pl:plan-cert:upload`、`pl:plan-cert:ready` 权限,不因有移动入口就赋予写权限。权限加载失败按无权限处理。 - 人工齐备需二次确认,提示易制毒/易制爆的证书要求及之后仍可补附件;取消齐备提示其对运输安排的影响。 - 调用现有 `PATCH /transport/plan/{id}/product-certs`、`PATCH /transport/plan/{id}/hazard-cert-ready`,不增加替代接口或绕过已有租户/数据范围保护。 ## 5. 入口和样式 - 工作台「运输管理」新增 code `pl-plan-cert-webview`。 - 路径映射到已有 `mpWebview` 容器,目标 `/m/pl/plan-cert`;沿用票据换取登录、返回工作台及安全区处理。 - 新移动权限建议 `mini:pl:plan-cert:list`;迁移 SQL 通过 Web `pl:plan-cert:list` 匹配既有角色,补齐移动端根及运输管理父级绑定,不改 Web 菜单、不自动扩大上传或齐备权限。 - 当前 SQL 目录没有可直接复用的运输计划移动菜单脚本。新增脚本前须只读核对已有运输管理父菜单 ID、路径和租户归属,不猜测父级 ID,也不新增第二个同名运输根菜单。 - 使用 `MpWebviewShell`、`MpBottomSheet` 和本模块样式。结构 class 对齐 Demo 的 `mp-wv-header`、`status-tabs/filter-tag`、`filter-bar/filter-trig`、`expense-card`、`detail-tabs`、`att-grid/att-img` 语义;详情禁止 `ticket-*`。品牌绿 `#0a9f6d`,不得出现 Fresh Mint `#10b981`,375/414px 验证,交互触达至少 44px,状态使用浅底语义标签,弹层无背景模糊。 - 本模块筛选和上传 Sheet 底栏操作水平居中、按钮间距 12px;按钮宽度约 96px、不伸满、不粘连,视觉字号 14px,实际触达高度不少于 44px。该规则只作用于本模块,不能修改共享 Sheet 导致其他界面变化。 - 首次新增本地工作台入口需要发布含入口配置的小程序包及 H5,并执行本模块菜单 SQL;不能误用“以后只更新 H5 无需提审”的说明代替首次发布步骤。 ## 6. 验证和交付 - 先写失败测试覆盖五个 Tab 查询、默认状态、冲突筛选、操作限制、批量目标、证书载荷及上传中保护,再实现。 - 浏览器模拟 API 验证列表、搜索、筛选、全部 Tab、分页、详情、上传增删预览、保存、单条/批量齐备与取消、无权限和接口失败。模拟测试不向真实业务数据库写入。 - 375px 和 414px 截图检查列表、详情、附件和底部操作栏,不以编译通过替代界面验收。 - 运行新增测试、目标文件 lint、构建及类型检查;把已有类型错误与新增错误区分。核对 Web 原文件内容没有因本次迁移变化。 - 更新模块接入文档、SQL、交付和问题记录,按仓库要求更新相关知识图谱。真机和部署未实际执行时必须明确标注,不能宣称通过。 ## 7. 当前状态 用户已明确给出第三次校准要求:独立详情、删除详情顶部特殊区、列表横向无额外间距、统一按钮/字号、Sheet 底栏按钮居中适宽、列表顶部对齐 OpenSpec。当前分支为 `V1.5`,在现有工作区实施并保留前序任务及用户的未提交改动。数据库写入与发布不属于此次开发默认授权,另行确认。