From 92c59d67b45a5a3e7fd33e2fb069d387f222023a Mon Sep 17 00:00:00 2001
From: zlwu <704541015@qq.com>
Date: Wed, 21 Oct 2026 17:58:43 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E4=B8=BA=E8=BF=90=E8=B4=B9=E6=89=B9?=
 =?UTF-8?q?=E6=AC=A1=E5=A2=9E=E5=8A=A0=E9=A1=BA=E4=B8=B0=E5=8D=95=E5=8F=B7?=
 =?UTF-8?q?=E5=92=8C=E7=BB=93=E7=AE=97=E5=AD=97=E6=AE=B5=EF=BC=8C=E5=B9=B6?=
 =?UTF-8?q?=E8=A1=A5=E4=B8=8A=E9=A1=BA=E4=B8=B0=E6=9C=88=E7=BB=93=E8=8F=9C?=
 =?UTF-8?q?=E5=8D=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 backend/app/models/models.py                  |  5 +-
 backend/tests/test_sf_express_settlement.py   | 10 ++
 ...26-10-21-sf-express-monthly-settlement.sql | 96 +++++++++++++++++++
 3 files changed, 110 insertions(+), 1 deletion(-)
 create mode 100644 docs/sql/migrations/2026-10-21-sf-express-monthly-settlement.sql

diff --git a/backend/app/models/models.py b/backend/app/models/models.py
index 8e590d97..2eddd144 100644
--- a/backend/app/models/models.py
+++ b/backend/app/models/models.py
@@ -1616,7 +1616,10 @@ class BizSampleFreight(Base):
     id = Column(String(64), primary_key=True, comment="主键ID")
     freight_no = Column(String(32), nullable=False, default="", comment="运费批次号 YF+YYYYMMDD+序号")
     transport_mode = Column(String(100), nullable=False, default="", comment="运输方式字典值")
-    freight_amount = Column(Numeric(18, 2), nullable=False, default=0, comment="运费（元）")
+    freight_amount = Column(Numeric(18, 2), nullable=True, comment="运费（元），顺丰月结未填时为空")
+    waybill_no = Column(String(64), nullable=True, comment="顺丰单号")
+    settle_status = Column(String(8), nullable=True, comment="结算状态 wjs/yjs")
+    settle_time = Column(DateTime, nullable=True, comment="结算时间")
     tenant_no = Column(String(64), nullable=False, default="zkxw", comment="租户编号")
     order_num = Column(Integer, nullable=True, comment="排序号")
     remark = Column(String(512), nullable=True, comment="备注")
diff --git a/backend/tests/test_sf_express_settlement.py b/backend/tests/test_sf_express_settlement.py
index 8745f91d..c0be2689 100644
--- a/backend/tests/test_sf_express_settlement.py
+++ b/backend/tests/test_sf_express_settlement.py
@@ -171,3 +171,13 @@ def test_settled_batch_cannot_delete_or_change_samples():
     assert_freight_mutable("wjs", "delete")
     assert freight_amount_label("sfkd", Decimal("8")) == "8.00"
     assert freight_amount_label("zxc", None) == ""
