--- description: "Task list template for feature implementation" --- # Tasks: Contracts Module (Contratos) **Input**: Design documents from `/specs/003-contratos-module/` **Prerequisites**: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md (all present) **Tests**: Not included — no automated test suite exists in this codebase (Constitution Principle VIII) and the spec does not request one. `quickstart.md` is the manual verification plan (Polish phase runs it). **Organization**: Tasks are grouped by user story (spec.md's Story 1–7, priority P1–P7) so each can be implemented and verified independently, in priority order. This is a completion/correction pass over an already-substantial existing implementation (see `research.md` §1) — most tasks modify existing files rather than create new ones. **Revision note**: This list was corrected twice this session. First, after a `/speckit-analyze` pass plus user clarification found: (a) "Gestão" is not a new `Perfil新` tier — it's an existing `AreaComercial新` row reached via a Padrão-profile user's `Cargo新.area`, so the originally-planned `Perfil新` insert task is removed entirely and replaced with a small access-check helper; (b) three requirements (FR-014, FR-015 server-side, FR-026 on update.php, FR-028 on update.php modes, FR-040) had no task coverage and now do; (c) `create.php`/`update.php`'s error-leaking catch blocks are fixed using the same response shape already established on `fix/general-backlog` (research.md §12), to avoid diverging patterns at merge time. Second, two earlier decisions were explicitly reversed by the user and `spec.md` was updated to match: (d) Renovar/Ampliar/Reduzir keep the existing `duplicate()`-row/deactivate-old-row design — the "convert to in-place UPDATE" work is no longer part of this feature; (e) Cancelar's `motivo` stays required — the "make it optional" work is no longer part of this feature. Both are now correctly reflected in `spec.md` (FR-031, FR-036, User Stories 4/6/7) as well as here. ## Format: `[ID] [P?] [Story] Description` - **[P]**: Can run in parallel (different files, no dependency on an incomplete task) - **[Story]**: Which user story this task belongs to (US1–US7) - Every task states its exact file path ## Path Conventions All paths are under `sistema/new/` (existing single monolithic project, pages/ajax/js triad — no new top-level structure, per plan.md's Structure Decision). --- ## Phase 1: Setup **Purpose**: New, self-contained infrastructure with no dependency on schema changes — safe to build first. - [X] T001 [P] Create `sistema/new/includes/funcoes/so5.php` with `so5_get_marcas()`, `so5_get_segmentos(string $marcaCodigo)`, `so5_get_produtos_insumo(string $marcaCodigo)` — raw `curl_init()` calls (matching `includes/apis/get_cnpj.php`'s existing pattern, no new dependency), base URL/token read via `getenv()` only (Constitution Principle VI), each function returns `null` (not `[]`) on any non-2xx/timeout/malformed-JSON response and `error_log()`s the failure before returning (Constitution Principle VII, CNF-18). Per `contracts/so5-integration.md`. - [X] T002 [P] Add `usuario_pode_gerir_contratos($sql)` to `sistema/new/includes/funcoes/funcoes.php` (existing shared file, already included via `ajaxheader.php` — no new include wiring): returns true if `$_SESSION['perfil'] == 2` (Administrador), or if `$_SESSION['perfil'] == 1` (Padrão) and the logged-in user's área resolves to Gestão via `Usuarios.cargo → Cargo新.id → Cargo新.area → AreaComercial新.id == 3` (a small JOIN query using `$_SESSION['user_id']`). No schema change — `AreaComercial新` id 3 "Gestão" already exists. Per research.md §8. --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Schema change User Story 1 (and transitively User Story 3) depends on. Must complete before Phase 3. **⚠️ CRITICAL**: US1 cannot write `so_brand`, and US3's `segmento.php`/`insumo.php` cannot look up a produto's SO5 link, until T003 lands. - [X] T003 Create `sistema/new/migrations/sql/produto_so_brand_column.sql`: `ALTER TABLE Produto新 ADD COLUMN so_brand VARCHAR(64) NULL`, guarded via an `INFORMATION_SCHEMA.COLUMNS` existence check + `PREPARE`/`EXECUTE` so re-running is a no-op (idempotent, per FR-041/CNF-10 — MySQL has no native `ADD COLUMN IF NOT EXISTS`). Plain `.sql` file, run directly against the DB (`mysql ... < file.sql`) — schema/table changes now live under `migrations/sql/` as SQL files, not PHP scripts (convention changed this session; existing PHP scripts under `migrations/` remain data-backfill scripts, a different concern). Run against the local dev DB, verified via `DESCRIBE` and a second run confirming the no-op path. **Checkpoint**: Schema ready — Phase 3 (US1) can begin. --- ## Phase 3: User Story 1 - Configure produto_marca for the Contracts module (Priority: P1) **Goal**: An Admin can link a produto_marca to its SO5 marca and assign it a valid Classe (VHP / Plataforma / Serviço Padrão), in Cadastro > Produto. **Independent Test**: Open a produto in Cadastro > Produto, select a "Marca SO" value, select a non-conflicting Classe, save, reopen — both persisted. Try an invalid Classe combination — rejected. ### Implementation for User Story 1 - [X] T004 [P] [US1] `sistema/new/includes/ajax/produto/create.php`: accept new `so_brand` field and write it to `Produto新.so_brand`. **No Classe combination-rule validation here** — corrected mid-session after live testing: a produto_marca can be linked to any subset of the three Classe values as available options; the mutual-exclusivity rule (FR-004) is enforced at contract time instead, moved to T016/T017 (`contrato/create.php`/`update.php`). Per `contracts/produto-classe-so-brand.md`. - [X] T005 [P] [US1] `sistema/new/includes/ajax/produto/update.php`: same `so_brand` write as T004, no Classe validation here either (same correction). - [X] T006 [P] [US1] `sistema/new/includes/ajax/produto/read.php`: return `so_brand` in the response. - [X] T007 [US1] Create `sistema/new/includes/ajax/produto/so_brand.php`: calls `so5_get_marcas()` (T001), returns `[{id, nome}]`; `502` with a clear message if the call returns `null` (SO5 unreachable). Depends on T001. - [X] T008 [US1] `sistema/new/pages/produto/cadastro.php`: add the "Marca SO" select field; `sistema/new/includes/js/produto.js`: wire it via `initChoicesSelect()`/`choiceslist.so_brand` — the explicit-call pattern this file already uses for Categoria (not the declarative `.choices-select-element` scan), so the existing generic edit-handler branch picks up `so_brand` automatically. Depends on T006, T007. - [X] T009 [US1] Create `sistema/new/migrations/sql/produto_classe_so_brand_backfill.sql` covering, for `Produto新` where `grupo=1 AND categoria IN (1,2)`: (a) Classe default — where none of the three are linked, insert `VHP`(3) as default; (b) `so_brand` backfill — `UPDATE Produto新 SET so_brand = id WHERE so_brand IS NULL` (scoped to the same produto set); (c) `UPDATE Classe新 SET nome='Plataforma + Serviço Padrão' WHERE id=2 AND grupo=1`. Idempotent (a temp table captures touched produtos before mutation; a second run finds nothing to touch or log). Logs one `Logs新` row per produto touched (`objeto="Produto"`, `responsavel=1` matching the existing Admin-user convention already used by every pre-existing `Logs新` row). Plain `.sql` file per the Phase 2 convention (schema/data changes as SQL, run directly against the DB). Per `contracts/produto-classe-so-brand.md`'s Migration section, research.md §6. Depends on T003. Run against the local dev DB and verified: live data was 5 conflicts (not research.md's stale "5 all-three + 1 two-only = 6")/7 unclassified/12 in scope — research.md corrected to match; post-run state confirmed correct for all 12 produtos, rename confirmed, 12 `Logs新` rows confirmed, second run confirmed idempotent (still 12 rows, no changes). **Correction (mid-session, after T004/T005's mistake was caught)**: this migration originally also deleted the `VHP` link from the 5 conflicting produtos, based on the same wrong "produto-level exclusivity" assumption — reverted via `migrations/sql/produto_classe_vhp_correction.sql` (re-adds `VHP` to those 5 produtos, verified against the pre-migration state, idempotent, 5 `Logs新` rows). - [X] T009a [US1] **Post-launch correction**: the (c) rename from T009 was reverted per user request — `sistema/new/migrations/sql/produto_classe_nome_reversao.sql` (`UPDATE Classe新 SET nome='Serviço Padrão' WHERE id=2 AND grupo=1`, same idempotent temp-table + `Logs新` pattern) restores the classification's display name to "Serviço Padrão". FR-005 is withdrawn (spec.md/research.md updated). FR-004's dependency-on-Plataforma rule is untouched — it's an id-based check in `contrato/create.php`/`contrato/update.php`, never tied to this label. Run against the local dev DB via `docker exec crm-mysql-crm-1`, verified (before: "Plataforma + Serviço Padrão"; after: "Serviço Padrão"; one `Logs新` row; second run confirmed idempotent, no duplicate row). **Checkpoint**: Story 1 fully functional and independently testable — Cadastro > Produto now drives real SO5 links and valid Classe values. --- ## Phase 4: User Story 2 - View and access-control the contracts list (Priority: P2) **Goal**: Admin/Gestão see the contracts list with the required fields and action buttons; every other profile is blocked, including by direct URL. **Independent Test**: Non-elevated user hits the contracts screen/URL — denied. Admin/Gestão sees the full list with all action buttons and no "Interações de sucesso" button. ### Implementation for User Story 2 - [X] T010 [US2] `sistema/new/includes/ajax/empresa/load.php`: gate the `case 'contratos':` dispatch branch (the only place `pages/contratos/contratos.php` is ever loaded — a tab of the empresa detail view, not a standalone route) with `usuario_pode_gerir_contratos()`, including `pages/error/403.php` (pre-existing) instead when denied. `sistema/new/pages/contratos/contratos.php`: removed the "Interações de sucesso" button. - [X] T011 [US2] `sistema/new/includes/ajax/contrato/read.php`: added the same `usuario_pode_gerir_contratos()` gate (403 JSON — this ajax entry point needs its own gate regardless of T010's page-level block); added the missing tenant check (`JOIN Empresa新 ON Empresa新.id = Contrato新.empresa` + `Empresa新.grupo = ?` using `$_SESSION['grupo']`) to both list-mode and detail-mode queries — research.md §4. Verified: 0 of 23 existing contracts have an orphaned `empresa` reference, so the new (non-LEFT) `JOIN` drops nothing legitimate. - [X] T012 [US2] `sistema/new/includes/ajax/contrato/download.php`: added the same `usuario_pode_gerir_contratos()` gate and the same tenant check before streaming the `arquivo` BLOB (had neither — research.md §4). **Checkpoint**: Story 2 fully functional and independently testable — list, access control, and tenant isolation all correct, even before Story 3's wizard is complete. --- ## Phase 5: User Story 3 - Register a new contract (Priority: P3) **Goal**: Admin/Gestão can create a complete new contract — SO5-backed segmento/insumo per produto_marca, dates, payment, signature — in one flow. **Independent Test**: Start a new contract, select a produto_marca, complete its section (SO5-backed segmento/insumo, classe, tipo, entregáveis), fill dates/payment/signature, save; reopen and confirm every value persisted. **Depends on**: US1 (needs real `so_brand` links + valid Classe data to have anything meaningful to select) and US2 (the screen this launches from). ### Implementation for User Story 3 - [X] T013 [P] [US3] Rewrote `sistema/new/includes/ajax/contrato/segmento.php`: replaced the hardcoded array with a lookup of the requested produto's `so_brand` (returns `[]` if `NULL`) then `so5_get_segmentos($marcaCodigo)`; `502` with `{error:"so5_unavailable"}` if that call returns `null`. Live-verified (produto 1 → 8 real segmentos). - [X] T014 [P] [US3] Rewrote `sistema/new/includes/ajax/contrato/insumo.php`: same pattern via `so5_get_produtos_insumo($marcaCodigo)`. This forced a JS-side breaking change since insumo.php is no longer one universal catalog: `getInsumoCatalog()` in `contratos.js` became per-produto (`insumoCatalog`/`insumoCatalogPromise` keyed by produto id, request body includes `produto`), covered under T019. - [X] T015 [US3] `sistema/new/includes/ajax/contrato/formproduto.php`: added `data-param="produto" data-produto=""` to the segmento select (needed once segmento.php became produto-scoped); added FR-040 legacy-flag computation (`$so5Status`: `legacySegmentos`/`legacyInsumos`/`unavailable`) comparing stored ids against the produto's live SO5 lists, passed to the fragment's inline script for T019's `renderSo5Status()` to render. - [X] T016 [US3] `sistema/new/includes/ajax/contrato/create.php`: added `usuario_pode_gerir_contratos()` gate; added `validateArquivoUpload()` (PDF-only/≤10MB, mirrors `interacoes/create.php`) as one small reusable function — kept separate from persistence so a future S3-backed upload only changes the persist step, not this check; added `validateInsumoOneSegmento()` (FR-015) called per produto; added demais≠focal check (FR-026); catch block now `error_log($e)` + the exact `fix/general-backlog` safe shape. **Scoping decision**: FR-029a (SO5-down blocks a produto's section) is enforced client-side only (matching how `contracts/so5-integration.md` frames it) — no server-side SO5 re-check at save time, since a produto saved with an incomplete matrix from a transient SO5 outage is the same accepted state as an unlinked `so_brand` (FR-003). Flagged for review. **Correction added after live testing**: `validateClasseCombination()` (FR-004) moved here from `produto/create.php` (T004) — it's a contract-time selection rule, not a produto-configuration rule; called per produto on `classe-{produto}`. - [X] T017 [US3] `sistema/new/includes/ajax/contrato/update.php`: added the gate at the top of the file (covers every mode). Added the same `validateArquivoUpload()`/`validateInsumoOneSegmento()`/demais≠focal guards to `editar` and `editaradmin` specifically (per contract scope — `renovar`/`ampliar`/`reduzir` get theirs in T022/T027/T028). Same catch-block fix as T016. Same `validateClasseCombination()` correction as T016, added to `editaradmin` (the only mode here where `classe-{produto}` is re-submitted/editable — `editar` locks it). - [X] T018 [US3] `sistema/new/includes/js/contratos.js` + `formproduto.php`: added `updateProdutoStatus()` (gray/yellow/green dot based on Classe+Tipo required fields plus any optional field touched), wired to classe/tipo/pacotes/entregaveis changes and to `syncInsumosUI()` (covers segmento/insumo changes transitively); produto-groups now render with the `close` class and `i-caret-right` by default (collapsed). - [X] T019 [US3] `sistema/new/includes/js/contratos.js`: `getInsumoCatalog(produto)` made per-produto (T014's breaking change); added `produtoSo5Errors` tracking + `markProdutoSo5Error()`/`clearProdutoSo5Error()`, disabling `.form-submit-button` and blocking `submitContrato()` while any produto has an error; added `renderSo5Status()` rendering T015's legacy/unavailable flags inline. **Note**: the segmento `