G3 POC Hub

Ứng dụng web nội bộ để quản lý POC Requests giữa Sale và Implementor teams.

📋 Tổng quan dự án

G3 POC Hub là một hệ thống quản lý POC (Proof of Concept) Requests, cho phép:

• Sale: Tạo và theo dõi POC requests cho khách hàng
• Implementor: Nhận, thực hiện và cập nhật trạng thái POC requests
• Admin: Quản lý users và POC requests (non-implemented)

🌐 URLs

Development (Sandbox)

• Application: https://3000-ilhqpzum32xjwuevf7r1n-dfc00ec5.sandbox.novita.ai
• Health Check: https://3000-ilhqpzum32xjwuevf7r1n-dfc00ec5.sandbox.novita.ai/api/health

Production (Sẽ deploy lên Cloudflare Pages)

• Chưa deploy

🚀 Tính năng chính

✅ Đã hoàn thành

Authentication & Authorization

• Đăng ký tài khoản với role-based (Sale/Implementor)
• Đăng nhập với JWT authentication
• Role detection qua URL parameter (?role=sale/implementor)
• BD Role validation cho Sale users

Sale Features

• Tạo POC Request mới
• Xem danh sách POC của mình (My Requests)
• Sửa POC Request (chỉ với status REQUESTED)
• Xem chi tiết POC Request (tất cả status)
• Filter POC theo status
• Tìm kiếm POC đã Implemented
• Dashboard với thống kê nhanh
• Search theo keyword, market, priority

Implementor Features

• Xem danh sách POC chờ xử lý (sorted by priority)
• Process POC Request (assign to self)
• Cập nhật status POC
• Cập nhật thông tin triển khai (GitHub, Vercel, function list, keywords)
• Mark POC as Implemented
• Tìm kiếm POC đã Implemented

Admin Features

• Quản lý Users (Create, Read, Update, Delete, Reset Password)
• Quản lý POC Requests (chỉ non-implemented)
• View system statistics
• Edit POC details
• Reassign POC to different implementor
• Delete POC (non-implemented only)
• View audit logs

Search & Filtering

• Full-text search trên multiple fields
• Filter theo market, priority, status
• Tag/Category sidebar với keyword counting
• Click tag để filter

🔄 Status Workflow

REQUESTED → IMPLEMENTING → IMPLEMENTED
     ↓           ↓
  CLARIFYING ──→

🗄️ Data Architecture

Database: Cloudflare D1 (SQLite)

Users Table

- id (UUID, PK)
- username (unique)
- password_hash
- market
- cmc_account
- role (SALE | IMPLEMENTOR)
- bd_role (BD | AM, nullable)
- created_at, updated_at

POC Requests Table

- id (UUID, PK)
- poc_name
- client_name
- client_logo_url
- ui_color_suggestion
- market
- domain
- description
- requirement
- priority (HIGH | MEDIUM | LOW)
- purpose (BUILD_SO | CLIENT_ENGAGE | POC_FOR_SPEC)
- status (REQUESTED | IMPLEMENTING | CLARIFYING | IMPLEMENTED)
- sale_id (FK → users)
- implementor_id (FK → users)
- eta
- created_at, updated_at

POC Implement Info Table

- id (UUID, PK)
- poc_id (FK → poc_requests)
- function_list
- github_url
- github_account
- vercel_url
- vercel_account
- keywords (CSV)
- created_at, updated_at

Status Audit Log Table

- id (UUID, PK)
- poc_id (FK → poc_requests)
- user_id (FK → users)
- from_status
- to_status
- timestamp

📡 API Endpoints

Authentication

• POST /api/v1/auth/signup - Đăng ký tài khoản
• POST /api/v1/auth/login - Đăng nhập

POC Management (requires JWT token)

• POST /api/v1/pocs - Tạo POC Request (SALE only)
• GET /api/v1/pocs/my - Lấy POC của tôi (SALE only)
• GET /api/v1/pocs/implemented - Search POC đã hoàn thành
• GET /api/v1/pocs/pending - Lấy POC chờ xử lý (IMPLEMENTOR only)
• GET /api/v1/pocs/:id - Chi tiết POC
• POST /api/v1/pocs/:id/process - Process POC (IMPLEMENTOR only)
• PATCH /api/v1/pocs/:id/status - Cập nhật status (IMPLEMENTOR only)
• PUT /api/v1/pocs/:id/implement-info - Cập nhật implement info (IMPLEMENTOR only)
• GET /api/v1/pocs/tags/implemented - Lấy danh sách tags

Admin Management (requires ADMIN role)

User Management

• GET /api/v1/admin/users - Lấy danh sách users
• GET /api/v1/admin/users/:id - Chi tiết user
• POST /api/v1/admin/users - Tạo user mới
• PUT /api/v1/admin/users/:id - Cập nhật user
• DELETE /api/v1/admin/users/:id - Xóa user
• PATCH /api/v1/admin/users/:id/password - Reset password

POC Management (Non-Implemented only)

• GET /api/v1/admin/pocs - Lấy danh sách POC non-implemented
• GET /api/v1/admin/pocs/:id - Chi tiết POC với audit log
• PUT /api/v1/admin/pocs/:id - Cập nhật POC
• DELETE /api/v1/admin/pocs/:id - Xóa POC
• PATCH /api/v1/admin/pocs/:id/assign - Reassign POC

Statistics

• GET /api/v1/admin/statistics - Lấy thống kê hệ thống

🛠️ Tech Stack

Backend

• Framework: Hono (lightweight web framework)
• Runtime: Cloudflare Workers
• Database: Cloudflare D1 (SQLite)
• Authentication: JWT with Web Crypto API
• Language: TypeScript

Frontend

• UI Framework: Vanilla JavaScript (SPA)
• CSS: TailwindCSS (CDN)
• Icons: Font Awesome
• HTTP Client: Axios

Development Tools

• Package Manager: npm
• Build Tool: Vite
• Process Manager: PM2 (sandbox only)
• CLI: Wrangler (Cloudflare)

📦 Project Structure

webapp/
├── src/
│   ├── index.tsx              # Main application entry
│   ├── routes/
│   │   ├── auth.ts            # Authentication routes
│   │   └── pocs.ts            # POC management routes
│   ├── middleware/
│   │   └── auth.ts            # JWT authentication middleware
│   ├── types/
│   │   └── index.ts           # TypeScript type definitions
│   └── utils/
│       └── auth.ts            # Auth utilities (JWT, hashing)
├── public/
│   └── static/
│       ├── app.js             # Frontend main logic
│       ├── app-part2.js       # Sale features
│       └── app-part3.js       # Implementor features
├── migrations/
│   └── 0001_initial_schema.sql
├── seed.sql                   # Test data
├── wrangler.jsonc             # Cloudflare configuration
├── ecosystem.config.cjs       # PM2 configuration
├── package.json
└── README.md

🚀 Getting Started

Prerequisites

• Node.js 18+
• npm

Local Development (Sandbox)

1. Install dependencies

cd /home/user/webapp
npm install

2. Apply migrations

npm run db:migrate:local

3. Seed test data

npm run db:seed

4. Build project

npm run build

5. Start development server

pm2 start ecosystem.config.cjs

6. Test application

curl http://localhost:3000/api/health

Useful Commands

# Database
npm run db:migrate:local      # Apply migrations to local DB
npm run db:migrate:prod       # Apply migrations to production DB
npm run db:seed               # Seed test data
npm run db:reset              # Reset local database

# Development
npm run build                 # Build project
npm run dev:sandbox           # Start dev server (sandbox)
npm run clean-port            # Kill port 3000

# PM2
pm2 list                      # List all processes
pm2 logs g3-poc-hub           # View logs
pm2 restart g3-poc-hub        # Restart app
pm2 delete g3-poc-hub         # Stop and remove

