# Design Document: Project Management Enhancement

## Overview

本设计文档描述了项目管理界面的增强功能架构，包括项目完成状态管理和数据导出功能。设计遵循现有的组件架构和 API 模式。

## Architecture

### Frontend Architecture

```
ProjectDetailModal
├── Project Info Section
├── Action Buttons Section
│   ├── "标记为已完成" Button (conditional)
│   └── "导出数据" Button
├── Tasks Section
└── Modals
    ├── ProjectEditModal (existing)
    ├── ProjectCompletionDialog (new)
    └── DataExportDialog (new)
```

### Backend Architecture

```
API Endpoints
├── PATCH /api/projects/{project_id}/status (update status)
├── POST /api/projects/{project_id}/export (initiate export)
└── GET /api/exports/{export_id}/status (check export status)
```

## Components and Interfaces

### Frontend Components

#### 1. ProjectDetailModal Enhancement
- Add "标记为已完成" button (visible when completion_rate === 100%)
- Add "导出数据" button (always visible)
- Integrate ProjectCompletionDialog
- Integrate DataExportDialog

#### 2. ProjectCompletionDialog (New)
- Confirmation dialog for marking project as completed
- Shows project name and completion status
- Buttons: Cancel, Confirm
- Handles status update API call

#### 3. DataExportDialog (New)
- Export format selection dropdown
- Format options: JSON, CSV, COCO, YOLO
- Format descriptions
- Export button with loading state
- Progress indicator during export
- Success/error messages

### API Interfaces

#### Update Project Status
```typescript
PATCH /api/projects/{project_id}/status
Request: { status: "completed" }
Response: Project
```

#### Initiate Export
```typescript
POST /api/projects/{project_id}/export
Request: { format: "json" | "csv" | "coco" | "yolo" }
Response: { export_id: string, status: string }
```

#### Check Export Status
```typescript
GET /api/exports/{export_id}/status
Response: { status: string, progress: number, download_url?: string, error?: string }
```

## Data Models

### Frontend State

```typescript
interface ProjectCompletionState {
  isDialogOpen: boolean;
  isSubmitting: boolean;
  error: string | null;
}

interface DataExportState {
  isDialogOpen: boolean;
  selectedFormat: ExportFormat | null;
  isExporting: boolean;
  exportProgress: number;
  error: string | null;
  downloadUrl: string | null;
}

type ExportFormat = 'json' | 'csv' | 'coco' | 'yolo';
```

### Backend Models

```python
class ProjectStatusUpdate(BaseModel):
    status: str  # "completed"

class ExportRequest(BaseModel):
    format: str  # "json", "csv", "coco", "yolo"

class ExportResponse(BaseModel):
    export_id: str
    status: str
    progress: float
    download_url: Optional[str]
    error: Optional[str]
```

## Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

### Property 1: Project Completion Status Invariant
*For any* project with 100% completion rate, when the admin marks it as completed, the project status SHALL be updated to "completed" and remain in that state until explicitly changed.

**Validates: Requirements 1.1, 1.3**

### Property 2: Completion Button Visibility
*For any* project, the "标记为已完成" button SHALL be visible if and only if the project completion rate is exactly 100%.

**Validates: Requirements 1.2, 2.2**

### Property 3: Export Format Validation
*For any* export request, the selected format SHALL be one of the valid formats (JSON, CSV, COCO, YOLO), and the export SHALL fail gracefully if an invalid format is provided.

**Validates: Requirements 3.1, 6.1**

### Property 4: Export Status Consistency
*For any* export job, the status returned by the status check endpoint SHALL be consistent with the actual export state, and progress SHALL be monotonically increasing.

**Validates: Requirements 3.2, 6.2**

### Property 5: Authorization Check
*For any* project status update or export request, if the user is not an admin, the system SHALL return a 403 Forbidden error.

**Validates: Requirements 5.5, 6.1**

### Property 6: Completion Timestamp Recording
*For any* project marked as completed, the system SHALL record a completion timestamp that is greater than or equal to the current time.

**Validates: Requirements 1.3**

## Error Handling

### Frontend Error Handling

1. **Status Update Errors**
   - Display error message in modal
   - Keep modal open for retry
   - Show specific error details

2. **Export Errors**
   - Display error message in export dialog
   - Allow user to retry with different format
   - Log error for debugging

3. **Network Errors**
   - Show connection error message
   - Provide retry button
   - Timeout after 30 seconds

### Backend Error Handling

1. **Invalid Status Transition**
   - Return 400 Bad Request
   - Include error message explaining valid transitions

2. **Incomplete Project**
   - Return 400 Bad Request
   - Include completion rate in response

3. **Export Failures**
   - Return 500 Internal Server Error
   - Include error details in response
   - Log error for debugging

## Testing Strategy

### Unit Tests

1. **ProjectCompletionDialog**
   - Test button visibility based on completion rate
   - Test confirmation dialog behavior
   - Test error handling

2. **DataExportDialog**
   - Test format selection
   - Test export initiation
   - Test progress display
   - Test error messages

3. **Backend Status Update**
   - Test valid status transitions
   - Test authorization checks
   - Test timestamp recording

### Property-Based Tests

1. **Status Update Property Test**
   - Generate random projects with various completion rates
   - Verify status update only succeeds at 100%
   - Verify status is persisted correctly

2. **Export Format Property Test**
   - Generate random export requests with valid/invalid formats
   - Verify only valid formats are accepted
   - Verify error handling for invalid formats

3. **Authorization Property Test**
   - Generate requests with different user roles
   - Verify only admins can update status/export
   - Verify non-admins get 403 error

### Integration Tests

1. **Complete Project Workflow**
   - Create project with tasks
   - Complete all tasks
   - Mark project as completed
   - Verify status change

2. **Export Workflow**
   - Create project with annotations
   - Initiate export with different formats
   - Verify export completes successfully
   - Verify download link is provided