Phase 1: Rails API substrate v2 refactor

[dadachi]

Summary

Phase 1 of the substrate v2 transformation — turns this Rails API from a queue-specific template (NFC/QR/scan flows, A001-style queue numbers, 7-tier queue-operator roles) into a generic single-resource CRUD substrate (Shop → ItemTag with name/description/position and a binary state) that nativeapptemplate-agent can rename and re-skin for any domain.

Design context: docs/nativeapptemplate-substrate-v2-overview.md. Step-by-step plan: docs/phase1-rails-api.md.

Scope: 21 commits, 82 files, +397 / −1686 lines. No DB-data migration required — existing roles jsonb keys for removed roles are silently ignored.

What changed

ItemTag schema

• Renamed queue_number → name (NOT NULL, no uniqueness constraint)
• Added description (text, nullable), position (integer, nullable), composite index on (shop_id, position)
• Removed scan_state, customer_read_at, already_completed, plus the (shop_id, queue_number) unique index

Models

• ItemTag: dropped enum :scan_state + AASM block, scan_tag!, complete_tag!, reset!, queue-format/uniqueness validations, turbo_stream callbacks; kept AASM :state (complete/idle events) and the limit_count validation
• Shop: dropped latest_completed_item_tag, create_default_item_tags! (A001-A010 generator), reset!, full_reload_entire_page. New after_create :create_sample_item_tag creates exactly one "Sample" ItemTag for first-run UX (rescue-logged so failure doesn't block Shop creation)
• AccountsShopkeeper::ROLES: [:admin, :senior_manager, :junior_manager, :senior_member, :junior_member, :guest] → [:admin, :member]

API surface

• Removed: POST /scan, GET /scan_customer, the entire display/ namespace, DELETE /shops/:id/reset, app root route + static controller
• Renamed: PATCH /item_tags/:id/reset → /idle (matches AASM event name; clearer separation from "delete")
• Same shape, new fields: POST /shops/:id/item_tags accepts { "item_tag": { "name", "description", "position", "state" } }; name is the only required field
• New behavior: creating a Shop auto-creates 1 "Sample" ItemTag (was 10 A00x queue numbers)

Roles & Permissions

	admin	member
create_shops	✓	✓
update_shops	✓	✓
delete_shops	✓	✓
update_organizations	✓
invitation	✓
read_data	✓	✓

Collaborative SaaS model (Notion/Linear/Trello-style): both tiers can freely CRUD resources; only admin can manage org and invite members. Rationale in overview §6.10–6.11.

ItemTagPolicy resolves to Shop permissions — no separate ItemTag permissions exist.

State machine

AASM :state with complete (idled → completed) and idle (idled/completed → idled) events. Controller actions inline the state transitions and completed_by/completed_at writes — no *_tag! wrapper methods on the model, so the agent's identifier rename (e.g. ItemTag → Todo) doesn't have to rewrite method bodies.

Cascading cleanup

• Removed lib/tasks/shop.rake (only task was create_default_item_tags)
• Removed orphan app/views/layouts/display.html.erb
• Removed stale docs/pagination-item-tags.md (pagy is wired in the controller, doc was pre-implementation notes)
• Madmin resources updated to expose new ItemTag attributes and 2-tier role booleans
• Locales: "number tag(s)" → "item tag(s)", attribute labels updated, removed-validation error keys dropped
• OpenAPI spec (docs/openapi.yaml) regenerated to match (-90/+31)
• Brakeman.ignore fingerprint refreshed (the dynamic permit(*ROLES) line gets a new fingerprint when the constant changes; same intentional rationale)

Test plan

• bin/rails test → 358 runs, 705 assertions, 0 failures, 0 errors
• bin/ci → all 6 steps green (Setup, Style: Ruby, Security: Gem audit, Security: Brakeman, Tests: Rails, Tests: Seeds)
• Fresh DB rebuild verifies counts:

  bin/rails db:drop db:create db:migrate && bin/rails db:seed_fu
  bin/rails runner "puts [Permission.count, Role.count].inspect"  # => [6, 2]

• Manual API smoke test:
  • Sign in, create a shop → response includes the 1 auto-created "Sample" item_tag
  • POST /api/v1/shopkeeper/shops/:id/item_tags with { "item_tag": { "name": "Buy milk" } } → 201, response uses name not queue_number
  • PATCH /api/v1/shopkeeper/item_tags/:id/complete → state becomes completed, completed_at set
  • PATCH /api/v1/shopkeeper/item_tags/:id/idle → state back to idled, completed_at cleared
  • DELETE /api/v1/shopkeeper/item_tags/:id → 200
• iOS / Android client tracking issues opened for: queue_number → name rename, removed scan/QR screens, role UI collapse to 2 tiers, reset route → idle rename (these are Phase 2–5 of the substrate v2 plan)

Rollback

Pre-refactor state preserved at tag v1.0.0-with-nfc and branch v1-with-nfc. To revert:

git checkout v1-with-nfc