Tag Classification Bulk Update

Overview

Maintain mappings of product tags to categories — creating Tag ICEs (IAO) with the IAO is_about relation linking them to MaterialArtifact collections. Bulk operations enable operational efficiency. Tag ICEs drive analytics, Agent Role Assignments, and performance groupings.

Goal: Insert/update many (category_name, tag_name) Tag ICE mappings at once while maintaining the uniqueness invariant.

Main success scenario

[CCO: Act creating ICEs | IAO: is_about relation to MaterialArtifact collections]

1. Person bearing Ops/Creative Role selects tags and categories in the UI
2. UI calls POST /api/tag-classifications/bulk with Tag ICE mapping list
3. API validates input, performs chunked upsert into tag_content_entity (UNIQUE(category_name, tag_name))
4. API optionally enqueues analytics refresh ProcedureExecution if cached aggregate tables exist

DTOs

Request:

{
  "mode": "upsert",
  "mappings": [
    { "category_name": "Theme", "tag_name": "floral" },
    { "category_name": "Theme", "tag_name": "abstract" },
    { "category_name": "Device", "tag_name": "iphone-16" }
  ]
}

Response:

{
  "updated": 120,
  "created": 34,
  "errors": []
}

API endpoints

• POST /api/tag-classifications/bulk — bulk upsert of Tag ICEs
• GET /api/tag-classifications/unclassified — tags not yet represented by any Tag ICE

Both protected by CF Access. CRUD target: p99 < 200ms for normal payloads.

Exception flows

IssueOccurrence	FallbackStep
Conflicting category updates	Define “move tag from A→B” semantics (delete prior Tag ICE + insert new)
PlanetScale limits	Chunk to < 100k rows per statement
Large payloads exceeding CRUD latency	Accept request quickly, process async if payload exceeds threshold

Acceptance criteria

• PASS: After bulk call, Tag ICEs appear in correct category; unclassified endpoint excludes them
• FAIL: Duplicate Tag ICEs; missed inserts; inconsistent uniqueness