Phase 3, erster Teil: Vorlagen-Bausteine und Schwärzung

Entschieden und festgehalten: jede Akte trägt Kurzvermerke und Dokumente, die Fallakte zusätzlich ihre Abschnitte. Die Trennung aus docs/05 bleibt damit bestehen. Eine Vorlage ist jetzt eine geordnete Liste von Bausteinen. Manche nehmen eine Eingabe entgegen, andere liefern festen Text mit Platzhaltern. Damit tragen dieselbe Struktur ein Vorfallsbericht, der fast nur aus Eingaben besteht, und ein Sonderarbeitsvertrag, der fast nur aus Paragraphen und Unterschriftenzeilen besteht. Eine neue Dokumentart bleibt ein Datensatz, kein Deployment. Der Schwärzungs-Parser gibt Segmente zurück, nicht den vollen Text mit einem Sichtbarkeits-Flag: was der Client ausblenden müsste, hat er dann schon. Die Balkenlänge wird auf ein Raster von acht Zeichen gerundet, sonst verrät sie, wie lang der geschwärzte Name war. Ein Test vergleicht den TypeScript-Parser gegen die SQL-Funktion strip_redactions aus der Migration. Laufen die beiden auseinander, findet die Suche einen Begriff, den die Ansicht verbirgt — und der Treffer allein verrät ihn dann.
2026-09-02 12:39:35 +02:00
parent cf4321a3bd
commit 4da89fcf1c
4 changed files with 388 additions and 0 deletions
@@ -0,0 +1,113 @@
+/**
+ * Schwärzung im Freitext.
+ *
+ * Im Editor markiert man einen Bereich und wählt eine Stufe. Gespeichert wird
+ * als Auszeichnung:
+ *
+ *   Der Hinweis kam von [[c4]]Wachmann Perreira, Sektor B[[/c4]] am 27.08.
+ *
+ * Der Server ersetzt den Inhalt für niedrigere Stufen. **Der echte Wert
+ * verlässt den Server nicht** — deshalb gibt diese Datei Segmente zurück und
+ * nicht etwa den vollen Text mit einem Sichtbarkeits-Flag. Was der Client
+ * ausblenden müsste, hat er schon.
+ *
+ * Die Länge wird auf ein festes Raster gerundet. Ein Balken exakter Länge
+ * verriete sonst, wie lang der Name war, und bei kurzen Einschüben ist das
+ * genug, um zu raten. Siehe docs/05-akten-und-vorlagen.md.
+ */
+
+/** Auf dieses Vielfache wird die Länge eines Balkens gerundet. */
+const LENGTH_GRID = 8
+
+const MARKUP = /\[\[c([0-5])\]\]([\s\S]*?)\[\[\/c\1\]\]/g
+
+export type Segment =
+  | { kind: 'text'; text: string }
+  | { kind: 'redacted'; requiredLevel: number; blockLength: number }
+
+/** Auf das Raster gerundete Länge, mindestens ein Block. */
+export function barLength(rawLength: number): number {
+  return Math.max(LENGTH_GRID, Math.ceil(rawLength / LENGTH_GRID) * LENGTH_GRID)
+}
+
+/**
+ * Zerlegt einen Text in Segmente und wendet dabei die Stufe des Lesers an.
+ * Bereiche über seiner Stufe kommen ohne ihren Inhalt zurück.
+ */
+export function redactForLevel(source: string, viewerLevel: number): Segment[] {
+  const segments: Segment[] = []
+  let cursor = 0
+
+  MARKUP.lastIndex = 0
+  let match: RegExpExecArray | null
+  while ((match = MARKUP.exec(source)) !== null) {
+    if (match.index > cursor) {
+      segments.push({ kind: 'text', text: source.slice(cursor, match.index) })
+    }
+
+    const requiredLevel = Number(match[1])
+    const content = match[2] ?? ''
+
+    if (viewerLevel >= requiredLevel) {
+      segments.push({ kind: 'text', text: content })
+    } else {
+      segments.push({
+        kind: 'redacted',
+        requiredLevel,
+        blockLength: barLength(content.length),
+      })
+    }
+
+    cursor = match.index + match[0].length
+  }
+
+  if (cursor < source.length) {
+    segments.push({ kind: 'text', text: source.slice(cursor) })
+  }
+
+  return segments
+}
+
+/**
+ * Die höchste Stufe, die in einem Text ausgezeichnet ist. Damit lässt sich an
+ * einem Eintrag anzeigen, dass er geschwärzte Stellen enthält, ohne den Text
+ * zu übertragen.
+ */
+export function highestRedactionLevel(source: string): number {
+  let highest = 0
+  MARKUP.lastIndex = 0
+  let match: RegExpExecArray | null
+  while ((match = MARKUP.exec(source)) !== null) {
+    highest = Math.max(highest, Number(match[1]))
+  }
+  return highest
+}
+
+/**
+ * Entfernt die Auszeichnung, behält den Inhalt. Für Leser, die alles sehen
+ * dürfen, und für den Volltextindex hoher Stufen.
+ */
+export function stripMarkup(source: string): string {
+  return source.replace(MARKUP, (_full, _level, content: string) => content)
+}
+
+/**
+ * Entfernt ausgezeichnete Bereiche samt Inhalt. Genau das tut auch die
+ * Funktion `strip_redactions` in der Migration, bevor der Suchvektor gefüllt
+ * wird — beide müssen dasselbe Ergebnis liefern.
+ */
+export function stripRedacted(source: string): string {
+  return source.replace(MARKUP, ' ')
+}
+
+/** Fügt eine Auszeichnung um einen markierten Bereich ein. */
+export function markRedaction(source: string, start: number, end: number, level: number): string {
+  if (start >= end || level < 0 || level > 5) return source
+  return (
+    source.slice(0, start) +
+    `[[c${level}]]` +
+    source.slice(start, end) +
+    `[[/c${level}]]` +
+    source.slice(end)
+  )
+}
@@ -0,0 +1,129 @@
+import { z } from 'zod'
+
+/**
+ * Bausteine einer Vorlage.
+ *
+ * Eine Vorlage ist eine **geordnete Liste von Bausteinen**. Manche nehmen eine
+ * Eingabe entgegen, andere liefern festen Text. Damit tragen dieselbe Struktur
+ * ein Vorfallsbericht (fast nur Eingaben) und ein Sonderarbeitsvertrag (fast
+ * nur fester Text mit ein paar Platzhaltern).
+ *
+ * Eine neue Dokumentart ist damit ein Datensatz, kein Deployment.
+ * Siehe docs/05-akten-und-vorlagen.md und docs/13-entscheidungen.md.
+ */
+
+/** Bausteine, die der Nutzer ausfüllt. Ihr Wert landet in einem Abschnitt. */
+export const INPUT_TYPES = [
+  'shorttext',
+  'longtext',
+  'select',
+  'multiselect',
+  'date',
+  'person',
+  'number',
+  'checklist',
+  'table',
+] as const
+
+/** Bausteine, die aus der Vorlage kommen und nicht ausgefüllt werden. */
+export const STATIC_TYPES = ['heading', 'paragraph', 'signature', 'pagebreak'] as const
+
+export type InputType = (typeof INPUT_TYPES)[number]
+export type StaticType = (typeof STATIC_TYPES)[number]
+
+const key = z
+  .string()
+  .min(1)
+  .max(64)
+  // Der Schlüssel ist stabil und wird nie geändert: ein Abschnitt findet über
+  // ihn seinen Baustein wieder, auch über Vorlagenversionen hinweg.
+  .regex(/^[a-z][a-z0-9_]*$/, 'Kleinbuchstaben, Ziffern und Unterstrich')
+
+const gemeinsam = {
+  key,
+  label: z.string().min(1).max(200),
+  help: z.string().max(500).optional(),
+  /** Feld erst ab dieser Stufe sichtbar, siehe docs/05-akten-und-vorlagen.md. */
+  minClearance: z.number().int().min(0).max(5).optional(),
+}
+
+const inputField = z.object({
+  ...gemeinsam,
+  type: z.enum(INPUT_TYPES),
+  required: z.boolean().optional(),
+  /** Blockiert den Abschluss des Falls, solange leer. */
+  requiredToClose: z.boolean().optional(),
+  /** Für select und multiselect. */
+  options: z.array(z.string().min(1)).optional(),
+  /** Für table: die Spaltenüberschriften. */
+  columns: z.array(z.string().min(1)).optional(),
+})
+
+const staticBlock = z.object({
+  ...gemeinsam,
+  type: z.enum(STATIC_TYPES),
+  /**
+   * Fester Text des Bausteins. Platzhalter in geschweiften Klammern werden
+   * beim Rendern durch Werte ersetzt: `{{name}}` zieht den Wert des
+   * Bausteins mit dem Schlüssel `name`.
+   */
+  text: z.string().max(20_000).optional(),
+})
+
+export const templateFieldSchema = z.union([inputField, staticBlock])
+export const templateFieldsSchema = z
+  .array(templateFieldSchema)
+  .max(200)
+  .superRefine((fields, ctx) => {
+    const seen = new Set<string>()
+    for (const [index, field] of fields.entries()) {
+      if (seen.has(field.key)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [index, 'key'],
+          message: `Schlüssel doppelt vergeben: ${field.key}`,
+        })
+      }
+      seen.add(field.key)
+
+      if (
+        (field.type === 'select' || field.type === 'multiselect') &&
+        (!('options' in field) || !field.options?.length)
+      ) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [index, 'options'],
+          message: 'Auswahlfelder brauchen mindestens eine Option',
+        })
+      }
+    }
+  })
+
+export type TemplateField = z.infer<typeof templateFieldSchema>
+export type InputField = z.infer<typeof inputField>
+
+export function isInputField(field: TemplateField): field is InputField {
+  return (INPUT_TYPES as readonly string[]).includes(field.type)
+}
+
+/** Platzhalter `{{schlüssel}}` in einem festen Textbaustein. */
+export const PLACEHOLDER = /\{\{\s*([a-z][a-z0-9_]*)\s*\}\}/g
+
+export function fillPlaceholders(
+  text: string,
+  values: Record<string, unknown>,
+  fallback = (key: string) => `[${key}]`,
+): string {
+  return text.replace(PLACEHOLDER, (_match, name: string) => {
+    const value = values[name]
+    if (value === undefined || value === null || value === '') return fallback(name)
+    return Array.isArray(value) ? value.join(', ') : String(value)
+  })
+}
+
+/** Die Bausteine, die vor dem Abschluss eines Falls gefüllt sein müssen. */
+export function requiredToCloseKeys(fields: TemplateField[]): string[] {
+  return fields
+    .filter((field): field is InputField => isInputField(field) && field.requiredToClose === true)
+    .map((field) => field.key)
+}