西藏巴青项目

交易订单管理 — 功能需求

1. 文档说明

项	说明
模块名称	交易订单管理（交易市场平台）
目标	登记供应商向承销商出售牲畜的交易订单，完成订单支付后自动生成供应商结算单，形成「交易 → 订单支付 → 结算付款」业务闭环
依据	同目录 `交易订单管理-草稿.md`、原型 `Snipaste_2026-05-22_13-54-54.jpg`；关联 `../供应商结算管理/供应商结算管理-草稿.md`、原型 `Snipaste_2026-05-22_13-55-35.jpg`
范围	仅功能与业务规则；不含库表、接口、报文、技术栈

1.1 使用角色与入口

角色	场景
交易市场运营人员	录入订单、完成订单支付、查询、打印小票/凭证
财务/结算人员	在供应商结算管理中处理待结算单（本模块不完成结算）
系统管理员	菜单与权限配置

默认进入 交易订单列表。

1.2 模块关系（业务视角）

供应商管理 ──────► 选供应商；收费方式/费率（结算计费依据）
承销商管理 ──────► 选承销商
市场进栏登记 ────► 采购明细耳标候选（已进栏牲畜）
交易订单管理 ────► 主单 + 采购明细；待支付 → 已完成
       │ 完成支付（支付凭证）
       ▼
供应商结算管理 ► 自动生成结算单；待结算 → 已完成（结算凭证）

关联模块	本模块依赖	约束
供应商管理	有效供应商	完成支付时须能读取收费规则
承销商管理	有效承销商	—
市场进栏登记	按供应商汇总已进栏耳标	无进栏耳标则无法建明细
隔离巡查登记	病死/病害耳标剔除（§4.2）	与「未病死、未病害」业务一致
供应商结算管理	支付成功后生成一条结算单	一对一；不可在本模块手工建结算单

2. 核心业务概念

2.1 一条交易订单

某供应商向某承销商出售多行牲畜（每行：耳标、重量 kg、金额元），汇总为交易总头数、交易总金额。

信息项	说明
订单编号	系统生成，业务唯一
采购明细	至少 1 行
交易总头数	= 明细行数
交易总金额	= 明细金额之和（元，保留 2 位小数展示）
订单状态	待支付 / 已完成
支付凭证	完成支付时上传的图片
订单创建时间	首次保存成功时写入
订单完成时间	完成支付成功时写入；此前为空

2.2 状态与流转

状态	含义	允许操作（见 §8.9）
待支付	已保存，未上传支付凭证	编辑、删除、完成支付、打印小票、查看
已完成	已支付并已生成结算单	查看、打印凭证

流转：仅待支付 → 已完成，不可逆。
已完成不可改业务字段、不可删除、不可再次完成支付。

2.3 删除

待支付：逻辑删除，列表不展示，数据保留。
已完成：禁止删除（已关联结算单）。
本期无回收站。

3. 字段与录入规则

3.1 订单编号

用户不可录入；新增时系统生成；修改不可改。
规则：YYYYMMDD + 3 位当日序号（001～999，左补零），如 20260520001。
序号按自然日递增，仅统计未逻辑删除订单。
保存时须唯一；冲突则拒绝并提示。

3.2 供应商

必填；表单单选，支持名称模糊搜索后选定。
仅能选 供应商管理 中有效供应商。
列表筛选：选定后精确匹配该供应商订单。
更换供应商：清空全部采购明细，重新加载耳标候选。

3.3 承销商

必填；表单单选，支持名称模糊搜索后选定。
仅能选 承销商管理 中有效承销商。
列表筛选：选定后精确匹配。

3.4 采购明细

至少 1 行；可增删行（保存时至少保留 1 行）。

