Ferias Project Skill

Purpose

• Provide a repeatable execution playbook for backend and database work.
• Keep delivery aligned with AGENTS.md (SOLID, DRY, YAGNI, KISS, LoD, TDA, SRP).

Scope

• In scope: SQL Server schema and query changes (ferias.sql).
• In scope: API work in backend/Ferias.Api (Data, Endpoints, Models, Infra).
• In scope: local run/build/validation commands.
• Out of scope: Pencil and layout.pen workflow.

Project map

• ferias.sql: database schema and seed/update scripts.
• run-db-tests.ps1: DB connectivity/check script using prod.env.
• backend/Ferias.Api/Program.cs: app bootstrap and endpoint registration.
• backend/Ferias.Api/Endpoints: HTTP contracts and endpoint mapping.
• backend/Ferias.Api/Data: repositories and DB access.
• backend/Ferias.Api/Models: request/response contracts.
• example.env: safe template for required environment variables.
• prod.env: real secrets/local environment values (never commit secrets).

Workflow 1: DB change

1. Update ferias.sql with the minimal required change.
2. Prefer additive and backward-compatible SQL when possible.
3. Re-run DB checks with powershell -NoProfile -ExecutionPolicy Bypass -File .\run-db-tests.ps1.
4. If a breaking change is required, document impact and migration steps.

Workflow 2: API endpoint change

1. Define/update request and response models in Models.
2. Implement repository method in Data with focused responsibility.
3. Add/adjust endpoint mapping in Endpoints.
4. Ensure API envelope/error pattern remains consistent with existing endpoints.
5. Keep authorization and role checks explicit in endpoint handlers.
6. Build and validate with dotnet build .\Ferias.sln.

Workflow 3: Auth and user domain rule

1. Keep accepted login domain restricted to @garsoncredito.com.br.
2. Validate email normalization consistently (trim/lowercase).
3. Reject invalid domain with clear and stable API error shape.

Workflow 4: Environment management

1. Keep example.env updated with every required key.
2. Do not store real credentials in repository-tracked files.
3. Use prod.env only for local/internal execution.
4. Confirm run-db-tests.ps1 reads expected keys before changing scripts.

Definition of done (backend/db task)

1. Change is minimal and matches current requirement.
2. dotnet build passes.
3. DB check script passes when DB is reachable.
4. No duplication introduced across endpoint/repository/model layers.
5. Public API response/error format remains consistent.
6. Any new env var is documented in example.env.

Guardrails

• Do not add abstractions unless they are needed now.
• Keep methods small and explicit.
• Avoid cross-layer leakage: endpoint knows contracts and orchestration.
• Avoid cross-layer leakage: repository knows SQL/data access.
• Avoid cross-layer leakage: model knows shape, not behavior.
• Do not revert unrelated user changes.