Zum Hauptinhalt springen
Diese Seite behandelt Entwicklungskonventionen und Code-Qualitätsstandards. Für den vollständigen Beitragsleitfaden – einschließlich des Pioneer Program, Feldtests, PR-Prozess und Community-Links – siehe CONTRIBUTING.md auf GitHub.

​
Einrichtung

Voraussetzungen: Python 3.11+, uv, Node.js 18+, pnpm. 
git clone https://github.com/fim-ai/fim-one.git && cd fim-one
cp example.env .env                        # LLM_API_KEY is optional for contributors
uv sync --all-extras                       # Python dependencies
cd frontend && pnpm install && cd ..       # frontend dependencies
bash scripts/setup-hooks.sh                # pre-commit hooks (required)
LLM_API_KEY ist nur erforderlich, um das Backend lokal auszuführen oder eine automatisch übersetzte Locale-Ausgabe bei Commit in der Vorschau anzuzeigen. Mitwirkende ohne einen Schlüssel können weiterhin EN-Änderungen committen — ein GitHub Actions-Workflow übersetzt nach dem PR-Merge auf master. Siehe i18n unten.
Überprüfen Sie, dass alles funktioniert: 
uv run pytest tests/ -x -q                # tests
uv run mypy src/fim_one/                   # type check
uv run ruff check src/                     # lint
cd frontend && pnpm build && cd ..         # frontend build

​
Typsicherheit

mypy strict mode ist erzwungen. Die gesamte Codebasis besteht ohne Fehler, und der Pre-Commit-Hook führt mypy auf jeder gestaffelten .py-Datei mit vollständiger Import-Chain-Überprüfung aus. Regeln:
  • Typ-Hinweise erforderlich auf allen öffentlichen Funktionen.
  • Kein # type: ignore außer für import-untyped (Bibliotheken von Drittanbietern ohne Stubs).
  • Verwenden Sie from __future__ import annotations für Forward References.
  • Beheben Sie die tatsächlichen Typen – unterdrücken Sie niemals Fehler, um CI zu bestehen.

​
Testen

Jedes neue Modul muss eine entsprechende Testdatei haben. Jeder Feature-Commit muss Tests enthalten.
KonventionMuster
Dateitests/test_{module}.py
KlasseTest{Feature}
Methodetest_{behavior_under_test}
Regeln:
  • Alle vorhandenen Tests müssen vor dem Commit erfolgreich sein: uv run pytest tests/ -x -q.
  • Tests dürfen nicht von externen Diensten abhängen — mocken Sie Datenbanken, MCP-Server, HTTP-Endpunkte und LLM-Aufrufe mit unittest.mock / AsyncMock.
  • Führen Sie Tests mit Coverage aus: uv run pytest --cov=fim_one.

​
Code-Stil

  • Async-first. Verwenden Sie async def für I/O-gebundene Operationen. Wrappen Sie synchrone Aufrufe mit asyncio.to_thread() anstatt den Event Loop zu blockieren.
  • Ruff zum Linting. uv run ruff check src/ — Zeilenlänge beträgt 100 Zeichen.
  • Minimale __init__.py Exporte. Exportieren Sie nur die öffentliche API; halten Sie interne Symbole privat.
  • Paketmanager. uv für Python, pnpm für Frontend. Verwenden Sie niemals pip oder npm.

​
Git-Konventionen

Atomare Commits. Eine logische Änderung pro Commit. Teilen Sie unabhängige Änderungen auf, auch wenn sie zusammen entwickelt wurden. Commit-Nachrichtenformat: type: description
TypeWann zu verwenden
featNeue benutzergerichtete Funktion
fixFehlerbehebung
refactorCode-Umstrukturierung ohne Verhaltensänderung
docsNur Dokumentation
testTests hinzufügen oder aktualisieren
choreBuild, CI, Abhängigkeitsaktualisierungen
Hooks niemals überspringen mit --no-verify. Die Pre-Commit-Pipeline existiert, um Fehler zu erkennen, bevor sie das Repository erreichen.

​
Pre-commit Hook-Pipeline

