# 页面级原型与字段说明

## 1. 通用页面规范

### 1.1 通用布局

| 端 | 布局 | 说明 |
| --- | --- | --- |
| Vue WEB 业务员端 | 顶部导航 + 左侧菜单 + 内容区 | 菜单按 `menus` 和 `permissions` 动态渲染 |
| Vue WEB 管理后台 | 顶部用户区 + 左侧多级菜单 + 内容区 | 适合表格、表单、配置和报表页面 |
| 微信原生小程序管理层端 | TabBar 或首页卡片入口 + 列表/详情页 | 重点支持审批、取消审批、下发确认、任务分配 |
| 微信原生小程序司机端 | TabBar：任务、我的 | 司机只处理本人任务 |

### 1.2 通用状态

| 状态 | 页面表现 |
| --- | --- |
| loading | 表格骨架屏、按钮 loading、防重复提交 |
| empty | 展示空状态文案和可选操作按钮 |
| error | 展示错误提示，保留重试按钮 |
| no_permission | 展示无权限页面，隐藏无权限按钮 |
| token_expired | 清理本地登录态并跳转登录页 |

### 1.3 通用按钮权限

| 按钮类型 | 控制方式 |
| --- | --- |
| 页面入口 | 由菜单权限控制 |
| 操作按钮 | 由按钮权限 + 当前业务状态共同控制 |
| 财务字段展示 | 以后端是否返回字段为准，前端不做越权兜底显示 |

## 2. Vue WEB 业务员端

### 2.1 登录页

| 项 | 内容 |
| --- | --- |
| 路由 | `/login` |
| API | `POST /api/auth/login` |
| 字段 | `username`、`password`、`role_type=salesman` |
| 按钮 | 登录 |
| 校验 | 账号必填、密码必填 |
| 成功 | 保存 token、用户信息、菜单权限，跳转 `/orders` |
| 失败 | 展示接口 `message` |

### 2.2 我的订单列表

| 项 | 内容 |
| --- | --- |
| 路由 | `/orders` |
| API | `GET /api/orders` |
| 筛选项 | 订单状态、客户姓名、客户手机号、订单来源、开始时间、结束时间 |
| 表格字段 | 订单编号、客户姓名、客户手机号脱敏、订单状态、订单来源、销售总额、创建时间、提交时间 |
| 隐藏字段 | 成本、利润、利润率、回扣，除后端允许返回外不展示 |
| 按钮 | 新建订单、查看、编辑草稿、提交审核、取消 |
| 权限状态 | 只展示当前业务员订单 |
| 分页 | `page_no`、`page_size` |

#### 按钮状态

| 按钮 | 可见条件 | 禁用条件 |
| --- | --- | --- |
| 新建订单 | 有 `order:create` 权限 | 无 |
| 编辑草稿 | `order_status=draft/rejected` 且本人订单 | 已取消、审核中、履约中 |
| 提交审核 | `order_status=draft/rejected` 且必填完整 | 明细为空、金额非法 |
| 取消 | `order_status` 非 `canceled/settled` | 已存在 `cancel_pending` |

### 2.3 订单录入/编辑页

| 项 | 内容 |
| --- | --- |
| 路由 | `/orders/create`、`/orders/:id/edit` |
| API | `POST /api/orders`、后续可扩展 `PUT /api/orders/{order_id}` |
| 页面分区 | 客户信息、订单信息、明细信息、费用信息、备注 |

#### 客户信息

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| customer_name | 输入框 | 是 | 客户姓名 |
| customer_mobile | 输入框 | 是 | 手机号 |
| customer_address | 输入框 | 否 | 客户地址 |
| customer_id | 隐藏字段 | 否 | 匹配到老客户时保存 |

#### 订单信息

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| order_source | 下拉/输入 | 否 | 订单来源标签 |
| delivery_type | 下拉 | 否 | 发货类型 |
| factory_id | 选择器 | 否 | 工厂 |
| commission_amount | 金额输入 | 否 | 订单固定提成 |
| remark | 多行文本 | 否 | 备注 |

#### 明细信息

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| product_id | 产品选择器 | 否 | 选产品后带出快照字段 |
| product_name | 输入框 | 是 | 产品名称 |
| specification | 输入框 | 是 | 规格 |
| unit | 输入框 | 是 | 单位 |
| quantity | 数字 | 是 | 数量，必须大于 0 |
| sale_price | 金额 | 是 | 销售单价 |
| cost_price | 金额 | 是 | 成本单价 |
| rebate_amount | 金额 | 否 | 行回扣 |
| freight_amount | 金额 | 否 | 行运费 |
| tax_amount | 金额 | 否 | 行税费 |
| other_fee_amount | 金额 | 否 | 其他费用 |
| remark | 输入框 | 否 | 行备注 |

