多角色农产品流通管理平台（农户-批发商-零售商）

注册表单含手机号（11位数字校验）、密码（6-20位，至少含字母和数字）、角色选择（农户/批发商/零售商）、姓名、身份证号（18位，校验格式）。手机号查重，重复时提示"该手机号已注册"。身份证号查重，重复时提示"该身份证号已注册"。成功后自动登录并跳转对应角色工作台。

登录表单含手机号+密码。POST /api/auth/login，入参 { phone, password }，校验手机号格式与密码非空。成功返回 JWT token（含 userId、role），失败返回 401 "手机号或密码错误"。三态：提交中按钮置灰+loading，失败显示错误提示，成功跳转。

登录成功后前端根据 token 中的 role 字段跳转：farmer→农户工作台 /supply，wholesaler→批发商工作台 /wholesale，retailer→零售商工作台 /retail。无 token 访问受保护路由时重定向到登录页。

Express 中间件从请求头 Authorization 提取 JWT，解析出 role。每个 API 路由声明 requiredRole 数组，中间件校验当前用户 role 是否在允许列表中。不在则返回 403 "您没有权限执行此操作"。token 过期或无效返回 401。

"我的资料"页面展示当前用户信息（头像、姓名、手机号、角色、注册时间）。支持编辑姓名和头像上传，修改密码需输入旧密码+新密码两次确认，旧密码错误提示"原密码不正确"。PUT /api/user/profile 和 PUT /api/user/password。

顶部导航栏消息图标显示未读消息数红点角标。点击进入消息中心，列表展示所有通知（询价通知、合同签署提醒、订单状态变更、发货通知、结算通知、系统通知），支持按类型筛选和已读/未读筛选，分页每页 15 条。点击单条消息标记已读并跳转至关联业务页面。GET /api/messages?type=&read=&page=&pageSize=，PUT /api/messages/:id/read，PUT /api/messages/read-all 一键全部已读。

农户填写供应表单：产品名称、品类（蔬菜/水果/粮食/禽畜/水产/其他）、规格（斤/公斤/吨/箱）、数量、单价（元）、产地、产品图片（最多5张，单张≤5MB）、描述（≤500字）。必填校验未通过时对应字段标红提示。POST /api/supply，成功后跳转供应列表并 toast"发布成功"。供应成交后系统自动扣减对应数量，扣至0时供应状态自动变为"已成交"。

农户端展示自己发布的供应列表，支持按品类下拉筛选、按产品名称搜索、按状态（待售/议价中/已成交/已下架）Tab 切换，分页每页 10 条。每条显示缩略图、名称、价格、库存、状态标签。空状态显示"暂无供应信息，去发布"引导按钮。GET /api/supply/mine?status=&keyword=&category=&page=&pageSize=。

点击供应列表中的"编辑"进入编辑表单，预填现有数据。仅允许编辑状态为"待售"或"已下架"的供应；议价中或已成交的供应禁止编辑，按钮置灰提示"当前状态不可编辑"。PUT /api/supply/:id，校验供应归属为当前用户。

供应列表中每条有"下架"/"上架"操作按钮。下架后该供应在批发商市场不可见，状态变为"已下架"；可重新上架恢复为"待售"。PUT /api/supply/:id/status，body { status: "listed"|"unlisted" }，已成交的供应不可操作。

农户在供应详情页查看该供应的询价列表（批发商发来的采购意向），展示批发商名称、采购数量、期望价格、询价时间。农户可对每条询价操作"接受"或"拒绝"。接受后供应状态变为"议价中"，并生成合同草稿。拒绝后该询价标记为"已拒绝"并通知批发商。

订单状态为"已确认"时，农户在订单详情页操作"确认发货"。弹出表单填写物流信息：物流公司（选填）、运单号（选填）、备注（选填，≤200字）。提交后 PUT /api/order/:id/ship，订单状态变为"已发货"，同时向批发商推送发货通知（站内消息）。

农户查看自己所有销售订单列表，支持按状态 Tab 切换（待确认/已确认/已发货/已收货/已取消），分页每页 10 条。每条显示批发商名称、商品名称、数量、金额、状态、时间。点击进入订单详情，可查看完整信息、物流信息和合同关联。GET /api/order/supply?status=&page=&pageSize=。

批发商端供应市场页面，以卡片/列表展示所有"待售"状态的供应。顶部搜索栏支持按产品名称模糊搜索、品类下拉筛选、价格区间（最低价-最高价）、产地筛选。分页每页 12 条，默认按发布时间倒序。空状态展示"暂无可采购的供应"。GET /api/supply/market?keyword=&category=&minPrice=&maxPrice=&origin=&page=&pageSize=。