字段	规则
耳标号	下拉单选，必填；须先选供应商；下拉候选见 §4.4；保存校验见 §4.4 / §5 R3；本单内不可重复
重量	必填；> 0；单位 kg；建议最多 2 位小数；库字段 `weight`
金额	必填；> 0；单位元；建议最多 2 位小数；库字段 `amount`
品质等级	只读；库字段 `grade_code`、`grade_name`；保存/修改订单时由服务端根据本行重量匹配 `biz_grade_weight_config`（闭区间 `[min_weight, max_weight]`）后同时写入编码与名称；前端无需传、不可手工改

子表 biz_trade_order_line 冗余 supplier_id（与主表一致），由服务端写入，前端 Body 无需传。
等级重量配置见 sql/biz_grade_weight_config.sql（如 A 一级 ≥140 kg、B 二级 120～139.99 kg 等）；重量落在任一档外时保存失败并提示。
耳标字符规则与 入场隔离 / 市场进栏 一致（单段 1～32 字符等）。

3.5 交易总头数 / 交易总金额

字段	规则
交易总头数	只读联动；= 明细行数；正整数
交易总金额	只读联动；= 明细金额之和；与手工合计不一致时以系统汇总为准

3.6 支付凭证

阶段	规则
待支付	无
完成支付	必填；单张图片；`jpg` / `jpeg` / `png`；≤ 10MB
已完成	列表/详情可查看；打印凭证须能展示

3.7 时间字段

字段	写入时机	规则
订单创建时间	首次保存成功	系统当前时间；用户不可改
订单完成时间	完成支付成功	系统当前时间

4. 采购明细耳标候选（已确认口径）

草稿要求从 市场进栏登记 按供应商筛选，且牲畜须未病死、未病害。与 市场进栏登记、隔离巡查 对齐后的规则如下。

4.1 集合 M：市场进栏耳标（按供应商）

市场进栏登记 中：del_flag 有效、供应商 = 当前所选供应商；
汇总所有进栏记录中的耳标（子表或聚合字段，逗号拆分、去重）→ M。

若 M 为空：提示「该供应商暂无进栏耳标，请先维护市场进栏登记」。

说明：订单不使用「入场隔离已结束」耳标池；仅以已进栏耳标为准。

4.2 集合 B：病死 / 病害耳标（全表巡查）

隔离巡查登记 中：del_flag 有效、病死病害数量 > 0、耳标号非空；
不按供应商过滤；耳标逗号拆分、去重 → B。

4.3 集合 C：他单已成交占用（已确认：不允许跨单重复使用）

在其他有效交易订单（待支付或已完成、未逻辑删除）的采购明细中已出现的耳标 → C。

不允许同一耳标同时出现在两笔有效订单中（含两笔待支付）。
修改本单时：本单当前已选耳标不计入 C（可保留、可调整）。

4.4 下拉与保存可选集（实现口径）

场景	集合 / 规则
加载下拉 `GET /supplierEarTags`	仅查 `biz_market_entry_ear_tag`：`supplier_id` = 当前供应商，`distinct ear_tag` 升序；不剔 B、不剔 C；可展示他单待支付已占用的耳标
保存校验（R3）	每行耳标 ∈ （M − B）− C；M 为 §4.1（有效进栏主表关联子表）；编辑时 C 排除本单 `order_id`
完成支付成功后	按本单每行 `supplier_id` + `ear_tag` 删除 `biz_market_entry_ear_tag` 对应记录，释放进栏耳标池（与下拉数据源一致）

下拉宽松、保存严格：用户可能选到保存时被 R3 拒绝的耳标（如病死 B、他单占用 C），须提示 §11 示例文案。

4.5 联动

时机	行为
选供应商	重载 `/supplierEarTags`（§4.4 下拉口径）
换供应商	清空明细
增删行	更新头数、金额
保存	执行 §5

5. 保存规则（R1～R8）

待支付订单新增/修改点「确定」时全部满足：

