# Customer Reconciliation Slip - API Documentation Summary

## Date: 2024-12-09

## Overview
This document provides a summary of all API documentation created for the Customer Reconciliation Slip feature, specifically focusing on the action endpoints: Approve, Reject, Complete, and Excel Export.

---

## Documentation Files Created

### 1. Main API Documentation
**File:** `docs/API_CustomerReconciliationSlip_Actions.md`
**Size:** ~50 KB
**Content:**
- Complete API reference for all action endpoints
- Detailed request/response examples
- Business logic and validation rules
- Workflow diagrams
- Data models
- Error codes
- Security considerations
- Usage examples

**Endpoints Documented:**
1. `PUT /api/CustomerReconciliationSlip/Approve/{id}` - Duyệt phiếu
2. `POST /api/CustomerReconciliationSlip/Reject` - Từ chối phiếu
3. `POST /api/CustomerReconciliationSlip/Complete` - Hoàn thành phiếu
4. `POST /api/CustomerReconciliationSlip/ExportExcel` - Xuất Excel danh sách
5. `POST /api/CustomerReconciliationSlip/ExportExcelDetail/{slipId}` - Xuất Excel chi tiết

### 2. Quick Reference Guide
**File:** `docs/API_CustomerReconciliationSlip_QuickReference.md`
**Size:** ~15 KB
**Content:**
- Quick endpoint overview table
- Curl examples for each endpoint
- Workflow diagrams (ASCII art)
- Status codes reference
- Type reference
- Permission matrix
- Common error responses
- Request models (TypeScript interfaces)
- Validation rules checklist
- Testing checklist
- Integration examples (JavaScript/TypeScript)

---

## API Endpoints Summary

### 1. Approve Slip
**Endpoint:** `PUT /api/CustomerReconciliationSlip/Approve/{id}`
**Purpose:** Duyệt phiếu đối soát (chỉ cho phiếu Receivable)
**Authorization:** Approve, Founder, Accountant
**Key Features:**
- Chuyển trạng thái từ PendingApproval → Approved
- Lưu thông tin người duyệt và thời gian
- Ghi log hành động

### 2. Reject Slip
**Endpoint:** `POST /api/CustomerReconciliationSlip/Reject`
**Purpose:** Từ chối phiếu đối soát với lý do cụ thể
**Authorization:** Creator, Reject, Founder, Accountant
**Key Features:**
- Chuyển trạng thái → Rejected
- Lưu lý do từ chối vào InternalNote
- Mở khóa đơn hàng để có thể tạo phiếu mới
- Ghi log hành động

### 3. Complete Slip
**Endpoint:** `POST /api/CustomerReconciliationSlip/Complete`
**Purpose:** Hoàn thành phiếu và xác nhận thanh toán
**Authorization:** Complete, Founder, Accountant
**Key Features:**
- Chuyển trạng thái → Completed
- Lưu thông tin thanh toán (method, transaction code, proof)
- Lưu thông tin người hoàn thành và thời gian
- Ghi log hành động

### 4. Export Excel List
**Endpoint:** `POST /api/CustomerReconciliationSlip/ExportExcel`
**Purpose:** Xuất danh sách phiếu đối soát ra Excel
**Authorization:** ExportExcel, Founder
**Key Features:**
- Hỗ trợ filter theo nhiều tiêu chí
- Tùy chọn bao gồm/loại trừ các thông tin
- Trả về download URL
- Metrics về thời gian xử lý

### 5. Export Excel Detail
**Endpoint:** `POST /api/CustomerReconciliationSlip/ExportExcelDetail/{slipId}`
**Purpose:** Xuất chi tiết một phiếu đối soát ra Excel
**Authorization:** ExportExcel, Founder
**Key Features:**
- Xuất đầy đủ thông tin phiếu
- Bao gồm danh sách đơn hàng
- Bao gồm lịch sử thao tác
- Format đẹp với nhiều sheet

---

## Business Workflows

### Workflow 1: Phiếu Chi Tiền (Receivable - Type = 1)
**Mô tả:** Công ty chuyển tiền cho khách hàng

```
Create → PendingApproval → Approve → Complete
                    ↓
                 Reject
```

**Quy trình:**
1. Sale tạo phiếu từ các đơn hàng đã giao
2. Kế toán duyệt phiếu (Approve)
3. Kế toán/Founder xác nhận đã chuyển tiền (Complete)
4. Hoặc từ chối nếu có vấn đề (Reject)

**Đặc điểm:**
- Bắt buộc phải duyệt trước khi hoàn thành
- Không cần upload ảnh chứng từ khi tạo
- Có thể upload ảnh chứng từ khi hoàn thành

### Workflow 2: Phiếu Thu Tiền (Payable - Type = 2)
**Mô tả:** Khách hàng chuyển tiền cho công ty

