Phil Skentelbery
915e77d994
- Add docker-compose.yml and docker-compose.example.yml for production deployment - Add .env.example with all required environment variables - Update architect agent with upgrade path requirements - Update developer agent with migration best practices - Add Phase 3 design documents (v0.3.0) - Add ADR-0006 for participant state management 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
279 lines
8.1 KiB
Markdown
279 lines
8.1 KiB
Markdown
# Phase 3 (v0.3.0) Design Documentation
|
|
|
|
**Version**: 0.3.0
|
|
**Date**: 2025-12-22
|
|
**Status**: Ready for Implementation
|
|
|
|
## Quick Start
|
|
|
|
Phase 3 implements participant self-management features, building on the authentication foundation from Phase 2.
|
|
|
|
**Core Features**:
|
|
- Participant list view (see who else registered)
|
|
- Profile updates (name and gift ideas)
|
|
- Reminder email preferences
|
|
- Participant withdrawal (before registration closes)
|
|
|
|
## Document Index
|
|
|
|
### 1. [System Overview](overview.md)
|
|
High-level architecture, goals, and design decisions for Phase 3.
|
|
|
|
**Read this first** to understand:
|
|
- What's in scope for v0.3.0
|
|
- Key design decisions (profile locks, withdrawal rules)
|
|
- Data flow diagrams
|
|
- State machine changes
|
|
|
|
**Key sections**:
|
|
- Phase Goals (page 1)
|
|
- Key Design Decisions (page 2)
|
|
- State Machine Impact (page 4)
|
|
|
|
### 2. [Participant Self-Management Component Design](participant-self-management.md)
|
|
Detailed component specifications for all Phase 3 features.
|
|
|
|
**Use this for**:
|
|
- Exact function signatures and implementations
|
|
- Form definitions
|
|
- Route specifications
|
|
- Template structures
|
|
- Email templates
|
|
|
|
**Key sections**:
|
|
- Business Logic Functions (page 1)
|
|
- Forms (page 6)
|
|
- Routes (page 8)
|
|
- Templates (page 11)
|
|
- Security Checklist (page 19)
|
|
|
|
### 3. [Test Plan](test-plan.md)
|
|
Comprehensive testing specifications for Phase 3.
|
|
|
|
**Use this for**:
|
|
- Unit test cases and fixtures
|
|
- Integration test scenarios
|
|
- Acceptance test procedures
|
|
- Manual QA steps
|
|
- Coverage requirements
|
|
|
|
**Key sections**:
|
|
- Unit Tests (page 1)
|
|
- Integration Tests (page 4)
|
|
- Acceptance Tests (page 9)
|
|
- Edge Cases (page 11)
|
|
|
|
### 4. [Implementation Guide](implementation-guide.md)
|
|
Step-by-step implementation instructions using TDD.
|
|
|
|
**Follow this to**:
|
|
- Implement features in correct order
|
|
- Write tests first, then code
|
|
- Verify each feature before moving on
|
|
- Create proper commits and PRs
|
|
|
|
**Key sections**:
|
|
- Implementation Order (page 1)
|
|
- Phase 3.1: Participant List (page 2)
|
|
- Phase 3.2: Profile Updates (page 4)
|
|
- Phase 3.3: Reminder Preferences (page 7)
|
|
- Phase 3.4: Withdrawal (page 9)
|
|
- Final Steps (page 14)
|
|
|
|
## Architecture Decision Records
|
|
|
|
### [ADR-0006: Participant State Management](../../decisions/0006-participant-state-management.md)
|
|
Documents key decisions about when participants can update profiles, withdraw, and how withdrawals are implemented.
|
|
|
|
**Key decisions**:
|
|
- Profile updates allowed until matching
|
|
- Withdrawals allowed until registration closes
|
|
- Soft delete implementation (withdrawn_at timestamp)
|
|
- Withdrawn participants visible only to admin
|
|
- No re-registration with same email
|
|
|
|
## User Stories Implemented
|
|
|
|
Phase 3 completes these backlog items:
|
|
|
|
### Epic 4: Participant Registration
|
|
- ✅ **Story 4.5**: View Participant List (Pre-Matching)
|
|
|
|
### Epic 6: Participant Self-Management
|
|
- ✅ **Story 6.1**: Update Profile
|
|
- ✅ **Story 6.2**: Withdraw from Exchange
|
|
- ✅ **Story 6.3**: Update Reminder Preferences
|
|
|
|
## Dependencies
|
|
|
|
### Prerequisites (from Phase 2)
|
|
- ✅ Participant model with `withdrawn_at` field
|
|
- ✅ Participant authentication (@participant_required decorator)
|
|
- ✅ Participant dashboard route
|
|
- ✅ Email service for sending emails
|
|
|
|
### No New Dependencies
|
|
Phase 3 requires **no new**:
|
|
- Python packages
|
|
- Database migrations
|
|
- Environment variables
|
|
- External services
|
|
|
|
## Technical Highlights
|
|
|
|
### New Files Created
|
|
```
|
|
src/
|
|
utils/participant.py # Business logic functions
|
|
services/withdrawal.py # Withdrawal service
|
|
|
|
templates/
|
|
participant/
|
|
profile_edit.html # Profile edit page
|
|
withdraw.html # Withdrawal confirmation
|
|
emails/
|
|
participant/
|
|
withdrawal_confirmation.html # Withdrawal email
|
|
withdrawal_confirmation.txt # Plain text version
|
|
|
|
tests/
|
|
unit/
|
|
test_participant_utils.py # Unit tests for business logic
|
|
test_withdrawal_service.py # Unit tests for withdrawal
|
|
integration/
|
|
test_profile_update.py # Profile update integration tests
|
|
test_withdrawal.py # Withdrawal integration tests
|
|
test_participant_list.py # Participant list tests
|
|
test_reminder_preferences.py # Preference update tests
|
|
```
|
|
|
|
### Modified Files
|
|
```
|
|
src/
|
|
routes/participant.py # New routes added
|
|
forms/participant.py # New forms added
|
|
services/email.py # Withdrawal email method added
|
|
|
|
templates/
|
|
participant/dashboard.html # Enhanced with participant list
|
|
```
|
|
|
|
## Design Principles Applied
|
|
|
|
Phase 3 adheres to project principles:
|
|
|
|
1. **Simplicity First**
|
|
- No new database tables (uses existing fields)
|
|
- No new external dependencies
|
|
- Soft delete instead of complex cascade handling
|
|
|
|
2. **State-Based Permissions**
|
|
- Clear rules about when operations are allowed
|
|
- Based on exchange state (draft, open, closed, matched)
|
|
- Easy to test and reason about
|
|
|
|
3. **TDD Approach**
|
|
- Implementation guide follows test-first methodology
|
|
- Every feature has unit and integration tests
|
|
- 80%+ coverage maintained
|
|
|
|
4. **Security by Design**
|
|
- All routes require authentication
|
|
- State validation prevents unauthorized operations
|
|
- CSRF protection on all POST operations
|
|
- Input sanitization via WTForms and Jinja2
|
|
|
|
5. **Privacy-Conscious**
|
|
- Participant list shows names only (no emails)
|
|
- Withdrawn participants hidden from other participants
|
|
- Gift ideas not revealed until matching
|
|
|
|
## Implementation Checklist
|
|
|
|
Use this to track progress:
|
|
|
|
- [ ] **Phase 3.1: Participant List View**
|
|
- [ ] Create `src/utils/participant.py`
|
|
- [ ] Write unit tests for utility functions
|
|
- [ ] Update dashboard route
|
|
- [ ] Update dashboard template
|
|
- [ ] Write integration tests
|
|
- [ ] Manual QA
|
|
|
|
- [ ] **Phase 3.2: Profile Updates**
|
|
- [ ] Add `can_update_profile()` function
|
|
- [ ] Write unit tests for state validation
|
|
- [ ] Create `ProfileUpdateForm`
|
|
- [ ] Create profile edit route
|
|
- [ ] Create profile edit template
|
|
- [ ] Update dashboard with edit link
|
|
- [ ] Write integration tests
|
|
- [ ] Manual QA
|
|
|
|
- [ ] **Phase 3.3: Reminder Preferences**
|
|
- [ ] Create `ReminderPreferenceForm`
|
|
- [ ] Create preference update route
|
|
- [ ] Update dashboard with preference form
|
|
- [ ] Write integration tests
|
|
- [ ] Manual QA
|
|
|
|
- [ ] **Phase 3.4: Withdrawal**
|
|
- [ ] Add `can_withdraw()` function
|
|
- [ ] Create `src/services/withdrawal.py`
|
|
- [ ] Write unit tests for withdrawal service
|
|
- [ ] Create `WithdrawForm`
|
|
- [ ] Create withdrawal route
|
|
- [ ] Create email templates
|
|
- [ ] Update email service
|
|
- [ ] Create withdrawal template
|
|
- [ ] Update dashboard with withdraw link
|
|
- [ ] Write integration tests
|
|
- [ ] Manual QA
|
|
|
|
- [ ] **Final Steps**
|
|
- [ ] Run all tests (≥ 80% coverage)
|
|
- [ ] Run linting and type checking
|
|
- [ ] Complete manual QA from test plan
|
|
- [ ] Update documentation if needed
|
|
- [ ] Create feature branch
|
|
- [ ] Commit changes
|
|
- [ ] Create pull request
|
|
|
|
## Success Criteria
|
|
|
|
Phase 3 is complete when:
|
|
|
|
1. ✅ All user stories have passing acceptance tests
|
|
2. ✅ Code coverage ≥ 80%
|
|
3. ✅ All linting and type checking passes
|
|
4. ✅ Manual QA completed
|
|
5. ✅ Security checklist verified
|
|
6. ✅ Accessibility tests pass
|
|
7. ✅ Browser compatibility verified
|
|
8. ✅ Phase 2 regression tests still pass
|
|
9. ✅ Documentation updated
|
|
10. ✅ Pull request approved and merged
|
|
|
|
## What's Next: Phase 4
|
|
|
|
After Phase 3 is complete, the next logical phase is:
|
|
|
|
**Phase 4 (v0.4.0)**: Post-Matching Participant Experience (Epic 11)
|
|
- View assigned recipient (match assignment)
|
|
- View recipient's gift ideas
|
|
- View exchange information post-matching
|
|
- Participant list (post-matching version)
|
|
|
|
This builds on Phase 3's participant dashboard foundation and enables the core Secret Santa experience after admin has matched participants.
|
|
|
|
## Questions?
|
|
|
|
- Review the [Project Overview](../../PROJECT_OVERVIEW.md) for product vision
|
|
- Check the [Backlog](../../BACKLOG.md) for user stories
|
|
- See [v0.2.0 Design](../v0.2.0/overview.md) for foundation architecture
|
|
- Consult existing [ADRs](../../decisions/) for architectural context
|
|
|
|
---
|
|
|
|
**Phase 3 Design Status**: ✅ Complete and Ready for Implementation
|