Yahoo Registration Runbook

Task: F.2 — Yahoo mall (mall_id=4) enablement runbook
Sprint: Sprint 45 (8656_apply_yahoo_mall_data)
Applies to: tv-api (this repo)

Overview

This runbook covers the steps required to safely enable Yahoo Shopping (mall_id=4) in the wishlist domain. Follow each step in order.

Pre-deploy checklist

1. Verify malls.id=4 is unused in production

Before deploying, confirm that no existing rows in the malls table have id=4:

-- Run on production DB (read-only replica preferred)
SELECT id, slug, name FROM malls WHERE id = 4;
-- Expected result: Empty set (0 rows)

If id=4 already exists with a different slug, STOP — contact the DBA team before proceeding.

2. Verify migration is ready

php artisan migrate:status | grep seed_yahoo_mall_idempotent

Expected: Pending (the migration has not yet run).

Deployment steps

Step 1: Run migrations

php artisan migrate

This runs 2026_05_26_000003_seed_yahoo_mall_idempotent.php, which inserts the Yahoo mall row idempotently:

INSERT INTO malls (id, slug, name, created_at) 
VALUES (4, 'yahoo', 'Yahoo', NOW())
ON DUPLICATE KEY UPDATE id = id;

Step 2: Verify the Yahoo row

SELECT id, slug, name FROM malls WHERE id = 4;
-- Expected: 4 | yahoo | Yahoo

Step 3: Idempotency check

Re-run the migration (or the seeder):

php artisan migrate
# or
php artisan db:seed --class=MallSeeder

Expected: No errors, no duplicate rows.

Post-deploy verification

Verify endpoints accept Yahoo inputs

Yahoo URL registration (temp wishlist):

curl -X POST /api/v1/general/temp-wishlist-to-group \
  -H "Authorization: Bearer {token}" \
  -d '{
    "wishlist_products": [
      { "input": "https://store.shopping.yahoo.co.jp/shop/abc123/", "input_type": "yahoo_id", "mall_id": 4 }
    ]
  }'
# Expected: 200 with mall_id=4 in response

Yahoo JAN registration:

# input_type=jan with mall_id=4 routes to Yahoo
{ "input": "4901234567890", "input_type": "jan", "mall_id": 4 }

Verify product_type=yahoo_only filter

GET /api/v1/general/wishlist-to-group/{wltg_slug}/grouped-wishlist-products?product_type=yahoo_only
# Expected: Only groups containing Yahoo (mall_id=4) products

Verify copy DS preserves Yahoo

When copying a dataset containing Yahoo products, confirm the resulting temp dataset includes all Yahoo products with mall_id=4 unchanged.

Rollback procedure

If issues are found post-deploy:

1. The 2026_05_26_000003_seed_yahoo_mall_idempotent.php migration inserts a row — rollback removes it:

   php artisan migrate:rollback --step=1
   

2. Existing wishlist_products rows with mall_id=4 (if any were inserted) will lose their FK reference if the malls row is removed. Coordinate with the DBA team if any data was already written.

3. The fourth_wishlist_product_id migration (2026_05_26_000001) is independent — it adds a column and does not need to be rolled back for Yahoo.

Related documentation

• docs/en/02.general/09.dataset-workflow/ — draft → finalize → sync background
• contracts/api-contracts.md — frozen API contracts for this change
• ADR-003 — subscription quota rules (mall-agnostic)
• ADR-004 — additive compatibility rule (no field removal/renaming)