feat(shared-data): per-review author key for seeding analysis

.gitignore

@@ -187,3 +187,7 @@ storageState*.json
 !*.env.js
 !*.env.mjs
 !*.env.d.ts
+# Reviewed DOS-Me migration proposal (DOS/Rate#1614): DDL only, no data, no credentials.
+!Docs/Proposals/2026-11-06-dos-me-review-author-keys.sql
+!Docs/Proposals/2026-11-06-dos-me-review-author-keys-rollback.sql
+!Docs/Proposals/2026-11-06-dos-me-review-author-keys-verify.sql

Docs/Proposals/2026-11-06-dos-me-review-author-keys-rollback.sql

@@ -0,0 +1,5 @@
+-- ROLLBACK the PROPOSAL 2026-11-06-dos-me-review-author-keys.sql (DOS/Rate#1614).
+-- Safe to run twice. The analyzer then groups authors by author_name again.
+BEGIN;
+DROP TABLE IF EXISTS rate.review_author_keys;
+COMMIT;

Docs/Proposals/2026-11-06-dos-me-review-author-keys-verify.sql

@@ -0,0 +1,26 @@
+-- VERIFY the PROPOSAL 2026-11-06-dos-me-review-author-keys.sql (DOS/Rate#1614).
+-- Read-only. V1 to V4 return 0.
+
+-- V1 the table exists with RLS on; expect 0
+SELECT count(*) FROM (SELECT 1) x
+WHERE NOT EXISTS (
+  SELECT 1 FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+  WHERE n.nspname = 'rate' AND c.relname = 'review_author_keys' AND c.relrowsecurity
+);
+
+-- V2 privilege matrix: anon and authenticated have nothing, rate_worker has no DELETE or
+-- TRUNCATE; expect 0
+SELECT count(*) FROM (VALUES
+  ('anon', 'SELECT'), ('anon', 'INSERT'), ('anon', 'UPDATE'), ('anon', 'DELETE'),
+  ('authenticated', 'SELECT'), ('authenticated', 'INSERT'), ('authenticated', 'UPDATE'),
+  ('authenticated', 'DELETE'), ('rate_worker', 'DELETE'), ('rate_worker', 'TRUNCATE')
+) AS t(role_name, priv)
+WHERE has_table_privilege(t.role_name, 'rate.review_author_keys', t.priv)
+   OR has_any_column_privilege(t.role_name, 'rate.review_author_keys', t.priv);
+
+-- V3 no stored key has a bad shape; expect 0
+SELECT count(*) FROM rate.review_author_keys WHERE author_key !~ '^[A-Za-z0-9_-]{16,128}$';
+
+-- V4 no key row points at a missing review; expect 0
+SELECT count(*) FROM rate.review_author_keys k
+WHERE NOT EXISTS (SELECT 1 FROM rate.reviews r WHERE r.id = k.review_id);

Docs/Proposals/2026-11-06-dos-me-review-author-keys.md

@@ -0,0 +1,56 @@
+# Per-review author key (DOS/Rate#1614)
+
+Status: **proposal, nothing applied.** The migration goes to DOS-Me; DOS/Rate never applies it.
+
+Rate-Services (DOS/Rate-Services#1073) masks `rate.reviews.author_name` and redacts contact data
+before the engine inserts reviews. The analyzer told authors apart by `author_name` for the
+duplicate-text and seeding checks, so masked names would merge many real authors. RS therefore
+sends a key per review and the analyzer groups by it.
+
+## Ingest contract (what RS sends)
+
+On each review of a `ScrapedProduct` (`reviews[]`):
+
+| Field       | Type   | Rule                                                                            |
+| ----------- | ------ | ------------------------------------------------------------------------------- |
+| `authorKey` | string | optional; 16 to 128 chars of `[A-Za-z0-9_-]`, else dropped (the review is kept) |
+
+- Recommended value: hex of `HMAC-SHA256(secret, normalised original author name)` (64 chars).
+  The secret stays in RS; Rate never sees it. Use one secret for all products and platforms so
+  the same author keeps one key. Not reversible.
+- The key is compared exactly (case-sensitive). Keep the normalisation in RS stable (for example
+  NFC, trimmed, lower-cased) so one author gets one key.
+- Absent key: the analyzer groups by `author_name` as before. Old rows keep working.
+- `author_name` is stored and shown as sent (masked or not). No UI change.
+
+## Storage
+
+`rate.review_author_keys (review_id, author_key, created_at)`, not a column on `rate.reviews`:
+anon has a table-level SELECT on `rate.reviews`, and a stable key would let anyone link one
+author's reviews across products. The new table is readable only by `service_role` and
+`rate_worker`. The importer upserts a row per keyed review after inserting the reviews (also for
+reviews already stored, so a later crawl backfills) and reads them for the analysis. A write or
+read failure logs a warning and the analysis falls back to `author_name`.
+
+## Analyzer
+
+`reviewAuthorIdentity` (apps/importer `ai-review-analyzer.ts`): `key:<author_key>` when present,
+else `name:<lower-cased author_name>`, else `id:<review id>`. Duplicate-text counts and the
+near-duplicate shingle pass use it. Scoring weights are unchanged.
+
+Limits: reviews stored before masking carry a raw name and get a key only when crawled again;
+until then they are one identity by name and a keyed copy of the same author counts as another.
+Unkeyed masked names ("N***n") can merge different authors. RS should send a key on every review.
+Do not rotate the HMAC secret or change the name normalisation: a crawl returns only a window of
+recent reviews, so old and new keys of one author would meet in one analysis and count as two
+authors. A change needs a full re-send of every review first.
+The worker role can write keys only for crawled reviews (not `origin = 'community'`).
+Also: `rate.review_input_hash` includes `author_name`, so masking changes that hash (RS/DB side; the crawl path does not use it).
+
+## Files
+
+| File                                                | What                      |
+| --------------------------------------------------- | ------------------------- |
+| `2026-11-06-dos-me-review-author-keys.sql`          | the migration             |
+| `2026-11-06-dos-me-review-author-keys-verify.sql`   | read-only checks V1 to V4 |
+| `2026-11-06-dos-me-review-author-keys-rollback.sql` | drops the table           |

Docs/Proposals/2026-11-06-dos-me-review-author-keys.sql

@@ -0,0 +1,55 @@
+-- =============================================================================
+-- PROPOSAL (DOS/Rate#1614): a per-review author key, so the review analyzer can tell authors
+-- apart after Rate-Services masks rate.reviews.author_name (DOS/Rate-Services#1073). A DOS-Me
+-- migration to review and apply; nothing here is applied by DOS/Rate.
+-- Verify: 2026-11-06-dos-me-review-author-keys-verify.sql (V1 to V4 return 0).
+-- Rollback: 2026-11-06-dos-me-review-author-keys-rollback.sql.
+--
+-- What it adds:
+--   rate.review_author_keys   one row per review that has a key: the keyed HMAC of the original
+--                             author name, computed by Rate-Services (the key never reaches
+--                             Rate). It is a separate table on purpose: anon holds a table-level
+--                             SELECT on rate.reviews, so a new column there would be public, and
+--                             a stable key would let anyone link one author's reviews across
+--                             products. This table has no grant for anon or authenticated.
+--
+-- The importer (service_role, rate_worker) writes it and reads it for the analysis. Reviews
+-- without a row are analysed by author_name as before. Nothing the user sees changes.
+--
+-- Idempotent. One transaction.
+-- =============================================================================
+
+BEGIN;
+SET LOCAL lock_timeout = '5s';
+
+CREATE TABLE IF NOT EXISTS rate.review_author_keys (
+  review_id  uuid PRIMARY KEY REFERENCES rate.reviews (id) ON DELETE CASCADE,
+  -- hex or base64url of an HMAC: 16 to 128 characters
+  author_key text NOT NULL CHECK (author_key ~ '^[A-Za-z0-9_-]{16,128}$'),
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+ALTER TABLE rate.review_author_keys ENABLE ROW LEVEL SECURITY;
+REVOKE ALL ON rate.review_author_keys FROM PUBLIC, anon, authenticated, rate_worker;
+GRANT ALL ON rate.review_author_keys TO service_role;
+GRANT SELECT, INSERT, UPDATE ON rate.review_author_keys TO rate_worker;
+
+DROP POLICY IF EXISTS review_author_keys_service ON rate.review_author_keys;
+CREATE POLICY review_author_keys_service ON rate.review_author_keys
+  FOR ALL TO service_role USING (true) WITH CHECK (true);
+-- Like reviews and review_flags: the worker reads all, writes only keys of crawled reviews.
+DROP POLICY IF EXISTS review_author_keys_worker ON rate.review_author_keys;
+DROP POLICY IF EXISTS review_author_keys_worker_read ON rate.review_author_keys;
+DROP POLICY IF EXISTS review_author_keys_worker_insert ON rate.review_author_keys;
+DROP POLICY IF EXISTS review_author_keys_worker_update ON rate.review_author_keys;
+CREATE POLICY review_author_keys_worker_read ON rate.review_author_keys
+  FOR SELECT TO rate_worker USING (true);
+CREATE POLICY review_author_keys_worker_insert ON rate.review_author_keys
+  FOR INSERT TO rate_worker
+  WITH CHECK (EXISTS (SELECT 1 FROM rate.reviews r WHERE r.id = review_author_keys.review_id AND r.origin <> 'community'));
+CREATE POLICY review_author_keys_worker_update ON rate.review_author_keys
+  FOR UPDATE TO rate_worker
+  USING (EXISTS (SELECT 1 FROM rate.reviews r WHERE r.id = review_author_keys.review_id AND r.origin <> 'community'))
+  WITH CHECK (EXISTS (SELECT 1 FROM rate.reviews r WHERE r.id = review_author_keys.review_id AND r.origin <> 'community'));
+
+COMMIT;

apps/importer/src/shopee/__tests__/shopee-to-supabase.test.ts

@@ -53,6 +53,7 @@ function createBaseProduct(overrides: Partial<ShopeeProduct> = {}): ShopeeProduc
 }
 
 interface StubPipelineOptions {
+  storedAuthorKeys?: Array<{ review_id: string; author_key: string }>;
   categoriesErr?: { message: string } | null;
   hintRow?: { id: string; storage_gb?: number | null } | null;
   hintErr?: { message: string } | null;
@@ -83,6 +84,7 @@ function createPipelineStubSupabase(opts: StubPipelineOptions = {}) {
     reviewInserts: Array<Array<Record<string, unknown>>>;
     verifiedUpdates: Array<{ verified: boolean; ids: string[] }>;
     marketStatsRefreshed: string[];
+    authorKeyUpserts: Array<Array<Record<string, unknown>>>;
   } = {
     merchantUpserts: 0,
     merchantPayloads: [],
@@ -93,6 +95,7 @@ function createPipelineStubSupabase(opts: StubPipelineOptions = {}) {
     reviewInserts: [],
     verifiedUpdates: [],
     marketStatsRefreshed: [],
+    authorKeyUpserts: [],
   };
 
   let reviewSelectPass = 0;
@@ -253,6 +256,20 @@ function createPipelineStubSupabase(opts: StubPipelineOptions = {}) {
       if (table === 'reviews') {
         return {
           select(cols: string) {
+            if (cols === 'id, platform_review_id') {
+              return {
+                eq(_col: string, _val: string) {
+                  return {
+                    in(_inCol: string, requested: string[]) {
+                      return Promise.resolve({
+                        data: requested.map(id => ({ id: `db-${id}`, platform_review_id: id })),
+                        error: null,
+                      });
+                    },
+                  };
+                },
+              };
+            }
             if (cols === 'platform_review_id') {
               return {
                 eq(_col: string, _val: string) {
@@ -357,6 +374,22 @@ function createPipelineStubSupabase(opts: StubPipelineOptions = {}) {
         };
       }
 
+      if (table === 'review_author_keys') {
+        return {
+          select(_columns: string) {
+            return {
+              in(_column: string, _ids: unknown[]) {
+                return Promise.resolve({ data: opts.storedAuthorKeys ?? [], error: null });
+              },
+            };
+          },
+          upsert(payload: Array<Record<string, unknown>>, _options?: unknown) {
+            events.authorKeyUpserts.push(payload);
+            return Promise.resolve({ data: null, error: null });
+          },
+        };
+      }
+
       if (table === 'review_flags' || table === 'review_analysis') {
         return {
           // persistAnalysisToSupabase reads flags written by other detectors first.
@@ -818,7 +851,8 @@ async function runTests() {
         },
         {
           reviewId: 'rev-explicit-1',
-          author: 'Minh Anh',
+          author: 'M***h',
+          authorKey: 'c'.repeat(64),
           ratingStar: 5,
           comment: 'Review mới còn lại sau khi lọc race',
           images: [],
@@ -846,6 +880,11 @@ async function runTests() {
     'Pass 2 should insert only the remaining non-raced review'
   );
   assert.equal(revRaceEvents.reviewInserts[1]?.[0]?.platform_review_id, 'rev-explicit-1');
+  assert.deepEqual(
+    revRaceEvents.authorKeyUpserts,
+    [[{ review_id: 'db-rev-explicit-1', author_key: 'c'.repeat(64) }]],
+    'author_key from RS is stored in review_author_keys for the review (DOS/Rate#1614)'
+  );
   assert.equal(
     revRaceEvents.verifiedUpdates.length,
     2,

apps/importer/src/shopee/ai-review-analyzer.ts

@@ -134,6 +134,11 @@ export interface BayesianRatingResult {
 export interface ReviewInputItem {
   id: string;
   author_name?: string | null;
+  /**
+   * Keyed HMAC of the original author name, computed by Rate-Services before it masks
+   * `author_name`. Preferred over the name to tell authors apart; absent on old rows.
+   */
+  author_key?: string | null;
   rating_star: number;
   comment?: string | null;
   variation?: string | null;
@@ -148,6 +153,24 @@ export interface ReviewInputItem {
   reviewer?: ScrapedReviewer | null;
 }
 
+/**
+ * Identity used to tell authors apart for duplicate-text and seeding analysis: the
+ * `author_key` when present (exact, case-sensitive), else the lower-cased `author_name`,
+ * else the review id. Prefixes keep a key from ever equal to a name.
+ */
+export function reviewAuthorIdentity(
+  r: Pick<ReviewInputItem, 'author_key' | 'author_name'>,
+  reviewId: string
+): string {
+  if (typeof r.author_key === 'string' && r.author_key.trim()) {
+    return `key:${r.author_key.trim()}`;
+  }
+  if (typeof r.author_name === 'string' && r.author_name.trim()) {
+    return `name:${r.author_name.toLowerCase()}`;
+  }
+  return `id:${reviewId}`;
+}
+
 export interface AnalyzedReviewResult {
   review_id: string;
   verdict: ReviewVerdict;
@@ -1182,9 +1205,7 @@ export class AiReviewAnalyzer {
       const norm = normalizeTextForDedupe(r.comment || '');
       // Rating labels repeat across buyers because the platform writes them, not because of seeding.
       if (norm.length >= 15 && !isRatingOnlyComment(r.comment)) {
-        const rawAuthor =
-          typeof r.author_name === 'string' && r.author_name.trim() ? r.author_name : reviewId;
-        const authorKey = rawAuthor.toLowerCase();
+        const authorKey = reviewAuthorIdentity(r, reviewId);
         const authors = commentCounts.get(norm) || new Set<string>();
         authors.add(authorKey);
         commentCounts.set(norm, authors);