feat: allow existing users to bind inviter via aff code

[hawken-im]

Summary

Currently, invitation codes can only be applied during registration via URL parameter ?aff=XXXX. This PR adds the ability for existing users to bind an inviter after account creation, with an admin-controlled feature gate.

• model/user.go: Add BindInviterByAffCode() — admin gate check, self-bind guard, optimistic lock (WHERE inviter_id = 0 prevents race conditions), quota rewards mirroring registration logic
• controller/user.go: Add BindAffCode handler
• router/api-router.go: Register POST /api/user/bind_aff under selfRoute (requires UserAuth)
• common/constants.go: Add AllowExistingUserBindInviterEnabled flag (default false)
• model/option.go: Wire new option into InitOptionMap and updateOptionMap
• Frontend: Bind-inviter card in InvitationCard (only shown when inviter_id === 0), admin toggle in Operation Settings, i18n keys for all 6 locales (zh-CN, zh-TW, en, fr, ja, ru, vi)

Behaviour

Condition	Result
Admin toggle off	管理员未开启此功能
User already has inviter	您已绑定过邀请人，无法重复绑定
User binds own aff code	不能绑定自己的邀请码
Invalid aff code	邀请码无效
Valid, first-time bind	success: true, both parties receive quota rewards

Test plan

• T1: Normal bind — success: true, inviter_id updated
• T2: Duplicate bind — rejected with correct message
• T3: Self-bind — rejected with correct message
• T4: Invalid code — rejected with correct message
• T5: Feature gate off — rejected with correct message
• Existing registration flow unchanged (purely additive change)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Registered users can bind an existing referrer by entering an invitation code; both parties receive quota rewards on success.
  • New rate-limited API endpoint to submit invitation codes.

• Settings

  • Admin toggle to enable/disable allowing existing users to bind a referrer.

• UI

  • “Bind Inviter” input and action added to the referral/invitation card with loading and success/error handling.

• Localization

  • Added translations for the binding flow in multiple locales.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3b5d1259-0476-448a-a039-fc20da1da77e

📥 Commits

Reviewing files that changed from the base of the PR and between d66438e and 8fe0c1a.

📒 Files selected for processing (1)

• model/user.go

🚧 Files skipped from review as they are similar to previous changes (1)

• model/user.go

---

Walkthrough

Adds a feature allowing existing registered users to bind an inviter via an affiliate code: feature flag, API endpoint, backend binding logic with transaction/optimistic lock, frontend UI and settings, status field, and locale entries across multiple languages.

Changes

