@kevlns/xlmerge 2.0.0 → 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,6 +6,7 @@ import hashlib
6
6
  import io
7
7
  import json
8
8
  import os
9
+ import re
9
10
  import shutil
10
11
  import subprocess
11
12
  import sys
@@ -27,6 +28,7 @@ if str(_PKG_ROOT) not in sys.path:
27
28
  sys.path.insert(0, str(_PKG_ROOT))
28
29
 
29
30
  from xlsx_merge_engine.xlsx_git_merge_bridge import analyze_workbooks as analyze_structural_workbooks
31
+ from prepare_progress import checkpoint, PreparationCancelled
30
32
 
31
33
 
32
34
  class ConflictError(RuntimeError):
@@ -306,8 +308,10 @@ def _workbook_has_formula(path: Path | str) -> bool:
306
308
  workbook.close()
307
309
 
308
310
 
309
- def _validate_value_workbook(path: Path | str) -> None:
310
- """Snapshots must be literal and must not contain calculation errors."""
311
+ def _validate_value_workbook(path: Path | str, *, allow_errors: bool = False) -> list[dict[str, Any]]:
312
+ """Validate literal snapshots; only history can contain typed unknowns."""
313
+ from formula_values import _ERROR_VALUES
314
+ errors = []
311
315
  workbook = load_workbook(path, data_only=False, keep_links=True, read_only=True)
312
316
  try:
313
317
  for ws in workbook.worksheets:
@@ -318,14 +322,19 @@ def _validate_value_workbook(path: Path | str) -> None:
318
322
  f"Formula materialization produced a formula in {path} ({ws.title}!{cell.coordinate})."
319
323
  )
320
324
  if cell.data_type == "e":
321
- raise ConflictError(
322
- f"Formula materialization produced an Excel error in {path} ({ws.title}!{cell.coordinate})."
323
- )
325
+ if not isinstance(cell.value, str) or cell.value not in _ERROR_VALUES:
326
+ raise ConflictError(f"Invalid Excel error at {ws.title}!{cell.coordinate}: {cell.value}")
327
+ if not allow_errors:
328
+ raise ConflictError(
329
+ f"Formula materialization produced an Excel error in {path} ({ws.title}!{cell.coordinate})."
330
+ )
331
+ errors.append({"sheet": ws.title, "coordinate": cell.coordinate, "error": cell.value})
324
332
  finally:
325
333
  workbook.close()
334
+ return errors
326
335
 
327
336
 
