Admin Frame Status Report

Generated May 14, 2026 · threads-api-v2 @ workspace

Migration

Report + bannedUntil

Admin modules

DTO/Input frame

Queue riêng

auto_remove_ban_queue

Checks

validate · generate · typecheck

Highlights

Frame-first implementation. Admin routes now have typed external DTOs and internal input interfaces, while service orchestration remains intentionally marked as TODO for later business logic.
Repository stays data-access focused. Repositories expose DB create/find/update/count/aggregate methods; they do not decide moderation outcomes such as approve, hide, or delete.
Dedicated BullMQ queue added. Auto-remove-ban has its own queue, producer, queue events file, and worker so it can be monitored separately from like/email/bloom/pinecone jobs.
No old HTML docs were removed. This file was added as a new report and linked from the docs hub.

Change Ledger

Area	Action	Technical change	Why	Risk
`prisma/schema.prisma`	modified	Added `User.bannedUntil`, `ReportTargetType`, `ReportStatus`, and `Report`.	Gives the admin frame durable tables/fields without inventing service behavior yet.	Med
`prisma/migrations/20260514120000...`	added	Adds `banned_until`, report table, indexes, and reporter foreign key.	Migration keeps database change explicit and reviewable.	Med
`report-management/dto`	added	External body DTO contains `action` and `adminNote`.	These values come from HTTP body, so they belong in DTO, not internal input.	Low
`report-management/interfaces`	added	`ModerateReportInput` enriches DTO with `reportId` and `adminId`.	Params/JWT values are internal context, not client body data.	Low
`report-management.repository.ts`	modified	Replaced no-op stub with `create`, `findById`, and `updateById`.	Repository now only exposes DB operations. It does not decide what approve/hide/delete means.	Low
`report-management.service.ts`	modified	Returns frame response with report lookup and clear `nextStep` TODO.	Keeps route usable while leaving core moderation orchestration for later service work.	Low
`user-management/dto`	added	External ban DTO accepts optional `bannedUntil` and `durationHours`.	Both values are caller-provided request data, so they are DTO-level.	Low
`user-management/interfaces`	added	Internal inputs add `userId`, `adminId`, normalized `Date`, and expired-ban update data.	These values are enriched by params/JWT/job runtime.	Low
`user-management.repository.ts`	modified	Added DB update methods for ban fields and expired banned users; selected `bannedUntil` in list users.	Needed DB primitives for later service logic and hourly worker frame.	Med
`hashtag-trending`	modified	Added query DTO/input and repository query ordered by `Topic.count desc`.	Turns the route from stub into a DB-backed frame with a normalized limit.	Low
`statistics`	modified	Added query DTO/input and repository aggregate/count queries for posts, users, reports, hashtags, and posts per day.	Stats endpoint now has real DB reads, while shaping policy can still evolve in service later.	Med
`src/constants/queue.ts`	modified	Added `AUTO_REMOVE_BAN_QUEUE`, `AUTO_REMOVE_BAN_WORKER`, and `RUN_AUTO_REMOVE_BAN`.	Matches the existing queue constant pattern and keeps monitoring names stable.	Low
`auto-remove-ban producer`	added	Creates a dedicated queue and registers an hourly repeat job with stable job id.	Separate queue makes remove-ban jobs visible apart from like sync jobs.	Med
`workers/auto-remove-ban.worker.ts`	added	Consumes `RUN_AUTO_REMOVE_BAN`, builds internal input, and calls the DB update hook.	Worker frame is ready; final service flow can replace the direct call later.	Med
`queues/auto-remove-ban.queue.ts`	added	Adds BullMQ `QueueEvents` logging for waiting/active/completed/failed.	Follows the existing queue event file format for observability.	Low
`src/server.ts`	modified	Initializes auto-remove-ban repeat job after like sync scheduler init.	Ensures scheduler registration happens at app startup using the repo's current pattern.	Med
`docs/index.html`	modified	Added this report card, updated counts, and mapped an icon.	Keeps the docs hub complete without deleting old docs.	Low