```
Create → PendingApproval → Complete
                    ↓
                 Reject
```

**Quy trình:**
1. Sale tạo phiếu từ các đơn hàng đã giao + upload ảnh chứng từ
2. Kế toán xác nhận đã nhận tiền (Complete) - bỏ qua bước duyệt
3. Hoặc từ chối nếu có vấn đề (Reject)

**Đặc điểm:**
- Không cần duyệt, hoàn thành trực tiếp
- Bắt buộc upload ảnh chứng từ khi tạo phiếu
- Nhanh hơn vì bỏ qua bước duyệt

---

## Permission Matrix

| Action | Creator | Founder | Accountant | Approve Perm | Reject Perm | Complete Perm | Export Perm |
|--------|---------|---------|------------|--------------|-------------|---------------|-------------|
| View | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
| Create | ✓ | ✓ | - | - | - | - | - |
| Approve (Receivable) | - | ✓ | ✓ | ✓ | - | - | - |
| Reject | ✓ | ✓ | ✓ | - | ✓ | - | - |
| Complete | - | ✓ | ✓ | - | - | ✓ | - |
| Export Excel | - | ✓ | - | - | - | - | ✓ |

**Legend:**
- ✓ = Has permission
- \- = No permission
- Creator = Người tạo phiếu
- Perm = Permission (quyền cụ thể)

---

## Data Models

### Request Models

#### RejectCustomerReconciliationSlipModel
```csharp
public class RejectCustomerReconciliationSlipModel
{
    [Required]
    public int Id { get; set; }

    [Required(ErrorMessage = "Vui lòng nhập lý do từ chối")]
    public string Reason { get; set; }
}
```

#### CompleteCustomerReconciliationSlipModel
```csharp
public class CompleteCustomerReconciliationSlipModel
{
    [Required]
    public int Id { get; set; }

    [Required]
    public string PaymentMethod { get; set; }

    public string TransactionCode { get; set; }
    public string ProofImageUrl { get; set; }
    public string Note { get; set; }
}
```

#### CustomerReconciliationSlipExcelExportModel
```csharp
public class CustomerReconciliationSlipExcelExportModel : BaseModel<int>
{
    public string? FileName { get; set; }
    public List<int>? CustomerReconciliationSlipIds { get; set; }
    public DateTime? FromDate { get; set; }
    public DateTime? ToDate { get; set; }
    public int? CustomerId { get; set; }
    public int? Status { get; set; }
    public int? Type { get; set; }
    public bool IncludeOrderDetails { get; set; } = true;
    public bool IncludeApprovalInfo { get; set; } = true;
    public bool IncludeNotes { get; set; } = true;
    public string? FolderPath { get; set; }
}
```

### Enums

#### CustomerReconciliationSlipType
```csharp
public enum CustomerReconciliationSlipType
{
    Receivable = 1,  // Phiếu chi tiền (công ty trả khách)
    Payable = 2      // Phiếu thu tiền (khách trả công ty)
}
```

#### CustomerReconciliationSlipStatus
```csharp
public enum CustomerReconciliationSlipStatus
{
    Draft = 1,              // Nháp
    PendingApproval = 2,    // Chờ duyệt
    Approved = 3,           // Đã duyệt
    Completed = 4,          // Hoàn thành
    Rejected = 8            // Từ chối
}
```

---

## Validation Rules Summary

### Approve
1. Phiếu phải tồn tại
2. Phiếu phải ở trạng thái `PendingApproval`
3. Chỉ áp dụng cho phiếu loại `Receivable`
4. User phải có quyền Approve/Founder/Accountant

### Reject
1. Phiếu phải tồn tại
2. Phiếu không được ở trạng thái `Completed` hoặc `Rejected`
3. Lý do từ chối không được để trống
4. Lý do từ chối tối thiểu 10 ký tự
5. User phải là Creator hoặc có quyền Reject/Founder/Accountant

### Complete
1. Phiếu phải tồn tại
2. **Receivable:** Phải ở trạng thái `Approved`
3. **Payable:** Phải ở trạng thái `PendingApproval`
4. PaymentMethod không được để trống
5. User phải có quyền Complete/Founder/Accountant

### Export Excel
1. FromDate không được lớn hơn ToDate
2. Danh sách IDs phải chứa giá trị hợp lệ (> 0)
3. Tên file không được chứa ký tự đặc biệt
4. User phải có quyền ExportExcel/Founder

---

## Excel File Structure

### List Export (Multiple Slips)

**Sheet 1: Tổng Quan Phiếu Đối Soát**
- Thông tin cơ bản: Mã phiếu, khách hàng, loại, trạng thái
- Thông tin tài chính: COD, phí, số tiền cuối
- Thông tin duyệt/hoàn thành: người duyệt, người hoàn thành, thời gian
- Thông tin thanh toán: phương thức, mã giao dịch
- Ghi chú

