dingdanquanliucheng/开发细节/01-页面级原型字段说明.md

页面级原型与字段说明

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、结果、备注
按钮	查看前后值