docs: dịch 22 file Markdown còn lại sang tiếng Việt có dấu (TEC-2881)
Some checks failed
CI / Lint → Typecheck → Test → Build (22) (push) Failing after 18s
CI / E2E Tests (push) Has been skipped
CodeQL Analysis / CodeQL (javascript-typescript) (push) Failing after 2m15s
Deploy / Build API Image (push) Failing after 28s
Deploy / Build Web Image (push) Failing after 16s
Deploy / Build AI Services Image (push) Failing after 17s
E2E Tests / Playwright E2E (push) Failing after 31s
Security Scanning / Dependency Audit (pnpm) (push) Failing after 3s
Security Scanning / Trivy Scan — API Image (push) Failing after 1m46s
Security Scanning / Trivy Scan — Web Image (push) Failing after 1m7s
Security Scanning / Trivy Scan — AI Services Image (push) Failing after 53s
Security Scanning / Trivy Filesystem Scan (push) Failing after 35s
Deploy / Deploy to Staging (push) Has been skipped
Deploy / Smoke Test Staging (push) Has been skipped
Deploy / Deploy to Production (push) Has been skipped
Deploy / Smoke Test Production (push) Has been skipped
Security Scanning / Security Gate (push) Failing after 0s
Deploy / Rollback Staging (push) Has been skipped
Deploy / Rollback Production (push) Has been skipped

Hoàn tất đợt cuối của nhiệm vụ chuyển toàn bộ tài liệu sang tiếng Việt.
Đã dịch 22 file `.md` còn sót (~9.7k dòng) — gồm RUNBOOK, audits,
docs/architecture, docs/load-testing, libs READMEs và các quick references.
Giữ nguyên code blocks, đường dẫn, identifier kỹ thuật, URL và biến môi trường.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Ho Ngoc Hai
2026-04-19 03:26:14 +07:00
parent 11f2bf26e6
commit d8b409a9ab
22 changed files with 3697 additions and 3703 deletions

View File

