小程序危化品证上传 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 顺序：

未上传证书（默认）。
全部。
入库单。
出库单。
直销单。

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 和“筛选/刷新/重置”工具条。三栏固定为：

日期：全部日期、今天、明天、昨天、本周，可直接下拉选择。
齐备状态：全部、未齐备、已齐备，可直接下拉选择；与默认“未上传证书”Tab 冲突时 Tab 语义优先。
更多：打开底部筛选 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，在现有工作区实施并保留前序任务及用户的未提交改动。数据库写入与发布不属于此次开发默认授权，另行确认。

2026-10-17-mp-webview-pl-plan-cert-design.md 13 KB Постоянная ссылка История Исходник