From 06cdf4141f3c85113f20c6a22d2b0a037759661b Mon Sep 17 00:00:00 2001
From: liuwenxin <1009266660@qq.com>
Date: Tue, 13 Oct 2026 12:50:10 +0800
Subject: [PATCH] =?UTF-8?q?feat(business):=20=E5=89=8D=E7=AB=AF=E4=B8=9A?=
 =?UTF-8?q?=E5=8A=A1/=E5=8F=91=E8=B4=A7/=E5=9B=9E=E6=AC=BE=E7=AE=A1?=
 =?UTF-8?q?=E7=90=86=E4=B8=89=E9=A1=B5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 业务页：明细行编辑器、详情抽屉五分区（含状态时间线与毛利润卡片）
- 回款页：业务→发货批次级联指定（可清空）、已核算行禁改禁删
- 金额/比率字符串直出；毛利润卡片注明不含运费口径

Co-Authored-By: Claude Code <noreply@anthropic.com>
---
 frontend/src/api/businesses.ts                |  294 ++++
 frontend/src/api/receipts.ts                  |  104 ++
 frontend/src/api/shipments.ts                 |  117 ++
 frontend/src/router/index.ts                  |   19 +
 .../src/views/business/businesses/index.vue   | 1309 +++++++++++++++++
 .../src/views/business/receipts/index.vue     |  508 +++++++
 .../src/views/business/shipments/index.vue    |  497 +++++++
 7 files changed, 2848 insertions(+)
 create mode 100644 frontend/src/api/businesses.ts
 create mode 100644 frontend/src/api/receipts.ts
 create mode 100644 frontend/src/api/shipments.ts
 create mode 100644 frontend/src/views/business/businesses/index.vue
 create mode 100644 frontend/src/views/business/receipts/index.vue
 create mode 100644 frontend/src/views/business/shipments/index.vue

diff --git a/frontend/src/api/businesses.ts b/frontend/src/api/businesses.ts
new file mode 100644
index 0000000..f9c10cf
--- /dev/null
+++ b/frontend/src/api/businesses.ts
@@ -0,0 +1,294 @@
+import { request } from './request'
+import type { PageData } from './types'
+
+/**
+ * 业务产品明细行（对应后端 `BusinessItemOut`）。
+ *
+ * 数量与金额一律字符串直出 —— 金额红线：不经 float、不 toFixed，
+ * Decimal 运算收敛在后端 service 层。
+ */
+export interface BusinessItemRow {
+  id: number
+  product_id: number | null
+  product_name: string
+  spec_model: string | null
+  unit: string | null
+  /** municipal_water 市政水利 / rail_transit 轨道交通 —— 行级折算锚点 */
+  product_category: string
+  /** 数字字符串，>0 */
+  quantity: string
+  sale_price: string | null
+  /** 行销售额 = 数量 × 销售单价，后端计算固化 */
+  sale_amount: string
+  cost_amount: string | null
+  guided_price: string | null
+  remark: string | null
+}
+
+/** 业务列表项（对应后端 `BusinessOut`；四个汇总金额均为字符串直出） */
+export interface BusinessItem {
+  id: number
+  business_no: string
+  customer_id: number
+  customer_name: string | null
+  /** ISO 串（YYYY-MM-DD） */
+  business_date: string | null
+  /** 1执行中 2已完成 3已终止 */
+  status: number
+  owner_personnel_id: number | null
+  owner_personnel_name: string | null
+  assistant_personnel_id: number | null
+  assistant_personnel_name: string | null
+  /** 特殊业务标记：1是 0否 */
+  is_special: number
+  special_note: string | null
+  total_sale_amount: string | null
+  total_cost_amount: string | null
+  total_ship_amount: string | null
+  total_received_amount: string | null
+  total_freight_amount: string | null
+  remark: string | null
+}
+
+/** 业务详情：附产品明细行（编辑弹窗一次回显） */
+export interface BusinessDetail extends BusinessItem {
+  items: BusinessItemRow[]
+}
+
+export interface BusinessQueryParams {
+  pageNum?: number
+  pageSize?: number
+  /** 业务编号/公司名称，模糊匹配 */
+  keyword?: string
+  status?: number
+  customer_id?: number
+  owner_personnel_id?: number
+  /** 业务日期起（含），ISO 串 */
+  date_from?: string
+  /** 业务日期止（含），ISO 串 */
+  date_to?: string
+}
+
+/** 明细行入参（product_id 空 = 自由录入；金额/数量为数字字符串） */
+export interface BusinessItemParams {
+  product_id?: number | null
+  product_name: string
+  spec_model?: string | null
+  unit?: string | null
+  product_category: string
+  quantity: string
+  sale_price?: string | null
+  cost_amount?: string | null
+  guided_price?: string | null
+  remark?: string | null
+}
+
+/**
+ * 创建业务：主表信息 + 明细行（≥1）。
+ *
+ * is_special=1 时 special_note 必填（后端校验，前端同步拦截）。
+ */
+export interface BusinessCreateParams {
+  customer_id: number
+  business_date?: string | null
+  owner_personnel_id?: number | null
+  assistant_personnel_id?: number | null
+  is_special?: number
+  special_note?: string | null
+  items: BusinessItemParams[]
+  remark?: string | null
+}
+
+/**
+ * 编辑业务：明细全量替换并重算汇总。
+ *
+ * 不含归属字段 —— 归属调整统一走 `PUT /{id}/ownership`（唯一写归属
+ * 留痕的入口），编辑表单即使提交归属也会被后端忽略。
+ */
+export interface BusinessUpdateParams {
+  customer_id: number
+  business_date?: string | null
+  is_special?: number
+  special_note?: string | null
+  items: BusinessItemParams[]
+  remark?: string | null
+}
+
+/** 状态流转入参：执行中 → 2已完成 / 3已终止；终止时 reason 必填 */
+export interface BusinessStatusParams {
+  status: number
+  reason?: string | null
+}
+
+/** 归属变更入参（新负责/新协助；前后值写入留痕，不回溯历史） */
+export interface BusinessOwnershipParams {
+  new_owner_personnel_id?: number | null
+  new_assistant_personnel_id?: number | null
+  reason?: string | null
+}
+
+/** 业务归属变更留痕条目（对应后端 `OwnershipChangeLogOut`；姓名可随人员消失，ID 固化） */
+export interface OwnershipLogItem {
+  id: number
+  business_id: number
+  old_owner_personnel_id: number | null
+  new_owner_personnel_id: number | null
+  old_assistant_personnel_id: number | null
+  new_assistant_personnel_id: number | null
+  old_owner_name: string | null
+  new_owner_name: string | null
+  change_reason: string | null
+  operator_id: number | null
+  operator_name: string
+  create_time: string
+}
+
+/** 业务状态流转记录（对应后端 `BusinessStatusLogOut`；创建首条 old=new=1） */
+export interface StatusLogItem {
+  id: number
+  business_id: number
+  old_status: number
+  new_status: number
+  change_reason: string | null
+  operator_id: number | null
+  operator_name: string
+  create_time: string
+}
+
+/** 毛利润视图行（对应后端 `GrossProfitRowOut`）；成本缺失行派生列为 null */
+export interface GrossProfitRowItem {
+  item_id: number
+  product_category: string
+  product_name: string
+  spec_model: string | null
+  quantity: string
+  sale_amount: string
+  cost_amount: string | null
+  profit_amount: string | null
+  profit_rate: string | null
+  threshold: string
+  converted_profit: string | null
+  missing_reason: string | null
+}
+
+/** 按产品类别的毛利润汇总（成本缺失行不计入聚合） */
+export interface GrossProfitCategory {
+  product_category: string
+  sale_amount: string
+  cost_amount: string
+  profit_amount: string
+  /** 分数字符串原样（如 "997/1000"），不做数值化展示 */
+  profit_rate: string
+  threshold: string
+  converted_profit: string
+}
+
+/** 毛利润数据视图（对应后端 `GrossProfitOut`） */
+export interface GrossProfitView {
+  business_id: number
+  /** 参数取值时点（默认今日），ISO 串 */
+  as_of: string
+  rows: GrossProfitRowItem[]
+  categories: GrossProfitCategory[]
+  missing_count: number
+  note: string
+}
+
+/** 业务状态下拉项（与后端值域一致；执行中=1 已完成=2 已终止=3） */
+export const BUSINESS_STATUS_OPTIONS = [
+  { label: '执行中', value: 1 },
+  { label: '已完成', value: 2 },
+  { label: '已终止', value: 3 },
+] as const
+
+/** 状态编码 → 展示名 */
+export function businessStatusLabel(status: number): string {
+  return BUSINESS_STATUS_OPTIONS.find((o) => o.value === status)?.label ?? `状态${status}`
+}
+
+/** 状态编码 → 标签类型（三色：执行中 primary / 已完成 success / 已终止 danger） */
+export function businessStatusTagType(status: number): 'primary' | 'success' | 'danger' | 'info' {
+  if (status === 2) return 'success'
+  if (status === 3) return 'danger'
+  return 'primary'
+}
+
+/** 分页查询业务（编号/公司名称模糊，可按状态/客户/归属/日期范围筛选） */
+export function listBusinesses(params: BusinessQueryParams): Promise<PageData<BusinessItem>> {
+  return request({ url: '/v1/business/businesses', method: 'get', params })
+}
+
+/** 创建业务（编号自动生成，写首条状态留痕） */
+export function createBusiness(data: BusinessCreateParams): Promise<BusinessItem> {
+  return request({ url: '/v1/business/businesses', method: 'post', data })
+}
+
+/** 业务详情（附产品明细行） */
+export function getBusinessDetail(businessId: number): Promise<BusinessDetail> {
+  return request({ url: `/v1/business/businesses/${businessId}`, method: 'get' })
+}
+
+/** 编辑业务（明细全量替换；归属不在此端点调整） */
+export function updateBusiness(
+  businessId: number,
+  data: BusinessUpdateParams,
+): Promise<BusinessItem> {
+  return request({ url: `/v1/business/businesses/${businessId}`, method: 'put', data })
+}
+
+/** 删除业务（有发货或回款记录时后端拒绝，应改为已终止） */
+export function deleteBusiness(businessId: number): Promise<null> {
+  return request({ url: `/v1/business/businesses/${businessId}`, method: 'delete' })
+}
+
+/** 状态流转（终态不可再变更；终止必填原因） */
+export function changeBusinessStatus(
+  businessId: number,
+  data: BusinessStatusParams,
+): Promise<BusinessItem> {
+  return request({ url: `/v1/business/businesses/${businessId}/status`, method: 'put', data })
+}
+
+/** 调整负责/协助营销人员（同事务写归属变更留痕） */
+export function changeBusinessOwnership(
+  businessId: number,
+  data: BusinessOwnershipParams,
+): Promise<BusinessItem> {
+  return request({ url: `/v1/business/businesses/${businessId}/ownership`, method: 'put', data })
+}
+
+/** 某业务的归属变更留痕（分页，按变更时间倒序） */
+export function listOwnershipLogs(
+  businessId: number,
+  params: { pageNum?: number; pageSize?: number },
+): Promise<PageData<OwnershipLogItem>> {
+  return request({
+    url: `/v1/business/businesses/${businessId}/ownership-logs`,
+    method: 'get',
+    params,
+  })
+}
+
+/** 某业务的状态流转时间线（分页，按时间正序，从创建起展示） */
+export function listStatusLogs(
+  businessId: number,
+  params: { pageNum?: number; pageSize?: number },
+): Promise<PageData<StatusLogItem>> {
+  return request({
+    url: `/v1/business/businesses/${businessId}/status-logs`,
+    method: 'get',
+    params,
+  })
+}
+
+/** 毛利润数据视图（as_of 缺省=今日；阈值按该时点参数快照） */
+export function getGrossProfit(
+  businessId: number,
+  asOf?: string,
+): Promise<GrossProfitView> {
+  return request({
+    url: `/v1/business/businesses/${businessId}/gross-profit`,
+    method: 'get',
+    params: asOf ? { as_of: asOf } : undefined,
+  })
+}
diff --git a/frontend/src/api/receipts.ts b/frontend/src/api/receipts.ts
new file mode 100644
index 0000000..3dbb437
--- /dev/null
+++ b/frontend/src/api/receipts.ts
@@ -0,0 +1,104 @@
+import { request } from './request'
+import type { PageData } from './types'
+
+/**
+ * 回款列表项（对应后端 `ReceiptOut`；字段契约纯蛇形直出）。
+ *
+ * amount 字符串直出（金额红线）；payment_days 为派生值：未指定发货
+ * 批次时为 null，指定后 = 发货日到回款日的天数（发货日计第 1 天）。
+ */
+export interface ReceiptItem {
+  id: number
+  receipt_batch_no: string
+  business_id: number
+  business_no: string
+  shipment_id: number | null
+  shipment_no: string | null
+  /** 回款到账日，ISO 串（YYYY-MM-DD）；M3 核算按此日匹配参数版本 */
+  receipt_date: string
+  /** 回款金额（元），字符串直出 */
+  amount: string
+  /** 以物抵顶标记：1是 0否（绩效按比例折算） */
+  is_barter: number
+  /** 核算状态：0未核算 1已核算（已核算禁改禁删） */
+  settlement_status: number
+  payment_days: number | null
+  remark: string | null
+}
+
+export interface ReceiptQueryParams {
+  pageNum?: number
+  pageSize?: number
+  business_id?: number
+  /** 回款到账日起（含），ISO 串 */
+  date_from?: string
+  /** 回款到账日止（含），ISO 串 */
+  date_to?: string
+  is_barter?: number
+  settlement_status?: number
+}
+
+/**
+ * 新增回款：业务必选，发货批次可暂不指定（手动指定）。
+ *
+ * shipment_id 须与本回款同属一个业务（后端强校验，数据完整性红线）。
+ */
+export interface ReceiptCreateParams {
+  business_id: number
+  shipment_id?: number | null
+  receipt_date: string
+  /** 数字字符串，非负，最多两位小数 */
+  amount: string
+  is_barter?: number
+  remark?: string | null
+}
+
+/**
+ * 编辑回款：全量替换语义；不含 business_id（挂靠业务创建时定死）。
+ *
+ * shipment_id 传 null = 清除指定（回到「暂未指定」）。
+ */
+export interface ReceiptUpdateParams {
+  shipment_id?: number | null
+  receipt_date: string
+  amount: string
+  is_barter?: number
+  remark?: string | null
+}
+
+/** 以物抵顶筛选项 */
+export const BARTER_OPTIONS = [
+  { label: '以物抵顶', value: 1 },
+  { label: '货币回款', value: 0 },
+] as const
+
+/** 核算状态筛选项（与列表标签文案一致） */
+export const SETTLEMENT_OPTIONS = [
+  { label: '已核算', value: 1 },
+  { label: '未核算', value: 0 },
+] as const
+
+/** 分页查询回款（附业务号/发货单号与回款天数派生值） */
+export function listReceipts(params: ReceiptQueryParams): Promise<PageData<ReceiptItem>> {
+  return request({ url: '/v1/business/receipts', method: 'get', params })
+}
+
+/** 新增回款（批次号自动生成 HK 前缀；业务须执行中） */
+export function createReceipt(data: ReceiptCreateParams): Promise<ReceiptItem> {
+  return request({ url: '/v1/business/receipts', method: 'post', data })
+}
+
+/** 回款详情（含回款天数派生值） */
+export function getReceiptDetail(receiptId: number): Promise<ReceiptItem> {
+  return request({ url: `/v1/business/receipts/${receiptId}`, method: 'get' })
+}
+
+/** 编辑回款（全量替换；已核算回款后端拒绝） */
+export function updateReceipt(receiptId: number, data: ReceiptUpdateParams): Promise<ReceiptItem> {
+  return request({ url: `/v1/business/receipts/${receiptId}`, method: 'put', data })
+}
+
+/** 删除回款（已核算/业务非执行中时后端拒绝；业务回款合计自动回退） */
+export function deleteReceipt(receiptId: number): Promise<null> {
+  return request({ url: `/v1/business/receipts/${receiptId}`, method: 'delete' })
+}
diff --git a/frontend/src/api/shipments.ts b/frontend/src/api/shipments.ts
new file mode 100644
index 0000000..7feb2eb
--- /dev/null
+++ b/frontend/src/api/shipments.ts
@@ -0,0 +1,117 @@
+import { request } from './request'
+import type { PageData } from './types'
+
+/**
+ * 发货产品明细行（对应后端 `ShipmentItemOut`）。
+ *
+ * 数量/单价/行金额一律字符串直出 —— 金额红线：不经 float、不 toFixed；
+ * 行金额 = 数量 × 单价由后端计算固化，不信任前端传值。
+ */
+export interface ShipmentItemRow {
+  id: number
+  product_id: number | null
+  product_name: string
+  spec_model: string | null
+  unit: string | null
+  /** 数字字符串，>0 */
+  quantity: string
+  /** 发货单价，可空 = 待人工补价（补价前行金额记 0） */
+  sale_price: string | null
+  /** 行金额，后端按数量×单价计算固化 */
+  amount: string
+}
+
+/** 发货单列表项（对应后端 `ShipmentOut`；business_no 为联表附带列） */
+export interface ShipmentItem {
+  id: number
+  shipment_no: string
+  business_id: number
+  business_no: string | null
+  /** ISO 串（YYYY-MM-DD）；发货日是回款天数计算基准日（发货日计第 1 天） */
+  ship_date: string
+  /** 运费（元），仅记录展示，不计入毛利润口径 */
+  freight_amount: string
+  /** 发货总金额，后端按明细固化 */
+  total_amount: string
+  remark: string | null
+}
+
+/** 发货单详情：附产品明细行（编辑弹窗一次回显） */
+export interface ShipmentDetail extends ShipmentItem {
+  items: ShipmentItemRow[]
+}
+
+export interface ShipmentQueryParams {
+  pageNum?: number
+  pageSize?: number
+  /** 业务筛选，空 = 全部 */
+  business_id?: number
+  /** 发货日期起（含），ISO 串 */
+  ship_date_from?: string
+  /** 发货日期止（含），ISO 串 */
+  ship_date_to?: string
+}
+
+/** 发货明细行入参（product_id 空 = 自由录入；单价可空=待人工补价） */
+export interface ShipmentItemParams {
+  product_id?: number | null
+  product_name: string
+  spec_model?: string | null
+  unit?: string | null
+  quantity: string
+  sale_price?: string | null
+}
+
+/**
+ * 创建发货单：业务维度 + 明细行（≥1）。
+ *
+ * 业务须处于执行中（后端校验）；ship_date 为回款天数计算基准日。
+ */
+export interface ShipmentCreateParams {
+  business_id: number
+  ship_date: string
+  freight_amount?: string | null
+  items: ShipmentItemParams[]
+  remark?: string | null
+}
+
+/**
+ * 编辑发货单：明细全量替换。
+ *
+ * 不含 business_id —— 发货单挂靠的业务创建时定死，改挂会让已指定
+ * 本发货单的回款语义断裂。
+ */
+export interface ShipmentUpdateParams {
+  ship_date: string
+  freight_amount?: string | null
+  items: ShipmentItemParams[]
+  remark?: string | null
+}
+
+/** 分页查询发货单（附业务编号，可按业务/发货日期范围筛选） */
+export function listShipments(params: ShipmentQueryParams): Promise<PageData<ShipmentItem>> {
+  return request({ url: '/v1/business/shipments', method: 'get', params })
+}
+
+/** 创建发货单（明细 ≥1；业务须执行中） */
+export function createShipment(data: ShipmentCreateParams): Promise<ShipmentItem> {
+  return request({ url: '/v1/business/shipments', method: 'post', data })
+}
+
+/** 发货单详情（附产品明细行） */
+export function getShipmentDetail(shipmentId: number): Promise<ShipmentDetail> {
+  return request({ url: `/v1/business/shipments/${shipmentId}`, method: 'get' })
+}
+
+/** 编辑发货单（明细全量替换；终态业务的发货单后端拒绝） */
+export function updateShipment(
+  shipmentId: number,
+  data: ShipmentUpdateParams,
+): Promise<ShipmentItem> {
+  return request({ url: `/v1/business/shipments/${shipmentId}`, method: 'put', data })
+}
+
+/** 删除发货单（连带明细并回写业务汇总；被回款批次指定时后端拒绝） */
+export function deleteShipment(shipmentId: number): Promise<null> {
+  return request({ url: `/v1/business/shipments/${shipmentId}`, method: 'delete' })
+}
diff --git a/frontend/src/router/index.ts b/frontend/src/router/index.ts
index b8f8836..b3fb951 100644
--- a/frontend/src/router/index.ts
+++ b/frontend/src/router/index.ts
@@ -89,6 +89,25 @@ const routes: RouteRecordRaw[] = [
         component: () => import('@/views/base/customers/index.vue'),
         meta: { title: '客户管理', group: '基础数据', order: 10 },
       },
