A2-3: Сохранение слепка документа (JSONB) по схеме + версионность

В рамках задачи провели работу с версиями, управлением ими, интерфейсом.
- Каждый раз при сохранении формы создается новая версия документа.
- Вновь созданная версия документа автоматически помечается как текущая.
- Изменения через редактор JSON в окне версий сохраняются В ТЕКУЩУЮ версию
- При открытии формы она заполняется данными из ТЕКУЩЕЙ версии
- В интерфейсе окна версий есть возможность переключиться на любую сохраненную версию для ее изменения или заполнения формы на ее основе.
- Храним 20 версий, при создании новой версии при достижении этого предела, самая старая версия автоматически удаляется
- В интерфейсе окна версий есть возможность "защитить" любую версию от автоматического удаления.
- Версия в статусе final считается защищенной и является неизменяемой! Ее нельзя откорректировать через редактирование JSON в окне версий.
- При отдаче версии клиенту проводится ее серверная валидация.
  В дополнительные данные json РЯДОМ с payload отдается информация о результате валидации,
  включая количество ошибок и описание ошибок
- Версия не имеющая ошибок при сохранении помечается флагом clean, в противном случае помечается флагом draft.
- В финальную версию можно перевести только версию с флагом clean.
- Краткая справка по статусам версий, их хранении и отображению в интерфейсе приведена в подсказке в окне версий на клиенте.
- Проработан интерфейс окна версий.

Author: knoff

app/api/routes/document_versions.py

@@ -3,7 +3,10 @@
 from pydantic import BaseModel
 from sqlalchemy.orm import Session
 from app.db import get_db
-from app.models_sqlalchemy import DocumentRow, DocumentVersionRow
+from app.models_sqlalchemy import DocumentRow, DocumentVersionRow, Schema  # Schema есть в models_sqlalchemy
+from app.services.validate_model import validate_model  # серверная валидация по internal-model
+from app.services import xsd_internal  # build_internal_model(content)
+from app.storage import load_file_minio  # чтение XSD из MinIO
 
 router = APIRouter(prefix="/documents", tags=["documents"])
 
@@ -18,19 +21,89 @@ class VersionOut(BaseModel):
     document_id: int
     payload: dict
     created_at: datetime | None = None
+    # new fields for UI clarity
+    status: str | None = None          # 'draft' | 'clean' | 'final'
+    is_protected: bool | None = None
+    is_selected: bool | None = None
+    validation: dict | None = None     # {"source":"server","checked_at":ISO,"errors_count":N,"errors":{path:[...]}}
+
+RETAIN_VERSIONS = 20  # could be from settings/env
+
+def get_internal_model_for_document(doc: DocumentRow) -> dict:
+    """
+    Возвращает internal-model для документа, используя связанную схему:
+    1) document.schema_rel → Schema
+    2) Schema.file_path → чтение XSD из MinIO
+    3) xsd_internal.build_internal_model(content) → dict
+    """
+    schema: Schema | None = getattr(doc, "schema_rel", None)
+    if not schema or not getattr(schema, "file_path", None):
+        return {}
+    content = load_file_minio(schema.file_path)
+    if not content:
+        return {}
+    return xsd_internal.build_internal_model(content)
 
 @router.post("/{document_id}/versions", response_model=VersionOut, status_code=201)
-def save_draft(document_id: int, body: SaveDraftIn, db: Session = Depends(get_db)):
+def save_version(document_id: int, body: SaveDraftIn, db: Session = Depends(get_db)):
     doc = db.get(DocumentRow, document_id)
     if not doc:
         raise HTTPException(404, "Документ не найден")
-    v = DocumentVersionRow(document_id=doc.id, payload=body.payload, created_at=datetime.utcnow())
+    # server-side validation using the same internal-model as client
+    internal_model = get_internal_model_for_document(doc)
+    errs_dict = validate_model(body.payload, internal_model) if internal_model else {}
+    errors: list[dict] = [{"path": k, "messages": v} for k, v in errs_dict.items()]
+    status = "clean" if not errs_dict else "draft"
+    v = DocumentVersionRow(
+        document_id=doc.id,
+        payload=body.payload,
+        created_at=datetime.utcnow(),
+        status=status,
+        errors={"items": errors} if errors else None,
+        errors_count=len(errors),
+        is_protected=False,
+    )
+    try:
+        db.query(DocumentVersionRow).filter(
+            DocumentVersionRow.document_id == document_id,
+            getattr(DocumentVersionRow, "is_selected", False) == True
+        ).update({"is_selected": False})
+    except Exception:
+        # поле может отсутствовать до миграции — просто игнорируем
+        pass
+    if hasattr(v, "is_selected"):
+        v.is_selected = True
     db.add(v)
     # updated_at документа держим актуальным
     doc.updated_at = datetime.utcnow()
     db.commit()
     db.refresh(v)