#### 费用汇总

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| sale_price_total | 只读 | 明细销售金额汇总 |
| cost_price_total | 只读 | 明细成本汇总 |
| rebate_total | 可编辑/自动汇总 | 订单回扣总额 |
| freight_total | 可编辑/自动汇总 | 订单运费总额 |
| tax_total | 可编辑/自动汇总 | 订单税费总额 |
| other_fee_total | 可编辑/自动汇总 | 其他费用总额 |
| profit_total | 只读 | 后端最终计算为准 |
| profit_rate | 只读 | 后端最终计算为准 |

#### 页面按钮

| 按钮 | 行为 |
| --- | --- |
| 保存草稿 | 调用创建/更新接口，状态为 `draft` |
| 保存并提交 | 先保存，再调用提交审核 |
| 新增明细 | 增加一行明细 |
| 删除明细 | 删除当前行，至少保留一行 |
| 选择产品 | 弹窗选择产品 |

### 2.4 订单详情页

| 项 | 内容 |
| --- | --- |
| 路由 | `/orders/:id` |
| API | `GET /api/orders/{order_id}` |
| 分区 | 基本信息、明细、费用汇总、审批记录、物流节点、提醒/通知、附件 |
| 按钮 | 提交审核、取消订单、复制下发文本、返回 |

#### 业务员可见字段

| 类型 | 字段 |
| --- | --- |
| 基础 | 订单编号、客户、手机号脱敏、地址、来源、状态、工厂、备注 |
| 明细 | 产品、规格、单位、数量、销售单价、行备注 |
| 状态 | 提交时间、审批意见、取消状态、物流节点 |

#### 业务员不可见字段

| 字段 |
| --- |
| 成本价、回扣、利润、利润率、管理层审批内部备注、非本人订单详情 |

### 2.5 订单取消弹窗

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| cancel_reason | 下拉/输入 | 是 | 取消原因 |
| cancel_opinion | 多行文本 | 否 | 补充说明 |

| 状态 | 提交后结果 |
| --- | --- |
| `draft/pending_approve` | 直接进入 `canceled` |
| `approved/pending_factory/pending_driver/accepted/picked_up/shipped/delivered/production` | 进入 `cancel_pending` |

### 2.6 提醒中心

| 项 | 内容 |
| --- | --- |
| 路由 | `/reminders` |
| API | 可复用 `GET /api/reminders`，若未在总 API 中定义，需要新增 |
| 筛选项 | 提醒类型、状态、开始时间、结束时间 |
| 列表字段 | 标题、类型、业务编号、状态、创建时间、已读时间 |
| 按钮 | 查看、标记已读 |
| 权限 | 业务员只看本人提醒 |

## 3. 微信原生小程序管理层端

### 3.1 登录页

| 页面 | 字段 | 按钮 | 成功 |
| --- | --- | --- | --- |
| `/pages/login` | username、password、role_type=manager | 登录 | 跳转审批首页 |

### 3.2 审批首页/待审批列表

| 页面 | `/pages/approve-list` |
| --- | --- |
| API | `GET /api/orders?order_status=pending_approve` |
| 筛选项 | 客户姓名、业务员、时间 |
| 列表字段 | 订单编号、客户、业务员、销售金额、利润预览、提交时间 |
| 按钮 | 查看审批 |

### 3.3 审批详情页

| 页面 | `/pages/approve-detail` |
| --- | --- |
| API | `GET /api/orders/{order_id}`、`POST /api/orders/{order_id}/approve` |
| 分区 | 订单信息、客户信息、明细、利润计算、审批记录 |
| 可见字段 | 销售、成本、回扣、运费、税费、其他费用、利润、利润率、固定提成 |
| 按钮 | 通过、退回 |
| 弹窗 | 审批意见弹窗 |

#### 审批弹窗

| 字段 | 类型 | 必填 |
| --- | --- | --- |
| approve_result | 单选 | 是 |
| approve_opinion | 文本域 | 退回时必填 |

### 3.4 取消审批列表/详情

| 页面 | 内容 |
| --- | --- |
| 列表 API | `GET /api/orders?order_status=cancel_pending` |
| 详情 API | `GET /api/orders/{order_id}` |
| 操作 API | `POST /api/orders/{order_id}/cancel-approve` |
| 列表字段 | 订单编号、客户、原状态、申请人、取消原因、申请时间 |
| 按钮 | 同意取消、拒绝取消 |

### 3.5 下发工厂文本页

