---
phase: 12-offer-composition-drag-drop-csv-import
plan: 01
subsystem: database
tags: [drizzle, postgres, schema, migration]

# Dependency graph
requires:
  - phase: 11-catalog-database-view-ux
    provides: unified `services` catalog table (category/fase single-select pattern, migrated_from audit trail)
provides:
  - Additive Drizzle schema columns on offer_macros (description, category, ticket, is_archived, cliente_ideale, risultato, tempo, pain, metodo)
  - Additive Drizzle schema columns on offer_micros (tier_letter, public_price)
  - New offer_tier_services junction table + relations + types (offer_micros <-> services)
  - Hand-written migration 0008_offer_tier_schema.sql (additive/idempotent, CHECK constraint on tier_letter)
  - Idempotent push script scripts/push-12-offer-tier-schema.ts for Plan 02's BLOCKING prod-apply step
affects: [12-02-prod-migration-apply, 12-03-offer-list-editor, 12-04-tier-matrix, 12-05-offer-detail-actions]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Additive-only schema extension via hand-written SQL migration (drizzle-kit generate non-functional in this repo)"
    - "Single-select dimension columns (category/ticket) on offer_macros, mirroring services.category/fase pattern from Phase 11"
    - "New junction table (offer_tier_services) as additive replacement for legacy junction (offer_micro_services), pointing at unified services catalog instead of deprecated offer_services"
    - "DB-level CHECK constraint via guarded DO block for idempotent re-runs, with Zod validation deferred to server-action layer (Plan 03)"

key-files:
  created:
    - src/db/migrations/0008_offer_tier_schema.sql
    - scripts/push-12-offer-tier-schema.ts
  modified:
    - src/db/schema.ts
    - src/db/migrations/meta/_journal.json

key-decisions:
  - "tier_letter constrained via SQL CHECK (guarded DO block) rather than Drizzle enum, since this pg-core version has no native CHECK helper — Zod enum validation is deferred to Plan 03's server-action layer as defense-in-depth"
  - "offer_tier_services created as a brand-new junction (not a modification of offer_micro_services) to avoid touching legacy offer_services-linked data, per D-6"

patterns-established:
  - "Phase 12 additive columns documented inline with comment blocks above offer_macros/offer_micros, following the services.migrated_from comment style from Phase 11"

requirements-completed: [OFFER-11, OFFER-15, OFFER-16, OFFER-17, OFFER-18]

# Metrics
duration: 6min
completed: 2026-06-14
---

# Phase 12 Plan 01: Offer Tier Schema Foundation Summary

**Additive Drizzle schema + hand-written migration 0008 adding tier designations (A/B/C), manual public pricing, archive flag, category/ticket dimensions, structured transformation-promise fields, and a new offer_tier_services junction table pointing at the unified services catalog.**

## Performance

- **Duration:** 6 min
- **Started:** 2026-06-14T19:13:00Z (approx)
- **Completed:** 2026-06-14T19:19:38Z
- **Tasks:** 2 completed
- **Files modified:** 4

## Accomplishments

- Extended `offer_macros` with 9 additive columns: `description`, `category`, `ticket`, `is_archived`, and 5 structured transformation-promise fields (`cliente_ideale`, `risultato`, `tempo`, `pain`, `metodo`)
- Extended `offer_micros` with `tier_letter` (A/B/C, CHECK-constrained at SQL level) and `public_price` (numeric)
- Added new `offer_tier_services` junction table (tier <-> unified `services` catalog), its relations, and `OfferTierService`/`NewOfferTierService` types — without touching the legacy `offer_micro_services`/`offer_services` tables
- Hand-wrote idempotent, additive-only migration `0008_offer_tier_schema.sql` (11 `ADD COLUMN IF NOT EXISTS` statements, guarded DO-block CHECK constraint, `CREATE TABLE IF NOT EXISTS offer_tier_services` + index), appended journal entry
- Created `scripts/push-12-offer-tier-schema.ts` — idempotent push script with PRODUCTION DEPLOY NOTE documenting the BLOCKING manual prod-apply step required before Plan 02/Wave 3

## Task Commits

Each task was committed atomically:

1. **Task 1: Extend offer_macros and offer_micros, add offer_tier_services junction in schema.ts** - `11d6c11` (feat)
2. **Task 2: Hand-write migration 0008 SQL + journal entry + idempotent push script** - `89d15ee` (feat)

