# IDS platforma — technický návrh a roadmapa

Návrh implementace **buildingSMART IDS 1.0.0** autorské platformy jako samostatného
modulu vieweru, dle zadání `TECHNICKE_ZADANI_IDS_PLATFORMY.md`. Dokument mapuje
zadání na moduly, popisuje fáze a shrnuje rozhodnutí, která gate-ují hlubší práci
(§19 zadání).

## 1. Architektura — mapování zadání → moduly

Zadání dělí platformu na **IDS Core** (knihovna), **IDS Editor** (grafické UI) a
**IFC Context Adapter** (napojení na otevřený model). Modul to zachovává jako
oddělené vrstvy s jednosměrnou závislostí:

```
IFC Context Adapter ─┐
IDS Editor UI ───────┼─▶ IDS Core (doména · kodek · schéma)   ← žádná zpětná závislost
                     ┘
```

| Zadání | Modul (soubor) | Fáze | Stav |
|---|---|---|---|
| Doménový model, facety, applicability/requirements, cardinality, value constraints (§4–6, §9) | `domain/model.js`, `domain/constants.js` | 1 | ✅ hotovo |
| Příkazy (create/add/update/move/remove/duplicate), neměnné revize, undo (§10) | `domain/commands.js` | 1 | ✅ hotovo |
| Validace úroveň 3 (doménová pravidla, diagnostiky) (§8.1–8.2) | `domain/invariants.js` | 1 | ✅ hotovo |
| Serializace `.ids` XML, deterministická (§7.3) | `codec/serialize.js` | 1 | ✅ hotovo, **XSD-conformní** (ověřeno xmllint) |
| Registry verzovaných XSD (§8.3, AC-05) | `schema/registry.js` + `schema/ids.xsd` | 1 | ✅ **XSD 1.0.0 připnuté** (checksum) |
| Veřejné API IDS Core (§12) | `index.js` | 1 | ✅ hotovo |
| Autoritativní XSD validace úroveň 2 (§8.1, AC-05) | `schema/registry.js` | 1 | ◑ XSD připnuté; runtime strukturální + externí `xmllint` |
| Import `.ids` — XXE-safe parser, round-trip (§7.2, AC-08) | `codec/parse.js` + `codec/xml.js` | 1 | ✅ hotovo (round-trip ověřen) |
| IDS Editor UI — stromy, panely, i18n, náhled, import/export (§11, §13) | `ui/` (entrypoint `IDSEditor`) | 2 | ✅ hotovo (vanilla JS, CZ/EN) |
| **Integrace do vieweru** — navbar „IDS" + panel + adaptér nad ŽIVÝM modelem | `src/idsPanel.js` + `src/idsContext.js` (viewer) | 3 | ✅ hotovo (ověřeno v prohlížeči) |
| IFC Context Adapter — našeptávání + „kolik prvků vyhovuje applicability" (§14) | `adapter/` (matcher·context·viewerAdapter) | 3 | ✅ hotovo (ověřeno v prohlížeči) |
| Audit modelu proti IDS + reporty (HTML/BCF/MD) (§16) | `audit/` (auditor·report) | 4 | ✅ hotovo (ověřeno v prohlížeči) |
| CLI / dávkové ověření sady modelů (§16) | `cli/` | 5 | ⬜ volitelné (auditor je použitelný z CLI) |

## 2. Datový model (Fáze 1)

- **Document** `{ nodeId, standardVersion:"1.0.0", revision, info, specifications[] }`.
  `info` má povinný `title`; ostatní pole (author, date, purpose…) v pevném pořadí.
- **Specification** `{ nodeId, name, ifcVersions[], applicability[], requirements[] }`.
  `ifcVersions ⊆ {IFC2X3, IFC4, IFC4X3_ADD2}`.
- **Facet** (6 druhů): `entity · partOf · classification · attribute · property · material`.
  Applicability povoluje všech 6; requirements 5 (bez `entity`) — hlídá `isFacetAllowed`.
- **ValueConstraint**: `simpleValue` (přesná hodnota) nebo `xs:restriction`
  (enumeration / pattern / min|maxInclusive / min|maxExclusive / length…).
- **Cardinality** requirement faset: `required · optional · prohibited`.

Každý uzel má `nodeId` (adresace pro příkazy a diagnostiky). Příkazy pracují
**immutable** — `execute()` klonuje, aplikuje, zvýší `revision`; vstup zůstává →
undo/redo je „drž předchozí dokument".

## 3. Validace — tři úrovně (§8.1)

1. **Well-formed XML** — vlastní XXE-safe čtečka `codec/xml.js` (odmítá DOCTYPE/entity,
   běží v prohlížeči i node, bez `DOMParser`); `codec/parse.js` je inverzní k exportu
   (round-trip `serialize→parse→serialize` je stabilní).