批发商在供应详情页点击"我要采购"，弹出询价表单：采购数量（必填，正整数）、期望单价（必填，正数）、备注（选填，≤200字）。提交后 POST /api/inquiry 创建询价记录，状态为"待农户确认"，toast"询价已发送，请等待农户确认"。同一批发商对同一供应不可重复询价。

批发商查看自己所有采购订单列表，支持按状态 Tab 切换（待确认/已确认/已发货/已收货/已取消），分页每页 10 条。每条显示供应名称、农户信息、采购数量、金额、状态、时间。点击进入订单详情查看完整信息。GET /api/order/wholesale?status=&page=&pageSize=。

批发商可在供应市场将多个供应加入"采购车"（临时勾选，不跨会话持久）。在采购车页面统一填写各品目采购数量与期望单价，一次性提交生成多笔询价/订单。提交前校验每项数量>0，全部成功后跳转订单列表。

订单状态为"已发货"时批发商可操作"确认收货"。点击后弹出二次确认弹窗："确认已收到货物？确认后库存将自动入库"。确认后 PUT /api/order/:id/receive，订单状态变为"已收货"，同时触发批发商库存增加对应数量，生成库存变动记录。

批发商端查看零售商提交的采购订单列表，支持按状态 Tab（待确认/已确认/已发货/已收货/已取消），分页每页 10 条。对"待确认"订单可操作"确认"（扣减批发商库存，状态变为"已确认"）或"拒绝"（恢复预扣库存，状态变为"已取消"，通知零售商）。对"已确认"订单可操作"发货"，PUT /api/order/retail/:id/confirm、PUT /api/order/retail/:id/reject、PUT /api/order/retail/:id/ship。拒绝时需填写拒绝原因（≤200字）。

订单在"待确认"状态下，下单方和接单方均可取消，取消后恢复预扣库存，订单状态变为"已取消"。订单进入"已确认"及之后状态，不可单方面取消；需双方协商后由任一方发起"申请取消"，对方确认后 PUT /api/order/:id/cancel。已取消订单在列表中保留记录可查看，但不可继续操作。合同关联的订单取消时，对应合同状态变为"已失效"。

零售商端展示批发商已上架的商品列表（批发商库存>0的商品），支持按名称搜索、品类筛选、价格区间筛选，分页每页 12 条。每条展示商品图片、名称、批发价、批发商名称、库存量。空状态显示"暂无可采购商品"。GET /api/product/retail?keyword=&category=&minPrice=&maxPrice=&page=&pageSize=。

零售商在商品详情页填写采购数量（必填，正整数，不超过当前库存），点击"立即下单"。POST /api/order/retail 创建零售商订单，预扣批发商库存（库存暂不可被其他零售商下单），订单状态"待确认"。下单成功后 toast"下单成功，等待批发商确认"，跳转订单列表。若批发商拒绝则自动释放预扣库存。

零售商查看自己所有订单列表，支持按状态 Tab（待确认/已确认/已发货/已收货/已取消），分页每页 10 条。每条显示商品名称、批发商信息、数量、金额、状态。点击进入订单详情。GET /api/order/retail?status=&page=&pageSize=。

订单状态为"已发货"时零售商可操作"确认收货"。点击弹出二次确认："确认已收到货物？"。确认后 PUT /api/order/:id/receive，订单状态变为"已收货"，零售商库存自动增加对应数量并生成库存变动记录。

批发商端库存页面，以表格展示所有库存商品：商品名称、品类、当前库存量、单位、零售批发价、上架状态、上次变动时间。支持按名称搜索、品类筛选、上架状态筛选，分页每页 10 条。空状态"暂无库存记录"。库存>0且已设置售价的商品自动标记为"已上架"对零售商可见；库存为0或未定价的商品默认"已下架"。GET /api/inventory/wholesale?keyword=&category=&listing=&page=&pageSize=。

零售商端库存页面，表格展示已收货商品库存：商品名称、品类、当前库存量、单位、上次变动时间。支持名称搜索、品类筛选，分页每页 10 条。GET /api/inventory/retail?keyword=&category=&page=&pageSize=。

每次入库/出库自动生成库存变动记录：商品名称、变动类型（入库/出库）、变动数量、变动后库存、关联订单号、时间。按时间倒序展示，支持按类型筛选。GET /api/inventory/logs?type=&page=&pageSize=。此记录只读不可编辑。

用户可为每个库存商品设置低库存阈值（默认 10）。当库存量 ≤ 阈值时，库存列表该行高亮橙色背景并显示"库存不足"标签，同时在顶部横幅提示"您有 N 项商品库存不足，请及时补货"。阈值可修改，PUT /api/inventory/:id/threshold。

