feat(borrow): 转交粒度下沉到明细行，支持部分转交

背景（业务方推翻上一轮约束）
----
上一轮按「一张单同时只能有一个持有人」实现了**整单转交**，并把「单内出现多个
持有人」当作 bug 去修。业务方验收后明确纠正：

    物理现场经常只转交部分工具（借了 2 件、只把 1 件转给别人），
    单内多持有人才是符合现实的正常状态。

故转交粒度从 borrow_no 下沉回 trans_borrow.id（明细行）。

改动
----
· transfer_borrow：只操作传入的那**一行**明细，不再按单号整批覆盖。
  转出方 = 该行当前持有人；数量 = 该行待还量。
· accept_transfer：只转移 transfer.borrow_id 指向的那一行 ——
  整批改写会把别人手上的东西一并抢过来（部分转交下同单明细分属不同人）。
· 唯一性约束从「单号至多一条 PENDING」下沉为「明细行至多一条」：
  同单的其他明细可以同时各自挂着待接收，互不阻塞 —— 这正是部分转交的语义。
· get_records 的 pending_transfer 改按 borrow_id 关联（原按 borrow_no），
  否则同单多项待接收会互相覆盖。
· 删除已无用的 _load_slip_for_update。

★ 数量粒度：一行只支持**整行转交**。一行只能有一个 current_holder_id，
  「同一行只转一部分」需要把这行拆成两行 —— 经业务确认，现场场景中
  「借 2 件转 1 件」的两件本就是两条明细行，故该限制不影响实际使用；
  接口对传入的非整行数量会明确提示「应另立一条明细行」。

数据层
----
无需改表结构：borrow_id 本就是流水的关联列，borrow_no 退化为单据归属与
分组展示用。仅补 (borrow_id, status) 复合索引支撑新的查询路径。
存量撕裂数据（BOR-20260917-0001 的「测试 / 杜邢宸」）按业务方选择**保留不动**
—— 它现在不再是 bug，而是部分转交的正常形态。

验证（合成 2 明细单，21 项断言全通过）
----
· 只转工具A：工具B 完全不受影响
· 同一张单可同时挂两条待接收，互不阻塞；同一明细重复发起被拒
· accept 工具A 后：A→测试，B 仍是杜邢宸（单内两个持有人）
· 两个持有人、以及待接收人，三方各自都能在列表中看到该单
· pending_transfer 挂在正确的明细行上，is_mine 判定正确
· reject 后主表持有人不变；非整行数量被拒并提示拆行
· 全程 available_quantity 无变化，库存精确还原、零残留数据

db_migrations/phase4d_borrow_transfer_item_level.sql