DTO vs Internal Input

Module	DTO: outside data	Input: enriched internal data
`report-management`	`action`, `adminNote` from request body.	`reportId` from params, `adminId` from JWT, plus body fields.
`user-management`	`bannedUntil`, `durationHours` from request body.	`userId` from params, `adminId` from JWT, parsed `Date`.
`hashtag-trending`	`limit` from query string.	Normalized numeric `limit` with default 10.
`statistics`	`startDate`, `endDate` from query string.	Parsed optional `Date` range for DB aggregate queries.
`auto-remove-ban`	`triggeredBy`, `requestedAt` from job payload.	`now`, `jobId`, and normalized trigger metadata inside worker.

Name Glossary

Name	Definition	Where it appears
`bannedUntil`	Temporary-ban expiry time. If this Date is in the past, auto-remove-ban can move the user back to `ACTIVE`. If it is missing/null, the ban has no scheduled expiry in the current frame.	User DTO, user input, Prisma `users.banned_until`
`durationHours`	Relative ban length sent by a caller. It is stored in input for later service logic to convert into `bannedUntil`.	`BanUserRequestDto`, `BanUserInput`
`adminId`	Authenticated admin user id from JWT context. This is not body data; it is internal metadata for future audit logs.	Report and user-management inputs
`adminNote`	Human explanation written by an admin while handling a report. Later service logic can persist it to `reports.admin_note`.	Report DTO/input
`action`	Requested moderation action from outside: `approve`, `hide_post`, or `delete_post`. Repository receives only DB data; service will decide how this action maps to writes.	Report DTO/input
`targetType`	Type of reported entity. Current allowed values are `POST` and `USER`.	Prisma `Report`
`targetId`	Identifier of the reported entity. It is a string so it can point to either a post public id or a user id depending on `targetType`.	Prisma `Report`
`ReportStatus`	Moderation queue state: `PENDING` for new reports, `RESOLVED` for handled reports, `DISMISSED` for future reject/ignore flows.	Prisma enum, stats repository
`AutoRemoveBanJobDto`	Serialized BullMQ payload saved in Redis. It is treated like external data because producer and worker communicate through the queue boundary.	Auto-remove-ban producer/worker
`AutoRemoveBanInput.now`	Worker runtime Date used in the DB query `bannedUntil < now`.	Auto-remove-ban worker input
`triggeredBy`	Source of the auto-remove-ban job. Currently `scheduler`; `manual` is reserved for future admin-triggered jobs.	Auto-remove-ban job DTO/input
`jobId`	BullMQ id for the current job. Used only for logging/correlation.	Auto-remove-ban worker input

Auto-Remove-Ban Queue Flow

No per-user delayed job is added at ban time. Current frame uses one hourly scanner. If later service logic needs immediate delayed remove-ban per user, add that job at the end of the ban service after DB commit.

Removed or Deferred

Removed

No files were deleted. Stub response flags like implemented: false were removed from admin service responses where a clearer frame response now exists.

Deferred

Moderation decisions for approve, hide_post, and delete_post are not implemented yet. Add that orchestration in report-management.service.ts.

Deferred

durationHours is captured in DTO/input but not converted into bannedUntil yet. Add that rule in user-management.service.ts.

Deferred

Auto-remove-ban worker currently calls the repository DB hook directly. When the service flow is ready, move this call behind service orchestration and keep the worker as trigger/input builder.

Verification

Command	Result	Notes
`npx prisma validate`	Passed	Schema loaded from `prisma/schema.prisma` and validated successfully.
`npm run db:generate`	Passed	Prisma Client v7.8.0 generated so TypeScript can see new model/enum fields.
`npm run typecheck`	Passed	`tsc -p tsconfig.json --noEmit` completed without errors.