-    return VersionOut(id=v.id, document_id=v.document_id, payload=v.payload, created_at=v.created_at)
+    # retention: keep last N unprotected & non-final
+    to_delete = (
+        db.query(DocumentVersionRow.id)
+          .filter(DocumentVersionRow.document_id == document_id,
+                  DocumentVersionRow.is_protected == False,
+                  DocumentVersionRow.status != "final")
+          .order_by(DocumentVersionRow.id.desc())
+          .offset(RETAIN_VERSIONS)
+          .all()
+    )
+    if to_delete:
+        ids = [r.id for r in to_delete]
+        db.query(DocumentVersionRow).filter(DocumentVersionRow.id.in_(ids)).delete(synchronize_session=False)
+        db.commit()
+    return VersionOut(
+        id=v.id, document_id=v.document_id, payload=v.payload, created_at=v.created_at,
+        status=getattr(v, "status", None),
+        is_protected=getattr(v, "is_protected", None),
+        is_selected=getattr(v, "is_selected", None),
+        validation={
+            "source": "server",
+            "checked_at": datetime.utcnow().isoformat(),
+            "errors_count": v.errors_count,
+            "errors": errs_dict
+        },
+    )
 
 @router.get("/{document_id}/versions", response_model=list[VersionOut])
 def list_versions(document_id: int, db: Session = Depends(get_db)):
@@ -43,7 +116,22 @@ def list_versions(document_id: int, db: Session = Depends(get_db)):
         .order_by(DocumentVersionRow.id.desc())
         .all()
     )
-    return [VersionOut(id=r.id, document_id=r.document_id, payload=r.payload, created_at=r.created_at) for r in rows]
+    out = []
+    for r in rows:
+        out.append(VersionOut(
+            id=r.id, document_id=r.document_id, payload=r.payload, created_at=r.created_at,
+            status=getattr(r, "status", None),
+            is_protected=getattr(r, "is_protected", None),
+            is_selected=getattr(r, "is_selected", None),
+            validation={
+                "source": "server",
+                "checked_at": (r.created_at.isoformat() if r.created_at else None),
+                "errors_count": getattr(r, "errors_count", None),
+                # превратим JSON ошибок из БД в ожидаемый вид {path:[...]}
+                "errors": { item["path"]: item["messages"] for item in (getattr(r, "errors", {}) or {}).get("items", []) }
+            } if hasattr(r, "errors_count") else None
+        ))
+    return out
 
 # get one version by id (primary key)
 @router.get("/{document_id}/version/{version_id}", response_model=VersionOut)
@@ -73,39 +161,109 @@ def latest_version(document_id: int, db: Session = Depends(get_db)):
         raise HTTPException(404, "Версии отсутствуют")
     return VersionOut(id=v.id, document_id=v.document_id, payload=v.payload, created_at=v.created_at)
 
-@router.put("/{document_id}/versions/latest", response_model=VersionOut)
-def upsert_latest_version(document_id: int, body: VersionIn, db: Session = Depends(get_db)):
-    """
-    Create first version if none exists; otherwise update payload of the latest version.
-    """
+# @router.put("/{document_id}/versions/latest", response_model=VersionOut)
+# removed: versions are immutable; create a new one instead
+
+class VersionStatusIn(BaseModel):
+    status: str  # only 'final'
+
+@router.patch("/{document_id}/versions/{version_id}/status")
+def set_version_status(document_id: int, version_id: int, body: VersionStatusIn, db: Session = Depends(get_db)):
+    if body.status != "final":
+        raise HTTPException(400, "only transition to 'final' is allowed")
+    v = db.get(DocumentVersionRow, version_id)
+    if not v or v.document_id != document_id:
+        raise HTTPException(404, "Версия не найдена")
+    # каноническая проверка перед финализацией
     doc = db.get(DocumentRow, document_id)
