docs(comments): design of record for comments, ratings & reviews - #199
Merged
Conversation
Scopes the last WP-parity platform gap as ONE core module, off by default. The organising decision: **a review IS a comment with a rating**. One `comment` table with a nullable `rating` — a blog comment is rating=null, a product review is rating=4, a vendor's reply is parent_id set. Not two tables, not two moderation queues, not two spam paths. If a `review` table ever appears, §0 is what to re-read. It attaches to ANYTHING through a subject-provider registry (Tiger_Comment::registerSubject), modeled on the Tiger_Search / Tiger_Audience seams rather than free-string subject types — because core has to render a title and link, gate reads on the SUBJECT's ACL resource, know whether stars even apply to that kind of thing, and find orphans when a subject is deleted. None of that is possible from a bare string. Two details worth the ink: the aggregate table is not premature optimisation (a 60-card marketplace grid would otherwise be 60 AVG() queries), and "5 stars with half stars" means whole-star INPUT with half-star DISPLAY of averages — halves come from averaging, not a half-star picker. The door to half-star input stays open as a TINYINT 1-10 with no schema redesign. The differentiator scoped here is not the stars, it's the **verified reviewer**: Tiger has an entitlement oracle (the licence authority, an order, a membership grant), so "every review is from someone who bought it" is a claim WordPress structurally cannot make. The flag ships in v1 even if only the shop uses it, because retrofitting a trust flag onto existing rows is the hard version. Off by default (tiger.comment.enabled), same posture as /mcp: an open comment endpoint is the most-attacked surface a CMS has, and a brochure site shouldn't inherit one it never asked for.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Scopes the last WP-parity platform gap as one core module, off by default. Design only — no code.
The organising decision
A review IS a comment with a rating. One
commenttable, nullablerating:rating = nullrating = 4parent_idset,rating = nullbody = '',rating = 5One store, one moderation queue, one spam path, one admin screen. If a
reviewtable ever appears, §0 is what to re-read.Attach to anything
A subject-provider registry (
Tiger_Comment::registerSubject), modeled on the existingTiger_Search/Tiger_Audienceseams — not free-string subject types. Core needs to render a title and link, gate reads on the subject's own ACL resource, know whether stars apply to that kind of thing at all, and find orphans when a subject is deleted. A bare string gives none of that.Built-ins for
pageandblog.post; everything else (shop product, marketplace listing, profile) opts in.Two details worth the ink
AVG()queries per render.TINYINT1–10 later, no schema redesign.The differentiator isn't the stars
It's the verified reviewer. Tiger has an entitlement oracle — the licence authority, an order, a membership grant — so "every review here is from someone who bought it" is a claim WordPress structurally cannot make. The flag ships in v1 even if only the shop uses it at first, because retrofitting a trust flag onto existing rows is the hard version.
Off by default
tiger.comment.enabled, same posture as/mcp. An open comment endpoint is the most-attacked surface a CMS has; a brochure site shouldn't inherit one plus a standing moderation duty it never asked for.Wired into
CLAUDE.md,AGENTS.mdandBACKLOG.md. Fills the rating overlay a marketplace already publishes (TigerMarketplace/docs/design/reputation.md§8) and which is currently always zero.