{% extends 'workflows/base_shell.html' %}
{% load static %}

{% block title %}Project Wiki{% endblock %}



{% block extra_css %}
<link rel="stylesheet" href="{% static 'workflows/css/docs_pages.css' %}" />
{% endblock %}

{% block shell_body %}
      {% include 'workflows/includes/app_header.html' with header_show_home=1 header_inside_shell=1 %}
    <div class="page-stack">
    <div class="top">
      <h1>Project Wiki</h1>
    </div>
    <p class="sub">Operational and technical documentation for the Onboarding/Offboarding platform.</p>

    <div class="toc">
      <a href="#overview">Overview</a>
      <a href="#architecture">Architecture</a>
      <a href="#model">Data Model</a>
      <a href="#onboarding">Onboarding Flow</a>
      <a href="#offboarding">Offboarding Flow</a>
      <a href="#emails">Email Engine</a>
      <a href="#pdfs">PDF Engine</a>
      <a href="#integrations">Integrations</a>
      <a href="#admin">Admin Apps</a>
      <a href="#operations">Operations</a>
      <a href="#hardening">Hardening</a>
      <a href="#troubleshooting">Troubleshooting</a>
      <a href="#security">Security</a>
    </div>

    <h2 id="overview">1) Overview</h2>
    <div class="box">
      <p>
        This system handles employee onboarding and offboarding requests from web forms. It generates branded PDF documents,
        sends condition-based notifications, stores records in the database, and optionally uploads PDFs to Nextcloud.
      </p>
      <ul>
        <li>Primary users: regular staff (submit forms) and admin users (configure and operate).</li>
        <li>Main entry points: Home, Onboarding form, Offboarding form, Requests Dashboard, Admin Apps.</li>
        <li>Asynchronous processing: heavy tasks (PDF/email/upload) are executed by Celery worker jobs.</li>
      </ul>
    </div>

    <h2 id="architecture">2) Architecture</h2>
    <h3>Runtime Components</h3>
    <ul>
      <li><strong>Web:</strong> Django app served by Gunicorn</li>
      <li><strong>Worker:</strong> Celery worker for async processing</li>
      <li><strong>Broker:</strong> Redis (Celery queue)</li>
      <li><strong>DB:</strong> PostgreSQL</li>
      <li><strong>Email Sink (test):</strong> MailHog (when test mode is active)</li>
    </ul>

    <h3>Request Processing Pattern</h3>
    <ul>
      <li>User submits form in web UI.</li>
      <li>Form data is validated and stored as request object.</li>
      <li>Background task is queued with request ID.</li>
      <li>Worker generates PDF, sends notifications, uploads to Nextcloud (if enabled), and updates record.</li>
    </ul>

    <h2 id="model">3) Data Model (Key Entities)</h2>
    <ul>
      <li><code>OnboardingRequest</code>: onboarding data, generated PDF path, requester info, signature file/url, conditional fields.</li>
      <li><code>OffboardingRequest</code>: offboarding data, requester info, generated PDF path.</li>
      <li><code>EmployeeProfile</code>: searchable profile for offboarding prefill.</li>
      <li><code>WorkflowConfig</code>: routing emails, integration overrides, feature flags, welcome email delay.</li>
      <li><code>NotificationTemplate</code>: subject/body templates with placeholders.</li>
      <li><code>NotificationRule</code>: condition-based custom routing rules.</li>
      <li><code>FormFieldConfig</code> + <code>FormOption</code>: Form Builder configuration and selectable options.</li>
      <li><code>ScheduledWelcomeEmail</code>: delayed welcome email queue state.</li>
    </ul>

    <h2 id="onboarding">4) Onboarding Flow</h2>
    <ol>
      <li>User opens <code>/onboarding/new/</code> and completes multi-step form.</li>
      <li>Form saves request; requester identity is taken from logged-in user.</li>
      <li>Task <code>process_onboarding_request</code> runs in worker.</li>
      <li>PDF is generated using HTML template + letterhead overlay.</li>
      <li>Staff can additionally generate a separate <code>Einweisungs- und Übergabeprotokoll</code> from the Requests Dashboard for face-to-face employee introduction and sign-off.</li>
      <li>Staff can also open a simple live <code>Einweisung durchführen</code> page with real web checkboxes, notes, and draft/completed tracking.</li>
      <li>Default notification emails + optional rule-based emails are sent.</li>
      <li>Welcome email job is scheduled (configurable delay).</li>
      <li>PDF is uploaded to Nextcloud if enabled.</li>
    </ol>

    <h2 id="offboarding">5) Offboarding Flow</h2>
    <ol>
      <li>User opens <code>/offboarding/new/</code> and can search existing profile first.</li>
      <li>Form saves request with requester name/email from logged-in user.</li>
      <li>Task <code>process_offboarding_request</code> runs in worker.</li>
      <li>PDF is generated. If a previous onboarding request exists, the hardware section can be derived from that onboarding data.</li>
      <li>If no saved onboarding request exists for that person, the offboarding PDF automatically falls back to a manual onboarding reference sheet with grouped onboarding fields and printable checkbox lists.</li>
      <li>Notification emails are sent (default + rules).</li>
      <li>PDF upload to Nextcloud runs if enabled.</li>
    </ol>

    <h2 id="emails">6) Email Engine</h2>
    <h3>Modes</h3>
    <ul>
      <li><strong>Production mode:</strong> real recipients are used.</li>
      <li><strong>Test mode:</strong> recipients are redirected to test mailbox; original recipients are included in body.</li>
    </ul>

    <h3>Template Placeholders</h3>
    <p>Examples: <code>{{ VORNAME }}</code>, <code>{{ NACHNAME }}</code>, <code>{{ FULL_NAME }}</code>, <code>{{ EMAIL }}</code>, <code>{{ DEPARTMENT }}</code>, <code>{{ CONTRACT_START }}</code>.</p>

    <h3>Condition-based Rules</h3>
    <ul>
      <li>Configured in Admin Integrations page.</li>
      <li>Rule supports operators such as <code>always</code>, <code>equals</code>, <code>contains</code>, <code>is_true</code>, <code>is_false</code>.</li>
      <li>Can use template-based emails or custom subject/body.</li>
    </ul>

    <h2 id="pdfs">7) PDF Engine</h2>
    <ul>
      <li>Template source: <code>/backend/media/templates/onboarding_template.html</code> and <code>offboarding_template.html</code>.</li>
      <li>Additional onboarding intro template: <code>/backend/media/templates/onboarding_intro_template.html</code>.</li>
      <li>Letterhead defaults to <code>/backend/media/templates/templates.pdf</code>, but can be overridden from Admin Apps → <code>Branding</code>.</li>
      <li>Output folder: <code>/backend/media/pdfs/</code>.</li>
      <li>Fixed PDF labels and notes are rendered through task-level DE/EN text maps and follow the request language with German fallback.</li>
      <li>Signature images are embedded for compatibility with xhtml2pdf rendering.</li>
      <li>Conditional sections are hidden if no data is provided.</li>
      <li>Offboarding fallback behavior: if no onboarding record is available, the PDF renders a manual onboarding review layout grouped into <code>Stammdaten</code>, <code>Vertrag</code>, <code>IT-Setup</code>, and <code>Abschluss</code>, plus checkbox grids for devices, software, accesses, workspace groups, resources, and additional IT items.</li>
      <li>The onboarding intro PDF is a separate checklist-style document for live walkthroughs. It uses printable blank checkboxes and signature lines for both the employee and the trainer.</li>
      <li>The onboarding intro PDF can now use admin-configured checklist items from the dedicated <code>Einweisungs-Builder</code>. If no custom items are configured, the system falls back to built-in defaults.</li>
      <li>The live introduction page uses the same checklist structure as the intro PDF, so admins maintain one checklist definition and can use it both on screen and on paper.</li>
      <li>The live introduction page shows progress in percent and can generate a separate PDF export of the saved live checklist state.</li>
    </ul>

    <h2 id="integrations">8) Integrations</h2>
    <h3>Nextcloud</h3>
    <ul>
      <li>Configured from Admin Integrations UI (base URL, user, password, target directory).</li>
      <li>Can be globally enabled/disabled from Home Admin Apps.</li>
    </ul>

    <h3>Mail Server</h3>
    <ul>
      <li>SMTP host/port/account configured in Admin Integrations UI / backend config.</li>
      <li>Use SMTP test action before switching to production mode.</li>
    </ul>

    <h2 id="bilingual">8b) Bilingual Core UI</h2>
    <ul>
      <li><strong>Current scope:</strong> the core user interface supports German and English switching for the main fixed UI pages.</li>
      <li><strong>Covered now:</strong> login, home, requests dashboard, onboarding form shell, offboarding form shell, common status/messages in views, and the main admin-tool labels/buttons for builders, integrations, welcome emails, and the handbook hub.</li>
      <li><strong>Phase 2 added:</strong> dynamic Form Builder option labels, field label/help-text overrides, and intro-builder checklist item labels now support German and English values.</li>
      <li><strong>Email phase added:</strong> admin-managed notification template subject/body content, notification rule custom subject/body content, and welcome email subject/body content now support explicit DE/EN values.</li>
      <li><strong>Runtime selection:</strong> onboarding and offboarding requests store the UI language at submission time, and notification delivery uses that language with German fallback.</li>
      <li><strong>Stability hardening:</strong> request models normalize <code>preferred_language</code> on save, and the database schema also enforces a default of <code>de</code>. This prevents null-language inserts outside the main form/view path.</li>
      <li><strong>PDF phase added:</strong> fixed PDF headings, labels, notes, and confirmation text now render in German or English based on the request language, with German as the fallback.</li>
      <li><strong>Editing path:</strong> these DE/EN values are maintained directly in the frontend builder pages, not only in Django admin.</li>
      <li><strong>Not fully bilingual yet:</strong> the main remaining gaps are long-form handbook/wiki copy and a few secondary admin/help texts.</li>
      <li><strong>Smoke coverage:</strong> automated tests now verify DE/EN request language capture and English email-template selection for onboarding and welcome email flows.</li>
      <li><strong>Implementation:</strong> Django i18n with locale middleware, translation catalogs, and a DE/EN language switch in the main UI.</li>
    </ul>

    <h3>Translation Workflow</h3>
    <ul>
      <li>The long-term translation path uses Django's standard <code>makemessages</code> and <code>compilemessages</code> workflow.</li>
      <li><code>gettext</code> is installed in the Docker image so translations can be compiled inside the running container.</li>
      <li>Translation catalogs live under <code>/backend/locale/</code>.</li>
      <li>A root <code>Makefile</code> provides repeatable local commands for updating and compiling translations.</li>
      <li>CI validates translation compilation on push and pull request via <code>.github/workflows/i18n.yml</code>.</li>
      <li>The earlier ad hoc Python-based <code>.mo</code> compilation path should no longer be used for ongoing maintenance.</li>
    </ul>

    <h2 id="admin">9) Admin Apps (Home)</h2>
    <ul>
      <li><strong>Rollenmodell:</strong> the app now uses four named roles: <code>Super Admin</code>, <code>Admin</code>, <code>IT Staff</code>, and <code>Staff</code>.</li>
      <li><strong>Zugriffslogik:</strong> page visibility and critical actions are controlled by capability checks, not only by <code>is_staff</code>.</li>
      <li><strong>Fallback-Verhalten:</strong> legacy staff users without an explicit role group currently fall back to <code>Admin</code> access so existing operations do not break during rollout.</li>
      <li><strong>Form Builder:</strong> manage field visibility/order/options.</li>
      <li><strong>Einweisungs-Builder:</strong> manage custom checklist items for the intro PDF and live introduction checklist, including section, visibility, and conditional display logic.</li>
      <li><strong>Integrations:</strong> Nextcloud, SMTP, default routing addresses, notification rules, workflow rules, and remote backup target settings.</li>
      <li><strong>Branding:</strong> portal title, company name, company domain, support email, sender display name, logo, favicon, default language, PDF letterhead, footer/legal text, and basic brand colors.</li>
      <li><strong>App Registry:</strong> platform-level registry for enabling, ordering, relabeling, and role-targeting landing-page apps without editing the home template.</li>
      <li><strong>Trial Management:</strong> platform-only control surface for trial runtime, expiry, shell banner, and safe demo restrictions.</li>
      <li><strong>Benutzer &amp; Rollen:</strong> super-admin-only page for creating users, assigning roles, activating/deactivating access, sending access or password-reset links by email, and deleting accounts when appropriate.</li>
      <li><strong>Welcome Emails:</strong> scheduled jobs, pause/resume/cancel/trigger now.</li>
      <li><strong>Audit Log:</strong> staff-only trace of important admin changes such as builder edits, settings updates, PDF generation, welcome-email operations, and request deletions. Supports filtering by action, user, and date range.</li>
      <li><strong>Requests Dashboard:</strong> search records, open PDFs, delete records (single/bulk for staff).</li>
      <li><strong>Request Status & Retry:</strong> onboarding and offboarding requests now carry explicit processing state (<code>submitted</code>, <code>processing</code>, <code>completed</code>, <code>failed</code>). Failed requests expose the last error and can be retried from the dashboard.</li>
      <li><strong>Einweisungs- und Übergabeprotokoll:</strong> staff-only <code>PDF erzeugen</code>, <code>Neu erzeugen</code>, and <code>PDF öffnen</code> actions directly on onboarding rows in the Requests Dashboard.</li>
      <li><strong>Einweisung durchführen:</strong> staff-only live checklist page opened from onboarding rows, with draft/completed status, notes, progress tracking, and a separate live-status PDF export.</li>
      <li><strong>Project Wiki:</strong> this documentation page.</li>
      <li><strong>UI Shell Standard:</strong> interactive app pages should extend <code>base_shell.html</code>; PDF templates under <code>backend/media/templates/</code> must stay separate.</li>
      <li><strong>Release Checklist:</strong> dedicated staff-only release runbook for validation, rollout evidence, and rollback basics.</li>
    </ul>

    <h2 id="operations">10) Operations Runbook</h2>
    <h3>Health Checks</h3>
    <ul>
      <li>App endpoint: <code>/healthz/</code></li>
      <li>If <code>db=error</code>, verify DB container and connection settings.</li>
    </ul>

    <h3>Where to Find Generated PDFs</h3>
    <ul>
      <li>Container path: <code>/app/media/pdfs/</code></li>
      <li>Host path: project <code>backend/media/pdfs/</code> via mounted volume.</li>
      <li>Backup standard: create DB+media bundles under <code>backups/</code> and verify them with a temporary restore before using a real restore.</li>
      <li>Staff UI shortcut: Admin Apps → <code>Backup &amp; Recovery</code> for create, verify, and delete actions.</li>
      <li>Each backup row shows both local bundle availability and remote backup state.</li>
      <li>The backup page also shows whether the latest verification is current, stale, missing, or still pending.</li>
      <li>Remote backup target configuration lives under Admin Apps → <code>Integrationen</code> → <code>Backup-Ziel</code>.</li>
      <li>Nextcloud remote backups must use a separate backup directory, not the normal onboarding/offboarding document directory.</li>
      <li>Longer-running admin actions such as backup create/verify and integration tests use the same shared progress overlay after confirmation.</li>
      <li>For scheduled verification outside the browser, run:
        <pre><code>docker compose exec -T web python manage.py verify_latest_backup --create-if-missing</code></pre>
      </li>
      <li>Brand assets such as logo and PDF letterhead are managed separately under Admin Apps → <code>Branding</code>.</li>
      <li>Trial deployments can force safe integration behavior: Nextcloud is treated as disabled and email remains in test mode while the trial restriction is active.</li>
      <li>Expired trials should be cleaned with the dedicated command, not from the browser:
        <pre><code>docker compose exec -T web python manage.py cleanup_expired_trial_workspace --yes-delete</code></pre>
      </li>
    </ul>

    <h3>Deployment Notes</h3>
    <ul>
      <li>Use Docker Compose for web + worker + db + redis services.</li>
      <li>After template/form/task changes, restart web and worker containers.</li>
      <li>Run <code>python manage.py check</code> before release.</li>
      <li>On a fresh database, the web container boot sequence now runs <code>python manage.py bootstrap_initial_users</code> right after migrations.</li>
      <li>After adding or editing intro checklist items, regenerate the intro PDF from the Requests Dashboard to reflect the updated checklist.</li>
    </ul>

    <h3>Initial Bootstrap Users</h3>
    <ul>
      <li>Admin test user: <code>admin_test</code> / <code>admin12345</code></li>
      <li>Normal test user: <code>user_test</code> / <code>user12345</code></li>
      <li>The bootstrap step only creates these accounts when the user table is empty, so later restarts do not overwrite real users.</li>
    </ul>

    <h2 id="hardening">11) Security & Reliability Hardening (Current)</h2>
    <ul>
      <li><strong>Rollen &amp; Berechtigungen:</strong> operational areas such as Integrationen, Builders, Audit Log, Backup &amp; Recovery, request delete/retry, and intro-session actions are now protected by capability-based role checks.</li>
      <li><strong>Cookie + header hardening:</strong> HTTPOnly cookies, SameSite cookies, <code>X-Content-Type-Options: nosniff</code>, stricter referrer policy, and frame protection.</li>
      <li><strong>Optional secure-cookie mode:</strong> can be enabled via environment for HTTPS deployments.</li>
      <li><strong>Upload guards:</strong> server-side upload size limits plus signature image magic-byte validation for PNG/JPEG.</li>
      <li><strong>SMTP reliability:</strong> explicit SMTP timeout to avoid hanging worker/web on mail network issues.</li>
      <li><strong>Nextcloud reliability:</strong> retry/backoff on upload errors, bounded timeouts, and graceful failure return instead of crashing flow.</li>
      <li><strong>Filename safety:</strong> PDF filenames are sanitized to safe filesystem characters.</li>
      <li><strong>Least privilege runtime:</strong> web and worker containers run as non-root <code>app</code> user.</li>
      <li><strong>Dependency stability:</strong> the Docker image pins <code>chardet==5.2.0</code> so <code>requests</code> runs without compatibility warnings alongside ReportLab.</li>
    </ul>
    <div class="note">
      Recommended for production: set secure cookies, explicit allowed hosts, CSRF trusted origins, and a strong secret key via environment variables.
    </div>

    <h2 id="troubleshooting">12) Troubleshooting</h2>
    <div class="box">
      <h3>Browser timeout or page hangs</h3>
      <ul>
        <li>Try <code>http://127.0.0.1:8088/</code> instead of <code>localhost</code> if local DNS/proxy is unstable.</li>
        <li>Check <code>/healthz/</code> and web logs.</li>
      </ul>

      <h3>Onboarding submit does nothing</h3>
      <ul>
        <li>Check required/hidden conditional fields and form errors.</li>
        <li>Open browser dev tools for JS errors.</li>
      </ul>

      <h3>PDF not generated</h3>
      <ul>
        <li>Check Celery worker logs for PDF task errors.</li>
        <li>Verify template files exist and media folder permissions are correct.</li>
      </ul>

      <h3>Email not received</h3>
      <ul>
        <li>Verify email mode (test vs production).</li>
        <li>Run SMTP test from Admin Apps.</li>
        <li>Check SMTP settings and worker logs.</li>
      </ul>

      <h3>Login fails after fresh stack start</h3>
      <ul>
        <li>The system should bootstrap the initial users automatically after migrations on an empty database.</li>
        <li>If login still fails, inspect web logs for <code>bootstrap_initial_users</code> and confirm the database volume was initialized correctly.</li>
      </ul>

      <h3>Nextcloud upload missing</h3>
      <ul>
        <li>Verify Nextcloud is enabled.</li>
        <li>Test upload from Admin Apps.</li>
        <li>Check credentials and destination directory path.</li>
      </ul>
    </div>

    <h2 id="security">13) Security and Access Notes</h2>
    <ul>
      <li>Do not expose secrets in UI screenshots or logs.</li>
      <li>Only staff users should access Admin Apps and this wiki page.</li>
      <li>Use environment variables and admin overrides carefully in production.</li>
      <li>Prefer production SMTP only after successful test-mode verification.</li>
    </ul>

    <div class="note">
      Last updated for current system behavior as of March 19, 2026.
    </div>
    </div>
  
{% endblock %}