-    if not doc:
-        raise HTTPException(404, "Документ не найден")
-    v = (db.query(DocumentVersionRow)
-           .filter(DocumentVersionRow.document_id == document_id)
-           .order_by(DocumentVersionRow.id.desc())
-           .first())
-    if not v:
-        v = DocumentVersionRow(document_id=document_id, payload=body.payload, created_at=datetime.utcnow())
-        db.add(v)
-        db.commit(); db.refresh(v)
-        return VersionOut(id=v.id, document_id=v.document_id, payload=v.payload, created_at=v.created_at)
-    # overwrite latest
-    v.payload = body.payload
-    db.commit(); db.refresh(v)
-    return VersionOut(id=v.id, document_id=v.document_id, payload=v.payload, created_at=v.created_at)
+    internal_model = get_internal_model_for_document(doc) if doc else {}
+    errs_dict = validate_model(v.payload, internal_model) if internal_model else {}
+    v.errors = {"items": [{"path": k, "messages": m} for k, m in errs_dict.items()]} if errs_dict else None
+    v.errors_count = sum(len(m) for m in errs_dict.values())
+    v.status = "clean" if not errs_dict else "draft"
+    if v.status != "clean":
+        db.commit()
+        raise HTTPException(400, "only 'clean' can become 'final'")
+    v.status = "final"
+    v.is_protected = True
+    db.commit()
+    return {
+        "ok": True, "id": v.id, "status": v.status,
+        "validation": {
+            "source": "server",
+            "checked_at": datetime.utcnow().isoformat(),
+            "errors_count": v.errors_count,
+            "errors": errs_dict
+        }
+    }
 
-class PatchStatusIn(BaseModel):
-    status: str
+@router.post("/{document_id}/versions/{version_id}/freeze")
+def freeze_version(document_id: int, version_id: int, db: Session = Depends(get_db)):
+    v = db.get(DocumentVersionRow, version_id)
+    if not v or v.document_id != document_id:
+        raise HTTPException(404, "Версия не найдена")
+    if v.status != "final":
+        v.is_protected = True
+        db.commit()
+    return {"ok": True, "protected": True}
+
+@router.post("/{document_id}/versions/{version_id}/unfreeze")
+def unfreeze_version(document_id: int, version_id: int, db: Session = Depends(get_db)):
+    v = db.get(DocumentVersionRow, version_id)
+    if not v or v.document_id != document_id:
+        raise HTTPException(404, "Версия не найдена")
+    if v.status == "final":
+        raise HTTPException(400, "final versions cannot be unprotected")
+    v.is_protected = False
+    db.commit()
+    return {"ok": True, "protected": False}
+
+@router.post("/{document_id}/versions/{version_id}/select")
+def select_version(document_id: int, version_id: int, db: Session = Depends(get_db)):
+    v = db.get(DocumentVersionRow, version_id)
+    if not v or v.document_id != document_id:
+        raise HTTPException(404, "Версия не найдена")
+    # allow selecting clean/final; allow draft too — по договорённости (можно ограничить)
+    db.query(DocumentVersionRow).filter(
+        DocumentVersionRow.document_id == document_id,
+        DocumentVersionRow.is_selected == True
+    ).update({"is_selected": False})
+    v.is_selected = True
+    db.commit()
+    return {"ok": True, "selected_version_id": v.id}
+
+class PatchVersionIn(BaseModel):
+    payload: dict
 
-@router.patch("/{document_id}")
-def patch_status(document_id: int, body: PatchStatusIn, db: Session = Depends(get_db)):
-    if body.status not in ("draft", "final"):
-        raise HTTPException(400, "status must be 'draft'|'final'")
+@router.patch("/{document_id}/versions/{version_id}", response_model=VersionOut)
+def update_version(document_id: int, version_id: int, body: PatchVersionIn, db: Session = Depends(get_db)):
+    """Overwrite selected version payload in-place; forbid if final; set status=draft."""
     doc = db.get(DocumentRow, document_id)
     if not doc:
         raise HTTPException(404, "Документ не найден")
