xingbiyun-afk/requirements-docs-viewer

Lese-Einstieg für Anforderungsdokumente (Viewer) in der Seite

Ziel

Bestehende Anforderungsdokumente aus dem Projekt in die Produktoberfläche integrieren, sodass Benutzer die entsprechenden Erläuterungen direkt auf der aktuellen Seite einsehen können; gleichzeitig sicherstellen, dass der Einstieg die Startseite nicht verlangsamt, keine historischen Inhalte preisgibt und interne Dokumente in der Produktion nicht versehentlich exponiert werden.

Abgrenzung zum Dokumentenschreiben

• Diese Skill ist nur für die Umsetzung des Lese-Einstiegs zuständig: Einstiegsposition, Dokumenten-Mapping, Build-Kopie, Rendering, Suche, Lazy Loading, Fehlerzustände, Produktions-Expositionsfläche, Tests und Durchsicht.
• Der Dokumenteninhalt wird von prd-rule-authoring oder einer anderen Quelle bereitgestellt; diese Skill legt nicht fest, wie Dokumente geschrieben werden müssen, und verlangt nicht, dass das Projekt prd-rule-authoring verwendet.
• Beide sind voneinander unabhängig: Projekte ohne Lese-Einstieg sollten dennoch Anforderungsdokumente produzieren; ein Lese-Einstieg ändert nicht die Schreibregeln für Dokumente.
• Die einzige Kopplung ist die „Dokumentenverzeichnis + Markdown-Konvention“: Pfade, Titel, rendergerechte Syntax. Die Konvention wird in der Projektkonfiguration festgelegt und nicht in der Skill hartcodiert.

Wann verwenden

• Produkt/Entwicklung/Test wünschen, „Regeln direkt auf der aktuellen Seite einzusehen“, um die Aufteilung des Bildschirms für MD-Dateien zu vermeiden;
• Es gibt bereits ein etabliertes System von Markdown-Anforderungsdokumenten, die schreibgeschützt angezeigt werden sollen;
• Interne Dokumente sollen in Lieferpräsentationen eingebunden werden, aber die Sichtbarkeit in der Produktion muss kontrolliert werden.

Nicht geeignet: Online-Bearbeitung/kollaborative Kommentare, Dokumenten-Genehmigungsworkflows, Volltextsuche als Service, abgestufte Leseberechtigungen (können später erweitert werden, sind nicht in der Minimalimplementierung enthalten).

Lesereihenfolge

Datei	Wann lesen
references/integration-design.md	Beim Design von Einstieg/Build/Mapping/Lazy Loading
references/rendering-and-search.md	Beim Rendern von eingeschränktem MD, Filterung historischer Kapitel, Suche
references/acceptance-checklist.md	Bei Tests, Durchsicht und Abnahme
references/ops-and-governance.md	Bei Produktions-Expositionsfläche, Dokumentenaktualisierung und Release-Prozess

Minimale Implementierungs-Checkliste

