Declaration Smoke Runbook

This runbook covers the current local operator smoke path for:

• auction declaration flow
• tender declaration flow

It is written against the current local runtime chain and current declaration semantics.

Required local services

The expected local dev chain is:

• apps/web -> http://localhost:3000
• services/api -> http://localhost:4001
• services/svc-auth -> http://localhost:4100
• services/svc-tenders -> http://localhost:4020
• postgres -> postgres://kvary:kvary@127.0.0.1:5432/kvary
• minio object storage -> http://localhost:9000
• minio console -> http://localhost:9001

Recommended startup path:

npm run dev

Required DB migrations must already be applied.

Evidence upload/download also assumes MinIO is up and healthy.

Relevant declaration/evidence migrations include:

• auction declaration workflow/state migrations
• 0033_auction_registry_internal_states.sql
• 0034_auction_declaration_evidence.sql
• 0035_output_allocations_v1.sql
• 0036_link_auction_declarations_to_allocations.sql
• 0037_tender_declarations_v1.sql
• 0038_tender_declaration_evidence.sql

Required test user roles

Use a live auth user with one of these roles:

• AUCTION_DECLARER
  • auction declaration only
• MARKET_DECLARER
  • both auction and tender declaration

Current live auth note:

• TENDER_DECLARER is not currently mapped in svc-auth
• MARKET_DECLARER is the practical combined role for full smoke coverage

After changing auth_accounts.role:

1. restart svc-auth if code changed
2. sign out / sign in again to mint a fresh token

Auction happy path

A. Create allocation

Open:

• /en/global/allocations

Create an allocation with at least:

• allocationId
• stakeholderId
• productiveAssetId
• assetType
• productName
• productCategory
• quantity
• unit
• originRegion

Save the allocation.

Expected:

• allocation appears in internal allocation list
• operator can edit it
• operator sees action to launch declaration

B. Launch auction declaration from allocation

From allocation workspace/list, launch:

• Create Auction Declaration

Expected:

• route opens:
  • /en/global/auctions/declare?allocationId=<id>
• declaration form is prefilled from allocation
• suggested auctionId is prefilled
• operator can still edit the suggested auctionId before first save

C. Save draft

Required minimum:

• auctionId present

Expected:

• draft save succeeds
• declaration state stays:
  • DRAFT

D. Upload evidence

Go to evidence step.

Expected:

• before first save: uploader explains that a saved draft is required
• after save: upload is enabled
• upload works for supported file types
• evidence list shows:
  • file name
  • group key
  • MIME type
  • size
  • upload time
  • download action

E. Check readiness

Click:

• Check Readiness

Expected:

• readiness panel shows:
  • blocking errors
  • warnings
  • checklist
• current state remains:
  • DRAFT

F. Mark ready

Complete required fields and click:

• Mark Ready

Expected:

• state becomes:
  • READY_FOR_ANNOUNCEMENT

G. Declare

Click:

• Declare Auction

Expected:

• state becomes:
  • ANNOUNCED
• public auction registry can now show it

H. Visibility expectations

Internal auction view:

• can show:
  • DRAFT
  • READY_FOR_ANNOUNCEMENT
  • ANNOUNCED

Public auction view:

• must not show:
  • DRAFT
  • READY_FOR_ANNOUNCEMENT
• can show:
  • ANNOUNCED
  • later public lifecycle states

Tender happy path

A. Open tender declaration

Open:

• /en/global/tenders/declare

B. Use UUID-compatible tender id

Current tender registry still expects UUID-compatible tenderId.

Use one of:

• the suggested ID if present
• a valid UUID manually

Example:

77777777-7777-4777-8777-777777777777

Do not use free-form non-UUID ids in current tender flow.

C. Save draft

Expected:

• draft save succeeds
• state stays:
  • DRAFT

D. Upload evidence

Go to tender evidence step.

Expected:

• saved draft required before upload
• evidence list/download works after save
• evidence groups are tender-specific:
  • supportingDocuments
  • specificationEvidence
  • complianceEvidence

E. Check readiness

Click:

• Check Readiness

Expected:

• readiness panel shows procurement-specific blockers, warnings, checklist

F. Mark ready

Click:

• Mark Ready

Expected:

• state becomes:
  • READY_FOR_ANNOUNCEMENT

G. Declare

Click:

• Declare Tender

Expected:

• state becomes:
  • ANNOUNCED

H. Visibility expectations

Internal tender view:

• can show:
  • DRAFT
  • READY_FOR_ANNOUNCEMENT
  • ANNOUNCED

Public tender view:

• must not show:
  • DRAFT
  • READY_FOR_ANNOUNCEMENT
• can show:
  • ANNOUNCED
  • later public lifecycle states

Expected state transitions

Auction declaration

• DRAFT -> READY_FOR_ANNOUNCEMENT -> ANNOUNCED

Tender declaration

• DRAFT -> READY_FOR_ANNOUNCEMENT -> ANNOUNCED

No direct DRAFT -> ANNOUNCED path is expected in current v1 behavior.

Known caveats

Runtime alignment

Current local chain assumes:

• web -> 4001
• gateway/internal proxy -> 4020
• tenders service -> 4020

If env points to stale or wrong ports, list and declaration behavior can look broken even when DB state is correct.

Tender UUID requirement

Current tender declaration path still requires UUID-compatible tenderId because tenders.tender_id remains UUID-backed in the live schema.

This is a known current constraint.

Restart required after env/auth changes

If env changes:

• restart the affected process

At minimum:

• web env change -> restart apps/web
• API env change -> restart services/api
• tenders env change -> restart services/svc-tenders
• auth env/role mapping change -> restart services/svc-auth

If user role changes:

• sign out / sign back in to refresh token permissions

Internal/public behavior is deliberate

Draft and ready states are internal/operator-only by design.

If an operator says “it saved but I cannot see it publicly”, first verify whether they are looking at:

• internal registry
• or public registry