MineGeo/docs/map-community.md

Map reactions, comments, and account reports

Published map pages include a community panel. Visitors can read comments and see like/dislike totals. Active signed-in accounts can post comments of 1–2,000 characters, like or dislike a map, and submit reports. Clicking the selected reaction clears it; choosing the other reaction replaces it. Each account has one reaction per map.

Users can report a comment or its author, or report the map creator from the reaction bar. Reasons include Spam, Advertising, Inappropriate content, Harassment, and Other. Reports require a 10–2,000-character explanation. Only one open report per reporter and target is allowed.

Moderators and admins can remove comments directly on map pages or from Comment and account reports in their staff tools. Removal hides the comment publicly while preserving its body and reviewer for staff investigation. Staff resolve or dismiss reports with a decision reason. Reports never automatically remove comments, add map strikes, or ban accounts. Existing account controls remain responsible for account restrictions.

Setup and verification

Apply supabase/migrations/20261017073500_map_community_features.sql before deploying the application. This adds map_reactions, map_comments, community_reports, and map_reaction_summary. All tables enable RLS and restrict access to the server service role. Browser and device-token clients cannot directly read or write these tables. The server routes validate browser sessions, active account status, published-map visibility, and staff roles.

• node --import tsx --test tests/community.test.ts — validation, authentication, moderator authorization, scoped reactions, reporting and review conflicts.
• node scripts/test-community-sql.mjs — applies the full migration history in isolated PGlite and verifies constraints, counts, duplicates, deletion, and privileges. Uses the same optional .data/sql-verification runtime as the existing SQL suites.

API

• GET /api/v1/maps/:id/community: totals, current viewer/reaction, newest visible comments (30 per page), and nextCursor. Pass the URL-encoded cursor as ?cursor=... for the next page.
• POST /api/v1/maps/:id/reaction: { "value": -1 | 0 | 1 }.
• POST /api/v1/maps/:id/comments: { "body": "..." }.
• DELETE /api/v1/community/comments/:id: staff-only soft removal.
• POST /api/v1/community/reports: { "target": "comment" | "account", "targetId": "UUID", "category": "spam" | "advertising" | "inappropriate" | "harassment" | "other", "reason": "..." }.
• GET /api/v1/moderation/community-reports: staff-only open queue (50 per page), including comment evidence/account identity and nextCursor. Pass the URL-encoded cursor as ?cursor=... for the next page. Timestamp/ID cursors avoid skipping items when earlier comments are removed or reports resolved.
• PATCH /api/v1/moderation/community-reports/:id: staff-only { "decision": "resolved" | "dismissed", "reason": "..." }. Reviews atomically require the report to remain open.

Responses are not cached. Posting is limited per account to 10 comments per 10 minutes, 10 reports per hour, and 120 reaction changes per minute. Existing origin checks apply to every mutation.