编号	规则
R1	供应商、承销商、至少 1 行明细均已填
R2	供应商、承销商在各自主数据中仍有效
R3	每行耳标 ∈ §4.4 保存校验集合（M − B）− C；重量、金额 > 0；服务端按重量写入 `grade_code`、`grade_name`（§3.4）
R4	本单耳标不重复
R5	交易总头数 = 明细行数
R6	交易总金额 = 明细金额之和（按 2 位小数汇总）
R7	已完成订单不可保存修改
R8	订单编号唯一（系统生成冲突时拒绝）

6. 完成支付

6.1 入口

仅 待支付 显示「完成支付」→ 弹窗 「完成订单支付」。

6.2 弹窗

支付凭证：必填，§3.6。
确定 / 取消（取消不改变订单）。

6.3 确定后（须同一业务事务，全部成功或全部回滚）

序号	动作
1	订单状态 → 已完成
2	写入订单完成时间
3	保存支付凭证
4	生成一条供应商结算单（§7）
5	按明细 `supplier_id` + `ear_tag` 删除 `biz_market_entry_ear_tag` 中对应行（§4.4）

任一步失败：订单保持 待支付，提示原因；不得出现「已完成但无结算单」或「已完成但未释放进栏耳标」等半成品状态（同一事务回滚）。

6.4 重试与幂等（已确认）

情况	处理
用户再次点击「完成支付」且仍为待支付	允许重试上传凭证
订单已完成	不显示完成支付
订单已完成且结算单已存在	不得再次生成结算单

6.5 前置校验（完成支付时）

除支付凭证外，须满足：

供应商仍有效，且已配置 收费方式（否则无法计算结算金额）；
订单仍为 待支付；
采购明细、头数、金额仍满足 R3～R6（防止长时间挂单后数据失真）。

7. 与供应商结算管理的衔接

7.1 生成时机与数量

唯一触发：本模块 完成支付 成功。
一对一：一笔订单 → 一条结算单；不可在订单界面手工新建。
结算单不可由用户选择「关联多订单」。

7.2 带入结算单的信息

结算单展示项	来源
关联订单编号	本订单编号
供应商	本订单供应商
交易总头数	本订单
交易总金额（元）	本订单
结算创建时间	生成时刻

结算单编号、结算状态、服务费、实际应付、结算凭证等按 §7.3～§7.4 及结算模块自身规则处理。

7.3 结算单编号

系统自动生成：JSD + YYYYMMDD + 3 位当日序号（001～999）。
与订单编号独立；通过 关联订单编号 关联。

7.4 服务费与实际应付（生成时计算并固化）

读取生成结算单时刻该供应商在 供应商管理 中的收费配置，计算后写入结算单并不再随主数据变更自动重算（快照）。

收费方式	服务费金额（元）
按户计费	0
按头计费	交易总头数 × 收费标准（元/头）
按额计费	交易总金额 ×（交易费率 + 管理费率）÷ 100

实际应付结算金额（元） = 交易总金额 − 服务费金额。

金额精度（已确认）：

服务费、实际应付均保留 2 位小数；
按 四舍五入 至分；
按额计费时：先求（交易费率 + 管理费率）之和（%），再乘以交易总金额。

7.5 结算单初始状态

结算状态：待结算。
结算凭证、结算完成时间：空。
后续在 供应商结算管理 中「完成结算」、上传结算凭证。

7.6 订单与结算状态对照

订单：  （无）─保存─► 待支付 ──完成支付──► 已完成
结算：  （无）          （无）  ──生成──► 待结算 ──完成结算──► 已完成

订单 待支付：无结算单。
订单 已完成：必有 待结算 或 已完成 的结算单。
结算完成后，订单状态仍为已完成（不回退）。

8. 功能清单

8.1 新增

入口：列表「新增」。确定后：生成编号、待支付、订单创建时间。取消不保存。

8.2 列表查询

筛选项	匹配方式
订单编号	模糊
供应商	下拉选定后精确（支持输入模糊搜索后选定）
承销商	同上精确
组合	条件同时生效

仅未逻辑删除记录；默认按 订单创建时间 降序；默认每页 20 条。
工具栏：搜索、重置、新增。

