OmniRoute/docs/i18n/cs/CONTRIBUTING.md

Přispívání k OmniRoute

Děkujeme za váš zájem o přispění! Tato příručka obsahuje vše, co potřebujete k zahájení.

---

Nastavení vývoje

Předpoklady

• Node.js 20+ (doporučeno: 22 LTS)
• npm 10+
• Git

Klonovat a instalovat

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm install

Proměnné prostředí

# Create your .env from the template
cp .env.example .env

# Generate required secrets
echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env
echo "API_KEY_SECRET=$(openssl rand -hex 32)" >> .env

Klíčové proměnné pro vývoj:

Proměnná	Výchozí nastavení pro vývoj	Popis
PORT	3000	Port serveru
NEXT_PUBLIC_BASE_URL	http://localhost:3000	Základní URL pro frontend
JWT_SECRET	(vygenerovat výše)	Tajemství podpisu JWT
INITIAL_PASSWORD	123456	První přihlašovací heslo
ENABLE_REQUEST_LOGS	false	Povolit protokoly požadavků na ladění

Spuštěno lokálně

# Development mode (hot reload)
npm run dev

# Production build
npm run build
npm run start

# Common port configuration
PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev

Výchozí adresy URL:

• Dashboard : http://localhost:3000/dashboard
• API : http://localhost:3000/v1

---

Pracovní postup Gitu

⚠️ NIKDY se necommitujte přímo do main . Vždy používejte větve feature.

git checkout -b feat/your-feature-name
# ... make changes ...
git commit -m "feat: describe your change"
git push -u origin feat/your-feature-name
# Open a Pull Request on GitHub

Pojmenování poboček

Předpona	Účel
feat/	Nové funkce
fix/	Opravy chyb
refactor/	Restrukturalizace kódu
docs/	Změny dokumentace
test/	Doplnění/opravy testů
chore/	Nástroje, CI, závislosti

Zprávy o potvrzení

Postupujte podle konvenčních commitů :

feat: add circuit breaker for provider calls
fix: resolve JWT secret validation edge case
docs: update SECURITY.md with PII protection
test: add observability unit tests
refactor(db): consolidate rate limit tables

Rozsahy: db , sse , oauth , dashboard , api , cli , docker , ci .

---

Spouštění testů

# All unit tests
npm test
npm run test:unit

# Specific test suites
npm run test:security     # Security tests
npm run test:fixes        # Fix verification tests

# With coverage
npm run test:coverage

# E2E tests (requires Playwright)
npm run test:e2e

# Lint + format check
npm run lint
npm run check

Aktuální stav testování: 368+ jednotkových testů zahrnujících:

• Poskytovatelé překladů a konverze formátů
• Omezení rychlosti, jistič a odolnost
• Sémantická mezipaměť, idempotence, sledování průběhu
• Databázové operace a schéma
• Toky a ověřování OAuth
• Ověření koncového bodu API

---

Styl kódu

• ESLint — Spustí npm run lint před commitem
• Hezčí – Automaticky naformátováno pomocí lint-staged při commitu
• TypeScript — Veškerý kód src/ používá .ts / .tsx ; dokument s TSDoc ( @param , @returns , @throws )
• No eval() — ESLint vynucuje no-eval , no-implied-eval , no-new-func
• Ověření Zod — Použití schémat Zod pro ověřování vstupu API

---

Struktura projektu

src/                        # TypeScript (.ts / .tsx)
├── app/                    # Next.js App Router
│   ├── (dashboard)/        # Dashboard pages (.tsx)
│   ├── api/                # API routes (.ts)
│   └── login/              # Auth pages (.tsx)
├── domain/                 # Domain types and response helpers (.ts)
├── lib/                    # Core business logic (.ts)
│   ├── db/                 # SQLite database layer
│   ├── oauth/              # OAuth services per provider
│   ├── cacheLayer.ts       # LRU cache
│   ├── semanticCache.ts    # Semantic response cache
│   ├── idempotencyLayer.ts # Request deduplication
│   └── localDb.ts          # Settings facade (LowDB for config, SQLite for domain data)
├── shared/
│   ├── components/         # React components (.tsx)
│   ├── middleware/          # Correlation IDs, etc.
│   ├── utils/              # Circuit breaker, sanitizer, etc.
│   └── validation/         # Zod schemas
└── sse/                    # SSE chat handlers (.ts)

open-sse/                   # @omniroute/open-sse workspace (JavaScript)
├── handlers/               # chatCore.js — main request handler
├── services/               # Rate limit, fallback
├── translators/            # Format converters (OpenAI ↔ Claude ↔ Gemini)
└── utils/                  # Progress tracker, stream helpers

tests/
├── unit/                   # Node.js test runner (.test.mjs)
└── e2e/                    # Playwright tests

docs/                       # Documentation
├── USER_GUIDE.md           # Provider setup, CLI integration
├── API_REFERENCE.md        # All endpoints
├── TROUBLESHOOTING.md      # Common issues
├── ARCHITECTURE.md         # System architecture
└── adr/                    # Architecture Decision Records

---

Přidání nového poskytovatele

Krok 1: Služba OAuth (pokud používáte OAuth)

Vytvořte src/lib/oauth/services/your-provider.ts rozšiřující OAuthService :

import { OAuthService } from "../OAuthService";

export class YourProviderService extends OAuthService {
  constructor() {
    super({
      name: "your-provider",
      authUrl: "https://provider.com/oauth/authorize",
      tokenUrl: "https://provider.com/oauth/token",
      clientId: "...",
      scopes: ["..."],
    });
  }
}

Krok 2: Registrace poskytovatele

Přidat do src/lib/oauth/providers.ts :

import { YourProviderService } from "./services/your-provider";
// Add to the providers map

Krok 3: Přidání konstant

Přidejte konstanty poskytovatele do src/lib/providerConstants.ts :

• Předpona poskytovatele (např. yp/ )
• Výchozí modely
• Informace o cenách

Krok 4: Přidání překladače (pokud se nejedná o formát OpenAI)

Pokud poskytovatel používá vlastní formát API, vytvořte překladač v open-sse/translators/ .

Krok 5: Přidání časového limitu

Přidejte konfiguraci časového limitu požadavku do src/shared/utils/requestTimeout.ts .

Krok 6: Přidání testů

Pište jednotkové testy v tests/unit/ které pokrývají minimálně:

• Registrace poskytovatele
• Překlad žádostí/odpovědí
• Ošetření chyb

---

Kontrolní seznam žádostí o natažení

• Testy prošly ( npm test )
• Průchody pro linting ( npm run lint )
• Sestavení proběhlo úspěšně ( npm run build )
• Pro nové veřejné funkce a rozhraní přidány typy TypeScript
• Žádné pevně zakódované tajné kódy ani záložní hodnoty
• Aktualizován CHANGELOG (pokud se změna týká uživatele)
• Aktualizovaná dokumentace (pokud je to relevantní)

---

Uvolnění

Když je vytvořena nová verze GitHubu (např. v0.4.0 ), balíček je automaticky publikován do npm prostřednictvím akcí GitHubu:

gh release create v0.4.0 --title "v0.4.0" --generate-notes

---

Získání pomoci

• Architektura : Viz docs/ARCHITECTURE.md
• Problémy : github.com/diegosouzapw/OmniRoute/issues
• ADR : Viz docs/adr/