release: develop → production (留言防治 + quote-wall + campaign-discussion)

.env.example

@@ -105,6 +105,7 @@ MATTERS_PASSPHRASES_SECRET=
 MATTERS_SPAM_DETECTION_API_URL=
 MATTERS_SHORT_CONTENT_SPAM_DETECTION_API_URL=
 MATTERS_COMMENT_SPAM_DETECTION_API_URL=
+MATTERS_MOMENT_SPAM_DETECTION_API_URL=
 MATTERS_COMMENT_SPAM_AUTO_COLLAPSE=false
 MATTERS_AWS_SPAM_SAMPLE_QUEUE_URL=
 MATTERS_SPAM_SAMPLE_HASH_SALT=

AGENTS.md

@@ -1,11 +1,59 @@
----
-description: 
-globs: 
-alwaysApply: true
----
-You are an expect in Typescript, Graphql and Web development using express.js, and use best practices to write clean and maintainable code.
-
-- Obey documentations mentioned by [README.md](mdc:README.md).
-- *Must* read [Database-Modification.md](mdc:docs/Database-Modification.md) first for any database schema migration (create or alter tables).
-- Prefer using methods in services over adding new code.
-- Add or update tests according to [Unittest.md](mdc:docs/Unittest.md) for each changes.
+## Basic
+a. Never speculate. Investigate and confirm the facts before writing any code.
+b. Related Matters repositories for reference are at https://github.com/orgs/thematters/repositories
+c. If a requirement is ambiguous, or the existing architecture cannot solve the problem elegantly, ask the
+   developer first instead of modifying core low-level modules on your own.
+
+
+## Development
+a. TypeScript is the primary language.
+b. Prefer arrow functions. Avoid TypeScript generic type parameters where a concrete type works.
+c. Do not write an if-else on a single line.
+d. Write comments in English and only on the important parts. Keep them short and clear; avoid over-commenting.
+e. After every change, re-run lint and format to keep quality and style consistent.
+f. After every change, add or update the relevant test cases and run the tests to make sure they pass.
+g. Install non-essential packages as devDependencies, such as lint, format, build, test and tooling
+   packages like eslint and codecov; keep runtime dependencies minimal.
+
+
+## Error handling
+a. Always throw the named error classes defined in common/errors, such as ForbiddenError, UserNotFoundError,
+   EmailInvalidError.
+b. Do not throw strings or a generic Error. Add a new class only when none fits, to keep error codes consistent.
+c. When an error occurs, besides throwing from common/errors, log it with the logger.
+
+
+## Data access
+a. Do not write knex or raw SQL directly in a resolver; access data through the services in context.dataSources.
+b. Load list fields via the matching DataLoader to avoid N+1; never query row by row inside a loop.
+c. Wrap multi-write operations that need atomicity in an atomService transaction.
+
+
+## Pagination
+a. Return connection fields with connectionFromArray, connectionFromPromisedArray and cursorToIndex,
+   following the Relay cursor spec.
+b. Annotate connection fields with @complexity(multipliers input.first) to bound query complexity and
+   avoid over-fetching.
+
+
+## Constants and async
+a. Use the constants in common/enums for roles, states and types, such as USER_ROLE, USER_STATE and
+   NODE_TYPES; do not use magic strings.
+b. Offload heavy tasks such as sending email, on-chain calls and notifications to the queue; do not await
+   them synchronously inside a resolver.
+
+
+## Security
+a. Never hardcode passwords, API keys or any sensitive information in the code.
+
+
+## Git
+a. General feature development and fixes
+  a1. Branch off the develop branch and make changes on that branch.
+  a2. Before git push, sync with develop so conflicts are found and resolved first.
+  a3. When conflicts appear, do not revert on your own even if you are sure the revert is safe; ask the
+      developer first.
+b. Hotfix
+  b1. If the change is based on the master branch, cherry-pick it onto the develop branch.
+c. Commit message
+  c1. Follow Conventional Commits, such as feat:, fix: and docs:.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

codegen.json

@@ -74,9 +74,14 @@
           "Appreciation": "./appreciation.js#Appreciation",
           "OAuthClient": "./user.js#OAuthClientDB",
           "Report": "./report.js#Report",
+          "SpamRing": "./spamRing.js#SpamRing",
+          "SpamRingMember": "./spamRing.js#SpamRingMember",
+          "SpamRingEvent": "./spamRing.js#SpamRingEvent",
+          "SpamRingSignals": "./spamRing.js#SpamRingSignals",
           "IcymiTopic": "./misc.js#MattersChoiceTopic",
           "Moment": "./moment.js#Moment",
           "MomentFeedApplication": "./moment.js#MomentFeedUser",
+          "Quote": "./quote.js#Quote",
           "Writing": "./index.js#Writing",
           "Campaign": "./campaign.js#Campaign",
           "CampaignOSS": "./campaign.js#Campaign",