**Sheet 2: Chi Tiết Đơn Hàng** (optional)
- Mã phiếu, mã đơn hàng
- Thông tin tài chính đơn hàng
- Thông tin giao hàng
- Thông tin người nhận

### Detail Export (Single Slip)

**Sheet 1: Thông Tin Phiếu**
- Section 1: Thông tin cơ bản
- Section 2: Thông tin khách hàng
- Section 3: Thông tin tài chính
- Section 4: Thông tin duyệt/hoàn thành
- Section 5: Ghi chú

**Sheet 2: Danh Sách Đơn Hàng** (optional)
- Chi tiết tất cả đơn hàng trong phiếu

**Sheet 3: Lịch Sử Thao Tác** (optional)
- Thời gian, người thực hiện
- Loại hành động
- Trạng thái cũ → mới
- Ghi chú

---

## Error Handling

### Common HTTP Status Codes

| Code | Meaning | When |
|------|---------|------|
| 200 | OK | Request successful |
| 400 | Bad Request | Validation errors, invalid state |
| 401 | Unauthorized | Not authenticated |
| 403 | Forbidden | No permission |
| 404 | Not Found | Slip not found |
| 500 | Internal Server Error | System error |

### Common Error Messages

**Approve:**
- "Phiếu không tồn tại"
- "Trạng thái phiếu không hợp lệ"
- "Chỉ phiếu chi tiền mới cần duyệt"

**Reject:**
- "Phiếu không tồn tại"
- "Không thể từ chối phiếu ở trạng thái này"
- "Vui lòng nhập lý do từ chối"

**Complete:**
- "Phiếu không tồn tại"
- "Phiếu chưa được duyệt" (for Receivable)
- "Vui lòng nhập phương thức thanh toán"

**Export Excel:**
- "Ngày bắt đầu không được lớn hơn ngày kết thúc"
- "Danh sách ID phiếu đối soát chứa giá trị không hợp lệ"
- "Tên file chứa ký tự không hợp lệ"

---

## Testing Scenarios

### Approve Testing
1. ✓ Approve phiếu Receivable ở trạng thái PendingApproval
2. ✓ Không thể approve phiếu Payable
3. ✓ Không thể approve phiếu ở trạng thái Draft/Approved/Completed/Rejected
4. ✓ Kiểm tra quyền: chỉ Founder/Accountant/Approve permission
5. ✓ Kiểm tra thông tin người duyệt được lưu
6. ✓ Kiểm tra log được tạo

### Reject Testing
1. ✓ Reject phiếu với lý do hợp lệ
2. ✓ Không thể reject phiếu Completed
3. ✓ Không thể reject phiếu Rejected
4. ✓ Không thể reject với lý do rỗng
5. ✓ Kiểm tra quyền: Creator/Founder/Accountant/Reject permission
6. ✓ Kiểm tra lý do được lưu vào InternalNote
7. ✓ Kiểm tra đơn hàng được mở khóa
8. ✓ Kiểm tra log được tạo

### Complete Testing
1. ✓ Complete phiếu Receivable sau khi Approved
2. ✓ Complete phiếu Payable trực tiếp từ PendingApproval
3. ✓ Không thể complete phiếu Receivable chưa Approved
4. ✓ Không thể complete với PaymentMethod rỗng
5. ✓ Kiểm tra thông tin thanh toán được lưu
6. ✓ Kiểm tra quyền: Founder/Accountant/Complete permission
7. ✓ Kiểm tra thông tin người hoàn thành được lưu
8. ✓ Kiểm tra log được tạo

### Export Excel Testing
1. ✓ Export với filter theo ngày
2. ✓ Export với filter theo khách hàng
3. ✓ Export với filter theo trạng thái
4. ✓ Export với filter theo loại phiếu
5. ✓ Export danh sách IDs cụ thể
6. ✓ Export chi tiết một phiếu
7. ✓ Kiểm tra file Excel được tạo đúng format
8. ✓ Kiểm tra download URL hoạt động
9. ✓ Kiểm tra các sheet được tạo đúng
10. ✓ Kiểm tra quyền: ExportExcel permission/Founder

---

## Integration Guide

### Frontend Integration

