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

PATCH /api/projects/{project_id}/status
Request: { status: "completed" }
Response: Project

Initiate Export

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

Check Export Status

GET /api/exports/{export_id}/status
Response: { status: string, progress: number, download_url?: string, error?: string }

Data Models

Frontend State

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

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

Status Update Errors
- Display error message in modal
- Keep modal open for retry
- Show specific error details
Export Errors
- Display error message in export dialog
- Allow user to retry with different format
- Log error for debugging
Network Errors
- Show connection error message
- Provide retry button
- Timeout after 30 seconds

Backend Error Handling

Invalid Status Transition
- Return 400 Bad Request
- Include error message explaining valid transitions
Incomplete Project
- Return 400 Bad Request
- Include completion rate in response
Export Failures
- Return 500 Internal Server Error
- Include error details in response
- Log error for debugging

Testing Strategy

Unit Tests

ProjectCompletionDialog
- Test button visibility based on completion rate
- Test confirmation dialog behavior
- Test error handling
DataExportDialog
- Test format selection
- Test export initiation
- Test progress display
- Test error messages
Backend Status Update
- Test valid status transitions
- Test authorization checks
- Test timestamp recording

Property-Based Tests

Status Update Property Test
- Generate random projects with various completion rates
- Verify status update only succeeds at 100%
- Verify status is persisted correctly
Export Format Property Test
- Generate random export requests with valid/invalid formats
- Verify only valid formats are accepted
- Verify error handling for invalid formats
Authorization Property Test
- Generate requests with different user roles
- Verify only admins can update status/export
- Verify non-admins get 403 error

Integration Tests

Complete Project Workflow
- Create project with tasks
- Complete all tasks
- Mark project as completed
- Verify status change
Export Workflow
- Create project with annotations
- Initiate export with different formats
- Verify export completes successfully
- Verify download link is provided

design.md 6.6 KB Historia Raaka