Struktura dokumentacji

Ta strona definiuje konwencję pisania dokumentacji EVAN. Jej celem jest jedno: opisać każdy fakt dokładnie raz, tak aby utrzymanie nie polegało na poprawianiu tego samego w trzech miejscach.

Zasada nadrzędna: jedno źródło prawdy

Każdy fakt ma dokładnie jedną „ojczyznę" — jedną stronę, na której jest opisany. Wszystkie inne strony tylko linkują do niego, nigdy nie powtarzają treści.

System można opisywać na kilka ortogonalnych sposobów (proces, moduł, ekran, encja, rola). Nie wybieramy jednego „kosztem" reszty — wybieramy jeden kręgosłup opisowy, a pozostałe osie robimy nawigacyjno-orkiestracyjne: spis + linki, bez powtarzania szczegółów.

Trzy osie i ich role

Kręgosłupem opisowym jest moduł → ekran, bo moduł = jednostka utrzymania kodu: gdy zmienia się pakiet (np. FLOTA_GUI_PKG), istnieje jedna oczywista strona do aktualizacji. Proces i koncept to warstwy łączące, które niczego nie powielają.

Przykład: faktura w trzech osiach

Ten sam temat „Faktury" żyje na różnych osiach bez powielania:

• Proces „Fakturowanie / Przyjmowanie z KSeF" → opisuje przepływ i na każdym kroku linkuje do ekranu/modułu.
• Moduł „Faktury" (index) → wymienia swoje ekrany, pakiety (FAKTURA_TRA_PKG…), tabele; w nagłówku tag procesy: z linkiem.
• Ekran „Korekty" → opisany raz, u siebie. Proces i moduł go cytują linkiem.
• Koncept „Integracja KSeF" → protokół, pakiety, kryptografia — niezależnie od UI.

Frontmatter i tagi (standard)

Każda strona modułu/ekranu/procesu powinna mieć w nagłówku YAML pola łączące ją z pozostałymi osiami. Dzięki temu indeksy (procesy, role, encje) można generować z tagów, zamiast utrzymywać ręcznie:

---
title: Koszyki KSeF
description: Krótki, konkretny opis pod SEO i podgląd na liście.
navigation:
  icon: i-lucide-shopping-basket
aplikacje: [f1700]              # ID aplikacji APEX, których dotyczy strona
procesy: [przyjmowanie-faktur-ksef]   # slug(i) procesów, w których uczestniczy
encje: [KSEF_KOSZYK, FAKTURA_TRA]     # kluczowe tabele/obiekty
role: [fakturzysta, spedytor]   # persony, które tu pracują
---

Konwencja slugów: bez prefiksu numerycznego (numer steruje tylko kolejnością w nawigacji, nie URL-em). 4.analiza-szczegolowa/2.integracja-ksef.md → URL /analiza-szczegolowa/integracja-ksef.

Zalecenia techniczne dla Docusa

Automatyczne listy zamiast ręcznych spisów

Strona procesu (lub roli) nie wypisuje ręcznie powiązanych ekranów — listuje je z tagów przez queryCollection, więc duplikacja staje się technicznie niemożliwa:

<script setup lang="ts">
// Wszystkie strony oznaczone danym procesem
const route = useRoute()
const { data: powiazane } = await useAsyncData('proc-' + route.path, () =>
  queryCollection('content')
    .where('procesy', 'LIKE', '%przyjmowanie-faktur-ksef%')
    .select('title', 'path', 'description')
    .all()
)
</script>

Do czasu uzupełnienia tagów na istniejących stronach dopuszczalna jest lista ręczna — z komentarzem, że docelowo ma być generowana.

Komponenty MDC — prefiks u-

Wszystkie komponenty Nuxt UI w MDC wymagają prefiksu u- (::u-page-hero, :::u-page-feature, :::u-button). Bez prefiksu Vue ich nie rozwiąże.

Bloki treści — używaj spójnie

Diagram osadzamy przez prop code:

::mermaid
---
code: |
  flowchart TD
    A[Krok] --> B[Następny krok]
---
::

Linki — zawsze po slugu

Linkuj wewnętrznie po ścieżce slugowej (/katalog-modulow/faktury), nigdy po numerze. Dzięki temu przenumerowanie sekcji nie psuje odnośników.

Szablony stron

Strona procesu (orkiestracja, sekcja Procesy):

1. Lead: czego dotyczy proces + linki do stron-właścicieli (koncept, ekrany) + źródło (Confluence/Jira).
2. ::note wskazujący, gdzie żyją szczegóły (single source of truth).
3. Diagram ::mermaid całego przepływu.
4. Kroki procesu — orkiestracja z linkami (bez opisu pól).
5. Reguły decyzyjne / progi / statusy — to jest treść własna procesu.
6. „Co opisuje, a czego nie" — utrwalenie granicy.
7. Powiązania i źródła.

Strona modułu / ekranu (sekcja Katalog Modułów): frontmatter z tagami → po co → ekrany/pola/akcje → kluczowe obiekty (tabela) → powiązania (linki do procesów i konceptów).

Checklista przy dodawaniu strony

• Czy ten fakt nie jest już opisany gdzie indziej? Jeśli tak — linkuj, nie kopiuj.
• Czy strona ma poprawną oś (proces vs moduł/ekran vs koncept)?
• Uzupełniony frontmatter: title, description, navigation.icon oraz tagi (aplikacje, procesy, encje, role).
• Linki wewnętrzne po slugu, komponenty z prefiksem u-.
• Dodano odnośnik z/do stron sąsiednich (proces ↔ moduł ↔ koncept).