247 lines
8.9 KiB
Markdown
247 lines
8.9 KiB
Markdown
# HXBooks Development Plan & Progress
|
|
|
|
## User's Priorities (March 2026)
|
|
1. ✅ **Fix the domain and data model**
|
|
2. ✅ **Make sure everything related to the database is good**
|
|
3. ✅ **Make a CLI so I can test things manually**
|
|
4. ✅ **Make sure search and other basic functionality is good and can be accessed through CLI**
|
|
5. ✅ **Set up automated tests**
|
|
6. ✅ **Make sure search and other basic functionality is good**
|
|
7. **Fully rework the GUI**
|
|
|
|
*Everything else will come later.*
|
|
|
|
---
|
|
|
|
## ✅ COMPLETED: Domain Model & Database (Phase 1-2)
|
|
|
|
### Domain Model Decisions Made
|
|
- **No book/instance separation**: Keep it simple, treat duplicate editions as separate books
|
|
- **Author/Genre relationships**: Proper many-to-many instead of JSON fields
|
|
- **Location hierarchy**: `location_place` + `location_bookshelf` + `location_shelf` (numeric)
|
|
- **Auto-complete approach**: Authors/genres created on-demand with nice UI later
|
|
- **Multiple readings**: Separate records per reading session
|
|
- **Simple loaning**: `loaned_to` string + `loaned_date` for tracking
|
|
|
|
### Database Infrastructure ✅ DONE
|
|
- ✅ Flask-Migrate + Alembic set up
|
|
- ✅ Initial migration created and applied
|
|
- ✅ Fixed instance folder location (project root instead of src/instance)
|
|
- ✅ Database in correct location: `/hxbooks.sqlite`
|
|
- ✅ All tables created: author, genre, book, book_author, book_genre, reading, wishlist
|
|
|
|
### New Data Model ✅ IMPLEMENTED
|
|
```sql
|
|
-- Core entities
|
|
Author(id, name)
|
|
Genre(id, name)
|
|
Book(id, title, description, isbn, edition, publisher, notes,
|
|
added_date, bought_date,
|
|
location_place, location_bookshelf, location_shelf,
|
|
loaned_to, loaned_date, owner_id)
|
|
|
|
-- Many-to-many relationships
|
|
BookAuthor(book_id, author_id)
|
|
BookGenre(book_id, genre_id)
|
|
|
|
-- User activity
|
|
Reading(id, user_id, book_id, start_date, end_date,
|
|
finished, dropped, rating, comments)
|
|
Wishlist(id, user_id, book_id, wishlisted_date)
|
|
```
|
|
|
|
---
|
|
|
|
## ✅ COMPLETED: CLI Development (Phase 3)
|
|
|
|
### CLI Implementation ✅ DONE
|
|
- ✅ **Business logic separation**: Clean `services.py` module independent from web concerns
|
|
- ✅ **Book CRUD operations**: Create, read, update, delete books with proper validation
|
|
- ✅ **Author/Genre management**: Auto-create on-demand with many-to-many relationships
|
|
- ✅ **Location management**: Place, bookshelf, shelf hierarchy with filtering
|
|
- ✅ **Reading tracking**: Start, finish, drop, rate reading sessions
|
|
- ✅ **Wishlist operations**: Add, remove, list wishlist items
|
|
- ✅ **Advanced search**: pyparsing-based query language with field filters and comparison operators
|
|
- ✅ **ISBN import**: Google Books API integration for book metadata
|
|
- ✅ **Database utilities**: Status, initialization, seed data commands
|
|
- ✅ **Output formats**: Human-readable tables and JSON for scripting
|
|
|
|
### Advanced Search Language ✅ IMPLEMENTED
|
|
```bash
|
|
# Working CLI commands:
|
|
hxbooks book add "Title" --owner alice --authors "Author1,Author2" --genres "Fiction"
|
|
hxbooks book list --place "home" --bookshelf "office" --shelf 2
|
|
hxbooks book search "author:tolkien genre:fantasy"
|
|
hxbooks book search "shelf>=5 title:\"Lord of Rings\""
|
|
hxbooks book search -- "-genre:romance" # Negation
|
|
hxbooks reading start <book_id> --owner alice
|
|
hxbooks reading finish <book_id> --rating 4 --comments "Great book!"
|
|
hxbooks wishlist add <book_id> --owner alice
|
|
hxbooks book import 9780441172719 --owner alice # ISBN import
|
|
```
|
|
|
|
### Search Query Language Features
|
|
- **Field-specific searches**: `author:tolkien`, `genre:"science fiction"`
|
|
- **Comparison operators**: `shelf>=5`, `added>=2025-01-01`, `rating>3`
|
|
- **Quoted strings**: `title:"The Lord of the Rings"`
|
|
- **Negation**: `-genre:romance`
|
|
- **Date comparisons**: `added>=2026-03-01`, `bought<2025-12-31`
|
|
- **Multiple filters**: `author:herbert genre:scifi owner:alice`
|
|
|
|
---
|
|
|
|
## ✅ COMPLETED: Automated Testing (Phase 4)
|
|
|
|
### Testing Framework ✅ IMPLEMENTED
|
|
- ✅ **pytest infrastructure**: Database fixtures, isolated test environments
|
|
- ✅ **CLI command tests**: All 18 commands with happy paths and error scenarios (29+ tests)
|
|
- ✅ **Advanced search tests**: Parametrized tests for field filters and complex queries
|
|
- ✅ **Query parser unit tests**: Type conversion, operator logic, edge cases (36 tests)
|
|
- ✅ **Output format validation**: JSON and table formats for all commands
|
|
- ✅ **Database integration**: Full CLI → services → database → relationships flow testing
|
|
- ✅ **Error handling tests**: Invalid inputs, missing data, constraint violations
|
|
|
|
### Test Coverage Achieved
|
|
- **CLI Integration**: Book CRUD, reading tracking, wishlist operations, database utilities
|
|
- **Search functionality**: String filters, numeric filters, date filters, negation, complex queries
|
|
- **Parser robustness**: Edge cases, type conversion, fallback behavior, unicode support
|
|
- **Database validation**: Relationship integrity, user creation, data persistence
|
|
|
|
**Decision**: Migration tests deemed unnecessary for this simple personal app
|
|
**Status**: 65+ tests passing, comprehensive coverage for critical functionality
|
|
|
|
---
|
|
|
|
## ✅ COMPLETED: Search & Core Features Enhancement (Phase 5)
|
|
|
|
### Search Improvements ✅ IMPLEMENTED
|
|
- ✅ **Enhanced search functionality**: Additional improvements implemented
|
|
- ✅ **Query optimization**: Performance and usability enhancements
|
|
- ✅ **Core feature refinements**: Various search and functionality improvements
|
|
|
|
**Status**: Search functionality enhanced and ready for production use
|
|
|
|
---
|
|
|
|
## 📋 TODO: Remaining Phases
|
|
|
|
### Phase 6: GUI Rework
|
|
- [ ] Update templates for new data model
|
|
- [ ] Mobile-first responsive design
|
|
- [ ] Author/Genre autocomplete interfaces
|
|
- [ ] Location hierarchy picker
|
|
- [ ] Touch-optimized interactions
|
|
|
|
---
|
|
|
|
## 🗄️ Original Critique Archive
|
|
|
|
### Critical Issues RESOLVED ✅
|
|
- ❌ **Book ownership model**: Fixed - no artificial scarcity
|
|
- ❌ **JSON denormalization**: Fixed - proper Author/Genre relationships
|
|
- ❌ **Mixed properties**: Fixed - structured location hierarchy
|
|
- ❌ **No migrations**: Fixed - Alembic set up and working
|
|
- ❌ **Poor folder structure**: Fixed - database in project root
|
|
|
|
### Issues for Later Phases
|
|
- **Authentication**: Username-only insufficient (Future phases)
|
|
- **Configuration management**: No environment handling (Future phases)
|
|
- **Mobile UX**: Tables don't work on mobile (Phase 6)
|
|
- **Error handling**: No proper boundaries (Future phases)
|
|
- **Performance**: No indexing strategy yet (Phase 4)
|
|
|
|
---
|
|
|
|
*Last updated: March 17, 2026*
|
|
*Status: Phases 1-5 Complete ✅ | Ready for Phase 6: GUI Rework 🎨*
|
|
|
|
### Medium Priority Issues (Priority 3-4: CLI & Search)
|
|
|
|
#### Search & Discovery
|
|
- **Limited FTS capabilities**: Current implementation incomplete
|
|
- **No faceted search**: Missing filters by author, genre, year, etc.
|
|
- **Performance concerns**: JSON contains operations will be slow
|
|
- **Missing recommendations**: No "similar books" functionality
|
|
|
|
#### CLI Requirements for Testing
|
|
- Book CRUD operations
|
|
- Search functionality testing
|
|
- User management
|
|
- Reading tracking
|
|
- Data import/export capabilities
|
|
|
|
### Lower Priority Issues (Priority 5-6: Testing & GUI)
|
|
|
|
#### Testing Infrastructure Missing
|
|
- No testing framework configured
|
|
- No test database setup
|
|
- No fixtures or mock data
|
|
- No CI/CD pipeline
|
|
|
|
#### GUI/UX Issues
|
|
- Mobile responsiveness needs work
|
|
- No offline capabilities
|
|
- Tables don't work well on mobile
|
|
- Missing accessibility features
|
|
|
|
### Security & DevOps (Future)
|
|
- **Authentication**: Username-only is insufficient
|
|
- **Configuration management**: No environment handling
|
|
- **Deployment**: Dockerfile/requirements.txt mismatch
|
|
- **Secret management**: Hardcoded dev secrets
|
|
|
|
### Technical Debt
|
|
- **Python 3.14 requirement**: Too aggressive (doesn't exist yet)
|
|
- **Error handling**: No proper error boundaries
|
|
- **Logging**: No production logging configuration
|
|
- **Code quality**: Missing linting, formatting tools
|
|
|
|
---
|
|
|
|
## Implementation Notes
|
|
|
|
### Phase 1: Domain Model Rework
|
|
- [ ] Design new schema with proper relationships
|
|
- [ ] Create migration system
|
|
- [ ] Implement Author and Genre entities
|
|
- [ ] Separate Book from BookInstance
|
|
- [ ] Update all models with proper typing
|
|
|
|
### Phase 2: Database Infrastructure
|
|
- [ ] Set up Alembic migrations
|
|
- [ ] Add proper indexing
|
|
- [ ] Implement FTS correctly
|
|
- [ ] Add database constraints
|
|
- [ ] Create seed data
|
|
|
|
### Phase 3: CLI Development
|
|
- [ ] Create Click-based CLI
|
|
- [ ] Book management commands
|
|
- [ ] Search functionality
|
|
- [ ] User operations
|
|
- [ ] Import/export tools
|
|
|
|
### Phase 4: Search & Core Features
|
|
- [ ] Implement proper FTS
|
|
- [ ] Add faceted search
|
|
- [ ] Create search result serializers
|
|
- [ ] Add pagination
|
|
- [ ] Optimize query performance
|
|
|
|
### Phase 5: Testing Framework
|
|
- [ ] Set up pytest
|
|
- [ ] Database testing fixtures
|
|
- [ ] API endpoint tests
|
|
- [ ] Search functionality tests
|
|
- [ ] CLI command tests
|
|
|
|
### Phase 6: GUI Rework
|
|
- [ ] Mobile-first responsive design
|
|
- [ ] Progressive enhancement
|
|
- [ ] Accessibility improvements
|
|
- [ ] Modern HTMX patterns
|
|
- [ ] Touch-optimized interactions
|
|
|
|
---
|
|
|
|
*Last updated: March 14, 2026* |