F 04 Catalog Setup

Status: 🟢 ready to test Owner: Adilet Last updated: 2026-05-08 Last verified on production: —

Goal

An admin sets up the catalog tree (Organization → Product → Product Version) that test cycles attach to. This flow is the prerequisite for every cycle creation.

Actors

• Primary — Admin

Preconditions

• Admin is signed in.
• (Optional) Production already has the seeded Hackorda organisation, Hackorda Web product, and v0.1.0 version — for an additional setup, you start from this baseline.

Trigger

Admin clicks "New" on /app/admin/organizations (or /products / /products/:id versions panel).

Happy path — Step 1: create organization

Happy path — Step 2: create product

Happy path — Step 3: create product version

Acceptance criteria

• AC-1 — Given the admin fills a unique slug, when they submit the org form, then a row is inserted and the slug is enforced unique.
• AC-2 — Given the admin tries to create a product without selecting an organisation, when they submit, then the form blocks with a validation error.
• AC-3 — Given a product is configured with payoutRequiresVerification = true, when later cycles inherit, then the verification gate is active by default for issues filed under those cycles (see F-10).
• AC-4 — Given the admin enters a version string identical to an existing version on the same product, when they submit, then the API returns 400 (unique on (product_id, version)).
• AC-5 — Given the org / product / version are created, when the admin opens /app/admin/test-cycles/new, then the new entries appear in the dropdowns.

Test data / fixtures

Baseline seed not required — this flow creates the catalog tree. Use a unique slug like e2e-test-org to avoid colliding with seeded data.

Negative paths

Manual QA checklist

• Create a new Organization with slug qa-test-org
• Confirm it appears in the list
• Open the org detail page — basic info renders correctly
• Create a Product under it: name QA Test Product, slug qa-test-product, URL https://example.com, discipline web_app, verification gate ON
• Confirm the product card shows the URL link and discipline
• Create version v0.1.0 for the product
• Confirm version appears in versions panel
• On /app/admin/test-cycles/new, confirm the new product + version are pickable
• (Cleanup) Delete the version → product → organization (verify cascade or restrict behavior matches policy)

Automated test outline

test.describe("F-04 catalog setup", () => {
  test("creates org → product → version end-to-end", async ({ page, request }) => { … });
  test("rejects duplicate org slug", async ({ request }) => { … });
  test("blocks non-admin", async ({ request }) => { … });
});

Code references

• Pages: src/app/app/admin/organizations/page.tsx, src/app/app/admin/products/page.tsx
• API:
  • src/app/api/admin/organizations/route.ts (GET, POST)
  • src/app/api/admin/organizations/[id]/route.ts (GET, PATCH, DELETE)
  • src/app/api/admin/products/route.ts
  • src/app/api/admin/products/[id]/route.ts
  • src/app/api/admin/products/[id]/versions/route.ts
• Hooks: src/hooks/test-cycles/organizations.ts, src/hooks/test-cycles/products.ts
• Schema: organizations, products, product_versions

Events emitted (proposed)

• org.created — { org_id, slug, type, created_by }
• org.updated — { org_id, fields_changed }
• org.deleted — { org_id }
• product.created — { product_id, org_id, slug, discipline, gate_default }
• product.updated, product.deleted — analogous
• product_version.created — { version_id, product_id, version_string }

Open questions / known gaps

• No multi-tenant isolation: every admin sees every org. (Single-tenant by design for v1; flagged in feature-matrix.md §3.1.)
• No org logo / branding upload yet.
• Product integration_provider_slug + integration_config columns exist but the only wired provider is Linear (F-15).