328
- def _materialize_value_snapshot(source_path: Path | str, output_path: Path | str | None) -> Path:
337
+ def _materialize_value_snapshot(source_path: Path | str, output_path: Path | str | None, *, allow_errors: bool = False) -> Path:
329
338
  """Calculate one complete source workbook and return its literal snapshot.
330
339
 
331
340
  The implementation lives in formula_values.py so Excel/LibreOffice policy is
@@ -342,7 +351,9 @@ def _materialize_value_snapshot(source_path: Path | str, output_path: Path | str
342
351
  except ImportError as exc:
343
352
  raise ConflictError("Formula materialization is unavailable; refusing to compare formula workbooks.") from exc
344
353
  try:
345
- result = materialize_values(source, destination)
354
+ result = materialize_values(source, destination, allow_errors=allow_errors)
355
+ except PreparationCancelled:
356
+ raise
346
357
  except Exception as exc:
347
358
  raise ConflictError(f"Failed to calculate workbook {source}: {exc}") from exc
348
359
  value_path = Path(result) if result is not None else destination
@@ -350,7 +361,7 @@ def _materialize_value_snapshot(source_path: Path | str, output_path: Path | str
350
361
  value_path = (destination.parent / value_path).resolve()
351
362
  if not value_path.exists():
352
363
  raise ConflictError(f"Formula materialization did not produce a workbook for {source}.")
353
- _validate_value_workbook(value_path)
364
+ _validate_value_workbook(value_path, allow_errors=allow_errors)
354
365
  return value_path
355
366
 
356
367
 
@@ -367,6 +378,7 @@ def _snapshot_workbooks(
367
378
  snapshots: dict[str, Path | None] = {}
368
379
  metadata: dict[str, dict[str, Any]] = {}
369
380
  for side, source in sources.items():
381
+ checkpoint(phase='计算公式并验证', side=side, sheet='', sheetDone=0, sheetTotal=0)
370
382
  if source is None:
371
383
  snapshots[side] = None
372
384
  continue
@@ -375,10 +387,10 @@ def _snapshot_workbooks(
375
387
  # needless package rewrite (and preserve exact zip bytes for safety).
376
388
  if _workbook_has_formula(source):
377
389
  output = analysis_dir / f"{side}.values{source.suffix.lower()}"
378
- value_path = _materialize_value_snapshot(source, output)
390
+ value_path = _materialize_value_snapshot(source, output, allow_errors=True)
379
391
  else:
380
392
  value_path = source
381
- _validate_value_workbook(value_path)
393
+ _validate_value_workbook(value_path, allow_errors=True)
382
394
  snapshots[side] = value_path
383
395
  metadata[side] = {
384
396
  "sourcePath": str(source),
@@ -386,9 +398,183 @@ def _snapshot_workbooks(
386
398
  "valuePath": str(value_path),
387
399
  "valueSha256": _sha256_path(value_path),
388
400
  }
401
+ errors = _validate_value_workbook(value_path, allow_errors=True)
402
+ metadata[side]["errors"] = errors
403
+ if errors:
404
+ source_book = load_workbook(source, data_only=False, keep_links=False)
405
+ try:
406
+ for error in errors:
407
+ error["formula"] = source_book[error["sheet"]][error["coordinate"]].value
408
+ error.update(_repair_field_info(source_book[error['sheet']], error['coordinate']))
409
+ finally:
410
+ source_book.close()
411
+ _replace_common_errors(snapshots, metadata, analysis_dir)
389
412
  return snapshots, metadata
390
413
 
391
414
 
415
+ def _repair_field_info(ws, coordinate):
416
+ column = ws[coordinate].column
417
+ var = next((r for r in range(1, min(ws.max_row, 40) + 1) if ws.cell(r, 1).value == '##var'), None)
418
+ typ = next((r for r in range(1, min(ws.max_row, 80) + 1) if ws.cell(r, 1).value == '##type'), None)
419
+ if var is None or typ is None:
420
+ return {}
421
+ field = str(ws.cell(var, column).value or '')
422
+ kind = str(ws.cell(typ, column).value or '').strip().casefold()
423
+ info = {'field': field, 'type': kind}
424
+ default = '' if kind == 'string' else False if kind == 'bool' else 0
425
+ try:
426
+ _validate_repair_value(kind, default)
427
+ except ConflictError:
428
+ return info
429
+ guarded = field.casefold().endswith('id') or 'ref' in field.casefold() or any(
430
+ ws.cell(r, 1).value in ('##ref', '##refs', '##key', '##index', '##validator', '##validate', '##validation', '##min', '##max', '##range', '##constraint')
431
+ and ws.cell(r, column).value not in (None, '') for r in range(var, typ + 10))
432
+ if not guarded:
433
+ info['defaultValue'] = default
434
+ return info
435
+
436
+
437
+ def _validate_repair_value(kind, value):
438
+ import math
439
+ if kind == 'string' and isinstance(value, str):
440
+ return
441
+ if kind == 'bool' and isinstance(value, bool):
442
+ return
443
+ if kind in ('float', 'double', 'decimal') and type(value) in (int, float) and math.isfinite(value):
444
+ return
445
+ match = re.fullmatch(r'(u?int)(8|16|32|64)?|(s?byte|u?short|u?long)', kind)
446
+ if match and type(value) is int:
447
+ bits = int(match.group(2) or 32) if match.group(1) else {'byte': 8, 'sbyte': 8, 'short': 16, 'ushort': 16, 'long': 64, 'ulong': 64}[kind]
448
+ unsigned = kind.startswith('u') or kind == 'byte'
449
+ if (0 if unsigned else -(2 ** (bits - 1))) <= value <= 2 ** (bits if unsigned else bits - 1) - 1:
450
+ return
451
+ raise ConflictError(f'修复值不符合声明类型 {kind!r};ID/引用值还需人工核对业务有效性。')
452
+
453
+
454
+ def _selected_repairs(sheet, selection):
455
+ side = selection.get('sheet')
456
+ errors = [e for e in sheet.get('calculationErrors', []) if e['side'] == side]
457
+ values = (selection.get('repairs') or {}).get(side, {})
458
+ if not isinstance(values, dict):
459
+ raise ConflictError('修复值必须按单元格提供。')
460
+ allowed = {e['coordinate']: e for e in errors}
461
+ if set(values) - set(allowed):
462
+ raise ConflictError('修复包含未经审阅的单元格。')
463
+ for coordinate, value in values.items():
464
+ _validate_repair_value(allowed[coordinate].get('type', ''), value)
465
+ for error in errors:
466
+ if error['coordinate'] not in values:
467
+ raise ConflictError(f"请修复所选 {side} 来源的 {sheet['name']}!{error['coordinate']}: {error['error']}")
468
+ return values
469
+
470
+
471
+ def _error_replacement_schema(ws):
472
+ """Only explicit primitive Luban fields with unique, valid IDs qualify."""
473
+ var_row = next((row for row in range(1, min(ws.max_row, 40) + 1)
474
+ if ws.cell(row, 1).value == "##var"), None)
475
+ if var_row is None:
476
+ return None
477
+ type_row = next((row for row in range(var_row + 1, min(ws.max_row, var_row + 40) + 1)
478
+ if ws.cell(row, 1).value == "##type"), None)
479
+ if type_row is None:
480
+ return None
481
+ fields = {}
482
+ duplicates = set()
483
+ for cell in list(ws._cells.values()):
484
+ if cell.row != var_row or cell.column == 1 or not isinstance(cell.value, str) or not cell.value.strip():
485
+ continue
486
+ field = cell.value.strip()
487
+ if field in fields:
488
+ duplicates.add(field)
489
+ fields[field] = cell.column
490
+ fields = {field: column for field, column in fields.items() if field not in duplicates}
491
+ ids = [column for field, column in fields.items() if field.casefold() == "id"]
492
+ if len(ids) != 1:
493
+ return None
494
+ start = var_row
495
+ while start <= ws.max_row and isinstance(ws.cell(start, 1).value, str) and ws.cell(start, 1).value.startswith("##"):
496
+ start += 1
497
+ records, duplicate_ids = {}, set()
498
+ for cell in list(ws._cells.values()):
499
+ if cell.column != ids[0] or cell.row < start:
500
+ continue
501
+ if cell.data_type == "e" or cell.value in (None, "") or not isinstance(cell.value, (str, int, float)) or isinstance(cell.value, bool):
502
+ continue
503
+ key = (cell.data_type, cell.value)
504
+ if key in records:
505
+ duplicate_ids.add(key)
506
+ records[key] = cell.row
507
+ records = {key: row for key, row in records.items() if key not in duplicate_ids}
508
+ defaults = {}
509
+ for field, column in fields.items():
510
+ if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", field) or field.casefold().endswith("id") or "ref" in field.casefold():
511
+ continue
512
+ if any(ws.cell(row, 1).value in ("##ref", "##refs", "##key", "##index", "##validator", "##validate", "##validation", "##min", "##max", "##range", "##constraint")
513
+ and ws.cell(row, column).value not in (None, "") for row in range(var_row, start)):
514
+ continue
515
+ kind = str(ws.cell(type_row, column).value or "").strip().casefold()
516
+ if kind == "string":
517
+ defaults[field] = (column, kind, "")
518
+ elif kind == "bool":
519
+ defaults[field] = (column, kind, False)
520
+ elif re.fullmatch(r"(?:s?byte|u?short|u?int|u?long|float|double|decimal|u?int(?:8|16|32|64))", kind):
521
+ defaults[field] = (column, kind, 0)
522
+ return records, defaults
523
+
524
+
525
+ def _replace_common_errors(paths, metadata, analysis_dir):
526
+ """Apply authorized defaults only to corresponding errors on both sides.
527
+
528
+ Use declared fields and unique IDs before structural alignment. Never
529
+ guess types from number formats, errors, or adjacent cells, and never
530
+ modify an extracted Git source or the repository working tree.
531
+ """
532
+ if not all(metadata.get(side, {}).get("errors") for side in ("ours", "theirs")):
533
+ return
534
+ from formula_values import _set_literal
535
+ books = {side: load_workbook(paths[side], keep_vba=paths[side].suffix.lower() == ".xlsm")
536
+ for side in ("ours", "theirs")}
537
+ replacements = {side: [] for side in books}
538
+ try:
539
+ errors = {side: {(error["sheet"], error["coordinate"]): error for error in metadata[side]["errors"]}
540
+ for side in books}
541
+ for name in set(books["ours"].sheetnames) & set(books["theirs"].sheetnames):
542
+ schemas = {side: _error_replacement_schema(book[name]) for side, book in books.items()}
543
+ if not all(schemas.values()):
544
+ continue
545
+ ours_rows, ours_fields = schemas["ours"]
546
+ theirs_rows, theirs_fields = schemas["theirs"]
547
+ by_row = {row: key for key, row in ours_rows.items()}
548
+ by_column = {info[0]: field for field, info in ours_fields.items()}
549
+ for error in metadata["ours"]["errors"]:
550
+ if error["sheet"] != name:
551
+ continue
552
+ own = books["ours"][name][error["coordinate"]]
553
+ key, field = by_row.get(own.row), by_column.get(own.column)
554
+ if key not in theirs_rows or field not in theirs_fields or ours_fields[field][1] != theirs_fields[field][1]:
555
+ continue
556
+ cells = {"ours": own, "theirs": books["theirs"][name].cell(theirs_rows[key], theirs_fields[field][0])}
557
+ if not all(cell.data_type == "e" for cell in cells.values()):
558
+ continue
559
+ kind, value = ours_fields[field][1:]
560
+ for side, cell in cells.items():
561
+ issue = errors[side][(name, cell.coordinate)]
562
+ replacements[side].append({**issue, "field": field, "recordId": key[1], "type": kind, "value": value})
563
+ _set_literal(cell, value)
564
+ for side, repairs in replacements.items():
565
+ if not repairs:
566
+ continue
567
+ output = analysis_dir / f"{side}.review.values{paths[side].suffix}"
568
+ books[side].save(output)
569
+ paths[side] = output
570
+ removed = {(repair["sheet"], repair["coordinate"]) for repair in repairs}
571
+ metadata[side].update(valuePath=str(output), valueSha256=_sha256_path(output), replacements=repairs,
572
+ errors=[error for error in metadata[side]["errors"] if (error["sheet"], error["coordinate"]) not in removed])
573
+ finally:
574
+ for book in books.values():
575
+ book.close()
576
+
577
+
392
578
  def _cell_token(cell, cached_cell=None) -> tuple[Any, str] | None:
393
579
  if cell is None or isinstance(cell, MergedCell):
394
580
  return None
@@ -702,7 +888,10 @@ def _structural_sheet_diff(report_sheet, wb_base, wb_ours, wb_theirs,
702
888
  ours_token = _cell_token(ours_cell, ours_cached)
703
889
  theirs_token = _cell_token(theirs_cell, theirs_cached)
704
890
  has_base = row.get("baseRow") is not None and column.get("baseCol") is not None
705
- changed = not (ours_token == theirs_token == base_token)
891
+ error_sides = {side: cell.value for side, cell in
892
+ (("base", base_cell), ("ours", ours_cell), ("theirs", theirs_cell))
893
+ if cell is not None and cell.data_type == "e"}
894
+ changed = bool(error_sides) or not (ours_token == theirs_token == base_token)
706
895
  structural = row["state"] != "common" or column["state"] != "common"
707
896
  selectable = (
708
897
  row["state"] in ("common", "delete_modify")
@@ -712,6 +901,8 @@ def _structural_sheet_diff(report_sheet, wb_base, wb_ours, wb_theirs,
712
901
  changed_row_ids.add(row["id"])
713
902
  resolution = _cell_resolution(base_cell, ours_cell, theirs_cell, has_base=has_base,
714
903
  base_cached=base_cached, ours_cached=ours_cached, theirs_cached=theirs_cached)
904
+ if error_sides:
905
+ resolution = "conflict"
715
906
  if changed and resolution != "same":
716
907
  row_attention.add(row["id"])
717
908
  stable_id = f'{row["id"]}|{column["id"]}'
@@ -735,6 +926,8 @@ def _structural_sheet_diff(report_sheet, wb_base, wb_ours, wb_theirs,
735
926
  "changed": changed,
736
927
  "structural": structural,
737
928
  "selectable": selectable,
929
+ "requiresChoice": bool(error_sides),
930
+ "errorSides": error_sides,
738
931
  })
739
932
 
740
933
  # 只显示需要关注的行:结构变化行 + 含非 same(需决策/有变化信息)cell 的行
@@ -797,11 +990,84 @@ def _structural_sheet_diff(report_sheet, wb_base, wb_ours, wb_theirs,
797
990
  "rawChangedCellCount": sum(cell["changed"] for cell in cells),
798
991
  "conflictCount": len(selectable_cells),
799
992
  "structuralConflictCount": structural_conflicts,
800
- "needsAttention": bool(selectable_cells) or structural_conflicts > 0
993
+ "needsAttention": decision_cell_count > 0 or structural_conflicts > 0
801
994
  or report_sheet.get("renameStatus") == "rename_conflict",
802
995
  }
803
996
 
804
997
 
998
+ def _require_error_review(sheet: dict[str, Any], snapshots: dict[str, Any]) -> None:
999
+ """Unknown values may never justify alignment or automatic resolution."""
1000
+ names = sheet.get("names") or {side: sheet["name"] for side in ("base", "ours", "theirs")}
1001
+ relevant = [{**error, "side": side} for side, meta in snapshots.items()
1002
+ for error in meta.get("errors", []) if error["sheet"] == names.get(side)]
1003
+ repairs = [{**repair, "side": side} for side, meta in snapshots.items()
1004
+ for repair in meta.get("replacements", []) if repair["sheet"] == names.get(side)]
1005
+ if repairs:
1006
+ sheet.update(replacements=repairs, needsAttention=True, rebuildRequired=True)
1007
+ lookup = {(repair["side"], repair["coordinate"]): repair for repair in repairs}
1008
+ rows = {row["id"]: row for row in sheet.get("allRows", [])}
1009
+ columns = {column["id"]: column for column in sheet.get("columns", [])}
1010
+ corrected_rows, excluded = set(), set()
1011
+ for cell in sheet.get("allCells", []):
1012
+ row, column = rows[cell["rowId"]], columns[cell["colId"]]
1013
+ pair = {}
1014
+ for side in ("ours", "theirs"):
1015
+ if row.get(f"{side}Row") is not None and column.get(f"{side}Col") is not None:
1016
+ coordinate = f'{get_column_letter(column[f"{side}Col"])}{row[f"{side}Row"]}'
1017
+ if (side, coordinate) in lookup:
1018
+ pair[side] = lookup[(side, coordinate)]
1019
+ if len(pair) != 2 or pair["ours"]["recordId"] != pair["theirs"]["recordId"] or pair["ours"]["field"] != pair["theirs"]["field"]:
1020
+ continue
1021
+ cell.update(replacement=pair, requiresChoice=False, selectable=False, resolution="replacement", changed=True)
1022
+ corrected_rows.add(row["id"])
1023
+ if row.get("baseRow") is not None and column.get("baseCol") is not None:
1024
+ excluded.add(("base", f'{get_column_letter(column["baseCol"])}{row["baseRow"]}'))
1025
+ relevant = [error for error in relevant if (error["side"], error["coordinate"]) not in excluded]
1026
+ visible = {row["id"] for row in sheet.get("rows", [])} | corrected_rows
1027
+ sheet["rows"] = [row for row in sheet.get("allRows", []) if row["id"] in visible]
1028
+ sheet["gridCells"] = [cell for cell in sheet.get("allCells", []) if cell["rowId"] in visible]
1029
+ sheet["cells"] = [cell for cell in sheet["gridCells"] if cell["changed"]]
1030
+ sheet["changedCount"] = sheet["decisionCellCount"] = sum(cell["selectable"] for cell in sheet["cells"])
1031
+ sheet["conflictCount"] = sum(cell["resolution"] == "conflict" for cell in sheet["cells"])
1032
+ if not relevant:
1033
+ return
1034
+ sheet["calculationErrors"] = relevant
1035
+ sheet["needsAttention"] = True
1036
+ if sheet["action"] == "merge":
1037
+ represented = sum(len(cell.get("errorSides", {})) for cell in sheet.get("allCells", []) if cell.get("requiresChoice"))
1038
+ structural = any(axis["state"] != "common"
1039
+ for axis in [*sheet.get("allRows", []), *sheet.get("columns", [])])
1040
+ id_columns = [column for column in sheet.get("columns", []) if column["id"].casefold() == "id"]
1041
+ identity_cells = [cell for cell in sheet.get("allCells", [])
1042
+ if id_columns and cell["colId"] == id_columns[0]["id"]]
1043
+ uncertain_rows = {cell["rowId"] for cell in sheet.get("allCells", []) if cell.get("requiresChoice")}
1044
+ reliable = bool(id_columns) and all(
1045
+ any(cell["rowId"] == row_id and not cell.get("requiresChoice")
1046
+ and cell["base"] is not None and cell["base"] == cell["ours"] == cell["theirs"]
1047
+ and all(sum(other[side] == cell[side] for other in identity_cells) == 1
1048
+ for side in ("base", "ours", "theirs")) for cell in identity_cells)
1049
+ for row_id in uncertain_rows
1050
+ )
1051
+ if not structural and represented == len(relevant) and reliable:
1052
+ by_coordinate = {(error["side"], error["coordinate"]): error for error in relevant}
1053
+ rows = {row["id"]: row for row in sheet["allRows"]}
1054
+ columns = {column["id"]: column for column in sheet["columns"]}
1055
+ for cell in sheet["allCells"]:
1056
+ if cell.get("requiresChoice"):
1057
+ cell["calculationErrors"] = {}
1058
+ for side in cell["errorSides"]:
1059
+ coordinate = f'{get_column_letter(columns[cell["colId"]][f"{side}Col"])}{rows[cell["rowId"]][f"{side}Row"]}'
1060
+ cell["calculationErrors"][side] = by_coordinate[(side, coordinate)]
1061
+ return
1062
+ # Errors in headers, unmatched/deleted rows, or changing axes undermine
1063
+ # structural evidence. Require a whole-sheet choice instead of guessing
1064
+ # row/column correspondence or interpreting an unknown as "unchanged".
1065
+ sheet.update(action="conflict_calculation_errors", requiresChoice=True,
1066
+ cells=[], gridCells=[], allCells=[], rows=[], allRows=[], columns=[],
1067
+ headerRows=[], changedCount=0, conflictCount=0,
1068
+ structuralConflictCount=1, renameStatus="unchanged", mergedCells=None)
1069
+
1070
+
805
1071
  def diff_workbooks(
806
1072
  base_path: Path | str | None,
807
1073
  ours_path: Path | str,
@@ -814,7 +1080,8 @@ def diff_workbooks(
814
1080
  snapshot_paths, value_snapshots = _snapshot_workbooks(
815
1081
  base_path, ours_path, theirs_path, structural_dir,
816
1082
  )
817
- # These workbooks are complete, calculated value snapshots. Keeping the
1083
+ # These workbooks are complete, calculated snapshots with typed errors
1084
+ # represented as unknowns requiring review. Keeping the
818
1085
  # three sides separate is important for cross-sheet formulas: each side is
819
1086
  # calculated against its own original workbook before alignment/merge.
820
1087
  wb_base = load_workbook(snapshot_paths["base"], data_only=False, keep_links=True) if snapshot_paths["base"] else None
@@ -822,13 +1089,17 @@ def diff_workbooks(
822
1089
  wb_theirs = load_workbook(snapshot_paths["theirs"], data_only=False, keep_links=True)
823
1090
  wb_base_v = wb_ours_v = wb_theirs_v = None
824
1091
  try:
1092
+ if any(meta.get("errors") or meta.get("replacements") for meta in value_snapshots.values()):
1093
+ skip_hidden_sheets = False
825
1094
  if base_path is not None:
826
1095
  structural = analyze_structural_workbooks(
827
1096
  snapshot_paths["base"], snapshot_paths["ours"], snapshot_paths["theirs"], structural_dir,
828
1097
  write_sidecars=False, skip_hidden_sheets=skip_hidden_sheets,
1098
+ progress=lambda **p: checkpoint(phase='对齐 Sheet / 行 / 列', **p),
829
1099
  )
830
1100
  sheets = []
831
- for report_sheet in structural["sheets"]:
1101
+ for index, report_sheet in enumerate(structural["sheets"]):
1102
+ checkpoint(phase='生成审阅数据', sheet=report_sheet['name'], sheetDone=index, sheetTotal=len(structural['sheets']))
832
1103
  if report_sheet["action"] == "merge":
833
1104
  sheets.append(_structural_sheet_diff(
834
1105
  report_sheet, wb_base, wb_ours, wb_theirs,
@@ -866,6 +1137,8 @@ def diff_workbooks(
866
1137
  "structuralConflictCount": int(action.startswith("conflict_")),
867
1138
  "needsAttention": action.startswith("conflict_"),
868
1139
  })
1140
+ for sheet in sheets:
1141
+ _require_error_review(sheet, value_snapshots)
869
1142
  return {
870
1143
  "engineVersion": structural["version"],
871
1144
  "valueSnapshots": value_snapshots,
@@ -875,21 +1148,23 @@ def diff_workbooks(
875
1148
  "changedCellCount": sum(sheet["changedCount"] for sheet in sheets),
876
1149
  "cellConflictCount": sum(sheet["conflictCount"] for sheet in sheets),
877
1150
  "structuralConflictCount": sum(sheet.get("structuralConflictCount", 0) for sheet in sheets),
878
- "sheetConflictCount": structural["summary"].get("sheetConflictCount", 0),
1151
+ "sheetConflictCount": sum(sheet["action"].startswith("conflict_") for sheet in sheets),
879
1152
  },
880
1153
  }
881
1154
 
882
1155
  sheets: list[dict[str, Any]] = []
883
- for name in _ordered_sheet_names(wb_base, wb_ours, wb_theirs):
1156
+ ordered_names = _ordered_sheet_names(wb_base, wb_ours, wb_theirs)
1157
+ for index, name in enumerate(ordered_names):
1158
+ checkpoint(phase='生成审阅数据', sheet=name, sheetDone=index, sheetTotal=len(ordered_names))
884
1159
  base_exists = wb_base is not None and name in wb_base.sheetnames
885
1160
  ours_exists = name in wb_ours.sheetnames
886
1161
  theirs_exists = name in wb_theirs.sheetnames
887
1162
  ws_base = wb_base[name] if base_exists else None
888
1163
  ws_ours = wb_ours[name] if ours_exists else None
889
1164
  ws_theirs = wb_theirs[name] if theirs_exists else None
890
- ws_base_v = wb_base_v[name] if base_exists else None
891
- ws_ours_v = wb_ours_v[name] if ours_exists else None
892
- ws_theirs_v = wb_theirs_v[name] if theirs_exists else None
1165
+ ws_base_v = wb_base_v[name] if base_exists and wb_base_v is not None else None
1166
+ ws_ours_v = wb_ours_v[name] if ours_exists and wb_ours_v is not None else None
1167
+ ws_theirs_v = wb_theirs_v[name] if theirs_exists and wb_theirs_v is not None else None
893
1168
 
894
1169
  if ours_exists and theirs_exists:
895
1170
  sheet = _modified_sheet_diff(name, ws_base, ws_ours, ws_theirs,
@@ -939,6 +1214,8 @@ def diff_workbooks(
939
1214
  "conflictCount": conflict_count,
940
1215
  })
941
1216
 
1217
+ for sheet in sheets:
1218
+ _require_error_review(sheet, value_snapshots)
942
1219
  return {
943
1220
  "valueSnapshots": value_snapshots,
944
1221
  "sheets": sheets,
@@ -1030,7 +1307,8 @@ def prepare_conflicts(
1030
1307
  auto_filters = load_auto_theirs_filters(repo_root)
1031
1308
  prepared_files = []
1032
1309
  auto_entries: list[dict[str, Any]] = []
1033
- for item in conflicts:
1310
+ for index, item in enumerate(conflicts):
1311
+ checkpoint(file=item['path'], fileDone=index, fileTotal=len(conflicts), phase='提取三方版本', sheet='', sheetDone=0, sheetTotal=0, side='')
1034
1312
  path = item["path"]
1035
1313
  if auto_theirs_path(path, auto_filters):
1036
1314
  if 3 not in item["stages"]:
@@ -1106,6 +1384,7 @@ def prepare_conflicts(
1106
1384
  "autoTheirsCount": len(auto_entries),
1107
1385
  },
1108
1386
  }
1387
+ checkpoint(phase='完成解析', fileDone=len(conflicts), sheet='', sheetDone=0, sheetTotal=0)
1109
1388
  manifest_path = target_dir / "manifest.json"
1110
1389
  manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
1111
1390
  return manifest_path
@@ -1216,8 +1495,19 @@ def _validate_decisions(manifest: dict[str, Any], decisions: dict[str, Any]) ->
1216
1495
  sheet_choices = file_choice.get("sheets") or {}
1217
1496
  for sheet in file_entry["diff"]["sheets"]:
1218
1497
  choice = sheet_choices.get(sheet["name"]) or {}
1498
+ if choice.get('sheet') in ('ours', 'theirs'):
1499
+ if sheet['action'] != 'merge' and not sheet['action'].startswith('conflict_'):
1500
+ raise ConflictError('自动处理 Sheet 不支持额外整表覆盖。')
1501
+ _selected_repairs(sheet, choice)
1502
+ continue
1219
1503
  if sheet["action"].startswith("conflict_") and choice.get("sheet") not in ("ours", "theirs"):
1220
1504
  missing.append(f"{file_entry['path']} / {sheet['name']} / <sheet>")
1505
+ if sheet["action"].startswith("conflict_"):
1506
+ selected_errors = [error for error in sheet.get("calculationErrors", [])
1507
+ if error["side"] == choice.get("sheet")]
1508
+ if selected_errors:
1509
+ error = selected_errors[0]
1510
+ raise ConflictError(f"Selected {error['side']} source has an Excel error at {file_entry['path']} / {error['sheet']}!{error['coordinate']}: {error['error']}")
1221
1511
  if sheet.get("renameStatus") == "rename_conflict" and choice.get("rename") not in ("ours", "theirs"):
1222
1512
  missing.append(f"{file_entry['path']} / {sheet['name']} / <rename>")
1223
1513
  if (sheet.get("mergedCells") or {}).get("status") == "conflict" and choice.get("mergedCells") not in ("ours", "theirs"):
@@ -1232,7 +1522,10 @@ def _validate_decisions(manifest: dict[str, Any], decisions: dict[str, Any]) ->
1232
1522
  missing.append(f"{file_entry['path']} / {sheet['name']} / {column['id']}")
1233
1523
  cell_choices = choice.get("cells") or {}
1234
1524
  for cell in sheet["cells"]:
1235
- if cell["resolution"] == "conflict" and _cell_choice(cell_choices, cell) not in ("ours", "theirs"):
1525
+ side = _cell_choice(cell_choices, cell)
1526
+ if side in cell.get("errorSides", {}):
1527
+ raise ConflictError(f"Selected {side} source has an Excel error at {file_entry['path']} / {sheet['name']} / {cell['coordinate']}: {cell['errorSides'][side]}")
1528
+ if cell["resolution"] == "conflict" and side not in ("ours", "theirs"):
1236
1529
  missing.append(f"{file_entry['path']} / {sheet['name']} / {cell['coordinate']}")
1237
1530
  if missing:
1238
1531
  preview = "\n".join(f"- {item}" for item in missing[:20])
@@ -1563,7 +1856,7 @@ def _build_merged_file(file_entry: dict[str, Any], decisions: dict[str, Any]) ->
1563
1856
  expected = meta.get("valueSha256")
1564
1857
  if expected and _sha256_path(value_path) != expected:
1565
1858
  raise ConflictError(f"Immutable {side} value snapshot changed for {file_entry['path']}; refusing apply.")
1566
- _validate_value_workbook(value_path)
1859
+ _validate_value_workbook(value_path, allow_errors=True)
1567
1860
  value_paths[side] = value_path
1568
1861
  fd, temp_name = tempfile.mkstemp(prefix=f".{output.stem}-", suffix=extension, dir=output.parent)
1569
1862
  os.close(fd)
@@ -1586,9 +1879,10 @@ def _build_merged_file(file_entry: dict[str, Any], decisions: dict[str, Any]) ->
1586
1879
  name = sheet["name"]
1587
1880
  action = sheet["action"]
1588
1881
  selection = sheet_choices.get(name) or {}
1882
+ whole_source = selection.get('sheet') in ('ours', 'theirs')
1589
1883
  original_name = (sheet.get("names") or {}).get("ours") or name
1590
1884
  is_affected = (
1591
- action.startswith("conflict_")
1885
+ whole_source or action.startswith("conflict_")
1592
1886
  or action in ("auto_add_ours", "auto_add_theirs")
1593
1887
  or (
1594
1888
  action == "merge"
@@ -1601,7 +1895,9 @@ def _build_merged_file(file_entry: dict[str, Any], decisions: dict[str, Any]) ->
1601
1895
  )
1602
1896
  if is_affected:
1603
1897
  affected_sheet_names.add(original_name)
1604
- if action == "merge":
1898
+ if whole_source:
1899
+ affected_output_sheet_names.add((sheet.get('names') or {}).get(selection['sheet']) or name)
1900
+ elif action == "merge":
1605
1901
  affected_output_sheet_names.add(_selected_sheet_name(sheet, selection))
1606
1902
  elif action.startswith("conflict_"):
1607
1903
  affected_output_sheet_names.add((sheet.get("names") or {}).get(selection.get("sheet")) or name)
@@ -1631,13 +1927,20 @@ def _build_merged_file(file_entry: dict[str, Any], decisions: dict[str, Any]) ->
1631
1927
  index=min(wb_ours.sheetnames.index(ours_name), len(wb_out.sheetnames)),
1632
1928
  )
1633
1929
  continue
1634
- if action.startswith("conflict_"):
1930
+ if whole_source or action.startswith("conflict_"):
1635
1931
  side = selection["sheet"]
1636
1932
  if side == "ours":
1637
1933
  source_wb = wb_ours
1638
1934
  else:
1639
1935
  source_wb = wb_theirs
1640
1936
  source_name = (sheet.get("names") or {}).get(side) or name
1937
+ if source_name in source_wb.sheetnames:
1938
+ from formula_values import _set_literal
1939
+ for coordinate, value in _selected_repairs(sheet, selection).items():
1940
+ _set_literal(source_wb[source_name][coordinate], value)
1941
+ ours_name = (sheet.get("names") or {}).get("ours") or name
1942
+ if ours_name != source_name and ours_name in wb_out.sheetnames:
1943
+ wb_out.remove(wb_out[ours_name])
1641
1944
  if source_name in source_wb.sheetnames:
1642
1945
  _replace_sheet(wb_out, source_wb[source_name], source_wb.sheetnames)
1643
1946
  elif name in wb_out.sheetnames:
@@ -1727,6 +2030,8 @@ def _build_merged_file(file_entry: dict[str, Any], decisions: dict[str, Any]) ->
1727
2030
  raise ConflictError(
1728
2031
  f"Affected Sheet {ws.title} retained formula at {cell.coordinate}; output was not written."
1729
2032
  )
2033
+ if cell.data_type == "e":
2034
+ raise ConflictError(f"Selected source contains an Excel error at {ws.title}!{cell.coordinate}; output was not written.")
1730
2035
  finally:
1731
2036
  check_wb.close()
1732
2037
  if keep_vba:
@@ -1785,7 +2090,25 @@ def _build_commit_message(manifest: dict[str, Any], decisions: dict[str, Any]) -
1785
2090
  sheet_choices = file_choice.get("sheets") or {}
1786
2091
  for sheet in file_entry["diff"]["sheets"]:
1787
2092
  choice = sheet_choices.get(sheet["name"]) or {}
2093
+ if choice.get('sheet') in ('ours', 'theirs'):
2094
+ lines.append(f"resolve(sheet): [表:{file_entry['path']}]-[sheet:{sheet['name']}]-[选择:{choice['sheet']} 全量]")
2095
+ for coordinate, value in _selected_repairs(sheet, choice).items():
2096
+ lines.append(f"resolve(manual): [表:{file_entry['path']}]-[sheet:{sheet['name']}]-[来源:{choice['sheet']}]-[单元格:{coordinate}]-[值:{json.dumps(value, ensure_ascii=False)}]")
2097
+ recorded = set()
2098
+ for repair in sheet.get("replacements", []):
2099
+ if sheet["action"].startswith("conflict_") and repair["side"] != choice.get("sheet"):
2100
+ continue
2101
+ key = (repair["side"], repair["coordinate"]) if repair.get("manual") else (repair["recordId"], repair["field"])
2102
+ if key in recorded:
2103
+ continue
2104
+ recorded.add(key)
2105
+ if repair.get("manual"):
2106
+ lines.append(f"resolve(manual): [表:{file_entry['path']}]-[sheet:{sheet['name']}]-[来源:{repair['side']}]-[单元格:{repair['coordinate']}]-[字段:{repair['field']}]-[类型:{repair['type']}]-[值:{json.dumps(repair['value'], ensure_ascii=False)}]")
2107
+ else:
2108
+ lines.append(f"resolve(default): [表:{file_entry['path']}]-[sheet:{sheet['name']}]-[id:{repair['recordId']}]-[字段:{repair['field']}]-[类型:{repair['type']}]-[值:{json.dumps(repair['value'], ensure_ascii=False)}]")
1788
2109
  cell_choices = choice.get("cells") or {}
2110
+ if choice.get('sheet') in ('ours', 'theirs'):
2111
+ continue
1789
2112
  for cell in sheet["cells"]:
1790
2113
  if cell.get("resolution") != "conflict":
1791
2114
  continue
@@ -1856,7 +2179,7 @@ def _validate_manifest_sources(manifest: dict[str, Any], repo: Path) -> None:
1856
2179
  snapshot = Path(value_path).resolve()
1857
2180
  if not snapshot.exists() or _sha256_path(snapshot) != expected_value:
1858
2181
  raise ConflictError(f"Immutable value snapshot changed for {relative} ({side}); refusing apply.")
1859
- _validate_value_workbook(snapshot)
2182
+ _validate_value_workbook(snapshot, allow_errors=True)
1860
2183
  output = (repo / Path(relative)).resolve()
1861
2184
  expected_output = entry.get("outputSha256")
1862
2185
  if expected_output is None: