Quản lý Nhà thầu - Vendor Management

1. Tổng quan

1.1. Tại sao cần quản lý Vendor?

Thực tế Agency:

Không thể làm tất cả mọi thứ in-house
Cần outsource: Web dev, App dev, UI/UX design, Video production, Content writing
Vấn đề: Không tracking được chi phí vendor → Không tính được profit chính xác → Chạy lỗ mà không biết

Giải pháp: Quản lý chặt chẽ vendor assignment và vendor cost.

1.2. Vendor trong hệ thống

Scope (Gói dịch vụ)
  ├── Campaign Plan (nếu là Ads - tự chạy)
  ├── Vendor Assignment (nếu cần outsource)
  │     └── Vendor Payment Schedule
  └── Payment Milestone (Thu tiền từ client)

Chi phí thực tế của Scope:

Total Cost = Ads Spend + Vendor Cost + Infrastructure Cost
Profit = Revenue - Total Cost

2. Vendor Master Data

2.1. Schema

{
  "vendor_id": "VND-001",
  "vendor_code": "ABC-DEV",
  "name": "ABC Development Agency",
  "type": "agency", // agency, freelancer, studio, infrastructure

  // Services offered
  "services": ["web", "app", "ui-design", "backend"],

  // Contact
  "contact_person": "Nguyen Van A",
  "email": "[email protected]",
  "phone": "+84901234567",
  "address": "123 ABC Street, District 1, HCMC",

  // Legal
  "tax_code": "0123456789",
  "company_name": "ABC Development Co., Ltd.",

  // Payment
  "payment_terms": "Net 30", // Net 15, Net 30, Net 45, 50% upfront
  "bank_name": "Vietcombank",
  "bank_account": "0123456789",
  "bank_account_name": "ABC Development Co., Ltd.",

  // Performance
  "rating": 4.5, // 1-5
  "total_projects": 12,
  "on_time_delivery_rate": 0.92,
  "quality_score": 4.3,

  "status": "active", // active, inactive, blacklisted
  "notes": "Reliable for web projects, sometimes delays on mobile",

  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

2.2. Vendor Types

Type	Description	Examples
agency	Development agency	Web/App development companies
freelancer	Individual contractor	UI designer, Copywriter, Video editor
studio	Production studio	Video production, Photo studio
infrastructure	Infrastructure provider	Cloudflare, AWS, Domain registrar
consultant	Business consultant	SEO consultant, Marketing strategist

2.3. Use Cases

UC-VND-01: Tạo Vendor mới

Actor: PM / Admin

Main Flow:

Click "Add Vendor"
Nhập thông tin vendor:
- Basic info (name, code, type)
- Contact details
- Legal info (tax code)
- Payment info (bank account, terms)
Hệ thống validate:
- Vendor code unique
- Email format valid
- Tax code format valid (if provided)
Hệ thống tạo vendor với status = "active"
Vendor sẵn sàng để assign vào scope

Postcondition:

Vendor được tạo
Có thể assign vào projects

UC-VND-02: Đánh giá Vendor

Actor: PM

Trigger: Sau khi vendor hoàn thành assignment

Main Flow:

PM nhận deliverable từ vendor
PM review và rate vendor:
- Overall rating: 1-5 stars
- On-time delivery: Yes/No
- Quality: 1-5
- Communication: 1-5
- Would work again: Yes/No
PM nhập feedback (optional)

Hệ thống update vendor metrics:

vendor.total_projects += 1
vendor.rating = (vendor.rating * (n-1) + new_rating) / n
vendor.quality_score = average(all_quality_ratings)

Nếu rating < 2.5 liên tiếp 3 lần → Warning flag

Postcondition:

Vendor rating updated
Historical record saved

3. Vendor Assignment

3.1. Schema

{
  "assignment_id": "ASG-001",
  "scope_id": "SCP-2026-002",
  "vendor_id": "VND-001",

  "role": "Full-stack Developer", // Role in this project
  "description": "Develop landing page with Next.js and CMS integration",

  // Cost
  "cost": 25000000, // VND
  "cost_breakdown": {
    "ui_design": 5000000,
    "frontend": 10000000,
    "backend": 8000000,
    "deployment": 2000000
  },

  // Timeline
  "start_date": "2026-01-01",
  "end_date": "2026-02-15",

  // Deliverables
  "deliverable": "Responsive landing page with CMS, deployed to production",
  "deliverable_checklist": [
    "UI design approved",
    "Frontend development completed",
    "CMS integration completed",
    "Testing completed",
    "Deployed to production"
  ],

  // Status
  "status": "active", // pending, active, completed, cancelled
  "completion_date": null,
  "rating": null,

  "notes": "Vendor requires design assets by Jan 5",

  "created_at": "2025-12-20T00:00:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

3.2. Use Cases

UC-ASGN-01: Assign Vendor vào Scope

Actor: PM

Precondition:

Scope đã được tạo
Scope.service_type cần vendor (web, app, video, etc.)

Main Flow:

PM chọn scope (ví dụ: WEB01 - Landing page)
Click "Assign Vendor"
Chọn vendor từ dropdown (filtered by service type)
Nhập assignment details:
- Role
- Description
- Cost (có thể breakdown chi tiết)
- Start/End date
- Deliverable checklist
Hệ thống validate:
- Vendor active
- Assignment cost reasonable (có thể warning nếu quá cao)
- Dates trong khoảng scope dates

Hệ thống tính lại scope profit:

scope.cost_estimated += assignment.cost
scope.profit = scope.revenue - scope.cost_estimated
scope.margin = (scope.profit / scope.revenue) * 100

# Check margin
if scope.margin \< scope.margin_target:
    → WARNING: "Margin below target"

Hệ thống tạo vendor payment schedule (default: 50% deposit, 50% upon completion)
Hệ thống tạo assignment với status = "pending"

Postcondition:

Vendor assigned
Cost updated
Payment schedule created

UC-ASGN-02: Track Deliverable Progress

Actor: PM

Main Flow:

PM xem assignment details

PM update deliverable checklist:

☑ UI design approved
☑ Frontend development completed
☐ CMS integration completed (in progress)
☐ Testing completed
☐ Deployed to production

Hệ thống tính progress:

Progress = Completed items / Total items
= 2 / 5 = 40%

Hệ thống hiển thị timeline:

Start: 2026-01-01
End: 2026-02-15
Today: 2026-01-20

Days elapsed: 20 / 46 (43%)
Progress: 40%

Status: ⚠ Slightly behind schedule

UC-ASGN-03: Complete Assignment

Actor: PM

Precondition:

Tất cả deliverables hoàn thành
PM review và accept

Main Flow:

PM check tất cả deliverables đã done
PM click "Complete Assignment"
PM rate vendor (UC-VND-02)

Hệ thống update:

assignment.status = "completed"
assignment.completion_date = today
assignment.rating = pm_rating

Hệ thống check payment:
- Nếu còn payment chưa paid → Reminder to accounting
Hệ thống update scope progress
Notification to vendor (thank you + request for invoice)

Postcondition:

Assignment completed
Vendor rated
Payment to be processed

4. Vendor Payment Management

4.1. Payment Schema

{
  "payment_id": "VPY-001",
  "assignment_id": "ASG-001",
  "vendor_id": "VND-001",

  "payment_type": "deposit", // deposit, milestone, final
  "description": "50% deposit for landing page development",

  "amount": 12500000,
  "due_date": "2026-01-10",

  "status": "pending", // pending, approved, paid, overdue
  "approved_by": null,
  "approved_date": null,
  "payment_date": null,
  "payment_method": "bank_transfer",

  "invoice_number": "INV-VENDOR-001", // Vendor's invoice to us
  "invoice_file_url": "s3://invoices/inv-vendor-001.pdf",

  "notes": "Payment upon design approval",

  "created_at": "2025-12-25T00:00:00Z"
}

4.2. Payment Workflow

pending
   ↓ (PM confirms work done)
approved
   ↓ (Accounting processes payment)
paid

4.3. Use Cases

UC-PAY-01: Create Payment Schedule

Actor: System (auto when assignment created)

Main Flow:

Khi assignment được tạo, hệ thống tạo payment schedule dựa vào vendor payment_terms:

Nếu payment_terms = "50% upfront":

payments = [
```json
    {
        "payment_type": "deposit",
        "amount": assignment.cost * 0.5,
        "due_date": assignment.start_date,
        "status": "pending"
    },

    {
        "payment_type": "final",
        "amount": assignment.cost * 0.5,
        "due_date": assignment.end_date,
        "status": "pending"
    }

]

**Nếu payment_terms = "Net 30"**:
```python
payments = [
```json
    {
        "payment_type": "final",
        "amount": assignment.cost,
        "due_date": assignment.end_date + 30 days,
        "status": "pending"
    }

]

---

#### UC-PAY-02: Approve Payment
**Actor**: PM / Director

**Precondition**:
- Vendor đã hoàn thành công việc (hoặc milestone)
- Vendor đã gửi invoice

**Main Flow**:
1. Vendor hoàn thành và gửi invoice
2. PM review work và invoice
3. PM upload invoice file vào hệ thống
4. PM click "Approve Payment"
5. Hệ thống update:
   ```python
   payment.status = "approved"
   payment.approved_by = pm_id
   payment.approved_date = today

Hệ thống tạo task cho Accounting: "Process vendor payment"

Email to Accounting với details:

Vendor Payment Approved

Vendor: ABC Development
Amount: 12,500,000 VND
Due date: 2026-01-10
Invoice: INV-VENDOR-001

Bank details:
- Bank: Vietcombank
- Account: 0123456789
- Account name: ABC Development Co., Ltd.

Reason: Deposit for landing page development
Approved by: PM Nguyen Van B

Postcondition:

Payment approved
Accounting task created
Email sent

UC-PAY-03: Process Payment

Actor: Accounting

Main Flow:

Accounting nhận email về approved payment
Accounting login banking và transfer money

Accounting update payment:

payment.status = "paid"
payment.payment_date = today
payment.payment_method = "bank_transfer"

Accounting upload payment proof (bank transfer screenshot)
Hệ thống update cashflow (cash outflow)
Hệ thống send notification to vendor: "Payment processed"
Hệ thống send notification to PM: "Payment completed"

Postcondition:

Payment marked as paid
Cashflow updated
Notifications sent

UC-PAY-04: Overdue Payment Alert

Actor: System (auto, daily)

Trigger: Payment due_date < today AND status = "approved"

Main Flow:

Daily job check overdue vendor payments:

overdue_payments = get_payments_where(
    status = 'approved',
    due_date \< today
)

Cho mỗi overdue payment:

⚠ VENDOR PAYMENT OVERDUE

Vendor: ABC Development
Payment: VPY-001
Amount: 12,500,000 VND
Due date: 2026-01-10
Days overdue: 5 days

This may affect:
- Vendor relationship
- Future collaboration

ACTION: Process payment immediately

Email to Accounting + Finance
Update payment.status = "overdue"

5. Cost Tracking & Profit Calculation

5.1. Scope Total Cost

def calculate_scope_total_cost(scope_id):
    """Calculate total cost for a scope"""

    # Ads cost
    ads_cost = sum(campaign_execution.spend for campaign in scope.campaigns)

    # Vendor cost
    vendor_cost = sum(assignment.cost for assignment in scope.vendor_assignments)

    # Infrastructure cost
    infra_cost = scope.infrastructure_cost # monthly hosting, tools, etc.

    total_cost = ads_cost + vendor_cost + infra_cost

    return {
        'ads_cost': ads_cost,
        'vendor_cost': vendor_cost,
        'infra_cost': infra_cost,
        'total_cost': total_cost
    }

5.2. Scope Profit/Loss

SELECT
  s.scope_id,
  s.scope_code,
  s.name,

  -- Revenue
  s.revenue,

  -- Costs
  COALESCE(SUM(ce.spend), 0) AS ads_cost,
  COALESCE(SUM(va.cost), 0) AS vendor_cost,
  s.infrastructure_cost AS infra_cost,

  -- Total
  s.revenue - (
    COALESCE(SUM(ce.spend), 0) +
    COALESCE(SUM(va.cost), 0) +
    s.infrastructure_cost
  ) AS profit,

  -- Margin
  (s.revenue - (
    COALESCE(SUM(ce.spend), 0) +
    COALESCE(SUM(va.cost), 0) +
    s.infrastructure_cost
  )) / s.revenue * 100 AS margin_pct

FROM scope s
LEFT JOIN campaign_execution ce ON s.scope_id = ce.scope_id
LEFT JOIN vendor_assignment va ON s.scope_id = va.scope_id
GROUP BY s.scope_id;

Example Output:

Scope: WEB01 - Kewpie Landing Page
─────────────────────────────────────────────────
Revenue:          50,000,000 VND

Costs:
  Ads:                     0 VND
  Vendor:         25,000,000 VND
  Infrastructure:  2,000,000 VND (hosting 1 year)
                 ─────────────────
  Total Cost:     27,000,000 VND

Profit:           23,000,000 VND
Margin:           46% ✓ (target: 40%)

Status: PROFITABLE

6. Vendor Performance Tracking

6.1. Vendor Scorecard

def generate_vendor_scorecard(vendor_id):
    """Generate vendor performance scorecard"""
    vendor = get_vendor(vendor_id)
    assignments = get_assignments(vendor_id, status='completed')

    return {
        'vendor_name': vendor.name,
        'total_projects': len(assignments),
        'total_value': sum(a.cost for a in assignments),

        # Timeliness
        'on_time_count': sum(1 for a in assignments if a.completion_date \<= a.end_date),
        'on_time_rate': sum(1 for a in assignments if a.completion_date \<= a.end_date) / len(assignments),
        'avg_delay_days': avg((a.completion_date - a.end_date).days for a in assignments if a.completion_date \> a.end_date),

        # Quality
        'avg_rating': avg(a.rating for a in assignments),
        'quality_score': avg(a.quality_rating for a in assignments),

        # Recent performance
        'last_3_projects_rating': [a.rating for a in assignments[-3:]],
        'trend': 'improving' if recent_trend_up else 'declining'
    }

Dashboard Display:

VENDOR SCORECARD: ABC Development
═════════════════════════════════════════════════

Overview
─────────────────────────────────────────────────
Total Projects:        12
Total Value:           180,000,000 VND
Avg Project Value:     15,000,000 VND

Performance
─────────────────────────────────────────────────
Overall Rating:        4.5 / 5.0 ⭐⭐⭐⭐
On-time Delivery:      92% (11/12)
Avg Delay:             3 days
Quality Score:         4.3 / 5.0

Recent Projects (Last 3)
─────────────────────────────────────────────────
1. Kewpie Landing Page      Rating: 5.0 ✓
2. Vinamilk Mobile App      Rating: 4.5 ✓
3. Grab Website Redesign    Rating: 4.0 ✓

Trend: 📈 Improving

Recommendation: PREFERRED VENDOR

6.2. Vendor Comparison

TOP VENDORS BY RATING
═════════════════════════════════════════════════
Rank | Vendor          | Projects | Rating | On-time
─────────────────────────────────────────────────
1    | ABC Development | 12       | 4.5    | 92%
2    | XYZ Studio      | 8        | 4.3    | 88%
3    | DEF Agency      | 15       | 4.1    | 80%
4    | GHI Freelance   | 6        | 3.8    | 67%

7. Vendor Onboarding

7.1. Onboarding Checklist

□ Basic Information
  □ Company name & legal entity
  □ Tax code
  □ Business license

□ Contact Information
  □ Main contact person
  □ Email & phone
  □ Office address

□ Banking Information
  □ Bank name
  □ Account number
  □ Account holder name

□ Service Capabilities
  □ Services offered
  □ Portfolio/Previous work
  □ Team size
  □ Technology stack

□ Commercial Terms
  □ Payment terms
  □ Pricing model
  □ Availability

□ Legal & Compliance
  □ NDA signed
  □ Service agreement signed
  □ Insurance (if applicable)

7.2. Trial Project

Trước khi assign dự án lớn, nên có trial project nhỏ để đánh giá:

Quality
Timeliness
Communication
Working style

8. Vendor Contract Management

8.1. Contract Types

Type	Description	Use Case
Per-project	Fixed price cho mỗi project	Web/App development
Hourly rate	Tính theo giờ	Freelancer, Consultant
Monthly retainer	Fixed monthly fee	Hosting, Maintenance
Revenue share	% revenue	KOL, Affiliate marketing

8.2. Contract Template Fields

{
  "vendor_contract_id": "VCON-001",
  "vendor_id": "VND-001",
  "contract_type": "per_project",
  "start_date": "2026-01-01",
  "end_date": "2026-12-31",
  "auto_renew": false,

  // Pricing
  "pricing_model": "fixed_price",
  "unit_rate": null, // for hourly/daily
  "minimum_commitment": null,

  // Payment terms
  "payment_terms": "Net 30",
  "deposit_required": 0.5, // 50%
  "payment_milestones": ["design_approval", "development_complete", "golive"],

  // SLA
  "response_time_hours": 24,
  "revision_rounds": 3,
  "warranty_days": 30,

  // Legal
  "nda_signed": true,
  "contract_file_url": "s3://contracts/vcon-001.pdf"
}

9. Integrations

9.1. Với Accounting System

Sync vendor payments
Generate vendor payment reports
Track accounts payable

9.2. Với Project Management

Link vendor assignments to project tasks
Sync deliverable progress
Time tracking for hourly vendors

9.3. Với Communication Tools

Slack/Teams notification khi vendor assigned
Auto-create channel cho mỗi project với vendor

10. Reports

10.1. Vendor Cost Report

VENDOR COST SUMMARY - Q1 2026
═════════════════════════════════════════════════
Vendor              | Projects | Total Cost | Avg Cost
─────────────────────────────────────────────────
ABC Development     | 3        | 75M        | 25M
XYZ Studio          | 2        | 40M        | 20M
Cloudflare          | 12       | 36M        | 3M (monthly)
─────────────────────────────────────────────────
TOTAL                         | 151M

10.2. Vendor Performance Report

Rating trends over time
On-time delivery trends
Cost efficiency (actual vs estimated)

10.3. Vendor Payment Report

Pending payments
Overdue payments
Payment history by vendor

11. Best Practices

11.1. Vendor Selection

Portfolio review: Xem previous work
Reference check: Gọi điện cho previous clients
Trial project: Start nhỏ trước khi scale
Contract clarity: Rõ ràng scope, timeline, price

11.2. Vendor Management

Clear communication: Expectations rõ ràng từ đầu
Regular check-ins: Weekly update meetings
Timely feedback: Feedback ngay, không để lâu
Fair payment: Pay on time để maintain relationship

11.3. Cost Control

Detailed scope: Càng chi tiết càng ít change requests
Fixed price preferred: Dễ budget hơn hourly rate
Milestone payments: Không pay 100% upfront
Review invoices: Double-check trước khi approve

11.4. Risk Mitigation

Backup vendors: Luôn có plan B
Escrow for large projects: Hold payment until deliver
Penalty clauses: For late delivery
IP ownership: Clarify trong contract

1. Tổng quan​

1.1. Tại sao cần quản lý Vendor?​

1.2. Vendor trong hệ thống​

2. Vendor Master Data​

2.1. Schema​

2.2. Vendor Types​

2.3. Use Cases​

UC-VND-01: Tạo Vendor mới​

UC-VND-02: Đánh giá Vendor​

3. Vendor Assignment​

3.1. Schema​

3.2. Use Cases​

UC-ASGN-01: Assign Vendor vào Scope​

UC-ASGN-02: Track Deliverable Progress​

UC-ASGN-03: Complete Assignment​

4. Vendor Payment Management​

4.1. Payment Schema​

4.2. Payment Workflow​

4.3. Use Cases​

UC-PAY-01: Create Payment Schedule​

UC-PAY-03: Process Payment​

UC-PAY-04: Overdue Payment Alert​

5. Cost Tracking & Profit Calculation​

5.1. Scope Total Cost​

5.2. Scope Profit/Loss​

6. Vendor Performance Tracking​

6.1. Vendor Scorecard​

6.2. Vendor Comparison​

7. Vendor Onboarding​

7.1. Onboarding Checklist​

7.2. Trial Project​

8. Vendor Contract Management​

8.1. Contract Types​

8.2. Contract Template Fields​

9. Integrations​

9.1. Với Accounting System​

9.2. Với Project Management​

9.3. Với Communication Tools​

10. Reports​

10.1. Vendor Cost Report​

10.2. Vendor Performance Report​

10.3. Vendor Payment Report​

11. Best Practices​

11.1. Vendor Selection​

11.2. Vendor Management​

11.3. Cost Control​

11.4. Risk Mitigation​

1. Tổng quan

1.1. Tại sao cần quản lý Vendor?

1.2. Vendor trong hệ thống

2. Vendor Master Data

2.1. Schema

2.2. Vendor Types

2.3. Use Cases

UC-VND-01: Tạo Vendor mới

UC-VND-02: Đánh giá Vendor

3. Vendor Assignment

3.1. Schema

3.2. Use Cases

UC-ASGN-01: Assign Vendor vào Scope

UC-ASGN-02: Track Deliverable Progress

UC-ASGN-03: Complete Assignment

4. Vendor Payment Management

4.1. Payment Schema

4.2. Payment Workflow

4.3. Use Cases

UC-PAY-01: Create Payment Schedule

UC-PAY-03: Process Payment

UC-PAY-04: Overdue Payment Alert

5. Cost Tracking & Profit Calculation

5.1. Scope Total Cost

5.2. Scope Profit/Loss

6. Vendor Performance Tracking

6.1. Vendor Scorecard

6.2. Vendor Comparison

7. Vendor Onboarding

7.1. Onboarding Checklist

7.2. Trial Project

8. Vendor Contract Management

8.1. Contract Types

8.2. Contract Template Fields

9. Integrations

9.1. Với Accounting System

9.2. Với Project Management

9.3. Với Communication Tools

10. Reports

10.1. Vendor Cost Report

10.2. Vendor Performance Report

10.3. Vendor Payment Report

11. Best Practices

11.1. Vendor Selection

11.2. Vendor Management

11.3. Cost Control

11.4. Risk Mitigation