#### 1. Service Layer
```typescript
// reconciliationSlipService.ts
export class ReconciliationSlipService {
  async approve(slipId: number): Promise<void> {
    await api.put(`/api/CustomerReconciliationSlip/Approve/${slipId}`);
  }

  async reject(slipId: number, reason: string): Promise<void> {
    await api.post('/api/CustomerReconciliationSlip/Reject', {
      Id: slipId,
      Reason: reason,
    });
  }

  async complete(data: CompleteModel): Promise<void> {
    await api.post('/api/CustomerReconciliationSlip/Complete', data);
  }

  async exportExcel(filter: ExportModel): Promise<string> {
    const response = await api.post(
      '/api/CustomerReconciliationSlip/ExportExcel',
      filter
    );
    return response.data.DownloadUrl;
  }

  async exportExcelDetail(slipId: number, options: ExportModel): Promise<string> {
    const response = await api.post(
      `/api/CustomerReconciliationSlip/ExportExcelDetail/${slipId}`,
      options
    );
    return response.data.DownloadUrl;
  }
}
```

#### 2. UI Components
- Approve Button: Hiển thị cho phiếu Receivable ở trạng thái PendingApproval
- Reject Button: Hiển thị cho tất cả phiếu (trừ Completed và Rejected)
- Complete Button: Hiển thị theo điều kiện của từng loại phiếu
- Export Excel Button: Hiển thị trên list view và detail view

#### 3. Permission Checks
```typescript
// Check if user can approve
const canApprove = slip.Type === SlipType.Receivable &&
                   slip.Status === SlipStatus.PendingApproval &&
                   (hasRole('Founder') || hasRole('Accountant') || hasPermission('Approve'));

// Check if user can reject
const canReject = slip.Status !== SlipStatus.Completed &&
                  slip.Status !== SlipStatus.Rejected &&
                  (isCreator || hasRole('Founder') || hasRole('Accountant') || hasPermission('Reject'));

// Check if user can complete
const canComplete = ((slip.Type === SlipType.Receivable && slip.Status === SlipStatus.Approved) ||
                     (slip.Type === SlipType.Payable && slip.Status === SlipStatus.PendingApproval)) &&
                    (hasRole('Founder') || hasRole('Accountant') || hasPermission('Complete'));
```

---

## Security Considerations

1. **Authentication:** All endpoints require valid JWT token
2. **Authorization:** Role-based and permission-based access control
3. **Data Validation:** All inputs are validated server-side
4. **Audit Trail:** All actions are logged in CustomerReconciliationLog
5. **File Security:** Exported files are stored securely and auto-deleted
6. **SQL Injection:** Use parameterized queries
7. **XSS Prevention:** Sanitize all user inputs
8. **CSRF Protection:** Use anti-forgery tokens

---

## Performance Considerations

1. **Database Indexes:**
   - Index on Status, CustomerId, CreatedTime
   - Index on Type for faster filtering
   - Composite index on (CustomerId, Status) for common queries

2. **Caching:**
   - Cache user permissions
   - Cache frequently accessed slips
   - Invalidate cache on status changes

3. **Excel Export:**
   - Implement background job processing for large exports
   - Add progress tracking
   - Limit concurrent exports per user
   - Auto-cleanup old export files

4. **API Rate Limiting:**
   - Limit approve/reject/complete actions per minute
   - Limit export requests per hour
   - Implement exponential backoff for retries

---

## Related Documentation

### Main Documentation
- [API Actions - Full Documentation](./API_CustomerReconciliationSlip_Actions.md)
- [API Quick Reference](./API_CustomerReconciliationSlip_QuickReference.md)

### Related Features
- [Permission Updates](./CustomerReconciliationSlip_Permission_Updates.md)
- [Excel Export Details](./API_CustomerReconciliationSlipExcelExport.md)
- [Create & Search APIs](./API_GetCustomersOverview.md)
- [Get Reconciliable Orders](./API_GetReconciliableOrders.md)

### Implementation
- [Excel Export Implementation](./CustomerReconciliationSlip_ExcelExport_Implementation.md)

---

## Changelog

### 2024-12-09
- ✅ Created comprehensive API documentation for Approve, Reject, Complete endpoints
- ✅ Created comprehensive API documentation for Excel Export endpoints
- ✅ Created Quick Reference guide
- ✅ Created Summary document
- ✅ Added workflow diagrams
- ✅ Added integration examples
- ✅ Added testing checklists
- ✅ Added security and performance considerations

---

## Next Steps

1. **Implementation:**
   - Implement actual Excel generation service
   - Add background job processing for large exports
   - Implement file cleanup mechanism

2. **Testing:**
   - Unit tests for all endpoints
   - Integration tests
   - Load testing for Excel export
   - Security testing

3. **Frontend:**
   - Implement UI components
   - Add permission checks
   - Add loading states and error handling
   - Implement file download mechanism

4. **Documentation:**
   - Add Postman collection
   - Add Swagger/OpenAPI spec
   - Create video tutorials
   - Update user manual

---

## Support

For questions or issues:
- Check the [Full API Documentation](./API_CustomerReconciliationSlip_Actions.md)
- Check the [Quick Reference](./API_CustomerReconciliationSlip_QuickReference.md)
- Contact the development team
- Create an issue in the project repository