+
+
+def test_freight_model_allows_null_amount_and_settlement_columns():
+    from app.models.models import BizSampleFreight
+
+    cols = {column.name: column for column in BizSampleFreight.__table__.columns}
+    assert cols["freight_amount"].nullable is True
+    assert cols["waybill_no"].nullable is True
+    assert cols["settle_status"].nullable is True
+    assert cols["settle_time"].nullable is True
diff --git a/docs/sql/migrations/2026-10-21-sf-express-monthly-settlement.sql b/docs/sql/migrations/2026-10-21-sf-express-monthly-settlement.sql
new file mode 100644
index 00000000..55db5c59
--- /dev/null
+++ b/docs/sql/migrations/2026-10-21-sf-express-monthly-settlement.sql
@@ -0,0 +1,96 @@
+-- 顺丰月结：运费可空，增加单号与结算字段；历史顺丰补未结算，不改原金额。
+ALTER TABLE biz_sample_freight
+  MODIFY COLUMN freight_amount DECIMAL(18,2) NULL DEFAULT NULL COMMENT '运费（元），顺丰月结未填时为空',
+  ADD COLUMN waybill_no VARCHAR(64) NULL DEFAULT NULL COMMENT '顺丰单号' AFTER freight_amount,
+  ADD COLUMN settle_status VARCHAR(8) NULL DEFAULT NULL COMMENT '结算状态：wjs 未结算，yjs 已结算' AFTER waybill_no,
+  ADD COLUMN settle_time DATETIME NULL DEFAULT NULL COMMENT '结算时间' AFTER settle_status;
+
+UPDATE biz_sample_freight
+SET settle_status = 'wjs'
+WHERE del_flag = 0
+  AND transport_mode = 'sfkd'
+  AND (settle_status IS NULL OR settle_status = '');
+
+-- 菜单插在缴费财务确认之前。id 尚未占用。
+UPDATE sys_menu
+SET order_num = IFNULL(order_num, 0) + 1,
+    update_time = NOW()
+WHERE id = '50000000000000000000000000000004'
+  AND del_flag = 0
+  AND NOT EXISTS (
+    SELECT 1 FROM (
+      SELECT id FROM sys_menu
+      WHERE id = '50000000000000000000000000000023' AND del_flag = 0
+    ) existing_menu
+  );
+
+INSERT INTO sys_menu (
+  id, menu_name, parent_id, menu_type, path, component, perms,
+  is_frame, visible, status, tenant_no, order_num, remark,
+  create_by, create_dept_id, create_time, update_by, update_time, del_flag
+)
+SELECT
+  '50000000000000000000000000000023',
+  '顺丰月结',
+  'CEL00000000000000000000000000001',
+  'C',
+  'sf-express-settlement',
+  '/cell-storage/sf-express-settlement/index',
+  'cell-storage:sf-express-settlement:list',
+  1,
+  '1',
+  '1',
+  'zkxw',
+  (
+    SELECT order_num - 1 FROM (
+      SELECT order_num FROM sys_menu
+      WHERE id = '50000000000000000000000000000004' AND del_flag = 0
+      LIMIT 1
+    ) pay_menu
+  ),
+  '细胞存储：顺丰月结',
+  NULL,
+  '',
+  NOW(),
+  NULL,
+  NOW(),
+  0
+FROM DUAL
+WHERE NOT EXISTS (
+  SELECT 1 FROM sys_menu m
+  WHERE m.del_flag = 0
+    AND (
+      m.id = '50000000000000000000000000000023'
+      OR m.perms = 'cell-storage:sf-express-settlement:list'
+    )
+);
+
+INSERT INTO sys_role_menu (
+  id, role_id, menu_id, tenant_no, order_num, remark,
+  create_by, create_dept_id, create_time, update_by, update_time, del_flag
+)
+SELECT
+  MD5(CONCAT(r.id, '|50000000000000000000000000000023')),
+  r.id,
+  '50000000000000000000000000000023',
+  IFNULL(NULLIF(r.tenant_no, ''), 'zkxw'),
+  0,
+  'grant sf-express settlement to payment-confirm roles',
+  NULL,
+  '',
+  NOW(),
+  NULL,
+  NOW(),
+  0
+FROM sys_role r
+INNER JOIN sys_role_menu rm
+  ON rm.role_id = r.id
+ AND rm.menu_id = '50000000000000000000000000000004'
+ AND rm.del_flag = 0
+WHERE r.del_flag = 0
+  AND NOT EXISTS (
+    SELECT 1 FROM sys_role_menu x
+    WHERE x.role_id = r.id
+      AND x.menu_id = '50000000000000000000000000000023'
+      AND x.del_flag = 0
+  );