sqxp/docs/小程序-配送员端UI改造指南.md

小程序配送员端 UI 改造指南（基于 Demo 强约束）

1. 目标与范围

本指南用于指导 miniprogram 配送员端进行一次完整、可验收、可追踪的 UI 改造。
改造原则：视觉样式按 Demo 执行、业务功能保持不变。

• 视觉基准（唯一）：mobile-ui/sanqiang-deliverer-ui-demo.html
• 功能基准（保持）：现有配送员端接口、状态流转、操作入口
• 首要目标：首页必须按 Demo 的布局与配色 1:1 落地

---

2. 总体改造原则

2.1 不受现有 UI 影响

改造时禁止“参考现有页面微调”，必须先从 Demo 提炼设计语言，再反向覆盖现有页面。

2.2 首页强约束

pages/deliverer/home/home 必须完全遵循 Demo 的信息架构、视觉层级、区块顺序与交互节奏。

2.3 功能零损失

• 不改接口契约（请求参数、响应字段）
• 不改业务流程（抢单、取货、送达、拨号、退出登录）
• 不改权限与路由保护逻辑（登录态、角色态）
• 不改功能集合与入口：现有页面已有功能必须原样保留，禁止新增、删减、替换功能项
• 首页“常用功能”菜单必须严格沿用当前代码中的功能定义与跳转，不允许按设计稿主观扩展

2.3.1 首页功能菜单硬约束（新增）

• 首页 UI 可改样式（布局、颜色、图标、卡片形态），但不可改功能内容
• “常用功能”中的菜单项数量、名称、点击行为、跳转目标必须与改造前代码一致
• 若设计稿与现有功能不一致，以现有功能为准，设计仅做视觉适配
• 若确需调整功能（新增/删除/替换/改名/改跳转），必须先经产品确认并单独立项，不属于本次 UI 改造范围

2.4 先基建后页面

按“Token -> 公共组件 -> 页面迁移 -> 联调验收”顺序执行，避免重复返工。

2.5 卡片素材可替换（明确许可）

• 配送员端界面卡片中的 icon 与图片素材可按设计图及统一视觉方案替换
• 不要求复用现有素材
• 替换后必须满足：语义清晰、风格统一、交互可识别

---

3. Demo 设计要点提炼（配送员端）

基于 mobile-ui/sanqiang-deliverer-ui-demo.html 提炼以下不可偏离的样式点。

3.1 颜色与语义

• 主色：#0a9f6d
• 深主色：#087f57
• 页面背景：#f3f7f5
• 卡片底色：#ffffff
• 边框色：#d9e9e1
• 警示色：#cf8a19
• 成功色：#189b65

状态标签语义：

• pending：暖黄浅底 + 警示文案
• delivering：浅绿底 + 成功文案
• completed：绿色浅底 + 深绿文案（已完成/已送达/已完结）
• cancelled：灰色浅底 + 灰色文案（已取消/作废）

3.2 首页布局骨架（必须一致）

1. 顶部渐变头部：标题、退出登录、配送员身份信息
   
2. 头部下方悬浮统计卡：三列数字统计
   
3. 任务状态 Tab：待取货 / 配送中 / 已完成
   
4. 功能宫格：抢单大厅 / 我的任务 / 异常上报 / 联系客服（位于任务区上方）
   
5. 当前任务列表：卡片式任务流
   

3.3 任务卡片结构（必须一致）

• 第一行：任务号 + 状态标签
• 中段：取货信息块（虚线框、弱底色）
• 中段：配送信息块（虚线框、弱底色）
• 底部：件数与时效 + 主操作按钮

3.4 视觉细节

• 头部：大圆角渐变、轻阴影
• 卡片：中圆角、细边框、轻阴影
• 按钮：胶囊圆角，主按钮实色
• 文本：主信息与辅助信息层级分明，避免同层级抢视觉

---

4. 现有配送员端页面清单（改造对象）

主页面（miniprogram/src/pages/deliverer）：

• home/home.vue：配送员工作台首页
• task/task.vue：配送任务列表
• task/detail/detail.vue：配送任务详情
• snatch/snatch.vue：抢单大厅
• profile/profile.vue：个人中心

关联页面（配送员入口可能跳转）：

• pages/supplier/settings/avatar
• pages/supplier/settings/password

---

5. 分批改造计划（推荐执行顺序）

第 0 批：样式基建批（必须先做）

目标：建立统一设计系统，防止页面各自实现。

