Přispívání

Přispívání do Sencai

Při přispívání do Sencai se řiďte těmito pravidly.

Kam se podívat nejdřív

Než začnete cokoliv měnit, přečtěte si tyto zdroje — jsou to aktuální, živé reference (ne text téhle stránky):

• .claude/AGENTS.md — role agentů a hranice jejich autonomie
• .claude/context/ — architektura, glosář, onboarding, audit patterny, checklist pro code review
• PHASE-5-PLAN.md / PHASE-6-PLAN.md (kořen repozitáře) — aktuální fázové plány (FÁZE 5 je gate-overridnutá a aktivně se lokálně implementuje, FÁZE 6 je ve fázi přípravy); PHASE-2-PLAN.md, PHASE-3-PLAN.md i PHASE-4-PLAN.md jsou už archivované pod ai-context-staging/phase-2/, phase-3/ a phase-4/, protože tyto fáze jsou implementačně dokončené

Git workflow

Sencai monorepo je ve skutečnosti polyrepo: každá služba (sencai.space, api-manager, cloud-connector, sencai-web a zhruba dalších 30) je vlastní nezávislý Git repozitář s vlastním remote — žádný jednotný kořenový repozitář je nespojuje.

Žádný z těchto repozitářů nemá větev main. Každý aktivní repozitář má přesně jednu dlouhověkou větev, dev, ze které staví CI. Hrstka starších repozitářů (ai-context-staging, auth-service-consumer, bootstrap, graphql-gateway) si ještě nese pozůstatkovou větev master z doby před ustálením konvence „jen dev”, ale žádný z nich ji nepoužívá jako integrační cíl — všude, kde na tom záleží, je to dev.

V historii žádného repozitáře také nejsou doklady o workflow s feature branchemi — reálná praxe je Conventional Commits přímo na dev:

git checkout dev
git pull origin dev
# ...proveďte změny...
git add .
git commit -m "fix(security): account-limit-guard invite bypass"
git push origin dev

