rebranded to BIT
This commit is contained in:
serversdwn
160
ARCHIVE_FEATURE_README.md
Normal file
160
ARCHIVE_FEATURE_README.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# Project Archive Feature
|
||||
|
||||
## Overview
|
||||
|
||||
The Break It Down (BIT) application now supports archiving projects! This helps you organize your workspace by hiding completed or inactive projects from the main view while keeping them accessible.
|
||||
|
||||
## Features Added
|
||||
|
||||
### 1. **Archive Status**
|
||||
- Projects can be marked as archived or active
|
||||
- Archived projects are kept in the database but hidden from the default view
|
||||
- All tasks and data are preserved when archiving
|
||||
|
||||
### 2. **Tab Navigation**
|
||||
The main Projects page now has three tabs:
|
||||
- **Active** (default) - Shows only non-archived projects
|
||||
- **Archived** - Shows only archived projects
|
||||
- **All** - Shows all projects regardless of archive status
|
||||
|
||||
### 3. **Quick Actions**
|
||||
Each project card now has two action buttons:
|
||||
- **Archive/Unarchive** (📦/↩️) - Toggle archive status
|
||||
- **Delete** (🗑️) - Permanently delete the project
|
||||
|
||||
### 4. **Visual Indicators**
|
||||
- Archived projects appear with reduced opacity and gray border
|
||||
- "(archived)" label appears next to archived project names
|
||||
- Context-aware empty state messages
|
||||
|
||||
## Database Changes
|
||||
|
||||
A new column has been added to the `projects` table:
|
||||
- `is_archived` (BOOLEAN) - Defaults to `False` for new projects
|
||||
|
||||
## Installation & Migration
|
||||
|
||||
### For New Installations
|
||||
No action needed! The database will be created with the correct schema automatically.
|
||||
|
||||
### For Existing Databases
|
||||
|
||||
If you have an existing Break It Down database, run the migration script:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
python3 migrate_add_is_archived.py
|
||||
```
|
||||
|
||||
This will add the `is_archived` column to your existing projects table and set all existing projects to `is_archived=False`.
|
||||
|
||||
### Restart the Backend
|
||||
|
||||
After migration, restart the backend server to load the updated models:
|
||||
|
||||
```bash
|
||||
# Stop the current backend process
|
||||
pkill -f "uvicorn.*backend.main:app"
|
||||
|
||||
# Start the backend again
|
||||
cd /path/to/break-it-down
|
||||
uvicorn backend.main:app --host 0.0.0.0 --port 8001
|
||||
```
|
||||
|
||||
Or if using Docker:
|
||||
```bash
|
||||
docker-compose restart backend
|
||||
```
|
||||
|
||||
## API Changes
|
||||
|
||||
### Updated Endpoint: GET /api/projects
|
||||
|
||||
New optional query parameter:
|
||||
- `archived` (boolean, optional) - Filter projects by archive status
|
||||
- `archived=false` - Returns only active projects
|
||||
- `archived=true` - Returns only archived projects
|
||||
- No parameter - Returns all projects
|
||||
|
||||
Examples:
|
||||
```bash
|
||||
# Get active projects
|
||||
GET /api/projects?archived=false
|
||||
|
||||
# Get archived projects
|
||||
GET /api/projects?archived=true
|
||||
|
||||
# Get all projects
|
||||
GET /api/projects
|
||||
```
|
||||
|
||||
### Updated Endpoint: PUT /api/projects/{id}
|
||||
|
||||
New field in request body:
|
||||
```json
|
||||
{
|
||||
"name": "Project Name", // optional
|
||||
"description": "Description", // optional
|
||||
"statuses": [...], // optional
|
||||
"is_archived": true // optional - new!
|
||||
}
|
||||
```
|
||||
|
||||
### New API Helper Functions
|
||||
|
||||
The frontend API client now includes:
|
||||
- `archiveProject(id)` - Archive a project
|
||||
- `unarchiveProject(id)` - Unarchive a project
|
||||
|
||||
## File Changes Summary
|
||||
|
||||
### Backend
|
||||
- `backend/app/models.py` - Added `is_archived` Boolean column to Project model
|
||||
- `backend/app/schemas.py` - Updated ProjectUpdate and Project schemas
|
||||
- `backend/app/main.py` - Added `archived` query parameter to list_projects endpoint
|
||||
- `backend/app/crud.py` - Updated get_projects to support archive filtering
|
||||
- `backend/migrate_add_is_archived.py` - Migration script (new file)
|
||||
|
||||
### Frontend
|
||||
- `frontend/src/pages/ProjectList.jsx` - Added tabs, archive buttons, and filtering logic
|
||||
- `frontend/src/utils/api.js` - Added archive/unarchive functions and updated getProjects
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Archive a Project
|
||||
1. Go to the Projects page
|
||||
2. Click the archive icon (📦) on any project card
|
||||
3. The project disappears from the Active view
|
||||
4. Switch to the "Archived" tab to see it
|
||||
|
||||
### Unarchive a Project
|
||||
1. Switch to the "Archived" tab
|
||||
2. Click the unarchive icon (↩️) on the project card
|
||||
3. The project returns to the Active view
|
||||
|
||||
### View All Projects
|
||||
Click the "All" tab to see both active and archived projects together.
|
||||
|
||||
## Status vs Archive
|
||||
|
||||
**Important distinction:**
|
||||
- **Task Status** (backlog, in_progress, on_hold, done) - Applied to individual tasks within a project
|
||||
- **Project Archive** - Applied to entire projects to organize your workspace
|
||||
|
||||
The existing task status "on_hold" is still useful for pausing work on specific tasks, while archiving is for entire projects you want to hide from your main view.
|
||||
|
||||
## Backward Compatibility
|
||||
|
||||
All changes are backward compatible:
|
||||
- Existing projects will default to `is_archived=false` (active)
|
||||
- Old API calls without the `archived` parameter still work (returns all projects)
|
||||
- The frontend gracefully handles projects with or without the archive field
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential additions:
|
||||
- Archive date tracking
|
||||
- Bulk archive operations
|
||||
- Archive projects from the ProjectSettings modal
|
||||
- Auto-archive projects after X days of inactivity
|
||||
- Project status badges (active, archived, on-hold, completed)
|
||||
Reference in New Issue
Block a user