@@ -0,0 +1,74 @@
+-- =============================================================================
+-- 借库转交 · 粒度下沉到明细行（部分转交）
+--
+-- 背景（业务方推翻上一轮约束）
+--   上一轮按「一张单同时只能有一个持有人」实现了**整单转交**，并把「单内出现
+--   多个持有人」当作 bug 去修。业务方验收后明确纠正：
+--     物理现场经常只转交部分工具（借了 2 件，只把 1 件转给别人），
+--     **单内多持有人才是符合现实的正常状态**。
+--   故转交粒度从 borrow_no 下沉回 trans_borrow.id（明细行）。
+--
+-- ---------------------------------------------------------------------------
+-- 本次改动的实质
+--   代码层：transfer_borrow / accept_transfer 只操作**一行**明细，
+--           唯一性约束从「单号最多一条 PENDING」改为「明细行最多一条 PENDING」。
+--   数据层：**无需改动任何表结构** —— borrow_id（明细行）本就是流水的主键
+--           关联列，borrow_no 继续保留作单据归属与展示分组用。
+--           仅补一个复合索引，支撑「按明细行查待接收流水」这一新查询路径。
+--
+-- ★ 为什么不需要新的列
+--     转交粒度既然回到明细行，覆盖范围就是 borrow_id 指向的那一行本身 ——
+--     不需要额外的「覆盖清单」来表达范围，borrow_no 退化为分组/展示用途。
+--
+-- ★ 存量数据不动（业务方选择）
+--     BOR-20260917-0001 的「测试 / 杜邢宸」双持有人状态予以保留：
+--     它现在不再是 bug，而是「部分转交」的正常业务形态。
+--
+-- 幂等：带 IF NOT EXISTS，可重复执行。
+-- 执行：docker exec -i inventory_db psql -U test -d inventory_system < 本文件
+-- =============================================================================
+
+BEGIN;
+
+-- 支撑「该明细行是否已有待接收流水」的唯一性检查，以及按明细行批量取待接收
+CREATE INDEX IF NOT EXISTS ix_trans_borrow_transfer_borrow_status
+    ON trans_borrow_transfer (borrow_id, status);
+
+COMMENT ON COLUMN trans_borrow_transfer.borrow_no IS
+    '借用单号。仅用于单据归属与列表分组展示；转交的**覆盖范围**是 borrow_id 指向的单个明细行';
+COMMENT ON COLUMN trans_borrow_transfer.borrow_id IS
+    '转交目标明细行ID（trans_borrow.id）。转交粒度 = 明细行，一行最多一条待接收流水';
+
+COMMIT;
+
+
+-- =============================================================================
+-- 执行后核对
+-- =============================================================================
+\echo '--- 1) 复合索引已就位 ---'
+SELECT indexname FROM pg_indexes
+ WHERE tablename = 'trans_borrow_transfer'
+   AND indexname = 'ix_trans_borrow_transfer_borrow_status';
+
+\echo '--- 2) 存量流水（borrow_id / borrow_no / status）---'
+SELECT id, borrow_id, borrow_no, status, from_user_name, to_user_name
+  FROM trans_borrow_transfer ORDER BY id;
+
+\echo '--- 3) 各明细行的待接收流水数（应全部 <= 1）---'
+SELECT borrow_id, count(*) AS 待接收数
+  FROM trans_borrow_transfer WHERE status = 'PENDING'
+ GROUP BY borrow_id HAVING count(*) > 1;
+
+\echo '--- 4) 单内多持有人的单号（现在属正常业务形态，不再视为异常）---'
+SELECT borrow_no, count(DISTINCT current_holder_id) AS 持有人数,
+       string_agg(DISTINCT coalesce(current_holder_name,'NULL'), ', ') AS 持有人
+  FROM trans_borrow WHERE is_returned = FALSE
+ GROUP BY borrow_no HAVING count(DISTINCT current_holder_id) > 1;
+
+
+-- =============================================================================
+-- 回滚段
+-- =============================================================================
+-- BEGIN;
+-- DROP INDEX IF EXISTS ix_trans_borrow_transfer_borrow_status;
+-- COMMIT;

inventory-backend/app/api/v1/transactions.py

@@ -636,8 +636,9 @@ def transfer_borrow(borrow_id):
       东西还没到接收人手上，责任仍归原持有人 —— 接收人在自己的列表里确认
       （POST /borrow/transfer/<id>/accept）后才真正转移。
 
-    ★ 覆盖范围是**整张单**（borrow_no）的全部未还明细，不是传入的这一行，
+    ★ 转交粒度 = **明细行**（传入的 borrow_id 就是目标）。同一张单的其他明细
-      避免同一张单出现两个持有人。
+      不受影响，故「借 2 件只转 1 件」得到天然支持；同单不同明细归属不同持有人
+      是正常业务形态。
 
     ★ 严禁触碰库存：转交是纯持有权变更，实物不出入库，
       stock_buy / stock_semi / stock_product 的任何字段都不会被修改。
@@ -677,17 +678,17 @@ def accept_borrow_transfer(transfer_id):
     ★ 权限：**不加 permission_required**。这不是库管职权，而是员工对自己名下
       资产的确认动作；service 层强校验当前登录人 == to_user_id 本人。
 