Model Git Flow založený na main, s feature/* větvemi, PR review a release procesem spouštěným tagem, v tomto kódu dnes neexistuje. Pokud jste tento model viděli popsaný jinde (včetně .claude/skills/release.md — viz poznámka níže), berte ho jako aspirační stav, ne aktuální praxi.

Commitování změn

Používejte Conventional Commits jako jednořádkovou zprávu:

git commit -m "feat(billing): add overview endpoint"

Podle kořenového CLAUDE.md: jedna věta, bez tečky na konci, žádné konvence pro tělo/footer commitu typu Closes #42 se nepoužívají.

Tvrdé pravidlo — bez výjimek: commity nesmí nikdy obsahovat Co-Authored-By, Signed-off-by ani žádnou zmínku o Claude/AI — ani ve zprávě, ani v kódu/komentářích. Vynucuje se napříč celým projektem. (Poznámka: malé množství starých historických commitů toto pravidlo předchází — neberte je jako precedens.)

Typy commitů

Typ	Popis
feat	Nová funkce
fix	Oprava chyby
docs	Dokumentace
chore	Build, závislosti, tooling
refactor	Refaktoring (bez změny chování)
test	Přidání/úprava testů
ci	Změny CI/CD pipeline
perf	Zlepšení výkonu

Proces Pull Requestů

V běžném provozu aktuálně neexistuje žádný proces review přes pull requesty: napříč repozitáři chybí PULL_REQUEST_TEMPLATE.md, chybí soubor CODEOWNERS a neexistuje žádný CI workflow spouštěný na pull_request pro hlavní lint/test/build gate (ci.yml) — ten běží výhradně na push do dev. Pokud se v budoucnu zavede workflow založený na PR a review, tato sekce se aktualizuje. Do té doby berte jakýkoliv PR/branch/squash-merge proces popsaný zde nebo jinde jako aspirační, ne jako aktuální praxi.

Aktualizace CHANGELOG

Každá změna musí aktualizovat CHANGELOG dotčené služby v sekci ## [Unreleased].

Formát

Používá se Keep a Changelog:

## [Unreleased]

### Added
- Nová funkce

### Changed
- Změněné chování

### Fixed
- Opravená chyba

### Removed
- Odstraněný endpoint

Příklad

## [Unreleased]

### Added
- GET /api/billing/overview endpoint
- Měsíční agregace nákladů

### Fixed
- Problém se sync smyčkou v Keycloaku

Databázové migrace

Disciplína migrací se liší podle služby — kompletní rozpis podle jednotlivých služeb je v .claude/skills/db-migration.md. Dva nejběžnější vzory:

• Strapi (sencai.space) — Knex migrace pod database/migrations/. Nikdy neupravovat ani nemazat existující migrační soubor, vždy přidat nový. Migrace se spouští automaticky při startu Strapi. Pro změny polí content-type obvykle úprava schema.json migraci vygeneruje automaticky.
• Cloud Connector (cloud-connector) — synchronizace TypeORM entit, ne souborové migrace. Změny schématu se dělají přímo v definicích entit pod src/database/entities/; v devu aplikuje schéma synchronize: true v TypeORM, produkční změny jdou přes typeorm migration:generate. Jde o odlišnou disciplínu než u Strapi — nepředpokládejte, že zde existují Knex-style migrační soubory.

Nikdy nemazat ani neupravovat existující Knex migrace, bez ohledu na službu.

Testování

Spouštění testů

# Backend
cd sencai.space && npm test

# Frontend
cd sencai.space-frontend && npm test

# Microservices
cd api-manager && npm test

CI/CD

CI běží při každém push do dev (ne na pull requestech — hlavní pipeline nemá PR trigger). Základní gate ci.yml typicky spouští:

1. Lint — ESLint + Prettier
2. Type check — TypeScript
3. Testy — Jest/Vitest
4. Build — produkční build

Nezávisle na ci.yml běží ještě dva další gaty, jak na schedule, tak na push:

• Dependency Audit (dependency-audit.yml) — npm audit (blokující při high/critical nálezu), běží na push do dev a každou noc přes cron 0 4 * * *.
• Secret scanning (gitleaks.yml) — hledá zacommitované secrety; několik repozitářů to řeší přes akci gacts/gitleaks (wrapper bez license-gate nad stejným OSS gitleaks scannerem, přijatý poté, co gitleaks/gitleaks-action@v2 začal pro organizační repozitáře vyžadovat placenou licenci).

Všechny gaty musí v praxi projít, než je změna považována za mergovatelnou/nasaditelnou — i bez formálního kroku PR review, který by to vynucoval.

Dokumentace

Aktualizace README

Pokud přidáváte funkce nebo služby:

service-name/
├── README.md ← doplnit dokumentaci
├── CLAUDE.md ← kontext pro Claude Code
├── CHANGELOG.md ← formát Keep a Changelog
└── .env.example ← všechny ENV proměnné

Povinné soubory v nových službách

• README.md — popis, tech stack, jak spustit
• CLAUDE.md — kontext pro Claude Code
• CHANGELOG.md — formát Keep a Changelog
• .env.example — všechny proměnné prostředí
• Dockerfile — kontejnerizace
• .dockerignore — vyloučení build souborů

Výjimka: čistě konfigurační adresáře bez vlastního aplikačního kódu — auth-service/, git-service/, sencai-mq/, k8s-agent/ — nepotřebují Dockerfile/.dockerignore/.env.example, protože jejich runtime image pochází z upstream projektu (Keycloak, Gitea, RabbitMQ), ne z buildu tady. infra-gcp/ (CDKTF infrastructure-as-code) je z požadavku na Dockerfile/.dockerignore stejně tak vyňat, protože nejde o běžící službu.

Release proces

Při vydání release přesuňte [Unreleased] v CHANGELOG.md dané služby do datované verzové sekce:

## [1.2.0] - 2026-04-20

### Added
- Billing overview

### Fixed
- Keycloak sync

Poté bumpněte verzi v package.json:

{
  "version": "1.2.0"
}

Tahle část workflow je reálná a odpovídá aktuální praxi.

Co není aktuální praxe: neexistuje větev main, do které by se mergovalo, neexistuje krok git tag v1.2.0 ani release pipeline spouštěná tagem. Jediné reálně pozorované schéma tagování image v repozitářích je dev-latest — Docker image se rebuilduje a pushuje do ghcr.io pod tímto jediným tagem při každém push do dev. Verzované tagy image (ghcr.io/...:v1.2.0) a GitHub Releases nejsou součástí aktuální pipeline.

.claude/skills/release.md v současnosti popisuje stejný nepodporovaný flow dev → main → tagovaný release, který byl z téhle stránky odstraněn. Tenhle skill soubor by se měl časem opravit tak, aby odpovídal realitě „jen dev, tag dev-latest”, ale jeho úprava je mimo rozsah tohoto content fixu.

Bezpečnostní pravidla

• Nikdy necommitovat .env — použít .env.example
• Nikdy nešifrované secrety — API klíče, tokeny, hesla
• Validovat vstup — vždy
• Používat parametrizované dotazy — prevence SQL injection
• Nakonfigurovat CORS/CSRF — pořádně

Časté chyby

Problém	Příčina	Řešení
CI „push” selhal	Chyba lintu	Spustit lokálně npm run lint:fix před pushem
Testy neprochází	Chybějící fixture	Zkontrolovat setup testů
Dependency Audit selhává	High/critical nález z npm audit	Opravit závislost, nebo zdokumentovat v audit allowlistu služby s poznámkou a expirací
Chybí CHANGELOG	Zapomenutá aktualizace [Unreleased]	Aktualizovat CHANGELOG.md, než se změna považuje za hotovou

Dotazy

Pro onboarding a architektonické otázky začněte u .claude/AGENTS.md a .claude/context/onboarding.md, ne u obecných komunitních kanálů — jde o interní platformu bez veřejných GitHub Issues/Discussions nebo komunitního chatu zřízeného pro dotazy k přispívání.

Skutečné CI/CD gaty jednotlivých služeb najdete v jejich .github/workflows/.