Ugrás a fő tartalomhoz

OMI Studio 1.0 Refactoring and PR Plan

Baseline: Studio eca2cf45762116e1c00a89b3397840ed89109511 és a 2026-09-19-i OMI/PKP commitok
Cél: kis, külön tesztelhető, visszagörgethető PR-okkal eljutni 1.0.0-rc.1, majd 1.0.0 kiadásig.

1. Végrehajtási elvek

  1. Contract vagy adapter előbb, callsite-migráció utána, régi út eltávolítása legutoljára.
  2. Minden PR egyetlen elsődleges architekturális változást végezzen; mechanikus move ne keveredjen szemantikai változással.
  3. Magas kockázatú PR előtt characterization/golden fixture kerüljön be.
  4. A meglévő fájlformátumot az átmenet alatt dual-read/new-write vagy shadow-validation védi; nincs csendes in-place conversion.
  5. A régi route/store facade addig marad, amíg minden ismert kliens/callsite át nem állt.
  6. A rollout feature flagje nem kompatibilitási stratégia: az adatformatum és identity/security váltásoknak explicit rollback/forward tervük van.
  7. Tesztanyag kizárólag synthetic, nyilvános vagy kifejezetten tesztcélú; privát manuscript cím, szerző, fájlnév, tartalom és lokális path nem kerül Gitbe vagy CI-logba.

2. Függőségi kép

flowchart TB
A["A: contracts and freeze"] --> B["B: core boundaries"]
A --> C["C: interoperability"]
B --> C
B --> D["D: platform hardening"]
C --> E["E: release candidate"]
D --> E
E --> F["F: 1.0 release"]

A fázison belül az alábbi PR-számok topologikus sorrendet jelentenek. Párhuzamosítható PR-t külön jelölünk.

3. Phase A — Architecture freeze

Kilépési feltétel: elfogadott compatibility policy; normatív schema/container/content contract candidate; /api/v1 és connector contract irány; dependency boundary lint; feature support matrix.