• 建立配送员端 Token（颜色、圆角、间距、阴影、字号）
• 建立状态映射表（待取货/配送中/已完成/取消）
• 抽离公共组件（头部、统计、Tab、任务卡、功能宫格）
• 清理页面硬编码色值（魔法值）

交付物：

• deliverer 主题 token 文件
• 公共 UI 组件与样式变量文档

第 1 批：首页强约束批（最高优先级）

目标：home/home.vue 视觉与布局完全对齐 Demo，功能保持不变。

• 头部、统计卡、Tab、功能宫格、任务区顺序严格对齐
• 任务卡结构改为 Demo 同构
• 保留并验证：任务拉取、Tab 切换、拨号、详情跳转、退出登录

验收门槛：

• 首页逐区块对比 Demo，无结构偏差
• 关键动作全部可用，无接口回归

第 2 批：任务主链路批

目标：任务列表与详情页面风格统一，形成配送主流程闭环。

• task/task.vue：统一列表、标签、卡片、空态/加载态
• task/detail/detail.vue：统一信息分组、按钮态、凭证上传区域视觉
• 确保状态流转与接口行为不变

第 3 批：次核心页面批

目标：补齐体验一致性，避免局部旧风格残留。

• snatch/snatch.vue：抢单卡片、按钮、空态对齐主题
• profile/profile.vue：个人中心头图、菜单、退出按钮对齐主题

第 4 批：依赖跳转页面批

目标：跨目录页面视觉统一，避免“点进去风格断层”。

• 头像设置页、密码修改页进行主题化覆盖

第 5 批：收口与文档批

目标：改造“彻底完成”。

• 旧样式清理（废弃 class/重复样式/无主变量）
• 全流程回归与边界态巡检
• 回写规范到 docs/miniprogram-ui-spec-sanqiang.md
• 回写改造记录到 docs/小程序-配送员端UI改造指南.md（新增“变更记录”小节，至少包含改造页面、视觉变更点、功能保持说明、遗留项）

---

6. 验收标准（确保改造完善彻底）

6.1 视觉验收

• 首页信息架构与 Demo 一致（顺序、层级、区块形态）
• 颜色、间距、圆角、阴影与 Demo 语义一致
• 关键页面不出现旧风格卡片或按钮

6.2 交互验收

• 点击态、禁用态、加载态、空态、错误态完整覆盖
• 拨号、跳转、Tab 切换、提交按钮反馈完整

6.3 业务验收

• 主流程可走通：待取货 -> 配送中 -> 已完成
• 抢单流程可走通：列表加载 -> 抢单成功/失败提示
• 详情流程可走通：取货确认、送达确认、凭证上传与预览
• 首页常用功能验收：菜单项与改造前保持一致（数量、名称、行为、跳转一致）

6.4 性能与稳定性验收

• 首页首屏渲染稳定
• 列表滚动不卡顿
• 网络异常时有可读反馈，不白屏

---

7. 防漏改执行机制

• 建立“页面改造看板”：待改造 / 改造中 / 待验收 / 已完成
• 建立“组件映射表”：旧组件 -> 新组件（完成状态）
• 建立“样式清理清单”：每页完成即清理遗留样式
• 每批完成做真机巡检，不仅依赖模拟器

---

8. 实施注意事项

• 首页是本次改造的视觉锚点，必须先完成并通过验收
• 业务接口与字段只做读取适配，不做契约变更
• 优先改模板结构与样式，不轻易触碰业务逻辑
• 所有新增样式优先来自 Token，禁止散落硬编码

8.1 本轮首页改造注意点（2026-04-17）

• 常用功能区位置：必须放在“待取货/配送中/今日完成”统计卡下方
• 常用功能视觉：功能卡片去掉底色块，仅保留图标 + 文案；图标可替换为语义更清晰的 icon
• 过滤区位置：待取货/配送中/已完成 的 Tab 必须放在“配送任务”标题上方
• 检索增强：在过滤 Tab 上方增加检索输入框，支持按单号、人员信息进行快速模糊检索
• 号码呼出图标：任务卡内电话号码后的呼出 icon 更换为更简洁美观样式，且不使用背景色底
• 任务卡布局：信息摆放参考 mobile-ui/sanqiang-deliverer-ui-demo.html 的卡片结构（任务号/状态、取货信息、配送信息、底部操作）
• 卡片高度控制：在保证信息可读前提下尽量压缩卡片高度，减少冗余留白，提高单屏可视任务数
  • 任务卡同构要求：优先采用“line1(任务号+状态) -> 两块 blk 信息区 -> foot(件数+主按钮)”结构；如需额外字段（如订单号/备货进度），放入 meta 行，保持弱信息层级
  • 反外层滚动：首页需避免出现整页纵向滚动条，采用“外层 100vh + overflow:hidden，任务列表内部 scroll-view 滚动”的结构

