Elevate-Web/docs/PLAN-member-numeric-code.md

Add Permanent 7-Digit Member Code

Problem

Members currently have text usernames (companyone, globaltwo) in the DB. The admin panel shows @globaltwo instead of a permanent numeric code like @8885423. Need a permanent, immutable 7-digit code for every member.

Decisions (User Confirmed)

Decision	Answer
Code length	7 digits
Preserve existing seeder codes?	Yes — pad 6-digit codes (e.g. 888203 → 8882030 or prefix with leading digit)
Referral link logic	Use display_name if set, else member_code. Both must work as lookup.

Proposed Changes

---

Phase 1: Database Migration

[NEW] database/migrations/xxxx_add_member_code_to_members_table.php

// 1. Add nullable column
$table->string('member_code', 10)->unique()->nullable()->after('username');

// 2. Backfill existing members
foreach (DB::table('members')->get() as $member) {
    // If username is already numeric, use it (pad to 7 digits)
    if (preg_match('/^\d+$/', $member->username)) {
        $code = str_pad($member->username, 7, '0', STR_PAD_RIGHT);
    } else {
        // Generate unique 7-digit code
        do {
            $code = str_pad((string) random_int(1000000, 9999999), 7, '0', STR_PAD_LEFT);
        } while (DB::table('members')->where('member_code', $code)->exists());
    }
    DB::table('members')->where('id', $member->id)->update(['member_code' => $code]);
}

// 3. Make NOT NULL
$table->string('member_code', 10)->nullable(false)->unique()->change();

---

Phase 2: Model Update

[MODIFY] app/Models/Member.php

• Add member_code to $fillable
• Auto-generate on creating event:

static::creating(function ($member) {
    if (empty($member->member_code)) {
        do {
            $code = str_pad((string) random_int(1000000, 9999999), 7, '0', STR_PAD_LEFT);
        } while (static::where('member_code', $code)->exists());
        $member->member_code = $code;
    }
});

• Update referralLink():

public function referralLink(): string
{
    // Priority: display_name (if set) → member_code
    $code = $this->display_name 
        ? str_replace(' ', '', $this->display_name) 
        : $this->member_code;
    return url('/ref/' . $code);
}

---

Phase 3: Referral Lookup (Dual Support)

[MODIFY] app/Http/Controllers/Member/AuthController.php

Update showRegister() sponsor lookup to also search member_code:

$sponsor = Member::whereRaw("REPLACE(display_name, ' ', '') = ?", [$referralCode])
    ->orWhere('member_code', $referralCode)     // ← ADD THIS
    ->orWhere('username', $referralCode)
    ->orWhere('referral_code', $referralCode)
    ->first();

This means both /ref/AngelaTolentino AND /ref/8885423 will work.

---

Phase 4: Backend — Pass member_code to Frontend

[MODIFY] app/Http/Controllers/Admin/UserController.php

index() transform:

$member->sponsor_member_code = $member->sponsor->member_code ?? null;
$member->beneficiary_member_code = (...) ? ($member->placement->member_code ?? null) : null;

edit() / show(): Include member_code in the member data.

[MODIFY] app/Http/Controllers/Member/ReferralController.php

Add member_code to the member data passed to the referral page.

---

Phase 5: Frontend — Display @member_code Everywhere

[MODIFY] resources/js/pages/Admin/Users/Index.tsx

Location	Before	After
Member column	@{m.username}	@{m.member_code}
Sponsor column	@{m.sponsor_username}	@{m.sponsor_member_code}
Beneficiary column	@{m.beneficiary_username}	@{m.beneficiary_member_code}

[MODIFY] resources/js/pages/Admin/Users/Edit.tsx

• Header: show @{member.member_code} (permanent, no pencil icon needed)
• Remove the username edit pencil icon (member_code is immutable)

[MODIFY] resources/js/pages/Admin/Users/Show.tsx

• Replace @{member.username} → @{member.member_code}
• Sponsor display: @{member.sponsor.member_code}

[MODIFY] resources/js/pages/Member/Referral/Index.tsx

• Show member_code alongside referral link

---

Phase 6: Member Creation Flows

[MODIFY] app/Http/Controllers/Admin/UserController.php — store()

• Remove manual username generation logic, let model boot handle member_code
• Or keep username as numeric but also generate member_code

[MODIFY] app/Http/Controllers/Member/AuthController.php — register()

• Auto-generates member_code via model boot (no change needed if boot is set)

---

Verification Plan

Automated

php artisan migrate
php artisan tinker --execute="echo \App\Models\Member::select('id','username','member_code','display_name')->take(15)->get();"
npm run build

Manual

1. /admin/members → all show @1234567 format
2. Sponsor column → shows @1234567 format
3. /admin/members/{id}/edit → shows permanent @member_code
4. Create new member → auto-generates member_code
5. Test /ref/8885423 → resolves to correct member
6. Test /ref/AngelaTolentino → still works (display_name)
7. Edit username → member_code stays unchanged

---

File Change Summary

File	Action
database/migrations/xxxx_add_member_code.php	NEW
app/Models/Member.php	MODIFY — fillable, boot, referralLink
app/Http/Controllers/Admin/UserController.php	MODIFY — index, edit, show transforms
app/Http/Controllers/Member/AuthController.php	MODIFY — sponsor lookup
app/Http/Controllers/Member/ReferralController.php	MODIFY — pass member_code
resources/js/pages/Admin/Users/Index.tsx	MODIFY — display @member_code
resources/js/pages/Admin/Users/Edit.tsx	MODIFY — display @member_code
resources/js/pages/Admin/Users/Show.tsx	MODIFY — display @member_code
resources/js/pages/Member/Referral/Index.tsx	MODIFY — display member_code