feat(squads): bounded contexts + ADRs for onboarding & squads governance#332
feat(squads): bounded contexts + ADRs for onboarding & squads governance#332danielhe4rt wants to merge 14 commits into
Conversation
stherzada
left a comment
stherzada
left a comment
There was a problem hiding this comment.
Avalie as considerações, e me dê um toque.
There was a problem hiding this comment.
No geral não entendi quais decisões ele viu de problema, necessito de mais contexto para atuar nesse review.
|
up! |
1 similar comment
|
up! |
Co-authored-by: Sther <72408918+stherzada@users.noreply.github.com> Signed-off-by: Daniel Reis <danielhe4rt@gmail.com>
|
Comentário do Elves:
|
R: Faz sentido capturar qualquer evento de uma squad. Por mais simples que seja, é o que precisamos no momento.
R: Ambos serão o mesmo payload, no final, o meio não importa desde que tenha a Action fazendo essa fronteira entre o |
stherzada
left a comment
stherzada
left a comment
There was a problem hiding this comment.
Só não esquece de mandar o a doc lá!
| | `completed_at` | timestamptz? | | | ||
| | timestamps | tz | | | ||
| | UNIQUE | `(onboarding_id, step_key)` | | | ||
|
|
There was a problem hiding this comment.
pra fins de auditoria de transicionamento e checks mais rapidos, nao valeria armazenar a transição de steps com uma coluna de previously_at? traria ganho pra disciplina de transition mencionada na linha 102
ou eles foram desenhados pra serem "ever-forward" (flow nao é um grafo direcionado, apenas guarda estados)?
| PR do candidato** num repo de desafio. A plataforma precisa reagir a essa aprovação. | ||
|
|
||
| O `integration-github` já é o **único** ponto que fala com o GitHub: `GithubWebhookController` recebe | ||
| todos os webhooks, grava no `GithubEventLog` (lake, dedup por `delivery_id`), e o `ProjectGithubEvent` |
There was a problem hiding this comment.
estamos distinguindo repositório de projeto ou ambas palavras se referem à mesma coisa? um evento emitido por um repositorio deveria RepoGithubEvent ou ProjectGithubEvent como é agora?
There was a problem hiding this comment.
por que os CONTEXT.md estão em inglês e os ADRs não? pra fins de linguagem ubiqua, não deveria serem todos no mesmo idioma?
| consulta interna do `integration-github`) e furaria o encapsulamento do lake. Descartado. | ||
| - **Config de repo de desafio dentro do `onboarding`** (em vez do `purpose` na allowlist): manteria o | ||
| `integration-github` sem nenhuma categoria nova, mas duplicaria o cadastro de repos e perderia o | ||
| benefício de excluir o repo de desafio da projeção de contribuições num lugar só. Trade-off aceito |
There was a problem hiding this comment.
com o purpose acoplamos a entidade do GithubRepository no dominio de onboarding. cada type nao poderia ter um repo (unique key) como repo challenge apenas apontando pro repo (1:1)*? isso ainda permitiria excluir os repos de challenge das contribuições
*1 type aponta para 1 repo de challenge
| | **OnboardingFlow** | The per-type handler (a class behind the `OnboardingFlow` contract). Declares `steps()`, `prerequisites()`, `advance()`, `isComplete()`. All type-specific rules live here. | The model — the Flow is stateless behaviour; the Onboarding is the state | | ||
| | **OnboardingStep** | One auditable stage of a flow, one row in `onboarding_steps`. Carries its own `status` + `data` (jsonb) + `completed_at`. Enables pause/resume and history. | A prerequisite (another _type_ that must be complete first) | | ||
| | **Prerequisite** | Another `OnboardingType` that must be **completed** before this one can start (e.g. `Squads` requires `Welcome`). Declared by the flow, enforced on start. | A step (intra-type) — a prerequisite is inter-type | | ||
| | **APTO** | Domain shorthand for "completed the `Squads` onboarding". The condition that unlocks squad candidacy and squad creation. It is _not_ a global flag — it is `Squads` completion. | A generic "active member" — APTO is specifically squad-eligible | |
There was a problem hiding this comment.
APTO ta amarrado ao contexto do onboarding de Squads ou pretendemos reutilizar esse shorthand pra futuros onboarding types? se pretendemos reutilizar acho bom ja desamarrarmos os conceitos
| ### Modelo | ||
|
|
||
| - `squads` (`status`: `draft`/`active`/`inactive`/`archived`, `objective`, `slug`, tenant-scoped). | ||
| - `squad_members` (pivot): `role` (`Captain`/`SubCaptain`/`Member`/`ExMember`), `joined_at`, `left_at`. |
There was a problem hiding this comment.
Sailor (marujo) ao inves de Member se quiserem que o schema esteja bem aderido ao tema de piratas, xd
| ### `squads` | ||
|
|
||
| `name`, `slug`, `objective` (text, nullable — `draft` pode não ter), `status` (`SquadStatus` | ||
| `draft`/`active`/`inactive`/`archived`, default `draft`), timestamps. |
There was a problem hiding this comment.
created_by pra auxiliar a encontrar o autor do squad no futuro (utilidade)
gvieira18
force-pushed
the
feat/onboarding-squads
branch
from
3079a6f to
36262a8
Compare
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Central YAML (inherited) Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (2)
📝 WalkthroughWalkthroughTwo new app-modules are added: Possibly related issues
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (6)
composer.json (2)
32-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winInconsistent version constraint.
Other
he4rt/*packages use>=1or^1.1;*is looser and inconsistent. Align with>=1unless path-repo semantics require otherwise.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@composer.json` at line 32, The dependency constraint for he4rt/onboarding is too loose and inconsistent with the other he4rt/* packages. Update the composer.json requirement for he4rt/onboarding to match the existing versioning style used by the other package entries (preferably >=1, unless the repository setup truly requires *), so the package constraints stay aligned.
37-37: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winInconsistent version constraint.
Same as above for
he4rt/squads.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@composer.json` at line 37, The dependency constraint for he4rt/squads is inconsistent with the other packages in composer.json; update its version requirement to match the same fixed constraint pattern used nearby instead of using a wildcard. Locate the he4rt/squads entry in composer.json and align it with the surrounding dependency versions so the package list stays consistent.app-modules/onboarding/composer.json (2)
5-5: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winRemove hardcoded version.
Path repositories with
*constraint don't need a version; Composer derives it from VCS or uses1.1.0fallback. Hardcoding creates maintenance churn.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@app-modules/onboarding/composer.json` at line 5, Remove the hardcoded version from the onboarding Composer manifest; the package should rely on the path repository/VCS-derived version instead of the current fixed value. Update the composer.json entry so the package metadata no longer declares a manual version, keeping the manifest aligned with Composer’s version inference behavior.
3-3: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd a description.
Empty description field.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@app-modules/onboarding/composer.json` at line 3, The composer.json for the onboarding module has an empty description field and needs a meaningful package description. Update the description value in the manifest so it briefly explains the purpose of the onboarding module, keeping it aligned with the module name and existing package metadata.app-modules/onboarding/CONTEXT.md (2)
41-50: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd
textlanguage to fenced block.Same as above for the directory structure block.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@app-modules/onboarding/CONTEXT.md` around lines 41 - 50, The directory structure example in CONTEXT.md uses a fenced block without a language, so update that block to use text syntax highlighting like the other fenced example. Locate the markdown fence around the `src/` tree in the onboarding context doc and change it to a text-labeled code block while keeping the content unchanged.
26-35: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd
textlanguage to fenced block.markdownlint flags missing language. Use
textfor the ASCII diagram.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@app-modules/onboarding/CONTEXT.md` around lines 26 - 35, The fenced ASCII diagram in CONTEXT.md is missing a language tag, which triggers markdownlint. Update the fenced block around the onboarding flow diagram to use text as the fence language so the block is explicitly marked as plain text.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@app-modules/onboarding/composer.json`:
- Line 5: Remove the hardcoded version from the onboarding Composer manifest;
the package should rely on the path repository/VCS-derived version instead of
the current fixed value. Update the composer.json entry so the package metadata
no longer declares a manual version, keeping the manifest aligned with
Composer’s version inference behavior.
- Line 3: The composer.json for the onboarding module has an empty description
field and needs a meaningful package description. Update the description value
in the manifest so it briefly explains the purpose of the onboarding module,
keeping it aligned with the module name and existing package metadata.
In `@app-modules/onboarding/CONTEXT.md`:
- Around line 41-50: The directory structure example in CONTEXT.md uses a fenced
block without a language, so update that block to use text syntax highlighting
like the other fenced example. Locate the markdown fence around the `src/` tree
in the onboarding context doc and change it to a text-labeled code block while
keeping the content unchanged.
- Around line 26-35: The fenced ASCII diagram in CONTEXT.md is missing a
language tag, which triggers markdownlint. Update the fenced block around the
onboarding flow diagram to use text as the fence language so the block is
explicitly marked as plain text.
In `@composer.json`:
- Line 32: The dependency constraint for he4rt/onboarding is too loose and
inconsistent with the other he4rt/* packages. Update the composer.json
requirement for he4rt/onboarding to match the existing versioning style used by
the other package entries (preferably >=1, unless the repository setup truly
requires *), so the package constraints stay aligned.
- Line 37: The dependency constraint for he4rt/squads is inconsistent with the
other packages in composer.json; update its version requirement to match the
same fixed constraint pattern used nearby instead of using a wildcard. Locate
the he4rt/squads entry in composer.json and align it with the surrounding
dependency versions so the package list stays consistent.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Central YAML (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 6b3001fb-8800-43c2-b335-94e1d1223642
📒 Files selected for processing (26)
CONTEXT-MAP.mdapp-modules/onboarding/CONTEXT.mdapp-modules/onboarding/composer.jsonapp-modules/onboarding/database/factories/.gitkeepapp-modules/onboarding/database/migrations/.gitkeepapp-modules/onboarding/database/seeders/.gitkeepapp-modules/onboarding/docs/adr/0001-onboarding-polimorfico-por-tipo.mdapp-modules/onboarding/docs/adr/0002-sinal-de-pr-aprovado-via-evento-de-dominio.mdapp-modules/onboarding/phpstan.ignore.neonapp-modules/onboarding/phpstan.neonapp-modules/onboarding/src/Providers/OnboardingServiceProvider.phpapp-modules/onboarding/tests/Feature/.gitkeepapp-modules/onboarding/tests/Unit/.gitkeepapp-modules/squads/CONTEXT.mdapp-modules/squads/composer.jsonapp-modules/squads/database/factories/.gitkeepapp-modules/squads/database/migrations/.gitkeepapp-modules/squads/database/seeders/.gitkeepapp-modules/squads/docs/adr/0001-governanca-como-registro.mdapp-modules/squads/docs/adr/0002-modelo-de-dados.mdapp-modules/squads/phpstan.ignore.neonapp-modules/squads/phpstan.neonapp-modules/squads/src/Providers/SquadsServiceProvider.phpapp-modules/squads/tests/Feature/.gitkeepapp-modules/squads/tests/Unit/.gitkeepcomposer.json
Bump guzzle to ^7.13.1 and refresh transitive locks; normalize he4rt/onboarding and he4rt/squads constraints from "*" to ">=1" to match sibling path modules.
Update tailwindcss/vite to 4.3.2, prettier to 3.9.3, npm-check-updates to 22.2.9.
5 participants
Artefato de fluxo de tasks
O quê
Estabelece dois novos bounded contexts —
onboarding(camada de Entrada) esquads(Governança) — via scaffold dos módulos + documentação de domínio (CONTEXT.md + ADRs). Sem código de runtime ainda — é a fundação de design que destrava a implementação.Resultado de uma sessão
/grill-with-docssobre o Mapa de Fluxos dos Squads (camadas Entrada + Governança; o Núcleo do jogo fica de fora por enquanto).Decisões principais (ver ADRs)
Onboarding (Entrada)
ADR-0001— Onboarding polimórfico por tipo (OnboardingType → handler(), mesmo idioma doIdentityProvider::getClient). Modeloonboarding+ tabelaonboarding_steps(auditoria por etapa). Cadeia de pré-requisitos entre tipos (Welcomeé pré-req deSquads). "APTO" =Squadsonboarding concluído.ADR-0002— Sinal de "PR aprovado" via novo evento de domínioGithubPullRequestApproveddointegration-github(transporte continua centralizado; HMAC/dedup reusados). Repo de desafio viaGithubRepository.purpose = challenge. Vínculo do GitHub é gate → sem reconciliação (diverge do BDD original da P.O.).Squads (Governança)
ADR-0001— Governança como record-keeping, não workflow engine. Eleição/remoção/saída/realocação rodam off-system; o módulo registra o resultado. Candidatura é o único fluxo conduzido. Autoridade = super-admins (config('he4rt.admins')) + capitão gere o próprio squad.ADR-0002— Modelo de dados:squads,squad_members(pivot com role),squad_membership_events(append-only),squad_applications. Capitão derivado do pivot (semcaptain_id). Capitão único + exclusividade "1 squad ativo" garantidos no banco (partial unique) + validação na Action.Fora de escopo (regras humanas, aplicadas off-system)
Elegibilidade "≥1 entrega", desempate pelo Head, candidatura única, mínimo de votos proporcional, "sem reeleição direta". Só o resultado é registrado — por isso o ponto aberto "definição de entrega" não bloqueia.
Arquivos
CONTEXT-MAP.md— registra os dois contextos + regras de dependênciaapp-modules/onboarding/— scaffold +CONTEXT.md+ 2 ADRsapp-modules/squads/— scaffold +CONTEXT.md+ 2 ADRsFollow-ups (não neste PR)
GithubPullRequestApproved, campoGithubRepository.purpose*ServiceProviderdesrc/Providers/→src/(guideline.ai/02-module-architecture)