+      {
+        // 业务数据组一律为业务操作：登录即可访问，不设 requiresAdmin
+        path: '/business/businesses',
+        name: 'business-businesses',
+        component: () => import('@/views/business/businesses/index.vue'),
+        meta: { title: '业务管理', group: '业务数据', order: 11 },
+      },
+      {
+        path: '/business/shipments',
+        name: 'business-shipments',
+        component: () => import('@/views/business/shipments/index.vue'),
+        meta: { title: '发货管理', group: '业务数据', order: 12 },
+      },
+      {
+        path: '/business/receipts',
+        name: 'business-receipts',
+        component: () => import('@/views/business/receipts/index.vue'),
+        meta: { title: '回款管理', group: '业务数据', order: 13 },
+      },
       {
         // 业务数据组首个页面：评级计算器是打分工具，不影响绩效金额，
         // 登录用户即可用，不设 requiresAdmin（区别于系统管理组）
diff --git a/frontend/src/views/business/businesses/index.vue b/frontend/src/views/business/businesses/index.vue
new file mode 100644
index 0000000..ae3769a
--- /dev/null
+++ b/frontend/src/views/business/businesses/index.vue
@@ -0,0 +1,1309 @@
+<script setup lang="ts">
+import { computed, onMounted, reactive, ref } from 'vue'
+import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
+
+import * as businessApi from '@/api/businesses'
+import { businessStatusLabel } from '@/api/businesses'
+import type { BusinessDetail, BusinessItem, GrossProfitView, StatusLogItem } from '@/api/businesses'
+import * as customerApi from '@/api/customers'
+import * as personnelApi from '@/api/personnel'
+import { productCategoryLabel } from '@/api/products'
+import AppPagination from '@/components/table/AppPagination.vue'
+import { useConfirmAction } from '@/composables/useConfirmAction'
+import { usePagedList } from '@/composables/usePagedList'
+import { formatDateTime } from '@/utils/format'
+import { handledError } from '@/utils/error'
+
+/**
+ * 业务管理（需求 2.2.1/2.2.4：业务台账 + 产品明细 + 状态机 + 归属留痕 + 毛利润视图）。
+ *
+ * 与后端约定对齐：
+ * - 创建/编辑弹窗承载明细行编辑器（明细 ≥1 行，编辑为全量替换）；
+ *   编辑端点忽略归属字段 —— 归属调整统一走「归属调整」按钮（PUT /{id}/ownership），
+ *   是唯一写归属留痕的入口
+ * - 状态流转独立操作（执行中 → 已完成/已终止；终止必填原因，终态不可再变更）
+ * - 金额/数量字符串直出与提交（金额红线：不经 float、不 toFixed）
+ * - 详情抽屉含状态时间线（status-logs 按时间正序）、归属留痕（分页倒序）、
+ *   毛利润视图（categories 汇总卡片 + rows 行级明细；毛利润率是分数字符串原样展示）
+ */
+const { confirmAndRun } = useConfirmAction()
+
+// ==================== 列表 ====================
+
+const filters = reactive({
+  keyword: '',
+  status: undefined as number | undefined,
+})
+/** 日期范围单独存（el-date-picker daterange 回参是 [起, 止]） */
+const dateRange = ref<[string, string] | null>(null)
+
+const { records, total, pageNum, pageSize, loading, load, search, onPageChange, onSizeChange, reloadAfterDelete } =
+  usePagedList<BusinessItem, businessApi.BusinessQueryParams>(
+    businessApi.listBusinesses,
+    () => ({
+      keyword: filters.keyword,
+      status: filters.status,
+      date_from: dateRange.value?.[0],
+      date_to: dateRange.value?.[1],
+    }),
+  )
+
+function resetFilters(): void {
+  filters.keyword = ''
+  filters.status = undefined
+  dateRange.value = null
+  search()
+}
+
+// ==================== 客户 / 人员下拉数据源 ====================
+
+interface CustomerOption {
+  id: number
+  name: string
+}
+
+interface PersonnelOption {
+  id: number
+  name: string
+  status: number
+}
+
+const customerOptions = ref<CustomerOption[]>([])
+const personnelOptions = ref<PersonnelOption[]>([])
+
+async function loadCustomerOptions(): Promise<void> {
+  try {
+    // 客户下拉的近似全量数据源：内部系统规模有限，200 条足够；超出由后端校验兜底
+    const data = await customerApi.listCustomers({ pageNum: 1, pageSize: 200 })
+    customerOptions.value = data.list.map((c) => ({ id: c.id, name: c.company_name }))
+  } catch (error) {
+    handledError(error) // 下拉为空不阻断列表使用
+  }
+}
+
+async function loadPersonnelOptions(): Promise<void> {
+  try {
+    const data = await personnelApi.listPersonnel({ pageNum: 1, pageSize: 200 })
+    personnelOptions.value = data.list.map((p) => ({
+      id: p.id,
+      name: p.personnel_name,
+      status: p.status,
+    }))
+  } catch (error) {
+    handledError(error)
+  }
+}
+
+/** 下拉项展示名：离职人员加后缀标注（可否被选由后端归属校验兜底） */
+function personnelLabel(option: PersonnelOption): string {
+  return option.status === 1 ? option.name : `${option.name}（离职）`
+}
+
+// ==================== 新增 / 编辑（含明细行编辑器） ====================
+
+/** 金额/数量形态：非负数字、最多两位小数（纯形态校验，不涉及 float 运算） */
+const AMOUNT_PATTERN = /^(\d+)(\.\d{1,2})?$/
+/** 全零形态：数量用它排除「>0」语义，不走 float 比较 */
+const ZERO_PATTERN = /^0+(\.0+)?$/
+
+const dialogVisible = ref(false)
+const editingId = ref<number | null>(null)
+/** 单一状态源：编辑中 ⇔ editingId 非空（避免双状态漂移） */
+const isEdit = computed(() => editingId.value !== null)
+const formRef = ref<FormInstance>()
+const submitting = ref(false)
+
+/** 明细行草稿（编辑时由详情回显；全量替换，行 id 不参与提交） */
+interface ItemDraft {
+  product_name: string
+  spec_model: string
+  unit: string
+  product_category: string
+  quantity: string
+  sale_price: string
+  cost_amount: string
+  guided_price: string
+}
+
+const form = reactive({
+  customer_id: undefined as number | undefined,
+  business_date: '',
+  owner_personnel_id: undefined as number | undefined,
+  assistant_personnel_id: undefined as number | undefined,
+  is_special: 0,
+  special_note: '',
+  remark: '',
+})
+
+/** 默认落在首个类别上，避免空类别提交被后端拒 */
+function emptyItem(): ItemDraft {
+  return {
+    product_name: '',
+    spec_model: '',
+    unit: '',
+    product_category: 'municipal_water',
+    quantity: '',
+    sale_price: '',
+    cost_amount: '',
+    guided_price: '',
+  }
+}
+
+const itemRows = ref<ItemDraft[]>([])
+
+const rules = computed<FormRules>(() => ({
+  customer_id: [{ required: true, message: '请选择客户', trigger: 'change' }],
+  special_note: [
+    {
+      required: form.is_special === 1,
+      message: '特殊业务必须填写说明',
+      trigger: 'blur',
+    },
+    { max: 255, message: '说明最长 255 个字符', trigger: 'blur' },
+  ],
+  remark: [{ max: 255, message: '备注最长 255 个字符', trigger: 'blur' }],
+}))
+
+function openCreate(): void {
+  editingId.value = null
+  Object.assign(form, {
+    customer_id: undefined,
+    business_date: '',
+    owner_personnel_id: undefined,
+    assistant_personnel_id: undefined,
+    is_special: 0,
+    special_note: '',
+    remark: '',
+  })
+  itemRows.value = [emptyItem()] // 预置一空行，用户可直接填写
+  dialogVisible.value = true
+  formRef.value?.clearValidate()
+}
+
+async function openEdit(row: BusinessItem): Promise<void> {
+  editingId.value = row.id
+  dialogVisible.value = true
+  const detail: BusinessDetail | null = await businessApi.getBusinessDetail(row.id).catch((error) => {
+    handledError(error) // 失败提示由请求拦截器统一完成，弹窗保持空表
+    return null
+  })
+  if (!detail) return
+  Object.assign(form, {
+    customer_id: detail.customer_id,
+    business_date: detail.business_date ?? '',
+    owner_personnel_id: detail.owner_personnel_id ?? undefined,
+    assistant_personnel_id: detail.assistant_personnel_id ?? undefined,
+    is_special: detail.is_special,
+    special_note: detail.special_note ?? '',
+    remark: detail.remark ?? '',
+  })
+  itemRows.value = detail.items.map((it) => ({
+    product_name: it.product_name,
+    spec_model: it.spec_model ?? '',
+    unit: it.unit ?? '',
+    product_category: it.product_category,
+    quantity: it.quantity,
+    sale_price: it.sale_price ?? '',
+    cost_amount: it.cost_amount ?? '',
+    guided_price: it.guided_price ?? '',
+  }))
+  formRef.value?.clearValidate()
+}
+
+function addItemRow(): void {
+  itemRows.value.push(emptyItem())
+}
+
+function removeItemRow(index: number): void {
+  itemRows.value.splice(index, 1)
+}
+
+/**
+ * 明细行校验：返回第一处问题的提示文案，全部通过返回 null。
+ *
+ * 数量须 >0（靠全零形态排除，不走 float 比较）；金额选填，填写时须
+ * 非负且最多两位小数 —— 与后端 `_check_amount` 同一口径的前端闸门。
+ */
+function validateItemRows(rows: ItemDraft[]): string | null {
+  if (rows.length === 0) return '请至少录入一行产品明细'
+  for (let i = 0; i < rows.length; i += 1) {
+    const row = rows[i]
+    const no = `第 ${i + 1} 行`
+    if (!row.product_name.trim()) return `${no}的产品名称未填写`
+    if (!AMOUNT_PATTERN.test(row.quantity) || ZERO_PATTERN.test(row.quantity)) {
+      return `${no}的数量须为大于 0 的数字，最多两位小数`
+    }
+    const prices = [
+      ['销售单价', row.sale_price],
+      ['成本额', row.cost_amount],
+      ['指导价', row.guided_price],
+    ] as const
+    for (const [label, value] of prices) {
+      if (value.trim() && !AMOUNT_PATTERN.test(value.trim())) {
+        return `${no}的${label}须为非负数字，最多两位小数`
+      }
+    }
+  }
+  return null
+}
+
+/** 明细草稿 → 提交行（空串归一为 null，与后端「空串归一」口径一致） */
+function buildItemParams(rows: ItemDraft[]): businessApi.BusinessItemParams[] {
+  return rows.map((row) => ({
+    product_name: row.product_name.trim(),
+    spec_model: row.spec_model.trim() || null,
+    unit: row.unit.trim() || null,
+    product_category: row.product_category,
+    quantity: row.quantity.trim(),
+    sale_price: row.sale_price.trim() || null,
+    cost_amount: row.cost_amount.trim() || null,
+    guided_price: row.guided_price.trim() || null,
+  }))
+}
+
+async function handleSubmit(): Promise<void> {
+  const valid = await formRef.value?.validate().catch(() => false)
+  if (!valid) return
+
+  const rowError = validateItemRows(itemRows.value)
+  if (rowError) {
+    ElMessage.warning(rowError)
+    return
+  }
+
+  submitting.value = true
+  try {
+    if (editingId.value !== null) {
+      // 编辑端点不含归属：归属调整统一走「归属调整」按钮，保证留痕完整
+      await businessApi.updateBusiness(editingId.value, {
+        customer_id: form.customer_id as number,
+        business_date: form.business_date || null,
+        is_special: form.is_special,
+        special_note: form.is_special === 1 ? form.special_note.trim() || null : null,
+        items: buildItemParams(itemRows.value),
+        remark: form.remark.trim() || null,
+      })
+      ElMessage.success('已保存')
+    } else {
+      await businessApi.createBusiness({
+        customer_id: form.customer_id as number,
+        business_date: form.business_date || null,
+        owner_personnel_id: form.owner_personnel_id ?? null,
+        assistant_personnel_id: form.assistant_personnel_id ?? null,
+        is_special: form.is_special,
+        special_note: form.is_special === 1 ? form.special_note.trim() || null : null,
+        items: buildItemParams(itemRows.value),
+        remark: form.remark.trim() || null,
+      })
+      ElMessage.success('业务已创建')
+    }
+    dialogVisible.value = false
+    await load()
+  } catch (error) {
+    handledError(error) // 失败提示由请求拦截器统一完成
+  } finally {
+    submitting.value = false
+  }
+}
+
+// ==================== 状态流转 ====================
+
+const statusVisible = ref(false)
+const statusTarget = ref<BusinessItem | null>(null)
+const statusSubmitting = ref(false)
+const statusForm = reactive({
+  status: 2,
+  reason: '',
+})
+
+function openStatus(row: BusinessItem): void {
+  statusTarget.value = row
+  statusForm.status = 2
+  statusForm.reason = ''
+  statusVisible.value = true
+}
+
+async function handleStatusSubmit(): Promise<void> {
+  const target = statusTarget.value
+  if (!target) return
+  if (statusForm.status === 3 && !statusForm.reason.trim()) {
+    ElMessage.warning('终止业务必须填写原因')
+    return
+  }
+
+  const targetLabel = businessStatusLabel(statusForm.status)
+  await confirmAndRun({
+    confirmText:
+      statusForm.status === 3
+        ? `确定终止业务「${target.business_no}」？终态不可再变更，请确认发货与回款均已处理完毕。`
+        : `确定将业务「${target.business_no}」标记为已完成？终态不可再变更。`,
+    title: '状态流转确认',
+    confirmButtonText: targetLabel,
+    successText: '状态已变更',
+    run: async () => {
+      statusSubmitting.value = true
+      try {
+        await businessApi.changeBusinessStatus(target.id, {
+          status: statusForm.status,
+          reason: statusForm.status === 3 ? statusForm.reason.trim() : null,
+        })
+      } finally {
+        statusSubmitting.value = false
+      }
+    },
+    after: async () => {
+      statusVisible.value = false
+      await load()
+      // 详情抽屉开着且正是该业务时，同步刷新时间线与毛利润视图
+      await refreshDrawer(target.id)
+    },
+  })
+}
+
+// ==================== 归属调整 ====================
+
+const ownershipVisible = ref(false)
+const ownershipTarget = ref<BusinessItem | null>(null)
+const ownershipSubmitting = ref(false)
+const ownershipForm = reactive({
+  new_owner_personnel_id: undefined as number | undefined,
+  new_assistant_personnel_id: undefined as number | undefined,
+  reason: '',
+})
+
+function openOwnership(row: BusinessItem): void {
+  ownershipTarget.value = row
+  ownershipForm.new_owner_personnel_id = row.owner_personnel_id ?? undefined
+  ownershipForm.new_assistant_personnel_id = row.assistant_personnel_id ?? undefined
+  ownershipForm.reason = ''
+  ownershipVisible.value = true
+}
+
+async function handleOwnershipSubmit(): Promise<void> {
+  const target = ownershipTarget.value
+  if (!target) return
+
+  const nextOwnerId = ownershipForm.new_owner_personnel_id ?? null
+  const nextAssistantId = ownershipForm.new_assistant_personnel_id ?? null
+  if (nextOwnerId === (target.owner_personnel_id ?? null) && nextAssistantId === (target.assistant_personnel_id ?? null)) {
+    ElMessage.warning('负责与协助均未变化，请至少调整一项后再提交')
+    return
+  }
+
+  const ownerName = nextOwnerId === null ? '（清空负责）' : personnelName(nextOwnerId)
+  const assistantName = nextAssistantId === null ? '（无协助）' : personnelName(nextAssistantId)
+  await confirmAndRun({
+    // 归属留痕只影响变更后的核算，不回溯历史 —— 文案保留业务口径
+    confirmText: `确定调整业务「${target.business_no}」的归属？负责：${ownerName}；协助：${assistantName}。归属变更仅影响变更后核算，不回溯历史。`,
+    title: '归属调整确认',
+    confirmButtonText: '确认调整',
+    successText: '归属已调整',
+    run: async () => {
+      ownershipSubmitting.value = true
+      try {
+        await businessApi.changeBusinessOwnership(target.id, {
+          new_owner_personnel_id: nextOwnerId,
+          new_assistant_personnel_id: nextAssistantId,
+          reason: ownershipForm.reason.trim() || null,
+        })
+      } finally {
+        ownershipSubmitting.value = false
+      }
+    },
+    after: async () => {
+      ownershipVisible.value = false
+      await load()
+      await refreshDrawer(target.id)
+    },
+  })
+}
+
+function personnelName(id: number): string {
+  return personnelOptions.value.find((o) => o.id === id)?.name ?? `人员#${id}`
+}
+
+// ==================== 详情抽屉 ====================
+
+const drawerVisible = ref(false)
+const drawerRowId = ref<number | null>(null)
+const drawerRow = ref<BusinessItem | null>(null)
+const drawerTitle = computed(() =>
+  drawerRow.value ? `「${drawerRow.value.business_no}」· 业务详情` : '业务详情',
+)
+const detail = ref<BusinessDetail | null>(null)
+const statusLogs = ref<StatusLogItem[]>([])
+const gp = ref<GrossProfitView | null>(null)
+const drawerLoading = ref(false)
+
+async function loadDrawerData(id: number): Promise<void> {
+  drawerLoading.value = true
+  try {
+    // 状态流转频次低，50 条足够覆盖从创建起的完整时间线
+    const [detailData, logData, profitData] = await Promise.all([
+      businessApi.getBusinessDetail(id),
+      businessApi.listStatusLogs(id, { pageNum: 1, pageSize: 50 }),
+      businessApi.getGrossProfit(id),
+    ])
+    detail.value = detailData
+    statusLogs.value = logData.list
+    gp.value = profitData
+  } catch (error) {
+    handledError(error) // 失败提示由请求拦截器统一完成，抽屉显示空分区
+  } finally {
+    drawerLoading.value = false
+  }
+}
+
+/** 抽屉开着且正是该业务时刷新（状态流转/归属调整后调用） */
+async function refreshDrawer(id: number): Promise<void> {
+  if (!drawerVisible.value || drawerRowId.value !== id) return
+  void loadDrawerData(id)
+  void loadOwnershipLogs()
+}
+
+function openDrawer(row: BusinessItem): void {
+  drawerRow.value = row
+  drawerRowId.value = row.id
+  drawerVisible.value = true
+  detail.value = null
+  statusLogs.value = []
+  gp.value = null
+  ownershipLogsId.value = row.id
+  ownershipLogPageNum.value = 1
+  void loadDrawerData(row.id)
+  void loadOwnershipLogs()
+}
+
+// ---- 抽屉分区④：归属变更记录（分页留痕，按变更时间倒序） ----
+
+const {
+  records: ownershipLogs,
+  total: ownershipLogTotal,
+  pageNum: ownershipLogPageNum,
+  pageSize: ownershipLogPageSize,
+  loading: ownershipLogsLoading,
+  load: loadOwnershipLogs,
+  onPageChange: onOwnershipLogPageChange,
+  onSizeChange: onOwnershipLogSizeChange,
+} = usePagedList<businessApi.OwnershipLogItem, object>(
+  (params) => {
+    const id = ownershipLogsId.value
+    // 抽屉未指定业务时兜底空数据，避免发出无意义请求
+    return id === null
+      ? Promise.resolve({ list: [], total: 0, pageNum: 1, pageSize: 10 })
+      : businessApi.listOwnershipLogs(id, params)
+  },
+  () => ({}),
+)
+
+const ownershipLogsId = ref<number | null>(null)
+
+/** 留痕展示：负责/协助的新旧人员（姓名随联表，ID 固化） */
+function ownershipTransition(row: businessApi.OwnershipLogItem): string {
+  const oldOwner = row.old_owner_name ?? '（无）'
+  const newOwner = row.new_owner_name ?? '（无）'
+  const oldAssistant = row.old_assistant_personnel_id === null ? '（无）' : `#${row.old_assistant_personnel_id}`
+  const newAssistant = row.new_assistant_personnel_id === null ? '（无）' : `#${row.new_assistant_personnel_id}`
+  return `负责 ${oldOwner} → ${newOwner}；协助 ${oldAssistant} → ${newAssistant}`
+}
+
+// ==================== 删除 ====================
+
+async function handleDelete(row: BusinessItem): Promise<void> {
+  await confirmAndRun({
+    confirmText: `确定删除业务「${row.business_no}」？删除为物理删除、不可恢复；有发货或回款记录时不可删除，请改为已终止。`,
+    title: '删除确认',
+    confirmButtonText: '删除',
+    successText: '业务已删除',
+    run: () => businessApi.deleteBusiness(row.id),
+    after: reloadAfterDelete,
+  })
+}
+
+// ==================== 初始化 ====================
+
+onMounted(() => {
+  // 三个请求各自容错（load 内部已兜底），互不拖累
+  void load()
+  void loadCustomerOptions()
+  void loadPersonnelOptions()
+})
+</script>
+
+<template>
+  <div>
+    <el-card shadow="never">
+      <el-form class="filter-form" :inline="true" @submit.prevent>
+        <el-form-item label="关键词">
+          <el-input
+            v-model="filters.keyword"
+            placeholder="业务编号或公司名称"
+            clearable
+            style="width: 190px"
+            @keyup.enter="search"
+          />
+        </el-form-item>
+        <el-form-item label="状态">
+          <el-select v-model="filters.status" placeholder="全部" clearable style="width: 110px">
+            <el-option
+              v-for="item in businessApi.BUSINESS_STATUS_OPTIONS"
+              :key="item.value"
+              :label="item.label"
+              :value="item.value"
+            />
+          </el-select>
+        </el-form-item>
+        <el-form-item label="业务日期">
+          <el-date-picker
+            v-model="dateRange"
+            type="daterange"
+            value-format="YYYY-MM-DD"
+            range-separator="至"
+            start-placeholder="起"
+            end-placeholder="止"
+            style="width: 240px"
+          />
+        </el-form-item>
+        <el-form-item>
+          <el-button type="primary" @click="search">查询</el-button>
+          <el-button @click="resetFilters">重置</el-button>
+        </el-form-item>
+      </el-form>
+
+      <div class="toolbar">
+        <el-button type="primary" @click="openCreate">新增业务</el-button>
+      </div>
+
+      <el-table v-loading="loading" :data="records" stripe>
+        <el-table-column prop="business_no" label="业务编号" min-width="150" />
+        <el-table-column prop="customer_name" label="客户名称" min-width="160">
+          <template #default="{ row }">{{ row.customer_name ?? '—' }}</template>
+        </el-table-column>
+        <el-table-column prop="business_date" label="业务日期" min-width="110">
+          <template #default="{ row }">{{ row.business_date ?? '—' }}</template>
+        </el-table-column>
+        <el-table-column label="状态" width="90" align="center">
+          <template #default="{ row }">
+            <el-tag
+              :type="businessApi.businessStatusTagType(row.status)"
+              size="small"
+              disable-transitions
+            >
+              {{ businessApi.businessStatusLabel(row.status) }}
+            </el-tag>
+          </template>
+        </el-table-column>
+        <el-table-column prop="owner_personnel_name" label="负责人员" min-width="100">
+          <template #default="{ row }">{{ row.owner_personnel_name ?? '（待指定）' }}</template>
+        </el-table-column>
+        <el-table-column prop="assistant_personnel_name" label="协助人员" min-width="100">
+          <template #default="{ row }">{{ row.assistant_personnel_name ?? '—' }}</template>
+        </el-table-column>
+        <el-table-column label="销售额（元）" min-width="120" align="right">
+          <template #default="{ row }">
+            <!-- 字符串直出：金额红线，禁 toFixed / float 格式化 -->
+            <span class="cell-amount">{{ row.total_sale_amount ?? '—' }}</span>
+          </template>
+        </el-table-column>
+        <el-table-column label="成本（元）" min-width="120" align="right">
+          <template #default="{ row }">
+            <span class="cell-amount">{{ row.total_cost_amount ?? '—' }}</span>
+          </template>
+        </el-table-column>
+        <el-table-column label="发货额（元）" min-width="120" align="right">
+          <template #default="{ row }">
+            <span class="cell-amount">{{ row.total_ship_amount ?? '—' }}</span>
+          </template>
+        </el-table-column>
+        <el-table-column label="回款额（元）" min-width="120" align="right">
+          <template #default="{ row }">
+            <span class="cell-amount">{{ row.total_received_amount ?? '—' }}</span>
+          </template>
+        </el-table-column>
+        <el-table-column label="操作" width="300" fixed="right">
+          <template #default="{ row }">
+            <el-button link type="primary" size="small" @click="openDrawer(row)">详情</el-button>
+            <el-button link type="primary" size="small" @click="openEdit(row)">编辑</el-button>
+            <el-tooltip content="终态不可再变更" :disabled="row.status === 1" placement="top">
+              <span class="op-wrap">
+                <el-button
+                  link
+                  type="primary"
+                  size="small"
+                  :disabled="row.status !== 1"
+                  @click="openStatus(row)"
+                >
+                  状态
+                </el-button>
+              </span>
+            </el-tooltip>
+            <el-button link type="primary" size="small" @click="openOwnership(row)">归属</el-button>
+            <el-button link type="danger" size="small" @click="handleDelete(row)">删除</el-button>
+          </template>
+        </el-table-column>
+      </el-table>
+
+      <AppPagination
+        :total="total"
+        :page-num="pageNum"
+        :page-size="pageSize"
+        @page-change="onPageChange"
+        @size-change="onSizeChange"
+      />
+    </el-card>
+
+    <!-- 新增 / 编辑（含明细行编辑器；编辑不含归属，归属走独立按钮保证留痕） -->
+    <el-dialog
+      v-model="dialogVisible"
+      :title="isEdit ? '编辑业务' : '新增业务'"
+      width="980px"
+      destroy-on-close
+    >
+      <el-form ref="formRef" :model="form" :rules="rules" label-width="96px">
+        <el-row :gutter="16">
+          <el-col :span="12">
+            <el-form-item label="客户" prop="customer_id">
+              <el-select
+                v-model="form.customer_id"
+                placeholder="选择业务客户"
+                filterable
+                style="width: 100%"
+              >
+                <el-option
+                  v-for="item in customerOptions"
+                  :key="item.id"
+                  :label="item.name"
+                  :value="item.id"
+                />
+              </el-select>
+            </el-form-item>
+          </el-col>
+          <el-col :span="12">
+            <el-form-item label="业务日期" prop="business_date">
+              <el-date-picker
+                v-model="form.business_date"
+                type="date"
+                value-format="YYYY-MM-DD"
+                placeholder="选填"
+                style="width: 100%"
+              />
+            </el-form-item>
+          </el-col>
+          <el-col :span="12">
+            <el-form-item label="负责人员" prop="owner_personnel_id">
+              <el-select
+                v-model="form.owner_personnel_id"
+                placeholder="不选择=待指定"
+                clearable
+                filterable
+                style="width: 100%"
+              >
+                <el-option
+                  v-for="item in personnelOptions"
+                  :key="item.id"
+                  :label="personnelLabel(item)"
+                  :value="item.id"
+                />
+              </el-select>
+            </el-form-item>
+          </el-col>
+          <el-col :span="12">
+            <el-form-item label="协助人员" prop="assistant_personnel_id">
+              <el-select
+                v-model="form.assistant_personnel_id"
+                placeholder="选填"
+                clearable
+                filterable
+                style="width: 100%"
+              >
+                <el-option
+                  v-for="item in personnelOptions"
+                  :key="item.id"
+                  :label="personnelLabel(item)"
+                  :value="item.id"
+                />
+              </el-select>
+            </el-form-item>
+          </el-col>
+          <el-col :span="24">
+            <el-form-item label="特殊业务" prop="is_special">
+              <el-switch v-model="form.is_special" :active-value="1" :inactive-value="0" />
+              <span class="switch-hint">特殊业务需填写说明以便追溯（影响计提规则匹配时勾选）</span>
+            </el-form-item>
+          </el-col>
+          <el-col v-if="form.is_special === 1" :span="24">
+            <el-form-item label="特殊说明" prop="special_note">
+              <el-input
+                v-model="form.special_note"
+                type="textarea"
+                :rows="2"
+                maxlength="255"
+                placeholder="说明特殊在何处（必填）"
+              />
+            </el-form-item>
+          </el-col>
+        </el-row>
+      </el-form>
+
+      <div class="items-head">
+        <span class="items-title">产品明细（至少 1 行，编辑为全量替换）</span>
+        <el-button size="small" @click="addItemRow">添加一行</el-button>
+      </div>
+      <el-table :data="itemRows" stripe size="small" class="items-table">
+        <el-table-column label="产品名称" min-width="170">
+          <template #default="{ row }">
+            <el-input v-model="row.product_name" maxlength="128" placeholder="产品名称，可手填" />
+          </template>
+        </el-table-column>
+        <el-table-column label="规格型号" min-width="120">
+          <template #default="{ row }">
+            <el-input v-model="row.spec_model" maxlength="128" placeholder="选填" />
+          </template>
+        </el-table-column>
+        <el-table-column label="单位" min-width="80">
+          <template #default="{ row }">
+            <el-input v-model="row.unit" maxlength="16" placeholder="如 台" />
+          </template>
+        </el-table-column>
+        <el-table-column label="类别" min-width="120">
+          <template #default="{ row }">
+            <el-select v-model="row.product_category" style="width: 100%">
+              <el-option label="市政水利" value="municipal_water" />
+              <el-option label="轨道交通" value="rail_transit" />
+            </el-select>
+          </template>
+        </el-table-column>
+        <el-table-column label="数量" min-width="100">
+          <template #default="{ row }">
+            <el-input v-model="row.quantity" placeholder=">0" />
+          </template>
+        </el-table-column>
+        <el-table-column label="销售单价" min-width="110">
+          <template #default="{ row }">
+            <el-input v-model="row.sale_price" placeholder="元，选填" />
+          </template>
+        </el-table-column>
+        <el-table-column label="成本额" min-width="110">
+          <template #default="{ row }">
+            <el-input v-model="row.cost_amount" placeholder="元，选填" />
+          </template>
+        </el-table-column>
+        <el-table-column label="指导价" min-width="110">
+          <template #default="{ row }">
+            <el-input v-model="row.guided_price" placeholder="元，选填" />
+          </template>
+        </el-table-column>
+        <el-table-column label="操作" width="70" align="center">
+          <template #default="{ $index }">
+            <el-button link type="danger" size="small" @click="removeItemRow($index)">删除</el-button>
+          </template>
+        </el-table-column>
+      </el-table>
+
+      <el-form label-width="96px" class="tail-form" @submit.prevent>
+        <el-form-item label="备注" prop="remark">
+          <el-input v-model="form.remark" type="textarea" :rows="2" maxlength="255" placeholder="选填" />
+        </el-form-item>
+      </el-form>
+      <template #footer>
+        <el-button @click="dialogVisible = false">取消</el-button>
+        <el-button type="primary" :loading="submitting" @click="handleSubmit">保存</el-button>
+      </template>
+    </el-dialog>
+
+    <!-- 状态流转（执行中 → 已完成/已终止；终止必填原因） -->
+    <el-dialog v-model="statusVisible" title="状态流转" width="480px" destroy-on-close>
+      <el-form label-width="90px">
+        <el-form-item label="业务">
+          <span>{{ statusTarget?.business_no }}</span>
+        </el-form-item>
+        <el-form-item label="目标状态">
+          <el-radio-group v-model="statusForm.status">
+            <el-radio :value="2">已完成</el-radio>
+            <el-radio :value="3">已终止</el-radio>
+          </el-radio-group>
+        </el-form-item>
+        <el-form-item label="变更原因">
+          <el-input
+            v-model="statusForm.reason"
+            type="textarea"
+            :rows="3"
+            maxlength="255"
+            :placeholder="statusForm.status === 3 ? '终止原因（必填）' : '选填，将写入状态流转留痕'"
+          />
+        </el-form-item>
+      </el-form>
+      <div class="op-warn">状态流转后终态不可再变更；变更将写入状态流转时间线。</div>
+      <template #footer>
+        <el-button @click="statusVisible = false">取消</el-button>
+        <el-button type="primary" :loading="statusSubmitting" @click="handleStatusSubmit">
+          确认变更
+        </el-button>
+      </template>
+    </el-dialog>
+
+    <!-- 归属调整（唯一写归属留痕的入口） -->
+    <el-dialog v-model="ownershipVisible" title="归属调整" width="500px" destroy-on-close>
+      <el-form label-width="110px">
+        <el-form-item label="业务">
+          <span>{{ ownershipTarget?.business_no }}</span>
+        </el-form-item>
+        <el-form-item label="新负责人员">
+          <el-select
+            v-model="ownershipForm.new_owner_personnel_id"
+            placeholder="不选择并提交=清空负责"
+            clearable
+            filterable
+            style="width: 100%"
+          >
+            <el-option
+              v-for="item in personnelOptions"
+              :key="item.id"
+              :label="personnelLabel(item)"
+              :value="item.id"
+            />
+          </el-select>
+        </el-form-item>
+        <el-form-item label="新协助人员">
+          <el-select
+            v-model="ownershipForm.new_assistant_personnel_id"
+            placeholder="不选择并提交=清空协助"
+            clearable
+            filterable
+            style="width: 100%"
+          >
+            <el-option
+              v-for="item in personnelOptions"
+              :key="item.id"
+              :label="personnelLabel(item)"
+              :value="item.id"
+            />
+          </el-select>
+        </el-form-item>
+        <el-form-item label="调整原因">
+          <el-input
+            v-model="ownershipForm.reason"
+            type="textarea"
+            :rows="3"
+            maxlength="255"
+            placeholder="选填，将写入归属变更留痕"
+          />
+        </el-form-item>
+      </el-form>
+      <div class="op-warn">归属变更仅影响变更后核算，不回溯历史。</div>
+      <template #footer>
+        <el-button @click="ownershipVisible = false">取消</el-button>
+        <el-button type="primary" :loading="ownershipSubmitting" @click="handleOwnershipSubmit">
+          提交调整
+        </el-button>
+      </template>
+    </el-dialog>
+
+    <!-- 详情抽屉：基本信息 / 产品明细 / 状态时间线 / 归属留痕 / 毛利润视图 -->
+    <el-drawer v-model="drawerVisible" :title="drawerTitle" size="920px" destroy-on-close>
+      <div v-loading="drawerLoading">
+        <div class="sub-section">
+          <div class="sub-section-title">基本信息</div>
+          <el-descriptions v-if="detail" :column="3" border size="small" class="detail-desc">
+            <el-descriptions-item label="业务编号">{{ detail.business_no }}</el-descriptions-item>
+            <el-descriptions-item label="客户名称">
+              {{ detail.customer_name ?? '—' }}
+            </el-descriptions-item>
+            <el-descriptions-item label="业务日期">
+              {{ detail.business_date ?? '—' }}
+            </el-descriptions-item>
+            <el-descriptions-item label="状态">
+              <el-tag
+                :type="businessApi.businessStatusTagType(detail.status)"
+                size="small"
+                disable-transitions
+              >
+                {{ businessApi.businessStatusLabel(detail.status) }}
+              </el-tag>
+            </el-descriptions-item>
+            <el-descriptions-item label="负责人员">
+              {{ detail.owner_personnel_name ?? '（待指定）' }}
+            </el-descriptions-item>
+            <el-descriptions-item label="协助人员">
+              {{ detail.assistant_personnel_name ?? '—' }}
+            </el-descriptions-item>
+            <el-descriptions-item label="特殊业务">
+              <el-tag v-if="detail.is_special === 1" type="warning" size="small" disable-transitions>
+                特殊业务
+              </el-tag>
+              <span v-else class="cell-muted">否</span>
+            </el-descriptions-item>
+            <el-descriptions-item label="销售额（元）">
+              <span class="cell-amount">{{ detail.total_sale_amount ?? '—' }}</span>
+            </el-descriptions-item>
+            <el-descriptions-item label="成本（元）">
+              <span class="cell-amount">{{ detail.total_cost_amount ?? '—' }}</span>
+            </el-descriptions-item>
+            <el-descriptions-item label="发货额（元）">
+              <span class="cell-amount">{{ detail.total_ship_amount ?? '—' }}</span>
+            </el-descriptions-item>
+            <el-descriptions-item label="回款额（元）">
+              <span class="cell-amount">{{ detail.total_received_amount ?? '—' }}</span>
+            </el-descriptions-item>
+            <el-descriptions-item label="运费额（元）">
+              <span class="cell-amount">{{ detail.total_freight_amount ?? '—' }}</span>
+            </el-descriptions-item>
+            <el-descriptions-item label="备注">
+              {{ detail.remark ?? '—' }}
+            </el-descriptions-item>
+            <el-descriptions-item v-if="detail.is_special === 1" label="特殊说明" :span="3">
+              {{ detail.special_note ?? '—' }}
+            </el-descriptions-item>
+          </el-descriptions>
+        </div>
+
+        <div class="sub-section">
+          <div class="sub-section-title">产品明细</div>
+          <el-table v-if="detail" :data="detail.items" stripe size="small">
+            <el-table-column prop="product_name" label="产品名称" min-width="150" />
+            <el-table-column label="规格型号" min-width="110">
+              <template #default="{ row }">{{ row.spec_model ?? '—' }}</template>
+            </el-table-column>
+            <el-table-column label="单位" width="70">
+              <template #default="{ row }">{{ row.unit ?? '—' }}</template>
+            </el-table-column>
+            <el-table-column label="类别" width="100">
+              <template #default="{ row }">{{ productCategoryLabel(row.product_category) }}</template>
+            </el-table-column>
+            <el-table-column label="数量" min-width="80" align="right">
+              <template #default="{ row }">
+                <span class="cell-amount">{{ row.quantity }}</span>
+              </template>
+            </el-table-column>
+            <el-table-column label="销售单价" min-width="100" align="right">
+              <template #default="{ row }">
+                <span class="cell-amount">{{ row.sale_price ?? '—' }}</span>
+              </template>
+            </el-table-column>
+            <el-table-column label="行销售额" min-width="110" align="right">
+              <template #default="{ row }">
+                <span class="cell-amount">{{ row.sale_amount }}</span>
+              </template>
+            </el-table-column>
+            <el-table-column label="成本额" min-width="100" align="right">
+              <template #default="{ row }">
+                <span class="cell-amount">{{ row.cost_amount ?? '—' }}</span>
+              </template>
+            </el-table-column>
+            <el-table-column label="指导价" min-width="100" align="right">
+              <template #default="{ row }">
+                <span class="cell-amount">{{ row.guided_price ?? '—' }}</span>
+              </template>
+            </el-table-column>
+          </el-table>
+        </div>
+
+        <div class="sub-section">
+          <div class="sub-section-title">状态流转</div>
+          <el-timeline v-if="statusLogs.length > 0" class="status-timeline">
+            <el-timeline-item
+              v-for="log in statusLogs"
+              :key="log.id"
+              :timestamp="formatDateTime(log.create_time)"
+              placement="top"
+            >
+              <div class="log-line">
+                <template v-if="log.old_status === log.new_status">
+                  <span class="log-title">业务创建（{{ businessApi.businessStatusLabel(log.new_status) }}）</span>
+                </template>
+                <template v-else>
+                  <el-tag
+                    :type="businessApi.businessStatusTagType(log.old_status)"
+                    size="small"
+                    disable-transitions
+                  >
+                    {{ businessApi.businessStatusLabel(log.old_status) }}
+                  </el-tag>
+                  <span class="log-arrow">→</span>
+                  <el-tag
+                    :type="businessApi.businessStatusTagType(log.new_status)"
+                    size="small"
+                    disable-transitions
+                  >
+                    {{ businessApi.businessStatusLabel(log.new_status) }}
+                  </el-tag>
+                </template>
+                <span class="log-operator">操作人：{{ log.operator_name }}</span>
+              </div>
+              <div v-if="log.change_reason" class="log-reason">原因：{{ log.change_reason }}</div>
+            </el-timeline-item>
+          </el-timeline>
+          <div v-else class="cell-muted">暂无状态流转记录</div>
+        </div>
+
+        <div class="sub-section">
+          <div class="sub-section-title">归属变更记录</div>
+          <el-table v-loading="ownershipLogsLoading" :data="ownershipLogs" stripe size="small">
+            <el-table-column label="变更时间" width="160">
+              <template #default="{ row }">{{ formatDateTime(row.create_time) }}</template>
+            </el-table-column>
+            <el-table-column label="变更内容" min-width="240">
+              <template #default="{ row }">{{ ownershipTransition(row) }}</template>
+            </el-table-column>
+            <el-table-column label="变更原因" min-width="160">
+              <template #default="{ row }">{{ row.change_reason ?? '—' }}</template>
+            </el-table-column>
+            <el-table-column prop="operator_name" label="操作人" width="100" />
+          </el-table>
+          <AppPagination
+            :total="ownershipLogTotal"
+            :page-num="ownershipLogPageNum"
+            :page-size="ownershipLogPageSize"
+            @page-change="onOwnershipLogPageChange"
+            @size-change="onOwnershipLogSizeChange"
+          />
+        </div>
+
+        <div class="sub-section">
+          <div class="sub-section-title">毛利润视图</div>
+          <template v-if="gp">
+            <el-alert
+              v-if="gp.missing_count > 0"
+              type="warning"
+              :closable="false"
+              show-icon
+              class="gp-alert"
+              :title="`共 ${gp.missing_count} 行成本缺失，无法计算毛利润，不计入类别汇总`"
+            />
+            <el-row v-if="gp.categories.length > 0" :gutter="12">
+              <el-col v-for="cat in gp.categories" :key="cat.product_category" :span="12">
+                <div class="gp-card">
+                  <div class="gp-card-title">
+                    {{ productCategoryLabel(cat.product_category) }}
+                    <span class="gp-as-of">核对时点 {{ gp.as_of }}</span>
+                  </div>
+                  <div class="gp-grid">
+                    <span class="gp-label">销售额</span>
+                    <span class="gp-value cell-amount">{{ cat.sale_amount }}</span>
+                    <span class="gp-label">成本额</span>
+                    <span class="gp-value cell-amount">{{ cat.cost_amount }}</span>
+                    <span class="gp-label">毛利润额</span>
+                    <span class="gp-value cell-amount">{{ cat.profit_amount }}</span>
+                    <span class="gp-label">毛利润率</span>
+                    <!-- 分数字符串原样展示（如 997/1000），禁止数值化 -->
+                    <span class="gp-value cell-amount">{{ cat.profit_rate }}</span>
+                    <span class="gp-label">折算阈值</span>
+                    <span class="gp-value cell-amount">{{ cat.threshold }}</span>
+                    <span class="gp-label">折算毛利润额</span>
+                    <span class="gp-value cell-amount">{{ cat.converted_profit }}</span>
+                  </div>
+                </div>
+              </el-col>
+            </el-row>
+            <div v-else class="cell-muted">暂无可汇总的明细数据</div>
+
+            <el-table v-if="gp.rows.length > 0" :data="gp.rows" stripe size="small" class="gp-rows">
+              <el-table-column prop="product_name" label="产品名称" min-width="140" />
+              <el-table-column label="规格型号" min-width="100">
+                <template #default="{ row }">{{ row.spec_model ?? '—' }}</template>
+              </el-table-column>
+              <el-table-column label="类别" width="100">
+                <template #default="{ row }">{{ productCategoryLabel(row.product_category) }}</template>
+              </el-table-column>
+              <el-table-column label="数量" min-width="80" align="right">
+                <template #default="{ row }">
+                  <span class="cell-amount">{{ row.quantity }}</span>
+                </template>
+              </el-table-column>
+              <el-table-column label="销售额" min-width="100" align="right">
+                <template #default="{ row }">
+                  <span class="cell-amount">{{ row.sale_amount }}</span>
+                </template>
+              </el-table-column>
+              <el-table-column label="成本额" min-width="120" align="right">
+                <template #default="{ row }">
+                  <span v-if="row.cost_amount" class="cell-amount">{{ row.cost_amount }}</span>
+                  <span v-else class="cell-missing">{{ row.missing_reason ?? '成本缺失' }}</span>
+                </template>
+              </el-table-column>
+              <el-table-column label="毛利润额" min-width="100" align="right">
+                <template #default="{ row }">
+                  <span class="cell-amount">{{ row.profit_amount ?? '—' }}</span>
+                </template>
+              </el-table-column>
+              <el-table-column label="毛利润率" min-width="100" align="right">
+                <template #default="{ row }">
+                  <span class="cell-amount">{{ row.profit_rate ?? '—' }}</span>
+                </template>
+              </el-table-column>
+              <el-table-column label="折算阈值" min-width="90" align="right">
+                <template #default="{ row }">
+                  <span class="cell-amount">{{ row.threshold }}</span>
+                </template>
+              </el-table-column>
+              <el-table-column label="折算毛利润额" min-width="110" align="right">
+                <template #default="{ row }">
+                  <span class="cell-amount">{{ row.converted_profit ?? '—' }}</span>
+                </template>
+              </el-table-column>
+            </el-table>
+
+            <div class="gp-note">{{ gp.note }}</div>
+          </template>
+          <div v-else class="cell-muted">毛利润数据加载中或加载失败</div>
+        </div>
+      </div>
+    </el-drawer>
+  </div>
+</template>
+
+<style scoped>
+.cell-muted {
+  color: var(--ys-ink-3);
+  font-size: 12px;
+}
+
+.cell-amount {
+  font-family: 'SFMono-Regular', Consolas, 'Courier New', monospace;
+  font-size: 12px;
+  color: var(--ys-ink-2);
+}
+
+.cell-missing {
+  font-size: 12px;
+  color: var(--el-color-warning);
+}
+
+.op-wrap {
+  display: inline-block;
+}
+
+.switch-hint {
+  margin-left: 10px;
+  color: var(--ys-ink-3);
+  font-size: 12px;
+}
+
+.op-warn {
+  margin-top: 4px;
+  padding: 8px 12px;
+  border-radius: 6px;
+  background: var(--ys-indigo-wash);
+  color: var(--ys-ink-2);
+  font-size: 12px;
+  line-height: 1.7;
+}
+
+.items-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+}
+
+.items-title {
+  font-weight: 600;
+  color: var(--ys-ink);
+  font-size: 13px;
+}
+
+.items-table {
+  margin-bottom: 16px;
+}
+
+.tail-form {
+  margin-top: 4px;
+}
+
+.detail-desc {
+  margin-top: 8px;
+}
+
+.sub-section {
+  margin-bottom: 24px;
+}
+
+.sub-section-title {
+  font-weight: 600;
+  color: var(--ys-ink);
+  margin-bottom: 8px;
+}
+
+.status-timeline {
+  padding-left: 4px;
+}
+
+.log-line {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.log-title {
+  font-weight: 600;
+  color: var(--ys-ink);
+}
+
+.log-arrow {
+  color: var(--ys-ink-3);
+}
+
+.log-operator {
+  color: var(--ys-ink-3);
+  font-size: 12px;
+}
+
+.log-reason {
+  margin-top: 4px;
+  color: var(--ys-ink-2);
+  font-size: 12px;
+}
+
+.gp-alert {
+  margin-bottom: 12px;
+}
+
+.gp-card {
+  padding: 12px 14px;
+  margin-bottom: 12px;
+  border: 1px solid var(--ys-line);
+  border-radius: 8px;
+  background: var(--ys-mist);
+}
+
+.gp-card-title {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  font-weight: 600;
+  color: var(--ys-ink);
+  margin-bottom: 8px;
+}
+
+.gp-as-of {
+  font-weight: 400;
+  color: var(--ys-ink-3);
+  font-size: 12px;
+}
+
+.gp-grid {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 4px 12px;
+}
+
+.gp-label {
+  color: var(--ys-ink-3);
+  font-size: 12px;
+}
+
+.gp-value {
+  text-align: right;
+}
+
+.gp-rows {
+  margin-top: 8px;
+}
+
+.gp-note {
+  margin-top: 8px;
+  color: var(--ys-ink-3);
+  font-size: 12px;
+}
+</style>
diff --git a/frontend/src/views/business/receipts/index.vue b/frontend/src/views/business/receipts/index.vue
new file mode 100644
index 0000000..35a6e80
--- /dev/null
+++ b/frontend/src/views/business/receipts/index.vue
@@ -0,0 +1,508 @@
+<script setup lang="ts">
+import { computed, onMounted, reactive, ref } from 'vue'
+import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
+
+import * as businessApi from '@/api/businesses'
+import * as receiptApi from '@/api/receipts'
+import type { ReceiptItem } from '@/api/receipts'
+import * as shipmentApi from '@/api/shipments'
+import type { ShipmentItem } from '@/api/shipments'
+import AppPagination from '@/components/table/AppPagination.vue'
+import { useConfirmAction } from '@/composables/useConfirmAction'
+import { usePagedList } from '@/composables/usePagedList'
+import { handledError } from '@/utils/error'
+
+/**
+ * 回款管理（需求 2.2.3：回款登记 + 发货批次级联指定 + 派生回款天数）。
+ *
+ * 与后端约定对齐：
+ * - 业务必选、发货批次可暂不指定；选中业务后级联加载其发货单
+ *   （shipment_id 须与业务同源，后端强校验），可清空
+ * - payment_days 为派生值（发货日 → 回款日，发货日计第 1 天），
+ *   未指定批次时为 null，列表显示「未指定批次」
+ * - 已核算（settlement_status=1）行禁改禁删（按钮 disabled + tooltip）
+ * - 金额字符串直出与提交（金额红线：不经 float、不 toFixed）
+ */
+const { confirmAndRun } = useConfirmAction()
+
+// ==================== 列表 ====================
+
+const filters = reactive({
+  business_id: undefined as number | undefined,
+  is_barter: undefined as number | undefined,
+  settlement_status: undefined as number | undefined,
+})
+/** 回款日期范围单独存（el-date-picker daterange 回参是 [起, 止]） */
+const dateRange = ref<[string, string] | null>(null)
+
+const { records, total, pageNum, pageSize, loading, load, search, onPageChange, onSizeChange, reloadAfterDelete } =
+  usePagedList<ReceiptItem, receiptApi.ReceiptQueryParams>(
+    receiptApi.listReceipts,
+    () => ({
+      business_id: filters.business_id,
+      is_barter: filters.is_barter,
+      settlement_status: filters.settlement_status,
+      date_from: dateRange.value?.[0],
+      date_to: dateRange.value?.[1],
+    }),
+  )
+
+function resetFilters(): void {
+  filters.business_id = undefined
+  filters.is_barter = undefined
+  filters.settlement_status = undefined
+  dateRange.value = null
+  search()
+}
+
+// ==================== 业务下拉数据源 ====================
+
+interface BusinessOption {
+  id: number
+  no: string
+  name: string
+}
+
+const businessOptions = ref<BusinessOption[]>([])
+
+async function loadBusinessOptions(): Promise<void> {
+  try {
+    // 业务下拉数据源：一页 200 条覆盖内部系统规模；超出由后端校验兜底
+    const data = await businessApi.listBusinesses({ pageNum: 1, pageSize: 200 })
+    businessOptions.value = data.list.map((b) => ({
+      id: b.id,
+      no: b.business_no,
+      name: b.customer_name ?? '',
+    }))
+  } catch (error) {
+    handledError(error) // 下拉为空不阻断列表使用
+  }
+}
+
+function businessLabel(option: BusinessOption): string {
+  return option.name ? `${option.no} · ${option.name}` : option.no
+}
+
+// ==================== 新增 / 编辑 ====================
+
+/** 金额形态：非负数字、最多两位小数（与后端 `_check_amount` 同口径） */
+const AMOUNT_PATTERN = /^(\d+)(\.\d{1,2})?$/
+
+const dialogVisible = ref(false)
+const editingId = ref<number | null>(null)
+/** 单一状态源：编辑中 ⇔ editingId 非空（避免双状态漂移） */
+const isEdit = computed(() => editingId.value !== null)
+const formRef = ref<FormInstance>()
+const submitting = ref(false)
+
+const form = reactive({
+  business_id: undefined as number | undefined,
+  shipment_id: undefined as number | undefined,
+  receipt_date: '',
+  amount: '',
+  is_barter: 0,
+  remark: '',
+})
+
+const rules = computed<FormRules>(() => ({
+  business_id: [{ required: true, message: '请选择业务', trigger: 'change' }],
+  receipt_date: [{ required: true, message: '请选择回款到账日', trigger: 'change' }],
+  amount: [
+    { required: true, message: '请输入回款金额', trigger: 'blur' },
+    {
+      pattern: AMOUNT_PATTERN,
+      message: '金额须为非负数字，最多两位小数',
+      trigger: 'blur',
+    },
+  ],
+  remark: [{ max: 255, message: '备注最长 255 个字符', trigger: 'blur' }],
+}))
+
+// ---- 级联：业务 → 该业务的发货单（回款↔发货批次级联指定） ----
+
+const shipmentOptions = ref<ShipmentItem[]>([])
+const shipmentLoading = ref(false)
+
+/** 编辑中的回款（回显业务编号/批次语义用） */
+const editingRow = computed(() =>
+  editingId.value === null ? null : records.value.find((r) => r.id === editingId.value) ?? null,
+)
+
+/** 下拉展示：发货单号（发货日期，总额）—— 与任务约定文案一致 */
+function shipmentLabel(row: ShipmentItem): string {
+  return `${row.shipment_no}（${row.ship_date}，合计 ${row.total_amount} 元）`
+}
+
+/** 按业务级联加载发货单（列表一页 200 条足够该业务规模） */
+async function loadShipmentOptions(businessId: number): Promise<void> {
+  shipmentLoading.value = true
+  try {
+    const data = await shipmentApi.listShipments({
+      business_id: businessId,
+      pageNum: 1,
+      pageSize: 200,
+    })
+    shipmentOptions.value = data.list
+  } catch (error) {
+    shipmentOptions.value = []
+    handledError(error) // 失败提示由请求拦截器统一完成，下拉保持空
+  } finally {
+    shipmentLoading.value = false
+  }
+}
+
+/** 业务切换：清空已选发货批次并重新级联（原批次极可能不再法属于新业务） */
+function handleBusinessChange(value: number | undefined): void {
+  form.shipment_id = undefined
+  shipmentOptions.value = []
+  if (value) void loadShipmentOptions(value)
+}
+
+function openCreate(): void {
+  editingId.value = null
+  Object.assign(form, {
+    business_id: undefined,
+    shipment_id: undefined,
+    receipt_date: '',
+    amount: '',
+    is_barter: 0,
+    remark: '',
+  })
+  shipmentOptions.value = []
+  dialogVisible.value = true
+  formRef.value?.clearValidate()
+}
+
+async function openEdit(row: ReceiptItem): Promise<void> {
+  editingId.value = row.id
+  Object.assign(form, {
+    business_id: row.business_id,
+    shipment_id: row.shipment_id ?? undefined,
+    receipt_date: row.receipt_date,
+    amount: row.amount,
+    is_barter: row.is_barter,
+    remark: row.remark ?? '',
+  })
+  dialogVisible.value = true
+  if (row.business_id) await loadShipmentOptions(row.business_id)
+  formRef.value?.clearValidate()
+}
+
+async function handleSubmit(): Promise<void> {
+  const valid = await formRef.value?.validate().catch(() => false)
+  if (!valid) return
+
+  submitting.value = true
+  try {
+    if (editingId.value !== null) {
+      // 编辑全量替换：shipment_id 传 null = 清除既有指定（回到「暂未指定」）
+      await receiptApi.updateReceipt(editingId.value, {
+        shipment_id: form.shipment_id ?? null,
+        receipt_date: form.receipt_date,
+        amount: form.amount.trim(),
+        is_barter: form.is_barter,
+        remark: form.remark.trim() || null,
+      })
+      ElMessage.success('已保存')
+    } else {
+      await receiptApi.createReceipt({
+        business_id: form.business_id as number,
+        shipment_id: form.shipment_id ?? null,
+        receipt_date: form.receipt_date,
+        amount: form.amount.trim(),
+        is_barter: form.is_barter,
+        remark: form.remark.trim() || null,
+      })
+      ElMessage.success('回款已登记')
+    }
+    dialogVisible.value = false
+    await load()
+  } catch (error) {
+    handledError(error) // 失败提示由请求拦截器统一完成
+  } finally {
+    submitting.value = false
+  }
+}
+
+// ==================== 删除 ====================
+
+async function handleDelete(row: ReceiptItem): Promise<void> {
+  await confirmAndRun({
+    confirmText: `确定删除回款「${row.receipt_batch_no}」？删除为物理删除、不可恢复；删除后业务回款合计将自动回退。`,
+    title: '删除确认',
+    confirmButtonText: '删除',
+    successText: '回款已删除',
+    run: () => receiptApi.deleteReceipt(row.id),
+    after: reloadAfterDelete,
+  })
+}
+
+// ==================== 初始化 ====================
+
+onMounted(() => {
+  // 两个请求各自容错（load 内部已兜底），互不拖累
+  void load()
+  void loadBusinessOptions()
+})
+</script>
+
+<template>
+  <div>
+    <el-card shadow="never">
+      <el-form class="filter-form" :inline="true" @submit.prevent>
+        <el-form-item label="业务">
+          <el-select
+            v-model="filters.business_id"
+            placeholder="全部"
+            clearable
+            filterable
+            style="width: 230px"
+          >
+            <el-option
+              v-for="item in businessOptions"
+              :key="item.id"
+              :label="businessLabel(item)"
+              :value="item.id"
+            />
+          </el-select>
+        </el-form-item>
+        <el-form-item label="回款日期">
+          <el-date-picker
+            v-model="dateRange"
+            type="daterange"
+            value-format="YYYY-MM-DD"
+            range-separator="至"
+            start-placeholder="起"
+            end-placeholder="止"
+            style="width: 240px"
+          />
+        </el-form-item>
+        <el-form-item label="以物抵顶">
+          <el-select v-model="filters.is_barter" placeholder="全部" clearable style="width: 120px">
+            <el-option
+              v-for="item in receiptApi.BARTER_OPTIONS"
+              :key="item.value"
+              :label="item.label"
+              :value="item.value"
+            />
+          </el-select>
+        </el-form-item>
+        <el-form-item label="核算状态">
+          <el-select
+            v-model="filters.settlement_status"
+            placeholder="全部"
+            clearable
+            style="width: 110px"
+          >
+            <el-option
+              v-for="item in receiptApi.SETTLEMENT_OPTIONS"
+              :key="item.value"
+              :label="item.label"
+              :value="item.value"
+            />
+          </el-select>
+        </el-form-item>
+        <el-form-item>
+          <el-button type="primary" @click="search">查询</el-button>
+          <el-button @click="resetFilters">重置</el-button>
+        </el-form-item>
+      </el-form>
+
+      <div class="toolbar">
+        <el-button type="primary" @click="openCreate">新增回款</el-button>
+      </div>
+
+      <el-table v-loading="loading" :data="records" stripe>
+        <el-table-column prop="receipt_batch_no" label="批次号" min-width="150" />
+        <el-table-column prop="business_no" label="业务编号" min-width="140">
+          <template #default="{ row }">{{ row.business_no }}</template>
+        </el-table-column>
+        <el-table-column label="发货单号" min-width="140">
+          <template #default="{ row }">{{ row.shipment_no ?? '—' }}</template>
+        </el-table-column>
+        <el-table-column prop="receipt_date" label="回款日期" min-width="110" />
+        <el-table-column label="金额（元）" min-width="120" align="right">
+          <template #default="{ row }">
+            <!-- 字符串直出：金额红线，禁 toFixed / float 格式化 -->
+            <span class="cell-amount">{{ row.amount }}</span>
+          </template>
+        </el-table-column>
+        <el-table-column label="以物抵顶" width="100" align="center">
+          <template #default="{ row }">
+            <el-tag v-if="row.is_barter === 1" type="warning" size="small" disable-transitions>
+              以物抵顶
+            </el-tag>
+            <span v-else class="cell-muted">否</span>
+          </template>
+        </el-table-column>
+        <el-table-column label="回款天数" width="120" align="center">
+          <template #default="{ row }">
+            <span v-if="row.payment_days !== null" class="cell-amount">{{ row.payment_days }} 天</span>
+            <span v-else class="cell-muted">未指定批次</span>
+          </template>
+        </el-table-column>
+        <el-table-column label="核算状态" width="90" align="center">
+          <template #default="{ row }">
+            <el-tag
+              :type="row.settlement_status === 1 ? 'success' : 'info'"
+              size="small"
+              disable-transitions
+            >
+              {{ row.settlement_status === 1 ? '已核算' : '未核算' }}
+            </el-tag>
+          </template>
+        </el-table-column>
+        <el-table-column label="操作" width="130" fixed="right">
+          <template #default="{ row }">
+            <el-tooltip
+              content="已核算回款不可变更"
+              :disabled="row.settlement_status !== 1"
+              placement="top"
+            >
+              <span class="op-wrap">
+                <el-button
+                  link
+                  type="primary"
+                  size="small"
+                  :disabled="row.settlement_status === 1"
+                  @click="openEdit(row)"
+                >
+                  编辑
+                </el-button>
+              </span>
+            </el-tooltip>
+            <el-tooltip
+              content="已核算回款不可变更"
+              :disabled="row.settlement_status !== 1"
+              placement="top"
+            >
+              <span class="op-wrap">
+                <el-button
+                  link
+                  type="danger"
+                  size="small"
+                  :disabled="row.settlement_status === 1"
+                  @click="handleDelete(row)"
+                >
+                  删除
+                </el-button>
+              </span>
+            </el-tooltip>
+          </template>
+        </el-table-column>
+      </el-table>
+
+      <AppPagination
+        :total="total"
+        :page-num="pageNum"
+        :page-size="pageSize"
+        @page-change="onPageChange"
+        @size-change="onSizeChange"
+      />
+    </el-card>
+
+    <!-- 新增 / 编辑（业务必选 + 发货批次级联指定，可清空=暂不指定） -->
+    <el-dialog
+      v-model="dialogVisible"
+      :title="isEdit ? '编辑回款' : '新增回款'"
+      width="620px"
+      destroy-on-close
+    >
+      <el-form ref="formRef" :model="form" :rules="rules" label-width="110px">
+        <el-form-item v-if="!isEdit" label="业务" prop="business_id">
+          <el-select
+            v-model="form.business_id"
+            placeholder="搜索并选择业务（编号 / 客户名）"
+            filterable
+            style="width: 100%"
+            @change="handleBusinessChange"
+          >
+            <el-option
+              v-for="item in businessOptions"
+              :key="item.id"
+              :label="businessLabel(item)"
+              :value="item.id"
+            />
+          </el-select>
+        </el-form-item>
+        <el-form-item v-else label="业务">
+          <!-- 挂靠业务创建时定死，编辑时只读展示 -->
+          <span>{{ editingRow?.business_no ?? '—' }}</span>
+        </el-form-item>
+        <el-form-item label="发货批次" prop="shipment_id">
+          <el-select
+            v-model="form.shipment_id"
+            placeholder="选业务后级联加载该业务发货单"
+            clearable
+            filterable
+            :loading="shipmentLoading"
+            :disabled="!form.business_id"
+            style="width: 100%"
+          >
+            <el-option
+              v-for="item in shipmentOptions"
+              :key="item.id"
+              :label="shipmentLabel(item)"
+              :value="item.id"
+            />
+          </el-select>
+          <span class="field-hint">可清空（暂不指定）；指定后回款天数方可派生（发货日计第 1 天）</span>
+        </el-form-item>
+        <el-form-item label="回款到账日" prop="receipt_date">
+          <el-date-picker
+            v-model="form.receipt_date"
+            type="date"
+            value-format="YYYY-MM-DD"
+            placeholder="M3 核算按此日匹配参数版本"
+            style="width: 100%"
+          />
+        </el-form-item>
+        <el-form-item label="金额（元）" prop="amount">
+          <el-input v-model="form.amount" placeholder="非负数字，最多两位小数" />
+        </el-form-item>
+        <el-form-item label="以物抵顶" prop="is_barter">
+          <el-switch v-model="form.is_barter" :active-value="1" :inactive-value="0" />
+          <span class="switch-hint">绩效按 80% 折算，比例见参数配置</span>
+        </el-form-item>
+        <el-form-item label="备注" prop="remark">
+          <el-input v-model="form.remark" type="textarea" :rows="2" maxlength="255" placeholder="选填" />
+        </el-form-item>
+      </el-form>
+      <template #footer>
+        <el-button @click="dialogVisible = false">取消</el-button>
+        <el-button type="primary" :loading="submitting" @click="handleSubmit">保存</el-button>
+      </template>
+    </el-dialog>
+  </div>
+</template>
+
+<style scoped>
+.cell-muted {
+  color: var(--ys-ink-3);
+  font-size: 12px;
+}
+
+.cell-amount {
+  font-family: 'SFMono-Regular', Consolas, 'Courier New', monospace;
+  font-size: 12px;
+  color: var(--ys-ink-2);
+}
+
+.op-wrap {
+  display: inline-block;
+}
+
+.switch-hint {
+  margin-left: 10px;
+  color: var(--ys-ink-3);
+  font-size: 12px;
+}
+
+.field-hint {
+  display: block;
+  width: 100%;
+  color: var(--ys-ink-3);
+  font-size: 12px;
+  line-height: 1.6;
+}
+</style>
diff --git a/frontend/src/views/business/shipments/index.vue b/frontend/src/views/business/shipments/index.vue
new file mode 100644
index 0000000..2b3b788
--- /dev/null
+++ b/frontend/src/views/business/shipments/index.vue
@@ -0,0 +1,497 @@
+<script setup lang="ts">
+import { computed, onMounted, reactive, ref } from 'vue'
+import { ElMessage, type FormInstance, type FormRules } from 'element-plus'
+
+import * as businessApi from '@/api/businesses'
+import * as shipmentApi from '@/api/shipments'
+import type { ShipmentDetail, ShipmentItem } from '@/api/shipments'
+import AppPagination from '@/components/table/AppPagination.vue'
+import { useConfirmAction } from '@/composables/useConfirmAction'
+import { usePagedList } from '@/composables/usePagedList'
+import { handledError } from '@/utils/error'
+
+/**
+ * 发货管理（需求 2.2.2：发货单 + 明细行 + 运费 + 汇总回写）。
+ *
+ * 与后端约定对齐：
+ * - 发货单挂靠执行中的业务（后端校验状态门槛）；创建绑业务后不可改挂，
+ *   编辑端点不含 business_id（保证已指定本单的回款语义不断裂）
+ * - ship_date 是回款天数计算基准日（发货日计第 1 天）—— 表单旁注提示
+ * - 明细行金额 = 数量 × 单价由后端固化；单价可空 = 待人工补价（行金额记 0）
+ * - 删除连带明细并回写业务汇总；被回款批次指定时后端拒绝
+ */
+const { confirmAndRun } = useConfirmAction()
+
+// ==================== 列表 ====================
+
+const filters = reactive({
+  business_id: undefined as number | undefined,
+})
+/** 发货日期范围单独存（el-date-picker daterange 回参是 [起, 止]） */
+const dateRange = ref<[string, string] | null>(null)
+
+const { records, total, pageNum, pageSize, loading, load, search, onPageChange, onSizeChange, reloadAfterDelete } =
+  usePagedList<ShipmentItem, shipmentApi.ShipmentQueryParams>(
+    shipmentApi.listShipments,
+    () => ({
+      business_id: filters.business_id,
+      ship_date_from: dateRange.value?.[0],
+      ship_date_to: dateRange.value?.[1],
+    }),
+  )
+
+function resetFilters(): void {
+  filters.business_id = undefined
+  dateRange.value = null
+  search()
+}
+
+// ==================== 业务下拉数据源（可搜索过滤） ====================
+
+interface BusinessOption {
+  id: number
+  no: string
+  name: string
+  status: number
+}
+
+const businessOptions = ref<BusinessOption[]>([])
+
+async function loadBusinessOptions(): Promise<void> {
+  try {
+    // 业务下拉数据源：一页 200 条覆盖标签页规模；超出规模由后端校验兜底
+    const data = await businessApi.listBusinesses({ pageNum: 1, pageSize: 200 })
+    businessOptions.value = data.list.map((b) => ({
+      id: b.id,
+      no: b.business_no,
+      name: b.customer_name ?? '',
+      status: b.status,
+    }))
+  } catch (error) {
+    handledError(error) // 下拉为空不阻断列表使用
+  }
+}
+
+/** 下拉项展示：业务编号 + 客户名；终态业务加后缀标注（创建发货单会被后端拦） */
+function businessLabel(option: BusinessOption): string {
+  const state = option.status === 1 ? '' : option.status === 2 ? '（已完成）' : '（已终止）'
+  return option.name ? `${option.no} · ${option.name}${state}` : `${option.no}${state}`
+}
+
+// ==================== 新增 / 编辑（含明细行编辑器） ====================
+
+/** 金额/数量形态：非负数字、最多两位小数（与后端 `_check_amount` 同口径） */
+const AMOUNT_PATTERN = /^(\d+)(\.\d{1,2})?$/
+/** 全零形态：数量排除「>0」语义，不走 float 比较 */
+const ZERO_PATTERN = /^0+(\.0+)?$/
+
+const dialogVisible = ref(false)
+const editingId = ref<number | null>(null)
+/** 单一状态源：编辑中 ⇔ editingId 非空（避免双状态漂移） */
+const isEdit = computed(() => editingId.value !== null)
+const formRef = ref<FormInstance>()
+const submitting = ref(false)
+
+/** 编辑中的发货单（回显业务编号用，编辑挂靠不可改） */
+const editingRow = computed(() =>
+  editingId.value === null ? null : records.value.find((r) => r.id === editingId.value) ?? null,
+)
+
+/** 明细行草稿（编辑时由详情回显；全量替换，行 id 不参与提交） */
+interface ItemDraft {
+  product_name: string
+  spec_model: string
+  unit: string
+  quantity: string
+  sale_price: string
+}
+
+const form = reactive({
+  business_id: undefined as number | undefined,
+  ship_date: '',
+  freight_amount: '',
+  remark: '',
+})
+
+function emptyItem(): ItemDraft {
+  return { product_name: '', spec_model: '', unit: '', quantity: '', sale_price: '' }
+}
+
+const itemRows = ref<ItemDraft[]>([])
+
+const rules = computed<FormRules>(() => ({
+  business_id: [{ required: true, message: '请选择业务', trigger: 'change' }],
+  ship_date: [{ required: true, message: '请选择发货日期', trigger: 'change' }],
+  freight_amount: [
+    { pattern: AMOUNT_PATTERN, message: '运费须为非负数字，最多两位小数', trigger: 'blur' },
+  ],
+  remark: [{ max: 255, message: '备注最长 255 个字符', trigger: 'blur' }],
+}))
+
+function openCreate(): void {
+  editingId.value = null
+  Object.assign(form, {
+    business_id: undefined,
+    ship_date: '',
+    freight_amount: '',
+    remark: '',
+  })
+  itemRows.value = [emptyItem()] // 预置一空行，用户可直接填写
+  dialogVisible.value = true
+  formRef.value?.clearValidate()
+}
+
+async function openEdit(row: ShipmentItem): Promise<void> {
+  editingId.value = row.id
+  dialogVisible.value = true
+  const detail: ShipmentDetail | null = await shipmentApi.getShipmentDetail(row.id).catch((error) => {
+    handledError(error) // 失败提示由请求拦截器统一完成，弹窗保持空表
+    return null
+  })
+  if (!detail) return
+  Object.assign(form, {
+    business_id: detail.business_id,
+    ship_date: detail.ship_date,
+    freight_amount: detail.freight_amount ?? '',
+    remark: detail.remark ?? '',
+  })
+  itemRows.value = detail.items.map((it) => ({
+    product_name: it.product_name,
+    spec_model: it.spec_model ?? '',
+    unit: it.unit ?? '',
+    quantity: it.quantity,
+    sale_price: it.sale_price ?? '',
+  }))
+  formRef.value?.clearValidate()
+}
+
+function addItemRow(): void {
+  itemRows.value.push(emptyItem())
+}
+
+function removeItemRow(index: number): void {
+  itemRows.value.splice(index, 1)
+}
+
+/** 明细行校验：返回第一处问题的提示文案，全部通过返回 null */
+function validateItemRows(rows: ItemDraft[]): string | null {
+  if (rows.length === 0) return '请至少录入一行发货明细'
+  for (let i = 0; i < rows.length; i += 1) {
+    const row = rows[i]
+    const no = `第 ${i + 1} 行`
+    if (!row.product_name.trim()) return `${no}的产品名称未填写`
+    if (!AMOUNT_PATTERN.test(row.quantity) || ZERO_PATTERN.test(row.quantity)) {
+      return `${no}的数量须为大于 0 的数字，最多两位小数`
+    }
+    if (row.sale_price.trim() && !AMOUNT_PATTERN.test(row.sale_price.trim())) {
+      return `${no}的发货单价须为非负数字，最多两位小数`
+    }
+  }
+  return null
+}
+
+/** 明细草稿 → 提交行（空串归一为 null，与后端「空串归一 NULL」口径一致） */
+function buildItemParams(): shipmentApi.ShipmentItemParams[] {
+  return itemRows.value.map((row) => ({
+    product_name: row.product_name.trim(),
+    spec_model: row.spec_model.trim() || null,
+    unit: row.unit.trim() || null,
+    quantity: row.quantity.trim(),
+    sale_price: row.sale_price.trim() || null,
+  }))
+}
+
+async function doSubmit(): Promise<void> {
+  const items = buildItemParams()
+  submitting.value = true
+  try {
+    if (editingId.value !== null) {
+      // 编辑不含 business_id：发货单挂靠的业务创建时定死
+      await shipmentApi.updateShipment(editingId.value, {
+        ship_date: form.ship_date,
+        freight_amount: form.freight_amount.trim() || null,
+        items,
+        remark: form.remark.trim() || null,
+      })
+      ElMessage.success('已保存')
+    } else {
+      await shipmentApi.createShipment({
+        business_id: form.business_id as number,
+        ship_date: form.ship_date,
+        freight_amount: form.freight_amount.trim() || null,
+        items,
+        remark: form.remark.trim() || null,
+      })
+      ElMessage.success('发货单已创建')
+    }
+    dialogVisible.value = false
+    await load()
+  } catch (error) {
+    handledError(error) // 失败提示由请求拦截器统一完成
+  } finally {
+    submitting.value = false
+  }
+}
+
+async function handleSubmit(): Promise<void> {
+  const valid = await formRef.value?.validate().catch(() => false)
+  if (!valid) return
+
+  const rowError = validateItemRows(itemRows.value)
+  if (rowError) {
+    ElMessage.warning(rowError)
+    return
+  }
+
+  if (isEdit.value) {
+    await doSubmit() // 编辑全量替换无破坏性语义变化，直接提交
+    return
+  }
+  // 创建走 confirm 二次确认（提交回写入业务发货额汇总）
+  await confirmAndRun({
+    confirmText: '确定创建发货单？提交后业务发货额将同步更新。',
+    title: '创建确认',
+    confirmButtonText: '确认创建',
+    successText: '发货单已创建',
+    run: doSubmit,
+  })
+}
+
+// ==================== 删除 ====================
+
+async function handleDelete(row: ShipmentItem): Promise<void> {
+  await confirmAndRun({
+    confirmText: `确定删除发货单「${row.shipment_no}」？删除将连带明细行并回写业务汇总；被回款批次指定时不可删除。`,
+    title: '删除确认',
+    confirmButtonText: '删除',
+    successText: '发货单已删除',
+    run: () => shipmentApi.deleteShipment(row.id),
+    after: reloadAfterDelete,
+  })
+}
+
+// ==================== 初始化 ====================
+
+onMounted(() => {
+  // 两个请求各自容错（load 内部已兜底），互不拖累
+  void load()
+  void loadBusinessOptions()
+})
+</script>
+
+<template>
+  <div>
+    <el-card shadow="never">
+      <el-form class="filter-form" :inline="true" @submit.prevent>
+        <el-form-item label="业务">
+          <el-select
+            v-model="filters.business_id"
+            placeholder="全部"
+            clearable
+            filterable
+            style="width: 240px"
+          >
+            <el-option
+              v-for="item in businessOptions"
+              :key="item.id"
+              :label="businessLabel(item)"
+              :value="item.id"
+            />
+          </el-select>
+        </el-form-item>
+        <el-form-item label="发货日期">
+          <el-date-picker
+            v-model="dateRange"
+            type="daterange"
+            value-format="YYYY-MM-DD"
+            range-separator="至"
+            start-placeholder="起"
+            end-placeholder="止"
+            style="width: 240px"
+          />
+        </el-form-item>
+        <el-form-item>
+          <el-button type="primary" @click="search">查询</el-button>
+          <el-button @click="resetFilters">重置</el-button>
+        </el-form-item>
+      </el-form>
+
+      <div class="toolbar">
+        <el-button type="primary" @click="openCreate">新增发货单</el-button>
+      </div>
+
+      <el-table v-loading="loading" :data="records" stripe>
+        <el-table-column prop="shipment_no" label="发货单号" min-width="150" />
+        <el-table-column prop="business_no" label="业务编号" min-width="150">
+          <template #default="{ row }">{{ row.business_no ?? '—' }}</template>
+        </el-table-column>
+        <el-table-column label="发货日期" min-width="140">
+          <template #default="{ row }">
+            <span>{{ row.ship_date }}</span>
+            <!-- 回款天数计算基准日提示：发货日计第 1 天 -->
+            <el-tooltip content="本单发货日期是回款天数计算基准日（发货日计第 1 天）" placement="top">
+              <span class="cell-muted">（基准日）</span>
+            </el-tooltip>
+          </template>
+        </el-table-column>
+        <el-table-column label="运费（元）" min-width="110" align="right">
+          <template #default="{ row }">
+            <!-- 字符串直出：金额红线，禁 toFixed / float 格式化 -->
+            <span class="cell-amount">{{ row.freight_amount }}</span>
+          </template>
+        </el-table-column>
+        <el-table-column label="发货总额（元）" min-width="130" align="right">
+          <template #default="{ row }">
+            <span class="cell-amount">{{ row.total_amount }}</span>
+          </template>
+        </el-table-column>
+        <el-table-column label="操作" width="130" fixed="right">
+          <template #default="{ row }">
+            <el-button link type="primary" size="small" @click="openEdit(row)">编辑</el-button>
+            <el-button link type="danger" size="small" @click="handleDelete(row)">删除</el-button>
+          </template>
+        </el-table-column>
+      </el-table>
+
+      <AppPagination
+        :total="total"
+        :page-num="pageNum"
+        :page-size="pageSize"
+        @page-change="onPageChange"
+        @size-change="onSizeChange"
+      />
+    </el-card>
+
+    <!-- 新增 / 编辑（明细行编辑器；编辑不含 business_id，挂靠业务不可改） -->
+    <el-dialog
+      v-model="dialogVisible"
+      :title="isEdit ? '编辑发货单' : '新增发货单'"
+      width="820px"
+      destroy-on-close
+    >
+      <el-form ref="formRef" :model="form" :rules="rules" label-width="110px">
+        <el-form-item v-if="!isEdit" label="业务" prop="business_id">
+          <el-select
+            v-model="form.business_id"
+            placeholder="搜索或选择业务（筛选后按编号 / 客户名匹配）"
+            filterable
+            style="width: 100%"
+          >
+            <el-option
+              v-for="item in businessOptions"
+              :key="item.id"
+              :label="businessLabel(item)"
+              :value="item.id"
+            />
+          </el-select>
+        </el-form-item>
+        <el-form-item v-else label="业务">
+          <!-- 挂靠业务创建时定死，编辑时只读展示 -->
+          <span>{{ editingRow?.business_no ?? '—' }}</span>
+        </el-form-item>
+        <el-form-item label="发货日期" prop="ship_date">
+          <el-date-picker
+            v-model="form.ship_date"
+            type="date"
+            value-format="YYYY-MM-DD"
+            placeholder="选择日期"
+            style="width: 100%"
+          />
+          <span class="field-hint">回款天数计算基准日（发货日计第 1 天）</span>
+        </el-form-item>
+        <el-form-item label="运费（元）" prop="freight_amount">
+          <el-input v-model="form.freight_amount" placeholder="选填；仅记录展示，不计入毛利润口径" />
+        </el-form-item>
+      </el-form>
+
+      <div class="items-head">
+        <span class="items-title">发货明细（至少 1 行，编辑为全量替换）</span>
+        <el-button size="small" @click="addItemRow">添加一行</el-button>
+      </div>
+      <el-table :data="itemRows" stripe size="small" class="items-table">
+        <el-table-column label="产品名称" min-width="180">
+          <template #default="{ row }">
+            <el-input v-model="row.product_name" maxlength="128" placeholder="产品名称，可手填" />
+          </template>
+        </el-table-column>
+        <el-table-column label="规格型号" min-width="130">
+          <template #default="{ row }">
+            <el-input v-model="row.spec_model" maxlength="128" placeholder="选填" />
+          </template>
+        </el-table-column>
+        <el-table-column label="单位" min-width="90">
+          <template #default="{ row }">
+            <el-input v-model="row.unit" maxlength="16" placeholder="如 台" />
+          </template>
+        </el-table-column>
+        <el-table-column label="数量" min-width="110">
+          <template #default="{ row }">
+            <el-input v-model="row.quantity" placeholder=">0" />
+          </template>
+        </el-table-column>
+        <el-table-column label="单价（元）" min-width="130">
+          <template #default="{ row }">
+            <el-input v-model="row.sale_price" placeholder="可空=待人工补价" />
+          </template>
+        </el-table-column>
+        <el-table-column label="操作" width="70" align="center">
+          <template #default="{ $index }">
+            <el-button link type="danger" size="small" @click="removeItemRow($index)">删除</el-button>
+          </template>
+        </el-table-column>
+      </el-table>
+
+      <el-form label-width="110px" class="tail-form" @submit.prevent>
+        <el-form-item label="备注" prop="remark">
+          <el-input v-model="form.remark" type="textarea" :rows="2" maxlength="255" placeholder="选填" />
+        </el-form-item>
+      </el-form>
+      <template #footer>
+        <el-button @click="dialogVisible = false">取消</el-button>
+        <el-button type="primary" :loading="submitting" @click="handleSubmit">保存</el-button>
+      </template>
+    </el-dialog>
+  </div>
+</template>
+
+<style scoped>
+.cell-amount {
+  font-family: 'SFMono-Regular', Consolas, 'Courier New', monospace;
+  font-size: 12px;
+  color: var(--ys-ink-2);
+}
+
+.cell-muted {
+  color: var(--ys-ink-3);
+  font-size: 12px;
+}
+
+.field-hint {
+  display: block;
+  width: 100%;
+  color: var(--ys-ink-3);
+  font-size: 12px;
+  line-height: 1.6;
+}
+
+.items-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+}
+
+.items-title {
+  font-weight: 600;
+  color: var(--ys-ink);
+  font-size: 13px;
+}
+
+.items-table {
+  margin-bottom: 16px;
+}
+
+.tail-form {
+  margin-top: 4px;
+}
+</style>