feat: 档口入库码后台批量回写 (#246)

admin/repository/inner_code.go

@@ -21,6 +21,9 @@ var ErrInnerCodeRestoreConflict = errors.New("已回写或需核对的删除记
 // ErrInnerCodeDeleteConflict 表示批量删除时记录已经不可见或不存在，整批不会部分删除。
 var ErrInnerCodeDeleteConflict = errors.New("部分档口入库码记录已删除或不存在")
 
+// ErrInnerCodeApplyConflict 表示所选记录有一条已不再可回写，整批不会部分入队。
+var ErrInnerCodeApplyConflict = errors.New("部分档口入库码记录已不再可回写")
+
 // InnerCodeListFilter 是独立页面可组合的查询条件。
 type InnerCodeListFilter struct {
 	BusinessDate string
@@ -32,9 +35,30 @@ type InnerCodeListFilter struct {
 type InnerCodeStatusCounts struct {
 	Total      int
 	Ready      int
+	Queued     int
+	Applying   int
 	NeedsCheck int
 }
 
+// InnerCodeApplyBatchProgress 是从单表聚合得到的后台回写进度。
+type InnerCodeApplyBatchProgress struct {
+	BatchID       string
+	Total         int
+	Queued        int
+	Applying      int
+	Updated       int
+	AlreadyFilled int
+	Skipped       int
+	Failed        int
+	NeedsCheck    int
+	Ready         int
+}
+
+// Processed 返回已经结束远端处理的数量；恢复为 ready 的未开始记录不算已处理。
+func (p InnerCodeApplyBatchProgress) Processed() int {
+	return p.Updated + p.AlreadyFilled + p.Skipped + p.Failed + p.NeedsCheck
+}
+
 // InnerCodeImportOutcome 说明幂等导入是新增、更新还是恢复软删除记录。
 type InnerCodeImportOutcome string
 
@@ -133,6 +157,7 @@ func UpsertInnerCodeImportRow(tx *sql.Tx, row model.InnerCodeImportRow, now stri
 				    status='pending',stock_id=NULL,detail_id=NULL,syb_spec=NULL,syb_sku=NULL,
 				    syb_variation_sku=NULL,purchase_platform=NULL,purchase_code=NULL,
 				    remote_inner_code=NULL,result_message=NULL,planned_at=NULL,
+				    apply_batch_id=NULL,apply_queued_at=NULL,apply_started_at=NULL,
 				    deleted_at=NULL,deleted_by_user_id=NULL,updated_at=?
 				WHERE id=?`, row.SourceRow, nullablePositiveInt(row.PrintSequence), nullableString(row.ShopName),
 				row.SpecRaw, row.InnerCode, row.SourceDuplicateCount, now, id)
@@ -147,18 +172,21 @@ func UpsertInnerCodeImportRow(tx *sql.Tx, row model.InnerCodeImportRow, now stri
 		UPDATE syb_inner_code_records
 		   SET source_row=?,print_sequence=?,shop_name=?,spec_raw=?,inner_code=?,
 		       source_duplicate_count=?,
-		       status=CASE WHEN status IN ('updated','already_filled','applying','needs_check')
+		       status=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check')
 		                   THEN status ELSE 'pending' END,
-		       stock_id=CASE WHEN status IN ('updated','already_filled','applying','needs_check') THEN stock_id ELSE NULL END,
-		       detail_id=CASE WHEN status IN ('updated','already_filled','applying','needs_check') THEN detail_id ELSE NULL END,
-		       syb_spec=CASE WHEN status IN ('updated','already_filled','applying','needs_check') THEN syb_spec ELSE NULL END,
-		       syb_sku=CASE WHEN status IN ('updated','already_filled','applying','needs_check') THEN syb_sku ELSE NULL END,
-		       syb_variation_sku=CASE WHEN status IN ('updated','already_filled','applying','needs_check') THEN syb_variation_sku ELSE NULL END,
-		       purchase_platform=CASE WHEN status IN ('updated','already_filled','applying','needs_check') THEN purchase_platform ELSE NULL END,
-		       purchase_code=CASE WHEN status IN ('updated','already_filled','applying','needs_check') THEN purchase_code ELSE NULL END,
-		       remote_inner_code=CASE WHEN status IN ('updated','already_filled','applying','needs_check') THEN remote_inner_code ELSE NULL END,
-		       result_message=CASE WHEN status IN ('updated','already_filled','applying','needs_check') THEN result_message ELSE NULL END,
-		       planned_at=CASE WHEN status IN ('updated','already_filled','applying','needs_check') THEN planned_at ELSE NULL END,
+		       stock_id=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN stock_id ELSE NULL END,
+		       detail_id=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN detail_id ELSE NULL END,
+		       syb_spec=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN syb_spec ELSE NULL END,
+		       syb_sku=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN syb_sku ELSE NULL END,
+		       syb_variation_sku=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN syb_variation_sku ELSE NULL END,
+		       purchase_platform=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN purchase_platform ELSE NULL END,
+		       purchase_code=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN purchase_code ELSE NULL END,
+		       remote_inner_code=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN remote_inner_code ELSE NULL END,
+		       result_message=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN result_message ELSE NULL END,
+		       planned_at=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN planned_at ELSE NULL END,
+		       apply_batch_id=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN apply_batch_id ELSE NULL END,
+		       apply_queued_at=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN apply_queued_at ELSE NULL END,
+		       apply_started_at=CASE WHEN status IN ('queued','updated','already_filled','applying','needs_check') THEN apply_started_at ELSE NULL END,
 		       updated_at=?
 		 WHERE id=?`,
 		row.SourceRow, nullablePositiveInt(row.PrintSequence), nullableString(row.ShopName), row.SpecRaw,
@@ -171,7 +199,8 @@ func UpsertInnerCodeImportRow(tx *sql.Tx, row model.InnerCodeImportRow, now stri
 
 func innerCodeStatusPreservesImportResult(status model.InnerCodeStatus) bool {
 	switch status {
-	case model.InnerCodeApplying, model.InnerCodeUpdated, model.InnerCodeAlreadyFilled, model.InnerCodeNeedsCheck:
+	case model.InnerCodeQueued, model.InnerCodeApplying, model.InnerCodeUpdated,
+		model.InnerCodeAlreadyFilled, model.InnerCodeNeedsCheck:
 		return true
 	default:
 		return false
@@ -239,7 +268,7 @@ func ListInnerCodePlanningContext(q Execer, businessDate string, orderNumbers []
 	rows, err := q.Query(`SELECT `+innerCodeListColumns+`
 		  FROM syb_inner_code_records
 		 WHERE business_date=? AND order_number IN (`+strings.Join(placeholders, ",")+`)
-		   AND (deleted_at IS NULL OR status IN ('applying','updated','already_filled','needs_check'))
+		   AND (deleted_at IS NULL OR status IN ('queued','applying','updated','already_filled','needs_check'))
 		 ORDER BY source_row,id`, args...)
 	if err != nil {
 		return nil, fmt.Errorf("查询档口入库码匹配上下文失败: %w", err)
@@ -274,7 +303,8 @@ func SaveInnerCodePlans(db *sql.DB, plans []model.InnerCodeRecord, plannedAt str
 			UPDATE syb_inner_code_records
 			   SET stock_id=?,detail_id=?,syb_spec=?,syb_sku=?,syb_variation_sku=?,
 			       purchase_platform=?,purchase_code=?,remote_inner_code=?,status=?,
-			       result_message=?,planned_at=?,updated_at=?
+			       result_message=?,planned_at=?,apply_batch_id=NULL,apply_queued_at=NULL,
+			       apply_started_at=NULL,updated_at=?
 			 WHERE id=? AND deleted_at IS NULL AND status IN ('pending','ready','skipped','failed')`,
 			nullablePositiveInt64(plan.StockID), nullablePositiveInt64(plan.DetailID),
 			nullableString(plan.SybSpec), nullableString(plan.SybSKU), nullableString(plan.SybVariationSKU),
@@ -322,7 +352,7 @@ func lockAndValidateInnerCodePlanClaims(tx *sql.Tx, plans []model.InnerCodeRecor
 		rows, err := tx.Query(`SELECT id,COALESCE(detail_id,0),status
 			FROM syb_inner_code_records
 			WHERE business_date=? AND order_number=?
-			  AND (deleted_at IS NULL OR status IN ('applying','updated','already_filled','needs_check'))
+			  AND (deleted_at IS NULL OR status IN ('queued','applying','updated','already_filled','needs_check'))
 			ORDER BY id FOR UPDATE`, key.BusinessDate, key.OrderNumber)
 		if err != nil {
 			return fmt.Errorf("锁定档口入库码订单匹配上下文失败: %w", err)
@@ -362,7 +392,7 @@ func lockAndValidateInnerCodePlanClaims(tx *sql.Tx, plans []model.InnerCodeRecor
 
 func innerCodeStatusHoldsDetail(status model.InnerCodeStatus) bool {
 	switch status {
-	case model.InnerCodeReady, model.InnerCodeApplying, model.InnerCodeUpdated,
+	case model.InnerCodeReady, model.InnerCodeQueued, model.InnerCodeApplying, model.InnerCodeUpdated,
 		model.InnerCodeAlreadyFilled, model.InnerCodeNeedsCheck:
 		return true
 	default:
@@ -372,6 +402,7 @@ func innerCodeStatusHoldsDetail(status model.InnerCodeStatus) bool {
 
 const innerCodeListColumns = `id,business_date,source_row,COALESCE(print_sequence,0),order_number,
 	COALESCE(shop_name,''),stall,spec_raw,spec_key,inner_code,source_duplicate_count,
+	COALESCE(apply_batch_id,''),COALESCE(apply_queued_at,''),
 	COALESCE(stock_id,0),COALESCE(detail_id,0),COALESCE(syb_spec,''),COALESCE(syb_sku,''),
 	COALESCE(syb_variation_sku,''),COALESCE(purchase_platform,''),COALESCE(purchase_code,''),
 	COALESCE(remote_inner_code,''),status,COALESCE(result_message,''),created_by_user_id,
@@ -429,13 +460,14 @@ func CountInnerCodeRecords(q Execer, filter InnerCodeListFilter) (int, error) {
 	return count, nil
 }
 
-// CountInnerCodeStatuses 统计当前业务日期总量、可回写和需核对数量。
+// CountInnerCodeStatuses 统计当前业务日期总量和后台回写关键状态。
 func CountInnerCodeStatuses(q Execer, businessDate string) (InnerCodeStatusCounts, error) {
 	var result InnerCodeStatusCounts
 	err := q.QueryRow(`SELECT COUNT(*),
-		COALESCE(SUM(status='ready'),0),COALESCE(SUM(status='needs_check'),0)
+		COALESCE(SUM(status='ready'),0),COALESCE(SUM(status='queued'),0),
+		COALESCE(SUM(status='applying'),0),COALESCE(SUM(status='needs_check'),0)
 		FROM syb_inner_code_records WHERE business_date=? AND deleted_at IS NULL`, businessDate).
-		Scan(&result.Total, &result.Ready, &result.NeedsCheck)
+		Scan(&result.Total, &result.Ready, &result.Queued, &result.Applying, &result.NeedsCheck)
 	if err != nil {
 		return result, fmt.Errorf("统计档口入库码状态失败: %w", err)
 	}
@@ -450,7 +482,8 @@ func scanInnerCodeRecord(scanner innerCodeRowScanner) (model.InnerCodeRecord, er
 	var row model.InnerCodeRecord
 	err := scanner.Scan(&row.ID, &row.BusinessDate, &row.SourceRow, &row.PrintSequence,
 		&row.OrderNumber, &row.ShopName, &row.Stall, &row.SpecRaw, &row.SpecKey,
-		&row.InnerCode, &row.SourceDuplicateCount, &row.StockID, &row.DetailID,
+		&row.InnerCode, &row.SourceDuplicateCount, &row.ApplyBatchID, &row.ApplyQueuedAt,
+		&row.StockID, &row.DetailID,
 		&row.SybSpec, &row.SybSKU, &row.SybVariationSKU, &row.PurchasePlatform,
 		&row.PurchaseCode, &row.RemoteInnerCode, &row.Status, &row.ResultMessage,
 		&row.CreatedByUserID, &row.AppliedByUserID, &row.PlannedAt, &row.ApplyStartedAt,
@@ -461,41 +494,148 @@ func scanInnerCodeRecord(scanner innerCodeRowScanner) (model.InnerCodeRecord, er
 	return row, nil
 }
 
-// ClaimInnerCodeForApply 原子领取一条 ready 记录。返回 claimed=false 表示状态已变化。
-func ClaimInnerCodeForApply(db *sql.DB, id int64, actorUserID, now string) (*model.InnerCodeRecord, bool, error) {
+// QueueInnerCodeApplyBatch 把所选 ready 记录原子加入同一后台批次。
+// 任一记录不存在、已删除或状态变化时整批回滚，避免页面选择与实际队列不一致。
+func QueueInnerCodeApplyBatch(db *sql.DB, ids []int64, batchID, actorUserID, queuedAt string) (int, error) {
+	if len(ids) == 0 {
+		return 0, nil
+	}
+	placeholders := make([]string, len(ids))
+	args := make([]any, 0, len(ids)+4)
+	args = append(args, batchID, queuedAt, actorUserID, queuedAt)
+	for index, id := range ids {
+		placeholders[index] = "?"
+		args = append(args, id)
+	}
 	tx, err := db.Begin()
 	if err != nil {
-		return nil, false, fmt.Errorf("开始领取档口入库码事务失败: %w", err)
+		return 0, fmt.Errorf("开始档口入库码排队事务失败: %w", err)
 	}
 	defer tx.Rollback()
-	record, err := scanInnerCodeRecord(tx.QueryRow(`SELECT `+innerCodeListColumns+
-		` FROM syb_inner_code_records WHERE id=? AND deleted_at IS NULL FOR UPDATE`, id))
-	if errors.Is(err, sql.ErrNoRows) {
+	result, err := tx.Exec(`UPDATE syb_inner_code_records
+		SET status='queued',apply_batch_id=?,apply_queued_at=?,applied_by_user_id=?,
+		    result_message='已进入后台回写队列',apply_started_at=NULL,updated_at=?
+		WHERE deleted_at IS NULL AND status='ready' AND id IN (`+strings.Join(placeholders, ",")+`)`, args...)
+	if err != nil {
+		return 0, fmt.Errorf("档口入库码加入后台队列失败: %w", err)
+	}
+	affected, err := result.RowsAffected()
+	if err != nil {
+		return 0, fmt.Errorf("读取档口入库码排队数量失败: %w", err)
+	}
+	if affected != int64(len(ids)) {
+		return 0, ErrInnerCodeApplyConflict
+	}
+	if err := tx.Commit(); err != nil {
+		return 0, fmt.Errorf("提交档口入库码排队事务失败: %w", err)
+	}
+	return int(affected), nil
+}
+
+// ListQueuedInnerCodeIDs 返回批次下一组待处理记录。分组只控制数据库读取，不放宽逐条远端门禁。
+func ListQueuedInnerCodeIDs(q Execer, batchID string, limit int) ([]int64, error) {
+	rows, err := q.Query(`SELECT id FROM syb_inner_code_records
+		WHERE apply_batch_id=? AND status='queued' ORDER BY id LIMIT ?`, batchID, limit)
+	if err != nil {
+		return nil, fmt.Errorf("读取档口入库码后台队列失败: %w", err)
+	}
+	defer rows.Close()
+	ids := make([]int64, 0, limit)
+	for rows.Next() {
+		var id int64
+		if err := rows.Scan(&id); err != nil {
+			return nil, fmt.Errorf("读取档口入库码后台队列编号失败: %w", err)
+		}
+		ids = append(ids, id)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("遍历档口入库码后台队列失败: %w", err)
+	}
+	return ids, nil
+}
+
+// ClaimQueuedInnerCodeForApply 原子领取批次中的一条 queued 记录。
+func ClaimQueuedInnerCodeForApply(db *sql.DB, id int64, batchID, actorUserID, now string) (*model.InnerCodeRecord, bool, error) {
+	tx, err := db.Begin()
+	if err != nil {
+		return nil, false, fmt.Errorf("开始领取档口入库码后台事务失败: %w", err)
+	}
+	defer tx.Rollback()
+	result, err := tx.Exec(`UPDATE syb_inner_code_records
+		SET status='applying',applied_by_user_id=?,apply_started_at=?,updated_at=?
+		WHERE id=? AND apply_batch_id=? AND status='queued'`, actorUserID, now, now, id, batchID)
+	if err != nil {
+		return nil, false, fmt.Errorf("领取档口入库码后台记录失败: %w", err)
+	}
+	affected, err := result.RowsAffected()
+	if err != nil {
+		return nil, false, fmt.Errorf("读取档口入库码后台领取结果失败: %w", err)
+	}
+	if affected != 1 {
 		return nil, false, nil
 	}
+	record, err := scanInnerCodeRecord(tx.QueryRow(`SELECT `+innerCodeListColumns+
+		` FROM syb_inner_code_records WHERE id=? AND apply_batch_id=?`, id, batchID))
 	if err != nil {
 		return nil, false, err
 	}
-	if record.Status != model.InnerCodeReady {
-		return &record, false, nil
+	if err := tx.Commit(); err != nil {
+		return nil, false, fmt.Errorf("提交档口入库码后台领取失败: %w", err)
 	}
-	result, err := tx.Exec(`UPDATE syb_inner_code_records
-		SET status='applying',applied_by_user_id=?,apply_started_at=?,updated_at=?
-		WHERE id=? AND deleted_at IS NULL AND status='ready'`, actorUserID, now, now, id)
+	return &record, true, nil
+}
+
+// InterruptInnerCodeApplyBatch 收敛异常批次：未知远端结果转需核对，未开始记录恢复可回写。
+func InterruptInnerCodeApplyBatch(db *sql.DB, batchID, interruptedAt string) (int, int, error) {
+	tx, err := db.Begin()
 	if err != nil {
-		return nil, false, fmt.Errorf("领取档口入库码记录失败: %w", err)
+		return 0, 0, fmt.Errorf("开始收敛档口入库码后台批次失败: %w", err)
 	}
-	if affected, err := result.RowsAffected(); err != nil || affected != 1 {
-		return &record, false, nil
+	defer tx.Rollback()
+	applying, err := tx.Exec(`UPDATE syb_inner_code_records
+		SET status='needs_check',result_message='后台回写异常中断，远端结果不确定；系统不会自动重写',updated_at=?
+		WHERE apply_batch_id=? AND status='applying'`, interruptedAt, batchID)
+	if err != nil {
+		return 0, 0, fmt.Errorf("收敛档口入库码未知回写结果失败: %w", err)
+	}
+	queued, err := tx.Exec(`UPDATE syb_inner_code_records
+		SET status='ready',result_message='后台回写中断，本条尚未发送远端请求，已恢复为可回写',updated_at=?
+		WHERE apply_batch_id=? AND status='queued'`, interruptedAt, batchID)
+	if err != nil {
+		return 0, 0, fmt.Errorf("释放档口入库码后台队列失败: %w", err)
+	}
+	applyingCount, err := applying.RowsAffected()
+	if err != nil {
+		return 0, 0, fmt.Errorf("读取档口入库码未知结果数量失败: %w", err)
+	}
+	queuedCount, err := queued.RowsAffected()
+	if err != nil {
+		return 0, 0, fmt.Errorf("读取档口入库码后台释放数量失败: %w", err)
 	}
 	if err := tx.Commit(); err != nil {
-		return nil, false, fmt.Errorf("提交档口入库码领取失败: %w", err)
+		return 0, 0, fmt.Errorf("提交档口入库码后台收敛失败: %w", err)
 	}
-	record.Status = model.InnerCodeApplying
-	record.AppliedByUserID = actorUserID
-	record.ApplyStartedAt = now
-	record.UpdatedAt = now
-	return &record, true, nil
+	return int(applyingCount), int(queuedCount), nil
+}
+
+// GetInnerCodeApplyBatchProgress 从现有业务表聚合批次进度。
+func GetInnerCodeApplyBatchProgress(q Execer, batchID string) (*InnerCodeApplyBatchProgress, error) {
+	p := &InnerCodeApplyBatchProgress{BatchID: batchID}
+	err := q.QueryRow(`SELECT COUNT(*),
+		COALESCE(SUM(status='queued'),0),COALESCE(SUM(status='applying'),0),
+		COALESCE(SUM(status='updated'),0),COALESCE(SUM(status='already_filled'),0),
+		COALESCE(SUM(status='skipped'),0),COALESCE(SUM(status='failed'),0),
+		COALESCE(SUM(status='needs_check'),0),COALESCE(SUM(status='ready'),0)
+		FROM syb_inner_code_records WHERE apply_batch_id=?`, batchID).
+		Scan(&p.Total, &p.Queued, &p.Applying, &p.Updated, &p.AlreadyFilled,
+			&p.Skipped, &p.Failed, &p.NeedsCheck, &p.Ready)
+	if err != nil {
+		return nil, fmt.Errorf("读取档口入库码后台进度失败: %w", err)
+	}
+	if p.Total == 0 {
+		return nil, nil
+	}
+	return p, nil
 }
 
 // FinishInnerCodeApply 保存一条已领取记录的最终结果。
@@ -579,19 +719,29 @@ func SaveInnerCodeRecheck(q Execer, id int64, status model.InnerCodeStatus, mess
 	return nil
 }
 
-// InterruptApplyingInnerCodes 在启动时把未知结果的 applying 收敛为 needs_check。
+// InterruptApplyingInnerCodes 在启动时收敛后台状态：未知写入转需核对，未开始队列恢复可回写。
 func InterruptApplyingInnerCodes(q Execer, interruptedAt string) (int, error) {
-	result, err := q.Exec(`UPDATE syb_inner_code_records
+	applying, err := q.Exec(`UPDATE syb_inner_code_records
 		SET status='needs_check',result_message='Admin 在回写完成前退出，请重新核对远端结果；系统不会自动重写',
 		    updated_at=? WHERE status='applying'`, interruptedAt)
 	if err != nil {
 		return 0, fmt.Errorf("恢复中断的档口入库码回写失败: %w", err)
 	}
-	affected, err := result.RowsAffected()
+	applyingCount, err := applying.RowsAffected()
 	if err != nil {
 		return 0, fmt.Errorf("读取中断档口入库码数量失败: %w", err)
 	}
-	return int(affected), nil
+	queued, err := q.Exec(`UPDATE syb_inner_code_records
+		SET status='ready',result_message='Admin 在后台回写开始前退出，本条未发送远端请求，已恢复为可回写',
+		    updated_at=? WHERE status='queued'`, interruptedAt)
+	if err != nil {
+		return 0, fmt.Errorf("恢复未开始的档口入库码队列失败: %w", err)
+	}
+	queuedCount, err := queued.RowsAffected()
+	if err != nil {
+		return 0, fmt.Errorf("读取恢复档口入库码队列数量失败: %w", err)
+	}
+	return int(applyingCount + queuedCount), nil
 }
 
 func nullablePositiveInt(value int) any {