# TMS Permission Backend - Setup Guide

## 📁 Cấu trúc Project (Monorepo)

Project sử dụng **single package.json** ở root để quản lý tất cả dependencies:

```
dkiDownload/
├── package.json              # ← Single source of truth
├── tsconfig.json             # ← TypeScript config chung
├── .env.example              # ← Environment variables template
├── .env                      # ← Your actual env vars (gitignored)
├── src/                      # Backend TypeScript
│   ├── server.ts            # Express server chính
│   ├── types/
│   │   └── index.ts         # TypeScript definitions
│   ├── utils/
│   │   └── logger.ts        # Logger utility
│   ├── services/
│   │   ├── auth.service.ts          # TMS authentication + token cache
│   │   ├── mongodb.service.ts       # MongoDB connection + TMS ID lookup
│   │   ├── tms-api.service.ts       # TMS API operations + search filter
│   │   ├── supabase.service.ts      # Submissions CRUD + autocomplete
│   │   └── worker.service.ts        # Background queue polling
│   └── controllers/
│       └── permission.controller.ts  # Core automated permission logic
├── components/               # Frontend React components
├── App.tsx                  # Frontend main app
└── index.tsx                # Frontend entry point
```

## 🚀 Setup & Chạy (Simplified!)

### 1. Cài đặt dependencies (1 lần duy nhất!)

```bash
npm install
```

### 2. Tạo file .env ở root

```bash
cp .env.example .env
```

**Nội dung file .env:**

```env
# TMS API Configuration
TMS_API_BASE_URL=https://api.tms.example.com
TMS_USERNAME=your_username
TMS_PASSWORD=your_password

# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017/tms_database
MONGODB_DB_NAME=tms_database

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# Server Configuration
TMS_PORT=4000

# Worker Configuration (optional)
WORKER_POLL_INTERVAL=3000
```

### 3. Khởi động MongoDB

Đảm bảo MongoDB đang chạy với collection `titles_data`:

```bash
# Windows
mongod --dbpath "C:\data\db"

# hoặc dùng MongoDB service
net start MongoDB
```

### 4. Chạy Full Stack

**Option A: Chạy cả Backend + Frontend cùng lúc (Recommended)**

```bash
npm run dev
```

Backend: **http://localhost:4000**  
Frontend: **http://localhost:3000**

**Option B: Chạy riêng từng service**

```bash
# Terminal 1: Backend only
npm run dev:backend

# Terminal 2: Frontend only
npm run dev:frontend
```

**Production:**

```bash
npm run build              # Build cả backend + frontend
npm run start:backend      # Start backend
npm run preview            # Preview frontend build
```

### 5. Kiểm tra backend

Mở trình duyệt và truy cập:

```
http://localhost:4000/health
```

Nếu thành công, bạn sẽ thấy:

```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2025-11-26T...",
    "service": "TMS Permission Backend"
  }
}
```

## 📡 API Endpoints

| Method | Endpoint                     | Mô tả                              |
| ------ | ---------------------------- | ---------------------------------- |
| POST   | `/api/submit`                | Tạo submission mới                 |
| GET    | `/api/submissions/:id`       | Lấy status + results               |
| GET    | `/api/submissions?limit=30`  | Lịch sử submissions                |
| DELETE | `/api/submissions/:id`       | Xóa submission                     |
| POST   | `/api/submissions/:id/retry` | Retry submission failed            |
| GET    | `/api/usernames`             | Danh sách usernames (autocomplete) |
| POST   | `/api/user/search`           | Tìm user TMS (có filter project)   |
| GET    | `/health`                    | Health check                       |

## 🎯 Features Automated Logic

### 1. Username Suffix Detection

- `(DM)` hoặc `(DM/QC)` → Grant **RW** permission
- `(L)` → Grant **R** permission
- Username khác → Skip (không xử lý)

### 2. Fixed Member

- **Luôn luôn** thêm `DKI_공통_Tool(DM/QC)` với **RW** permission đầu tiên
- Sau đó mới xử lý các usernames khác

### 3. Final Flag Support

- Nếu input có keyword `final` (ví dụ: `1000 de final`)
- Sẽ grant permission cho subset **FINAL** thay vì **ALL**

### 4. Search User với Project Filter

- Frontend có thể gọi `/api/user/search` với `excludeProjectId`
- Backend sẽ tự động loại bỏ users đã có trong project đó

## 🧪 Testing Workflow

### Test 1: Create Submission

```bash
curl -X POST http://localhost:4000/api/submit \
  -H "Content-Type: application/json" \
  -d '{
    "submission_type": "tms_permission",
    "username_list": ["user1(DM)", "user2(L)"],
    "ge_input": "1000 de\n1001 us final"
  }'
```

### Test 2: Check Status

```bash
curl http://localhost:4000/api/submissions/tms_1732xxxxx_xxxxx
```

### Test 3: Search User

```bash
curl -X POST http://localhost:4000/api/user/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "John",
    "excludeProjectId": "12345"
  }'
```

## 🔧 Frontend Integration

Frontend đã được cập nhật để gọi API qua Vite proxy:

**vite.config.ts:**

```typescript
proxy: {
  '/api': {
    target: 'http://127.0.0.1:4000',  // ← Đã update từ 8000
    changeOrigin: true,
    secure: false,
  }
}
```

**App.tsx:**

```typescript
// ✅ Updated - Dùng relative path
const response = await fetch('/api/submit', { ... });

// ❌ Old - Hardcode localhost:4000
// const response = await fetch('http://localhost:4000/api/submit', { ... });
```

## 🏃 Quick Start

```bash
# 1. Install dependencies (1 lần duy nhất)
npm install

# 2. Setup environment
cp .env.example .env
# Edit .env với credentials thật

# 3. Start MongoDB
net start MongoDB

# 4. Run full stack
npm run dev

# 5. Open browser
# Frontend: http://localhost:3000
# Backend:  http://localhost:4000
```

## 📝 Logs

Backend sẽ log ra console:

- `[INFO]` - Thông tin general
- `[DEBUG]` - Chi tiết debug
- `[WARN]` - Cảnh báo
- `[ERROR]` - Lỗi

Example:

```
[2025-11-26T10:30:45.123Z] [INFO] 🚀 TMS Backend server running on port 4000
[2025-11-26T10:31:20.456Z] [INFO] ✅ Submission created {"submissionId":"tms_...","usernames":2,"ges":2}
[2025-11-26T10:31:23.789Z] [INFO] 📝 Processing submission tms_...
```

## 🧹 Next Steps

1. ✅ Backend src/ hoàn thành
2. ✅ Frontend đã update API calls
3. ✅ Vite proxy đã config
4. ⏳ **TODO:** Test toàn bộ flow
5. ⏳ **TODO:** Delete folder `backend-tms/` sau khi test thành công

## 🐛 Troubleshooting

### Backend không start

- Kiểm tra MongoDB đang chạy
- Kiểm tra file `.env` đã tạo và đúng format
- Kiểm tra port 4000 chưa bị chiếm

### API trả về lỗi 401 (Unauthorized)

- Kiểm tra TMS credentials trong `.env`
- Token có thể đã expired, restart backend để refresh

### Worker không process queue

- Kiểm tra Supabase connection
- Kiểm tra MongoDB connection
- Xem logs để debug chi tiết