Der Hook wird bei jedem Commit automatisch ausgeführt. Er verarbeitet nur gestaffelte Dateien, die für jeden Schritt relevant sind – wenn Sie nur Python-Dateien geändert haben, wird der i18n-Schritt übersprungen und umgekehrt.
ReihenfolgeSchrittAuslöserFunktion
0Locale-Edit-SchutzAlle gestaffelten Dateien unter messages/{locale}/, docs/{locale}/ oder README.{locale}.mdBricht den Commit ab – kein Override möglich. Beheben Sie Übersetzungen über scripts/translation-glossary.md.
1OpenAPI-Spec-Regenerationsrc/fim_one/web/**/*.py geändertExportiert docs/openapi.json neu aus FastAPI-Routen
2i18n-Übersetzungmessages/en/*.json, docs/*.mdx oder README.md geändert (benötigt lokalen LLM_API_KEY, sonst wird es nach dem Merge von CI verarbeitet)Übersetzt neue/geänderte Schlüssel in alle Zielsprachen
3mypy-TypprüfungBeliebige src/fim_one/**/*.py geändertFührt mypy mit vollständiger Import-Kette auf gestaffelten Dateien aus
4MDX-ValidierungBeliebige .mdx-Datei gestaffeltValidiert JSX/MDX-Syntax, bevor sie Mintlify erreicht
Wenn ein Schritt fehlschlägt, wird der Commit abgebrochen. Beheben Sie die gemeldeten Fehler und versuchen Sie es erneut.

​
i18n

FIM One unterstützt 6 Sprachen (EN, ZH, JA, KO, DE, FR). Übersetzungen sind vollständig automatisiert. Bearbeiten Sie nur englische Quelldateien:
  • frontend/messages/en/{namespace}.json — UI-Strings
  • docs/*.mdx (Stammebene, nicht in Locale-Unterverzeichnissen) — Dokumentation
  • README.md — Projekt-Readme
Andere Locale-Dateien (messages/zh/, docs/zh/, README.zh.md usw.) werden automatisch generiert und der Pre-Commit-Hook lehnt Commits ab, die diese manuell bearbeiten. Um eine Fehlübersetzung zu beheben, bearbeiten Sie scripts/translation-glossary.md — die in jeden Übersetzungs-Prompt injizierte Single Source of Truth für jede Übersetzungsregel — und generieren Sie dann betroffene Dateien mit uv run scripts/translate.py --files <en-sources> --force neu. Jede Glossar-Korrektur gilt dauerhaft für alle fünf Sprachen. Zwei Wege zur Generierung von Locale-Dateien:
  1. Lokaler Pre-Commit-Hook — wird ausgeführt, wenn LLM_API_KEY in .env gesetzt ist. Die Übersetzung erfolgt vor dem Push, sodass Sie die Ausgabe in der Vorschau anzeigen können.
  2. CI-Fallback — wenn der lokale Hook keinen Schlüssel hatte und übersprungen wurde, übersetzt .github/workflows/i18n-sync.yml nach dem Merge auf master und committed das Ergebnis automatisch.
Mitwirkende ohne API-Schlüssel können EN-Änderungen frei committen — der CI-Pfad stellt sicher, dass Locales korrekt landen. Neuen i18n-Namespace hinzufügen: Erstellen Sie messages/en/{ns}.json — andere Locale-Dateien werden beim nächsten Commit oder nach dem Merge auf CI generiert. Vollständige Neuübersetzung erzwingen: uv run scripts/translate.py --all (erfordert lokalen LLM_API_KEY).

​
Datenbankmigrationen

Dev verwendet SQLite, Produktion verwendet PostgreSQL. Ein Satz von Alembic-Migrationsdateien muss auf beiden funktionieren. Wichtige Regeln:
  • Jedes neue ORM-Modell oder jede neue Spalte muss eine Migration haben — verlassen Sie sich niemals auf metadata.create_all().
  • Alle Migrationen müssen idempotent sein — verwenden Sie Hilfsfunktionen aus fim_one.migrations.helpers (table_exists, table_has_column, index_exists).
  • Boolean-Standardwerte: server_default=sa.text("FALSE") / sa.text("TRUE"). Niemals "0" / "1" — PostgreSQL lehnt Integer-Literale für Boolean-Spalten ab.
  • SQLite kann ALTER COLUMN nicht ausführen — verwenden Sie op.batch_alter_table() für Änderungen an Spaltenbeschränkungen.
  • Nach dem Schreiben einer Migration führen Sie sofort uv run alembic upgrade head aus, um sie anzuwenden.

​
Kurzreferenz

# Development
./start.sh dev                            # hot reload (Python + Next.js HMR)
./start.sh dev:api                        # API only, dev mode (hot reload)
./start.sh dev:ui                         # Frontend only, dev mode (HMR)
./start.sh api                            # FastAPI only (headless)

# Quality checks
uv run pytest tests/ -x -q               # tests (stop on first failure)
uv run pytest --cov=fim_one              # tests with coverage
uv run mypy src/fim_one/                  # type check
uv run ruff check src/                    # lint

# i18n
uv run scripts/translate.py --all         # force full retranslation

# Database
uv run alembic upgrade head               # apply migrations
uv run alembic revision -m "description"  # create new migration