8.2 本轮验收补充项（2026-04-17）

• 首页区块顺序验收：统计卡 -> 常用功能 -> 检索框 -> 状态 Tab -> 配送任务列表
• 常用功能验收：功能项与行为保持不变，仅允许图标与样式变化
• 检索验收：支持关键字模糊匹配，输入后列表实时或触发式过滤；空关键字恢复全量
• 任务卡验收：与 Demo 信息结构一致，且卡片高度较改造前明显收敛
• 呼出图标验收：无背景底色、风格统一、点击区域可识别（触控友好）
• 顶部品牌验收：首页头部需展示“logo + 叁强鲜配”品牌信息，并在头部区域水平居中
  • 滚动验收：首页不出现整页纵向滚动条；任务列表区域可独立滚动

---

9. 建议里程碑

• M1（第 0-1 批）：首页 Demo 同构完成并验收通过
• M2（第 2 批）：任务链路页面统一完成，主流程回归通过
• M3（第 3-4 批）：全配送员端视觉统一，跨页跳转无断层
• M4（第 5 批）：清理收口、规范回写、形成长期可维护基线

---

10. 变更记录（模板）

说明：配送员端每次 UI 改造完成后，必须新增一条记录。建议按时间倒序维护（最新在上）。

[2026-04-17] 第 1 批-首页细化调整（布局与检索）

• 改造页面：
  • miniprogram/src/pages/deliverer/home/home.vue
• 视觉变更点：
  • 常用功能区下移至统计卡下方，并去除功能卡背景底色（仅保留 icon + 文案）
  • 配送任务 区新增检索输入框，并将状态 Tab 放到配送任务列表上方
  • 任务卡信息布局向 Demo 靠拢并做紧凑化，减少纵向留白
  • 电话呼出 icon 改为无背景底色样式
  • 头部新增品牌条（logo + 叁强鲜配），并做水平居中展示
  • 修复头部“双 logo 靠左”问题：品牌标题居中，默认头像不再展示站点 logo，改为中性字母头像
  • 根据视觉反馈移除头部品牌条（叁强 logo + 叁强鲜配），恢复“配送员工作台”左对齐
  • 首页新增背景水印层：叁强 logo + “叁强鲜配”文字（低透明度、不可点击、不影响业务交互）
  • 调整水印层级与透明度，确保 H5 首页可见（保持不可点击与低干扰）
  • 水印形态升级为“平铺网格型”：覆盖页面约 70% 区域，低透明重复呈现 logo + 品牌文字
  • 根据视觉反馈移除首页背景水印，恢复简洁背景方案
  • 首页标题文案调整为“叁强鲜配 配送员工作台”
  • 水印方案调整为“仅顶部背景水印”：只在头部渐变区放置单枚低透明 logo（不平铺、不可点击）
  • 常用功能图标替换为语义化彩色 icon（仅替换视觉素材，不改变功能项与跳转）
  • 常用功能中的“设置头像/修改密码”图标均已替换为新语义图标，保持功能不变
  • 多色 icon 实现约定：若 SVG 为单色（如 fill=白色），采用“彩色底（渐变）+ 白色 SVG”方案实现彩色入口，避免小程序端 SVG 上色兼容问题
  • 配送任务列表页（pages/deliverer/task/task）已对齐首页风格：顶部搜索+状态Tab、任务卡同构、状态Tag分色、仅列表内部滚动
  • 配送任务详情页（pages/deliverer/task/detail/detail）已对齐首页风格：hero 改为薄荷绿渐变、拨号按钮与关键数值色统一为薄荷绿、状态Tag按语义分色
  • 抢单大厅（pages/deliverer/snatch/snatch）已对齐首页风格：增加顶部薄荷绿 header（含轻水印）、卡片与按钮统一为薄荷绿体系、文案与间距对齐首页节奏
  • 个人中心（pages/deliverer/profile/profile）已对齐首页风格：用户信息卡改为薄荷绿 header（含轻水印）、菜单与退出按钮统一为“白底描边+圆角+轻阴影/留白”的卡片体系
  • 关联设置页（pages/supplier/settings/avatar、pages/supplier/settings/password）已做薄荷绿体系适配：背景/卡片/输入/按钮统一对齐首页（功能与流程不变）
  • 首页任务区微调：已移除“待取货/配送中/已完成”Tab 外框；空态“暂无配送任务”改为占满任务区剩余高度并增加空态 icon，提升无数据场景观感
  • 详情页（pages/deliverer/task/detail/detail）补充统一：电话号码右侧拨号 icon 改为首页同款（透明底 icon-only）；底部“配送明细”重绘为薄荷绿卡片风格（标题头、商品行、总计条统一）
  • 详情页“配送明细”二次美化：参考 mobile-ui/sanqiang-client-cart-ui-demo.html 的购物车风格，增加头部标签、商品行分层（名称+标签+规格+数量胶囊）、已送达提示胶囊，提升信息可读性