-    ★ 副作用：该单号下全部未还明细的 current_holder 一并改为接收人。
+    ★ 副作用：**仅**该转交指向的那一条明细的 current_holder 改为接收人。
-      转交是整单行为，不允许单内出现两个持有人。
+      同单的其他明细可能挂在别人名下（部分转交），一律不动。
     """
     try:
-        transfer, affected = TransService.accept_transfer(
+        transfer, record = TransService.accept_transfer(
             transfer_id=transfer_id,
             user_id=get_jwt_identity(),
         )
         return jsonify({
             'code': 200,
-            'msg': f'已接收，{affected} 项资产的持有权已转移到您名下',
+            'msg': f'已接收，物品【{record.sku}】的持有权已转移到您名下',
             'data': transfer.to_dict(),
         }), 200
     except ValueError as e:

inventory-backend/app/services/trans_service.py

@@ -512,30 +512,20 @@ class TransService:
             raise e
 
     # ==========================================================================
-    # 借库转交（一期 + 双向握手）
+    # 借库转交（双向握手 + 明细行粒度）
     #
     # 状态机：
     #   PENDING ──accept──> ACCEPTED  （主表 current_holder 正式转移）
     #       └───reject──> REJECTED  （主表不动，责任仍在原持有人）
     #
-    # ★ 覆盖范围是**整张单**（borrow_no），不是单行明细 —— 原实现收明细行 ID
+    # ★ 转交粒度 = **明细行**（trans_borrow.id），不是整张单。
-    #   只改一行，一张 2 明细的单转交后一半归新接收人、一半仍是原借用人，
+    #   物理现场经常只转交部分工具（借了 2 件、只把 1 件给别人），
-    #   前端按单号聚合便同时显示两个名字（实测 BOR-20260917-0001）。
+    #   一张单下的不同明细归属不同持有人是**正常业务形态**，不是需要修复的
+    #   「单内撕裂」。前端按单号聚合时需自行处理「多人持有」的展示。
+    #
+    #   （唯一性约束也随之从「单号至多一条 PENDING」下沉为「明细行至多一条」，
+    #     故同单的其他明细可以同时各自挂着待接收，互不阻塞。）
     # ==========================================================================
-    @staticmethod
-    def _load_slip_for_update(borrow_no):
-        """
-        按单号锁定整单并返回全部明细行（含已归还的）。
-
-        ★ 按 id 升序加锁：并发下所有事务以相同顺序取行锁，避免与归还/转交
-          交叉加锁造成死锁（与 execute_dispatch 的 items.sort 同一考虑）。
-        """
-        return (TransBorrow.query
-                .filter(TransBorrow.borrow_no == borrow_no)
-                .order_by(TransBorrow.id.asc())
-                .with_for_update()
-                .all())
-
     @staticmethod
     def transfer_borrow(borrow_id, to_user_id, transfer_qty=None, operator_name='System', remark=None):
         """
@@ -564,47 +554,45 @@ class TransService:
         except (TypeError, ValueError):
             raise ValueError("接收人 to_user_id 格式无效，应为数字ID")
 
-        anchor = TransBorrow.query.get(borrow_id)
+        # ★ 转交粒度 = **明细行**（trans_borrow.id），不是整张单。
-        if not anchor:
+        #   物理现场经常只转交部分工具（借了 2 件、只把 1 件给别人），
+        #   一张单下的不同明细本就允许归属不同持有人 —— 那是正常业务形态，
+        #   不是需要修复的「撕裂」。
+        record = TransBorrow.query.with_for_update().get(borrow_id)
+        if not record:
             raise ValueError("借出记录不存在")
-        borrow_no = anchor.borrow_no
+        borrow_no = record.borrow_no
-        if not borrow_no:
-            raise ValueError("该借出记录缺少单号，无法转交")
 
-        rows = TransService._load_slip_for_update(borrow_no)
+        # --- 1. 状态准入：这一行必须还在外 ---
-        open_rows = [r for r in rows if not r.is_returned]
+        if record.is_returned:
+            raise ValueError("该明细已归还，无可转交的实物")
+        if record.status == 'scrapped':
+            raise ValueError("该明细已转入报废流程，不可转交")
 