-    doc.status = body.status
-    doc.updated_at = datetime.utcnow()
-    db.commit()
-    return {"ok": True, "id": doc.id, "status": doc.status}
+    v = db.get(DocumentVersionRow, version_id)
+    if not v or v.document_id != document_id:
+        raise HTTPException(404, "Версия не найдена")
+    # forbid editing finals
+    if getattr(v, "status", None) == "final":
+        raise HTTPException(400, "final-версию редактировать нельзя")
+    # validate new payload on server
+    internal_model = get_internal_model_for_document(doc)
+    errs_dict = validate_model(body.payload, internal_model) if internal_model else {}
+    v.payload = body.payload
+    v.errors = {"items": [{"path": k, "messages": m} for k, m in errs_dict.items()]} if errs_dict else None
+    v.errors_count = sum(len(m) for m in errs_dict.values())
+    v.status = "clean" if not errs_dict else "draft"
+    db.commit(); db.refresh(v)
+    return VersionOut(
+        id=v.id, document_id=v.document_id, payload=v.payload, created_at=v.created_at,
+        status=getattr(v, "status", None),
+        is_protected=getattr(v, "is_protected", None),
+        is_selected=getattr(v, "is_selected", None),
+        validation={
+            "source": "server",
+            "checked_at": datetime.utcnow().isoformat(),
+            "errors_count": v.errors_count,
+            "errors": errs_dict
+        },
+    )

app/api/routes/documents_crud.py

@@ -72,13 +72,17 @@ def get_document(doc_id: int, db: Session = Depends(get_db)):
     if not d: raise HTTPException(404, "not found")
     obj = db.get(ObjectRow, d.object_id) if d.object_id else None
     sch = db.get(Schema, int(d.schema_id)) if d.schema_id else None
-    # latest version (id + payload)
-    v = (
-        db.query(DocumentVersionRow)
-          .filter(DocumentVersionRow.document_id == d.id)
-          .order_by(DocumentVersionRow.id.desc())
-          .first()
-    )
+    
+    # chosen (is_selected) or latest
+    v = (db.query(DocumentVersionRow)
+           .filter(DocumentVersionRow.document_id == d.id, DocumentVersionRow.is_selected == True)
+           .order_by(DocumentVersionRow.id.desc())
+           .first())
+    if not v:
+        v = (db.query(DocumentVersionRow)
+               .filter(DocumentVersionRow.document_id == d.id)
+               .order_by(DocumentVersionRow.id.desc())
+               .first())
     base = _pack(d, obj, sch).dict()
     return DocumentWithLatestOut(**base, latest_version_id=(v.id if v else None), payload=(v.payload if v else None))
 

app/models_sqlalchemy.py

@@ -2,7 +2,7 @@
 from datetime import datetime
 from typing import Optional
 
-from sqlalchemy import String, Integer, JSON, DateTime, ForeignKey, UniqueConstraint, cast
+from sqlalchemy import String, Integer, JSON, DateTime, ForeignKey, UniqueConstraint, cast, Boolean, Index
 from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Mapped, mapped_column, relationship, foreign
 
@@ -59,12 +59,27 @@ class ObjectRow(Base):
     name: Mapped[str] = mapped_column(String)  # user-facing name
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
 
+
 class DocumentVersionRow(Base):
     __tablename__ = "document_versions"
     id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
     document_id: Mapped[int] = mapped_column(ForeignKey("documents.id"), nullable=False)
     payload: Mapped[dict] = mapped_column(JSONB)  # JSONB for GIN/jsonb_path_ops
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
+    # new:
+    status: Mapped[str] = mapped_column(String(16), default="draft")  # 'draft' | 'clean' | 'final'
+    errors: Mapped[dict | None] = mapped_column(JSON, nullable=True)  # {items:[...]} or None
+    errors_count: Mapped[int] = mapped_column(Integer, default=0)
+    is_protected: Mapped[bool] = mapped_column(Boolean, default=False)  # manual “freeze”; final is implicitly protected
+    is_selected: Mapped[bool] = mapped_column(Boolean, default=False)  # chosen for editing/view
+
+# one selected version per document (partial unique index)
+Index(
+    "uq_document_versions_selected_once",
+    DocumentVersionRow.document_id,
+    unique=True,
+    postgresql_where=(DocumentVersionRow.is_selected == True),
+)
 
 class FileRow(Base):
     __tablename__ = "files"