db/migrations/20260611100000_create_quote_table.js

@@ -0,0 +1,34 @@
+import { baseDown } from '../utils.js'
+
+const table = 'quote'
+
+const indexName = `${table}_user_id_article_id_content_unique`
+
+export const up = async (knex) => {
+  await knex('entity_type').insert({ table })
+  await knex.schema.createTable(table, (t) => {
+    t.bigIncrements('id').primary()
+    t.text('content').notNullable()
+    t.bigInteger('article_id').unsigned().notNullable()
+    t.bigInteger('campaign_id').unsigned().notNullable()
+    t.bigInteger('user_id').unsigned().notNullable()
+    t.enu('state', ['active', 'archived', 'banned']).notNullable()
+    t.timestamp('created_at').defaultTo(knex.fn.now())
+    t.timestamp('updated_at').defaultTo(knex.fn.now())
+
+    t.foreign('article_id').references('id').inTable('article')
+    t.foreign('campaign_id').references('id').inTable('campaign')
+    t.foreign('user_id').references('id').inTable('user')
+
+    t.index('campaign_id')
+    t.index('article_id')
+    t.index(['user_id', 'created_at'])
+  })
+
+  // create a partial unique index to dedupe active quotes
+  await knex.raw(
+    `CREATE UNIQUE INDEX ${indexName} ON ${table} ("user_id", "article_id", "content") WHERE state = 'active'`
+  )
+}
+
+export const down = baseDown(table)

db/migrations/20260612000000_alter_comment_type_add_campaign_discussion.js

@@ -0,0 +1,26 @@
+import { alterEnumString } from '../utils.js'
+
+const table = 'comment'
+
+export const up = async (knex) => {
+  await knex.raw(
+    alterEnumString(table, 'type', [
+      'article',
+      'circle_discussion',
+      'circle_broadcast',
+      'moment',
+      'campaign_discussion',
+    ])
+  )
+}
+
+export const down = async (knex) => {
+  await knex.raw(
+    alterEnumString(table, 'type', [
+      'article',
+      'circle_discussion',
+      'circle_broadcast',
+      'moment',
+    ])
+  )
+}

db/migrations/20260617000000_alter_campaign_to_add_enable_quote_wall.js

@@ -0,0 +1,16 @@
+const table = 'campaign'
+
+export const up = async (knex) => {
+  await knex.schema.alterTable(table, (t) => {
+    // whether this campaign exposes a quote wall (post-to-wall affordance).
+    // opt-in: defaults to false; 七日書 campaigns are enabled via data backfill
+    // and, going forward, via the OSS campaign editor toggle.
+    t.boolean('enable_quote_wall').notNullable().defaultTo(false)
+  })
+}
+
+export const down = async (knex) => {
+  await knex.schema.alterTable(table, (t) => {
+    t.dropColumn('enable_quote_wall')
+  })
+}

db/migrations/20260617000100_backfill_enable_quote_wall_seven_day_book.js

@@ -0,0 +1,17 @@
+const table = 'campaign'
+
+// One-time backfill: enable the quote wall for existing 七日書 campaigns.
+// The name match is used here ONCE (at migration time) only; from now on the
+// flag is data-driven (toggled in the OSS campaign editor), so renaming a
+// campaign no longer affects quote-wall eligibility.
+export const up = async (knex) => {
+  await knex(table).where('name', 'like', '%七日書%').update({
+    enable_quote_wall: true,
+  })
+}
+
+export const down = async (knex) => {
+  await knex(table).where('name', 'like', '%七日書%').update({
+    enable_quote_wall: false,
+  })
+}

db/migrations/20260617000200_alter_campaign_enable_quote_wall_default_on.js

@@ -0,0 +1,20 @@
+const table = 'campaign'
+
+// Interim decision: open the quote wall for every campaign by default, instead
+// of the original 七日書-only opt-in. The per-campaign `enable_quote_wall` flag
+// is kept (as a future hook for the OSS toggle / 七日書-only restriction); we
+// only flip its default to true and enable it on all existing campaigns.
+export const up = async (knex) => {
+  await knex.schema.alterTable(table, (t) => {
+    t.boolean('enable_quote_wall').notNullable().defaultTo(true).alter()
+  })
+  await knex(table).update({ enable_quote_wall: true })
+}
+
+export const down = async (knex) => {
+  // revert the default; existing per-campaign values are left as-is (the prior
+  // mixed state cannot be reconstructed)
+  await knex.schema.alterTable(table, (t) => {
+    t.boolean('enable_quote_wall').notNullable().defaultTo(false).alter()
+  })
+}

db/migrations/20260620000000_create_spam_ring_table.js