| 页面 | `/pages/supplier-text` |
| --- | --- |
| API | `POST /api/orders/{order_id}/supplier-text`、确认下发接口 |
| 字段 | 订单编号、工厂、模板类型、文本内容 |
| 按钮 | 生成文本、复制文本、确认下发 |
| 状态 | 仅 `approved` 订单可确认下发，确认后进入 `pending_factory` |

### 3.6 司机任务分配页

| 页面 | `/pages/task-create` |
| --- | --- |
| API | 新增 `POST /api/logistics/tasks` |
| 字段 | order_id、driver_id、pickup_address、delivery_address、pickup_content、quantity、factory_id、remark |
| 按钮 | 保存、取消 |
| 权限 | 管理层、管理员 |

### 3.7 经营数据概览

| 页面 | `/pages/dashboard` |
| --- | --- |
| API | `GET /api/reports/performance` |
| 筛选项 | 统计类型、时间范围、分类 |
| 指标 | 订单数、订单金额、分类金额、固定提成汇总 |

## 4. 微信原生小程序司机端

### 4.1 登录页

| 页面 | 字段 | 按钮 | 成功 |
| --- | --- | --- | --- |
| `/pages/login` | username、password、role_type=driver | 登录 | 跳转任务列表 |

### 4.2 任务列表

| 页面 | `/pages/task-list` |
| --- | --- |
| API | `GET /api/driver/tasks` |
| 筛选项 | 任务状态 |
| Tab | 待接单、已接单、已揽货、已送达 |
| 列表字段 | 任务编号、取货地址、送达地址、取件内容、数量、状态 |
| 按钮 | 查看详情 |
| 权限 | 仅本人任务 |

### 4.3 任务详情

| 页面 | `/pages/task-detail` |
| --- | --- |
| API | `GET /api/driver/tasks/{task_id}` |
| 可见字段 | 任务编号、状态、取货地址、送达地址、取件内容、数量、工厂、有限业务员信息、备注 |
| 不可见字段 | 客户敏感信息、销售价、成本、回扣、利润 |
| 按钮 | 接单、确认揽货、确认送达 |

#### 按钮状态

| 按钮 | 可见条件 |
| --- | --- |
| 接单 | `status=pending` |
| 确认揽货 | `status=accepted` |
| 确认送达 | `status=picked_up` |

### 4.4 确认揽货弹窗

| 字段 | 类型 | 必填 |
| --- | --- | --- |
| photo_files | 图片上传 | 是 |
| video_files | 视频上传 | 否 |
| remark | 文本域 | 否 |

| 存储 | 说明 |
| --- | --- |
| 阿里云 OSS | 图片、视频上传后返回附件 ID 和文件 URL |

### 4.5 确认送达弹窗

| 字段 | 类型 | 必填 |
| --- | --- | --- |
| remark | 文本域 | 否 |

## 5. Vue WEB 管理后台

### 5.1 后台登录页

| 路由 | 字段 | 角色 |
| --- | --- | --- |
| `/login` | username、password、role_type=admin | 管理员 |

### 5.2 后台首页

| 路由 | `/dashboard` |
| --- | --- |
| 组件 | 指标卡片、待处理事项、最近订单、快捷入口 |
| 指标 | 今日订单、待审批、待分配任务、欠款提醒、订单金额 |

### 5.3 用户管理

| 路由 | `/system/users` |
| --- | --- |
| API | 用户 CRUD，需要新增接口 |
| 筛选项 | 账号、姓名、手机号、角色、状态 |
| 表格字段 | 用户 ID、账号、姓名、手机号、角色、状态、创建时间 |
| 按钮 | 新增、编辑、停用/启用、重置密码 |
| 弹窗字段 | username、real_name、mobile、role_id、status、password |

### 5.4 角色与菜单管理

| 路由 | `/system/roles`、`/system/menus` |
| --- | --- |
| 筛选项 | 角色名称、角色编码、状态 |
| 角色字段 | role_name、role_code、status |
| 菜单字段 | parent_id、menu_name、menu_path、menu_type、permission_code、icon、sort_no、status |
| 按钮 | 新增、编辑、停用、分配菜单 |

### 5.5 客户管理

| 路由 | `/customers` |
| --- | --- |
| API | `GET/POST /api/customers`、`GET /api/customers/{customer_id}`、`POST /api/customers/import` |
| 筛选项 | 客户姓名、手机号、客户类型、结算方式、业务员 |
| 表格字段 | 客户姓名、手机号、地址、结算方式、账期天数、归属业务员、欠款金额、状态 |
| 按钮 | 新增、查看、编辑、导入、停用 |
| 弹窗字段 | customer_name、mobile、address、settlement_type、settlement_days、settlement_start_type、customer_type、salesman_id、credit_limit、remark |