批发商收货入库后，在库存列表每条商品有"设置售价"按钮，弹出表单填写零售批发价（必填，正数，单位元）。设置售价后该商品自动对零售商可见（库存>0且已定价）。批发商可在库存列表操作"下架"使该商品对零售商不可见，或"上架"恢复可见。PUT /api/inventory/:id/pricing 设置售价，PUT /api/inventory/:id/listing { status: "listed"|"unlisted" } 控制上下架。

农户接受批发商询价后，系统自动生成电子合同草稿。合同内容含：合同编号（CNT-年月日-序号）、双方信息（农户姓名/手机号、批发商名称/手机号）、商品明细（名称、规格、数量、单价、总金额）、生成时间。POST /api/contract 在询价接受时自动触发，状态为"待签署"。

合同详情页展示完整合同信息（双方信息、商品明细表格、金额合计、签署状态）。提供"下载 PDF"按钮，GET /api/contract/:id/pdf 返回 PDF 文件流，浏览器触发下载，文件名格式"合同_{合同编号}.pdf"。PDF 内容包含合同全部信息和水印。

合同双方各自在自己的合同详情页看到"确认签署"按钮。点击后弹出签署确认弹窗，提示"签署后合同即生效，具有法律效力"，需二次确认。PUT /api/contract/:id/sign，记录签署人角色和签署时间。双方均签署后合同状态变为"已生效"，触发订单状态更新为"已确认"。

各角色查看与自己相关的合同列表，支持按状态 Tab（待签署/已生效/已失效），分页每页 10 条。每条显示合同编号、对方名称、商品摘要、金额、签署状态、生成时间。GET /api/contract?status=&page=&pageSize=。

每笔订单成交后自动生成交易流水：流水号、关联订单号、交易双方、金额、交易方向（支出/收入）、时间。各角色在自己的财务页面查看流水列表，支持按时间范围、交易方向筛选，分页每页 20 条。GET /api/finance/transactions?startDate=&endDate=&direction=&page=&pageSize=。

按时间范围（起止日期必选）和交易方（可选）筛选，生成对账报表。报表含：时间段内总交易笔数、总支出金额、总收入金额、净额。表格逐笔列出交易明细含汇总行。支持"导出 Excel"，GET /api/finance/report?startDate=&endDate=&counterparty= 返回报表数据，Excel 导出通过 GET /api/finance/report/excel 下载。

各角色财务页面顶部展示应收/应付概览卡片：待结算总额、已结算总额。下方列表展示待结算订单，每条显示对方名称、订单号、金额、应结算日期。支持标记"已结算"，PUT /api/finance/order/:id/settle，结算后订单从待结算列表移除，记录结算时间。

一方标记"已结算"后，系统自动向对方发送结算通知。通知通过消息中心（见 FR-AUTH-006）投递，类型标记为"结算通知"，点击可跳转至对应订单详情。对方收到通知后可确认结算或提出异议。

后端使用 Express 框架，RESTful 风格 API，所有接口路径以 /api/ 为前缀。统一 JSON 响应格式：{ code: 0, data: ... } 成功，{ code: 错误码, message: "错误描述" } 失败。全局错误处理中间件捕获未处理异常返回 500。

前端使用 React 构建单页应用，React Router 管理路由，Axios 封装 API 请求（统一拦截 token 注入和 401/403 跳转）。按角色拆分工作台模块：/supply（农户）、/wholesale（批发商）、/retail（零售商），共享登录/注册/个人中心等公共页面。

使用 MySQL 作为数据库。核心数据表：users（用户与角色）、supplies（供应信息）、inquiries（询价记录）、orders（订单，通过 order_type 字段区分 purchase/retail 两类，含状态、金额、物流信息等）、inventory（库存）、inventory_logs（库存变动）、contracts（合同）、transactions（交易流水）、messages（站内消息）。所有表包含 created_at 和 updated_at 时间戳字段。

JWT token 有效期 7 天，存储在 localStorage。密码使用 bcrypt 加盐哈希存储，不可明文。敏感接口（下单、签署合同、结算）需验证 token 有效性 + 角色权限双重校验。密码强度要求：6-20 位，至少含字母和数字。

供应图片和合同 PDF 使用 multer 中间件处理上传，图片存储在服务器本地 /uploads 目录，按日期分文件夹。图片格式限制 jpg/png/webp，单张 ≤5MB。合同 PDF 使用 pdfkit 服务端生成。静态文件通过 Express 静态资源中间件对外提供访问。

API 响应 P95 < 500ms（不含文件下载）。前端首屏加载 ≤3s。所有 API 请求进行入参校验（express-validator），防止 SQL 注入（参数化查询）和 XSS（输入转义）。敏感数据（密码）不可在 API 响应中返回。系统需支持 HTTPS 部署。