2. **Autoritativní XSD** proti `ids.xsd 1.0.0` — XSD je **připnuté** (`schema/ids.xsd`
   + checksum). Serializer je s ním strukturálně srovnán a shoda ověřena nezávisle
   `xmllint`. Plný W3C XSD procesor ale není v čistě klientském JS bundlován, proto
   runtime `xsdValidate` vrací **neblokující** `IDS-XSD-100` (info) — ne falešné
   „prošlo" ani zbytečné blokování; pro vyčerpávající kontrolu slouží vložený
   `ids.xsd` s externím nástrojem, nebo injektovaný `validator`.
3. **Doménová pravidla** — `validateDomain()` → `Diagnostic[]` s kódy `IDS-DOM-*`
   (název specifikace, neprázdná applicability, jediná entity v applicability,
   povolenost fasety v sekci, cardinality dle typu — partOf `simpleCardinality`,
   `dataType` `[A-Z]+`, e-mailový `author`, korektní value constraints…).

Export (`exportIds`) je **blokován při chybě** (`severity:"error"`); info/warn
neblokují. `allowDraft:true` povolí obejít i chyby s výstupem označeným jako draft.

## 4. Bezpečnost

- **Offline** — žádné síťové volání; XSD se nestahuje automaticky (AC-05).
- **XXE / XML bomba** — čtečka `codec/xml.js` odmítá DOCTYPE i deklarace entit a
  nefetchuje nic externího (jako XML hardening v BCF a AI vrstvě). AC-08.
- Modul je čistě klientský/knihovní; nezapisuje a needituje IFC.

## 5. Roadmapa

- **Fáze 1 (IDS Core):** hotovo — model, příkazy, invarianty, XSD-conformní export,
  připnuté a ověřené `ids.xsd`, XXE-safe import s round-trip. Volitelné rozšíření:
  WASM XSD procesor pro plnou runtime XSD validaci v prohlížeči.
- **Fáze 2 (IDS Editor UI):** hotovo — samostatný esbuild entrypoint (global
  `IDSEditor`, bundluje Core), vanilla JS, i18n CZ/EN, strom info/spec/faset, editory
  všech faset + omezení, živý náhled XML + diagnostiky, Undo/Redo, import/export.
  Demo `examples/ids-editor/`. Ověřeno v prohlížeči.
- **Fáze 3 (IFC Context Adapter):** hotovo — čistý matcher + catalog/viewer provider,
  datalist našeptávání a živý badge „Vyhovuje N/M" u applicability. `matcher.elementMeetsRequirements`
  připraven pro audit. **Plně integrováno do vieweru** — navbar „IDS" → vložený editor
  napojený na PRÁVĚ OTEVŘENÝ model přes `src/idsContext.js` (extrakce prvků z fragmentů:
  třídy/psety/klasifikace/materiály/kontejner) a `src/idsPanel.js` (dynamické načtení
  `/ids/ids-editor.js`, mount, `setContext`). Ověřeno v prohlížeči: reálný model 49 prvků,
  našeptávání i audit nad skutečnými prvky (jména stěn Z024…), HTML/BCF report.
- **Fáze 4 (Audit + reporty):** hotovo — `audit/auditor.js` (applicability +
  requirements se sémantikou cardinality + occurs) a `audit/report.js`
  (HTML / BCF témata / Markdown). V editoru tlačítko „Ověřit model" s přehledem a
  stažením reportů. Ověřeno v prohlížeči (pass i fail scénář).
- **Fáze 5 (volitelné):** CLI/dávkové ověření sady modelů (auditor je čistý, použitelný
  i mimo prohlížeč) a napojení `toBcfTopics` na BCF platformu (bcf/) pro tvorbu BCFZip.

## 6. Rozhodnutí (§19) — vyřešeno

1. **Technologický stack — potvrzeno vanilla JS + esbuild.** Modul kopíruje konvenci
   repozitáře (ESM + IIFE global `IDS`, bez frameworku, zrcadlení do `build/`). IDS
   Editor UI (Fáze 2) bude rovněž vanilla JS panely v duchu stávajícího vieweru.
2. **Oficiální `ids.xsd 1.0.0` — vloženo a připnuto.** Staženo z ověřené release
   `buildingSMART/IDS` tag `v1.0.0` (`Development/ids.xsd`), uloženo do
   `ids/src/schema/ids.xsd`, checksum `sha256:8975dc18…d1f3` připnut v
   `schema/registry.js`. Serializace srovnána s XSD a ověřena `xmllint` (referenční
   export validuje; negativní kontrola selže). Export je tedy **validní dle XSD**,
   ne provizorní.

**Otevřené pro rozhodnutí u další fáze:** plná runtime XSD validace v prohlížeči
(WASM libxml2 vs. ponechat externí `xmllint`/injektovaný validator) — netriviální
offline; navrženo řešit až po `codec/parse.js`.