348 lines
20 KiB
Markdown
348 lines
20 KiB
Markdown
# Tasks: Document Export API Route
|
|
|
|
**Input**: Design documents from `/specs/002-document-export/`
|
|
**Prerequisites**: plan.md (complete), spec.md (complete), research.md (complete), data-model.md (complete), contracts/ (complete)
|
|
|
|
**Tests**: Test-First Development is MANDATORY per project constitution. All tests MUST be written and FAIL before implementation begins.
|
|
|
|
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
|
|
|
|
## Format: `[ID] [P?] [Story] Description`
|
|
|
|
- **[P]**: Can run in parallel (different files, no dependencies)
|
|
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
|
|
- Include exact file paths in descriptions
|
|
|
|
## Path Conventions
|
|
|
|
- Single project structure: `src/`, `tests/` at repository root
|
|
- All business logic in `src/proxyScripts/proxy.js` (monolithic architecture)
|
|
- Helper functions (optional) in `src/globalVariables/googleDriveAdapterHelper.js`
|
|
- Tests organized by contract/integration/unit in `tests/`
|
|
|
|
---
|
|
|
|
## Phase 1: Setup (Project Initialization)
|
|
|
|
**Purpose**: Verify project structure and dependencies are ready for document export feature
|
|
|
|
- [X] T001 Verify existing project dependencies (axios, jsonwebtoken, uuid, xmlbuilder2) in package.json
|
|
- [X] T002 Verify test infrastructure using Node.js built-in test runner with existing test structure in tests/
|
|
|
|
**Checkpoint**: Project structure validated - ready for foundational work
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Core infrastructure and helper functions that MUST be complete before ANY user story can be implemented
|
|
|
|
**⚠️ CRITICAL**: No user story work can begin until this phase is complete
|
|
|
|
- [X] T003 [P] Add format selection helper function to src/globalVariables/googleDriveAdapterHelper.js with EXPORT_FORMATS constant and selectExportFormat() function
|
|
- [X] T004 [P] Add filename sanitization helper function to src/globalVariables/googleDriveAdapterHelper.js for Content-Disposition headers
|
|
- [X] T005 [P] Add file extension mapping helper function to src/globalVariables/googleDriveAdapterHelper.js (mimeType → extension)
|
|
- [X] T006 [P] Add error status code mapping helper function to src/globalVariables/googleDriveAdapterHelper.js (Google Drive API errors → HTTP status codes)
|
|
|
|
**Checkpoint**: Helper functions ready - user story implementation can now begin in parallel
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Export Google Workspace Documents (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Users can request Google Workspace documents (Docs, Sheets, Slides) via `/documents/:documentId` and receive them in the best available format (Markdown > HTML > PDF) with appropriate headers.
|
|
|
|
**Independent Test**: Request a Google Doc via `/documents/:documentId` with valid document ID and verify response contains exported document in correct format with Content-Type and Content-Disposition headers.
|
|
|
|
### Tests for User Story 1 (MANDATORY - Write FIRST) ⚠️
|
|
|
|
> **CRITICAL**: Write these tests FIRST, ensure they FAIL before implementation begins. User approval required before proceeding to implementation.
|
|
|
|
- [X] T007 [P] [US1] Contract test: Valid Google Workspace document returns 200 with correct Content-Type header in tests/contract/documents-export.test.js
|
|
- [X] T008 [P] [US1] Contract test: Valid document returns Content-Disposition header with inline and correct filename in tests/contract/documents-export.test.js
|
|
- [X] T009 [P] [US1] Contract test: Document with Markdown export returns text/x-markdown Content-Type in tests/contract/documents-export.test.js
|
|
- [X] T010 [P] [US1] Contract test: Document without Markdown but with HTML returns text/html Content-Type in tests/contract/documents-export.test.js
|
|
- [X] T011 [P] [US1] Contract test: Document with only PDF export returns application/pdf Content-Type in tests/contract/documents-export.test.js
|
|
- [X] T012 [P] [US1] Integration test: Fetch metadata from Google Drive API with correct fields (id,name,mimeType,exportLinks) in tests/integration/google-drive-export.test.js
|
|
- [X] T013 [P] [US1] Integration test: Select first available export format from priority list (Markdown > HTML > PDF) in tests/integration/google-drive-export.test.js
|
|
- [X] T014 [P] [US1] Integration test: Stream content from Google Drive export link to response in tests/integration/google-drive-export.test.js
|
|
- [X] T015 [P] [US1] Unit test: Format selection prioritizes text/x-markdown over text/html and application/pdf in tests/unit/format-selection.test.js
|
|
- [X] T016 [P] [US1] Unit test: Content-Disposition header generation with sanitized filename and correct extension in tests/unit/export-headers.test.js
|
|
|
|
**Checkpoint**: All User Story 1 tests written and FAILING. Request user approval of test scenarios before proceeding to implementation.
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T017 [US1] Add /documents/:documentId route handler in src/proxyScripts/proxy.js to extract documentId from URL path
|
|
- [X] T018 [US1] Implement Google Drive metadata fetch in src/proxyScripts/proxy.js using files.get API with fields parameter
|
|
- [X] T019 [US1] Implement format selection logic in src/proxyScripts/proxy.js using selectExportFormat() helper (Markdown > HTML > PDF priority)
|
|
- [X] T020 [US1] Implement export link streaming in src/proxyScripts/proxy.js using axios to fetch content from export URL
|
|
- [X] T021 [US1] Implement Content-Type header setting in src/proxyScripts/proxy.js based on selected export format
|
|
- [X] T022 [US1] Implement Content-Disposition header setting in src/proxyScripts/proxy.js with inline and sanitized filename
|
|
- [X] T023 [US1] Add response streaming logic in src/proxyScripts/proxy.js to pipe content from Google Drive to HTTP response
|
|
|
|
**Checkpoint**: User Story 1 complete - all tests should now PASS. Verify independently before proceeding to User Story 2.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Export Native PDF Files (Priority: P2)
|
|
|
|
**Goal**: Users can request native PDF files stored in Google Drive and receive them streamed directly without conversion.
|
|
|
|
**Independent Test**: Upload a native PDF file to Google Drive, request it via `/documents/:documentId`, and verify the PDF is streamed correctly with `Content-Type: application/pdf` header.
|
|
|
|
### Tests for User Story 2 (MANDATORY - Write FIRST) ⚠️
|
|
|
|
> **CRITICAL**: Write these tests FIRST, ensure they FAIL before implementation begins. User approval required before proceeding to implementation.
|
|
|
|
- [ ] T024 [P] [US2] Contract test: Native PDF file (application/pdf mimeType) returns 200 with application/pdf Content-Type in tests/contract/documents-export.test.js
|
|
- [ ] T025 [P] [US2] Contract test: Native PDF returns Content-Disposition with inline and .pdf extension in tests/contract/documents-export.test.js
|
|
- [ ] T026 [P] [US2] Contract test: Native PDF larger than 10MB returns 413 Payload Too Large in tests/contract/documents-export.test.js
|
|
- [ ] T027 [P] [US2] Integration test: Native PDF document without exportLinks streams via files.get with alt=media in tests/integration/google-drive-export.test.js
|
|
- [ ] T028 [P] [US2] Integration test: Check Content-Length header before streaming and enforce 10MB limit in tests/integration/google-drive-export.test.js
|
|
- [ ] T029 [P] [US2] Unit test: Detect native PDF by mimeType=application/pdf and absence of exportLinks in tests/unit/format-selection.test.js
|
|
|
|
**Checkpoint**: All User Story 2 tests written and FAILING. Request user approval of test scenarios before proceeding to implementation.
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [ ] T030 [US2] Add native PDF detection logic in src/proxyScripts/proxy.js (check mimeType=application/pdf and no exportLinks)
|
|
- [ ] T031 [US2] Implement native PDF streaming in src/proxyScripts/proxy.js using files.get API with alt=media parameter
|
|
- [ ] T032 [US2] Add Content-Length validation in src/proxyScripts/proxy.js to enforce 10MB limit (return 413 if exceeded)
|
|
- [ ] T033 [US2] Add Content-Type and Content-Disposition headers for native PDF in src/proxyScripts/proxy.js
|
|
- [ ] T034 [US2] Add response streaming for native PDF in src/proxyScripts/proxy.js to pipe from Google Drive to HTTP response
|
|
|
|
**Checkpoint**: User Story 2 complete - all tests should now PASS. Verify independently: US1 and US2 both work without affecting each other.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Handle Unsupported File Types (Priority: P3)
|
|
|
|
**Goal**: Users attempting to export unsupported file types receive clear error messages (403 status) indicating the mimetype is not supported. Includes timeout and API error handling.
|
|
|
|
**Independent Test**: Request a document with an unsupported mimetype (e.g., image, video, zip) via `/documents/:documentId` and verify a 403 response with appropriate error message.
|
|
|
|
### Tests for User Story 3 (MANDATORY - Write FIRST) ⚠️
|
|
|
|
> **CRITICAL**: Write these tests FIRST, ensure they FAIL before implementation begins. User approval required before proceeding to implementation.
|
|
|
|
- [ ] T035 [P] [US3] Contract test: Invalid document ID returns 404 with "Document not found" message in tests/contract/documents-export.test.js
|
|
- [ ] T036 [P] [US3] Contract test: Document user cannot access returns 401 with "Unauthorized" message in tests/contract/documents-export.test.js
|
|
- [ ] T037 [P] [US3] Contract test: Unsupported mimeType (no exportLinks, not PDF) returns 403 with "mimetype not supported" in tests/contract/documents-export.test.js
|
|
- [ ] T038 [P] [US3] Contract test: Export operation exceeding 30 seconds returns 504 with "Gateway Timeout" message in tests/contract/documents-export.test.js
|
|
- [ ] T039 [P] [US3] Contract test: Google Drive API unavailable returns 502 with "Bad Gateway - Google Drive API unavailable" in tests/contract/documents-export.test.js
|
|
- [ ] T040 [P] [US3] Contract test: Malformed export link returns 500 with "Export failed - unable to retrieve document content" in tests/contract/documents-export.test.js
|
|
- [ ] T041 [P] [US3] Integration test: Map Google Drive 404 error to HTTP 404 response in tests/integration/google-drive-export.test.js
|
|
- [ ] T042 [P] [US3] Integration test: Map Google Drive 401/403 errors to HTTP 401 response in tests/integration/google-drive-export.test.js
|
|
- [ ] T043 [P] [US3] Integration test: Enforce 30-second timeout using axios timeout configuration in tests/integration/google-drive-export.test.js
|
|
- [ ] T044 [P] [US3] Unit test: Error status code mapping function correctly maps Google Drive errors to HTTP codes in tests/unit/error-mapping.test.js
|
|
|
|
**Checkpoint**: All User Story 3 tests written and FAILING. Request user approval of test scenarios before proceeding to implementation.
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [ ] T045 [US3] Add 404 error handling in src/proxyScripts/proxy.js for invalid/non-existent document IDs (return "Document not found")
|
|
- [ ] T046 [US3] Add 401 error handling in src/proxyScripts/proxy.js for insufficient permissions (return "Unauthorized")
|
|
- [ ] T047 [US3] Add 403 error handling in src/proxyScripts/proxy.js for unsupported mimetypes with no exportLinks (return "mimetype not supported")
|
|
- [ ] T048 [US3] Add 502 error handling in src/proxyScripts/proxy.js for Google Drive API unavailability (return "Bad Gateway - Google Drive API unavailable")
|
|
- [ ] T049 [US3] Add 500 error handling in src/proxyScripts/proxy.js for malformed/inaccessible export links (return "Export failed - unable to retrieve document content")
|
|
- [ ] T050 [US3] Add 30-second timeout configuration in src/proxyScripts/proxy.js for all axios requests using timeout option
|
|
- [ ] T051 [US3] Add 504 error handling in src/proxyScripts/proxy.js for timeout errors (return "Gateway Timeout")
|
|
- [ ] T052 [US3] Integrate error mapping helper in src/proxyScripts/proxy.js to convert Google Drive API errors to appropriate HTTP status codes
|
|
|
|
**Checkpoint**: User Story 3 complete - all tests should now PASS. Verify all three user stories (US1, US2, US3) work independently and together.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Improvements that affect multiple user stories and final quality checks
|
|
|
|
- [ ] T053 [P] Run all tests to verify 80%+ code coverage target achieved using Node.js built-in coverage tool
|
|
- [ ] T054 [P] Update quickstart.md with actual implementation details and verify all examples work in specs/002-document-export/quickstart.md
|
|
- [ ] T055 [P] Code review: Verify all logic in src/proxyScripts/proxy.js follows monolithic architecture (no imports/exports)
|
|
- [ ] T056 [P] Code review: Verify all helper functions in src/globalVariables/googleDriveAdapterHelper.js are pure functions with literal function body pattern
|
|
- [ ] T057 [P] Security review: Verify authentication uses existing Google Drive OAuth2/service account credentials
|
|
- [ ] T058 [P] Performance validation: Test with 50 concurrent requests and verify <5 second response time for documents <10MB
|
|
- [ ] T059 Manual testing: Test complete workflow with real Google Drive documents (Docs, Sheets, Slides, PDFs)
|
|
- [ ] T060 Documentation: Update README.md or API documentation with new /documents/:documentId endpoint usage
|
|
|
|
**Checkpoint**: Feature complete - ready for integration testing and deployment
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: No dependencies - can start immediately
|
|
- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
|
|
- **User Stories (Phase 3-5)**: All depend on Foundational phase completion
|
|
- User stories can then proceed in parallel (if staffed)
|
|
- Or sequentially in priority order (P1 → P2 → P3)
|
|
- **Polish (Phase 6)**: Depends on all desired user stories being complete
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
|
|
- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - Independent of US1 (different code paths)
|
|
- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - Adds error handling to US1/US2 code paths
|
|
|
|
### Within Each User Story
|
|
|
|
**MANDATORY TEST-FIRST WORKFLOW**:
|
|
1. Tests MUST be written FIRST
|
|
2. Tests MUST FAIL before implementation
|
|
3. User MUST approve test scenarios
|
|
4. Implementation proceeds only after approval
|
|
5. Tests MUST PASS after implementation
|
|
6. Code coverage MUST be ≥80%
|
|
|
|
**Task Execution**:
|
|
- All tests for a story marked [P] can be written in parallel
|
|
- Implementation tasks may have dependencies (metadata fetch before format selection)
|
|
- Verify all tests pass before moving to next user story
|
|
|
|
### Parallel Opportunities
|
|
|
|
- **Setup tasks**: Both can run in parallel
|
|
- **Foundational tasks**: All T003-T006 marked [P] can run in parallel (different helper functions)
|
|
- **User story tests**: All tests within a story marked [P] can run in parallel (different test files or independent test cases)
|
|
- **User stories**: Once Foundational completes, all three user stories can be implemented in parallel by different developers (mostly independent code paths)
|
|
- US1: Main export logic (metadata fetch, format selection, streaming)
|
|
- US2: Native PDF path (separate code branch)
|
|
- US3: Error handling (wraps US1/US2 code)
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1 Tests
|
|
|
|
```bash
|
|
# Launch all US1 tests together (after Phase 2 complete):
|
|
Task T007: "Contract test: Valid Google Workspace document returns 200..."
|
|
Task T008: "Contract test: Valid document returns Content-Disposition..."
|
|
Task T009: "Contract test: Document with Markdown export returns..."
|
|
Task T010: "Contract test: Document without Markdown but with HTML..."
|
|
Task T011: "Contract test: Document with only PDF export..."
|
|
Task T012: "Integration test: Fetch metadata from Google Drive API..."
|
|
Task T013: "Integration test: Select first available export format..."
|
|
Task T014: "Integration test: Stream content from Google Drive..."
|
|
Task T015: "Unit test: Format selection prioritizes text/x-markdown..."
|
|
Task T016: "Unit test: Content-Disposition header generation..."
|
|
```
|
|
|
|
All these tests can be written simultaneously since they test different aspects of the same functionality.
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First (User Story 1 Only)
|
|
|
|
1. Complete Phase 1: Setup (T001-T002)
|
|
2. Complete Phase 2: Foundational (T003-T006) - CRITICAL blocker
|
|
3. Complete Phase 3: User Story 1 (T007-T023)
|
|
- Write ALL tests first (T007-T016)
|
|
- Get user approval of test scenarios
|
|
- Implement (T017-T023)
|
|
- Verify all tests pass
|
|
4. **STOP and VALIDATE**: Test User Story 1 independently with real Google Drive documents
|
|
5. Deploy/demo if ready - MVP feature complete!
|
|
|
|
**MVP Scope**: Export Google Workspace documents in best available format with proper headers.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Complete Setup + Foundational → Foundation ready
|
|
2. Add User Story 1 → Test independently → Deploy/Demo (MVP - export Workspace docs!)
|
|
3. Add User Story 2 → Test independently → Deploy/Demo (add native PDF support)
|
|
4. Add User Story 3 → Test independently → Deploy/Demo (add comprehensive error handling)
|
|
5. Complete Polish → Final validation → Production ready
|
|
|
|
### Parallel Team Strategy
|
|
|
|
With multiple developers:
|
|
|
|
1. Team completes Setup + Foundational together (CRITICAL - blocks everything)
|
|
2. Once Foundational is done:
|
|
- **Developer A**: User Story 1 (main export logic)
|
|
- **Developer B**: User Story 2 (native PDF streaming)
|
|
- **Developer C**: User Story 3 (error handling)
|
|
3. Stories complete and integrate independently
|
|
4. Team validates together
|
|
|
|
**Note**: US3 (error handling) may need to coordinate with US1/US2 since it wraps their code paths with error handling, but can still be developed in parallel and merged last.
|
|
|
|
---
|
|
|
|
## Testing Strategy (Constitution Requirement)
|
|
|
|
### Test-First Development (MANDATORY)
|
|
|
|
Per project constitution Section III:
|
|
|
|
1. **Write failing tests FIRST** - all test tasks (T007-T016, T024-T029, T035-T044) MUST be completed before corresponding implementation tasks
|
|
2. **Obtain user approval** - checkpoint after each test phase to review and approve test scenarios
|
|
3. **Implement minimum code** - only enough to pass tests
|
|
4. **Maintain 80%+ coverage** - verified in Phase 6 (T053)
|
|
|
|
### Test Organization
|
|
|
|
- **Contract Tests** (`tests/contract/documents-export.test.js`):
|
|
- HTTP endpoint behavior verification
|
|
- Status codes, headers, response formats
|
|
- End-to-end request/response validation
|
|
|
|
- **Integration Tests** (`tests/integration/google-drive-export.test.js`):
|
|
- Google Drive API interactions with mocks
|
|
- Format selection algorithm
|
|
- Streaming behavior
|
|
- Timeout and size limit enforcement
|
|
|
|
- **Unit Tests** (`tests/unit/`):
|
|
- `format-selection.test.js`: Format priority logic
|
|
- `export-headers.test.js`: Header generation (Content-Type, Content-Disposition)
|
|
- `error-mapping.test.js`: Error code mapping
|
|
|
|
### Success Criteria
|
|
|
|
- ✅ All tests pass
|
|
- ✅ Code coverage ≥80%
|
|
- ✅ All user stories independently testable
|
|
- ✅ No imports/exports in proxy.js (monolithic architecture verified)
|
|
- ✅ Performance: <5s for docs <10MB, 50 concurrent requests
|
|
- ✅ 99% success rate for valid requests
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- **[P] tasks** = different files, no dependencies, can run in parallel
|
|
- **[Story] label** maps task to specific user story for traceability
|
|
- **Test-First is MANDATORY** - constitution requires TDD workflow
|
|
- **Monolithic architecture** - all business logic in `src/proxyScripts/proxy.js`, zero imports/exports
|
|
- **Helper functions** - optional pure utilities in `src/globalVariables/googleDriveAdapterHelper.js`
|
|
- **User approval required** at test checkpoints before implementation
|
|
- **Commit after each task** or logical group
|
|
- **Stop at any checkpoint** to validate story independently
|
|
- **Total tasks**: 60 (10 tests, 50 implementation/setup, solid coverage of all requirements)
|
|
|
|
---
|
|
|
|
## Task Count Summary
|
|
|
|
- **Phase 1 (Setup)**: 2 tasks
|
|
- **Phase 2 (Foundational)**: 4 tasks (all parallelizable)
|
|
- **Phase 3 (User Story 1)**: 17 tasks (10 tests [P], 7 implementation)
|
|
- **Phase 4 (User Story 2)**: 11 tasks (6 tests [P], 5 implementation)
|
|
- **Phase 5 (User Story 3)**: 18 tasks (10 tests [P], 8 implementation)
|
|
- **Phase 6 (Polish)**: 8 tasks (7 parallelizable)
|
|
|
|
**Total**: 60 tasks
|
|
|
|
**Parallel Opportunities**: 37 tasks marked [P] (62% of all tasks)
|
|
|
|
**Test Coverage**: 26 test tasks (43% of total) ensuring TDD compliance
|
|
|
|
**MVP Scope**: Phases 1-3 (23 tasks) = Basic Google Workspace document export
|