Cohort / File(s)	Summary
Backend Configuration common/constants.go, model/option.go	Add feature flag AllowExistingUserBindInviterEnabled (default false) and integrate it into OptionMap initialization and updates.
Backend API Handler & Routing controller/user.go, router/api-router.go	Add BindAffCode HTTP handler for POST /api/user/bind_aff and register route with CriticalRateLimit middleware.
Backend Business Logic model/user.go	Add BindInviterByAffCode(userId, affCode) error implementing feature-flag check, validations, aff-code resolution, optimistic-lock transaction to set inviter_id, quota updates, logs, and cache invalidation.
Status Endpoint controller/misc.go	Expose allow_existing_user_bind_inviter in GetStatus response sourced from the feature flag.
Frontend UI Components web/src/components/topup/InvitationCard.jsx, web/src/components/topup/index.jsx	Add binding UI (input, button, loading state) and pass new props (API, showSuccess, showError, reloadUser, allowBindInviter) to enable binding flow.
Frontend Settings web/src/pages/Setting/Operation/SettingsCreditLimit.jsx	Add AllowExistingUserBindInviterEnabled toggle in settings form and wire it into form state.
Localization web/src/i18n/locales/*.json	Add six new translation keys for invitation/binding UI across en, fr, ja, ru, vi, zh-CN, zh-TW locales.

Sequence Diagram

sequenceDiagram
    participant Client as Client
    participant Handler as BindAffCode Handler
    participant Model as BindInviterByAffCode
    participant DB as Database

    Client->>Handler: POST /api/user/bind_aff {aff_code}
    Handler->>Handler: Trim & validate aff_code
    Handler->>Model: BindInviterByAffCode(userId, aff_code)

    Model->>Model: Check feature flag
    Model->>DB: Load user (by userId)
    DB-->>Model: user record
    Model->>Model: Resolve inviter_id from aff_code
    Model->>Model: Validate no self-bind and inviter exists

    Model->>DB: BEGIN TRANSACTION
    Model->>DB: UPDATE users SET inviter_id=? WHERE id=? AND inviter_id=0
    DB-->>Model: affected rows
    Model->>DB: UPDATE quotas/counters for inviter & invitee
    Model->>DB: COMMIT
    DB-->>Model: commit result

    Model-->>Handler: return success / error
    Handler-->>Client: JSON response (success or error)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• seefs001

Poem

🐰 I nibble code beneath the moon,
A bind, a click, an invite soon,
Two quotas grow, a ribbon tied,
Hop—aff codes bridge both sides,
Hooray, rewards for far and near! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main feature addition: allowing existing users to bind an inviter via affiliate code after account creation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@controller/user.go`:
- Around line 348-350: After binding JSON with c.ShouldBindJSON(&req), trim
whitespace from req.AffCode (e.g. req.AffCode = strings.TrimSpace(req.AffCode))
before performing the empty check; then use the trimmed value in the if
condition that currently reads "if err := c.ShouldBindJSON(&req); err != nil ||
req.AffCode == "" { ... }" and call common.ApiErrorMsg(c, "邀请码不能为空") when the
trimmed AffCode is empty. Ensure you import the strings package if not already
present.

In `@model/user.go`:
- Around line 1064-1081: The bind + reward sequence must be made atomic: wrap
the optimistic update of inviter_id and both reward operations inside a DB
transaction (use DB.Transaction or tx := DB.Begin()/tx.Commit()/tx.Rollback()),
perform the WHERE "id = ? AND inviter_id = 0" Update on User via the transaction
(tx.Model(&User{}).Where(...).Update(...)) and return error if RowsAffected==0,
then within the same transaction call IncreaseUserQuota (or inline the quota
increment into the users/quotas table via tx to check its error) and write
RecordLog via tx, and for the inviter avoid calling inviteUser() (which does
RMW) and instead increment inviter counters in-place using a single atomic DB
update (e.g. tx.Model(&User{}).Where("id = ?",
inviterId).UpdateColumn("invite_count", gorm.Expr("invite_count + ?", 1)) and
any quota increment for inviter similarly), check errors after each tx operation
and let the transaction roll back on failure so the bind and rewards succeed or
fail together.

In `@web/src/components/topup/InvitationCard.jsx`:
- Around line 227-261: The bind-inviter card is currently shown based only on
userState?.user?.inviter_id === 0 which lets users see the form even when the
backend feature is disabled; update the render condition to also check the
feature flag (e.g., allowBindInviter) passed from the parent so the block inside
InvitationCard (the Card/Input/button and handleBindAff) is only
rendered/enabled when allowBindInviter is true and inviter_id === 0; ensure the
parent passes allowBindInviter through props/state and use that prop in
InvitationCard to hide or disable the input/button when the feature is off.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 872bf019-2c26-411e-81a8-64ef0ae09aeb

📥 Commits

Reviewing files that changed from the base of the PR and between 4e1b05e and cf95698.

📒 Files selected for processing (15)

• common/constants.go
• controller/user.go
• model/option.go
• model/user.go
• router/api-router.go
• web/src/components/topup/InvitationCard.jsx
• web/src/components/topup/index.jsx
• web/src/i18n/locales/en.json
• web/src/i18n/locales/fr.json
• web/src/i18n/locales/ja.json
• web/src/i18n/locales/ru.json
• web/src/i18n/locales/vi.json
• web/src/i18n/locales/zh-CN.json
• web/src/i18n/locales/zh-TW.json
• web/src/pages/Setting/Operation/SettingsCreditLimit.jsx

Actionable comments posted: 1

♻️ Duplicate comments (1)

model/user.go (1)

1066-1085: ⚠️ Potential issue | 🔴 Critical

The reward path still escapes the transaction and can deadlock itself.

tx only covers the inviter_id write. Line 1079 calls IncreaseUserQuota() on the global DB, and Line 1083 calls inviteUser() which does its own read-modify-write on the global DB too; both errors are dropped. After Line 1068 updates the invitee row, the out-of-transaction quota update can block on that same row under MySQL/PostgreSQL, and even when it doesn’t, inviter_id can commit while quota/counter updates fail or lose increments.

Suggested fix

 return DB.Transaction(func(tx *gorm.DB) error {
 	result := tx.Model(&User{}).Where("id = ? AND inviter_id = 0", userId).
 		Update("inviter_id", inviterId)
 	if result.Error != nil {
 		return result.Error
 	}
 	if result.RowsAffected == 0 {
 		return errors.New("绑定失败，请重试")
 	}

 	if common.QuotaForInvitee > 0 {
-		_ = IncreaseUserQuota(userId, common.QuotaForInvitee, true)
-		RecordLog(userId, LogTypeSystem, fmt.Sprintf("绑定邀请码赠送 %s", logger.LogQuota(common.QuotaForInvitee)))
+		if err := tx.Model(&User{}).Where("id = ?", userId).
+			Update("quota", gorm.Expr("quota + ?", common.QuotaForInvitee)).Error; err != nil {
+			return err
+		}
 	}
 	if common.QuotaForInviter > 0 {
-		_ = inviteUser(inviterId)
-		RecordLog(inviterId, LogTypeSystem, fmt.Sprintf("被邀请用户绑定赠送 %s", logger.LogQuota(common.QuotaForInviter)))
+		if err := tx.Model(&User{}).Where("id = ?", inviterId).Updates(map[string]interface{}{
+			"aff_count":   gorm.Expr("aff_count + ?", 1),
+			"aff_quota":   gorm.Expr("aff_quota + ?", common.QuotaForInviter),
+			"aff_history": gorm.Expr("aff_history + ?", common.QuotaForInviter),
+		}).Error; err != nil {
+			return err
+		}
 	}

 	return nil
 })

Then do cache/log side effects only after DB.Transaction returns success.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@model/user.go` around lines 1066 - 1085, The current transaction only updates
inviter_id via DB.Transaction(tx ...) while calling IncreaseUserQuota(userId,
...), inviteUser(inviterId) and RecordLog(...) outside the transaction (and
swallowing their errors), which can deadlock or leave inviter_id committed while
quota/counters fail; fix by performing quota and inviter counter mutations
inside the same transaction using the provided tx (i.e. replace
IncreaseUserQuota and inviteUser calls with transactional equivalents or pass tx
into those functions so they use tx for their read-modify-write operations) and
propagate/return any errors from those calls so the transaction can roll back on
failure; keep non-database side-effects (cache updates,
RecordLog/logging/notifications) only after the DB.Transaction returns nil
(success).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@controller/user.go`:
- Around line 343-362: The BindAffCode endpoint (function BindAffCode) lacks
abuse controls; update the router to attach the CriticalRateLimit middleware so
authenticated users cannot brute-force 4-char affiliate codes — e.g., change the
route registration for "POST /bind_aff" to use middleware.CriticalRateLimit()
(selfRoute.POST("/bind_aff", middleware.CriticalRateLimit(),
controller.BindAffCode)) and ensure the middleware is imported/available in the
router setup.

---

Duplicate comments:
In `@model/user.go`:
- Around line 1066-1085: The current transaction only updates inviter_id via
DB.Transaction(tx ...) while calling IncreaseUserQuota(userId, ...),
inviteUser(inviterId) and RecordLog(...) outside the transaction (and swallowing
their errors), which can deadlock or leave inviter_id committed while
quota/counters fail; fix by performing quota and inviter counter mutations
inside the same transaction using the provided tx (i.e. replace
IncreaseUserQuota and inviteUser calls with transactional equivalents or pass tx
into those functions so they use tx for their read-modify-write operations) and
propagate/return any errors from those calls so the transaction can roll back on
failure; keep non-database side-effects (cache updates,
RecordLog/logging/notifications) only after the DB.Transaction returns nil
(success).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f4185764-91d7-4172-a6b2-f9b2de95b3cb

📥 Commits

Reviewing files that changed from the base of the PR and between cf95698 and f4ea858.

📒 Files selected for processing (5)

• controller/misc.go
• controller/user.go
• model/user.go
• web/src/components/topup/InvitationCard.jsx
• web/src/components/topup/index.jsx

⚠️ Potential issue | 🟠 Major

This endpoint needs abuse controls before it goes live.

The new bind flow is wired on an authenticated route without middleware.CriticalRateLimit(), while affiliate codes are still only 4 characters. Since a successful bind grants invitee quota, a logged-in user can script random attempts until one valid code hits and claim the reward. At minimum, this route should be rate-limited like the registration flow.

Suggested router hardening

selfRoute.POST("/bind_aff", middleware.CriticalRateLimit(), controller.BindAffCode)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@controller/user.go` around lines 343 - 362, The BindAffCode endpoint
(function BindAffCode) lacks abuse controls; update the router to attach the
CriticalRateLimit middleware so authenticated users cannot brute-force 4-char
affiliate codes — e.g., change the route registration for "POST /bind_aff" to
use middleware.CriticalRateLimit() (selfRoute.POST("/bind_aff",
middleware.CriticalRateLimit(), controller.BindAffCode)) and ensure the
middleware is imported/available in the router setup.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@model/user.go`:
- Around line 1084-1098: Move the non-transactional RecordLog calls out of the
transactional closure and only write logs after the tx commits; specifically,
remove or postpone the RecordLog(inviterId, LogTypeSystem, ...) and
RecordLog(userId, ...) calls from inside the tx flow and call them after a
successful tx.Commit. Also ensure the inviter update checks the update result's
RowsAffected: when executing tx.Model(&User{}).Where("id = ?",
inviterId).Updates(...), inspect the returned result.RowsAffected and return an
error (or handle it) if 0 to avoid silently skipping inviter credit when no row
was matched. Ensure these changes reference the existing tx update block and the
RecordLog and inviterId symbols so logs are only written on committed success
and updates verify RowsAffected.
- Around line 1079-1083: The direct DB update using tx.Model(&User{}).Where("id
= ?", userId).Update("quota", gorm.Expr("quota + ?", common.QuotaForInvitee))
bypasses the cache invalidation/refresh that IncreaseUserQuota performs and can
leave the invitee's Redis/cache stale; replace this direct update with a call to
IncreaseUserQuota (pass the current tx or context and userId and
common.QuotaForInvitee) or, if IncreaseUserQuota cannot be used, perform the DB
update then explicitly invalidate/refresh the user's cache via the same helper
used elsewhere (e.g., RefreshUserCache/InvalidateUserCache) so the
in-memory/Redis view is immediately consistent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 31f1faff-ad70-46d2-af01-06def5209a01

📥 Commits

Reviewing files that changed from the base of the PR and between f4ea858 and d66438e.

📒 Files selected for processing (2)

• model/user.go
• router/api-router.go

🚧 Files skipped from review as they are similar to previous changes (1)

• router/api-router.go