@@ -0,0 +1,41 @@
+const table = 'spam_ring'
+
+export const up = async (knex) => {
+  await knex('entity_type').insert({ table })
+
+  await knex.schema.createTable(table, (t) => {
+    t.bigIncrements('id').primary()
+    t.uuid('uuid').notNullable().unique()
+    // 模板/家族指紋：偵測 job 端的歸群 key，同一 ring 跨次匯入用它做 idempotent upsert
+    t.text('fingerprint').notNullable().unique()
+    t.enu('status', ['pending', 'frozen', 'dismissed', 'restored'])
+      .notNullable()
+      .defaultTo('pending')
+    // app 層訊號摘要（nearDupRingSize/entityRingSize/botUsernameRatio/topEntity/sampleCodes/sampleBrands/contentModelMax）
+    t.jsonb('signals').notNullable().defaultTo('{}')
+    t.integer('n_articles').notNullable().defaultTo(0)
+    t.integer('n_authors').notNullable().defaultTo(0)
+    t.decimal('new_account_ratio', 5, 4)
+    t.decimal('score', 8, 4)
+    t.enu('severity', ['low', 'medium', 'high', 'critical'])
+    t.timestamp('detected_at').notNullable().defaultTo(knex.fn.now())
+    t.timestamp('first_seen_at')
+    t.timestamp('last_seen_at')
+    t.timestamp('frozen_at')
+    t.bigInteger('frozen_by').unsigned()
+    t.text('note')
+    t.timestamp('created_at').defaultTo(knex.fn.now())
+    t.timestamp('updated_at').defaultTo(knex.fn.now())
+
+    t.foreign('frozen_by').references('id').inTable('user')
+    t.index(['status', 'score'])
+    t.index(['status', 'detected_at'])
+    t.index(['status', 'n_authors'])
+    t.index(['detected_at'])
+  })
+}
+
+export const down = async (knex) => {
+  await knex('entity_type').where({ table }).del()
+  await knex.schema.dropTable(table)
+}

db/migrations/20260620001000_create_spam_ring_member_table.js

@@ -0,0 +1,34 @@
+const table = 'spam_ring_member'
+
+export const up = async (knex) => {
+  await knex('entity_type').insert({ table })
+
+  await knex.schema.createTable(table, (t) => {
+    t.bigIncrements('id').primary()
+    t.uuid('uuid').notNullable().unique()
+    t.bigInteger('ring_id').unsigned().notNullable()
+    t.bigInteger('user_id').unsigned().notNullable()
+    t.enu('status', ['pending', 'frozen', 'skipped', 'restored'])
+      .notNullable()
+      .defaultTo('pending')
+    // 可逆性關鍵：unfreeze 只解除「本 ring 凍結造成的」封禁，不動其他原因已封的帳號
+    t.boolean('banned_by_this_ring').notNullable().defaultTo(false)
+    t.text('skip_reason')
+    // 凍結當下捕捉的帳號狀態（稽核/還原參考）
+    t.enu('pre_freeze_state', ['active', 'banned', 'archived', 'frozen'])
+    t.jsonb('evidence').notNullable().defaultTo('{}')
+    t.timestamp('created_at').defaultTo(knex.fn.now())
+    t.timestamp('updated_at').defaultTo(knex.fn.now())
+
+    t.foreign('ring_id').references('id').inTable('spam_ring')
+    t.foreign('user_id').references('id').inTable('user')
+    t.unique(['ring_id', 'user_id'])
+    t.index(['ring_id', 'status'])
+    t.index(['user_id'])
+  })
+}
+
+export const down = async (knex) => {
+  await knex('entity_type').where({ table }).del()
+  await knex.schema.dropTable(table)
+}

db/migrations/20260620002000_create_spam_ring_event_table.js

@@ -0,0 +1,37 @@
+const table = 'spam_ring_event'
+
+export const up = async (knex) => {
+  await knex('entity_type').insert({ table })
+
+  await knex.schema.createTable(table, (t) => {
+    t.bigIncrements('id').primary()
+    t.uuid('uuid').notNullable().unique()
+    t.bigInteger('ring_id').unsigned().notNullable()
+    t.bigInteger('member_id').unsigned()
+    // nullable：機器偵測（detected）事件無管理員，actor_id 留空
+    t.bigInteger('actor_id').unsigned()
+    t.enu('action', [
+      'detected',
+      'frozen',
+      'unfrozen',
+      'dismissed',
+      'member_banned',
+      'member_skipped',
+      'member_restored',
+    ]).notNullable()
+    t.jsonb('detail').notNullable().defaultTo('{}')
+    t.timestamp('created_at').defaultTo(knex.fn.now())
+
+    t.foreign('ring_id').references('id').inTable('spam_ring')
+    t.foreign('member_id').references('id').inTable('spam_ring_member')
+    t.foreign('actor_id').references('id').inTable('user')
+    t.index(['ring_id', 'created_at'])
+    t.index(['actor_id', 'created_at'])
+    t.index(['action', 'created_at'])
+  })
+}
+
+export const down = async (knex) => {
+  await knex('entity_type').where({ table }).del()
+  await knex.schema.dropTable(table)
+}