ADR-0036: Admin Bulk Actions – One /bulk Endpoint per Resource, Per-Row Calls to Existing Services¶
Metadata¶
Status: Accepted (2026-11-01) · Date: 2026-11-01 · Deciders: nguyenhuuca · Tags: api, frontend, convention Related PRD: PRD-admin-bulk-actions · Supersedes: N/A · Superseded By: N/A
Tech Strategy: ✅ Follows Golden Path (explicit admin controllers, layered Controller → Service → Repository, @AuditLog, @RateLimited, React Query mutations). No new dependency.
Context¶
- Only Comments has bulk today.
PATCH /admin/comments/moderationandPOST /admin/comments/hard-delete(AdminController.java:233-258) takeids(max 100,BulkModerateCommentRequest.MAX_IDS).AdminCommentServiceImpl.bulkModerateruns the whole batch in one@Transactional, treats business no-ops asunchanged, and returns counts plusnotFound. - The other tabs' rules live in single-row service methods, each
@Transactionalwith its own guards and side effects:AdminVideoServiceImpl.updateStatus / updateVisibility / deleteVideo–feedCache.invalidate(); delete also touches local/Drive files and HLS underdriveFileLocks.tryClaim.VideoCollectionServiceImpl.addVideo– PUBLISHED and not HIDDEN only, 500-item cap (409),requireManageable(own or PUBLIC-as-admin).AdminAccountServiceImpl.updateRole / updatePermissions / deleteAccount– no self change, actor outranks target and new role, autopilot bits SUPER_ADMIN only,credentialsVersionbump.VideoSuggestionServiceImpl.approve / reject– row lock, import-job creation (409 on duplicate), 503 when import is disabled,SuggestionReviewedEvent.VideoImportServiceImplcancel / retry – conditional updates, 409 on wrong state.
- Several of these can fail per row for legitimate reasons (409 state conflicts, locked files, outranked accounts). With comments' all-or-nothing transaction, one such row would roll back the rest.
- Frontend selection lives inside
AdminCommentTable.jsx(selectedSet,toggleAll, clear on page/filter change,.admin-bulk-bar). Five more tables need the same.
Decision Drivers¶
- Bulk must apply exactly the single-row rules (no second copy of business logic – Core Principle 5).
- One bad row must not undo the good ones; every skipped row must be reported with a reason.
- One HTTP request per bulk action (rate limit, audit, latency on a 1 vCPU VM).
- Consistent API and UI across tabs; small, independently mergeable tasks.
Considered Options¶
Option 1: Client loops over the existing single-row endpoints¶
- ✅ No backend work.
- ❌ N requests per action: N audit entries without a batch id, rate limits hit at 10–30/min, partial failure handling in every table, slow on mobile.
Option 2: Comments-style bulk – one transaction per batch, set-based logic in the service¶
- ✅ Atomic; one query for simple updates.
- ❌ Duplicates every guard in set form (role hierarchy, collection cap, Drive locks); one 409 rolls back the batch; delete/approve side effects (files, events, import jobs) do not fit one transaction.
Option 3: POST /admin/<resource>/bulk with an action discriminator; a bulk service calls the single-row method per id through its Spring proxy (chosen)¶
- ✅ Each row runs the existing single-row method → all guards and side effects reused unchanged; a row is exactly as atomic as that method (some are
@Transactional,AdminVideoServiceImplmethods are single repository calls). - ✅ Domain exceptions per row become
skipped[{id, code}]; other rows proceed. - ✅ One request, one
@AuditLogentry with the ids, one rate-limit permit. - ❌ N independent units of work instead of 1 (acceptable: N ≤ 100, in practice ≤ 20 = page size).
- ❌ Not atomic – by design; the result reports exactly what happened.
Decision Outcome¶
Chosen: Option 3.
API convention¶
| Resource | Endpoint | Actions |
|---|---|---|
| Videos | POST /admin/videos/bulk |
STATUS {status}, VISIBILITY {visibility}, DELETE {deleteLocalFile} |
| Collection items | POST /collections/{id}/videos/bulk |
add {videoIds} |
| Accounts | POST /admin/accounts/bulk |
ROLE {role}, GRANT_PERMISSION {permission}, REVOKE_PERMISSION {permission}, DELETE |
| Suggestions | POST /admin/video-suggestions/bulk |
APPROVE, REJECT {reason, note} |
| Imports | POST /admin/video-imports/bulk |
CANCEL, RETRY |
- Request:
{ ids: [..] (1–100, unique), action, ...params }, validated with@NotEmpty @Size(max = 100); action-specific params validated once before any row is touched (e.g. REJECT+OTHER needs a note,import disabled→ 503 for APPROVE). - Response:
ResultObjectInfo<BulkResultDto>withrequested,updated,unchanged,skipped: [{id, code, message}],notFound: [id]. - Every endpoint: class-level admin
@PreAuthorize,@HasPermission(perm = Permission.ADMIN),@AuditLog("bulk<Resource>"),@RateLimited(permit = 10). GRANT/REVOKE_PERMISSIONchange one bit server-side from the current mask (no stale client mask), then callupdatePermissions.- Bulk video delete never deletes Drive files (per-row only).
Backend structure¶
dto/admin/BulkRequestbase (ids + validation) and one request record per resource; sharedBulkResultDto+BulkResultCollector(counts, skipped, notFound).- One
*BulkServicebean per resource (AdminVideoBulkServiceImpl, …) that is not@Transactionalitself and calls the existing service interface per id throughBulkResultCollector.run(id, row), which owns the outcome mapping:true/false→updated/unchanged;ResourceNotFoundException→notFound;CustomException→skippedwith its i18n key and user-facing message;IllegalStateException→skippederror.conflict; anything else →skippederror.unexpected. OnlyCustomExceptiontext reaches the client; other messages are logged server-side only (CWE-209). - Lookups the bulk path relies on throw
ResourceNotFoundException(extendsIllegalArgumentException, so single-row endpoints keep their 400). - Single-row methods that currently cannot tell "changed" from "no-op" get a boolean return where needed (status, visibility); existing callers ignore it.
Frontend structure¶
hooks/useBulkSelection.js(Set, toggle, toggleAll(pageIds), clear onresetKeychange, max 100) andcomponents/admin/BulkActionBar.jsx(count, children actions, clear) +formatBulkResult()for the notice.AdminCommentTablemoves onto them first with no behavior change (Comments keep their existing endpoints and DTOs).
Quantified Impact¶
| Metric | Before | After |
|---|---|---|
| Requests to change 20 videos | 20 | 1 |
| Places holding role/collection/lock rules | 1 | 1 (unchanged) |
| Bulk-capable admin tabs | 1 (Comments) + Drive Sync | 6 |
Consequences¶
Positive¶
- Bulk is a thin orchestration layer; rule changes in single-row services apply to bulk automatically.
- Uniform result shape lets one notice component serve every tab.
Negative¶
- Not atomic: a crash mid-batch leaves the processed rows changed. Mitigation: per-row idempotent operations, result lists every id, the admin can rerun.
- N transactions and N
feedCache.invalidate()calls per batch. Mitigation: ≤ 100 ids; invalidation is a cheap flag.
Neutral¶
- Comments keep their atomic bulk endpoints; their semantics fit (no external side effects besides events).
Validation¶
- Unit tests per bulk service: mixed ids (ok / no-op / guarded / missing) → exact counts and codes; one row throwing does not affect the others.
- Permission tests per endpoint: 200 admin, 403 USER, 400 empty ids, 400 > 100 ids, 400 missing action param.
- Frontend: selection clear on page/filter change, kept on error, notice text from a mixed result.
Links¶
- PRD: PRD-admin-bulk-actions
- Sequence: sequence-admin-bulk-actions
- Plan: plan-admin-bulk-actions
- Prior art: plan-admin-comment-moderation; ADR-0035 (visibility enum)
Changelog¶
- 2026-11-01: Proposed.
- 2026-11-01: BK-1 review: typed not-found, shared outcome mapping in
BulkResultCollector.run, no raw exception text to clients; per-row "transaction" wording corrected. - 2026-11-01: Accepted by the owner (no Drive-file delete in bulk; Accounts checkboxes disabled for self/outranked).