From 292e8c67957488de981da27686bbd20f03040ed0 Mon Sep 17 00:00:00 2001 From: "Gabe@w7dev" Date: Mon, 26 Jan 2026 11:52:06 +0000 Subject: [PATCH 1/2] docs: add DAILY-FLOW and PHASE-FLOW documentation - DAILY-FLOW.md: Daily development workflow (branch strategy, PR flow, commands) - PHASE-FLOW.md: Phase completion workflow (lifecycle, snapshot, sync) Co-Authored-By: Claude Opus 4.5 --- docs/DAILY-FLOW.md | 175 ++++++++++++++++++++++++++++++++ docs/PHASE-FLOW.md | 243 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 418 insertions(+) create mode 100644 docs/DAILY-FLOW.md create mode 100644 docs/PHASE-FLOW.md diff --git a/docs/DAILY-FLOW.md b/docs/DAILY-FLOW.md new file mode 100644 index 00000000..3ceefe42 --- /dev/null +++ b/docs/DAILY-FLOW.md @@ -0,0 +1,175 @@ +# Daily Development Flow + +A napi fejlesztési munkafolyamat a ForecastLabAI projekthez. + +--- + +## Branch Stratégia + +``` +main (protected) <- Production releases only + │ + └── dev <- Integration branch + │ + └── feat/* <- Feature branches +``` + +--- + +## Napi Fejlesztési Ciklus + +### 1. Munka Kezdése + +```bash +# Frissítsd a dev branchet +git checkout dev +git pull origin dev + +# Hozz létre feature branchet +git checkout -b feat/prp-X-feature-name +``` + +### 2. Fejlesztés Közben + +```bash +# Rendszeres commitok +git add +git commit -m "feat(module): description" + +# Lokális ellenőrzések +uv run ruff check . +uv run ruff format . +uv run mypy app/ +uv run pyright app/ +uv run pytest -v +``` + +### 3. PR Létrehozása + +```bash +# Push feature branch +git push origin feat/prp-X-feature-name + +# PR létrehozása dev-be +gh pr create --base dev --title "feat(module): description" --body "..." +``` + +### 4. CI Ellenőrzések + +A PR-nek át kell mennie: +- [ ] Lint & Format +- [ ] Type Check (MyPy + Pyright) +- [ ] Test +- [ ] Migration Check +- [ ] Code Review (Sourcery, CodeRabbit) + +### 5. Merge to Dev + +```bash +# Review után merge +gh pr merge --squash --delete-branch +``` + +--- + +## Dev → Main Merge (Feature Complete) + +Amikor egy feature teljesen kész: + +```bash +# Checkout dev +git checkout dev +git pull origin dev + +# PR létrehozása main-be +gh pr create --base main --head dev --title "feat(module): merge feature to main" + +# CI ellenőrzések után merge +gh pr merge --squash +``` + +--- + +## Release Flow + +A `main` branch-re történő merge után a `release-please` automatikusan: +1. Létrehoz egy Release PR-t (version bump + CHANGELOG) +2. CI lefut a Release PR-en +3. Merge után GitHub Release + tag jön létre + +```bash +# Release PR ellenőrzése +gh pr list --label "autorelease: pending" + +# CI trigger ha szükséges +git checkout +git commit --allow-empty -m "chore: trigger CI" +git push + +# Merge release PR +gh pr merge --squash --delete-branch +``` + +--- + +## Commit Message Konvenció + +``` +(): + +Types: +- feat: Új feature +- fix: Bug fix +- docs: Dokumentáció +- refactor: Refaktorálás +- test: Teszt hozzáadás/módosítás +- chore: Build, CI, dependencies + +Scope (opcionális): +- data-platform +- ingest +- forecasting +- backtesting +- registry +- rag +- dashboard +``` + +--- + +## Gyors Parancsok + +```bash +# Status check +git status && git log --oneline -5 + +# Lint + format +uv run ruff check --fix . && uv run ruff format . + +# Type check +uv run mypy app/ && uv run pyright app/ + +# Tesztek +uv run pytest -v +uv run pytest -v -m integration # DB szükséges + +# PR checks +gh pr checks + +# Watch workflow +gh run watch +``` + +--- + +## Következő Phase: Ingest Layer (PRP-3) + +```bash +# Kezdés +git checkout dev +git pull origin dev +git checkout -b feat/prp-3-ingest-layer + +# Fejlesztés... +# PR → dev → main → release → phase-2 snapshot +``` diff --git a/docs/PHASE-FLOW.md b/docs/PHASE-FLOW.md new file mode 100644 index 00000000..e69365d3 --- /dev/null +++ b/docs/PHASE-FLOW.md @@ -0,0 +1,243 @@ +# Phase Completion Flow + +A phase lezárási munkafolyamat a ForecastLabAI projekthez. + +--- + +## Phase Lifecycle + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ PHASE LIFECYCLE │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ 1. DEVELOPMENT (feat/* → dev) │ +│ └── Feature branches merged to dev │ +│ │ +│ 2. INTEGRATION (dev → main) │ +│ └── All features complete, merge dev to main │ +│ │ +│ 3. RELEASE (release-please) │ +│ └── Automated version bump + GitHub Release │ +│ │ +│ 4. DOCUMENTATION │ +│ └── Update PHASE-index.md, phase docs │ +│ │ +│ 5. SNAPSHOT (main → phase-N) │ +│ └── Create protected branch + audit tag │ +│ │ +│ 6. SYNC (phase-N → dev) │ +│ └── Sync dev with main for next phase │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Részletes Lépések + +### 1. Feature Complete - Dev → Main + +```bash +# Ellenőrizd hogy minden feature merged dev-be +git checkout dev +git pull origin dev + +# PR létrehozása main-be +gh pr create --base main --head dev \ + --title "feat(phase-N): complete Phase N implementation" \ + --body "## Summary +- Feature 1 +- Feature 2 +- Feature 3 + +## Test plan +- [x] All tests passing +- [x] Type checks green +- [x] Lint checks green" + +# CI ellenőrzés és merge +gh pr checks --watch +gh pr merge --squash +``` + +### 2. Release + +```bash +# Várd meg a release-please PR-t +gh pr list --label "autorelease: pending" + +# Trigger CI ha szükséges +git checkout +git commit --allow-empty -m "chore: trigger CI" +git push + +# Merge release PR (review szükséges) +gh pr merge --squash --delete-branch + +# Ellenőrizd a release-t +gh release view v0.X.Y +``` + +### 3. Dokumentáció Frissítése + +```bash +# Checkout main +git checkout main +git pull origin main + +# Hozz létre docs branchet +git checkout -b docs/phase-N-completed + +# Frissítsd a dokumentációt: +# - docs/PHASE-index.md (status: Completed) +# - docs/PHASE/N-PHASE_NAME.md (status, release info) + +# PR és merge +gh pr create --base main --title "docs: mark Phase N as completed" +gh pr merge --squash --delete-branch +``` + +### 4. Phase Snapshot + +```bash +# Frissítsd main-t +git checkout main +git pull origin main + +# Hozd létre a phase branchet MAIN-ről +git checkout -b phase-N +git push origin phase-N + +# Várj a phase-snapshot.yml workflow-ra +gh run list --workflow=phase-snapshot.yml --limit 1 +gh run watch + +# Ellenőrizd a taget +git fetch --tags +git tag -l "phase-N-*" +``` + +### 5. Dev Szinkronizálás + +```bash +# Szinkronizáld dev-et a phase branch-ről +git checkout dev +git reset --hard phase-N +git push origin dev --force + +# VAGY PR-rel (biztonságosabb) +gh pr create --base dev --head phase-N \ + --title "sync: update dev from phase-N" +``` + +--- + +## Phase Snapshot Workflow + +A `phase-snapshot.yml` automatikusan: + +1. **Full Validation** + - Lint check + - Type check (MyPy + Pyright) + - Migration check + - All tests (unit + integration) + +2. **Create Audit Snapshot** + - Generate metadata JSON + - Collect validation results + - Create markdown report + - Upload audit artifact + - Create annotated tag: `phase-N-snapshot-YYYYMMDD-` + +--- + +## Branch Protection + +A `phase-*` branchek automatikusan védettek: +- No force push +- No deletion +- Serves as audit trail + +--- + +## Checklist: Phase Completion + +```markdown +## Phase N Completion Checklist + +### Development +- [ ] All PRPs implemented +- [ ] All features merged to dev +- [ ] All tests passing + +### Integration +- [ ] Dev merged to main +- [ ] Release PR merged +- [ ] GitHub Release created (vX.Y.Z) + +### Documentation +- [ ] PHASE-index.md updated (status: Completed) +- [ ] docs/PHASE/N-*.md updated +- [ ] Version history entry added + +### Snapshot +- [ ] phase-N branch created from main +- [ ] phase-snapshot workflow passed +- [ ] Annotated tag created +- [ ] Audit artifact uploaded + +### Sync +- [ ] Dev synced with main/phase-N +- [ ] Ready for next phase +``` + +--- + +## Példa: Phase 1 → Phase 2 Átmenet + +```bash +# Phase 1 lezárva, Phase 2 kezdése + +# 1. Ellenőrizd hogy phase-1 rendben van +git checkout phase-1 +git log --oneline -3 + +# 2. Dev szinkronizálva van +git checkout dev +git log --oneline -3 # Ugyanaz mint phase-1 + +# 3. Kezdd Phase 2-t +git checkout -b feat/prp-3-ingest-layer +# ... fejlesztés ... +``` + +--- + +## Hibaelhárítás + +### Phase branch behind main +```bash +# Töröld és hozd újra létre main-ről +git push origin --delete phase-N +git checkout main && git pull +git checkout -b phase-N +git push origin phase-N +``` + +### Dev diverged from main +```bash +# Reset dev to main +git checkout dev +git reset --hard origin/main +git push origin dev --force +``` + +### Régi phase tag törlése +```bash +# Töröld a remote taget +git push origin --delete phase-N-snapshot-YYYYMMDD- + +# Töröld a local taget +git tag -d phase-N-snapshot-YYYYMMDD- +``` From 46f5ad87a0f35e8bcbfb17ad469bf465f11fd077 Mon Sep 17 00:00:00 2001 From: "Gabe@w7dev" Date: Mon, 26 Jan 2026 11:59:20 +0000 Subject: [PATCH 2/2] docs(initial-3): add key resolution requirements for ingest layer External systems send natural keys (store_code, sku) rather than internal database IDs. The ingest service must resolve these codes to IDs and handle unknown codes gracefully by rejecting individual rows without failing the entire batch. Co-Authored-By: Claude Opus 4.5 --- INITIAL-3.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/INITIAL-3.md b/INITIAL-3.md index 3501906f..334c3459 100644 --- a/INITIAL-3.md +++ b/INITIAL-3.md @@ -20,6 +20,11 @@ - FastAPI request models + validation patterns - Postgres upsert (ON CONFLICT) + uniqueness constraints +## KEY RESOLUTION +- Ingest payloads accept natural keys (`store_code`, `sku`) instead of internal IDs. +- Service resolves codes → IDs before upsert. +- Unknown codes: reject individual row with error detail; continue processing valid rows. + ## OTHER CONSIDERATIONS: - Logging: inserted/updated counts + dedupe stats. - Batch sizing/timeouts must be configurable.