# Deployment
npm run deploy                # Deploy to Cloudflare Pages
npm run deploy:prod           # Deploy with project name

👤 Hướng dẫn sử dụng

Cho Sale

1. Đăng ký/Đăng nhập

   • Truy cập: /?role=sale
   • Đăng ký với role = SALE, cung cấp BD Role (BD hoặc AM)
   • Đăng nhập

2. Tạo POC Request

   • Click "Tạo POC Request mới"
   • Điền thông tin: POC name, Client, Market, Description, Requirement, Priority, Purpose
   • Submit

3. Theo dõi POC

   • Click "POC của tôi" để xem danh sách
   • Filter theo status: REQUESTED, IMPLEMENTING, CLARIFYING, IMPLEMENTED

4. Tìm POC Reference

   • Click "Tìm POC đã hoàn thành"
   • Search theo keyword, filter theo market/priority
   • Click tags để filter nhanh

Cho Implementor

1. Đăng nhập

   • Truy cập: /?role=implementor
   • Đăng ký với role = IMPLEMENTOR
   • Đăng nhập

2. Nhận POC Request

   • Xem "POC chờ xử lý" (sorted by priority)
   • Click "Bắt đầu xử lý" để assign POC cho mình
   • Status tự động chuyển sang IMPLEMENTING

3. Cập nhật Progress

   • Trong danh sách pending, click "Cập nhật"
   • Có thể chuyển status: IMPLEMENTING, CLARIFYING, IMPLEMENTED

4. Hoàn thành POC

   • Khi chọn status = IMPLEMENTED
   • Bắt buộc nhập:
     • Function List
     • GitHub URL & Account
     • Vercel URL & Account
     • Keywords (tags cho search)
   • Submit → POC marked as Implemented

5. Tìm POC Reference

   • Giống như Sale, có thể search POC đã hoàn thành

Cho Admin

1. Đăng nhập

   • Truy cập: /?role=admin
   • Username: admin
   • Password: 123456
   • Đăng nhập

2. Quản lý Users

   • Click "Quản lý Users"
   • Xem danh sách users
   • Tạo user mới
   • Sửa thông tin user
   • Reset password user
   • Xóa user (không thể xóa nếu user có POC)

3. Quản lý POC Requests

   • Click "Quản lý POC Requests"
   • Xem danh sách POC non-implemented
   • Filter theo status, priority, market
   • Xem chi tiết POC với audit log
   • Sửa thông tin POC
   • Reassign POC cho implementor khác
   • Xóa POC (chỉ non-implemented)

4. Xem thống kê

   • Dashboard hiển thị thống kê:
     • Số lượng users theo role
     • Số lượng POC theo status
     • Số lượng POC active theo priority

🔐 Security

• JWT tokens với expiration (7 days)
• Password hashing với SHA-256 (Web Crypto API)
• Role-based authorization ở backend
• CORS enabled cho API routes
• Input validation trên tất cả endpoints

📊 Database Queries Performance

• Indexes trên: username, role, status, priority, market, sale_id, implementor_id
• Full-text search optimization với LIKE queries
• Pagination support (page, pageSize)

🐛 Known Issues / Limitations

• Password hashing đang dùng SHA-256 (nên upgrade lên bcrypt trong production)
• Frontend là SPA đơn giản (có thể cải thiện với React/Vue)
• No real-time updates (cần refresh để xem thay đổi)
• Limited error handling trong UI

📝 Next Steps / Improvements

• Deploy lên Cloudflare Pages production
• Setup GitHub repository
• Thêm email notifications
• Real-time updates với WebSocket/SSE
• Rich text editor cho description/requirement
• File upload cho client logo
• Advanced analytics dashboard
• Export POC reports
• Role permissions fine-tuning

🤝 Contributing

Internal project for G3 team. Contact maintainer for access.

📄 License

Internal use only - CMC Global

---

Last Updated: 2026-01-27 Version: 1.0.0 Status: ✅ Development Complete - Ready for Testing