mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-01 21:02:12 +03:00
274 lines
7.6 KiB
Markdown
274 lines
7.6 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
git clone https://github.com/diegosouzapw/OmniRoute.git
|
||
cd OmniRoute
|
||
npm install
|
||
```
|
||
|
||
### Proměnné prostředí
|
||
|
||
```bash
|
||
# 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ě
|
||
|
||
```bash
|
||
# 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.
|
||
|
||
```bash
|
||
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ů](https://www.conventionalcommits.org/) :
|
||
|
||
```
|
||
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ů
|
||
|
||
```bash
|
||
# 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` :
|
||
|
||
```typescript
|
||
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` :
|
||
|
||
```typescript
|
||
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:
|
||
|
||
```bash
|
||
gh release create v0.4.0 --title "v0.4.0" --generate-notes
|
||
```
|
||
|
||
---
|
||
|
||
## Získání pomoci
|
||
|
||
- **Architektura** : Viz [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
|
||
- **Problémy** : [github.com/diegosouzapw/OmniRoute/issues](https://github.com/diegosouzapw/OmniRoute/issues)
|
||
- **ADR** : Viz `docs/adr/`
|