feat: structure des classeurs Excel editable depuis la visionneuse #153

A14 : service mutate_xlsx_structure (batch ordonné d'actions
sheet_add/sheet_rename/sheet_delete/sheet_duplicate et
row/col_insert/delete, une seule réécriture verrouillée et atomique,
409 lossy sans force, backup, dernier sheet protégé) ; endpoint
PUT /api/file/{vault}/xlsx/structure (1-50 actions/requête) ;
menu « structure » dans la visionneuse : ajout/renommage/duplication/
suppression de feuilles et insertion/suppression de ligne/colonne à
partir de la cellule active, confirmations explicites pour les
destructions, re-rendu serveur après succès, reprise force après
confirmation 409.

Vérifié : test_xlsx_structure.py 11 (ops, gardes, atomicité du batch,
409 lossy + force) + contre-preuve (garde dernier sheet neutralisée ->
1 échec), xlsx-viewer.test.mjs 33/33 (3 nouveaux), ruff 0, mypy 0,
i18n parity, validate-imports.

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <[email protected]>

backend/routers/files_write.py

@@ -64,6 +64,9 @@ from backend.services.mutations import (
 from backend.services.mutations import (
     move_path as service_move_path,
 )
+from backend.services.mutations import (
+    mutate_xlsx_structure as service_mutate_xlsx_structure,
+)
 from backend.services.mutations import (
     rename_directory as service_rename_directory,
 )
@@ -174,6 +177,61 @@ def api_file_xlsx_save(
     return {"status": "ok", "vault": result["vault"], "path": result["path"], "size": result["size"]}
 
 
+@router.put("/api/file/{vault_name}/xlsx/structure", response_model=FileSaveResponse)
+def api_file_xlsx_structure(
+    vault_name: str,
+    path: str = Query(..., description="Relative path to the .xlsx file"),
+    body: dict = Body(
+        ...,
+        description=(
+            '{"actions": [{"op": "sheet_add", "name": "X"}, '
+            '{"op": "row_insert", "sheet": "X", "at": 2, "count": 1}], '
+            '"force": false}'
+        ),
+    ),
+    current_user=Depends(require_auth),
+):
+    """Apply structural changes to an .xlsx workbook (#153 A14).
+
+    ``actions`` is an ordered list applied in one locked, atomic rewrite:
+    ``sheet_add`` (``name``, optional ``at`` 0-based), ``sheet_rename``
+    (``from``/``to``), ``sheet_delete`` (refused on the last sheet),
+    ``sheet_duplicate`` (``name``/``as``) and ``row_insert``/``row_delete``/
+    ``col_insert``/``col_delete`` (``sheet``, 1-based ``at``, ``count``).
+
+    Without ``force`` the call fails **409** ``xlsx_lossy_content`` when the
+    workbook carries features openpyxl cannot rewrite (same gate as the cell
+    edits). A backup is created before the archive is replaced.
+
+    Args:
+        vault_name: Name of the vault.
+        path: Relative path to the ``.xlsx`` file.
+        body: JSON body with ``actions`` (1 to 50) and optional ``force``.
+
+    Returns:
+        ``FileSaveResponse`` confirming the write.
+    """
+    if not check_vault_access(vault_name, current_user):
+        raise HTTPException(status_code=403, detail=f"Accès refusé à la vault '{vault_name}'")
+
+    actions = body.get("actions")
+    if not isinstance(actions, list) or not actions or len(actions) > 50:
+        raise HTTPException(status_code=400, detail="Actions invalides (1 à 50 par requête)")
+    raw_force = body.get("force", False)
+    if not isinstance(raw_force, bool):
+        raise HTTPException(status_code=400, detail="Flag invalide: force")
+
+    result = service_mutate_xlsx_structure(
+        vault_name, path, actions, force=raw_force
+    )
+    log_file_save(
+        current_user["username"], vault_name, path,
+        len(actions),
+        current_user.get("_request_ip", "unknown"),
+    )
+    return {"status": "ok", "vault": result["vault"], "path": result["path"], "size": len(result["applied"])}
+
+
 @router.delete("/api/file/{vault_name}", response_model=FileDeleteResponse)
 async def api_file_delete(vault_name: str, path: str = Query(..., description="Relative path to file"), current_user=Depends(require_auth)):
     """Delete a file from the vault.

backend/services/mutations.py

@@ -455,6 +455,193 @@ def edit_xlsx_cells(
     }
 
 
+def mutate_xlsx_structure(
+    vault_name: str,
+    path: str,
+    actions: list[dict[str, Any]],
+    *,
+    backup: bool = True,
+    force: bool = False,
+) -> dict[str, Any]:
+    """Apply structural changes to an ``.xlsx`` workbook (#153 A14).
+
+    ``actions`` is an ordered list — the workbook is loaded once and every
+    action is applied in sequence inside the same per-file lock and the same
+    atomic replace, so a half-applied batch can never reach the disk:
+
+    * ``{"op": "sheet_add", "name": "X", "at": 1}`` — new sheet (at =
+      optional 0-based position);
+    * ``{"op": "sheet_rename", "from": "X", "to": "Y"}``;
+    * ``{"op": "sheet_delete", "name": "X"}`` — refused when it is the
+      last sheet (an openpyxl workbook must keep one);
+    * ``{"op": "sheet_duplicate", "name": "X", "as": "Y"}`` — values,
+      styles and merged ranges are copied (not the data-dependent objects);
+    * ``{"op": "row_insert"|"row_delete"|"col_insert"|"col_delete",
+      "sheet": "X", "at": N, "count": k}`` — 1-based position, default 1.
+
+    All of it rides the same guards as the cell edits (P0): per-file lock,
+    ``.tmp`` + ``os.replace`` atomic write and the ``force`` gate on lossy
+    round-trips. The UI proposes these actions with an explicit confirmation
+    — deletions are NOT recoverable from the viewer (only via the ``.bak``).
+    """
+    root = get_vault_root(vault_name)
+    _ensure_writable(root)
+    file_path = resolve_safe_path(root, path)
+
+    if not file_path.exists() or not file_path.is_file():
+        raise ServiceError(
+            f"File not found: {path}",
+            code="not_found",
+            status=404,
+            details={"vault": vault_name, "path": path},
+        )
+
+    if not actions or len(actions) > 50:
+        raise ServiceError(
+            "Invalid actions (1 to 50 per request)", code="invalid", status=400
+        )
+
+    if not force:
+        from backend.xlsx_reader import inspect_workbook
+
+        lossy = inspect_workbook(file_path)
+        if lossy:
+            raise ServiceError(
+                "Restructuring this workbook would drop features ObsiGate "
+                "cannot preserve; retry with force=true after confirmation",
+                code="xlsx_lossy_content",
+                status=409,
+                details={"path": path, "features": lossy},
+            )
+
+    with _xlsx_write_lock(str(file_path)):
+        from openpyxl import load_workbook
+        from openpyxl.worksheet.copier import WorksheetCopy
+
+        try:
+            wb = load_workbook(file_path)
+        except Exception as exc:
+            raise ServiceError(
+                f"Cannot open workbook: {exc}", code="invalid", status=400
+            ) from exc
+
+        rel_path = _rel(root, file_path)
+        applied: list[str] = []
+        try:
+            for i, action in enumerate(actions):
+                op = action.get("op")
+                try:
+                    if op == "sheet_add":
+                        name = str(action.get("name", "")).strip()
+                        if not name or name in wb.sheetnames:
+                            raise ServiceError(
+                                f"Nom de feuille invalide ou déjà pris: {name!r}",
+                                code="invalid", status=400,
+                            )
+                        ws = wb.create_sheet(name[:31])
+                        at = action.get("at")
+                        # create_sheet appends at the end: shift left by the
+                        # distance between the last index and the target.
+                        if isinstance(at, int) and 0 <= at < len(wb.sheetnames):
+                            wb.move_sheet(ws, offset=at - (len(wb.sheetnames) - 1))
+                        applied.append(f"sheet_add:{ws.title}")
+                    elif op == "sheet_rename":
+                        src, dst = str(action.get("from", "")), str(action.get("to", "")).strip()
+                        if src not in wb.sheetnames or not dst or dst in wb.sheetnames:
+                            raise ServiceError(
+                                f"Renommage invalide: {src!r} -> {dst!r}",
+                                code="invalid", status=400,
+                            )
+                        wb[src].title = dst[:31]
+                        applied.append(f"sheet_rename:{src}->{dst}")
+                    elif op == "sheet_delete":
+                        name = str(action.get("name", ""))
+                        if name not in wb.sheetnames:
+                            raise ServiceError(
+                                f"Feuille introuvable: {name}", code="invalid", status=400
+                            )
+                        if len(wb.sheetnames) <= 1:
+                            raise ServiceError(
+                                "Impossible de supprimer la dernière feuille",
+                                code="invalid", status=400,
+                            )
+                        del wb[name]
+                        applied.append(f"sheet_delete:{name}")
+                    elif op == "sheet_duplicate":
+                        name = str(action.get("name", ""))
+                        new_name = str(action.get("as", "")).strip()
+                        if name not in wb.sheetnames or not new_name or new_name in wb.sheetnames:
+                            raise ServiceError(
+                                f"Duplication invalide: {name!r} -> {new_name!r}",
+                                code="invalid", status=400,
+                            )
+                        # WorksheetCopy is the documented dup path (openpyxl
+                        # 3.1); it copies values, styles and merges — not
+                        # charts/images, which openpyxl itself cannot clone.
+                        copy = wb.create_sheet(new_name[:31])
+                        WorksheetCopy(wb[name], copy).copy_worksheet()
+                        applied.append(f"sheet_duplicate:{name}->{copy.title}")
+                    elif op in ("row_insert", "row_delete", "col_insert", "col_delete"):
+                        sheet = str(action.get("sheet", ""))
+                        if sheet not in wb.sheetnames:
+                            raise ServiceError(
+                                f"Feuille introuvable: {sheet}", code="invalid", status=400
+                            )
+                        ws = wb[sheet]
+                        at = action.get("at", 1)
+                        count = action.get("count", 1)
+                        if not isinstance(at, int) or at < 1 or not isinstance(count, int) or count < 1:
+                            raise ServiceError(
+                                "Position 'at' / 'count' invalides", code="invalid", status=400
+                            )
+                        if op == "row_insert":
+                            ws.insert_rows(at, count)
+                        elif op == "row_delete":
+                            ws.delete_rows(at, count)
+                        elif op == "col_insert":
+                            ws.insert_cols(at, count)
+                        else:
+                            ws.delete_cols(at, count)
+                        applied.append(f"{op}:{sheet}@{at}x{count}")
+                    else:
+                        raise ServiceError(
+                            f"Action inconnue: {op!r}", code="invalid", status=400
+                        )
+                except ServiceError:
+                    raise
+                except Exception as exc:
+                    raise ServiceError(
+                        f"Action {i + 1} ({op}) a échoué: {exc}",
+                        code="invalid", status=400,
+                    ) from exc
+        except ServiceError:
+            wb.close()
+            raise
+
+        if backup:
+            create_backup(file_path, vault_name, rel_path)
+
+        tmp_path = file_path.with_name(f"{file_path.name}.{os.getpid()}.tmp")
+        try:
+            wb.save(tmp_path)
+            os.replace(tmp_path, file_path)
+        except Exception:
+            tmp_path.unlink(missing_ok=True)
+            wb.close()
+            raise
+        wb.close()
+
+    logger.info(
+        f"XLSX structure: {vault_name}/{rel_path} {applied}"
+    )
+    return {
+        "success": True,
+        "vault": vault_name,
+        "path": rel_path,
+        "applied": applied,
+    }
+
+
 def append_to_file(
     vault_name: str,
     path: str,