列表列：订单编号、订单创建时间、供应商、承销商、采购明细（入口）、交易总头数（头）、交易总金额（元）、订单状态、支付凭证、订单完成时间、操作。

采购明细列：点击打开 采购明细表 弹窗（只读展示该单全部行：耳标、重量、金额、品质等级名称）；列表行内可摘要展示（如首耳标+「等 N 头」）。

8.3 修改

仅待支付；全部业务字段可改（含明细）；编号、创建时间不可改。
规则同 §4、§5。

8.4 查看

全字段只读；明细完整；支付凭证可查看；含审计信息（与项目惯例一致）。

8.5 删除

仅待支付；二次确认（宜含编号、供应商、金额或头数）；逻辑删除。

8.6 打印

功能	范围	内容
打印小票	仅待支付	编号、双方、明细、头数、金额、创建时间；不含支付凭证、完成时间
打印凭证	仅已完成	含 §3 交易信息 + 订单完成时间 + 支付凭证 + 订单状态

待支付不提供「打印凭证」；已完成不提供「打印小票」。

8.7 按状态操作矩阵

状态	操作
待支付	打印小票、完成支付、查看、编辑、删除
已完成	打印凭证、查看

无权限不显示按钮。

8.8 本期不做

部分支付/退款、拆单、批量导入导出、订单侧完成结算、改已完成订单、物理删除、承销商结算。

9. 业务流程图

9.1 订单主流程

flowchart TD
    L[订单列表] --> N[新增/编辑]
    N --> V{R1-R8?}
    V -->|否| N
    V -->|是| P[待支付]
    P --> E[编辑/删除/打小票]
    P --> Pay[完成支付+凭证]
    Pay --> OK{成功?}
    OK -->|否| P
    OK -->|是| D[已完成+生成结算单]
    D --> L

9.2 与结算衔接

sequenceDiagram
    participant O as 交易订单
    participant S as 供应商结算
    O->>O: 完成支付
    O->>S: 生成结算单(待结算,费用快照)
    S->>S: 完成结算(结算凭证)

9.3 耳标候选

flowchart LR
    M[进栏耳标 M] --> X[M-B]
    X --> Y[减他单 C]
    Y --> Z[下拉/保存校验]

10. 权限（业务层）

查询列表、查看详情、新增、修改、删除、完成支付、打印（小票/凭证）— 实施配置，本文不列编码。

11. 提示语（示例）

情况	示例
缺供应商/承销商/明细	请选择供应商 / 承销商 / 请至少添加一行采购明细
请先选供应商	请先选择供应商
无进栏耳标	该供应商暂无进栏耳标，请先维护市场进栏登记
耳标重复	存在重复耳标：{耳标号}
耳标不可用	耳标 {耳标号} 不可选或已被其他订单占用
已完成不可改删	已完成订单不可修改 / 不可删除
支付凭证	请上传支付凭证 / 文件格式或大小不符合要求
完成支付失败	完成支付失败：{原因}
供应商收费未配置	供应商收费方式未配置，无法生成结算单
编号冲突	订单编号生成冲突，请重试

12. 关联需求分析（供应商结算管理）

依据 ../供应商结算管理/供应商结算管理功能需求.md（及草稿、原型），明确两模块分工与一致性。

12.1 职责边界

能力	交易订单管理	供应商结算管理
交易与采购明细	✓	—
订单支付凭证	✓	—
触发创建结算单	✓（自动）	被动接收
服务费/实际应付计算	生成时计算并快照	展示、打印
结算凭证与结算完成	—	✓
按结算单号/订单号查询	—	✓

12.2 关键字段对照

概念	订单	结算	一致性
编号	日期+3位	JSD+日期+3位	独立；用关联订单编号串联
交易总头数	头	头	生成时一致
交易总金额	元	元	生成时一致
服务费	—	元	§7.4
实际应付	—	元	总金额−服务费
支付凭证 vs 结算凭证	订单支付	结算付款	两阶段、两种凭证