**Plan metadata:** (this commit, follows)

## Files Created/Modified

- `src/db/schema.ts` - Additive columns on offer_macros/offer_micros, new offer_tier_services table + relations + types
- `src/db/migrations/0008_offer_tier_schema.sql` - Hand-written additive/idempotent migration (ALTER TABLE ADD COLUMN IF NOT EXISTS, guarded CHECK constraint, CREATE TABLE IF NOT EXISTS, CREATE INDEX IF NOT EXISTS)
- `src/db/migrations/meta/_journal.json` - Appended entry for `0008_offer_tier_schema` (idx 8, following 0006 entry shape)
- `scripts/push-12-offer-tier-schema.ts` - Idempotent push script for Plan 02's BLOCKING production-apply step

## Decisions Made

- `tier_letter` validated via DB-level CHECK constraint (guarded DO block, idempotent) rather than a Drizzle-native enum/CHECK helper (unavailable in this pg-core version); Zod enum validation will be added at the server-action layer in Plan 03 as defense-in-depth (per plan's T-12-02 mitigation)
- `offer_tier_services` is a brand-new additive junction table (not a modification of `offer_micro_services`), pointing at the unified `services` catalog (Phase 11) rather than the deprecated `offer_services` table, per D-6/D-3

## Deviations from Plan

None - plan executed exactly as written. The acceptance-criteria grep counts for `tier_letter`/`public_price`, the 6 transformation/archive columns, and the DROP/TRUNCATE/RENAME check show slightly higher raw match counts than the plan's exact numbers because explanatory comment blocks (explicitly requested by the plan, e.g. "Add a comment block directly above offer_macros documenting...") also contain those words (e.g. a comment mentions "tier_letter" when describing the CHECK constraint, and the migration's header comment says "No drops/truncates"). All actual code definitions are present exactly once, the diff to `src/db/schema.ts` is purely additive (`git diff HEAD~2 -- src/db/schema.ts | grep '^-'` returns empty), and a line-anchored grep (`grep -inE "^\s*(DROP|TRUNCATE|RENAME)\b"`) confirms zero actual destructive SQL statements in the migration.

## Issues Encountered

A `cd /Users/simonecavalli/Vault/IAMCAVALLI` in one intermediate Bash call caused a transient cwd drift into the main repo's worktree (sibling path with the same relative structure), which produced false "0 matches" results for one verification pass. Re-ran all verification from the correct worktree root (`/Users/simonecavalli/Vault/IAMCAVALLI/.claude/worktrees/agent-ab7d5b1ee10efadff`) with confirmed correct results before committing. No files were affected — all Edit/Write operations used relative paths inside the worktree.

## User Setup Required

None - no external service configuration required. Note: migration 0008 and the push script are created here only; per the plan and project memory, the actual production apply (SSH+docker exec) is Plan 02's BLOCKING step and is NOT performed in this plan.

## Next Phase Readiness

- `src/db/schema.ts` compiles cleanly (`npx tsc --noEmit` passes, zero errors) and exposes all Phase 12 additive columns/table/types needed by Plan 03's query layer and server actions
- Migration 0008 + push script are ready for Plan 02 to apply to production via SSH+docker exec before Wave 3 code reads `offer_tier_services`/`tier_letter`/`public_price`/`category`/`ticket`
- No existing table/column was dropped, renamed, or altered destructively — `clients`/`projects`/`payments`/`phases` and legacy offer tables (`offer_micro_services`, `offer_services`) remain byte-identical

---

*Phase: 12-offer-composition-drag-drop-csv-import*
*Completed: 2026-06-14*

## Self-Check: PASSED

All created/modified files verified present on disk:

- FOUND: src/db/schema.ts
- FOUND: src/db/migrations/0008_offer_tier_schema.sql
- FOUND: src/db/migrations/meta/_journal.json
- FOUND: scripts/push-12-offer-tier-schema.ts
- FOUND: .planning/phases/12-offer-composition-drag-drop-csv-import/12-01-SUMMARY.md

All task commits verified present in git log:

- FOUND: 11d6c11 (Task 1)
- FOUND: 89d15ee (Task 2)
- FOUND: bfc9932 (docs: complete plan)
