feat: add inbound hold lifecycle

firstleg/src/main/resources/openapi/firstleg-v1.yaml

@@ -6,6 +6,44 @@ info:
 security:
   - bearerAuth: []
 paths:
+  /api/platform/inbounds/{inboundId}/hold:
+    get:
+      summary: 查询入库单当前扣货快照与不可变历史
+      description: 需要 platform:firstleg:inbound:list；canHold/canRelease 由服务端按实物作业事实计算，前端不得推导。
+      parameters:
+        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+      responses:
+        '200': {description: 成功时 data 为 InboundHoldDetail；客户归属不匹配时响应体 code=A0404}
+    post:
+      summary: 扣货入库单
+      description: 需要 platform:firstleg:inbound:hold；同事务写当前快照和不可变历史，不改变 Order 主状态。
+      parameters:
+        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/InboundHoldCommand'}
+      responses:
+        '200': {description: 成功或完全同参幂等重放时 data 为 InboundHoldDetail；版本、状态、异参重放或实物作业冲突时响应体 code=A0409}
+  /api/platform/inbounds/{inboundId}/hold/release:
+    post:
+      summary: 解除入库单扣货
+      description: 需要 platform:firstleg:inbound:hold；解除原因进入不可变历史，当前原因快照清空，入库聚合 version 递增 1。
+      parameters:
+        - {name: inboundId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: tenantId, in: query, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/InboundHoldCommand'}
+      responses:
+        '200': {description: 成功或完全同参幂等重放时 data 为 InboundHoldDetail；版本、状态、异参重放或实物作业冲突时响应体 code=A0409}
   /api/merchant/v1/first-leg/inbounds/{inboundId}/carton-label-pdf:
     post:
       summary: 客户端生成本客户入库单箱唛 PDF
@@ -1218,6 +1256,38 @@ components:
       required: true
       schema: {type: string, pattern: '^[1-9][0-9]*$'}
   schemas:
+    InboundHoldCommand:
+      type: object
+      required: [expectedVersion, reason]
+      properties:
+        expectedVersion: {type: integer, minimum: 0, description: 当前入库聚合 version；成功后递增 1}
+        reason: {type: string, minLength: 1, maxLength: 1000}
+        evidenceFileId: {type: integer, format: int64, minimum: 1, nullable: true, description: 可选的既有证据文件引用；本接口不上传文件}
+    InboundHoldHistoryItem:
+      type: object
+      required: [id, action, reason, operatedAt]
+      properties:
+        id: {type: integer, format: int64}
+        action: {type: string, enum: [HOLD, RELEASE]}
+        reason: {type: string, maxLength: 1000}
+        evidenceFileId: {type: integer, format: int64, nullable: true}
+        operatorName: {type: string, nullable: true}
+        operatedAt: {type: string, format: date-time}
+    InboundHoldDetail:
+      type: object
+      required: [inboundId, tenantId, holdFlag, version, canHold, canRelease, history]
+      properties:
+        inboundId: {type: integer, format: int64}
+        tenantId: {type: integer, format: int64}
+        holdFlag: {type: boolean, description: 当前权威扣货状态}
+        currentHoldReason: {type: string, maxLength: 1000, nullable: true, description: 未扣货时固定为 null}
+        version: {type: integer, minimum: 0}
+        canHold: {type: boolean}
+        canRelease: {type: boolean}
+        actionBlockReason: {type: string, nullable: true}
+        history:
+          type: array
+          items: {$ref: '#/components/schemas/InboundHoldHistoryItem'}
     OrderChannelChangeValidationRequest:
       type: object
       additionalProperties: false