@@ -1,8 +1,8 @@
# GoodGo Platform - Authentication Quick Reference
# GoodGo Platform - Tham chiếu nhanh Authentication
## 🔑 Key Points at a Glance
## 🔑 Các điểm chính trong nháy mắt
### Password Hashing
### Hash mật khẩu
```
Algorithm: bcrypt
Salt Rounds: 12 (env: BCRYPT_ROUNDS)
@@ -10,7 +10,7 @@ Min Length: 8 characters
Example: bcrypt.hash('password', 12)
```
### Phone Numbers (Vietnamese)
### Số điện thoại (Việt Nam)
```
Valid Formats: 0900000001, 84900000001, +84900000001
Normalized: +84900000001
@@ -25,7 +25,7 @@ Normalization: lowercase + trim
Storage: admin@goodgo.vn
```
### PII Encryption
### Mã hoá PII
```
Algorithm: AES-256-GCM
Key: 32 bytes (64 hex chars)
@@ -35,7 +35,7 @@ Searchable: email → emailHash (HMAC-SHA256)
Env Var: FIELD_ENCRYPTION_KEY
```
### User Login
### Đăng nhập User
```
Username: phone (normalized)
Password: plain text
@@ -44,7 +44,7 @@ Required: isActive = true, passwordHash ≠ null
Response: tokens (or MFA challenge)
```
### User Roles
### Vai trò người dùng
```
BUYER - Search, inquire, offer (default)
SELLER - Create listings
@@ -63,33 +63,33 @@ Hashing: HMAC-SHA256 (not bcrypt)
---
## 📋 Creating a Login-Capable Admin User
## 📋 Tạo người dùng Admin có thể đăng nhập
### 5-Step Process
### Quy trình 5 bước
**1. Normalize phone**
**1. Chuẩn hoá số điện thoại**
```typescript
phone = '0900000001' '+84900000001'
```
**2. Derive HMAC key**
**2. Tạo HMAC key**
```typescript
hmacKey = crypto.hkdfSync('sha256', Buffer.from(encryptionKey, 'hex'),
Buffer.alloc(0), Buffer.from('goodgo-field-hash', 'utf8'), 32)
```
**3. Compute hashes**
**3. Tính các hash**
```typescript
phoneHash = crypto.createHmac('sha256', hmacKey).update('+84900000001').digest('hex')
emailHash = crypto.createHmac('sha256', hmacKey).update('admin@goodgo.vn').digest('hex')
```
**4. Hash password**
**4. Hash mật khẩu**
```typescript
passwordHash = await bcrypt.hash('AdminPassword123', 12)
```
**5. Create user**
**5. Tạo user**
```typescript
await prisma.user.create({
data: {
@@ -111,7 +111,7 @@ await prisma.user.create({
---
## 🧪 Test Login
## 🧪 Test đăng nhập
```bash
curl -X POST http://localhost:3000/auth/login \
@@ -122,7 +122,7 @@ curl -X POST http://localhost:3000/auth/login \
}'
```
**Success Response:**
**Response thành công:**
```json
{
"requiresMfa": false,
@@ -136,42 +136,42 @@ curl -X POST http://localhost:3000/auth/login \
---
## ⚠️ Common Issues
## ⚠️ Vấn đề thường gặp
| Issue | Fix |
| Vấn đề | Cách sửa |
|-------|-----|
| User can't login | Check: `passwordHash` ≠ null, `isActive` = true |
| "Invalid phone" | Phone must match regex (mobile only) |
| Hash mismatch | Verify `FIELD_ENCRYPTION_KEY` is consistent |
| MFA issue | Verify `MFA_BACKUP_CODE_SECRET` env var |
| PII not encrypted | Verify key is exactly 32 bytes (64 hex chars) |
| User không đăng nhập được | Kiểm tra: `passwordHash` ≠ null, `isActive` = true |
| "Invalid phone" | Phone phải khớp regex (chỉ mobile) |
| Hash không khớp | Xác minh `FIELD_ENCRYPTION_KEY` nhất quán |
| Vấn đề MFA | Xác minh biến môi trường `MFA_BACKUP_CODE_SECRET` |
| PII không được mã hoá | Xác minh key đúng 32 bytes (64 ký tự hex) |
---
## 📁 Key Files
## 📁 Các file chính
| File | Purpose |
| File | Mục đích |
|------|---------|
| `hashed-password.vo.ts` | bcrypt hashing |
| `vietnam-phone.validator.ts` | Phone validation |
| `field-encryption.ts` | AES-256-GCM encryption |
| `local.strategy.ts` | Login endpoint |
| `mfa.service.ts` | TOTP / backup codes |
| `user.entity.ts` | User domain model |
| `prisma-user.repository.ts` | User persistence |
| `seed.ts` | Seed script |
| `hashed-password.vo.ts` | Hash bcrypt |
| `vietnam-phone.validator.ts` | Validation số điện thoại |
| `field-encryption.ts` | Mã hoá AES-256-GCM |
| `local.strategy.ts` | Endpoint đăng nhập |
| `mfa.service.ts` | TOTP / backup code |
| `user.entity.ts` | Domain model User |
| `prisma-user.repository.ts` | Persistence User |
| `seed.ts` | Script seed |
---
## 🔐 Checklist for Seed User
## 🔐 Checklist cho Seed User
- [ ] Password ≥ 8 chars
- [ ] Phone matches regex
- [ ] Phone normalized: +84...
- [ ] Phone hashed: HMAC-SHA256
- [ ] Email lowercased
- [ ] Email hashed: HMAC-SHA256
- [ ] Password hashed: bcrypt (12 rounds)
- [ ] Mật khẩu ≥ 8 ký tự
- [ ] Phone khớp regex
- [ ] Phone đã chuẩn hoá: +84...
- [ ] Phone đã hash: HMAC-SHA256
- [ ] Email đã chuyển lowercase
- [ ] Email đã hash: HMAC-SHA256
- [ ] Password đã hash: bcrypt (12 rounds)
- [ ] `isActive: true`
- [ ] `passwordHash` ≠ null
- [ ] `totpEnabled: false`
@@ -179,14 +179,14 @@ curl -X POST http://localhost:3000/auth/login \
---
## 📚 Full Documentation Files
## 📚 Các file tài liệu đầy đủ
1. **AUTHENTICATION_GUIDE.md** - Complete technical reference
2. **AUTH_IMPLEMENTATION_CHECKLIST.md** - Implementation checklist & troubleshooting
3. **SEED_GENERATION_SCRIPT.ts** - Ready-to-use seed script
4. **QUICK_REFERENCE.md** - This file
1. **AUTHENTICATION_GUIDE.md** - Tham chiếu kỹ thuật đầy đủ
2. **AUTH_IMPLEMENTATION_CHECKLIST.md** - Checklist triển khai & troubleshoot
3. **SEED_GENERATION_SCRIPT.ts** - Script seed sẵn sàng dùng
4. **QUICK_REFERENCE.md** - File này
---
**Last Updated:** April 12, 2026
**Status:** Production-Ready
**Cập nhật cuối:** 12 tháng 4, 2026
**Trạng thái:** ✅ Sẵn sàng Production