-        # --- 1. 状态准入 ---
+        # --- 2. 数量：整行转交 ---
-        if not open_rows:
+        #     一行只能有一个 current_holder_id，故不支持「同一行只转一部分」——
-            raise ValueError("该借用单已全部归还，无可转交的实物")
+        #     那需要把这行拆成两行。经业务确认，现场场景中「借 2 件转 1 件」
-        if any(r.status == 'scrapped' for r in open_rows):
+        #     的两件本就是两条明细行，故此限制不影响实际使用。
-            raise ValueError("该借用单已转入报废流程，不可转交")
+        pending_qty = float(record.quantity or 0) - float(record.returned_quantity or 0)
-
+        if pending_qty <= 0:
-        # --- 2. 数量：整单全量，不接受部分转交 ---
+            raise ValueError("该明细待还数量为 0，无可转交的实物")
-        total_pending = sum(
-            float(r.quantity or 0) - float(r.returned_quantity or 0) for r in open_rows
-        )
-        if total_pending <= 0:
-            raise ValueError("该借用单待还数量为 0，无可转交的实物")
         if transfer_qty is not None:
             try:
                 transfer_qty = float(transfer_qty)
             except (TypeError, ValueError):
                 raise ValueError("转交数量格式无效，应为数字")
-            if abs(transfer_qty - total_pending) > 1e-6:
+            if abs(transfer_qty - pending_qty) > 1e-6:
                 raise ValueError(
-                    f"目前仅支持整单全部转交：本单待还 {total_pending}，"
+                    f"转交粒度是整条明细：该明细待还 {pending_qty}，"
-                    f"本次仅转交 {transfer_qty}。部分转交会让同一张单出现两个持有人，"
+                    f"本次填写 {transfer_qty}。若需转交其中一部分，"
-                    f"请整单转交，或先办理部分归还后再转交。"
+                    f"该部分应为另一条明细行。"
                 )
 
-        # --- 3. 转出方 = 所选明细当前的持有人 ---
+        # --- 3. 转出方 = 该明细当前的持有人 ---
-        #     正常单据内各明细持有人一致；历史遗留的「单内撕裂」以所选明细为准，
+        if record.current_holder_id is None:
-        #     accept 时会把该单未还明细**整体归一**到接收人名下（见 accept_transfer）。
+            raise ValueError("该明细的当前持有人未锚定（历史数据），无法转交，请先办理归还")
-        if anchor.current_holder_id is None:
+        from_id = int(record.current_holder_id)
-            raise ValueError("该借出记录的当前持有人未锚定（历史数据），无法转交，请先办理归还")
+        from_name = record.current_holder_name or user_display_name(SysUser.query.get(from_id))
-        from_id = int(anchor.current_holder_id)
-        from_name = anchor.current_holder_name or user_display_name(SysUser.query.get(from_id))
 
         # --- 4. 接收人校验 ---
         to_user = SysUser.query.get(to_user_id)
@@ -614,33 +602,35 @@ class TransService:
         if to_user_id == from_id:
             raise ValueError(f"接收人与当前持有人同为【{to_user_name}】，无需转交")
 
-        # --- 5. 同一单号只允许一条待接收流水（否则两个接收人争抢同一批实物）---
+        # --- 5. 唯一性下沉到明细行：同一行至多一条待接收 ---
+        #     （同一张单的**其他**明细可以同时各自挂一条，互不影响 ——
+        #       这正是部分转交要表达的语义）
         pending = TransBorrowTransfer.query.filter(
-            TransBorrowTransfer.borrow_no == borrow_no,
+            TransBorrowTransfer.borrow_id == record.id,
             TransBorrowTransfer.status == TRANSFER_STATUS_PENDING,
         ).first()
         if pending:
             raise ValueError(
-                f"该借用单已有一条待接收的转交（接收人："
+                f"该物品已有一条待接收的转交（接收人："
                 f"{pending.to_user_name or pending.to_user_id}），请等待对方处理"
             )
 
         # --- 6. 行级公司隔离（Fail-Closed）---