1. Einstieg: Nur auf Seiten mit Dokumenten-Mapping anzeigen; ohne Mapping nicht rendern (keine toten Schaltflächen hinterlassen); der Einstieg selbst lädt keine Dokumente.
2. Quelle: Dokumentenquelle ist Markdown (oder gleichwertige statische Dateien) im Repository; während des Builds in das Ausgabeverzeichnis kopieren; beim Build eine bidirektionale Validierung von Ausgabe ↔ Mapping durchführen (fehlende/verwaiste Dateien führen zu Build-Fehlern).
3. Mapping: Das Register Route/Seite → Dokumentenpfad ist die einzige Mapping-Quelle; der Dokumentenbaum wird nach Modulen gruppiert; modulebezogene Dokumente werden separat gekennzeichnet.
4. Laden: Dokument wird erst nach Öffnen des Drawer/Panels angefordert; erstmaliges Öffnen lädt das aktuelle Dokument; der Suchindex wird nach dem Öffnen im Leerlauf aufgebaut; keine Vorablade von Dokumenten beim Start.
5. Rendering: Eingeschränktes Markdown-Rendering (Überschriften/Absätze/Listen/Tabellen/Code/Zitate/Trennlinien/Links); vollständiges HTML-Escaping, nur Whitelist-Tags ausgeben; URL-Kodierung für Dateinamen mit chinesischen Zeichen/Klammern; Anpassung an Sub-Pfad-Deployment; Sicherung von Anker-Slugs gegen gefährliche HTML/URL-Zeichen (<>&"'), zentraler Ausgang für die Slug-Generierung (gemeinsam genutzt von Inhaltsverzeichnis/Text/Suche/Lokalisierung).
6. Reader-Regeln: Nur die neuesten Erläuterungen anzeigen – Kapitel „Änderungshistorie/Änderungsprotokoll“ (einschließlich ihres Inhalts) nicht rendern; Inhaltsverzeichnis und Suche synchron ausschließen; falls Quelldokumente historische Schnappschuss-Notizen enthalten, gemäß Projektkonvention filtern oder vom Dokumentenautor nicht schreiben lassen.
7. Interaktion: Klick im Inhaltsverzeichnis zur Positionierung, Aktionsseiten können standardmäßig zu einem Kapitel springen, globale Stichwortsuche (nach Dokument gruppiert, Treffer auf aktueller Seite zuoberst, Snippet ohne Markdown-Rauschen) und Sprung, Fehlerzustände und Wiederholung, Schließen. Suchkontextnavigation: Klick auf Treffer wechselt nur den Text, löscht nicht das Suchwort/die Ergebnisliste; behält die Scrollposition des Ergebnisbereichs; Treffer hervorheben (stabiler Key, mindestens Dokument + Anker + Titel, bei Bedarf Snippet zur Unterscheidung mehrerer Treffer im selben Kapitel); klarer „Suche leeren“-Eintrag zum Wiederherstellen des Dokumentenbaums; beim Öffnen eines Dokuments aus dem Dokumentenbaum die Suche leeren; Index nicht neu aufbauen. Rote Linie: Wenn das Inhaltsverzeichnis oben fixiert ist oder die expandierte Liste ständig über dem Text liegt, muss die Klick-Positionierung um die Überdeckungshöhe versetzt werden, um Abdeckung zu vermeiden; automatisierte Tests mit Abdeckungs-Assertion („toBeVisible“ prüft nicht auf Abdeckung). Details zu erweiterten Formen wie einklappbarem fixiertem Inhaltsverzeichnis und Scroll-Kompensation siehe references/integration-design.md §7.
8. Produktions-Expositionsfläche: Der Einstiegsschalter steuert nur die Schaltfläche, schützt nicht die statischen Dokumente; in der Produktion muss eine von zwei Optionen gewählt werden: Dokumentenverzeichnis aus dem Build ausschließen oder Dokumentenpfade mit Authentifizierung versehen (in die Produktionszugangskontrolle schreiben).
9. Tests: Mapping-Vollständigkeit, Konsistenz der Build-Artefakte, Nichtanzeige historischer Kapitel, Lazy Loading ohne Vorabladen, Suche und Sprung, Suchkontextbewahrung (Stichwort/Ergebnis/Scrollposition erhalten, aufeinanderfolgende Treffer, Leeren stellt Baum wieder her, Hervorhebung eindeutig, Index nicht neu aufbauen), Fehlerzustände; Inhaltsverzeichnis/Positionierung mit Abdeckungs-Assertion („toBeVisible“ prüft nicht auf Abdeckung); Scroll-Wiederherstellungs-Assertion toleriert Clamping, erfordert keine pixelgenaue absolute Gleichheit; sichtbare Browser-Durchsicht und Archivierung von Beweisen (Screenshots stimmen mit dem endgültigen Verhalten überein).

Grenzen

• Keine Änderung des Geschäftsseitenverhaltens, der Menü/Routen-Geschäftswerte oder der Mock-Daten; nur Hinzufügen des Lese-Einstiegs und der Dokumenten-Asset-Pipeline.
• Keine Einbindung von schweren Drittanbieter-MD-Rendering-Abhängigkeiten; Renderer eingeschränkt, testbar, escapbar.
• Keine „Dokumentenschreibkonvention“ in diese Skill aufnehmen; keine „Details zur Einstiegsimplementierung“ in die Dokumentenschreib-Skill aufnehmen.
• Echte Berechtigungen, Produktions-Deployment und Authentifizierungsmethode richten sich nach der Projektzugangskontrolle; Mock/Demo-Bestätigung ist kein Ersatz für Produktionsschutz.

Lieferumfang

Einstiegsposition und Sichtbarkeitsbedingung, Dokumentenquelle und Mapping, Build-Kopie und Validierung, Rendering und historische Filterung, Lazy Loading und Suche, Fehlerzustände, Behandlung der Produktions-Expositionsfläche, Tests und Durchsicht-Beweise, nicht abgedeckte Punkte.