PRCélÉrintett modulok / várható fájlokElőfeltételKötelező tesztBreaking-change kockázatTechnikai kockázat
A01Rögzítse az 1.0 stable/preview/deferred scope-ot és a három verzióvonalat.OMI/Studio docs/architecture, docs/release/1.0-scope.md, ADR-knincsdocs link/check; support matrix completenessnincs runtime breaklow
A02Tegye az OMI 0.2 schema-fixture suite-ot kötelező OMI CI-vé és release artifacttá.OMI package.json, .github/workflows/website-build.yml vagy új conformance workflow, tests/file-format, schemaA018 meglévő + új negative/future fixture; schema checksumschema artifact freeze után breakingmedium
A03Vendorolja a released sémát a Studioba és vezessen be OmiEnvelopeClassifier/validator modult shadow módban.src/schemas/*, új src/core/omi/format/*, build sync script, testsA02checksum drift, valid/invalid/future classification; jelenlegi docs shadow reportnincs: még nem blokkolmedium
A04Vezessen be explicit open policyt és future-schema quarantine/read-only eredményt.nativeManuscriptFile.ts, omiContainerImport.ts, új application/documents/open*, UI error/read-only stateA03new-major/minor/invalid/oversize fixtures; nincs overwrite; raw recoveryuser-visible új elutasítás, szándékoshigh
A05Vezessen be pre-save/export validation gate-et és unknown-extension preservation fixture-t.exportOmi.ts, save actions, format serializer, extension bagA03, A04open→save semantic equality; invalid save blocked; unknown payload hashhibás dokumentum többé nem menthető csendbenhigh
A06Fagyassza a SPEC-100 portable content AST candidate-et, és adjon ContentCodec contractot a jelenlegi Tiptap JSON fölé.OMI content spec/schema; Studio új core/omi/content, editor-tiptap/codec; richText.ts, inlineSemantics.tsA01legacy text + jelenlegi PM JSON → AST → PM golden; unknown node diagnosticscontract még internal/candidatehigh
A07Fagyassza a SPEC-330 container manifest/path/checksum/security candidate-et a működő Studio parserből.OMI container spec/schema/fixtures; Studio omiContainer*.ts, simpleZip.tsA02, A03cross-repo golden containers; corrupt/path/symlink/CRC/SHA/limitsúj container writer később breakinghigh
A08Definiálja az egységes diagnostics/fidelity/provenance alapcontractot.új src/application/diagnostics, import/export type shimekA01serialization, redaction, stable code registrynincslow
A09Hozza létre az /api/v1 transport alapot közös error/idempotency/correlation contracttal, régi route érintése nélkül.server/src/api/v1, Zod/OpenAPI registry, middleware, app.tsA01contract test, error envelope, auth middleware orderingnincs, additívmedium
A10Vezessen be import-boundary architecture testet és compatibility re-export mintát.ESLint config/custom rule vagy dependency-cruiser, CI, új barrel modulokA03, A06, A09tiltott core→React/Tiptap/Prisma/fetch import fixturesCI új hibát jelezhetlow

A fázis blocker-ek: nincs kijelölt owner az OMI schema release-re; SPEC-100 AST nem elég konkrét; SPEC-330 implementáció–spec eltérés nincs lezárva; stable platform/export scope nincs kimondva.

4. Phase B — Core refactoring

Kilépési feltétel: create/open/save és legalább a fő editing/history út application facade mögött; Tiptap adapter boundary működik; portable/persistence/UI state ownership elkülönült; native credential nem localStorage.

PRCélÉrintett modulok / várható fájlokElőfeltételKötelező tesztBreaking-change kockázatTechnikai kockázat
B01Hozzon létre application portokat és StudioApplication facade-ot a jelenlegi model functionök változtatása nélkül.új src/application/ports, documents, editing; composition rootA10fake repository/clock/ID generator unit testsnincsmedium
B02Migrálja a document create/open/save/close/recover use-case-eket a facade mögé.newDocumentActions.ts, documentLifecycle.ts, nativeManuscriptFile.ts, lastSessionPersistence.ts, store delegate-ekA04, A05, B01create/open/save/reopen; invalid/future; close dirty matrixbelső API; UI viselkedés regresszió lehetségeshigh
B03Bontsa szét a Zustand ownershipot domain snapshot, UI, editor session és persistence projection szerint.useStudioStore.ts, új ui/state/*, selector compatibility layerB01, B02441 jelenlegi teszt + selector/action characterization + fake-clockbelső action signatures átmenetileg dualhigh
B04Egyesítse az automatikus checkpoint timereket egy document-scoped schedulerbe.useStudioStore.ts, history/actions, új schedulerB03fake timer, close/switch/reopen, no duplicate commitnincs külső breakmedium
B05Terelje a Tiptap-content összes olvasását/írását a ContentCodec facade mögé.BlockEditor.tsx, continuous doc, citations, notes, xrefs, search, lists, proofing, clipboard, exporterekA06, B01jelenlegi editor/export golden output diff; corrupted node diagnosticsnincs még wire-format breakhigh
B06Váltsa az új mentést a portable OMI AST-re; a pre-stable Tiptap-string formátum csak explicit import legyen.OMI schema/content, codec, serializer, legacy importer, fixturesB05, A05AST round-trip; old experimental fixture import; new-major quarantineigen: ez az első stable format candidatehigh
B07Vezessen be RevisionRepository portot a jelenlegi full-snapshot algoritmus adapterével.versioning.ts, workingState.ts, revisionIntegrity.ts, IndexedDB/container adapterB01, B06current history suite; materialize/revert/integrity cross-adapternincs szemantikai breakmedium
B08Adjon crash-safe atomic save/recovery journal implementációt és opaque DocumentLocation-t.native/browser persistence adapterek, nativeManuscriptFile.ts, session stateB02, B07kill/fail injection minden írási ponton; backup restore; concurrent digest conflictpath/session internal API változikhigh
B09Formalizálja az identity DB authorityt és a main DB StudioPrincipal projectiont.két Prisma schema/migration, studioPrincipalBridge.ts, auth service, reconciliation jobA09migration rollback snapshot; idempotent ensure; drift/reconcile; auth flowsDB migration, kompatibilis dual-read szükségeshigh
B10Vezesse be a platform SecureStorage portot és migrálja a native bearer tokent.frontend auth API, native auth handoff, Tauri/Android/Apple adapter/configB01upgrade token migration, logout/revoke, XSS/localStorage absence testrégi natív session kijelentkeztethető fallbackkelhigh
B11Válassza szét account, auth identity, scholarly agent, contribution és evidence mappinget.model/identity.ts, linked identity routes/service, OMI agents UI/API, author signatureB09no implicit email/ORCID merge; verified link/revoke; contribution persistenceDTO változás v1 candidate-benhigh
B12Cserélje a proofing/tracked-change string-offset modellt stable anchor/semantic operationre adapterrel.model/proofing.ts, Tiptap proofing extensions, proofreading API/UIB05, B06concurrent edit/anchor remap; Unicode/grapheme; accept/reject round-tripportable proofing schema változik a freeze előtthigh
B13Izolálja vagy távolítsa el az árva workspace alpha store-t és az üres domain placeholder modulokat.src/store/workspaceStore.ts, model/workspace.ts, üres model fájlok, exportsA10, B03, usage auditfull build/tests; no import/reference; optional data export notecsak nem támogatott alpha statelow

Miért nem egy PR? B03, B05, B06, B08 és B09 külön rollback domén. Store-refaktor közben nem szabad wire-formatot váltani; schema-váltás közben nem szabad DB authorityt migrálni. A jelenlegi viselkedést B05-ig változatlan codec védi.

5. Phase C — Interoperability hardening

Kilépési feltétel: közös importer/renderer/connector/review contractok; OJS és OMP ugyanazt a contract suite-ot teljesíti; publication artifact reprodukálható és validált; schema/container conformance kötelező.

PRCélÉrintett modulok / várható fájlokElőfeltételKötelező tesztBreaking-change kockázatTechnikai kockázat
C01Vezesse be az Importer registryt source/probe/progress/abort/diagnostics/fidelity contracttal.új application/import, adapter registry; A08 typesA08, B01, B06fake importer, ambiguity/probe, abort, redaction, no store mutation before commitnincs, wrappersmedium
C02Csomagolja be az OMI/DOCX/PDF/HTML/table/image/music/reference importereket; javítsa a MIDI routingot.docx*, pdfImport*, officeImport.ts, musicImport.ts, referenceInterchange.ts, app actionsC01formátumonként golden; MIDI .mid/.midi; size/cancel/hostile corpusimport diagnostics változhat, content nemhigh
C03Vezesse be a Renderer registryt és válassza le az ArtifactDeliveryPort-ot.export*.ts, exportFileDelivery.ts, UI export panelekA08, B05, B06minden exporter wrapper contract; delivery fake; nincs picker rendererbőlbelső APIhigh
C04Válassza le a publication profile-t az OMI module augmentationről és építse meg az immutable RenderingContext-et.publicationProfile.ts, paragraph styles, publication rendering/build, profile UI/storageC03old embedded profile dual-read; profile version; context goldenúj profile storage contract, dual-read kellhigh
C05Pinelje renderer/validator/font/resource verziókat; különítse el semantic és byte reproducibilityt.build manifest/sidecar, JATS/HTML/PDF rendererek, font service, signature modulesC04repeated build hashes; font substitution; timezone/locale; signature cross-runtimeartifact manifest schema változik freeze előtthigh
C06Készítsen közös Publishing System Connector schema/package-et capability/launch/submission/review/writeback receipt contracttal.Studio shared types/server; OJS/OMP plugin contract fixtures/docsA08, A09JSON contract fixture mindhárom repo-ban; version negotiationplugin protocol candidate változáshigh
C07Illessze az OJS klienst és plugint a közös connector API-ra compatibility route-tal.Studio OJS integrations/routes; OJS plugin routes/servicesC06supported OJS 3.5.0-4/5 Docker E2E; replay/scope/files/form/recommendation/artifactrégi plugin kompatibilitást meg kell tartanihigh
C08Illessze az OMP klienst és plugint a közös API-ra monograph/chapter extensionökkel.Studio OMP modules/routes; OMP plugin controllers/servicesC06OMP Docker E2E; assigned chapter confinement; rounds/stage files/attachmentsrégi plugin kompatibilitást meg kell tartanihigh
C09Vezessen be durable outbox/idempotent sagát submission/revision/review/artifact writebackra.Prisma migration, submission/review services, connector worker/status UIC07, C08, B09remote timeout/duplicate/retry/crash; receipt reconciliation; no false rollbackDB/runtime behavior, additivehigh
C10Emelje ki a publishing-system-neutral review domaint és hardenelje az anonymous projectiont.peer review/review manuscript services, core/review, serializers, asset transformsB11, C06role-transition matrix; identity leak corpus; asset EXIF/SVG; cache/log redactionsnapshot DTO v1 candidate változikhigh
C11Vezessen be server-issued ExecutionGrant modellt integrations/AI/DeepL/reference manager számára.integration contracts/execution/routes, provider registry, UI dialogs, credential repoB09, B11, A09denied scope, selection-only payload, confidential review, expiry/replay, audit digestrégi request flag többé nem ad jogothigh
C12Konszolidálja a credential storage-ot és csomagolja közös connectorba Zotero/Mendeley/ORCID/OIDC/provider secret útvonalakat.identity/main Prisma, reference manager service, secretCrypto, user integrationsB09, C11dual-read migration; encrypt/decrypt/key rotation; revoke; no logDB migrationhigh
C13Illessze a cloud storage providereket egységes remote object store contracthoz ETag/conflict receipt-tel.CloudStorageProvider, OAuth/WebDAV providers, cloud routes/client, local cloud folderB08, C11SSRF redirects, ETag conflict, checksum, token refresh, large/resume behavioradditív adapter; provider UX változhatmedium
C14Promotálja csak a bizonyított export formátumokat stable-re; a többit jelölje previewként runtime capabilityből.exporter descriptors, UI, docs, release metadataC03–C05JATS/HTML/DOCX/PDF gates; DTP/EPUB/LaTeX smoke; capability UIfeature label változáslow

C fázis blocker-ek: támogatott OJS/OMP verziókhoz nincs elérhető test image; fontlicenc nem engedi a reprodukálható bundle-t; JATS/profile követelmény nincs kijelölve; connector DTO owner nincs kijelölve.

6. Phase D — Platform hardening

Kilépési feltétel: minden stable platform ugyanazt a core/application suite-ot használja; platformadapter-contractok teljesülnek; teljesítmény és accessibility budget elfogadva.

PRCélÉrintett modulok / várható fájlokElőfeltételKötelező tesztBreaking-change kockázatTechnikai kockázat
D01Vezesse be a teljes platform port-készletet: picker/filesystem/secure storage/auth handoff/updater/fonts/share/notifications.adapters/platform, jelenlegi services, Tauri/mobile configB08, B10, C03contract fake + web/Tauri adapter tests; tiltott direct import lintnincs külső, belső importváltáshigh
D02Hardenelje a web file/session/recovery és PWA/browser capability fallbackokat.browser adapter, IndexedDB, last-session, authD01Chrome/Firefox/WebKit open/edit/save/reopen; quota/denied permission/offlinenincsmedium
D03Hardenelje a Windows/Linux/macOS Tauri artifactot és frissítést.Rust/Tauri capabilities, updater, installer workflowsD01install, open-with, atomic save, update/rollback, signed artifact; Win11/Ubuntu stable, mac scope szerintinstaller/update behaviorhigh
D04Hardenelje Android SAF/auth/update/process-death viselkedést.Android adapter/project, Tauri mobile bridge, release workflowD01Android 10+ picker permission persistence, large file, process death, updateplatform behaviorhigh
D05Fejezze be az iOS/iPadOS preview adaptereket, stable promotion nélkül.Apple Files/Keychain/auth/share adapter, simulator/release workflowD01simulator + device smoke; Files permission, background/resume, privacypreview onlymedium
D06Állítson be performance budgetet és javítsa a main chunk/editor/renderer lazy loadingot.Vite config, routes/components, exporter imports, progressive mountingB03, B05, C0310k/120k/500k benchmark; heap/editor count; main chunk budget; no ineffective dynamic importnincs, loading UX változhatmedium
D07Tegye release-blockinggá a kritikus accessibility journey-ket.React UI/focus styles, Playwright axe, manual checklistB03, D02keyboard-only create/edit/review/export; axe; screen-reader smoke; zoom/contrastUI kisebb változásmedium
D08Formalizálja a stable/preview platform capability manifestet és runtime kijelzést.version/release metadata, UI About/help, docsD02–D07build artifact capability snapshot; docs/runtime equalitynincslow

7. Phase E — Release Candidate

Kilépési feltétel: ugyanazon commitból előállított 1.0.0-rc.1 artifactok; minden mandatory gate zöld; nincs P0/P1 adatvesztési/security/anonymity blocker; acceptance report aláírva.

PRCélÉrintett modulok / várható fájlokElőfeltételKötelező tesztBreaking-change kockázatTechnikai kockázat
E01Építsen közös hostile-input/security corpust és fuzz harness-t.JSON/ZIP/XML/HTML/DOCX/assets/JATS parser tests; CI security jobsA04, A07, C02, C10ZIP bomb/traversal/duplicate; XXE/entity; SVG/script; SSRF; malformed JSON; log redactionnincshigh
E02Készítsen exact-commit RC aggregator workflow-t path filter nélkül..github/workflows/1.0-rc.yml, reusable workflows, evidence manifestminden A–D gateteljes matrix; artifact/SBOM/provenance hash; rerun policynincsmedium
E03Futtasson synthetic/public real-world acceptance corpust és zárt privát acceptance protokollt tartalomfeltöltés nélkül.test corpus manifest, local-only acceptance script/report templateC14, D08, E01format/platform journeys; private run csak content-free pass/fail/metrics reportot adnincsmedium
E04Zárja le az API/schema/container/connector compatibility baseline-t és generálja a release dokumentációt.specs, OpenAPI/schema snapshots, changelog, support matrix, deprecation policyE02, E03breaking-diff detector; docs links; fixture checksumfreeze után minden eltérés breakinghigh
E05Készítse el és tesztelje 1.0.0-rc.1 artifactokat.version files, release workflows, installers, plugin packages, website/schema artifactsE02–E04mandatory gate-ek exact tag commiton; install/update/rollback; signaturesrelease candidatehigh

RC soak és exit

  • Minimum egy teljes, előre rögzített soak időszak minden stable platformon.
  • P0/P1 bug esetén új RC; nincs „waiver” adatvesztésre, credential leakre, anonymity breachre, schema corruptionre vagy signature mismatchre.
  • P2 csak dokumentált workarounddal és ownerrel maradhat, ha nem érinti a stable contractot.
  • Privát acceptance kézirat helyben marad; Git/CI-be csak content-free mérőszám és issue reproducerként synthetic minimal case kerülhet.

8. Phase F — 1.0

PRCélÉrintett modulok / várható fájlokElőfeltételKötelező tesztBreaking-change kockázatTechnikai kockázat
F01Promotálja a legutolsó változatlan RC commitot 1.0.0-ra.release metadata/changelog/tags; nincs funkcionális kódRC exit aláírvaartifact hash az RC-vel egyezik vagy indokolt rebuild reproducibility igazoltnincs új breaklow
F02Publikálja a support/deprecation/security response csatornákat és compatibility fixture csomagot.docs/site/schema releases/plugin releasesF01public links/checksums/download install smokenincslow
F03Nyissa meg az 1.0.x hardening milestone-t kizárólag kompatibilis változásokra.GitHub milestones/issue templatesF01issue template policynincslow

Az 1.0.0 nem kaphat funkcionális javítást az utolsó RC-hez képest. Ha kód változik, új RC szükséges.

9. PR dependency register

PRKözvetlen függőségPárhuzamosítható ezzel
A01
A02A01A08, A09
A03A02A06, A08, A09
A04A03A06, A07
A05A03, A04A07–A10
A06A01A02–A05, A08–A10
A07A02, A03A04–A06, A08–A10
A08A01A02–A07, A09–A10
A09A01A02–A08
A10A03, A06, A09
B01A10
B02A04, A05, B01B09
B03B01, B02B09, B10
B04B03B05, B09–B11
B05A06, B01B09–B11
B06A05, B05B09–B11
B07B01, B06B09–B11
B08B02, B07B09–B12
B09A09B02–B08
B10B01B03–B09
B11B09B03–B08, B10
B12B05, B06B07–B11
B13A10, B03B04–B12
C01A08, B01, B06C06
C02C01C03, C06
C03A08, B05, B06C01, C06
C04C03C01–C02, C06
C05C04C06–C08
C06A08, A09C01–C05
C07C06C08, C10
C08C06C07, C10
C09C07, C08, B09C10–C14
C10B11, C06C07–C09
C11B09, B11, A09C07–C10
C12B09, C11C09–C10, C13–C14
C13B08, C11C09–C12, C14
C14C03–C05C09–C13
D01B08, B10, C03
D02–D05D01egymással
D06B03, B05, C03D02–D05, D07
D07B03, D02D03–D06
D08D02–D07
E01A04, A07, C02, C10D fázis
E02A–D fázis gate-jeiE01, E03 előkészítése
E03C14, D08, E01E02
E04E02, E03
E05E02–E04
F01RC exit

10. Nagyobb refaktorok indoklása

RefaktorMiért nem elég kisebb módosítás?Miért nem teljes újraírás?
Tiptap ↔ OMI content boundarySok független consumer közvetlenül parse-olja ugyanazt a stringet; egy exporter javítása nem hoz lossless formátumot.A Tiptap extensionök, editor UI és parsing logika megmarad; codec mögé kerülnek.
Zustand/application splitA globális store ownershipja miatt a platformfüggetlen use-case önmagában nem tesztelhető és a timer/persistence/UI együtt mozog.A jelenlegi action behavior characterization után egyesével delegálható; UI selectorok maradnak.
History repositoryA full snapshot minden revisionben skálázási gond, de előbb mérést és storage boundaryt igényel.A revision semantics, IDs, revert és integrity megtartható; csak tároló cserélhető.
Identity authorityKét schema ugyanazt a user/session/identity fogalmat hordozza; ad hoc javítás újabb driftet hoz.Az identity DB és a bridge működik; projection/outbox és fokozatos migration kell, nem új auth rendszer.
Connector common APIOJS/OMP capability-k párhuzamos DTO-i később minden új rendszerrel sokszorozódnának.A két plugin és kliens megmarad adapterként; csak közös contract mögé kerül.
Review projectionAnonimitás security boundary, ezért UI field hide nem elég.A meglévő szerveroldali allowlist/sanitizer a kiindulás; corpus és versioned projection erősíti.

11. Rollback stratégia

  • Schema/open: A03 shadow validator rollbackelhető; A04 után a régi parser csak explicit legacy-importként marad. Már új formátumba mentett dokumentumot nem downgrade-elünk automatikusan.
  • Content AST: B05 még változatlan wire outputot ad. B06 aktiválásakor a writer versiont vált; rollback esetén az új fájl read-only/recovery, nem régi writerrel overwrite.
  • Store: compatibility selector/action facade tartja a UI-t; slice-onként kapcsolható vissza.
  • DB/identity: expand–migrate–contract séma; először nullable/additive mező, dual-read és reconcile, csak később drop. Minden migrationhez tested down/restore eljárás.
  • Connector/outbox: connector adapter feature flaggel váltható, de az outbox eventet nem szabad elveszíteni; rollback worker ismeri mindkét payload verziót.
  • Platform: adapter selection composition rootban; régi adapter csak addig marad, amíg ugyanazt a security policyt teljesíti.

12. Milestone-javaslat

MilestoneTartalomExit artifact
1.0-architecture-freezeA01–A10accepted ADR-k, pinned schema/container/content/API candidates
1.0-core-boundariesB01–B13app facade, portable content, persistence/history/identity boundaries
1.0-interoperabilityC01–C14common import/render/connector/review contracts és evidence
1.0-platform-hardeningD01–D08stable platform matrix és budgets
1.0-rc.1E01–E05signed exact-commit RC artifact + evidence manifest
1.0.0F01–F03változatlanul promotált RC, public compatibility/support policy

13. Minimális issue-sablon minden PR-hoz

  • Contract/ADR hivatkozás.
  • Előtte–utána dependency boundary.
  • Megtartott jelenlegi viselkedés és szándékos változás.
  • Érintett stable/preview capability.
  • Synthetic/public fixture linkje.
  • Rollback feltétel és adatkompatibilitási megjegyzés.
  • Teszt evidence, performance/security hatás.
  • Dokumentáció/spec eltérés, amelyet a PR lezár vagy nyitva hagy.