### 5.6 产品分类管理

| 路由 | `/products/categories` |
| --- | --- |
| API | 需新增 `GET/POST/PUT /api/product-categories` |
| 筛选项 | 分类名称、状态 |
| 表格字段 | 分类名称、分类编码、排序、状态、备注 |
| 按钮 | 新增、编辑、停用 |
| 弹窗字段 | category_name、category_code、sort_no、status、remark |

### 5.7 产品管理

| 路由 | `/products` |
| --- | --- |
| API | `GET/POST /api/products`、`GET /api/products/{product_id}` |
| 筛选项 | 产品名称、规格、分类、状态 |
| 表格字段 | 产品名称、规格、单位、分类、成本价、售价、状态、更新时间 |
| 按钮 | 新增、查看、编辑、停用 |
| 弹窗字段 | product_name、specification、unit、category_id、cost_price、sale_price、status、remark |

### 5.8 工厂/供应商管理

| 路由 | `/suppliers` |
| --- | --- |
| API | `GET/POST /api/suppliers` |
| 筛选项 | 名称、类型、状态 |
| 表格字段 | 名称、类型、联系人、联系电话、地址、模板类型、状态 |
| 按钮 | 新增、编辑、停用 |
| 弹窗字段 | supplier_name、supplier_type、contact_name、contact_mobile、address、template_type、status、remark |

### 5.9 订单管理后台

| 路由 | `/orders` |
| --- | --- |
| API | `GET /api/orders`、`GET /api/orders/{order_id}` |
| 筛选项 | 状态、客户、业务员、工厂、来源、开始时间、结束时间 |
| 表格字段 | 订单编号、客户、业务员、状态、销售额、成本、利润、利润率、固定提成、创建时间 |
| 按钮 | 查看、取消、生成下发文本、创建司机任务 |
| 权限 | 管理员可见全量数据 |

### 5.10 司机任务管理

| 路由 | `/logistics/tasks` |
| --- | --- |
| API | 需新增 `GET/POST /api/logistics/tasks`、`GET /api/logistics/tasks/{task_id}` |
| 筛选项 | 任务状态、司机、订单编号、时间 |
| 表格字段 | 任务编号、订单编号、司机、取货地址、送达地址、状态、创建时间 |
| 按钮 | 新建任务、查看、取消任务 |
| 弹窗字段 | order_id、driver_id、pickup_address、delivery_address、pickup_content、quantity、factory_id、remark |

### 5.11 物流与 AI 管理

| 路由 | `/ops/logistics-ai` |
| --- | --- |
| API | 物流节点维护接口、`POST /api/ai/recognize`、`POST /api/ai/recognize/{log_id}/correct` |
| 筛选项 | 订单编号、客户、识别状态、时间 |
| 表格字段 | 订单编号、图片、识别置信度、识别状态、创建人、创建时间 |
| 按钮 | 上传图片、发起识别、人工修正、查看原始结果 |
| 弹窗字段 | image_url、biz_type、biz_id、corrected_result |

### 5.12 提醒管理

| 路由 | `/reminders` |
| --- | --- |
| API | 需新增 `GET /api/reminders`、`POST /api/reminders/{id}/read` |
| 筛选项 | 类型、状态、接收人、业务类型、时间 |
| 表格字段 | 提醒标题、类型、业务类型、接收人、状态、发送时间、创建时间 |
| 按钮 | 查看、标记已读、取消 |

### 5.13 报表统计

| 路由 | `/reports/performance` |
| --- | --- |
| API | `GET /api/reports/performance`、`GET /api/reports/performance/export` |
| 筛选项 | 统计类型、开始日期、结束日期、产品分类 |
| 图表 | 分类金额柱状图、订单趋势折线图 |
| 表格字段 | 统计周期、订单数、订单金额、分类金额、固定提成金额 |
| 按钮 | 查询、导出 |

### 5.14 系统配置

| 路由 | `/system/configs` |
| --- | --- |
| API | `GET /api/configs/{config_key}`、`PUT /api/configs/{config_key}` |
| 配置项 | 欠款生成模式、物流超时小时数、沉默客户周期、沉默客户金额阈值、报表分类映射、OSS 配置摘要、AI 配置摘要 |
| 按钮 | 保存 |
| 权限 | 管理员 |

### 5.15 审计日志

| 路由 | `/audit-logs` |
| --- | --- |
| API | `GET /api/audit-logs` |
| 筛选项 | 业务类型、业务 ID、操作人、操作类型、开始时间、结束时间 |
| 表格字段 | 操作人、操作时间、操作类型、业务类型、业务 ID、结果、备注 |
| 按钮 | 查看前后值 |