• 功能保持说明：
  • 常用功能项与跳转保持不变：设置头像、修改密码、联系客服
  • 新增检索仅对当前已加载任务做前端模糊过滤，不改接口契约与路由
• 联调与验收结果：
  • 代码级改造完成，待真机/模拟器验证视觉与检索体验
• 遗留问题：
  • IDE Vetur 的 @/ 别名提示仍存在（环境类提示）
• 关联提交（可选）：
  • Commit: <pending>
  • PR: <pending>

[2026-04-17] 第 1 批-首页强约束批（按功能不变约束重做）

• 改造页面：
  • miniprogram/src/pages/deliverer/home/home.vue
• 视觉变更点：
  • 首页整体视觉对齐 Demo：头部薄荷绿渐变、悬浮统计卡、状态 Tab、卡片边框与弱底色信息块
  • 将状态 Tab 前置到常用功能区之前，贴合 Demo 首页信息架构
  • 任务卡状态标签调整为语义色（待处理=暖黄、进行中=浅绿）
  • 联系电话按钮色和主操作按钮色统一为薄荷绿体系
• 功能保持说明：
  • 严格保留既有“常用功能”菜单项与跳转：设置头像、修改密码、联系客服
  • 未新增、删减或替换任何功能入口
  • 任务列表、分页、Tab 切换、详情跳转、拨号、退出登录逻辑保持不变
• 联调与验收结果：
  • 代码静态检查通过；需在真机/模拟器做视觉与交互回归确认
• 遗留问题：
  • IDE Vetur 的 @/ 别名提示仍存在（环境类提示）
• 关联提交（可选）：
  • Commit: <pending>
  • PR: <pending>

[2026-04-17] 第 1 批-首页强约束批（首轮落地）

• 改造页面：
  • miniprogram/src/pages/deliverer/home/home.vue
• 视觉变更点：
  • 首页区块顺序调整为 Demo 同构：头部 -> 统计卡 -> Tab -> 功能宫格 -> 当前任务
  • 首页主视觉改为 Demo 薄荷绿体系（头部渐变、卡片边框、任务状态标签语义）
  • 功能宫格改为 4 宫格，并替换卡片 icon 资源（不复用旧素材）
  • 任务卡改为 Demo 风格：信息块虚线框 + 弱底色 + 主操作胶囊按钮
• 功能保持说明：
  • 保持原有任务列表拉取、分页加载、Tab 切换、查看详情、拨号、退出登录逻辑不变
  • 新增“抢单大厅/我的任务”快捷跳转；“异常上报”暂为占位提示
• 联调与验收结果：
  • 主流程：本地静态检查通过，待真机/模拟器联调确认
  • 空态/加载态/无更多：页面已覆盖并保留
• 遗留问题：
  • 异常上报 页面未落地，当前为占位提示
  • IDE Vetur 对 @/ 别名报模块提示（属于项目环境类提示，非本次改造引入）
• 关联提交（可选）：
  • Commit: <pending>
  • PR: <pending>

[YYYY-MM-DD] 改造批次名称（示例：第 1 批-首页强约束批）

• 改造页面：
  • miniprogram/src/pages/deliverer/home/home.vue
  • miniprogram/src/pages/deliverer/task/task.vue
• 视觉变更点：
  • 首页头部/统计卡/Tab/宫格/任务卡已按 mobile-ui/sanqiang-deliverer-ui-demo.html 同构改造
  • 卡片 icon 与图片素材按统一视觉方案替换（不复用旧素材）
• 功能保持说明：
  • 保持现有接口与字段不变
  • 保持原有业务流程不变（抢单、取货、送达、拨号、退出登录）
• 联调与验收结果：
  • 主流程：通过 / 未通过（填写具体问题）
  • 空态/加载态/错误态：通过 / 未通过（填写具体问题）
• 遗留问题：
  • 无 / 有（列出具体待办）
• 关联提交（可选）：
  • Commit: <hash>
  • PR: <url>