-        _assert_borrow_company_visible(anchor)
+        _assert_borrow_company_visible(record)
 
         # ==================================================================
         # ★ 只写台账，主表 current_holder **保持不变** —— 双向握手的关键。
         #   库存字段更是一律不碰（转交是纯持有权变更，实物不出入库）。
         # ==================================================================
         transfer = TransBorrowTransfer(
-            borrow_id=anchor.id,
+            borrow_id=record.id,
             borrow_no=borrow_no,
             status=TRANSFER_STATUS_PENDING,
             from_user_id=from_id,
             from_user_name=from_name,
             to_user_id=to_user_id,
             to_user_name=to_user_name,
-            transfer_qty=total_pending,
+            transfer_qty=pending_qty,
             transfer_time=beijing_time(),
             operator_name=operator_name,
             remark=remark,
@@ -658,12 +648,12 @@ class TransService:
         """
         接收转交（双向握手第二步）：流水置 ACCEPTED，并**正式转移持有权**。
 
-        覆盖范围 = 该单号下**全部未还明细**。正常单据各明细持有人一致，整批转移
+        覆盖范围 = 该转交指向的**单条明细行**。同一张单的其他明细不受影响 ——
-        天然无歧义；若遇历史遗留的「单内撕裂」，此处的整批归一同时把它修复 ——
+        「借 2 件只转 1 件」时，那 1 件到接收人名下，另 1 件仍在原持有人手上，
-        一张单本就只应有一个持有人。
+        这是正常业务形态。
 
         权限：仅 to_user_id 本人（这是员工对自己名下资产的确认，不是库管权限）。
-        返回 (transfer, 本次转移的明细行数)
+        返回 (transfer, 被转移的明细行)
         """
         transfer = TransBorrowTransfer.query.with_for_update().get(transfer_id)
         if not transfer:
@@ -675,19 +665,22 @@ class TransService:
         if not transfer.borrow_no:
             raise ValueError("该转交记录缺少单号（历史数据），无法确认接收")
 
-        rows = TransService._load_slip_for_update(transfer.borrow_no)
+        # ★ 只转移 transfer.borrow_id 指向的**那一行**：
-        open_rows = [r for r in rows if not r.is_returned]
+        #   转交粒度是明细行，同单的其他明细可能挂在别人名下（部分转交），
-        if not open_rows:
+        #   整批改写会把别人手上的东西一并抢过来。
-            raise ValueError("该借用单已全部归还，无需接收")
+        record = TransBorrow.query.with_for_update().get(transfer.borrow_id)
+        if not record:
+            raise ValueError("转交目标明细已不存在（可能已被删除）")
+        if record.is_returned:
+            raise ValueError("该明细已归还，无需接收")
 
         to_name = transfer.to_user_name
         if not to_name:
             from app.models.system import SysUser
             to_name = user_display_name(SysUser.query.get(transfer.to_user_id))
 
-        for r in open_rows:
+        record.current_holder_id = int(transfer.to_user_id)
-            r.current_holder_id = int(transfer.to_user_id)
+        record.current_holder_name = to_name
-            r.current_holder_name = to_name
 
         transfer.status = TRANSFER_STATUS_ACCEPTED
         try:
@@ -695,7 +688,7 @@ class TransService:
         except Exception as e:
             db.session.rollback()
             raise e
-        return transfer, len(open_rows)
+        return transfer, record
 
     @staticmethod
     def reject_transfer(transfer_id, user_id, reason=None):
@@ -1430,14 +1423,16 @@ class TransService:
             #   应用层保证同一单号最多一条 PENDING，故 borrow_no 可直接作键。
             # ====================================================================
             if items_with_names:
-                _bnos = [d.get('borrow_no') for d in items_with_names if d.get('borrow_no')]
+                # ★ 按**明细行**（borrow_id）关联，不是单号：转交粒度已下沉到明细，
+                #   同一张单可能只有其中一件挂着待接收，其余仍是原持有人。
+                _ids = [d.get('id') for d in items_with_names if d.get('id')]
                 _pending = TransBorrowTransfer.query.filter(
-                    TransBorrowTransfer.borrow_no.in_(_bnos),
+                    TransBorrowTransfer.borrow_id.in_(_ids),
                     TransBorrowTransfer.status == TRANSFER_STATUS_PENDING,
-                ).all() if _bnos else []
+                ).all() if _ids else []
-                _pending_map = {t.borrow_no: t.to_dict() for t in _pending}
+                _pending_map = {t.borrow_id: t.to_dict() for t in _pending}
                 for d in items_with_names:
-                    _pt = _pending_map.get(d.get('borrow_no'))
+                    _pt = _pending_map.get(d.get('id'))
                     if _pt is not None:
                         # ★ is_mine 由后端判定：前端 localStorage 里只有 username
                         #   没有 user_id，靠姓名比对既有歧义又不可靠。