修改过时文档，优化文档内容

2026-03-17 11:06:26 +08:00
parent dac730474b
commit f33efe6ec8
45 changed files with 162 additions and 236 deletions
--- a/pages/mall/delivery/doc/old(弃用)/delivery.md
+++ b/pages/mall/delivery/doc/old(弃用)/delivery.md
@@ -0,0 +1,170 @@
+# Delivery 模块 — 总体架构
+
+## 概要
+本文件给出配送（delivery）模块的总体架构说明，覆盖前端视图组件、后端数据表与 API 交互、关键业务流、并发/事务策略与建议改进方向，便于开发者与运维快速理解与修改。
+
+## 架构概览
+- 前端（Uni-app / .uvue 组件）：负责页面渲染、用户交互与轻量校验，主要文件位于 `pages/mall/delivery/`。
+- 后端（Supabase/Postgres + RPC）：负责数据持久化、原子操作、权限校验与并发控制。建议将关键并发操作（例如“接单”）放在后端 RPC/函数中执行。
+- 数据层（Postgres 表）：主表包括 `ml_orders`、`ml_order_items`、`ml_shops`、`ml_delivery_tasks`、`ml_delivery_drivers` 等。
+- 通信：前端通过 Supabase 客户端或后端 HTTP RPC 调用进行读写；推荐对写操作使用后端受限 RPC，减小竞态风险。
+
+## 前端组件映射（关键文件）
+- 入口与导航：`pages/mall/delivery/index.uvue`（模块入口）
+- 任务列表 / 历史：`pages/mall/delivery/tasks.uvue`、`pages/mall/delivery/order-history.uvue`
+- 任务详情 / 订单详情：`pages/mall/delivery/task-detail.uvue`、`pages/mall/delivery/order-detail.uvue`
+- 配送员信息：`pages/mall/delivery/profile.uvue` / `profile-edit.uvue`
+- 收益 / 统计：`pages/mall/delivery/earnings.uvue`
+- 车辆管理：`pages/mall/delivery/vehicle.uvue`、`vehicle-add.uvue`、`vehicle-edit.uvue`
+- 帮助/反馈/测试：`help-center.uvue`、`feedback.uvue`、`test.uvue`
+
+对应文档（开发说明）位于 `pages/mall/delivery/doc/`，每个视图对应一个 `.md` 说明文件（例如 `order-detail.md`、`tasks.md` 等）。
+
+## 数据模型（常用字段 / 表）
+- `ml_orders`: id, cid, order_no, user_id, merchant_id, order_status / status, total_amount, shipping_fee, paid_amount, shipping_address, remark, created_at
+- `ml_order_items`: id, order_id, product_id, product_name, quantity, price, image_url
+- `ml_shops`: id, merchant_id, shop_name, contact_name, contact_phone, address
+- `ml_delivery_tasks`: id, order_id, driver_id, status, distance, estimated_time, pickup_time, delivered_time, created_at
+- `ml_delivery_drivers`: id, user_id, vehicle_id, status
+
+字段命名在代码中可能存在兼容写法（如 `order_status` vs `status`、`shipping_fee` vs `delivery_fee`），建议在前端统一使用一个转换函数 `normalizeOrderRow(row)` 做映射。
+
+## 关键业务流（简要）
+- 接单（Accept）
+  - 不要在前端直接做盲写；推荐后端 RPC 原子化操作：
+    - SQL 示例（后端执行）：
+      ```sql
+      UPDATE ml_delivery_tasks
+      SET driver_id = $1, status = 2
+      WHERE order_id = $2 AND (driver_id IS NULL OR driver_id = '')
+      RETURNING *;
+      ```
+    - 前端调用 RPC：根据返回行数判断是否接单成功；若返回 0 行则提示“已被其他配送员接单”。
+
+- 确认取货 / 确认送达
+  - 后端更新 `ml_delivery_tasks` 的时间戳字段（`pickup_time` / `delivered_time`）并更新 `ml_orders.order_status`，前端在成功回调后同步 UI 状态并展示时间戳。
+
+- 读取详情页（order-detail）
+  - 并行查询 `ml_orders`, `ml_order_items`, `ml_shops`, `ml_delivery_tasks` 并合并结果，务必对空值做兼容处理（地址可能是字符串或对象）。
+
+## 并发与事务策略
+- 将所有会改变接单归属或状态的操作放在数据库事务或后端函数中执行，前端仅调用并根据返回结果更新 UI。
+- 使用行级条件（`WHERE driver_id IS NULL` / `WHERE order_status = expected`）与 `RETURNING` 判断是否成功，避免乐观锁冲突。
+- 在前端增加防重（loading 标志位、按钮禁用）和超时重试策略，并记录幂等请求 ID（如必要）。
+
+## 错误处理与监控
+- 前端对所有写操作展示用户友好错误（网络错误 / 已被接单 / 权限不足）。
+- 后端应记录关键操作日志（接单、拒单、确认取货/送达），并导出指标（接单失败率、并发冲突数）。
+
+## 权限与安全
+- 接单/确认类操作必须在后端校验当前用户是合法配送员（基于 `ml_delivery_drivers.user_id`），并确保 RPC 仅对认证用户开放。
+
+## 开发与测试建议
+- 在 `pages/mall/delivery/test/create_test_orders.sql` 中准备自动化测试数据，用于本地/CI 环境的集成测试。
+- 在前端加入单元测试/集成测试用例，模拟并发接单场景，验证后端 RPC 行为。
+
+## 建议改进（优先级）
+- 高：把接单逻辑迁移为后端 RPC，前端只调用并根据返回结果更新 UI。
+- 高：在所有变更接口返回受影响行数与最新状态，便于前端做幂等与回退。
+- 中：统一并导出状态常量（例如 `ORDER_STATUS`）供前端与文档引用，避免魔法数字。
+- 中：为详情页加入字段规范示例（在 `order-detail.md` 中补充），并同步到 API 文档。
+
+---
+
+（如需将 `order-detail.uvue` 的接单逻辑改为调用 RPC 并添加 loading 状态，我可以继续提交补丁。）
+# Delivery 模块文档
+
+本文档为 `pages/mall/delivery` 模块的开发与运维手册，已按与 `analytics` 模块相近的结构补充：概览、文件清单、技术特性、页面架构、实现要点、部署与测试建议、下一步计划与代码质量指引。
+
+## 概览
+配送端（Delivery）面向配送员，覆盖：司机状态管理、任务与订单流转、配送记录/历史、收入统计、个人资料与车辆管理、帮助与反馈。页面既包含前端聚合逻辑，也与后端（Supabase / RPC）交互实现关键业务。
+
+## 文件清单（快速索引）
+
+- [about.uvue](pages/mall/delivery/about.uvue) — 关于我们（静态）
+- [index.uvue](pages/mall/delivery/index.uvue) — 配送端首页（司机信息、今日统计、可接订单）
+- [tasks.uvue](pages/mall/delivery/tasks.uvue) — 任务列表（筛选、分页）
+- [task-detail.uvue](pages/mall/delivery/task-detail.uvue) — 任务详情（联系、取货、完成）
+- [order-detail.uvue](pages/mall/delivery/order-detail.uvue) — 订单详情（多表聚合、状态流转）
+- [order-history.uvue](pages/mall/delivery/order-history.uvue) — 历史订单（本地合并刚完成订单显示）
+- [earnings.uvue](pages/mall/delivery/earnings.uvue) — 收入明细（按 `order_no` 聚合）
+- [profile.uvue](pages/mall/delivery/profile.uvue) — 个人中心与入口
+- [profile-edit.uvue](pages/mall/delivery/profile-edit.uvue) — 编辑资料（头像、服务区域）
+- [vehicle.uvue](pages/mall/delivery/vehicle.uvue) — 车辆管理（列表/新增/编辑）
+- [vehicle-add.uvue](pages/mall/delivery/vehicle-add.uvue) — 添加车辆表单
+- [vehicle-edit.uvue](pages/mall/delivery/vehicle-edit.uvue) — 编辑车辆
+- [feedback.uvue](pages/mall/delivery/feedback.uvue) — 意见反馈（图片、关联订单）
+- [help-center.uvue](pages/mall/delivery/help-center.uvue) — 帮助中心/FAQ
+- [ratings.uvue](pages/mall/delivery/ratings.uvue) — 评价记录（分页/筛选）
+- [settings.uvue](pages/mall/delivery/settings.uvue) — 设置页
+- [test.uvue](pages/mall/delivery/test.uvue) — Supabase 连接/权限诊断
+
+## 技术特性
+
+- UTS / Uni-app 页面实现（`.uvue`），兼容 UTS Android 规范（类型定义、UTSJSONObject 使用等）。
+- 使用 `supa`（项目内 Supabase 封装）进行数据读取、RPC 调用与认证。示例：`supa.from('ml_delivery_tasks')`、`supa.rpc('rpc_analytics_top_products', params)`（analytics 模式的参考）。
+- 本模块使用本地存储做页面间临时数据传递（`uni.setStorageSync`），并在部分页面（如 `vehicle`、`order-history`）合并本地临时项以支持无后端或原型场景。
+- 对接建议：关键写操作（接单/状态变更）必须依赖后端原子性保护（事务或 WHERE driver_id IS NULL 的更新语句）。
+
+## 页面架构与实现要点
+
+- 首页（`index.uvue`）：聚合 `driver`、`todayStats`、`currentTask` 与 `availableOrders`；包含 `_transformTask` 用于兼容多种地址/联系人字段格式。
+- 订单详情（`order-detail.uvue`）：按 id 格式选择查询字段（`id`/`cid`/`order_no`），并联查 `ml_order_items`, `ml_shops`, `ml_delivery_tasks`；提供接单/拒单/确认取货/确认送达等操作。
+- 任务流（`tasks` / `task-detail`）：任务筛选（待接单/进行中/已完成）与详情页的状态变更操作；完成时应记录时间戳与凭证以便对账。
+- 收入（`earnings`）：前端按 `order_no` 聚合并补齐来源类型，建议后端提供已聚合接口以提升性能与准确性。
+- 个人/车辆页：使用图片上传、表单校验与本地缓存作为临时方案；生产应对接车辆管理 API 并保存到服务端。
+
+## 典型 DB / RPC 示例
+
+Supabase (supa) 示例：
+```
+// 查询司机信息
+await supa.from('ml_delivery_drivers').select('*').eq('user_id', userId).limit(1).execute()
+
+// 查询可接任务（示例）
+await supa.from('ml_delivery_tasks').select('*').is('driver_id', null).eq('status', 1).order('created_at', { ascending: false }).range(offset, offset+size-1).execute()
+
+// 接单（需后端并发保护）
+await supa.from('ml_delivery_tasks').update({ driver_id: driverId, status: 2 }).eq('id', taskId).eq('driver_id', null).execute()
+```
+
+## 样式与 UI 设计
+
+- 推荐采用与 `analytics` 模块相同的卡片式布局与 KPI 卡片样式（便于统一风格）；关键组件（任务卡、订单明细卡、统计卡）应抽象成可复用组件以减少重复代码。
+
+## 部署与配置
+
+- 环境变量：确认 `SUPA_URL`/`SUPA_KEY` 在 `ak/config.uts` 或环境配置中正确配置。
+- 本地测试：使用 `pages/mall/delivery/test.uvue` 验证 Supabase 连接与权限（避免在仓库暴露明文 key）。
+
+## 测试建议
+
+- 功能测试：接单并发测试、状态流转（取货/送达）、图片上传与表单校验、分页与历史数据展示。
+- 兼容性：Android/不同屏幕尺寸测试（UTS Android 兼容性须验证）。
+- 性能：大量任务/历史记录分页测试，收入聚合在后端做性能验证。
+
+## 下一步计划
+
+1. 抽取并复用 UI 组件（任务卡、订单详情卡、统计 KPI 卡）。
+2. 将前端聚合逻辑（如 `earnings`）迁移或补充后端聚合接口以提升性能。
+3. 用后端事务或乐观锁增强接单并发保护，并在前端实现失败回退提示。
+4. 添加自动化测试用例覆盖关键流程（接单/确认/拒单/结算）。
+
+---
+Generated on: 2026-02-02
+## 快速参考（已合并页摘要）
+
+- `about.uvue`：关于我们（静态信息，运营可从 CMS 拉取版本/更新日志）。
+- `help-center.uvue`：帮助中心 / FAQ（本地数组或后端搜索，支持分类与全文检索）。
+- `settings.uvue`：设置页（通知、语言、隐私、登出），存储建议使用 `uni.setStorageSync` + 后端同步。
+- `feedback.uvue`：意见反馈（文本 + 图片 + 关联订单），图片需先上传再提交 URL。
+- `ratings.uvue`：评价记录列表（分页筛选，可能需要后端审核/屏蔽）。
+- `profile.uvue` / `profile-edit.uvue`：个人中心与编辑（头像上传、服务区域、车辆信息），建议在保存后同步刷新缓存。
+- `vehicle*.uvue`：车辆管理相关（列表/新增/编辑），当前以本地存储为演示，生产应对接 REST 接口并做权限校验。
+
+（已把上述 per-page md 移动到 `pages/mall/delivery/doc/archive/`，保留历史版本以便追溯。）
+
+---
+Generated on: 2026-02-02
+---
+Generated on: 2026-02-02