12.3 结算模块功能摘要（便于联调）

完整规则见 ../供应商结算管理/供应商结算管理功能需求.md。摘要如下：

项	规则
列表筛选	结算单编号模糊；关联订单编号模糊
列表列	结算单编号、结算创建时间、关联订单编号、供应商、交易总头数、交易总金额、服务费、实际应付、结算状态、结算凭证、结算完成时间
待结算操作	完成结算、查看
已完成操作	打印凭证、查看
完成结算	弹窗上传结算凭证（规则同订单支付凭证 §3.6）；确定后状态已完成、写入结算完成时间
流程终点	完成结算为平台业务链终点；结算模块内无后续必办
跨模块导航	不提供从结算列表/详情跳转至订单详情；关联订单编号仅展示与筛选

12.4 端到端业务链

市场进栏(耳标子表) → 交易订单(待支付) → 完成支付(删子表耳标+结算单) → 结算单(待结算) → 完成结算 → 闭环

12.5 异常场景（两模块协同）

场景	处理原则
完成支付时供应商已删或收费未配	拒绝完成支付
支付成功但结算生成失败	订单保持待支付（§6.3）；用户可重试
订单待支付被删	无结算单；耳标占用释放
订单已完成	不可删；结算单待结算/已完成均不回写订单状态
结算单已完成	订单仍已完成；不可作废订单
进栏登记删除某耳标	待支付订单保存时 R3 可能失败；已完成订单保留历史明细
完成支付成功	从 `biz_market_entry_ear_tag` 删除本单耳标；下拉池不再展示

12.6 对市场进栏登记的依赖

交易成交对象必须是 已进栏 耳标（§4.1，保存校验）。
下拉展示来自进栏耳标子表（§4.4），与保存可选集口径不同。
病死耳标通过 §4.2 与巡查模块联动，保存时剔除（下拉仍可能展示，由 R3 拦截）。
运营顺序建议：进栏 → 建单 → 支付 → 结算。

13. 非功能建议

项	建议
权限	操作分权
审计	增删改、完成支付留痕
校验	保存、完成支付须服务端执行 R1～R8 与 §6.5
事务	完成支付与生成结算单原子性
易用性	删除、完成支付二次确认

14. 已确认业务决策（评审纪要）

序号	决策
1	耳标候选来自市场进栏登记，不使用入场隔离池
2	剔除全表巡查病死/病害耳标（§4.2）
3	禁止同一耳标出现在多笔有效订单（§4.3）
4	结算费用以生成结算单时快照为准
5	金额 2 位小数、四舍五入
6	完成支付失败可重试；已成功不得重复生成结算单
7	打印：待支付仅小票；已完成仅凭证
8	下拉耳标：仅 `biz_market_entry_ear_tag` 按 `supplier_id`；保存仍 (M−B)−C
9	完成支付后删除进栏子表已成交耳标（`supplier_id` + `ear_tag`）
10	采购明细子表冗余 `supplier_id`，与主表一致

15. 草稿对照

草稿条目	章节
交易订单 1～7	§3、§4、§5、§8
交易订单 5、13～14	§6、§7、§8.7
交易订单 8～12	§8.3～§8.6
结算 2～11	§7、§12
技术栈、异常报文格式	不纳入

16. 修订记录

版本	说明
1.0	初稿：订单与结算衔接、耳标与状态
1.1	优化：拍板耳标/费用/快照/重试/打印边界；§4 与进栏/巡查对齐；§12 关联分析；§14 决策纪要；对齐草稿列表精确筛选
1.2	对齐实现：§4.4 拆「下拉子表 / 保存 M−B−C / 支付后删进栏耳标」；§3.4 子表 `supplier_id`；§6.3 步骤 5；§14 决策 8～10
1.3	对齐结算需求 v1.1：§12.3 补充「完成结算为流程终点、不跳转订单」

交易订单管理功能需求.md 21KB 文件历史 原始文件