feat(docs): complete P2.6 type safety cleanup and P2.7 system invariants
P2.6: Type Safety Cleanup - Replaced 'any' return types in vite-plugin.ts with concrete types (UserConfig, transform return type) - Documented TypeScript mixin 'any[]' exception in PlatformServiceMixin.ts - Audit confirmed: zero 'any' in codebase except documented TS mixin limitation - All external boundaries use 'unknown', all data payloads use 'Record<string, unknown>' P2.7: System Invariants Documentation - Created SYSTEM_INVARIANTS.md documenting all 6 enforced invariants - Added to docs/00-INDEX.md under Policy & Contracts section - Each invariant includes: What, Why, How, Where Progress Docs Updates: - Updated 00-STATUS.md: marked P2.6/P2.7 complete, added type safety invariant note - Updated 01-CHANGELOG-WORK.md: added 2025-12-22 entries for P2.6/P2.7 - Updated 03-TEST-RUNS.md: added P2.6 type safety audit test run - Updated P2-DESIGN.md: marked P2.6 acceptance criteria complete - Updated SYSTEM_INVARIANTS.md: added Type Safety Notes section Baseline Tag: - Created v1.0.11-p0-p1.4-p1.5-p2.6-p2.7-complete TypeScript compilation: ✅ PASSES Build: ✅ PASSES CI: ✅ All checks pass
This commit is contained in:
Matthew Raymer
103
docs/_archive/2025-12-16-consolidation/CONSOLIDATION_COMPLETE.md
Normal file
103
docs/_archive/2025-12-16-consolidation/CONSOLIDATION_COMPLETE.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# Documentation Consolidation Complete
|
||||
|
||||
**Date:** 2025-12-16
|
||||
**Status:** ✅ **CONSOLIDATION COMPLETE**
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Successfully consolidated 139 markdown files into an organized documentation structure with zero information loss.
|
||||
|
||||
### Results
|
||||
|
||||
- **Total Files Processed:** 139
|
||||
- **Canonical Files:** ~95 (active documentation)
|
||||
- **Archived Files:** ~29 (preserved verbatim)
|
||||
- **Merged Files:** ~15 (content incorporated into canonical docs)
|
||||
- **New Directory Structure:** 7 organized categories
|
||||
|
||||
---
|
||||
|
||||
## New Directory Structure
|
||||
|
||||
```
|
||||
docs/
|
||||
├── 00-INDEX.md # Central navigation hub
|
||||
├── CONSOLIDATION_SOURCE_MAP.md # Complete audit trail
|
||||
├── integration/ # Integration documentation
|
||||
├── platform/
|
||||
│ ├── ios/ # iOS platform docs
|
||||
│ └── android/ # Android platform docs
|
||||
├── testing/ # Testing documentation
|
||||
├── alarms/ # Alarm system (kept as-is)
|
||||
├── design/ # Design & research
|
||||
├── ai/ # AI/ChatGPT artifacts
|
||||
└── archive/
|
||||
└── 2025-legacy-doc/ # Historical documentation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Changes
|
||||
|
||||
### 1. Integration Documentation
|
||||
- Consolidated to `docs/integration/`
|
||||
- Primary guide: `INTEGRATION_GUIDE.md`
|
||||
- Quick start: `QUICK_START.md`
|
||||
- Troubleshooting: `TROUBLESHOOTING.md`
|
||||
|
||||
### 2. Platform Documentation
|
||||
- **iOS**: `docs/platform/ios/` (10 files)
|
||||
- **Android**: `docs/platform/android/` (9 files)
|
||||
- Separated by platform for clarity
|
||||
|
||||
### 3. Testing Documentation
|
||||
- Consolidated to `docs/testing/`
|
||||
- Platform-specific testing guides
|
||||
- Test app docs remain with test apps (indexed)
|
||||
|
||||
### 4. Legacy Documentation
|
||||
- Entire `doc/` directory archived to `docs/archive/2025-legacy-doc/`
|
||||
- Select files promoted to canonical locations
|
||||
- All files preserved verbatim
|
||||
|
||||
### 5. AI Artifacts
|
||||
- Moved to `docs/ai/`
|
||||
- Clearly separated from product documentation
|
||||
|
||||
### 6. Design & Research
|
||||
- Consolidated to `docs/design/`
|
||||
- Includes promoted design documents
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
✅ All 139 files have destinations
|
||||
✅ No files deleted
|
||||
✅ Archive preserves original structure
|
||||
✅ Index provides navigation
|
||||
✅ README.md updated with links
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review** the new structure
|
||||
2. **Update** any internal links that reference old paths
|
||||
3. **Test** navigation from README → Index → Documentation
|
||||
4. **Merge** content from "Merged" files into canonical docs (if needed)
|
||||
|
||||
---
|
||||
|
||||
## Reference Documents
|
||||
|
||||
- **[00-INDEX.md](./00-INDEX.md)** - Complete documentation index
|
||||
- **[CONSOLIDATION_SOURCE_MAP.md](./CONSOLIDATION_SOURCE_MAP.md)** - Complete file mapping
|
||||
|
||||
---
|
||||
|
||||
**Consolidation Date:** 2025-12-16
|
||||
**Status:** Complete - Ready for Use
|
||||
|
||||
@@ -0,0 +1,278 @@
|
||||
# Documentation Consolidation Source Map
|
||||
|
||||
**Date:** 2025-12-16
|
||||
**Purpose:** Complete audit trail of all markdown file destinations during consolidation
|
||||
**Total Files Mapped:** 139
|
||||
|
||||
This document guarantees no information loss by tracking every file's destination.
|
||||
|
||||
---
|
||||
|
||||
## Legend
|
||||
|
||||
- **Canonical**: File kept in active documentation, possibly edited/merged
|
||||
- **Merged**: Content incorporated into canonical document, original archived
|
||||
- **Archived**: File preserved verbatim in archive, referenced from index
|
||||
|
||||
---
|
||||
|
||||
## Root Canonical Files (Keep As-Is)
|
||||
|
||||
| Original Path | Status | Notes |
|
||||
|--------------|--------|-------|
|
||||
| `README.md` | Canonical | Main entry point, will link to docs/00-INDEX.md |
|
||||
| `ARCHITECTURE.md` | Canonical | Foundational architecture document |
|
||||
| `BUILDING.md` | Canonical | Build instructions |
|
||||
| `CHANGELOG.md` | Canonical | Version history |
|
||||
| `CONTRIBUTING.md` | Canonical | Contribution guidelines |
|
||||
| `SECURITY.md` | Canonical | Security documentation |
|
||||
| `API.md` | Canonical | API reference |
|
||||
| `USAGE.md` | Canonical | Usage guide |
|
||||
| `TODO.md` | Canonical | Project TODO list |
|
||||
| `PR_DESCRIPTION.md` | Canonical | PR template/description |
|
||||
| `MERGE_READY_SUMMARY.md` | Canonical | Merge readiness summary |
|
||||
|
||||
---
|
||||
|
||||
## Integration Documentation (Consolidate to `docs/integration/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `INTEGRATION_GUIDE.md` | `docs/integration/INTEGRATION_GUIDE.md` | Canonical | Primary integration guide |
|
||||
| `QUICK_INTEGRATION.md` | `docs/integration/QUICK_START.md` | Canonical | Quick start guide |
|
||||
| `AI_INTEGRATION_GUIDE.md` | `docs/ai/AI_INTEGRATION_GUIDE.md` | Canonical | AI-specific integration |
|
||||
| `doc/INTEGRATION_CHECKLIST.md` | `docs/integration/CHECKLIST.md` | Merged | Merge into INTEGRATION_GUIDE.md |
|
||||
| `docs/INTEGRATION_REFACTOR_CONTEXT.md` | `docs/integration/REFACTOR_NOTES.md` | Merged | Merge context into refactor notes |
|
||||
| `docs/INTEGRATION_REFACTOR_QUICK_START.md` | `docs/integration/REFACTOR_NOTES.md` | Merged | Merge into refactor notes |
|
||||
| `docs/aar-integration-troubleshooting.md` | `docs/integration/TROUBLESHOOTING.md` | Merged | Merge into troubleshooting guide |
|
||||
| `docs/integration-point-refactor-analysis.md` | `docs/integration/REFACTOR_NOTES.md` | Merged | Merge into refactor notes |
|
||||
|
||||
---
|
||||
|
||||
## Legacy Documentation (Archive to `docs/archive/2025-legacy-doc/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `doc/BACKGROUND_DATA_FETCHING_PLAN.md` | `docs/archive/2025-legacy-doc/BACKGROUND_DATA_FETCHING_PLAN.md` | Archived | Historical planning doc |
|
||||
| `doc/BUILD_FIXES_SUMMARY.md` | `docs/archive/2025-legacy-doc/BUILD_FIXES_SUMMARY.md` | Archived | Historical build fixes |
|
||||
| `doc/BUILD_SCRIPT_IMPROVEMENTS.md` | `docs/archive/2025-legacy-doc/BUILD_SCRIPT_IMPROVEMENTS.md` | Archived | Historical build improvements |
|
||||
| `doc/directives/0001-Daily-Notification-Plugin-Implementation-Directive.md` | `docs/archive/2025-legacy-doc/directives/0001-Daily-Notification-Plugin-Implementation-Directive.md` | Archived | Historical directive |
|
||||
| `doc/directives/0002-Daily-Notification-Plugin-Recommendations.md` | `docs/archive/2025-legacy-doc/directives/0002-Daily-Notification-Plugin-Recommendations.md` | Archived | Historical recommendations |
|
||||
| `doc/directives/0003-iOS-Android-Parity-Directive.md` | `docs/archive/2025-legacy-doc/directives/0003-iOS-Android-Parity-Directive.md` | Archived | Historical directive |
|
||||
| `doc/implementation-roadmap.md` | `docs/archive/2025-legacy-doc/implementation-roadmap.md` | Archived | Historical roadmap |
|
||||
| `doc/IOS_ANDROID_ERROR_CODE_MAPPING.md` | `docs/archive/2025-legacy-doc/IOS_ANDROID_ERROR_CODE_MAPPING.md` | Archived | Historical mapping |
|
||||
| `doc/IOS_PHASE1_FINAL_SUMMARY.md` | `docs/archive/2025-legacy-doc/IOS_PHASE1_FINAL_SUMMARY.md` | Archived | Historical summary |
|
||||
| `doc/IOS_PHASE1_GAPS_ANALYSIS.md` | `docs/archive/2025-legacy-doc/IOS_PHASE1_GAPS_ANALYSIS.md` | Archived | Historical analysis |
|
||||
| `doc/IOS_PHASE1_IMPLEMENTATION_CHECKLIST.md` | `docs/platform/ios/IMPLEMENTATION_CHECKLIST.md` | Merged | Promote to canonical iOS docs |
|
||||
| `doc/IOS_PHASE1_QUICK_REFERENCE.md` | `docs/archive/2025-legacy-doc/IOS_PHASE1_QUICK_REFERENCE.md` | Archived | Historical quick reference |
|
||||
| `doc/IOS_PHASE1_READY_FOR_TESTING.md` | `docs/archive/2025-legacy-doc/IOS_PHASE1_READY_FOR_TESTING.md` | Archived | Historical testing status |
|
||||
| `doc/IOS_PHASE1_TESTING_GUIDE.md` | `docs/testing/IOS_PHASE1_TESTING_GUIDE.md` | Merged | Promote to testing docs |
|
||||
| `doc/IOS_TEST_APP_SETUP_GUIDE.md` | `docs/testing/IOS_TEST_APP_SETUP.md` | Merged | Promote to testing docs |
|
||||
| `doc/migration-guide.md` | `docs/platform/ios/MIGRATION_GUIDE.md` | Merged | Promote to canonical iOS docs |
|
||||
| `doc/notification-system.md` | `docs/archive/2025-legacy-doc/notification-system.md` | Archived | Historical system doc |
|
||||
| `doc/PHASE1_COMPLETION_SUMMARY.md` | `docs/archive/2025-legacy-doc/PHASE1_COMPLETION_SUMMARY.md` | Archived | Historical summary |
|
||||
| `doc/RESEARCH_COMPLETE.md` | `docs/archive/2025-legacy-doc/RESEARCH_COMPLETE.md` | Archived | Historical research doc |
|
||||
| `doc/STARRED_PROJECTS_POLLING_IMPLEMENTATION.md` | `docs/design/STARRED_PROJECTS_POLLING_IMPLEMENTATION.md` | Canonical | Promote to design docs (large, relevant) |
|
||||
| `doc/test-app-ios/ENHANCEMENTS_APPLIED.md` | `docs/archive/2025-legacy-doc/test-app-ios/ENHANCEMENTS_APPLIED.md` | Archived | Historical enhancements |
|
||||
| `doc/test-app-ios/IOS_LOGGING_GUIDE.md` | `docs/testing/IOS_LOGGING_GUIDE.md` | Merged | Promote to testing docs |
|
||||
| `doc/test-app-ios/IOS_PREFETCH_GLOSSARY.md` | `docs/platform/ios/PREFETCH_GLOSSARY.md` | Merged | Promote to iOS docs |
|
||||
| `doc/test-app-ios/IOS_PREFETCH_TESTING.md` | `docs/testing/IOS_PREFETCH_TESTING.md` | Merged | Promote to testing docs |
|
||||
| `doc/test-app-ios/IOS_TEST_APP_REQUIREMENTS.md` | `docs/testing/IOS_TEST_APP_REQUIREMENTS.md` | Merged | Promote to testing docs |
|
||||
| `doc/UI_REQUIREMENTS.md` | `docs/archive/2025-legacy-doc/UI_REQUIREMENTS.md` | Archived | Historical requirements |
|
||||
|
||||
---
|
||||
|
||||
## Platform Documentation - iOS (Consolidate to `docs/platform/ios/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `docs/IOS_IMPLEMENTATION_CHECKLIST.md` | `docs/platform/ios/IMPLEMENTATION_CHECKLIST.md` | Canonical | Primary iOS checklist |
|
||||
| `docs/ios-implementation-directive.md` | `docs/platform/ios/IMPLEMENTATION_DIRECTIVE.md` | Canonical | iOS implementation directive |
|
||||
| `docs/IOS_IMPLEMENTATION_DOCUMENTATION_REVIEW.md` | `docs/platform/ios/DOCUMENTATION_REVIEW.md` | Canonical | Documentation review |
|
||||
| `docs/ios-core-data-migration.md` | `docs/platform/ios/CORE_DATA_MIGRATION.md` | Canonical | Core Data migration guide |
|
||||
| `docs/ios-recovery-scenario-mapping.md` | `docs/platform/ios/RECOVERY_SCENARIO_MAPPING.md` | Canonical | Recovery scenario mapping |
|
||||
| `docs/ios-rollover-edge-case-plan.md` | `docs/platform/ios/ROLLOVER_EDGE_CASES.md` | Canonical | Rollover edge cases |
|
||||
| `docs/ios-rollover-implementation-review.md` | `docs/platform/ios/ROLLOVER_IMPLEMENTATION_REVIEW.md` | Canonical | Rollover implementation review |
|
||||
| `docs/ios-rollover-open-questions-answers.md` | `docs/platform/ios/ROLLOVER_QA.md` | Canonical | Rollover Q&A |
|
||||
| `docs/ios-troubleshooting-guide.md` | `docs/platform/ios/TROUBLESHOOTING.md` | Canonical | iOS troubleshooting |
|
||||
|
||||
---
|
||||
|
||||
## Platform Documentation - Android (Consolidate to `docs/platform/android/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `docs/android-implementation-directive.md` | `docs/platform/android/IMPLEMENTATION_DIRECTIVE.md` | Canonical | Primary Android directive |
|
||||
| `docs/android-implementation-directive-phase1.md` | `docs/platform/android/PHASE1_DIRECTIVE.md` | Canonical | Phase 1 directive |
|
||||
| `docs/android-implementation-directive-phase2.md` | `docs/platform/android/PHASE2_DIRECTIVE.md` | Canonical | Phase 2 directive |
|
||||
| `docs/android-implementation-directive-phase3.md` | `docs/platform/android/PHASE3_DIRECTIVE.md` | Canonical | Phase 3 directive |
|
||||
| `docs/android-alarm-persistence-directive.md` | `docs/platform/android/ALARM_PERSISTENCE_DIRECTIVE.md` | Canonical | Alarm persistence directive |
|
||||
| `docs/android-app-analysis.md` | `docs/platform/android/APP_ANALYSIS.md` | Canonical | App analysis |
|
||||
| `docs/android-app-improvement-plan.md` | `docs/platform/android/APP_IMPROVEMENT_PLAN.md` | Canonical | App improvement plan |
|
||||
| `android/BUILDING.md` | `docs/platform/android/BUILDING.md` | Canonical | Android build guide |
|
||||
| `android/DATABASE_CONSOLIDATION_PLAN.md` | `docs/platform/android/DATABASE_CONSOLIDATION_PLAN.md` | Canonical | Database consolidation plan |
|
||||
|
||||
---
|
||||
|
||||
## Testing Documentation (Consolidate to `docs/testing/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `docs/comprehensive-testing-guide-v2.md` | `docs/testing/COMPREHENSIVE_GUIDE.md` | Canonical | Primary testing guide |
|
||||
| `docs/testing-quick-reference.md` | `docs/testing/QUICK_REFERENCE.md` | Canonical | Quick reference |
|
||||
| `docs/testing-quick-reference-v2.md` | `docs/testing/QUICK_REFERENCE.md` | Merged | Merge into QUICK_REFERENCE.md |
|
||||
| `docs/manual_smoke_test.md` | `docs/testing/MANUAL_SMOKE_TEST.md` | Canonical | Manual smoke test |
|
||||
| `docs/notification-testing-procedures.md` | `docs/testing/NOTIFICATION_PROCEDURES.md` | Canonical | Notification testing |
|
||||
| `docs/reboot-testing-procedure.md` | `docs/testing/REBOOT_PROCEDURE.md` | Canonical | Reboot testing |
|
||||
| `docs/reboot-testing-steps.md` | `docs/testing/REBOOT_PROCEDURE.md` | Merged | Merge into REBOOT_PROCEDURE.md |
|
||||
| `docs/boot-receiver-testing-guide.md` | `docs/testing/BOOT_RECEIVER_GUIDE.md` | Canonical | Boot receiver testing |
|
||||
| `docs/standalone-emulator-guide.md` | `docs/testing/EMULATOR_GUIDE.md` | Canonical | Emulator guide |
|
||||
| `docs/localhost-testing-guide.md` | `docs/testing/LOCALHOST_GUIDE.md` | Canonical | Localhost testing |
|
||||
|
||||
---
|
||||
|
||||
## Alarm System Documentation (Keep in `docs/alarms/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `docs/alarms/000-UNIFIED-ALARM-DIRECTIVE.md` | `docs/alarms/000-UNIFIED-ALARM-DIRECTIVE.md` | Canonical | Keep as-is |
|
||||
| `docs/alarms/01-platform-capability-reference.md` | `docs/alarms/01-platform-capability-reference.md` | Canonical | Keep as-is |
|
||||
| `docs/alarms/02-plugin-behavior-exploration.md` | `docs/alarms/02-plugin-behavior-exploration.md` | Canonical | Keep as-is |
|
||||
| `docs/alarms/03-plugin-requirements.md` | `docs/alarms/03-plugin-requirements.md` | Canonical | Keep as-is |
|
||||
| `docs/alarms/ACTIVATION-GUIDE.md` | `docs/alarms/ACTIVATION-GUIDE.md` | Canonical | Keep as-is |
|
||||
| `docs/alarms/PHASE1-EMULATOR-TESTING.md` | `docs/alarms/PHASE1-EMULATOR-TESTING.md` | Canonical | Keep as-is |
|
||||
| `docs/alarms/PHASE1-VERIFICATION.md` | `docs/alarms/PHASE1-VERIFICATION.md` | Canonical | Keep as-is |
|
||||
| `docs/alarms/PHASE2-EMULATOR-TESTING.md` | `docs/alarms/PHASE2-EMULATOR-TESTING.md` | Canonical | Keep as-is |
|
||||
| `docs/alarms/PHASE2-VERIFICATION.md` | `docs/alarms/PHASE2-VERIFICATION.md` | Canonical | Keep as-is |
|
||||
| `docs/alarms/PHASE3-EMULATOR-TESTING.md` | `docs/alarms/PHASE3-EMULATOR-TESTING.md` | Canonical | Keep as-is |
|
||||
| `docs/alarms/PHASE3-VERIFICATION.md` | `docs/alarms/PHASE3-VERIFICATION.md` | Canonical | Keep as-is |
|
||||
|
||||
---
|
||||
|
||||
## AI / ChatGPT Documentation (Consolidate to `docs/ai/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `chatgpt-assessment-package.md` | `docs/ai/chatgpt-assessment-package.md` | Canonical | AI artifacts |
|
||||
| `chatgpt-files-overview.md` | `docs/ai/chatgpt-files-overview.md` | Canonical | AI artifacts |
|
||||
| `chatgpt-improvement-directives-template.md` | `docs/ai/chatgpt-improvement-directives-template.md` | Canonical | AI artifacts |
|
||||
| `code-summary-for-chatgpt.md` | `docs/ai/code-summary-for-chatgpt.md` | Canonical | AI artifacts |
|
||||
| `key-code-snippets-for-chatgpt.md` | `docs/ai/key-code-snippets-for-chatgpt.md` | Canonical | AI artifacts |
|
||||
| `docs/chatgpt-analysis-guide.md` | `docs/ai/chatgpt-analysis-guide.md` | Canonical | AI artifacts |
|
||||
|
||||
---
|
||||
|
||||
## Design & Research Documentation (Consolidate to `docs/design/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `docs/exploration-findings-initial.md` | `docs/design/exploration-findings-initial.md` | Canonical | Design research |
|
||||
| `docs/explore-alarm-behavior-directive.md` | `docs/design/explore-alarm-behavior-directive.md` | Canonical | Design research |
|
||||
| `docs/improve-alarm-directives.md` | `docs/design/improve-alarm-directives.md` | Canonical | Design research |
|
||||
| `docs/plugin-behavior-exploration-template.md` | `docs/design/plugin-behavior-exploration-template.md` | Canonical | Design template |
|
||||
|
||||
---
|
||||
|
||||
## Deployment Documentation (Keep in `docs/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `DEPLOYMENT_CHECKLIST.md` | `docs/DEPLOYMENT_CHECKLIST.md` | Canonical | Move to docs/ |
|
||||
| `DEPLOYMENT_SUMMARY.md` | `docs/DEPLOYMENT_SUMMARY.md` | Canonical | Move to docs/ |
|
||||
| `docs/deployment-guide.md` | `docs/DEPLOYMENT_GUIDE.md` | Canonical | Primary deployment guide |
|
||||
|
||||
---
|
||||
|
||||
## Feature-Specific Documentation (Keep in `docs/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `docs/CROSS_PLATFORM_STORAGE_PATTERN.md` | `docs/CROSS_PLATFORM_STORAGE_PATTERN.md` | Canonical | Keep as-is |
|
||||
| `docs/DATABASE_INTERFACES.md` | `docs/DATABASE_INTERFACES.md` | Canonical | Keep as-is |
|
||||
| `docs/DATABASE_INTERFACES_IMPLEMENTATION.md` | `docs/DATABASE_INTERFACES_IMPLEMENTATION.md` | Canonical | Keep as-is |
|
||||
| `docs/NATIVE_FETCHER_CONFIGURATION.md` | `docs/NATIVE_FETCHER_CONFIGURATION.md` | Canonical | Keep as-is |
|
||||
| `docs/platform-capability-reference.md` | `docs/platform-capability-reference.md` | Canonical | Keep as-is |
|
||||
| `docs/plugin-requirements-implementation.md` | `docs/plugin-requirements-implementation.md` | Canonical | Keep as-is |
|
||||
| `docs/prefetch-scheduling-diagnosis.md` | `docs/prefetch-scheduling-diagnosis.md` | Canonical | Keep as-is |
|
||||
| `docs/prefetch-scheduling-trace.md` | `docs/prefetch-scheduling-trace.md` | Canonical | Keep as-is |
|
||||
| `docs/app-startup-recovery-solution.md` | `docs/app-startup-recovery-solution.md` | Canonical | Keep as-is |
|
||||
| `docs/getting-valid-plan-ids.md` | `docs/getting-valid-plan-ids.md` | Canonical | Keep as-is |
|
||||
| `docs/host-request-configuration.md` | `docs/host-request-configuration.md` | Canonical | Keep as-is |
|
||||
| `docs/hydrate-plan-implementation-guide.md` | `docs/hydrate-plan-implementation-guide.md` | Canonical | Keep as-is |
|
||||
| `docs/user-zero-stars-implementation.md` | `docs/user-zero-stars-implementation.md` | Canonical | Keep as-is |
|
||||
| `docs/accessibility-localization.md` | `docs/accessibility-localization.md` | Canonical | Keep as-is |
|
||||
| `docs/legal-store-compliance.md` | `docs/legal-store-compliance.md` | Canonical | Keep as-is |
|
||||
| `docs/observability-dashboards.md` | `docs/observability-dashboards.md` | Canonical | Keep as-is |
|
||||
| `docs/file-organization-summary.md` | `docs/file-organization-summary.md` | Canonical | Keep as-is |
|
||||
| `docs/capacitor-platform-service-clean-changes.md` | `docs/capacitor-platform-service-clean-changes.md` | Canonical | Keep as-is |
|
||||
|
||||
---
|
||||
|
||||
## Test App Documentation (Keep with Test Apps, Index in `docs/testing/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `test-apps/BUILD_PROCESS.md` | `test-apps/BUILD_PROCESS.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/android-test-app/docs/PHASE1_TEST0_GOLDEN.md` | `test-apps/android-test-app/docs/PHASE1_TEST0_GOLDEN.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/android-test-app/docs/PHASE1_TEST1_GOLDEN.md` | `test-apps/android-test-app/docs/PHASE1_TEST1_GOLDEN.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/daily-notification-test/docs/BUILD_QUICK_REFERENCE.md` | `test-apps/daily-notification-test/docs/BUILD_QUICK_REFERENCE.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/daily-notification-test/docs/NOTIFICATION_STACK_IMPROVEMENT_PLAN.md` | `test-apps/daily-notification-test/docs/NOTIFICATION_STACK_IMPROVEMENT_PLAN.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/daily-notification-test/docs/PLUGIN_DETECTION_GUIDE.md` | `test-apps/daily-notification-test/docs/PLUGIN_DETECTION_GUIDE.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/daily-notification-test/docs/VUE3_NOTIFICATION_IMPLEMENTATION_GUIDE.md` | `test-apps/daily-notification-test/docs/VUE3_NOTIFICATION_IMPLEMENTATION_GUIDE.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/daily-notification-test/IMPLEMENTATION_COMPLETE.md` | `test-apps/daily-notification-test/IMPLEMENTATION_COMPLETE.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/daily-notification-test/INVESTIGATION_JWT_ALGORITHM.md` | `test-apps/daily-notification-test/INVESTIGATION_JWT_ALGORITHM.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/daily-notification-test/INVESTIGATION_JWT_ALGORITHM_RESULTS.md` | `test-apps/daily-notification-test/INVESTIGATION_JWT_ALGORITHM_RESULTS.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/daily-notification-test/README.md` | `test-apps/daily-notification-test/README.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/daily-notification-test/TODO_NATIVE_FETCHER.md` | `test-apps/daily-notification-test/TODO_NATIVE_FETCHER.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/ios-test-app/BUILD_NOTES.md` | `test-apps/ios-test-app/BUILD_NOTES.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/ios-test-app/BUILD_SUCCESS.md` | `test-apps/ios-test-app/BUILD_SUCCESS.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/ios-test-app/COMPILATION_FIXES.md` | `test-apps/ios-test-app/COMPILATION_FIXES.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/ios-test-app/COMPILATION_STATUS.md` | `test-apps/ios-test-app/COMPILATION_STATUS.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/ios-test-app/COMPILATION_SUMMARY.md` | `test-apps/ios-test-app/COMPILATION_SUMMARY.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/ios-test-app/README.md` | `test-apps/ios-test-app/README.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/ios-test-app/SETUP_COMPLETE.md` | `test-apps/ios-test-app/SETUP_COMPLETE.md` | Canonical | Keep with test apps |
|
||||
| `test-apps/ios-test-app/SETUP_STATUS.md` | `test-apps/ios-test-app/SETUP_STATUS.md` | Canonical | Keep with test apps |
|
||||
|
||||
---
|
||||
|
||||
## Plugin-Specific Documentation (Keep in `ios/Plugin/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `ios/Plugin/README.md` | `ios/Plugin/README.md` | Canonical | Keep with plugin code |
|
||||
|
||||
---
|
||||
|
||||
## Cursor Rules Documentation (Keep in `.cursor/rules/`)
|
||||
|
||||
| Original Path | New Path | Status | Notes |
|
||||
|--------------|----------|--------|-------|
|
||||
| `.cursor/rules/README.md` | `.cursor/rules/README.md` | Canonical | Keep with cursor rules |
|
||||
| `.cursor/rules/architecture/README.md` | `.cursor/rules/architecture/README.md` | Canonical | Keep with cursor rules |
|
||||
| `.cursor/rules/meta_rule_architecture.md` | `.cursor/rules/meta_rule_architecture.md` | Canonical | Keep with cursor rules |
|
||||
|
||||
---
|
||||
|
||||
## Summary Statistics
|
||||
|
||||
- **Total Files:** 139
|
||||
- **Canonical (Active):** ~95 files
|
||||
- **Merged:** ~15 files
|
||||
- **Archived:** ~29 files
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] All 139 files have a destination
|
||||
- [ ] No file is marked for deletion
|
||||
- [ ] All merged content is traceable
|
||||
- [ ] Archive structure preserves original paths
|
||||
- [ ] Index references all canonical files
|
||||
- [ ] README.md links to docs/00-INDEX.md
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-12-16
|
||||
**Status:** Complete - Ready for Implementation
|
||||
|
||||
698
docs/_archive/2025-legacy-doc/BACKGROUND_DATA_FETCHING_PLAN.md
Normal file
698
docs/_archive/2025-legacy-doc/BACKGROUND_DATA_FETCHING_PLAN.md
Normal file
@@ -0,0 +1,698 @@
|
||||
# Background Data Fetching Implementation Plan
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Version**: 1.0.0
|
||||
**Created**: 2025-10-02 07:47:04 UTC
|
||||
**Last Updated**: 2025-10-02 12:45:00 UTC
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the **enhancement plan** for background data fetching in the Daily Notification Plugin to support TimeSafari integration with Option A architecture. This plan builds upon our existing implementation and adds:
|
||||
|
||||
- **Option A Enhancement**: ActiveDid-aware authentication on existing infrastructure
|
||||
- **TimeSafari Integration**: PlatformServiceMixin coordination with current plugin
|
||||
- **Authentication Layer**: JWT/DID support over existing HTTP callback system
|
||||
- **Database Enhancement**: Extend current storage with activeDid management
|
||||
- **Event & Change Management**: Identity change detection on existing notification system
|
||||
- **API Integration**: Endorser.ch endpoints through current ContentFetchConfig
|
||||
|
||||
This document serves as the enhancement roadmap for adding TimeSafari capabilities to our existing, working plugin.
|
||||
|
||||
## Current Implementation Baseline
|
||||
|
||||
### ✅ Already Implemented & Working
|
||||
- **Android Storage**: SharedPreferences + SQLite with migration (`DailyNotificationStorage.java`, `DailyNotificationDatabase.java`)
|
||||
- **Web Storage**: IndexedDB with comprehensive service worker (`sw.ts`, `IndexedDBManager`)
|
||||
- **Callback System**: HTTP/local callbacks with circuit breaker (`callback-registry.ts`)
|
||||
- **Configuration**: Database path, TTL, retention settings (`ConfigureOptions`)
|
||||
- **ETag Support**: Conditional HTTP requests (`DailyNotificationETagManager.java`)
|
||||
- **Dual Scheduling**: Content fetch + user notification separation
|
||||
- **Cross-Platform API**: Unified TypeScript interface (`DailyNotificationPlugin`)
|
||||
|
||||
### ⚠️ Enhancement Required for TimeSafari
|
||||
- **ActiveDid Integration**: Add activeDid-awareness to existing authentication
|
||||
- **JWT Generation**: Enhance HTTP layer with DID-based tokens
|
||||
- **Identity Change Detection**: Add event listeners to existing callback system
|
||||
- **Endorser.ch APIs**: Extend `ContentFetchConfig` with TimeSafari endpoints
|
||||
- **Platform Auth**: Add Android Keystore/iOS Keychain to existing storage
|
||||
|
||||
## Consolidated Architecture: Option A Platform Overview
|
||||
|
||||
```
|
||||
TimeSafari Host App
|
||||
↓ (provides activeDid)
|
||||
Daily Notification Plugin → Native Background Executor
|
||||
↓
|
||||
HTTP Client + Auth
|
||||
↓
|
||||
API Server Response
|
||||
↓
|
||||
Parse & Cache Data (plugin storage)
|
||||
↓
|
||||
Trigger Notifications
|
||||
```
|
||||
|
||||
### **Option A: Host Always Provides activeDid**
|
||||
|
||||
**Core Principle**: Host application queries its own database and provides activeDid to plugin.
|
||||
|
||||
### **Why Option A Is Superior:**
|
||||
1. **Clear Separation**: Host owns identity management, plugin owns notifications
|
||||
2. **No Database Conflicts**: Zero shared database access between host and plugin
|
||||
3. **Security Isolation**: Plugin data physically separated from user data
|
||||
4. **Platform Independence**: Works consistently regardless of host's database technology
|
||||
5. **Simplified Implementation**: Fewer moving parts, clearer debugging
|
||||
|
||||
## Android Implementation Strategy
|
||||
|
||||
### A. Background Execution Framework
|
||||
|
||||
- **Use WorkManager** for reliable background HTTP requests
|
||||
- **Enhance** existing Native HTTP clients (already implemented):
|
||||
- Extend `DailyNotificationETagManager.java` with JWT headers
|
||||
- Add JWT authentication to `DailyNotificationFetcher.java`
|
||||
- **Handle Android-specific constraints**: Doze mode, app standby, battery optimization
|
||||
|
||||
### B. Authentication Enhancement - Extend Current Infrastructure
|
||||
|
||||
**Goal**: Enhance existing `DailyNotificationETagManager.java` and `DailyNotificationFetcher.java` with JWT authentication
|
||||
|
||||
```kotlin
|
||||
// Enhance existing Android infrastructure with JWT authentication
|
||||
class DailyNotificationJWTManager {
|
||||
private val storage: DailyNotificationStorage
|
||||
private val currentActiveDid: String? = null
|
||||
|
||||
// Add JWT generation to existing fetcher
|
||||
fun generateJWTForActiveDid(activeDid: String, expiresInSeconds: Int): String {
|
||||
val payload = mapOf(
|
||||
"exp" to (System.currentTimeMillis() / 1000 + expiresInSeconds),
|
||||
"iat" to (System.currentTimeMillis() / 1000),
|
||||
"iss" to activeDid,
|
||||
"aud" to "timesafari.notifications",
|
||||
"sub" to activeDid
|
||||
)
|
||||
return signWithDID(payload, activeDid)
|
||||
}
|
||||
|
||||
// Enhance existing HTTP client with JWT headers
|
||||
fun enhanceHttpClientWithJWT(connection: HttpURLConnection, activeDid: String) {
|
||||
val jwt = generateJWTForActiveDid(activeDid, 60)
|
||||
connection.setRequestProperty("Authorization", "Bearer $jwt")
|
||||
connection.setRequestProperty("Content-Type", "application/json")
|
||||
}
|
||||
}
|
||||
|
||||
### C. HTTP Request Enhancement - Extend Existing Fetcher
|
||||
|
||||
**Goal**: Enhance existing `DailyNotificationFetcher.java` with Endorser.ch API support
|
||||
|
||||
```kotlin
|
||||
// Enhance existing DailyNotificationFetcher.java with TimeSafari APIs
|
||||
class EnhancedDailyNotificationFetcher : DailyNotificationFetcher {
|
||||
private val jwtManager: DailyNotificationJWTManager
|
||||
|
||||
suspend fun fetchEndorserOffers(activeDid: String, afterId: String?): Result {
|
||||
val connection = HttpURLConnection("$apiServer/api/v2/report/offers")
|
||||
|
||||
// Add JWT authentication to existing connection
|
||||
jwtManager.enhanceHttpClientWithJWT(connection, activeDid)
|
||||
|
||||
// Add Endorser.ch specific parameters
|
||||
connection.setRequestProperty("recipientDid", activeDid)
|
||||
if (afterId != null) {
|
||||
connection.setRequestProperty("afterId", afterId)
|
||||
}
|
||||
|
||||
// Use existing storeAndScheduleNotification method
|
||||
return fetchAndStoreContent(connection)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## iOS Implementation Strategy
|
||||
|
||||
### A. Background Execution Framework
|
||||
|
||||
- **Use BGTaskScheduler** for background HTTP requests
|
||||
- **Replace axios** with native iOS HTTP clients:
|
||||
- URLSession for HTTP requests
|
||||
- Combine framework for async/await patterns
|
||||
|
||||
### B. Authentication Implementation
|
||||
|
||||
```swift
|
||||
// JWT Generation in iOS
|
||||
class JWTHelper {
|
||||
func generateJWT(userDid: String, expiresInSeconds: Int) -> String {
|
||||
let payload: [String: Any] = [
|
||||
"exp": Int(Date().timeIntervalSince1970) + expiresInSeconds,
|
||||
"iat": Int(Date().timeIntervalSince1970),
|
||||
"iss": userDid
|
||||
]
|
||||
return signWithDID(payload, userDid)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### C. HTTP Request Implementation
|
||||
|
||||
```swift
|
||||
// Background HTTP Task
|
||||
class DataFetchTask {
|
||||
func fetchData() async {
|
||||
let jwt = generateJWT(userDid: activeDid, expiresInSeconds: 60)
|
||||
var request = URLRequest(url: apiURL)
|
||||
request.setValue("Bearer \(jwt)", forHTTPHeaderField: "Authorization")
|
||||
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
|
||||
|
||||
do {
|
||||
let (data, _) = try await URLSession.shared.data(for: request)
|
||||
let offersResponse = try JSONDecoder().decode(OffersResponse.self, from: data)
|
||||
await scheduleNotification(with: offersResponse.data)
|
||||
} catch {
|
||||
// Handle errors
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Data Models & Type Safety
|
||||
|
||||
### Shared TypeScript Interfaces
|
||||
|
||||
```typescript
|
||||
// Definitions for native bridge
|
||||
interface OffersResponse {
|
||||
data: OfferSummaryRecord[];
|
||||
hitLimit: boolean;
|
||||
}
|
||||
|
||||
interface OfferSummaryRecord {
|
||||
jwtId: string;
|
||||
handleId: string;
|
||||
issuedAt: string;
|
||||
offeredByDid: string;
|
||||
recipientDid: string;
|
||||
unit: string;
|
||||
amount: number;
|
||||
// ... other fields
|
||||
}
|
||||
```
|
||||
|
||||
### Native Implementations
|
||||
|
||||
- **Kotlin sealed classes** for type-safe responses
|
||||
- **Swift Codable structs** for JSON parsing
|
||||
- **Shared error handling** patterns
|
||||
|
||||
## Configuration Management
|
||||
|
||||
### Plugin Configuration
|
||||
|
||||
```typescript
|
||||
interface PluginConfig {
|
||||
apiServer: string;
|
||||
jwtExpirationSeconds: number;
|
||||
requestTimeoutMs: number;
|
||||
retryAttempts: number;
|
||||
activeDid: string; // Simplified to single active DID
|
||||
lastKnownOfferId?: string;
|
||||
lastKnownPlanId?: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Platform-Specific Settings
|
||||
|
||||
- **Android**: Manage API keys in `AndroidManifest.xml`, use SharedPreferences for runtime config
|
||||
- **iOS**: Use `Info.plist` for static config, UserDefaults for runtime settings
|
||||
|
||||
## Error Handling & Resilience
|
||||
|
||||
### Network Error Handling
|
||||
|
||||
- **Connectivity checks** before making requests
|
||||
- **Exponential backoff** for retry scenarios
|
||||
- **Circuit breaker pattern** for API failures
|
||||
- **Graceful degradation** when offline
|
||||
|
||||
### Authentication Error Handling
|
||||
|
||||
- **Token refresh** mechanisms
|
||||
- **Fallback to anonymous** requests when authentication fails
|
||||
- **Secure credential storage** using platform keychains
|
||||
|
||||
## Cache & State Management
|
||||
|
||||
### Data Persistence
|
||||
|
||||
#### **Platform-Specific Storage Architecture**
|
||||
|
||||
**Android/Electron Platforms:**
|
||||
- **@capacitor-community/sqlite** plugin integration for native SQLite access
|
||||
- **Shared plugin database** - Plugin manages its own SQLite database instance
|
||||
- **Direct SQL execution** via plugin's `dbExec()` methods for complex queries
|
||||
- **Background worker integration** for database operations during content fetch
|
||||
|
||||
**Web Platform:**
|
||||
- **absurd-sql** for SQLite support in browser (managed by host application)
|
||||
- **Plugin delegation pattern** - Plugin provides SQL queries, host executes them
|
||||
- **IndexedDB fallback** for basic caching when SQLite unavailable
|
||||
|
||||
**iOS Platform:**
|
||||
- **Core Data integration** via native Swift implementation
|
||||
- **Background task compatibility** with iOS background refresh constraints
|
||||
|
||||
### State Synchronization
|
||||
|
||||
- **JavaScript → Native** configuration updates
|
||||
- **Native → JavaScript** status reporting
|
||||
- **Cross-platform state consistency**
|
||||
- **Background ↔ Foreground** state synchronization
|
||||
- **Database logging** for audit trails and debugging
|
||||
|
||||
### Enhanced Caching Strategy
|
||||
|
||||
Based on TimeSafari's optimization patterns:
|
||||
|
||||
- **Batch-oriented processing** for API requests to reduce overhead
|
||||
- **Intelligent batching** with configurable timing (max 100ms wait, max 10 items)
|
||||
- **Memory-optimized caching** with automatic cleanup (keep last 1000 log entries)
|
||||
- **Request deduplication** to prevent redundant API calls
|
||||
- **Performance monitoring** with operation timing and metrics collection
|
||||
|
||||
## Performance Optimizations
|
||||
|
||||
### Request Optimization
|
||||
|
||||
- **Deduplication** of identical requests
|
||||
- **Batch requests** when possible
|
||||
- **Intelligent polling** based on user activity
|
||||
|
||||
### Memory Management
|
||||
|
||||
- **Background memory limits** enforcement
|
||||
- **Cache cleanup** on memory pressure
|
||||
- **Resource lifecycle** management
|
||||
|
||||
## Critical Requirement: Plugin Must Know When activeDid Changes
|
||||
|
||||
### **Security Implications of Missing ActiveDid Change Detection**
|
||||
|
||||
**Without immediate activeDid change detection, the plugin faces severe risks:**
|
||||
- **Cross-User Data Exposure**: Plugin fetches notifications for wrong user after identity switch
|
||||
- **Unauthorized API Access**: JWT tokens valid for incorrect user context
|
||||
- **Background Task Errors**: Content fetching operates with wrong identity
|
||||
|
||||
### **Event-Based Solution**
|
||||
|
||||
**Host Application Responsibility**: Dispatch `activeDidChanged` event
|
||||
```typescript
|
||||
// TimeSafari PlatformServiceMixin modification
|
||||
async $updateActiveDid(newDid: string | null): Promise<void> {
|
||||
// Update TimeSafari's active_identity table (existing logic)
|
||||
await this.$dbExec(
|
||||
"UPDATE active_identity SET activeDid = ?, lastUpdated = datetime('now') WHERE id = 1",
|
||||
[newDid || ""]
|
||||
);
|
||||
|
||||
// CRITICAL: Notify plugin of change IMMEDIATELY
|
||||
document.dispatchEvent(new CustomEvent('activeDidChanged', {
|
||||
detail: { activeDid: newDid }
|
||||
}));
|
||||
}
|
||||
```
|
||||
|
||||
**Plugin Responsibility**: Listen and respond to changes
|
||||
```typescript
|
||||
// Plugin service layer implementation
|
||||
plugin.onActiveDidChange(async (newActiveDid) => {
|
||||
// 1. Clear all cached content for previous identity
|
||||
await plugin.clearCacheForNewIdentity();
|
||||
|
||||
// 2. Refresh authentication tokens with new activeDid
|
||||
await plugin.refreshAuthenticationForNewIdentity(newActiveDid);
|
||||
|
||||
// 3. Restart background tasks with correct identity
|
||||
await plugin.updateBackgroundTaskIdentity(newActiveDid);
|
||||
|
||||
logger.info(`[DailyNotificationService] ActiveDid updated to: ${newActiveDid}`);
|
||||
});
|
||||
```
|
||||
|
||||
## TimeSafari Integration Patterns
|
||||
|
||||
### **ActiveDid Management Analysis**
|
||||
|
||||
**TimeSafari's Database Architecture:**
|
||||
- **Table**: `active_identity` (single row with `id = 1`)
|
||||
- **Content**: `activeDid TEXT`, `lastUpdated DATETIME`
|
||||
- **Purpose**: Single source of truth for active user identity
|
||||
|
||||
**Access via PlatformServiceMixin:**
|
||||
```typescript
|
||||
// Retrieving activeDid in TimeSafari components
|
||||
const activeIdentity = await this.$getActiveIdentity();
|
||||
const activeDid = activeIdentity.activeDid;
|
||||
|
||||
// Updating activeDid via PlatformServiceMixin
|
||||
async $updateActiveDid(newDid: string | null): Promise<void> {
|
||||
await this.$dbExec(
|
||||
"UPDATE active_identity SET activeDid = ?, lastUpdated = datetime('now') WHERE id = 1",
|
||||
[newDid || ""]
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### **Plugin Hosting Strategy**
|
||||
|
||||
**Existing Plugin Usage**: TimeSafari already uses Capacitor plugins extensively via `CapacitorPlatformService.ts`
|
||||
|
||||
**Recommended Integration Architecture:**
|
||||
- Plugin integrates as standard Capacitor plugin
|
||||
- Host provides activeDid via event-driven pattern
|
||||
- Plugin manages own isolated storage
|
||||
- Clear separation of responsibilities maintained
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Enhanced Plugin Interface for Host Application Integration
|
||||
|
||||
#### **Database Integration Patterns**
|
||||
|
||||
**Android/Electron: Host-Provided activeDid Approach (Option A)**
|
||||
```typescript
|
||||
// Host queries its own database and provides activeDid
|
||||
const activeIdentity = await this.$getActiveIdentity(); // Uses host's CapacitorSQLite
|
||||
await plugin.setActiveDidFromHost(activeIdentity.activeDid);
|
||||
|
||||
// Plugin configures its own isolated database
|
||||
await plugin.configureDatabase({
|
||||
platform: 'android',
|
||||
storageType: 'plugin-managed' // Plugin owns its storage
|
||||
});
|
||||
|
||||
// Set up activeDid change listener for future changes
|
||||
plugin.onActiveDidChange(async (newActiveDid) => {
|
||||
await plugin.clearCacheForNewIdentity();
|
||||
await plugin.refreshAuthenticationForNewIdentity(newActiveDid);
|
||||
logger.info(`[TimeSafari] ActiveDid changed to: ${newActiveDid}`);
|
||||
});
|
||||
```
|
||||
|
||||
**Web: Host-Provided activeDid Approach (Option A)**
|
||||
```typescript
|
||||
// Host queries its absurd-sql database and provides activeDid
|
||||
const activeIdentity = await this.$getActiveIdentity(); // Uses host's absurd-sql
|
||||
await plugin.setActiveDidFromHost(activeIdentity.activeDid);
|
||||
|
||||
// Plugin uses host-delegated storage for its own data
|
||||
await plugin.configureDatabase({
|
||||
platform: 'web',
|
||||
storageType: 'host-managed' // Plugin delegates to host for storage
|
||||
});
|
||||
|
||||
// Plugin operates independently with provided activeDid
|
||||
const results = await plugin.executeContentFetch(contentConfig);
|
||||
```
|
||||
|
||||
**iOS: Host-Provided activeDid Approach (Option A)**
|
||||
```typescript
|
||||
// Host queries its CapacitorSQLite database and provides activeDid
|
||||
const activeIdentity = await this.$getActiveIdentity(); // Uses host's CapacitorSQLite
|
||||
await plugin.setActiveDidFromHost(activeIdentity.activeDid);
|
||||
|
||||
// Plugin configures its own Core Data storage
|
||||
await plugin.configureDatabase({
|
||||
platform: 'ios',
|
||||
storageType: 'plugin-managed' // Plugin owns Core Data storage
|
||||
});
|
||||
|
||||
// Plugin operates with provided activeDid, no database sharing needed
|
||||
const results = await plugin.executeBackgroundContentFetch();
|
||||
```
|
||||
|
||||
#### **Enhancement Required: Extend Current Plugin Interface**
|
||||
|
||||
**Current Interface** (already implemented):
|
||||
```typescript
|
||||
interface DailyNotificationPlugin {
|
||||
configure(options: ConfigureOptions): Promise<void>;
|
||||
scheduleContentFetch(config: ContentFetchConfig): Promise<void>;
|
||||
scheduleUserNotification(config: UserNotificationConfig): Promise<void>;
|
||||
// ... existing methods (see definitions.ts)
|
||||
}
|
||||
```
|
||||
|
||||
**Enhancement Required** (add to existing interface):
|
||||
```typescript
|
||||
interface EnhancedDailyNotificationPlugin extends DailyNotificationPlugin {
|
||||
// Enhanced configuration with activeDid support
|
||||
configure(options: ConfigureOptions & {
|
||||
activeDidIntegration?: {
|
||||
platform: 'android' | 'ios' | 'web' | 'electron';
|
||||
storageType: 'plugin-managed' | 'host-managed';
|
||||
};
|
||||
}): Promise<void>;
|
||||
|
||||
// Host-provided activeDid Management (Option A Implementation)
|
||||
setActiveDidFromHost(activeDid: string): Promise<void>;
|
||||
|
||||
// Critical: ActiveDid Change Handling
|
||||
onActiveDidChange(callback: (newActiveDid: string) => Promise<void>): void;
|
||||
refreshAuthenticationForNewIdentity(activeDid: string): Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
### Background Scheduling with Hybrid activeDid Management
|
||||
|
||||
- **Integrate** with existing WorkManager/BGTaskScheduler
|
||||
- **Coordinate** API fetch timing with notification schedules
|
||||
- **Handle** app lifecycle events (background/foreground)
|
||||
- **Implement** host-provided activeDid access (Option A):
|
||||
- **Always**: Host provides activeDid via `setActiveDidFromHost()`
|
||||
- **No Database Sharing**: Plugin never accesses TimeSafari's active_identity table
|
||||
- **Critical**: Plugin **MUST** know when activeDid changes for:
|
||||
- **Event-Based Notification**: Host dispatches `activeDidChanged` events
|
||||
- **Cache Invalidation**: Clear cached content when user switches identity
|
||||
- **Token Refresh**: Generate new JWT tokens with updated active Did
|
||||
- **Background Task Coordination**: Restart tasks with new identity context
|
||||
- **Maintain** clear separation: Host owns identity management, plugin owns notifications
|
||||
|
||||
## Migration & Testing Strategy
|
||||
|
||||
### Gradual Migration
|
||||
|
||||
1. **Phase 1**: Implement basic HTTP + JWT authentication
|
||||
2. **Phase 2**: Add caching and state management
|
||||
3. **Phase 3**: Integrate with notification scheduling
|
||||
4. **Phase 4**: Add passkey authentication support
|
||||
|
||||
### Testing Approach with Host-Provided activeDid Management
|
||||
|
||||
- **Unit tests** for JWT generation and HTTP clients with activeDid
|
||||
- **Integration tests** for API endpoint interactions using TimeSafari active_identity patterns
|
||||
- **Host-provided activeDid testing**:
|
||||
- Test `setActiveDidFromHost()` with TimeSafari PlatformServiceMixin
|
||||
- Test host event dispatch and plugin event listening
|
||||
- **Critical**: Test `onActiveDidChange()` listener with identity switches
|
||||
- Test cache invalidation and token refresh during activeDid changes
|
||||
- Verify database isolation between host and plugin
|
||||
- **Background testing** on real devices (doze mode, app backgrounding)
|
||||
- **Authentication testing** with actual DID credentials from TimeSafari active_identity table
|
||||
- **Cross-platform testing** for Android/Electron (SQLite access) vs Web (host delegation) patterns
|
||||
|
||||
## API Endpoints to Support
|
||||
|
||||
### Offers to User Endpoint
|
||||
|
||||
```
|
||||
GET {apiServer}/api/v2/report/offers?recipientDid={userDid}&afterId={jwtId}&beforeId={jwtId}
|
||||
```
|
||||
|
||||
**Response Structure:**
|
||||
```json
|
||||
{
|
||||
"data": Array<OfferSummaryRecord>,
|
||||
"hitLimit": boolean
|
||||
}
|
||||
```
|
||||
|
||||
### Offers to User Projects Endpoint
|
||||
|
||||
```
|
||||
GET {apiServer}/api/v2/report/offersToPlansOwnedByMe?afterId={jwtId}&beforeId={jwtId}
|
||||
```
|
||||
|
||||
**Response Structure:**
|
||||
```json
|
||||
{
|
||||
"data": Array<OfferToPlanSummaryRecord>,
|
||||
"hitLimit": boolean
|
||||
}
|
||||
```
|
||||
|
||||
## Authentication Implementation Strategy
|
||||
|
||||
### Option 1: Simple DID Authentication (Basic)
|
||||
|
||||
- Generate traditional JWT using DID signing
|
||||
- Short-lived tokens (60 seconds)
|
||||
- Suitable for basic notification data fetching
|
||||
- Use `did-jwt` library for token generation and verification
|
||||
- Based on TimeSafari's existing JWT implementation patterns
|
||||
|
||||
### Option 2: Enhanced Passkey Authentication (Advanced)
|
||||
|
||||
- Leverage device biometrics/security keys
|
||||
- Longer-lived tokens with automatic refresh
|
||||
- Support for cached authentication state
|
||||
- Better user experience for frequent polling
|
||||
- Integrate with SimpleWebAuthn for cross-platform biometric support
|
||||
- Support JWANT tokens (JWT + WebAuthn) for enhanced security
|
||||
|
||||
## Platform-Specific Considerations
|
||||
|
||||
### Android Considerations
|
||||
|
||||
- Use OkHttp or native Android HTTP clients
|
||||
- Handle certificate pinning if required
|
||||
- Support Android Keystore for secure key storage
|
||||
- Handle biometric prompt integration for passkeys
|
||||
|
||||
### iOS Considerations
|
||||
|
||||
- Use URLSession for HTTP requests
|
||||
- Support iOS Keychain for authentication tokens
|
||||
- Handle Face ID/Touch ID integration for passkeys
|
||||
- Support certificate pinning if required
|
||||
- Use BGTaskScheduler for reliable background execution
|
||||
- Handle iOS-specific background refresh restrictions
|
||||
- Support Core Data for notification metadata persistence
|
||||
|
||||
## Data Flow Integration Points
|
||||
|
||||
### Token Generation
|
||||
|
||||
- Accept activeDid as input
|
||||
- Generate JWT authentication token using DID signing
|
||||
- Include activeDid as both issuer (`iss`) and subject (`sub`)
|
||||
- Return token for immediate use or caching
|
||||
|
||||
### Request Execution
|
||||
|
||||
- Construct full API URLs with query parameters
|
||||
- Apply authentication headers
|
||||
- Execute HTTP requests with proper error handling
|
||||
- Return structured response data
|
||||
|
||||
### Caching Strategy
|
||||
|
||||
- Support token caching with expiration management
|
||||
- Implement request deduplication for same endpoints
|
||||
- Support cache invalidation for authentication failures
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: Extend Core Infrastructure (Building on Existing)
|
||||
|
||||
- **Extend existing** Android `DailyNotificationFetcher.java` with JWT authentication
|
||||
- **Enhance existing** iOS implementation (when added) with authentication layer
|
||||
- **Add JWT generation** to existing `DailyNotificationETagManager.java`
|
||||
- **Enhance current** `ConfigureOptions` with activeDid integration
|
||||
- **Build on existing** error handling (circuit breaker already implemented)
|
||||
|
||||
### Phase 2: ActiveDid Integration & TimeSafari API Enhancement
|
||||
|
||||
- **Add** host-provided activeDid management to existing plugin interface
|
||||
- **Extend** existing `configure()` method with activeDid options
|
||||
- **Enhance** existing `ContentFetchConfig` with Endorser.ch API endpoints
|
||||
- **Add** `setActiveDidFromHost()` and `onActiveDidChange()` to existing interface
|
||||
- **Integrate** existing `callback-registry.ts` with activeDid-aware callbacks
|
||||
- **Enhance** existing platform storage:
|
||||
- **Android**: Extend existing SQLite with activeDid-aware JWT storage
|
||||
- **Web**: Enhance existing IndexedDB with activeDid support (no host delegation needed initially)
|
||||
|
||||
### Phase 3: Background Enhancement & TimeSafari Coordination
|
||||
|
||||
- **Enhance** existing WorkManager integration with activeDid-aware workers
|
||||
- **Coordinate** existing notification scheduling with TimeSafari PlatformServiceMixin
|
||||
- **Extend** existing app lifecycle handling with activeDid change detection
|
||||
- **Enhance** existing state synchronization with identity management
|
||||
- **Critical: Enhance retry policies** for activeDid changes:
|
||||
- **Android**: Modify `DailyNotificationFetchWorker.java` retry logic to detect activeDid changes during retry sequence
|
||||
- **Web**: Enhance `callback-registry.ts` to refresh authentication before retry attempts
|
||||
- **Unify**: Standardize retry delays across platforms (Android 1min→1hour vs Web 1sec→1min)
|
||||
- **Integrate activeDid change detection** into existing circuit breaker and error handling systems
|
||||
|
||||
### Phase 4: TimeSafari Integration & Advanced Features
|
||||
|
||||
- **Integrate** with TimeSafari's existing PlatformServiceMixin patterns
|
||||
- **Add** Endorser.ch API endpoint support to existing `ContentFetchConfig`
|
||||
- **Implement** DID-based authentication alongside existing callback system
|
||||
- **Enhance** existing testing with TimeSafari-specific scenarios
|
||||
|
||||
## Current Scheduled Event Update Policies
|
||||
|
||||
### ✅ **Existing Consistent Policies**
|
||||
- **Retry Logic**: Exponential backoff with platform-specific limits (Android: 5 retries, Web: 5 retries)
|
||||
- **Circuit Breaker**: Opens after 5 consecutive failures
|
||||
- **Fallback Content**: Uses cached/emergency content when all retries fail
|
||||
- **ETag Updates**: Conditional requests with 304 Not Modified handling
|
||||
- **Error Classification**: Network/Storage errors retryable, Permission/Config errors not retryable
|
||||
|
||||
### ⚠️ **Enhancement Required for TimeSafari Integration**
|
||||
- **ActiveDid Change Detection**: Handle identity switches during scheduled events
|
||||
- **Authentication Refresh**: Update JWT tokens for ongoing retry attempts
|
||||
- **Cache Invalidation**: Clear cached content when activeDid changes
|
||||
- **Platform Policy Unification**: Standardize retry delays and fallback mechanisms
|
||||
|
||||
### **TimeSafari-Aware Update Policy**
|
||||
```typescript
|
||||
interface TimeSafariUpdatePolicy extends ContentFetchConfig {
|
||||
activeDidAwareRetry?: {
|
||||
maxRetriesDuringActiveDidChange: number; // More retries during identity change
|
||||
authenticationRefreshDelay: number; // Time to refresh auth before retry
|
||||
cacheInvalidationOnChange: boolean; // Clear cache when activeDid changes
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] **Functional Requirements**: API data fetching works reliably in background with activeDid awareness
|
||||
- [ ] **Performance Requirements**: Requests complete within 30 seconds, including authentication refresh
|
||||
- [ ] **Security Requirements**: ActiveDid-based authentication with token refresh during retries
|
||||
- [ ] **Reliability Requirements**: Enhanced retry policies that handle activeDid changes gracefully
|
||||
- [ ] **Integration Requirements**: Seamless integration with existing plugin APIs + TimeSafari patterns
|
||||
- [ ] **Testing Requirements**: Comprehensive test coverage including activeDid change scenarios
|
||||
- [ ] **Authentication Requirements**: DID-based JWT with automatic refresh during scheduled events
|
||||
- [ ] **Optimization Requirements**: Intelligent retry policies based on error type and activeDid state
|
||||
- [ ] **Logging Requirements**: Structured logging with activeDid context and retry state tracking
|
||||
- [ ] **Cross-Platform Requirements**: Unified activeDid-aware retry and fallback mechanisms
|
||||
|
||||
## Risks & Mitigation
|
||||
|
||||
### Technical Risks
|
||||
|
||||
- **Background execution limits**: Mitigated by using platform-specific background task systems
|
||||
- **Authentication complexity**: Mitigated by implementing gradual migration path
|
||||
- **Cross-platform consistency**: Mitigated by shared interfaces and careful API design
|
||||
|
||||
### Timeline Risks
|
||||
|
||||
- **Platform-specific complexity**: Mitigated by prioritizing Android first, then iOS
|
||||
- **Testing complexity**: Mitigated by automated testing and CI/CD integration
|
||||
- **Integration challenges**: Mitigated by maintaining backward compatibility
|
||||
|
||||
---
|
||||
|
||||
**Status**: Enhancement plan for existing implementation (Option A) - Ready for implementation
|
||||
**Next Steps**: Begin Phase 1 - enhance existing Android HTTP infrastructure with JWT authentication
|
||||
**Dependencies**: Existing plugin infrastructure, Android Studio, Capacitor CLI, TimeSafari PlatformServiceMixin
|
||||
**Enhancement Approach**:
|
||||
- **Build on Existing**: Leverage current SQLite, IndexedDB, callback system, and dual scheduling
|
||||
- **Option A Integration**: Add activeDid management to existing configuration and HTTP layers
|
||||
- **TimeSafari Enhancement**: Extend current ContentFetchConfig with Endorser.ch API endpoints
|
||||
- **Authentication Layer**: Add JWT/DID authentication over existing HTTP infrastructure
|
||||
- **Event Integration**: Enhance existing callback system with activeDid change detection
|
||||
155
docs/_archive/2025-legacy-doc/BUILD_FIXES_SUMMARY.md
Normal file
155
docs/_archive/2025-legacy-doc/BUILD_FIXES_SUMMARY.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# iOS Build Fixes Summary
|
||||
|
||||
**Date:** 2025-11-13
|
||||
**Status:** ✅ **BUILD SUCCEEDED**
|
||||
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Fix all Swift compilation errors to enable iOS test app building and testing.
|
||||
|
||||
---
|
||||
|
||||
## Results
|
||||
|
||||
✅ **BUILD SUCCEEDED**
|
||||
✅ **All compilation errors resolved**
|
||||
✅ **Test app ready for iOS Simulator testing**
|
||||
|
||||
---
|
||||
|
||||
## Error Categories Fixed
|
||||
|
||||
### 1. Type System Mismatches
|
||||
- **Issue:** `Int64` timestamps incompatible with Swift `Date(timeIntervalSince1970:)` which expects `Double`
|
||||
- **Fix:** Explicit conversion: `Date(timeIntervalSince1970: Double(value) / 1000.0)`
|
||||
- **Files:** `DailyNotificationTTLEnforcer.swift`, `DailyNotificationRollingWindow.swift`
|
||||
|
||||
### 2. Logger API Inconsistency
|
||||
- **Issue:** Code called `logger.debug()`, `logger.error()` but API only provides `log(level:message:)`
|
||||
- **Fix:** Updated to `logger.log(.debug, "\(TAG): message")` format
|
||||
- **Files:** `DailyNotificationErrorHandler.swift`, `DailyNotificationPerformanceOptimizer.swift`, `DailyNotificationETagManager.swift`
|
||||
|
||||
### 3. Immutable Property Assignment
|
||||
- **Issue:** Attempted to mutate `let` properties on `NotificationContent`
|
||||
- **Fix:** Create new instances instead of mutating existing ones
|
||||
- **Files:** `DailyNotificationBackgroundTaskManager.swift`
|
||||
|
||||
### 4. Missing Imports
|
||||
- **Issue:** `CAPPluginCall` used without importing `Capacitor`
|
||||
- **Fix:** Added `import Capacitor`
|
||||
- **Files:** `DailyNotificationCallbacks.swift`
|
||||
|
||||
### 5. Access Control
|
||||
- **Issue:** `private` properties inaccessible to extension methods
|
||||
- **Fix:** Changed to `internal` (default) access level
|
||||
- **Files:** `DailyNotificationPlugin.swift`
|
||||
|
||||
### 6. Phase 2 Features in Phase 1
|
||||
- **Issue:** Code referenced CoreData `persistenceController` which doesn't exist in Phase 1
|
||||
- **Fix:** Stubbed Phase 2 methods with TODO comments
|
||||
- **Files:** `DailyNotificationBackgroundTasks.swift`, `DailyNotificationCallbacks.swift`
|
||||
|
||||
### 7. iOS API Availability
|
||||
- **Issue:** `interruptionLevel` requires iOS 15.0+ but deployment target is iOS 13.0
|
||||
- **Fix:** Added `#available(iOS 15.0, *)` checks
|
||||
- **Files:** `DailyNotificationPlugin.swift`
|
||||
|
||||
### 8. Switch Exhaustiveness
|
||||
- **Issue:** Missing `.scheduling` case in `ErrorCategory` switch
|
||||
- **Fix:** Added missing case
|
||||
- **Files:** `DailyNotificationErrorHandler.swift`
|
||||
|
||||
### 9. Variable Initialization
|
||||
- **Issue:** Variables captured by closures before initialization
|
||||
- **Fix:** Extract values from closures into local variables
|
||||
- **Files:** `DailyNotificationErrorHandler.swift`
|
||||
|
||||
### 10. Capacitor API Signature
|
||||
- **Issue:** `call.reject()` doesn't accept dictionary as error parameter
|
||||
- **Fix:** Use `call.reject(message, code)` format
|
||||
- **Files:** `DailyNotificationPlugin.swift`
|
||||
|
||||
### 11. Method Naming
|
||||
- **Issue:** Called `execSQL()` but method is `executeSQL()`
|
||||
- **Fix:** Updated to correct method name
|
||||
- **Files:** `DailyNotificationPerformanceOptimizer.swift`
|
||||
|
||||
### 12. Async/Await
|
||||
- **Issue:** Async function called in synchronous context
|
||||
- **Fix:** Made functions `async throws` where needed
|
||||
- **Files:** `DailyNotificationETagManager.swift`
|
||||
|
||||
### 13. Codable Conformance
|
||||
- **Issue:** `NotificationContent` needed `Codable` for JSON encoding
|
||||
- **Fix:** Added `Codable` protocol conformance
|
||||
- **Files:** `NotificationContent.swift`
|
||||
|
||||
---
|
||||
|
||||
## Build Script Improvements
|
||||
|
||||
### Simulator Auto-Detection
|
||||
- **Before:** Hardcoded "iPhone 15" (not available on all systems)
|
||||
- **After:** Auto-detects available iPhone simulators using device ID (UUID)
|
||||
- **Implementation:** Extracts device ID from `xcrun simctl list devices available`
|
||||
- **Fallback:** Device name → Generic destination
|
||||
|
||||
### Workspace Path
|
||||
- **Fix:** Corrected path to `test-apps/ios-test-app/ios/App/App.xcworkspace`
|
||||
|
||||
### CocoaPods Detection
|
||||
- **Fix:** Handles both system and rbenv CocoaPods installations
|
||||
|
||||
---
|
||||
|
||||
## Statistics
|
||||
|
||||
- **Total Error Categories:** 13
|
||||
- **Individual Errors Fixed:** ~50+
|
||||
- **Files Modified:** 12 Swift files + 2 configuration files
|
||||
- **Build Time:** Successful on first clean build after fixes
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
**Build Command:**
|
||||
```bash
|
||||
./scripts/build-ios-test-app.sh --simulator
|
||||
```
|
||||
|
||||
**Result:** ✅ BUILD SUCCEEDED
|
||||
|
||||
**Simulator Detection:** ✅ Working
|
||||
- Detects: iPhone 17 Pro (ID: 68D19D08-4701-422C-AF61-2E21ACA1DD4C)
|
||||
- Builds successfully for simulator
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Build successful
|
||||
2. ⏳ Run test app on iOS Simulator
|
||||
3. ⏳ Test Phase 1 plugin methods
|
||||
4. ⏳ Verify notification scheduling
|
||||
5. ⏳ Test background task execution
|
||||
|
||||
---
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
See `doc/directives/0003-iOS-Android-Parity-Directive.md` Decision Log section for detailed lessons learned from each error category.
|
||||
|
||||
**Key Takeaways:**
|
||||
- Always verify type compatibility when bridging platforms
|
||||
- Check API contracts before using helper classes
|
||||
- Swift's type system catches many errors at compile time
|
||||
- Phase separation (Phase 1 vs Phase 2) requires careful code organization
|
||||
- Auto-detection improves portability across environments
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-11-13
|
||||
|
||||
133
docs/_archive/2025-legacy-doc/BUILD_SCRIPT_IMPROVEMENTS.md
Normal file
133
docs/_archive/2025-legacy-doc/BUILD_SCRIPT_IMPROVEMENTS.md
Normal file
@@ -0,0 +1,133 @@
|
||||
# Build Script Improvements
|
||||
|
||||
**Date:** 2025-11-13
|
||||
**Status:** ✅ **FIXED**
|
||||
|
||||
---
|
||||
|
||||
## Issues Fixed
|
||||
|
||||
### 1. Missing Build Folder ✅
|
||||
|
||||
**Problem:**
|
||||
- Script was looking for `build` directory: `find build -name "*.app"`
|
||||
- Xcode actually builds to `DerivedData`: `~/Library/Developer/Xcode/DerivedData/App-*/Build/Products/`
|
||||
|
||||
**Solution:**
|
||||
- Updated script to search in `DerivedData`:
|
||||
```bash
|
||||
DERIVED_DATA_PATH="$HOME/Library/Developer/Xcode/DerivedData"
|
||||
APP_PATH=$(find "$DERIVED_DATA_PATH" -name "App.app" -path "*/Build/Products/Debug-iphonesimulator/*" -type d 2>/dev/null | head -1)
|
||||
```
|
||||
|
||||
**Result:** ✅ App path now correctly detected
|
||||
|
||||
---
|
||||
|
||||
### 2. Simulator Not Launching ✅
|
||||
|
||||
**Problem:**
|
||||
- Script only built the app, didn't boot or launch simulator
|
||||
- No automatic deployment after build
|
||||
|
||||
**Solution:**
|
||||
- Added automatic simulator boot detection and booting
|
||||
- Added Simulator.app opening if not already running
|
||||
- Added boot status polling (waits up to 60 seconds)
|
||||
- Added automatic app installation
|
||||
- Added automatic app launch (with fallback methods)
|
||||
|
||||
**Implementation:**
|
||||
```bash
|
||||
# Boot simulator if not already booted
|
||||
if [ "$SIMULATOR_STATE" != "Booted" ]; then
|
||||
xcrun simctl boot "$SIMULATOR_ID"
|
||||
open -a Simulator # Open Simulator app
|
||||
# Wait for boot with polling
|
||||
fi
|
||||
|
||||
# Install app
|
||||
xcrun simctl install "$SIMULATOR_ID" "$APP_PATH"
|
||||
|
||||
# Launch app
|
||||
xcrun simctl launch "$SIMULATOR_ID" com.timesafari.dailynotification.test
|
||||
```
|
||||
|
||||
**Result:** ✅ Simulator now boots and app launches automatically
|
||||
|
||||
---
|
||||
|
||||
## Improvements Made
|
||||
|
||||
### Boot Detection
|
||||
- ✅ Polls simulator state every second
|
||||
- ✅ Waits up to 60 seconds for full boot
|
||||
- ✅ Provides progress feedback every 5 seconds
|
||||
- ✅ Adds 3-second grace period after boot detection
|
||||
|
||||
### App Launch
|
||||
- ✅ Tries direct launch first
|
||||
- ✅ Falls back to console launch if needed
|
||||
- ✅ Provides manual instructions if automatic launch fails
|
||||
- ✅ Handles errors gracefully
|
||||
|
||||
### Error Handling
|
||||
- ✅ All commands have error handling
|
||||
- ✅ Warnings instead of failures for non-critical steps
|
||||
- ✅ Clear instructions for manual fallback
|
||||
|
||||
---
|
||||
|
||||
## Current Behavior
|
||||
|
||||
1. ✅ **Builds** the iOS test app successfully
|
||||
2. ✅ **Finds** the built app in DerivedData
|
||||
3. ✅ **Detects** available iPhone simulator
|
||||
4. ✅ **Boots** simulator if not already booted
|
||||
5. ✅ **Opens** Simulator.app if needed
|
||||
6. ✅ **Waits** for simulator to fully boot
|
||||
7. ✅ **Installs** app on simulator
|
||||
8. ✅ **Launches** app automatically
|
||||
|
||||
---
|
||||
|
||||
## Known Limitations
|
||||
|
||||
### Launch May Fail
|
||||
- Sometimes `xcrun simctl launch` fails even though app is installed
|
||||
- **Workaround:** App can be manually launched from Simulator home screen
|
||||
- **Alternative:** Use Xcode to run the app directly (Cmd+R)
|
||||
|
||||
### Boot Time
|
||||
- Simulator boot can take 30-60 seconds on first boot
|
||||
- Subsequent boots are faster
|
||||
- Script waits up to 60 seconds, but may need more on slower systems
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
**Command:**
|
||||
```bash
|
||||
./scripts/build-ios-test-app.sh --simulator
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
[INFO] Build successful!
|
||||
[INFO] App built at: /Users/.../DerivedData/.../App.app
|
||||
[STEP] Checking simulator status...
|
||||
[STEP] Booting simulator (iPhone 17 Pro)...
|
||||
[STEP] Waiting for simulator to boot...
|
||||
[INFO] Simulator booted successfully (took Xs)
|
||||
[STEP] Installing app on simulator...
|
||||
[INFO] App installed successfully
|
||||
[STEP] Launching app...
|
||||
[INFO] ✅ App launched successfully!
|
||||
[INFO] ✅ Build and deployment complete!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-11-13
|
||||
|
||||
214
docs/_archive/2025-legacy-doc/IMPLEMENTATION_CHECKLIST_LEGACY.md
Normal file
214
docs/_archive/2025-legacy-doc/IMPLEMENTATION_CHECKLIST_LEGACY.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# iOS Phase 1 Implementation Checklist
|
||||
|
||||
**Status:** ✅ **COMPLETE**
|
||||
**Date:** 2025-01-XX
|
||||
**Branch:** `ios-2`
|
||||
|
||||
---
|
||||
|
||||
## Implementation Verification
|
||||
|
||||
### ✅ Core Infrastructure
|
||||
|
||||
- [x] **DailyNotificationStorage.swift** - Storage abstraction layer created
|
||||
- [x] **DailyNotificationScheduler.swift** - Scheduler implementation created
|
||||
- [x] **DailyNotificationStateActor.swift** - Thread-safe state access created
|
||||
- [x] **DailyNotificationErrorCodes.swift** - Error code constants created
|
||||
- [x] **NotificationContent.swift** - Updated to use Int64 (milliseconds)
|
||||
- [x] **DailyNotificationDatabase.swift** - Database stub methods added
|
||||
|
||||
### ✅ Phase 1 Methods
|
||||
|
||||
- [x] `configure()` - Enhanced with full Android parity
|
||||
- [x] `scheduleDailyNotification()` - Main scheduling with prefetch
|
||||
- [x] `getLastNotification()` - Last notification retrieval
|
||||
- [x] `cancelAllNotifications()` - Cancel all notifications
|
||||
- [x] `getNotificationStatus()` - Status retrieval with next time
|
||||
- [x] `updateSettings()` - Settings update
|
||||
|
||||
### ✅ Background Tasks
|
||||
|
||||
- [x] BGTaskScheduler registration
|
||||
- [x] Background fetch handler (`handleBackgroundFetch`)
|
||||
- [x] Background notify handler (`handleBackgroundNotify`)
|
||||
- [x] BGTask miss detection (`checkForMissedBGTask`)
|
||||
- [x] BGTask rescheduling (15-minute window)
|
||||
- [x] Successful run tracking
|
||||
|
||||
### ✅ Thread Safety
|
||||
|
||||
- [x] State actor created and initialized
|
||||
- [x] All storage operations use state actor
|
||||
- [x] Background tasks use state actor
|
||||
- [x] Fallback for iOS < 13
|
||||
- [x] No direct concurrent access to shared state
|
||||
|
||||
### ✅ Error Handling
|
||||
|
||||
- [x] Error code constants defined
|
||||
- [x] Structured error responses matching Android
|
||||
- [x] Error codes used in all Phase 1 methods
|
||||
- [x] Helper methods for error creation
|
||||
- [x] Error logging with codes
|
||||
|
||||
### ✅ Permission Management
|
||||
|
||||
- [x] Permission auto-healing implemented
|
||||
- [x] Permission status checking
|
||||
- [x] Permission request handling
|
||||
- [x] Error codes for denied permissions
|
||||
- [x] Never silently succeed when denied
|
||||
|
||||
### ✅ Integration Points
|
||||
|
||||
- [x] Plugin initialization (`load()`)
|
||||
- [x] Background task setup (`setupBackgroundTasks()`)
|
||||
- [x] Storage initialization
|
||||
- [x] Scheduler initialization
|
||||
- [x] State actor initialization
|
||||
- [x] Health status method (`getHealthStatus()`)
|
||||
|
||||
### ✅ Utility Methods
|
||||
|
||||
- [x] `calculateNextScheduledTime()` - Time calculation
|
||||
- [x] `calculateNextOccurrence()` - Scheduler utility
|
||||
- [x] `getNextNotificationTime()` - Next time retrieval
|
||||
- [x] `formatTime()` - Time formatting for logs
|
||||
|
||||
### ✅ Code Quality
|
||||
|
||||
- [x] No linter errors
|
||||
- [x] All code compiles successfully
|
||||
- [x] File-level documentation
|
||||
- [x] Method-level documentation
|
||||
- [x] Type safety throughout
|
||||
- [x] Error handling comprehensive
|
||||
|
||||
---
|
||||
|
||||
## Testing Readiness
|
||||
|
||||
### Test Documentation
|
||||
|
||||
- [x] **IOS_PHASE1_TESTING_GUIDE.md** - Comprehensive testing guide created
|
||||
- [x] **IOS_PHASE1_QUICK_REFERENCE.md** - Quick reference created
|
||||
- [x] Testing checklist included
|
||||
- [x] Debugging commands documented
|
||||
- [x] Common issues documented
|
||||
|
||||
### Test App Status
|
||||
|
||||
- [ ] iOS test app created (`test-apps/ios-test-app/`)
|
||||
- [ ] Build script created (`scripts/build-ios-test-app.sh`)
|
||||
- [ ] Test app UI matches Android test app
|
||||
- [ ] Permissions configured in Info.plist
|
||||
- [ ] BGTask identifiers configured
|
||||
|
||||
---
|
||||
|
||||
## Known Limitations (By Design)
|
||||
|
||||
### Phase 1 Scope
|
||||
|
||||
- ✅ Single daily schedule only (one prefetch + one notification)
|
||||
- ✅ Dummy content fetcher (static content, no network)
|
||||
- ✅ No TTL enforcement (deferred to Phase 2)
|
||||
- ✅ Simple reboot recovery (basic reschedule on launch)
|
||||
- ✅ No rolling window (deferred to Phase 2)
|
||||
|
||||
### Platform Constraints
|
||||
|
||||
- ✅ iOS timing tolerance: ±180 seconds (documented)
|
||||
- ✅ iOS 64 notification limit (documented)
|
||||
- ✅ BGTask execution window: ~30 seconds (handled)
|
||||
- ✅ Background App Refresh required (documented)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate
|
||||
|
||||
1. **Create iOS Test App** (`test-apps/ios-test-app/`)
|
||||
- Copy structure from `android-test-app`
|
||||
- Configure Info.plist with BGTask identifiers
|
||||
- Set up Capacitor plugin registration
|
||||
- Create HTML/JS UI matching Android test app
|
||||
|
||||
2. **Create Build Script** (`scripts/build-ios-test-app.sh`)
|
||||
- Check environment (xcodebuild, pod)
|
||||
- Install dependencies (pod install)
|
||||
- Build for simulator or device
|
||||
- Clear error messages
|
||||
|
||||
3. **Manual Testing**
|
||||
- Run test cases from `IOS_PHASE1_TESTING_GUIDE.md`
|
||||
- Verify all Phase 1 methods work
|
||||
- Test BGTask execution
|
||||
- Test notification delivery
|
||||
|
||||
### Phase 2 Preparation
|
||||
|
||||
1. Review Phase 2 requirements
|
||||
2. Plan rolling window implementation
|
||||
3. Plan TTL enforcement integration
|
||||
4. Plan reboot recovery enhancement
|
||||
|
||||
---
|
||||
|
||||
## Files Summary
|
||||
|
||||
### Created Files (4)
|
||||
|
||||
1. `ios/Plugin/DailyNotificationStorage.swift` (334 lines)
|
||||
2. `ios/Plugin/DailyNotificationScheduler.swift` (322 lines)
|
||||
3. `ios/Plugin/DailyNotificationStateActor.swift` (211 lines)
|
||||
4. `ios/Plugin/DailyNotificationErrorCodes.swift` (113 lines)
|
||||
|
||||
### Enhanced Files (3)
|
||||
|
||||
1. `ios/Plugin/DailyNotificationPlugin.swift` (1157 lines)
|
||||
2. `ios/Plugin/NotificationContent.swift` (238 lines)
|
||||
3. `ios/Plugin/DailyNotificationDatabase.swift` (241 lines)
|
||||
|
||||
### Documentation Files (3)
|
||||
|
||||
1. `doc/PHASE1_COMPLETION_SUMMARY.md`
|
||||
2. `doc/IOS_PHASE1_TESTING_GUIDE.md`
|
||||
3. `doc/IOS_PHASE1_QUICK_REFERENCE.md`
|
||||
|
||||
---
|
||||
|
||||
## Verification Commands
|
||||
|
||||
### Compilation Check
|
||||
```bash
|
||||
cd ios
|
||||
xcodebuild -workspace DailyNotificationPlugin.xcworkspace \
|
||||
-scheme DailyNotificationPlugin \
|
||||
-sdk iphonesimulator \
|
||||
clean build
|
||||
```
|
||||
|
||||
### Linter Check
|
||||
```bash
|
||||
# Run Swift linter if available
|
||||
swiftlint lint ios/Plugin/
|
||||
```
|
||||
|
||||
### Code Review Checklist
|
||||
|
||||
- [ ] All Phase 1 methods implemented
|
||||
- [ ] Error codes match Android format
|
||||
- [ ] Thread safety via state actor
|
||||
- [ ] BGTask miss detection working
|
||||
- [ ] Permission auto-healing working
|
||||
- [ ] Documentation complete
|
||||
- [ ] No compilation errors
|
||||
- [ ] No linter errors
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ **PHASE 1 IMPLEMENTATION COMPLETE**
|
||||
**Ready for:** Testing and Phase 2 preparation
|
||||
|
||||
257
docs/_archive/2025-legacy-doc/IOS_ANDROID_ERROR_CODE_MAPPING.md
Normal file
257
docs/_archive/2025-legacy-doc/IOS_ANDROID_ERROR_CODE_MAPPING.md
Normal file
@@ -0,0 +1,257 @@
|
||||
# iOS-Android Error Code Mapping
|
||||
|
||||
**Status:** ✅ **VERIFIED**
|
||||
**Date:** 2025-01-XX
|
||||
**Objective:** Verify error code parity between iOS and Android implementations
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document provides a comprehensive mapping between Android error messages and iOS error codes for Phase 1 methods. All Phase 1 error scenarios have been verified for semantic equivalence.
|
||||
|
||||
**Conclusion:** ✅ **Error codes are semantically equivalent and match directive requirements.**
|
||||
|
||||
---
|
||||
|
||||
## Error Response Format
|
||||
|
||||
Both platforms use structured error responses (as required by directive):
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "error_code",
|
||||
"message": "Human-readable error message"
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Android uses `call.reject()` with string messages, but the directive requires structured error codes. iOS implementation provides structured error codes that semantically match Android's error messages.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 Method Error Mappings
|
||||
|
||||
### 1. `configure()`
|
||||
|
||||
| Android Error Message | iOS Error Code | iOS Message | Status |
|
||||
|----------------------|----------------|-------------|--------|
|
||||
| `"Configuration failed: " + e.getMessage()` | `CONFIGURATION_FAILED` | `"Configuration failed: [details]"` | ✅ Match |
|
||||
| `"Configuration options required"` | `MISSING_REQUIRED_PARAMETER` | `"Missing required parameter: options"` | ✅ Match |
|
||||
|
||||
**Verification:**
|
||||
- ✅ Both handle missing options
|
||||
- ✅ Both handle configuration failures
|
||||
- ✅ Error semantics match
|
||||
|
||||
---
|
||||
|
||||
### 2. `scheduleDailyNotification()`
|
||||
|
||||
| Android Error Message | iOS Error Code | iOS Message | Status |
|
||||
|----------------------|----------------|-------------|--------|
|
||||
| `"Time parameter is required"` | `MISSING_REQUIRED_PARAMETER` | `"Missing required parameter: time"` | ✅ Match |
|
||||
| `"Invalid time format. Use HH:mm"` | `INVALID_TIME_FORMAT` | `"Invalid time format. Use HH:mm"` | ✅ Match |
|
||||
| `"Invalid time values"` | `INVALID_TIME_VALUES` | `"Invalid time values"` | ✅ Match |
|
||||
| `"Failed to schedule notification"` | `SCHEDULING_FAILED` | `"Failed to schedule notification"` | ✅ Match |
|
||||
| `"Internal error: " + e.getMessage()` | `INTERNAL_ERROR` | `"Internal error: [details]"` | ✅ Match |
|
||||
| N/A (iOS-specific) | `NOTIFICATIONS_DENIED` | `"Notification permissions denied"` | ✅ iOS Enhancement |
|
||||
|
||||
**Verification:**
|
||||
- ✅ All Android error scenarios covered
|
||||
- ✅ iOS adds permission check (required by directive)
|
||||
- ✅ Error messages match exactly where applicable
|
||||
|
||||
---
|
||||
|
||||
### 3. `getLastNotification()`
|
||||
|
||||
| Android Error Message | iOS Error Code | iOS Message | Status |
|
||||
|----------------------|----------------|-------------|--------|
|
||||
| `"Internal error: " + e.getMessage()` | `INTERNAL_ERROR` | `"Internal error: [details]"` | ✅ Match |
|
||||
| N/A (iOS-specific) | `PLUGIN_NOT_INITIALIZED` | `"Plugin not initialized"` | ✅ iOS Enhancement |
|
||||
|
||||
**Verification:**
|
||||
- ✅ Error handling matches Android
|
||||
- ✅ iOS adds initialization check
|
||||
|
||||
---
|
||||
|
||||
### 4. `cancelAllNotifications()`
|
||||
|
||||
| Android Error Message | iOS Error Code | iOS Message | Status |
|
||||
|----------------------|----------------|-------------|--------|
|
||||
| `"Internal error: " + e.getMessage()` | `INTERNAL_ERROR` | `"Internal error: [details]"` | ✅ Match |
|
||||
| N/A (iOS-specific) | `PLUGIN_NOT_INITIALIZED` | `"Plugin not initialized"` | ✅ iOS Enhancement |
|
||||
|
||||
**Verification:**
|
||||
- ✅ Error handling matches Android
|
||||
|
||||
---
|
||||
|
||||
### 5. `getNotificationStatus()`
|
||||
|
||||
| Android Error Message | iOS Error Code | iOS Message | Status |
|
||||
|----------------------|----------------|-------------|--------|
|
||||
| `"Internal error: " + e.getMessage()` | `INTERNAL_ERROR` | `"Internal error: [details]"` | ✅ Match |
|
||||
| N/A (iOS-specific) | `PLUGIN_NOT_INITIALIZED` | `"Plugin not initialized"` | ✅ iOS Enhancement |
|
||||
|
||||
**Verification:**
|
||||
- ✅ Error handling matches Android
|
||||
|
||||
---
|
||||
|
||||
### 6. `updateSettings()`
|
||||
|
||||
| Android Error Message | iOS Error Code | iOS Message | Status |
|
||||
|----------------------|----------------|-------------|--------|
|
||||
| `"Internal error: " + e.getMessage()` | `INTERNAL_ERROR` | `"Internal error: [details]"` | ✅ Match |
|
||||
| N/A (iOS-specific) | `MISSING_REQUIRED_PARAMETER` | `"Missing required parameter: settings"` | ✅ iOS Enhancement |
|
||||
| N/A (iOS-specific) | `PLUGIN_NOT_INITIALIZED` | `"Plugin not initialized"` | ✅ iOS Enhancement |
|
||||
|
||||
**Verification:**
|
||||
- ✅ Error handling matches Android
|
||||
- ✅ iOS adds parameter validation
|
||||
|
||||
---
|
||||
|
||||
## Error Code Constants
|
||||
|
||||
### iOS Error Codes (DailyNotificationErrorCodes.swift)
|
||||
|
||||
```swift
|
||||
// Permission Errors
|
||||
NOTIFICATIONS_DENIED = "notifications_denied"
|
||||
BACKGROUND_REFRESH_DISABLED = "background_refresh_disabled"
|
||||
PERMISSION_DENIED = "permission_denied"
|
||||
|
||||
// Configuration Errors
|
||||
INVALID_TIME_FORMAT = "invalid_time_format"
|
||||
INVALID_TIME_VALUES = "invalid_time_values"
|
||||
CONFIGURATION_FAILED = "configuration_failed"
|
||||
MISSING_REQUIRED_PARAMETER = "missing_required_parameter"
|
||||
|
||||
// Scheduling Errors
|
||||
SCHEDULING_FAILED = "scheduling_failed"
|
||||
TASK_SCHEDULING_FAILED = "task_scheduling_failed"
|
||||
NOTIFICATION_SCHEDULING_FAILED = "notification_scheduling_failed"
|
||||
|
||||
// Storage Errors
|
||||
STORAGE_ERROR = "storage_error"
|
||||
DATABASE_ERROR = "database_error"
|
||||
|
||||
// System Errors
|
||||
PLUGIN_NOT_INITIALIZED = "plugin_not_initialized"
|
||||
INTERNAL_ERROR = "internal_error"
|
||||
SYSTEM_ERROR = "system_error"
|
||||
```
|
||||
|
||||
### Android Error Patterns (from DailyNotificationPlugin.java)
|
||||
|
||||
**Phase 1 Error Messages:**
|
||||
- `"Time parameter is required"` → Maps to `missing_required_parameter`
|
||||
- `"Invalid time format. Use HH:mm"` → Maps to `invalid_time_format`
|
||||
- `"Invalid time values"` → Maps to `invalid_time_values`
|
||||
- `"Failed to schedule notification"` → Maps to `scheduling_failed`
|
||||
- `"Configuration failed: [details]"` → Maps to `configuration_failed`
|
||||
- `"Internal error: [details]"` → Maps to `internal_error`
|
||||
|
||||
---
|
||||
|
||||
## Semantic Equivalence Verification
|
||||
|
||||
### Mapping Rules
|
||||
|
||||
1. **Missing Parameters:**
|
||||
- Android: `"Time parameter is required"`
|
||||
- iOS: `MISSING_REQUIRED_PARAMETER` with message `"Missing required parameter: time"`
|
||||
- ✅ **Semantically equivalent**
|
||||
|
||||
2. **Invalid Format:**
|
||||
- Android: `"Invalid time format. Use HH:mm"`
|
||||
- iOS: `INVALID_TIME_FORMAT` with message `"Invalid time format. Use HH:mm"`
|
||||
- ✅ **Exact match**
|
||||
|
||||
3. **Invalid Values:**
|
||||
- Android: `"Invalid time values"`
|
||||
- iOS: `INVALID_TIME_VALUES` with message `"Invalid time values"`
|
||||
- ✅ **Exact match**
|
||||
|
||||
4. **Scheduling Failure:**
|
||||
- Android: `"Failed to schedule notification"`
|
||||
- iOS: `SCHEDULING_FAILED` with message `"Failed to schedule notification"`
|
||||
- ✅ **Exact match**
|
||||
|
||||
5. **Configuration Failure:**
|
||||
- Android: `"Configuration failed: [details]"`
|
||||
- iOS: `CONFIGURATION_FAILED` with message `"Configuration failed: [details]"`
|
||||
- ✅ **Exact match**
|
||||
|
||||
6. **Internal Errors:**
|
||||
- Android: `"Internal error: [details]"`
|
||||
- iOS: `INTERNAL_ERROR` with message `"Internal error: [details]"`
|
||||
- ✅ **Exact match**
|
||||
|
||||
---
|
||||
|
||||
## iOS-Specific Enhancements
|
||||
|
||||
### Additional Error Codes (Not in Android, but Required by Directive)
|
||||
|
||||
1. **`NOTIFICATIONS_DENIED`**
|
||||
- **Reason:** Directive requires permission auto-healing
|
||||
- **Usage:** When notification permissions are denied
|
||||
- **Status:** ✅ Required by directive (line 229)
|
||||
|
||||
2. **`PLUGIN_NOT_INITIALIZED`**
|
||||
- **Reason:** iOS initialization checks
|
||||
- **Usage:** When plugin methods called before initialization
|
||||
- **Status:** ✅ Defensive programming, improves error handling
|
||||
|
||||
3. **`BACKGROUND_REFRESH_DISABLED`**
|
||||
- **Reason:** iOS-specific Background App Refresh requirement
|
||||
- **Usage:** When Background App Refresh is disabled
|
||||
- **Status:** ✅ Platform-specific requirement
|
||||
|
||||
---
|
||||
|
||||
## Directive Compliance
|
||||
|
||||
### Directive Requirements (Line 549)
|
||||
|
||||
> "**Note:** This TODO is **blocking for Phase 1**: iOS error handling must not be considered complete until the table is extracted and mirrored."
|
||||
|
||||
**Status:** ✅ **COMPLETE**
|
||||
|
||||
### Verification Checklist
|
||||
|
||||
- [x] Error codes extracted from Android implementation
|
||||
- [x] Error codes mapped to iOS equivalents
|
||||
- [x] Semantic equivalence verified
|
||||
- [x] Error response format matches directive (`{ "error": "code", "message": "..." }`)
|
||||
- [x] All Phase 1 methods covered
|
||||
- [x] iOS-specific enhancements documented
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
✅ **Error code parity verified and complete.**
|
||||
|
||||
All Phase 1 error scenarios have been mapped and verified for semantic equivalence. iOS error codes match Android error messages semantically, and iOS provides structured error responses as required by the directive.
|
||||
|
||||
**Additional iOS error codes** (e.g., `NOTIFICATIONS_DENIED`, `PLUGIN_NOT_INITIALIZED`) are enhancements that improve error handling and are required by the directive's permission auto-healing requirements.
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **Directive:** `doc/directives/0003-iOS-Android-Parity-Directive.md` (Line 549)
|
||||
- **Android Source:** `src/android/DailyNotificationPlugin.java`
|
||||
- **iOS Error Codes:** `ios/Plugin/DailyNotificationErrorCodes.swift`
|
||||
- **iOS Implementation:** `ios/Plugin/DailyNotificationPlugin.swift`
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ **VERIFIED AND COMPLETE**
|
||||
**Last Updated:** 2025-01-XX
|
||||
|
||||
318
docs/_archive/2025-legacy-doc/IOS_PHASE1_FINAL_SUMMARY.md
Normal file
318
docs/_archive/2025-legacy-doc/IOS_PHASE1_FINAL_SUMMARY.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# iOS Phase 1 Implementation - Final Summary
|
||||
|
||||
**Status:** ✅ **COMPLETE AND READY FOR TESTING**
|
||||
**Date:** 2025-01-XX
|
||||
**Branch:** `ios-2`
|
||||
**Objective:** Core Infrastructure Parity - Single daily schedule (one prefetch + one notification)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Executive Summary
|
||||
|
||||
Phase 1 of the iOS-Android Parity Directive has been **successfully completed**. All core infrastructure components have been implemented, tested for compilation, and documented. The implementation provides a solid foundation for Phase 2 advanced features.
|
||||
|
||||
### Key Achievements
|
||||
|
||||
- ✅ **6 Core Methods** - All Phase 1 methods implemented
|
||||
- ✅ **4 New Components** - Storage, Scheduler, State Actor, Error Codes
|
||||
- ✅ **Thread Safety** - Actor-based concurrency throughout
|
||||
- ✅ **Error Handling** - Structured error codes matching Android
|
||||
- ✅ **BGTask Management** - Miss detection and auto-rescheduling
|
||||
- ✅ **Permission Auto-Healing** - Automatic permission requests
|
||||
- ✅ **Documentation** - Comprehensive testing guides and references
|
||||
|
||||
---
|
||||
|
||||
## 📁 Files Created/Enhanced
|
||||
|
||||
### New Files (4)
|
||||
|
||||
1. **`ios/Plugin/DailyNotificationStorage.swift`** (334 lines)
|
||||
- Storage abstraction layer
|
||||
- UserDefaults + CoreData integration
|
||||
- Content caching with automatic cleanup
|
||||
- BGTask tracking for miss detection
|
||||
|
||||
2. **`ios/Plugin/DailyNotificationScheduler.swift`** (322 lines)
|
||||
- UNUserNotificationCenter integration
|
||||
- Permission auto-healing
|
||||
- Calendar-based triggers with ±180s tolerance
|
||||
- Utility methods: `calculateNextOccurrence()`, `getNextNotificationTime()`
|
||||
|
||||
3. **`ios/Plugin/DailyNotificationStateActor.swift`** (211 lines)
|
||||
- Thread-safe state access using Swift actors
|
||||
- Serializes all database/storage operations
|
||||
- Ready for Phase 2 rolling window and TTL enforcement
|
||||
|
||||
4. **`ios/Plugin/DailyNotificationErrorCodes.swift`** (113 lines)
|
||||
- Error code constants matching Android
|
||||
- Helper methods for error responses
|
||||
- Covers all error categories
|
||||
|
||||
### Enhanced Files (3)
|
||||
|
||||
1. **`ios/Plugin/DailyNotificationPlugin.swift`** (1157 lines)
|
||||
- Enhanced `configure()` method
|
||||
- Implemented all Phase 1 core methods
|
||||
- BGTask handlers with miss detection
|
||||
- Integrated state actor and error codes
|
||||
- Added `getHealthStatus()` for dual scheduling status
|
||||
- Improved `getNotificationStatus()` with next notification time calculation
|
||||
|
||||
2. **`ios/Plugin/NotificationContent.swift`** (238 lines)
|
||||
- Updated to use Int64 (milliseconds) matching Android
|
||||
- Added Codable support for JSON encoding
|
||||
- Backward compatibility for TimeInterval
|
||||
|
||||
3. **`ios/Plugin/DailyNotificationDatabase.swift`** (241 lines)
|
||||
- Added stub methods for notification persistence
|
||||
- Ready for Phase 2 full database integration
|
||||
|
||||
### Documentation Files (5)
|
||||
|
||||
1. **`doc/PHASE1_COMPLETION_SUMMARY.md`** - Detailed implementation summary
|
||||
2. **`doc/IOS_PHASE1_TESTING_GUIDE.md`** - Comprehensive testing guide (581 lines)
|
||||
3. **`doc/IOS_PHASE1_QUICK_REFERENCE.md`** - Quick reference guide
|
||||
4. **`doc/IOS_PHASE1_IMPLEMENTATION_CHECKLIST.md`** - Verification checklist
|
||||
5. **`doc/IOS_PHASE1_READY_FOR_TESTING.md`** - Testing readiness overview
|
||||
|
||||
---
|
||||
|
||||
## ✅ Phase 1 Methods Implemented
|
||||
|
||||
### Core Methods (6/6 Complete)
|
||||
|
||||
1. ✅ **`configure(options: ConfigureOptions)`**
|
||||
- Full Android parity
|
||||
- Supports dbPath, storage mode, TTL, prefetch lead, max notifications, retention
|
||||
- Stores configuration in UserDefaults/CoreData
|
||||
|
||||
2. ✅ **`scheduleDailyNotification(options: NotificationOptions)`**
|
||||
- Main scheduling method
|
||||
- Single daily schedule (one prefetch 5 min before + one notification)
|
||||
- Permission auto-healing
|
||||
- Error code integration
|
||||
|
||||
3. ✅ **`getLastNotification()`**
|
||||
- Returns last delivered notification
|
||||
- Thread-safe via state actor
|
||||
- Returns empty object if none exists
|
||||
|
||||
4. ✅ **`cancelAllNotifications()`**
|
||||
- Cancels all scheduled notifications
|
||||
- Clears storage
|
||||
- Thread-safe via state actor
|
||||
|
||||
5. ✅ **`getNotificationStatus()`**
|
||||
- Returns current notification status
|
||||
- Includes permission status, pending count, last notification time
|
||||
- Calculates next notification time
|
||||
- Thread-safe via state actor
|
||||
|
||||
6. ✅ **`updateSettings(settings: NotificationSettings)`**
|
||||
- Updates notification settings
|
||||
- Thread-safe via state actor
|
||||
- Error code integration
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Technical Implementation
|
||||
|
||||
### Thread Safety
|
||||
|
||||
All state access goes through `DailyNotificationStateActor`:
|
||||
- Uses Swift `actor` for serialized access
|
||||
- Fallback to direct storage for iOS < 13
|
||||
- Background tasks use async/await with actor
|
||||
- No direct concurrent access to shared state
|
||||
|
||||
### Error Handling
|
||||
|
||||
Structured error responses matching Android:
|
||||
```swift
|
||||
{
|
||||
"error": "error_code",
|
||||
"message": "Human-readable error message"
|
||||
}
|
||||
```
|
||||
|
||||
Error codes implemented:
|
||||
- `PLUGIN_NOT_INITIALIZED`
|
||||
- `MISSING_REQUIRED_PARAMETER`
|
||||
- `INVALID_TIME_FORMAT`
|
||||
- `SCHEDULING_FAILED`
|
||||
- `NOTIFICATIONS_DENIED`
|
||||
- `BACKGROUND_REFRESH_DISABLED`
|
||||
- `STORAGE_ERROR`
|
||||
- `INTERNAL_ERROR`
|
||||
|
||||
### BGTask Miss Detection
|
||||
|
||||
- Checks on app launch for missed BGTask
|
||||
- 15-minute window for detection
|
||||
- Auto-reschedules if missed
|
||||
- Tracks successful runs to avoid false positives
|
||||
|
||||
### Permission Auto-Healing
|
||||
|
||||
- Checks permission status before scheduling
|
||||
- Requests permissions if not determined
|
||||
- Returns appropriate error codes if denied
|
||||
- Logs error codes for debugging
|
||||
|
||||
---
|
||||
|
||||
## 📊 Code Quality Metrics
|
||||
|
||||
- **Total Lines of Code:** ~2,600+ lines
|
||||
- **Files Created:** 4 new files
|
||||
- **Files Enhanced:** 3 existing files
|
||||
- **Methods Implemented:** 6 Phase 1 methods
|
||||
- **Error Codes:** 8+ error codes
|
||||
- **Test Cases:** 10 test cases documented
|
||||
- **Linter Errors:** 0
|
||||
- **Compilation Errors:** 0
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Readiness
|
||||
|
||||
### Test Documentation
|
||||
|
||||
- ✅ **IOS_PHASE1_TESTING_GUIDE.md** - Comprehensive testing guide created
|
||||
- ✅ **IOS_PHASE1_QUICK_REFERENCE.md** - Quick reference created
|
||||
- ✅ Testing checklist included
|
||||
- ✅ Debugging commands documented
|
||||
- ✅ Common issues documented
|
||||
|
||||
### Test App Status
|
||||
|
||||
- ⏳ iOS test app needs to be created (`test-apps/ios-test-app/`)
|
||||
- ✅ Build script created (`scripts/build-ios-test-app.sh`)
|
||||
- ✅ Info.plist configured correctly
|
||||
- ✅ BGTask identifiers configured
|
||||
- ✅ Background modes configured
|
||||
|
||||
---
|
||||
|
||||
## 📋 Known Limitations (By Design)
|
||||
|
||||
### Phase 1 Scope
|
||||
|
||||
1. **Single Daily Schedule:** Only one prefetch + one notification per day
|
||||
- Rolling window deferred to Phase 2
|
||||
|
||||
2. **Dummy Content Fetcher:** Returns static content
|
||||
- JWT/ETag integration deferred to Phase 3
|
||||
|
||||
3. **No TTL Enforcement:** TTL validation skipped
|
||||
- TTL enforcement deferred to Phase 2
|
||||
|
||||
4. **Simple Reboot Recovery:** Basic reschedule on launch
|
||||
- Full reboot detection deferred to Phase 2
|
||||
|
||||
### Platform Constraints
|
||||
|
||||
- ✅ iOS timing tolerance: ±180 seconds (documented)
|
||||
- ✅ iOS 64 notification limit (documented)
|
||||
- ✅ BGTask execution window: ~30 seconds (handled)
|
||||
- ✅ Background App Refresh required (documented)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
### Immediate (Testing Phase)
|
||||
|
||||
1. **Create iOS Test App** (`test-apps/ios-test-app/`)
|
||||
- Copy structure from `android-test-app`
|
||||
- Configure Info.plist with BGTask identifiers
|
||||
- Set up Capacitor plugin registration
|
||||
- Create HTML/JS UI matching Android test app
|
||||
|
||||
2. **Create Build Script** (`scripts/build-ios-test-app.sh`)
|
||||
- Check environment (xcodebuild, pod)
|
||||
- Install dependencies (pod install)
|
||||
- Build for simulator or device
|
||||
- Clear error messages
|
||||
|
||||
3. **Run Test Cases**
|
||||
- Follow `IOS_PHASE1_TESTING_GUIDE.md`
|
||||
- Verify all Phase 1 methods work
|
||||
- Test BGTask execution
|
||||
- Test notification delivery
|
||||
|
||||
### Phase 2 Preparation
|
||||
|
||||
1. Review Phase 2 requirements in directive
|
||||
2. Plan rolling window implementation
|
||||
3. Plan TTL enforcement integration
|
||||
4. Plan reboot recovery enhancement
|
||||
5. Plan power management features
|
||||
|
||||
---
|
||||
|
||||
## 📖 Documentation Index
|
||||
|
||||
### Primary Guides
|
||||
|
||||
1. **Testing:** `doc/IOS_PHASE1_TESTING_GUIDE.md`
|
||||
2. **Quick Reference:** `doc/IOS_PHASE1_QUICK_REFERENCE.md`
|
||||
3. **Implementation Summary:** `doc/PHASE1_COMPLETION_SUMMARY.md`
|
||||
|
||||
### Verification
|
||||
|
||||
1. **Checklist:** `doc/IOS_PHASE1_IMPLEMENTATION_CHECKLIST.md`
|
||||
2. **Ready for Testing:** `doc/IOS_PHASE1_READY_FOR_TESTING.md`
|
||||
|
||||
### Directive
|
||||
|
||||
1. **Full Directive:** `doc/directives/0003-iOS-Android-Parity-Directive.md`
|
||||
|
||||
---
|
||||
|
||||
## ✅ Success Criteria Met
|
||||
|
||||
### Functional Parity
|
||||
- ✅ All Android `@PluginMethod` methods have iOS equivalents (Phase 1 scope)
|
||||
- ✅ All methods return same data structures as Android
|
||||
- ✅ All methods handle errors consistently with Android
|
||||
- ✅ All methods log consistently with Android
|
||||
|
||||
### Platform Adaptations
|
||||
- ✅ iOS uses appropriate iOS APIs (UNUserNotificationCenter, BGTaskScheduler)
|
||||
- ✅ iOS respects iOS limits (64 notification limit documented)
|
||||
- ✅ iOS provides iOS-specific features (Background App Refresh)
|
||||
|
||||
### Code Quality
|
||||
- ✅ All code follows Swift best practices
|
||||
- ✅ All code is documented with file-level and method-level comments
|
||||
- ✅ All code includes error handling and logging
|
||||
- ✅ All code is type-safe
|
||||
- ✅ No compilation errors
|
||||
- ✅ No linter errors
|
||||
|
||||
---
|
||||
|
||||
## 🔗 References
|
||||
|
||||
- **Directive:** `doc/directives/0003-iOS-Android-Parity-Directive.md`
|
||||
- **Android Reference:** `src/android/DailyNotificationPlugin.java`
|
||||
- **TypeScript Interface:** `src/definitions.ts`
|
||||
- **Testing Guide:** `doc/IOS_PHASE1_TESTING_GUIDE.md`
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Conclusion
|
||||
|
||||
**Phase 1 implementation is complete and ready for testing.**
|
||||
|
||||
All core infrastructure components have been implemented, integrated, and documented. The codebase is clean, well-documented, and follows iOS best practices. The implementation maintains functional parity with Android within Phase 1 scope.
|
||||
|
||||
**Next Action:** Begin testing using `doc/IOS_PHASE1_TESTING_GUIDE.md`
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ **PHASE 1 COMPLETE - READY FOR TESTING**
|
||||
**Last Updated:** 2025-01-XX
|
||||
|
||||
149
docs/_archive/2025-legacy-doc/IOS_PHASE1_GAPS_ANALYSIS.md
Normal file
149
docs/_archive/2025-legacy-doc/IOS_PHASE1_GAPS_ANALYSIS.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# iOS Phase 1 Gaps Analysis
|
||||
|
||||
**Status:** ✅ **ALL GAPS ADDRESSED - PHASE 1 COMPLETE**
|
||||
**Date:** 2025-01-XX
|
||||
**Objective:** Verify Phase 1 directive compliance
|
||||
|
||||
---
|
||||
|
||||
## Directive Compliance Check
|
||||
|
||||
### ✅ Completed Requirements
|
||||
|
||||
1. **Core Methods (6/6)** ✅
|
||||
- `configure()` ✅
|
||||
- `scheduleDailyNotification()` ✅
|
||||
- `getLastNotification()` ✅
|
||||
- `cancelAllNotifications()` ✅
|
||||
- `getNotificationStatus()` ✅
|
||||
- `updateSettings()` ✅
|
||||
|
||||
2. **Infrastructure Components** ✅
|
||||
- Storage layer (DailyNotificationStorage.swift) ✅
|
||||
- Scheduler (DailyNotificationScheduler.swift) ✅
|
||||
- State actor (DailyNotificationStateActor.swift) ✅
|
||||
- Error codes (DailyNotificationErrorCodes.swift) ✅
|
||||
|
||||
3. **Background Tasks** ✅
|
||||
- BGTaskScheduler registration ✅
|
||||
- BGTask miss detection ✅
|
||||
- Auto-rescheduling ✅
|
||||
|
||||
4. **Build Script** ✅
|
||||
- `scripts/build-ios-test-app.sh` created ✅
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Identified Gaps
|
||||
|
||||
### Gap 1: Test App Requirements Document
|
||||
|
||||
**Directive Requirement:**
|
||||
- Line 1013: "**Important:** If `doc/test-app-ios/IOS_TEST_APP_REQUIREMENTS.md` does not yet exist, it **MUST be created as part of Phase 1** before implementation starts."
|
||||
|
||||
**Status:** ✅ **NOW CREATED**
|
||||
- File created: `doc/test-app-ios/IOS_TEST_APP_REQUIREMENTS.md`
|
||||
- Includes UI parity requirements
|
||||
- Includes iOS permissions configuration
|
||||
- Includes build options
|
||||
- Includes debugging strategy
|
||||
- Includes test app implementation checklist
|
||||
|
||||
### Gap 2: Error Code Verification
|
||||
|
||||
**Directive Requirement:**
|
||||
- Line 549: "**Note:** This TODO is **blocking for Phase 1**: iOS error handling must not be considered complete until the table is extracted and mirrored. Phase 1 implementation should not proceed without verifying error code parity."
|
||||
|
||||
**Status:** ✅ **VERIFIED AND COMPLETE**
|
||||
|
||||
**Verification Completed:**
|
||||
- ✅ Comprehensive error code mapping document created: `doc/IOS_ANDROID_ERROR_CODE_MAPPING.md`
|
||||
- ✅ All Phase 1 error scenarios mapped and verified
|
||||
- ✅ Semantic equivalence confirmed for all error codes
|
||||
- ✅ Directive updated to reflect completion
|
||||
|
||||
**Findings:**
|
||||
- Android uses `call.reject()` with string messages
|
||||
- Directive requires structured error codes: `{ "error": "code", "message": "..." }`
|
||||
- iOS implementation provides structured error codes ✅
|
||||
- All iOS error codes semantically match Android error messages ✅
|
||||
- iOS error response format matches directive requirements ✅
|
||||
|
||||
**Error Code Mapping:**
|
||||
- `"Time parameter is required"` → `MISSING_REQUIRED_PARAMETER` ✅
|
||||
- `"Invalid time format. Use HH:mm"` → `INVALID_TIME_FORMAT` ✅
|
||||
- `"Invalid time values"` → `INVALID_TIME_VALUES` ✅
|
||||
- `"Failed to schedule notification"` → `SCHEDULING_FAILED` ✅
|
||||
- `"Configuration failed: ..."` → `CONFIGURATION_FAILED` ✅
|
||||
- `"Internal error: ..."` → `INTERNAL_ERROR` ✅
|
||||
|
||||
**Conclusion:**
|
||||
- ✅ Error code parity verified and complete
|
||||
- ✅ All Phase 1 methods covered
|
||||
- ✅ Directive requirement satisfied
|
||||
|
||||
---
|
||||
|
||||
## Remaining Tasks
|
||||
|
||||
### Critical (Blocking Phase 1 Completion)
|
||||
|
||||
1. ✅ **Test App Requirements Document** - CREATED
|
||||
2. ✅ **Error Code Verification** - VERIFIED AND COMPLETE
|
||||
|
||||
### Non-Critical (Can Complete Later)
|
||||
|
||||
1. ⏳ **iOS Test App Creation** - Not blocking Phase 1 code completion
|
||||
2. ⏳ **Unit Tests** - Deferred to Phase 2
|
||||
3. ⏳ **Integration Tests** - Deferred to Phase 2
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
### Code Implementation
|
||||
- [x] All Phase 1 methods implemented
|
||||
- [x] Storage layer complete
|
||||
- [x] Scheduler complete
|
||||
- [x] State actor complete
|
||||
- [x] Error codes implemented
|
||||
- [x] BGTask miss detection working
|
||||
- [x] Permission auto-healing working
|
||||
|
||||
### Documentation
|
||||
- [x] Testing guide created
|
||||
- [x] Quick reference created
|
||||
- [x] Implementation checklist created
|
||||
- [x] **Test app requirements document created** ✅
|
||||
- [x] Final summary created
|
||||
|
||||
### Error Handling
|
||||
- [x] Structured error codes implemented
|
||||
- [x] Error response format matches directive
|
||||
- [x] Error codes verified against Android semantics ✅
|
||||
- [x] Error code mapping document created ✅
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
1. **Error Code Verification:**
|
||||
- Review Android error messages vs iOS error codes
|
||||
- Ensure semantic equivalence
|
||||
- Document any discrepancies
|
||||
|
||||
2. **Test App Creation:**
|
||||
- Create iOS test app using requirements document
|
||||
- Test all Phase 1 methods
|
||||
- Verify error handling
|
||||
|
||||
3. **Final Verification:**
|
||||
- Run through Phase 1 completion checklist
|
||||
- Verify all directive requirements met
|
||||
- Document any remaining gaps
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ **ALL GAPS ADDRESSED - PHASE 1 COMPLETE**
|
||||
**Last Updated:** 2025-01-XX
|
||||
|
||||
129
docs/_archive/2025-legacy-doc/IOS_PHASE1_QUICK_REFERENCE.md
Normal file
129
docs/_archive/2025-legacy-doc/IOS_PHASE1_QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# iOS Phase 1 Quick Reference
|
||||
|
||||
**Status:** ✅ **PHASE 1 COMPLETE**
|
||||
**Quick reference for developers working with iOS implementation**
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
### Core Components
|
||||
|
||||
```
|
||||
ios/Plugin/
|
||||
├── DailyNotificationPlugin.swift # Main plugin (1157 lines)
|
||||
├── DailyNotificationStorage.swift # Storage abstraction (334 lines)
|
||||
├── DailyNotificationScheduler.swift # Scheduler (322 lines)
|
||||
├── DailyNotificationStateActor.swift # Thread-safe state (211 lines)
|
||||
├── DailyNotificationErrorCodes.swift # Error codes (113 lines)
|
||||
├── NotificationContent.swift # Data model (238 lines)
|
||||
└── DailyNotificationDatabase.swift # Database (241 lines)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Methods (Phase 1)
|
||||
|
||||
### Configuration
|
||||
```swift
|
||||
@objc func configure(_ call: CAPPluginCall)
|
||||
```
|
||||
|
||||
### Core Notification Methods
|
||||
```swift
|
||||
@objc func scheduleDailyNotification(_ call: CAPPluginCall)
|
||||
@objc func getLastNotification(_ call: CAPPluginCall)
|
||||
@objc func cancelAllNotifications(_ call: CAPPluginCall)
|
||||
@objc func getNotificationStatus(_ call: CAPPluginCall)
|
||||
@objc func updateSettings(_ call: CAPPluginCall)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Codes
|
||||
|
||||
```swift
|
||||
DailyNotificationErrorCodes.NOTIFICATIONS_DENIED
|
||||
DailyNotificationErrorCodes.INVALID_TIME_FORMAT
|
||||
DailyNotificationErrorCodes.SCHEDULING_FAILED
|
||||
DailyNotificationErrorCodes.PLUGIN_NOT_INITIALIZED
|
||||
DailyNotificationErrorCodes.MISSING_REQUIRED_PARAMETER
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Log Prefixes
|
||||
|
||||
- `DNP-PLUGIN:` - Main plugin operations
|
||||
- `DNP-FETCH:` - Background fetch operations
|
||||
- `DNP-FETCH-SCHEDULE:` - BGTask scheduling
|
||||
- `DailyNotificationStorage:` - Storage operations
|
||||
- `DailyNotificationScheduler:` - Scheduling operations
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
**Primary Guide:** `doc/IOS_PHASE1_TESTING_GUIDE.md`
|
||||
|
||||
**Quick Test:**
|
||||
```javascript
|
||||
// Schedule notification
|
||||
await DailyNotification.scheduleDailyNotification({
|
||||
options: {
|
||||
time: "09:00",
|
||||
title: "Test",
|
||||
body: "Test notification"
|
||||
}
|
||||
});
|
||||
|
||||
// Check status
|
||||
const status = await DailyNotification.getNotificationStatus();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Debugging Commands
|
||||
|
||||
**Xcode Debugger:**
|
||||
```swift
|
||||
// Check pending notifications
|
||||
po UNUserNotificationCenter.current().pendingNotificationRequests()
|
||||
|
||||
// Check permissions
|
||||
po await UNUserNotificationCenter.current().notificationSettings()
|
||||
|
||||
// Manually trigger BGTask (Simulator only)
|
||||
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.timesafari.dailynotification.fetch"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 Scope
|
||||
|
||||
✅ **Implemented:**
|
||||
- Single daily schedule (one prefetch + one notification)
|
||||
- Permission auto-healing
|
||||
- BGTask miss detection
|
||||
- Thread-safe state access
|
||||
- Error code matching
|
||||
|
||||
⏳ **Deferred to Phase 2:**
|
||||
- Rolling window (beyond single daily)
|
||||
- TTL enforcement
|
||||
- Reboot recovery (full implementation)
|
||||
- Power management
|
||||
|
||||
⏳ **Deferred to Phase 3:**
|
||||
- JWT authentication
|
||||
- ETag caching
|
||||
- TimeSafari API integration
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **Directive:** `doc/directives/0003-iOS-Android-Parity-Directive.md`
|
||||
- **Testing Guide:** `doc/IOS_PHASE1_TESTING_GUIDE.md`
|
||||
- **Completion Summary:** `doc/PHASE1_COMPLETION_SUMMARY.md`
|
||||
|
||||
272
docs/_archive/2025-legacy-doc/IOS_PHASE1_READY_FOR_TESTING.md
Normal file
272
docs/_archive/2025-legacy-doc/IOS_PHASE1_READY_FOR_TESTING.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# iOS Phase 1 - Ready for Testing
|
||||
|
||||
**Status:** ✅ **IMPLEMENTATION COMPLETE - READY FOR TESTING**
|
||||
**Date:** 2025-01-XX
|
||||
**Branch:** `ios-2`
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What's Been Completed
|
||||
|
||||
### Core Infrastructure ✅
|
||||
|
||||
All Phase 1 infrastructure components have been implemented:
|
||||
|
||||
1. **Storage Layer** (`DailyNotificationStorage.swift`)
|
||||
- UserDefaults + CoreData integration
|
||||
- Content caching with automatic cleanup
|
||||
- BGTask tracking for miss detection
|
||||
|
||||
2. **Scheduler** (`DailyNotificationScheduler.swift`)
|
||||
- UNUserNotificationCenter integration
|
||||
- Permission auto-healing
|
||||
- Calendar-based triggers with ±180s tolerance
|
||||
|
||||
3. **Thread Safety** (`DailyNotificationStateActor.swift`)
|
||||
- Actor-based concurrency
|
||||
- Serialized state access
|
||||
- Fallback for iOS < 13
|
||||
|
||||
4. **Error Handling** (`DailyNotificationErrorCodes.swift`)
|
||||
- Structured error codes matching Android
|
||||
- Helper methods for error responses
|
||||
|
||||
### Phase 1 Methods ✅
|
||||
|
||||
All 6 Phase 1 core methods implemented:
|
||||
|
||||
- ✅ `configure()` - Full Android parity
|
||||
- ✅ `scheduleDailyNotification()` - Main scheduling with prefetch
|
||||
- ✅ `getLastNotification()` - Last notification retrieval
|
||||
- ✅ `cancelAllNotifications()` - Cancel all notifications
|
||||
- ✅ `getNotificationStatus()` - Status retrieval
|
||||
- ✅ `updateSettings()` - Settings update
|
||||
|
||||
### Background Tasks ✅
|
||||
|
||||
- ✅ BGTaskScheduler registration
|
||||
- ✅ Background fetch handler
|
||||
- ✅ BGTask miss detection (15-minute window)
|
||||
- ✅ Auto-rescheduling on miss
|
||||
|
||||
---
|
||||
|
||||
## 📚 Testing Documentation
|
||||
|
||||
### Primary Testing Guide
|
||||
|
||||
**`doc/IOS_PHASE1_TESTING_GUIDE.md`** - Complete testing guide with:
|
||||
- 10 detailed test cases
|
||||
- Step-by-step instructions
|
||||
- Expected results
|
||||
- Debugging commands
|
||||
- Common issues & solutions
|
||||
|
||||
### Quick Reference
|
||||
|
||||
**`doc/IOS_PHASE1_QUICK_REFERENCE.md`** - Quick reference for:
|
||||
- File structure
|
||||
- Key methods
|
||||
- Error codes
|
||||
- Log prefixes
|
||||
- Debugging commands
|
||||
|
||||
### Implementation Checklist
|
||||
|
||||
**`doc/IOS_PHASE1_IMPLEMENTATION_CHECKLIST.md`** - Verification checklist
|
||||
|
||||
---
|
||||
|
||||
## 🧪 How to Test
|
||||
|
||||
### Quick Start
|
||||
|
||||
1. **Open Testing Guide:**
|
||||
```bash
|
||||
# View comprehensive testing guide
|
||||
cat doc/IOS_PHASE1_TESTING_GUIDE.md
|
||||
```
|
||||
|
||||
2. **Run Test Cases:**
|
||||
- Follow test cases 1-10 in the testing guide
|
||||
- Use JavaScript test code provided
|
||||
- Check Console.app for logs
|
||||
|
||||
3. **Debug Issues:**
|
||||
- Use Xcode debugger commands from guide
|
||||
- Check log prefixes: `DNP-PLUGIN:`, `DNP-FETCH:`, etc.
|
||||
- Review "Common Issues & Solutions" section
|
||||
|
||||
### Test App Setup
|
||||
|
||||
**Note:** iOS test app (`test-apps/ios-test-app/`) needs to be created. See directive for requirements.
|
||||
|
||||
**Quick Build (when test app exists):**
|
||||
```bash
|
||||
./scripts/build-ios-test-app.sh --simulator
|
||||
cd test-apps/ios-test-app
|
||||
open App.xcworkspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Testing Checklist
|
||||
|
||||
### Core Methods
|
||||
- [ ] `configure()` works correctly
|
||||
- [ ] `scheduleDailyNotification()` schedules notification
|
||||
- [ ] Prefetch scheduled 5 minutes before notification
|
||||
- [ ] `getLastNotification()` returns correct data
|
||||
- [ ] `cancelAllNotifications()` cancels all
|
||||
- [ ] `getNotificationStatus()` returns accurate status
|
||||
- [ ] `updateSettings()` updates settings
|
||||
|
||||
### Background Tasks
|
||||
- [ ] BGTask scheduled correctly
|
||||
- [ ] BGTask executes successfully
|
||||
- [ ] BGTask miss detection works
|
||||
- [ ] BGTask rescheduling works
|
||||
|
||||
### Error Handling
|
||||
- [ ] Error codes match Android format
|
||||
- [ ] Missing parameter errors work
|
||||
- [ ] Invalid time format errors work
|
||||
- [ ] Permission denied errors work
|
||||
|
||||
### Thread Safety
|
||||
- [ ] No race conditions
|
||||
- [ ] State actor used correctly
|
||||
- [ ] Background tasks use state actor
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Key Testing Points
|
||||
|
||||
### 1. Notification Scheduling
|
||||
|
||||
**Test:** Schedule notification 5 minutes from now
|
||||
|
||||
**Verify:**
|
||||
- Notification scheduled successfully
|
||||
- Prefetch BGTask scheduled 5 minutes before
|
||||
- Notification appears at scheduled time (±180s tolerance)
|
||||
|
||||
**Logs to Check:**
|
||||
```
|
||||
DNP-PLUGIN: Daily notification scheduled successfully
|
||||
DNP-FETCH-SCHEDULE: Background fetch scheduled for [date]
|
||||
DailyNotificationScheduler: Notification scheduled successfully
|
||||
```
|
||||
|
||||
### 2. BGTask Miss Detection
|
||||
|
||||
**Test:** Schedule notification, wait 15+ minutes, launch app
|
||||
|
||||
**Verify:**
|
||||
- Miss detection triggers on app launch
|
||||
- BGTask rescheduled for 1 minute from now
|
||||
- Logs show miss detection
|
||||
|
||||
**Logs to Check:**
|
||||
```
|
||||
DNP-FETCH: BGTask missed window; rescheduling
|
||||
DNP-FETCH: BGTask rescheduled for [date]
|
||||
```
|
||||
|
||||
### 3. Permission Auto-Healing
|
||||
|
||||
**Test:** Deny permissions, then schedule notification
|
||||
|
||||
**Verify:**
|
||||
- Permission request dialog appears
|
||||
- Scheduling succeeds after granting
|
||||
- Error returned if denied
|
||||
|
||||
**Logs to Check:**
|
||||
```
|
||||
DailyNotificationScheduler: Permission request result: true
|
||||
DailyNotificationScheduler: Scheduling notification: [id]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Common Issues
|
||||
|
||||
### BGTask Not Running
|
||||
|
||||
**Solution:** Use simulator-only LLDB command:
|
||||
```swift
|
||||
e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.timesafari.dailynotification.fetch"]
|
||||
```
|
||||
|
||||
### Notifications Not Delivering
|
||||
|
||||
**Check:**
|
||||
1. Permissions granted
|
||||
2. Notification scheduled: `getPendingNotificationRequests()`
|
||||
3. Time hasn't passed (iOS may deliver immediately)
|
||||
|
||||
### Build Failures
|
||||
|
||||
**Solutions:**
|
||||
1. Run `pod install` in `ios/` directory
|
||||
2. Clean build folder (Cmd+Shift+K)
|
||||
3. Verify Capacitor plugin path
|
||||
|
||||
---
|
||||
|
||||
## 📊 Implementation Statistics
|
||||
|
||||
- **Total Lines:** ~2,600+ lines
|
||||
- **Files Created:** 4 new files
|
||||
- **Files Enhanced:** 3 existing files
|
||||
- **Methods Implemented:** 6 Phase 1 methods
|
||||
- **Error Codes:** 8+ error codes
|
||||
- **Test Cases:** 10 test cases documented
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
### Immediate
|
||||
|
||||
1. **Create iOS Test App** (`test-apps/ios-test-app/`)
|
||||
2. **Create Build Script** (`scripts/build-ios-test-app.sh`)
|
||||
3. **Run Test Cases** from testing guide
|
||||
4. **Document Issues** found during testing
|
||||
|
||||
### Phase 2 Preparation
|
||||
|
||||
1. Review Phase 2 requirements
|
||||
2. Plan rolling window implementation
|
||||
3. Plan TTL enforcement
|
||||
4. Plan reboot recovery enhancement
|
||||
|
||||
---
|
||||
|
||||
## 📖 Documentation Files
|
||||
|
||||
1. **`doc/IOS_PHASE1_TESTING_GUIDE.md`** - Comprehensive testing guide
|
||||
2. **`doc/IOS_PHASE1_QUICK_REFERENCE.md`** - Quick reference
|
||||
3. **`doc/IOS_PHASE1_IMPLEMENTATION_CHECKLIST.md`** - Verification checklist
|
||||
4. **`doc/PHASE1_COMPLETION_SUMMARY.md`** - Implementation summary
|
||||
5. **`doc/directives/0003-iOS-Android-Parity-Directive.md`** - Full directive
|
||||
|
||||
---
|
||||
|
||||
## ✅ Verification
|
||||
|
||||
- [x] All Phase 1 methods implemented
|
||||
- [x] Error codes match Android format
|
||||
- [x] Thread safety via state actor
|
||||
- [x] BGTask miss detection working
|
||||
- [x] Permission auto-healing working
|
||||
- [x] Documentation complete
|
||||
- [x] No compilation errors
|
||||
- [x] No linter errors
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ **READY FOR TESTING**
|
||||
**Start Here:** `doc/IOS_PHASE1_TESTING_GUIDE.md`
|
||||
|
||||
265
docs/_archive/2025-legacy-doc/PHASE1_COMPLETION_SUMMARY.md
Normal file
265
docs/_archive/2025-legacy-doc/PHASE1_COMPLETION_SUMMARY.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# Phase 1 Implementation Completion Summary
|
||||
|
||||
**Date:** 2025-01-XX
|
||||
**Status:** ✅ **COMPLETE**
|
||||
**Branch:** `ios-2`
|
||||
**Objective:** Core Infrastructure Parity - Single daily schedule (one prefetch + one notification)
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Phase 1 of the iOS-Android Parity Directive has been successfully completed. All core infrastructure components have been implemented, providing a solid foundation for Phase 2 advanced features.
|
||||
|
||||
### Key Achievements
|
||||
|
||||
- ✅ **Storage Layer**: Complete abstraction with UserDefaults + CoreData
|
||||
- ✅ **Scheduler**: UNUserNotificationCenter integration with permission auto-healing
|
||||
- ✅ **Background Tasks**: BGTaskScheduler with miss detection and rescheduling
|
||||
- ✅ **Thread Safety**: Actor-based concurrency for all state access
|
||||
- ✅ **Error Handling**: Structured error codes matching Android format
|
||||
- ✅ **Core Methods**: All Phase 1 methods implemented and tested
|
||||
|
||||
---
|
||||
|
||||
## Files Created
|
||||
|
||||
### New Components
|
||||
|
||||
1. **DailyNotificationStorage.swift** (334 lines)
|
||||
- Storage abstraction layer
|
||||
- UserDefaults + CoreData integration
|
||||
- Content caching with automatic cleanup
|
||||
- BGTask tracking for miss detection
|
||||
- Thread-safe operations with concurrent queue
|
||||
|
||||
2. **DailyNotificationScheduler.swift** (322 lines)
|
||||
- UNUserNotificationCenter integration
|
||||
- Permission auto-healing (checks and requests automatically)
|
||||
- Calendar-based triggers with ±180s tolerance
|
||||
- Status queries and cancellation
|
||||
- Utility methods: `calculateNextOccurrence()`, `getNextNotificationTime()`
|
||||
|
||||
3. **DailyNotificationStateActor.swift** (211 lines)
|
||||
- Thread-safe state access using Swift actors
|
||||
- Serializes all database/storage operations
|
||||
- Ready for Phase 2 rolling window and TTL enforcement
|
||||
|
||||
4. **DailyNotificationErrorCodes.swift** (113 lines)
|
||||
- Error code constants matching Android
|
||||
- Helper methods for error responses
|
||||
- Covers all error categories
|
||||
|
||||
### Enhanced Files
|
||||
|
||||
1. **DailyNotificationPlugin.swift** (1157 lines)
|
||||
- Enhanced `configure()` method
|
||||
- Implemented all Phase 1 core methods
|
||||
- BGTask handlers with miss detection
|
||||
- Integrated state actor and error codes
|
||||
- Added `getHealthStatus()` for dual scheduling status
|
||||
- Improved `getNotificationStatus()` with next notification time calculation
|
||||
|
||||
2. **NotificationContent.swift** (238 lines)
|
||||
- Updated to use Int64 (milliseconds) matching Android
|
||||
- Added Codable support for JSON encoding
|
||||
|
||||
3. **DailyNotificationDatabase.swift** (241 lines)
|
||||
- Added stub methods for notification persistence
|
||||
- Ready for Phase 2 full database integration
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 Methods Implemented
|
||||
|
||||
### Core Methods ✅
|
||||
|
||||
1. **`configure(options: ConfigureOptions)`**
|
||||
- Full Android parity
|
||||
- Supports dbPath, storage mode, TTL, prefetch lead, max notifications, retention
|
||||
- Stores configuration in UserDefaults/CoreData
|
||||
|
||||
2. **`scheduleDailyNotification(options: NotificationOptions)`**
|
||||
- Main scheduling method
|
||||
- Single daily schedule (one prefetch 5 min before + one notification)
|
||||
- Permission auto-healing
|
||||
- Error code integration
|
||||
|
||||
3. **`getLastNotification()`**
|
||||
- Returns last delivered notification
|
||||
- Thread-safe via state actor
|
||||
- Returns empty object if none exists
|
||||
|
||||
4. **`cancelAllNotifications()`**
|
||||
- Cancels all scheduled notifications
|
||||
- Clears storage
|
||||
- Thread-safe via state actor
|
||||
|
||||
5. **`getNotificationStatus()`**
|
||||
- Returns current notification status
|
||||
- Includes permission status, pending count, last notification time
|
||||
- Thread-safe via state actor
|
||||
|
||||
6. **`updateSettings(settings: NotificationSettings)`**
|
||||
- Updates notification settings
|
||||
- Thread-safe via state actor
|
||||
- Error code integration
|
||||
|
||||
---
|
||||
|
||||
## Technical Implementation Details
|
||||
|
||||
### Thread Safety
|
||||
|
||||
All state access goes through `DailyNotificationStateActor`:
|
||||
- Uses Swift `actor` for serialized access
|
||||
- Fallback to direct storage for iOS < 13
|
||||
- Background tasks use async/await with actor
|
||||
- No direct concurrent access to shared state
|
||||
|
||||
### Error Handling
|
||||
|
||||
Structured error responses matching Android:
|
||||
```swift
|
||||
{
|
||||
"error": "error_code",
|
||||
"message": "Human-readable error message"
|
||||
}
|
||||
```
|
||||
|
||||
Error codes implemented:
|
||||
- `PLUGIN_NOT_INITIALIZED`
|
||||
- `MISSING_REQUIRED_PARAMETER`
|
||||
- `INVALID_TIME_FORMAT`
|
||||
- `SCHEDULING_FAILED`
|
||||
- `NOTIFICATIONS_DENIED`
|
||||
- `BACKGROUND_REFRESH_DISABLED`
|
||||
- `STORAGE_ERROR`
|
||||
- `INTERNAL_ERROR`
|
||||
|
||||
### BGTask Miss Detection
|
||||
|
||||
- Checks on app launch for missed BGTask
|
||||
- 15-minute window for detection
|
||||
- Auto-reschedules if missed
|
||||
- Tracks successful runs to avoid false positives
|
||||
|
||||
### Permission Auto-Healing
|
||||
|
||||
- Checks permission status before scheduling
|
||||
- Requests permissions if not determined
|
||||
- Returns appropriate error codes if denied
|
||||
- Logs error codes for debugging
|
||||
|
||||
---
|
||||
|
||||
## Testing Status
|
||||
|
||||
### Unit Tests
|
||||
- ⏳ Pending (to be implemented in Phase 2)
|
||||
|
||||
### Integration Tests
|
||||
- ⏳ Pending (to be implemented in Phase 2)
|
||||
|
||||
### Manual Testing
|
||||
- ✅ Code compiles without errors
|
||||
- ✅ All methods implemented
|
||||
- ⏳ iOS Simulator testing pending
|
||||
|
||||
---
|
||||
|
||||
## Known Limitations (By Design)
|
||||
|
||||
### Phase 1 Scope
|
||||
|
||||
1. **Single Daily Schedule**: Only one prefetch + one notification per day
|
||||
- Rolling window deferred to Phase 2
|
||||
|
||||
2. **Dummy Content Fetcher**: Returns static content
|
||||
- JWT/ETag integration deferred to Phase 3
|
||||
|
||||
3. **No TTL Enforcement**: TTL validation skipped
|
||||
- TTL enforcement deferred to Phase 2
|
||||
|
||||
4. **Simple Reboot Recovery**: Basic reschedule on launch
|
||||
- Full reboot detection deferred to Phase 2
|
||||
|
||||
---
|
||||
|
||||
## Next Steps (Phase 2)
|
||||
|
||||
### Advanced Features Parity
|
||||
|
||||
1. **Rolling Window Enhancement**
|
||||
- Expand beyond single daily schedule
|
||||
- Enforce iOS 64 notification limit
|
||||
- Prioritize today's notifications
|
||||
|
||||
2. **TTL Enforcement**
|
||||
- Check at notification fire time
|
||||
- Discard stale content
|
||||
- Log TTL violations
|
||||
|
||||
3. **Exact Alarm Equivalent**
|
||||
- Document iOS constraints (±180s tolerance)
|
||||
- Use UNCalendarNotificationTrigger with tolerance
|
||||
- Provide status reporting
|
||||
|
||||
4. **Reboot Recovery**
|
||||
- Uptime comparison strategy
|
||||
- Auto-reschedule on app launch
|
||||
- Status reporting
|
||||
|
||||
5. **Power Management**
|
||||
- Battery status reporting
|
||||
- Background App Refresh status
|
||||
- Power state management
|
||||
|
||||
---
|
||||
|
||||
## Code Quality Metrics
|
||||
|
||||
- **Total Lines of Code**: ~2,600+ lines
|
||||
- **Files Created**: 4 new files
|
||||
- **Files Enhanced**: 3 existing files
|
||||
- **Error Handling**: Comprehensive with structured responses
|
||||
- **Thread Safety**: Actor-based concurrency throughout
|
||||
- **Documentation**: File-level and method-level comments
|
||||
- **Code Style**: Follows Swift best practices
|
||||
- **Utility Methods**: Time calculation helpers matching Android
|
||||
- **Status Methods**: Complete health status reporting
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria ✅
|
||||
|
||||
### Functional Parity
|
||||
- ✅ All Android `@PluginMethod` methods have iOS equivalents (Phase 1 scope)
|
||||
- ✅ All methods return same data structures as Android
|
||||
- ✅ All methods handle errors consistently with Android
|
||||
- ✅ All methods log consistently with Android
|
||||
|
||||
### Platform Adaptations
|
||||
- ✅ iOS uses appropriate iOS APIs (UNUserNotificationCenter, BGTaskScheduler)
|
||||
- ✅ iOS respects iOS limits (64 notification limit documented)
|
||||
- ✅ iOS provides iOS-specific features (Background App Refresh)
|
||||
|
||||
### Code Quality
|
||||
- ✅ All code follows Swift best practices
|
||||
- ✅ All code is documented with file-level and method-level comments
|
||||
- ✅ All code includes error handling and logging
|
||||
- ✅ All code is type-safe
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **Directive**: `doc/directives/0003-iOS-Android-Parity-Directive.md`
|
||||
- **Android Reference**: `src/android/DailyNotificationPlugin.java`
|
||||
- **TypeScript Interface**: `src/definitions.ts`
|
||||
|
||||
---
|
||||
|
||||
**Status:** ✅ **PHASE 1 COMPLETE**
|
||||
**Ready for:** Phase 2 Advanced Features Implementation
|
||||
|
||||
157
docs/_archive/2025-legacy-doc/RESEARCH_COMPLETE.md
Normal file
157
docs/_archive/2025-legacy-doc/RESEARCH_COMPLETE.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# Daily Notification Plugin Enhancement - Research Complete
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-01-27
|
||||
**Status**: Research Phase Complete
|
||||
**Branch**: research/notification-plugin-enhancement
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Research phase completed for enhancing the daily notification plugin with dual
|
||||
scheduling system and callback mechanisms. Key findings:
|
||||
|
||||
- **Current State**: Basic notification plugin with single scheduling method
|
||||
- **Requirements**: Dual scheduling (content fetch + user notification) + callbacks
|
||||
- **Architecture**: Plugin API design with platform-specific implementations
|
||||
- **Next Phase**: Platform-specific implementation
|
||||
|
||||
## Requirements Analysis
|
||||
|
||||
### User Feedback
|
||||
|
||||
- Need callbacks for API calls, database operations, reporting services
|
||||
- Require two distinct scheduling methods:
|
||||
- Content fetch and storage
|
||||
- User notification display
|
||||
- Backward compatibility essential
|
||||
|
||||
### Core Requirements
|
||||
|
||||
1. **Dual Scheduling System**
|
||||
- `scheduleContentFetch()` - API calls, data processing, storage
|
||||
- `scheduleUserNotification()` - Retrieve data, display notifications
|
||||
2. **Callback Management**
|
||||
- API callbacks for external services
|
||||
- Database operation callbacks
|
||||
- Reporting service callbacks
|
||||
3. **Backward Compatibility**
|
||||
- Existing `schedule()` method must continue working
|
||||
- Gradual migration path for existing implementations
|
||||
|
||||
## Proposed Architecture
|
||||
|
||||
### Plugin API Design
|
||||
|
||||
```typescript
|
||||
interface DailyNotificationPlugin {
|
||||
// Dual Scheduling Methods
|
||||
scheduleContentFetch(config: ContentFetchConfig): Promise<void>;
|
||||
scheduleUserNotification(config: UserNotificationConfig): Promise<void>;
|
||||
scheduleDualNotification(config: DualScheduleConfiguration): Promise<void>;
|
||||
|
||||
// Status & Management
|
||||
getDualScheduleStatus(): Promise<DualScheduleStatus>;
|
||||
updateDualScheduleConfig(config: DualScheduleConfiguration): Promise<void>;
|
||||
cancelDualSchedule(): Promise<void>;
|
||||
|
||||
// Content Management
|
||||
getContentCache(): Promise<ContentCache>;
|
||||
clearContentCache(): Promise<void>;
|
||||
getContentHistory(): Promise<ContentHistory[]>;
|
||||
|
||||
// Callback Management
|
||||
registerCallback(id: string, callback: CallbackFunction): Promise<void>;
|
||||
unregisterCallback(id: string): Promise<void>;
|
||||
getRegisteredCallbacks(): Promise<CallbackRegistry>;
|
||||
}
|
||||
```
|
||||
|
||||
### Platform Integration
|
||||
|
||||
- **Android**: WorkManager, AlarmManager, NotificationManager
|
||||
- **iOS**: BGTaskScheduler, UNUserNotificationCenter
|
||||
- **Web**: Service Worker, Push API, IndexedDB
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
### Phase 1: Core API Design ✅
|
||||
|
||||
- TypeScript interfaces defined
|
||||
- Mock implementations for web platform
|
||||
- Test suite updated
|
||||
|
||||
### Phase 2: Platform-Specific Implementation
|
||||
|
||||
- Android native implementation
|
||||
- iOS native implementation
|
||||
- Web platform enhancement
|
||||
|
||||
### Phase 3: Callback System
|
||||
|
||||
- Callback registry implementation
|
||||
- Error handling and logging
|
||||
- Performance optimization
|
||||
|
||||
### Phase 4: Testing & Validation
|
||||
|
||||
- Unit tests for all platforms
|
||||
- Integration testing
|
||||
- Performance benchmarking
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
### Technical Risks
|
||||
|
||||
- **Platform Differences**: Each platform has unique scheduling constraints
|
||||
- **Performance Impact**: Dual scheduling may affect battery life
|
||||
- **Complexity**: Callback system adds significant complexity
|
||||
|
||||
### Mitigation Strategies
|
||||
|
||||
- Comprehensive testing across all platforms
|
||||
- Performance monitoring and optimization
|
||||
- Gradual rollout with fallback mechanisms
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Immediate Actions
|
||||
|
||||
1. **Begin Platform-Specific Implementation**
|
||||
- Start with Android implementation
|
||||
- Implement iOS native code
|
||||
- Enhance web platform functionality
|
||||
|
||||
2. **Callback System Development**
|
||||
- Design callback registry
|
||||
- Implement error handling
|
||||
- Add logging and monitoring
|
||||
|
||||
3. **Testing Strategy**
|
||||
- Unit tests for each platform
|
||||
- Integration testing
|
||||
- Performance validation
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Dual scheduling system functional on all platforms
|
||||
- [ ] Callback system operational with error handling
|
||||
- [ ] Backward compatibility maintained
|
||||
- [ ] Performance within acceptable limits
|
||||
- [ ] Comprehensive test coverage
|
||||
|
||||
## Conclusion
|
||||
|
||||
Research phase successfully completed with clear architecture and implementation
|
||||
strategy. The plugin enhancement will provide robust dual scheduling capabilities
|
||||
with callback support while maintaining backward compatibility. Ready to proceed
|
||||
with platform-specific implementation phase.
|
||||
|
||||
---
|
||||
|
||||
**Document Consolidation**: This document consolidates all research findings
|
||||
from previous separate documents (TODO.md, CALLBACK_ANALYSIS.md,
|
||||
IMPLEMENTATION_PLAN.md, README_RESEARCH.md) into a single source of truth.
|
||||
|
||||
**Last Updated**: 2025-01-27T15:30:00Z
|
||||
**Current Branch**: research/notification-plugin-enhancement
|
||||
**Status**: Ready for implementation phase
|
||||
503
docs/_archive/2025-legacy-doc/UI_REQUIREMENTS.md
Normal file
503
docs/_archive/2025-legacy-doc/UI_REQUIREMENTS.md
Normal file
@@ -0,0 +1,503 @@
|
||||
# Daily Notification Plugin - UI Requirements
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Version**: 1.0.0
|
||||
**Last Updated**: 2025-01-27
|
||||
**Purpose**: Comprehensive UI requirements for integrating the Daily Notification Plugin
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The Daily Notification Plugin requires specific UI components to provide a complete user experience for notification management, configuration, and monitoring. This document outlines all required UI elements, their functionality, and implementation patterns.
|
||||
|
||||
---
|
||||
|
||||
## Core UI Components
|
||||
|
||||
### 1. **Permission Management UI**
|
||||
|
||||
#### **Permission Request Dialog**
|
||||
**Purpose**: Request notification permissions from users
|
||||
|
||||
**Required Elements**:
|
||||
- **Title**: "Enable Daily Notifications"
|
||||
- **Description**: Explain why notifications are needed
|
||||
- **Permission Buttons**:
|
||||
- "Allow Notifications" (primary)
|
||||
- "Not Now" (secondary)
|
||||
- "Never Ask Again" (tertiary)
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface PermissionDialogProps {
|
||||
onAllow: () => Promise<void>;
|
||||
onDeny: () => void;
|
||||
onNever: () => void;
|
||||
platform: 'android' | 'ios' | 'web';
|
||||
}
|
||||
```
|
||||
|
||||
#### **Permission Status Display**
|
||||
**Purpose**: Show current permission status
|
||||
|
||||
**Required Elements**:
|
||||
- **Status Indicator**: Green (granted), Yellow (partial), Red (denied)
|
||||
- **Permission Details**:
|
||||
- Notifications: granted/denied
|
||||
- Background Refresh (iOS): enabled/disabled
|
||||
- Exact Alarms (Android): granted/denied
|
||||
- **Action Buttons**: "Request Permissions", "Open Settings"
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface PermissionStatusProps {
|
||||
status: PermissionStatus;
|
||||
onRequestPermissions: () => Promise<void>;
|
||||
onOpenSettings: () => void;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. **Configuration UI**
|
||||
|
||||
#### **Notification Settings Panel**
|
||||
**Purpose**: Configure notification preferences
|
||||
|
||||
**Required Elements**:
|
||||
- **Enable/Disable Toggle**: Master switch for notifications
|
||||
- **Time Picker**: Select notification time (HH:MM format)
|
||||
- **Content Type Selection**:
|
||||
- Offers (new/changed to me/my projects)
|
||||
- Projects (local/new/changed/favorited)
|
||||
- People (local/new/changed/favorited/contacts)
|
||||
- Items (local/new/changed/favorited)
|
||||
- **Notification Preferences**:
|
||||
- Sound: on/off
|
||||
- Vibration: on/off
|
||||
- Priority: low/normal/high
|
||||
- Badge: on/off
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface NotificationSettingsProps {
|
||||
settings: NotificationSettings;
|
||||
onUpdateSettings: (settings: NotificationSettings) => Promise<void>;
|
||||
onTestNotification: () => Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
#### **Advanced Configuration Panel**
|
||||
**Purpose**: Configure advanced plugin settings
|
||||
|
||||
**Required Elements**:
|
||||
- **TTL Settings**: Content validity duration (1-24 hours)
|
||||
- **Prefetch Lead Time**: Minutes before notification (5-60 minutes)
|
||||
- **Retry Configuration**:
|
||||
- Max retries (1-5)
|
||||
- Retry interval (1-30 minutes)
|
||||
- **Storage Settings**:
|
||||
- Cache size limit
|
||||
- Retention period
|
||||
- **Network Settings**:
|
||||
- Timeout duration
|
||||
- Offline fallback
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface AdvancedSettingsProps {
|
||||
config: ConfigureOptions;
|
||||
onUpdateConfig: (config: ConfigureOptions) => Promise<void>;
|
||||
onResetToDefaults: () => Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. **Status Monitoring UI**
|
||||
|
||||
#### **Notification Status Dashboard**
|
||||
**Purpose**: Display current notification system status
|
||||
|
||||
**Required Elements**:
|
||||
- **Overall Status**: Active/Inactive/Paused
|
||||
- **Next Notification**: Time until next notification
|
||||
- **Last Notification**: When last notification was sent
|
||||
- **Content Cache Status**:
|
||||
- Last fetch time
|
||||
- Cache age
|
||||
- TTL status
|
||||
- **Background Tasks**:
|
||||
- Fetch status
|
||||
- Delivery status
|
||||
- Error count
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface StatusDashboardProps {
|
||||
status: DualScheduleStatus;
|
||||
onRefresh: () => Promise<void>;
|
||||
onViewDetails: () => void;
|
||||
}
|
||||
```
|
||||
|
||||
#### **Performance Metrics Display**
|
||||
**Purpose**: Show system performance and health
|
||||
|
||||
**Required Elements**:
|
||||
- **Success Rate**: Percentage of successful notifications
|
||||
- **Average Response Time**: Time for content fetch
|
||||
- **Error Rate**: Percentage of failed operations
|
||||
- **Battery Impact**: Estimated battery usage
|
||||
- **Network Usage**: Data consumption statistics
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface PerformanceMetricsProps {
|
||||
metrics: PerformanceMetrics;
|
||||
onExportData: () => void;
|
||||
onViewHistory: () => void;
|
||||
}
|
||||
```
|
||||
|
||||
### 4. **Platform-Specific UI**
|
||||
|
||||
#### **Android-Specific Components**
|
||||
|
||||
##### **Battery Optimization Dialog**
|
||||
**Purpose**: Handle Android battery optimization
|
||||
|
||||
**Required Elements**:
|
||||
- **Warning Message**: "Battery optimization may prevent notifications"
|
||||
- **Action Button**: "Open Battery Settings"
|
||||
- **Skip Option**: "Continue Anyway"
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface BatteryOptimizationProps {
|
||||
onOpenSettings: () => Promise<void>;
|
||||
onSkip: () => void;
|
||||
onCheckStatus: () => Promise<BatteryStatus>;
|
||||
}
|
||||
```
|
||||
|
||||
##### **Exact Alarm Permission Dialog**
|
||||
**Purpose**: Request exact alarm permissions
|
||||
|
||||
**Required Elements**:
|
||||
- **Explanation**: Why exact alarms are needed
|
||||
- **Permission Button**: "Grant Exact Alarm Permission"
|
||||
- **Fallback Info**: "Will use approximate timing if denied"
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface ExactAlarmProps {
|
||||
status: ExactAlarmStatus;
|
||||
onRequestPermission: () => Promise<void>;
|
||||
onOpenSettings: () => Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
#### **iOS-Specific Components**
|
||||
|
||||
##### **Background App Refresh Dialog**
|
||||
**Purpose**: Handle iOS background app refresh
|
||||
|
||||
**Required Elements**:
|
||||
- **Explanation**: "Background App Refresh enables content fetching"
|
||||
- **Settings Button**: "Open Settings"
|
||||
- **Fallback Info**: "Will use cached content if disabled"
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface BackgroundRefreshProps {
|
||||
enabled: boolean;
|
||||
onOpenSettings: () => void;
|
||||
onCheckStatus: () => Promise<boolean>;
|
||||
}
|
||||
```
|
||||
|
||||
##### **Rolling Window Management**
|
||||
**Purpose**: Manage iOS rolling window
|
||||
|
||||
**Required Elements**:
|
||||
- **Window Status**: Current window state
|
||||
- **Maintenance Button**: "Maintain Rolling Window"
|
||||
- **Statistics**: Window performance metrics
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface RollingWindowProps {
|
||||
stats: RollingWindowStats;
|
||||
onMaintain: () => Promise<void>;
|
||||
onViewStats: () => void;
|
||||
}
|
||||
```
|
||||
|
||||
#### **Web-Specific Components**
|
||||
|
||||
##### **Service Worker Status**
|
||||
**Purpose**: Monitor web service worker
|
||||
|
||||
**Required Elements**:
|
||||
- **Worker Status**: Active/Inactive/Error
|
||||
- **Registration Status**: Registered/Unregistered
|
||||
- **Background Sync**: Enabled/Disabled
|
||||
- **Push Notifications**: Supported/Not Supported
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface ServiceWorkerProps {
|
||||
status: ServiceWorkerStatus;
|
||||
onRegister: () => Promise<void>;
|
||||
onUnregister: () => Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
### 5. **Error Handling UI**
|
||||
|
||||
#### **Error Display Component**
|
||||
**Purpose**: Show errors and provide recovery options
|
||||
|
||||
**Required Elements**:
|
||||
- **Error Message**: Clear description of the issue
|
||||
- **Error Code**: Technical error identifier
|
||||
- **Recovery Actions**:
|
||||
- "Retry" button
|
||||
- "Reset Configuration" button
|
||||
- "Contact Support" button
|
||||
- **Error History**: List of recent errors
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface ErrorDisplayProps {
|
||||
error: NotificationError;
|
||||
onRetry: () => Promise<void>;
|
||||
onReset: () => Promise<void>;
|
||||
onContactSupport: () => void;
|
||||
}
|
||||
```
|
||||
|
||||
#### **Network Error Dialog**
|
||||
**Purpose**: Handle network connectivity issues
|
||||
|
||||
**Required Elements**:
|
||||
- **Error Message**: "Unable to fetch content"
|
||||
- **Retry Options**:
|
||||
- "Retry Now"
|
||||
- "Retry Later"
|
||||
- "Use Cached Content"
|
||||
- **Offline Mode**: Toggle for offline operation
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface NetworkErrorProps {
|
||||
onRetry: () => Promise<void>;
|
||||
onUseCache: () => void;
|
||||
onEnableOffline: () => void;
|
||||
}
|
||||
```
|
||||
|
||||
### 6. **Testing and Debug UI**
|
||||
|
||||
#### **Test Notification Panel**
|
||||
**Purpose**: Test notification functionality
|
||||
|
||||
**Required Elements**:
|
||||
- **Test Button**: "Send Test Notification"
|
||||
- **Custom Content**: Input for test message
|
||||
- **Test Results**: Success/failure status
|
||||
- **Log Display**: Test execution logs
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface TestPanelProps {
|
||||
onSendTest: (content?: string) => Promise<void>;
|
||||
onClearLogs: () => void;
|
||||
logs: string[];
|
||||
}
|
||||
```
|
||||
|
||||
#### **Debug Information Panel**
|
||||
**Purpose**: Display debug information for troubleshooting
|
||||
|
||||
**Required Elements**:
|
||||
- **System Information**: Platform, version, capabilities
|
||||
- **Configuration**: Current settings
|
||||
- **Status Details**: Detailed system status
|
||||
- **Log Export**: Export logs for support
|
||||
|
||||
**Implementation**:
|
||||
```typescript
|
||||
interface DebugPanelProps {
|
||||
debugInfo: DebugInfo;
|
||||
onExportLogs: () => void;
|
||||
onClearCache: () => Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## UI Layout Patterns
|
||||
|
||||
### 1. **Settings Page Layout**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Notification Settings │
|
||||
├─────────────────────────────────────┤
|
||||
│ [Enable Notifications] Toggle │
|
||||
│ │
|
||||
│ Time: [09:00] [AM/PM] │
|
||||
│ │
|
||||
│ Content Types: │
|
||||
│ ☑ Offers │
|
||||
│ ☑ Projects │
|
||||
│ ☑ People │
|
||||
│ ☑ Items │
|
||||
│ │
|
||||
│ Preferences: │
|
||||
│ Sound: [On] Vibration: [On] │
|
||||
│ Priority: [Normal] Badge: [On] │
|
||||
│ │
|
||||
│ [Test Notification] [Save Settings] │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2. **Status Dashboard Layout**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Notification Status │
|
||||
├─────────────────────────────────────┤
|
||||
│ Status: ● Active │
|
||||
│ Next: 2 hours 15 minutes │
|
||||
│ Last: Yesterday 9:00 AM │
|
||||
│ │
|
||||
│ Content Cache: │
|
||||
│ Last Fetch: 1 hour ago │
|
||||
│ Cache Age: Fresh │
|
||||
│ TTL: Valid for 23 hours │
|
||||
│ │
|
||||
│ Background Tasks: │
|
||||
│ Fetch: ● Success │
|
||||
│ Delivery: ● Success │
|
||||
│ Errors: 0 │
|
||||
│ │
|
||||
│ [Refresh] [View Details] │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3. **Permission Request Layout**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Enable Daily Notifications │
|
||||
├─────────────────────────────────────┤
|
||||
│ │
|
||||
│ Get notified about new offers, │
|
||||
│ projects, people, and items in │
|
||||
│ your TimeSafari community. │
|
||||
│ │
|
||||
│ • New offers directed to you │
|
||||
│ • Changes to your projects │
|
||||
│ • Updates from favorited people │
|
||||
│ • New items of interest │
|
||||
│ │
|
||||
│ [Allow Notifications] │
|
||||
│ [Not Now] [Never Ask Again] │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation Guidelines
|
||||
|
||||
### 1. **Responsive Design**
|
||||
- **Mobile First**: Design for mobile, scale up
|
||||
- **Touch Friendly**: Minimum 44px touch targets
|
||||
- **Accessibility**: WCAG 2.1 AA compliance
|
||||
- **Platform Native**: Use platform-specific design patterns
|
||||
|
||||
### 2. **State Management**
|
||||
- **Loading States**: Show loading indicators
|
||||
- **Error States**: Clear error messages
|
||||
- **Success States**: Confirmation feedback
|
||||
- **Empty States**: Helpful empty state messages
|
||||
|
||||
### 3. **User Experience**
|
||||
- **Progressive Disclosure**: Show advanced options when needed
|
||||
- **Contextual Help**: Tooltips and help text
|
||||
- **Confirmation Dialogs**: For destructive actions
|
||||
- **Undo Functionality**: Where appropriate
|
||||
|
||||
### 4. **Performance**
|
||||
- **Lazy Loading**: Load components when needed
|
||||
- **Debounced Inputs**: Prevent excessive API calls
|
||||
- **Optimistic Updates**: Update UI immediately
|
||||
- **Error Boundaries**: Graceful error handling
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Considerations
|
||||
|
||||
### **Android**
|
||||
- **Material Design**: Follow Material Design guidelines
|
||||
- **Battery Optimization**: Handle battery optimization prompts
|
||||
- **Exact Alarms**: Request exact alarm permissions
|
||||
- **WorkManager**: Show background task status
|
||||
|
||||
### **iOS**
|
||||
- **Human Interface Guidelines**: Follow iOS design patterns
|
||||
- **Background App Refresh**: Handle background refresh settings
|
||||
- **Rolling Window**: Show rolling window management
|
||||
- **BGTaskScheduler**: Display background task status
|
||||
|
||||
### **Web**
|
||||
- **Progressive Web App**: PWA-compatible design
|
||||
- **Service Worker**: Show service worker status
|
||||
- **Push Notifications**: Handle push notification permissions
|
||||
- **Offline Support**: Offline functionality indicators
|
||||
|
||||
---
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
### **Unit Tests**
|
||||
- Component rendering
|
||||
- User interactions
|
||||
- State management
|
||||
- Error handling
|
||||
|
||||
### **Integration Tests**
|
||||
- API integration
|
||||
- Permission flows
|
||||
- Configuration persistence
|
||||
- Cross-platform compatibility
|
||||
|
||||
### **User Testing**
|
||||
- Usability testing
|
||||
- Accessibility testing
|
||||
- Performance testing
|
||||
- Cross-device testing
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The Daily Notification Plugin requires a comprehensive UI that handles:
|
||||
|
||||
1. **Permission Management**: Request and display permission status
|
||||
2. **Configuration**: Settings and preferences management
|
||||
3. **Status Monitoring**: Real-time system status and performance
|
||||
4. **Platform-Specific Features**: Android, iOS, and Web-specific components
|
||||
5. **Error Handling**: User-friendly error messages and recovery
|
||||
6. **Testing and Debug**: Tools for testing and troubleshooting
|
||||
|
||||
The UI should be responsive, accessible, and follow platform-specific design guidelines while providing a consistent user experience across all platforms.
|
||||
|
||||
---
|
||||
|
||||
**Next Steps**:
|
||||
1. Implement core UI components
|
||||
2. Add platform-specific features
|
||||
3. Integrate with plugin API
|
||||
4. Test across all platforms
|
||||
5. Optimize for performance and accessibility
|
||||
@@ -0,0 +1,229 @@
|
||||
# Daily Notification Plugin — Implementation Directive (v2)
|
||||
|
||||
## Current Status: Phase 1 Complete ✅
|
||||
|
||||
**API Design Phase:** ✅ **COMPLETE** - All TypeScript interfaces defined and tested
|
||||
**Next Phase:** Platform-specific implementation (Android → iOS → Web)
|
||||
|
||||
## Objectives
|
||||
|
||||
- ✅ **COMPLETED:** Implement **dual scheduling** (content fetch + user notification) with **backward compatibility** for existing `schedule*` paths.
|
||||
- ✅ **COMPLETED:** Add a **callback registry** (API/DB/reporting) with robust error handling + logging.
|
||||
- 🔄 **IN PROGRESS:** Preserve/extend current **native-first**, **TTL-at-fire**, **rolling window**, and **shared SQLite** guarantees.
|
||||
|
||||
## API Surface (TypeScript) ✅ COMPLETE
|
||||
>
|
||||
> ✅ **IMPLEMENTED:** Public API (TS) supports dual scheduling + callbacks while keeping current usage working.
|
||||
|
||||
- ✅ **COMPLETED:** Existing `configure(...)` and `scheduleDailyNotification(...)` preserved as backward-compatible wrappers
|
||||
- ✅ **COMPLETED:** All new dual scheduling methods implemented and tested
|
||||
- ✅ **IMPLEMENTED:** All methods defined in `src/definitions.ts`:
|
||||
|
||||
```ts
|
||||
// Scheduling ✅ COMPLETE
|
||||
scheduleContentFetch(cfg: ContentFetchConfig): Promise<void>;
|
||||
scheduleUserNotification(cfg: UserNotificationConfig): Promise<void>;
|
||||
scheduleDualNotification(cfg: DualScheduleConfiguration): Promise<void>;
|
||||
|
||||
// Status & Management ✅ COMPLETE
|
||||
getDualScheduleStatus(): Promise<DualScheduleStatus>;
|
||||
updateDualScheduleConfig(cfg: DualScheduleConfiguration): Promise<void>;
|
||||
cancelDualSchedule(): Promise<void>;
|
||||
|
||||
// Content Cache ✅ COMPLETE
|
||||
getContentCache(): Promise<ContentCache>;
|
||||
clearContentCache(): Promise<void>;
|
||||
getContentHistory(): Promise<ContentHistory[]>;
|
||||
|
||||
// Callbacks ✅ COMPLETE
|
||||
registerCallback(id: string, cb: CallbackFunction): Promise<void>;
|
||||
unregisterCallback(id: string): Promise<void>;
|
||||
getRegisteredCallbacks(): Promise<CallbackRegistry>;
|
||||
```
|
||||
|
||||
- ✅ **IMPLEMENTED:** All types defined: `ContentFetchConfig`, `UserNotificationConfig`, `DualScheduleConfiguration`, `DualScheduleStatus`, `CallbackFunction`, `CallbackRegistry`
|
||||
|
||||
## Storage & TTL Rules 🔄 NEXT PHASE
|
||||
>
|
||||
> **PENDING:** Leverage **Shared SQLite (WAL)** design and **TTL-at-fire** invariants.
|
||||
|
||||
**Status:** ❌ **NOT IMPLEMENTED** - Phase 2 requirement
|
||||
|
||||
## Platform Implementations (Phase Order) 🔄 NEXT PHASE
|
||||
>
|
||||
> **PENDING:** Follow the plan: Android → iOS → Web, with parity stubs.
|
||||
|
||||
**Status:** ❌ **NOT IMPLEMENTED** - Only web mock implementations exist
|
||||
|
||||
**Required Implementation:**
|
||||
|
||||
1. **Android** ❌ **NOT IMPLEMENTED**
|
||||
- Use **WorkManager** for fetch jobs (constraints: `NETWORK_CONNECTED`, backoff) and **AlarmManager**/**Exact Alarms** for user-visible notifications (respect permissions in `AndroidManifest`).
|
||||
- Implement **BOOT_COMPLETED** rescheduling and battery-opt exemptions prompts.
|
||||
- Handler flow: `FetchWork → SQLite upsert → TTL check at fire → NotificationManager`.
|
||||
|
||||
2. **iOS** ❌ **NOT IMPLEMENTED**
|
||||
- **BGTaskScheduler** (fetch) + **UNUserNotificationCenter** (notify) with background fetch/refresh. Ensure **silent push optionality** off by default.
|
||||
|
||||
3. **Web** ✅ **MOCK IMPLEMENTED**
|
||||
- **Service Worker** + **Push API** + **IndexedDB** (mirror schema) for parity; when Push is unavailable, fall back to **periodic Sync** or foreground timers with degraded guarantees.
|
||||
|
||||
## Callback Registry ⚠️ PARTIAL IMPLEMENTATION
|
||||
>
|
||||
> **PARTIAL:** Uniform callback lifecycle usable from any platform.
|
||||
|
||||
**Status:** ✅ **INTERFACE DEFINED** - Implementation pending
|
||||
|
||||
**Required Implementation:**
|
||||
|
||||
- **Kinds**: `http`, `local` (in-process hook), `queue` (future).
|
||||
- **When fired**:
|
||||
- `onFetchStart/Success/Failure`
|
||||
- `onNotifyStart/Delivered/SkippedTTL/Failure`
|
||||
- **Delivery semantics**:
|
||||
- Exactly-once attempt per event; retries via exponential backoff persisted in `history`.
|
||||
- Back-pressure guard: bounded concurrent callback executions + circuit breaker per callback id.
|
||||
- **Security**:
|
||||
- Never log secrets; redact headers/body in `history.diag_json`.
|
||||
- Respect "secure defaults" (least privilege, HTTPS-only callbacks unless explicitly allowed for dev).
|
||||
|
||||
## Backward Compatibility ✅ COMPLETE
|
||||
>
|
||||
> ✅ **IMPLEMENTED:** Current DX intact while migrating.
|
||||
|
||||
**Status:** ✅ **FULLY IMPLEMENTED** - All existing methods preserved
|
||||
|
||||
**Implementation Details:**
|
||||
|
||||
- ✅ `scheduleDailyNotification(...)` preserved as backward-compatible wrapper
|
||||
- ✅ All existing methods maintained in `src/definitions.ts` lines 289-300
|
||||
- ✅ No breaking changes to current API surface
|
||||
|
||||
## Observability & Diagnostics 🔄 NEXT PHASE
|
||||
>
|
||||
> **PENDING:** Structured logging and health monitoring
|
||||
|
||||
**Status:** ❌ **NOT IMPLEMENTED** - Phase 2 requirement
|
||||
|
||||
**Required Implementation:**
|
||||
|
||||
- **Structured logs** at INFO/WARN/ERROR with event codes: `DNP-FETCH-*`, `DNP-NOTIFY-*`, `DNP-CB-*`.
|
||||
- **Health**: `getDualScheduleStatus()` returns next run times, last outcomes, queue depth, and stale-armed flag.
|
||||
- **History compaction** job: keep 30 days by default; configurable via `configure(...)`.
|
||||
|
||||
## Testing Strategy ✅ COMPLETE
|
||||
>
|
||||
> ✅ **IMPLEMENTED:** Jest test suite with comprehensive coverage
|
||||
|
||||
**Status:** ✅ **FULLY IMPLEMENTED** - 58 tests passing
|
||||
|
||||
**Current Implementation:**
|
||||
|
||||
- ✅ **Unit Tests**: Pure TS for schedulers, TTL, callback backoff (Jest + jsdom env)
|
||||
- ✅ **Test Coverage**: 58 tests across 4 test files
|
||||
- ✅ **Mock Implementations**: Complete plugin interface mocked
|
||||
- ✅ **Edge Cases**: Comprehensive error handling and validation tests
|
||||
|
||||
**Pending Implementation:**
|
||||
|
||||
- **Contract tests**: Golden tests for DB schema migrations and TTL edge cases (past/future timezones, DST).
|
||||
- **Android Instrumentation**: Verify WorkManager chains and alarm delivery under doze/idle.
|
||||
- **Web SW tests**: Use headless browser to assert cache + postMessage flows.
|
||||
|
||||
## Performance & Battery 🔄 NEXT PHASE
|
||||
>
|
||||
> **PENDING:** Performance optimization and battery management
|
||||
|
||||
**Status:** ❌ **NOT IMPLEMENTED** - Phase 2 requirement
|
||||
|
||||
**Required Implementation:**
|
||||
|
||||
- **Jitter** fetches by ±5m default; coalesce adjacent fetch windows.
|
||||
- **Cap** retries (e.g., 5 with backoff up to 1h).
|
||||
- **Guard** network with `ACCESS_NETWORK_STATE` to avoid wakeups when offline.
|
||||
|
||||
## Security & Permissions 🔄 NEXT PHASE
|
||||
>
|
||||
> **PENDING:** Security validation and permission management
|
||||
|
||||
**Status:** ❌ **NOT IMPLEMENTED** - Phase 2 requirement
|
||||
|
||||
**Required Implementation:**
|
||||
|
||||
- Keep current permission set; enforce runtime gating for POST_NOTIFICATIONS and Exact Alarm rationale UI.
|
||||
- Validate callback targets; block non-https by default unless `allowInsecureDev` is set (dev-only).
|
||||
|
||||
## Versioning & Build ✅ COMPLETE
|
||||
>
|
||||
> ✅ **IMPLEMENTED:** Build system and versioning ready
|
||||
|
||||
**Status:** ✅ **FULLY IMPLEMENTED** - All build tools working
|
||||
|
||||
**Current Implementation:**
|
||||
|
||||
- ✅ **Build System**: `npm run build`, `npm test`, `markdown:check`, `lint`, `format` all working
|
||||
- ✅ **TypeScript Compilation**: Zero errors, all interfaces properly typed
|
||||
- ✅ **Test Suite**: 58 tests passing with comprehensive coverage
|
||||
- ✅ **Code Quality**: ESLint, Prettier, and markdownlint configured
|
||||
|
||||
**Pending Implementation:**
|
||||
|
||||
- **Minor bump** when releasing the new API (`1.1.0`) and mark compat methods as "soft-deprecated" in docs.
|
||||
|
||||
## Documentation Tasks 🔄 NEXT PHASE
|
||||
>
|
||||
> **PENDING:** API documentation and migration guides
|
||||
|
||||
**Status:** ❌ **NOT IMPLEMENTED** - Phase 2 requirement
|
||||
|
||||
**Required Implementation:**
|
||||
|
||||
- Update **API Reference** with new methods + types; keep a "Migration from `scheduleDailyNotification`" section.
|
||||
- Add **Enterprise callbacks** page with examples for API, DB, and reporting webhooks.
|
||||
- Extend **Implementation Roadmap** with Phase 2/3 milestones done/remaining.
|
||||
|
||||
## Acceptance Checklist
|
||||
|
||||
### ✅ Phase 1 Complete (API Design)
|
||||
|
||||
- [x] **API Surface**: All dual scheduling methods defined and typed
|
||||
- [x] **Type Definitions**: Complete TypeScript interfaces implemented
|
||||
- [x] **Backward Compatibility**: All existing methods preserved
|
||||
- [x] **Test Coverage**: 58 tests passing with comprehensive scenarios
|
||||
- [x] **Build System**: All build tools working (TypeScript, Jest, ESLint, Prettier)
|
||||
|
||||
### 🔄 Phase 2 Pending (Platform Implementation)
|
||||
|
||||
- [ ] **Android Implementation**: WorkManager + AlarmManager + SQLite
|
||||
- [ ] **iOS Implementation**: BGTaskScheduler + UNUserNotificationCenter
|
||||
- [ ] **Web Enhancement**: Service Worker + Push API + IndexedDB
|
||||
- [ ] **Storage System**: SQLite schema with TTL rules
|
||||
- [ ] **Callback Registry**: Full implementation with retries + redaction
|
||||
- [ ] **TTL-at-fire**: Rolling window behaviors preserved
|
||||
- [ ] **Observability**: Structured logging and health monitoring
|
||||
- [ ] **Security**: Permission validation and callback security
|
||||
- [ ] **Performance**: Battery optimization and network guards
|
||||
- [ ] **Documentation**: API reference and migration guides
|
||||
|
||||
## Nice-to-Have (Post-Merge)
|
||||
|
||||
- `onPermissionChanged` callback event stream.
|
||||
- In-plugin **metrics hooks** (success rates, latency) for dashboards.
|
||||
- Web: Progressive enhancement for **Periodic Background Sync** when available.
|
||||
|
||||
---
|
||||
|
||||
## Summary for Model Comparison
|
||||
|
||||
**Current Status:** Phase 1 Complete ✅ - Ready for Platform Implementation
|
||||
|
||||
**Key Files for Model Review:**
|
||||
|
||||
1. **`src/definitions.ts`** - Complete TypeScript interface definitions (321 lines)
|
||||
2. **`src/web.ts`** - Mock implementation showing API usage (230 lines)
|
||||
3. **`tests/`** - Comprehensive test suite (58 tests passing)
|
||||
4. **`doc/RESEARCH_COMPLETE.md`** - Consolidated research and requirements (158 lines)
|
||||
|
||||
**Implementation Consistency:** 85% - Perfect API alignment, pending platform-specific implementation
|
||||
|
||||
**Next Phase:** Android → iOS → Web platform implementations with SQLite storage and callback registry
|
||||
@@ -0,0 +1,255 @@
|
||||
|
||||
# Daily Notification Plugin — Phase 2 Recommendations (v3)
|
||||
|
||||
> This directive assumes Phase 1 (API surface + tests) is complete and aligns with the current codebase. It focuses on **platform implementations**, **storage/TTL**, **callbacks**, **observability**, and **security**.
|
||||
|
||||
---
|
||||
|
||||
## 1) Milestones & Order of Work
|
||||
|
||||
1. **Android Core (Week 1–2)**
|
||||
- Fetch: WorkManager (`Constraints: NETWORK_CONNECTED`, backoff: exponential)
|
||||
- Notify: AlarmManager (or Exact alarms if permitted), NotificationManager
|
||||
- Boot resilience: `RECEIVE_BOOT_COMPLETED` receiver reschedules jobs
|
||||
- Shared SQLite schema + DAO layer (Room recommended)
|
||||
2. **Callback Registry (Week 2)** — shared TS interface + native bridges
|
||||
3. **Observability & Health (Week 2–3)** — event codes, status endpoints, history compaction
|
||||
4. **iOS Parity (Week 3–4)** — BGTaskScheduler + UNUserNotificationCenter
|
||||
5. **Web SW/Push (Week 4)** — SW events + IndexedDB (mirror schema), periodic sync fallback
|
||||
6. **Docs & Examples (Week 4)** — migration, enterprise callbacks, health dashboards
|
||||
|
||||
---
|
||||
|
||||
## 2) Storage & TTL — Concrete Schema
|
||||
|
||||
> Keep **TTL-at-fire** invariant and **rolling window armed**. Use normalized tables and a minimal DAO.
|
||||
|
||||
### SQLite (DDL)
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS content_cache (
|
||||
id TEXT PRIMARY KEY,
|
||||
fetched_at INTEGER NOT NULL, -- epoch ms
|
||||
ttl_seconds INTEGER NOT NULL,
|
||||
payload BLOB NOT NULL,
|
||||
meta TEXT
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS schedules (
|
||||
id TEXT PRIMARY KEY,
|
||||
kind TEXT NOT NULL CHECK (kind IN ('fetch','notify')),
|
||||
cron TEXT, -- optional: cron expression
|
||||
clock_time TEXT, -- optional: HH:mm
|
||||
enabled INTEGER NOT NULL DEFAULT 1,
|
||||
last_run_at INTEGER,
|
||||
next_run_at INTEGER,
|
||||
jitter_ms INTEGER DEFAULT 0,
|
||||
backoff_policy TEXT DEFAULT 'exp',
|
||||
state_json TEXT
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS callbacks (
|
||||
id TEXT PRIMARY KEY,
|
||||
kind TEXT NOT NULL CHECK (kind IN ('http','local','queue')),
|
||||
target TEXT NOT NULL, -- url_or_local
|
||||
headers_json TEXT,
|
||||
enabled INTEGER NOT NULL DEFAULT 1,
|
||||
created_at INTEGER NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE IF NOT EXISTS history (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
ref_id TEXT, -- content or schedule id
|
||||
kind TEXT NOT NULL, -- fetch/notify/callback
|
||||
occurred_at INTEGER NOT NULL,
|
||||
duration_ms INTEGER,
|
||||
outcome TEXT NOT NULL, -- success|failure|skipped_ttl|circuit_open
|
||||
diag_json TEXT
|
||||
);
|
||||
|
||||
CREATE INDEX IF NOT EXISTS idx_history_time ON history(occurred_at);
|
||||
CREATE INDEX IF NOT EXISTS idx_cache_time ON content_cache(fetched_at);
|
||||
```
|
||||
|
||||
### TTL-at-fire Rule
|
||||
|
||||
- On notification fire: `if (now > fetched_at + ttl_seconds) -> skip (record outcome=skipped_ttl)`.
|
||||
- Maintain a **prep guarantee**: ensure a fresh cache entry for the next window even after failures (schedule a fetch on next window).
|
||||
|
||||
---
|
||||
|
||||
## 3) Android Implementation Sketch
|
||||
|
||||
### WorkManager for Fetch
|
||||
|
||||
```kotlin
|
||||
class FetchWorker(
|
||||
appContext: Context,
|
||||
workerParams: WorkerParameters
|
||||
) : CoroutineWorker(appContext, workerParams) {
|
||||
|
||||
override suspend fun doWork(): Result = withContext(Dispatchers.IO) {
|
||||
val start = SystemClock.elapsedRealtime()
|
||||
try {
|
||||
val payload = fetchContent() // http call / local generator
|
||||
dao.upsertCache(ContentCache(...))
|
||||
logEvent("DNP-FETCH-SUCCESS", start)
|
||||
Result.success()
|
||||
} catch (e: IOException) {
|
||||
logEvent("DNP-FETCH-FAILURE", start, e)
|
||||
Result.retry()
|
||||
} catch (e: Throwable) {
|
||||
logEvent("DNP-FETCH-FAILURE", start, e)
|
||||
Result.failure()
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Constraints**: `Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build()`
|
||||
**Backoff**: `setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 30, TimeUnit.SECONDS)`
|
||||
|
||||
### AlarmManager for Notify
|
||||
|
||||
```kotlin
|
||||
fun scheduleExactNotification(context: Context, triggerAtMillis: Long) {
|
||||
val alarmMgr = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
|
||||
val pi = PendingIntent.getBroadcast(context, REQ_ID, Intent(context, NotifyReceiver::class.java), FLAG_IMMUTABLE)
|
||||
alarmMgr.setExactAndAllowWhileIdle(AlarmManager.RTC_WAKEUP, triggerAtMillis, pi)
|
||||
}
|
||||
|
||||
class NotifyReceiver : BroadcastReceiver() {
|
||||
override fun onReceive(ctx: Context, intent: Intent?) {
|
||||
val cache = dao.latestCache()
|
||||
if (cache == null) return
|
||||
if (System.currentTimeMillis() > cache.fetched_at + cache.ttl_seconds * 1000) {
|
||||
recordHistory("notify", "skipped_ttl"); return
|
||||
}
|
||||
showNotification(ctx, cache)
|
||||
recordHistory("notify", "success")
|
||||
fireCallbacks("onNotifyDelivered")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Boot Reschedule
|
||||
|
||||
- Manifest: `RECEIVE_BOOT_COMPLETED`
|
||||
- On boot: read `schedules.enabled=1` and re-schedule WorkManager/AlarmManager
|
||||
|
||||
---
|
||||
|
||||
## 4) Callback Registry — Minimal Viable Implementation
|
||||
|
||||
### TS Core
|
||||
|
||||
```ts
|
||||
export type CallbackKind = 'http' | 'local' | 'queue';
|
||||
|
||||
export interface CallbackEvent {
|
||||
id: string;
|
||||
at: number;
|
||||
type: 'onFetchStart' | 'onFetchSuccess' | 'onFetchFailure' |
|
||||
'onNotifyStart' | 'onNotifyDelivered' | 'onNotifySkippedTTL' | 'onNotifyFailure';
|
||||
payload?: unknown;
|
||||
}
|
||||
|
||||
export type CallbackFunction = (e: CallbackEvent) => Promise<void> | void;
|
||||
```
|
||||
|
||||
### Delivery Semantics
|
||||
|
||||
- **Exactly-once attempt per event**, persisted `history` row
|
||||
- **Retry**: exponential backoff with cap; open **circuit** per `callback.id` on repeated failures
|
||||
- **Redaction**: apply header/body redaction before persisting `diag_json`
|
||||
|
||||
### HTTP Example
|
||||
|
||||
```ts
|
||||
async function deliverHttpCallback(cb: CallbackRecord, event: CallbackEvent) {
|
||||
const start = performance.now();
|
||||
try {
|
||||
const res = await fetch(cb.target, {
|
||||
method: 'POST',
|
||||
headers: { 'content-type': 'application/json', ...(cb.headers ?? {}) },
|
||||
body: JSON.stringify(event),
|
||||
});
|
||||
recordHistory(cb.id, 'callback', 'success', start, { status: res.status });
|
||||
} catch (err) {
|
||||
scheduleRetry(cb.id, event); // capped exponential
|
||||
recordHistory(cb.id, 'callback', 'failure', start, { error: String(err) });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5) Observability & Health
|
||||
|
||||
- **Event Codes**: `DNP-FETCH-*`, `DNP-NOTIFY-*`, `DNP-CB-*`
|
||||
- **Health API** (TS): `getDualScheduleStatus()` returns `{ nextRuns, lastOutcomes, cacheAgeMs, staleArmed, queueDepth }`
|
||||
- **Compaction**: nightly job to prune `history` > 30 days
|
||||
- **Device Debug**: Android broadcast to dump status to logcat for field diagnostics
|
||||
|
||||
---
|
||||
|
||||
## 6) Security & Permissions
|
||||
|
||||
- Default **HTTPS-only** callbacks, opt-out via explicit dev flag
|
||||
- Android: runtime gate for `POST_NOTIFICATIONS`; show rationale UI for exact alarms (if requested)
|
||||
- **PII/Secrets**: redact before persistence; never log tokens
|
||||
- **Input Validation**: sanitize HTTP callback targets; enforce allowlist pattern (e.g., `https://*.yourdomain.tld` in prod)
|
||||
|
||||
---
|
||||
|
||||
## 7) Performance & Battery
|
||||
|
||||
- **±Jitter (5m)** for fetch; coalesce same-minute schedules
|
||||
- **Retry Caps**: ≤ 5 attempts, upper bound 60 min backoff
|
||||
- **Network Guards**: avoid waking when offline; use WorkManager constraints to defer
|
||||
- **Back-Pressure**: cap concurrent callbacks; open circuit on sustained failures
|
||||
|
||||
---
|
||||
|
||||
## 8) Tests You Can Add Now
|
||||
|
||||
- **TTL Edge Cases**: past/future timezones, DST cutovers
|
||||
- **Retry & Circuit**: force network failures, assert capped retries + circuit open
|
||||
- **Boot Reschedule**: instrumentation test to simulate reboot and check re-arming
|
||||
- **SW/IndexedDB**: headless test verifying cache write/read + TTL skip
|
||||
|
||||
---
|
||||
|
||||
## 9) Documentation Tasks
|
||||
|
||||
- API reference for new **health** and **callback** semantics
|
||||
- Platform guides: Android exact alarm notes, iOS background limits, Web SW lifecycle
|
||||
- Migration note: why `scheduleDualNotification` is preferred; compat wrappers policy
|
||||
- “Runbook” for QA: how to toggle jitter/backoff; how to inspect `history`
|
||||
|
||||
---
|
||||
|
||||
## 10) Acceptance Criteria (Phase 2)
|
||||
|
||||
- Android end-to-end demo: fetch → cache → TTL check → notify → callback(s) → history
|
||||
- Health endpoint returns non-null next run, recent outcomes, and cache age
|
||||
- iOS parity path demonstrated on simulator (background fetch + local notif)
|
||||
- Web SW functional on Chromium + Firefox with IndexedDB persistence
|
||||
- Logs show structured `DNP-*` events; compaction reduces history size as configured
|
||||
- Docs updated; examples build and run
|
||||
|
||||
---
|
||||
|
||||
## 11) Risks & Mitigations
|
||||
|
||||
- **Doze/Idle drops alarms** → prefer WorkManager + exact when allowed; add tolerance window
|
||||
- **iOS background unpredictability** → encourage scheduled “fetch windows”; document silent-push optionality
|
||||
- **Web Push unavailable** → periodic sync + foreground fallback; degrade gracefully
|
||||
- **Callback storms** → batch events where possible; per-callback rate limit
|
||||
|
||||
---
|
||||
|
||||
## 12) Versioning
|
||||
|
||||
- Release as `1.1.0` when Android path merges; mark wrappers as **soft-deprecated** in docs
|
||||
- Keep zero-padded doc versions in `/doc/` and release notes linking to them
|
||||
File diff suppressed because it is too large
Load Diff
531
docs/_archive/2025-legacy-doc/implementation-roadmap.md
Normal file
531
docs/_archive/2025-legacy-doc/implementation-roadmap.md
Normal file
@@ -0,0 +1,531 @@
|
||||
# Daily Notification Plugin - Implementation Roadmap
|
||||
|
||||
**📝 SANITY CHECK IMPROVEMENTS APPLIED:** This document has been updated to clarify current implementation status and distinguish between existing infrastructure and planned T–lead logic.
|
||||
|
||||
**Status:** Ready for implementation
|
||||
**Date:** 2025-01-27
|
||||
**Author:** Matthew Raymer
|
||||
**Assessment Date:** 2025-01-27
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document outlines the implementation roadmap to bring the current Daily Notification Plugin (65% complete) to full compliance with the Native-First Notification System specification. The implementation is organized into three phases, with Phase 1 containing critical infrastructure components required for core functionality.
|
||||
|
||||
### Current State Assessment
|
||||
|
||||
- **Overall Completion:** 65% of specification requirements
|
||||
- **Critical Gaps:** SQLite database sharing, TTL-at-fire enforcement, rolling window safety
|
||||
- **Current Storage:** SharedPreferences (Android) / UserDefaults (iOS) + in-memory cache
|
||||
- **Background Infrastructure:** Basic WorkManager (Android) exists, but lacks T–lead logic
|
||||
- **Critical Path:** Data persistence → Freshness enforcement → Platform completion
|
||||
|
||||
---
|
||||
|
||||
## Current Implementation Status Clarification
|
||||
|
||||
### Background Fetch Infrastructure
|
||||
|
||||
**Current State:** Basic infrastructure exists but lacks T–lead logic
|
||||
|
||||
- **Android:** `DailyNotificationFetchWorker.java` (WorkManager) exists
|
||||
- **Android:** `DailyNotificationFetcher.java` with scheduling logic exists
|
||||
- **Missing:** T–lead calculation, TTL enforcement, ETag support
|
||||
- **Status:** Infrastructure ready, T–lead logic needs implementation
|
||||
|
||||
### iOS Implementation Status
|
||||
|
||||
**Current State:** Basic plugin structure with power management
|
||||
|
||||
- **Implemented:** Plugin skeleton, power management, UserDefaults storage
|
||||
- **Missing:** BGTaskScheduler, background tasks, T–lead prefetch
|
||||
- **Status:** Foundation exists, background execution needs implementation
|
||||
|
||||
---
|
||||
|
||||
**Gate:** No further freshness or scheduling work merges to main until **shared SQLite** (see Glossary → Shared DB) is in place and reading/writing under **WAL** (see Glossary → WAL), with UI hot-read verified.
|
||||
|
||||
**Dependencies:** None
|
||||
|
||||
### 1.1 SQLite Database Sharing Implementation
|
||||
|
||||
**Priority:** CRITICAL
|
||||
|
||||
#### Requirements
|
||||
|
||||
- Migrate from SharedPreferences/UserDefaults to shared SQLite database (see Glossary → Shared DB)
|
||||
- WAL mode configuration for concurrent access (see Glossary → WAL)
|
||||
- Schema version checking and compatibility validation (see Glossary → PRAGMA user_version)
|
||||
- Required tables: `notif_contents`, `notif_deliveries`, `notif_config`
|
||||
- **Migration Strategy:** Gradual migration from current tiered storage (see Glossary → Tiered Storage)
|
||||
|
||||
#### Implementation Tasks
|
||||
|
||||
- [ ] **Migration from Current Storage**
|
||||
- Create migration utilities from SharedPreferences to SQLite
|
||||
- Implement data migration from UserDefaults to SQLite (iOS)
|
||||
- Add backward compatibility during transition
|
||||
- Preserve existing notification data during migration
|
||||
|
||||
- [ ] **SQLite Setup (Android)**
|
||||
- Create `DailyNotificationDatabase.java` with WAL mode (see Glossary → WAL)
|
||||
- Implement schema version checking (`PRAGMA user_version`) (see Glossary → PRAGMA user_version)
|
||||
- Add database connection management with proper error handling
|
||||
|
||||
- [ ] **Database Configuration**
|
||||
- Add `dbPath: string` to `ConfigureOptions` interface
|
||||
- Implement database path resolution (absolute vs platform alias)
|
||||
- Add `storage: 'shared'` configuration option
|
||||
- Extend existing `NotificationOptions` with database settings
|
||||
|
||||
- [ ] **Database Schema**
|
||||
|
||||
```sql
|
||||
-- notif_contents: keep history, newest-first reads
|
||||
CREATE TABLE IF NOT EXISTS notif_contents(
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
slot_id TEXT NOT NULL,
|
||||
payload_json TEXT NOT NULL,
|
||||
fetched_at INTEGER NOT NULL, -- epoch ms
|
||||
etag TEXT,
|
||||
UNIQUE(slot_id, fetched_at)
|
||||
);
|
||||
CREATE INDEX IF NOT EXISTS notif_idx_contents_slot_time
|
||||
ON notif_contents(slot_id, fetched_at DESC);
|
||||
|
||||
-- notif_deliveries: track many deliveries per slot/time
|
||||
CREATE TABLE IF NOT EXISTS notif_deliveries(
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
slot_id TEXT NOT NULL,
|
||||
fire_at INTEGER NOT NULL, -- intended fire time (epoch ms)
|
||||
delivered_at INTEGER, -- when actually shown (epoch ms)
|
||||
status TEXT NOT NULL DEFAULT 'scheduled', -- scheduled|shown|error|canceled
|
||||
error_code TEXT, error_message TEXT
|
||||
);
|
||||
|
||||
-- notif_config: generic configuration KV
|
||||
CREATE TABLE IF NOT EXISTS notif_config(
|
||||
k TEXT PRIMARY KEY,
|
||||
v TEXT NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
- [ ] App and plugin can open the same SQLite file
|
||||
- [ ] WAL mode enables concurrent reads during writes
|
||||
- [ ] Schema version checking prevents compatibility issues
|
||||
- [ ] All required tables exist and are accessible
|
||||
- [ ] Shared DB visibility: UI reads updated rows immediately
|
||||
- [ ] WAL overlap shows no UI blocking during background writes
|
||||
- [ ] UI can read a row written by a background job **within the same second** (WAL hot-read)
|
||||
- [ ] Plugin refuses to write if `PRAGMA user_version` < expected
|
||||
|
||||
### 1.2 TTL-at-Fire Enforcement
|
||||
|
||||
**Priority:** CRITICAL
|
||||
|
||||
#### Requirements
|
||||
|
||||
- Skip arming notifications if `(T - fetchedAt) > ttlSeconds` (see Glossary → TTL)
|
||||
- Validate freshness before scheduling
|
||||
- Log TTL violations for debugging
|
||||
- **Current State:** Not implemented - needs to be added to existing scheduling logic
|
||||
- **Shared DB (single file):** App owns migrations (`PRAGMA user_version`) (see Glossary → PRAGMA user_version); plugin opens the **same path**; enable `journal_mode=WAL` (see Glossary → WAL), `synchronous=NORMAL`, `busy_timeout=5000`, `foreign_keys=ON`; background writes are **short & serialized**.
|
||||
|
||||
#### Implementation Tasks
|
||||
|
||||
- [ ] **TTL Validation Logic**
|
||||
- Insert TTL check into the scheduler path **before** any arm/re-arm
|
||||
- Add log code `TTL_VIOLATION`
|
||||
- Implement freshness validation before arming
|
||||
- Before arming, if `(T − fetchedAt) > ttlSeconds`, **skip arming** and log `TTL_VIOLATION`
|
||||
- Add TTL configuration to `NotificationOptions`
|
||||
|
||||
- [ ] **Freshness Checking**
|
||||
- Create `isContentFresh()` method
|
||||
- Implement TTL calculation logic
|
||||
- Add logging for TTL violations
|
||||
|
||||
- [ ] **Configuration Integration**
|
||||
- Add `ttlSeconds` to `NotificationOptions` interface
|
||||
- Implement default TTL values (3600 seconds = 1 hour)
|
||||
- Add TTL validation in option validation
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
- [ ] Notifications are skipped if content is stale
|
||||
- [ ] TTL violations are logged with timestamps
|
||||
- [ ] Default TTL values are applied when not specified
|
||||
- [ ] Freshness checking works across all platforms
|
||||
- [ ] No armed notification violates **TTL-at-fire**
|
||||
- [ ] No armed row violates TTL at T across platforms
|
||||
|
||||
### 1.3 Rolling Window Safety
|
||||
|
||||
**Priority:** CRITICAL
|
||||
|
||||
#### Requirements
|
||||
|
||||
- Keep today's remaining notifications armed
|
||||
- Keep tomorrow's notifications armed (within iOS caps) (see Glossary → Rolling window)
|
||||
- Ensure closed-app delivery reliability
|
||||
- **Current State:** Basic scheduling exists, but no rolling window logic
|
||||
|
||||
#### Implementation Tasks
|
||||
|
||||
- [ ] **Rolling Window Logic** (see Glossary → Rolling window)
|
||||
- Implement `armRollingWindow()` method
|
||||
- Calculate today's remaining slots
|
||||
- Calculate tomorrow's slots within iOS limits
|
||||
- Account for iOS pending-notification limits; arm tomorrow only if within cap
|
||||
|
||||
- [ ] **iOS Capacity Management**
|
||||
- Implement iOS pending notification limit checking
|
||||
- Add capacity-aware scheduling logic
|
||||
- Handle capacity overflow gracefully
|
||||
|
||||
- [ ] **Window Maintenance**
|
||||
- Create `maintainRollingWindow()` method
|
||||
- Implement automatic re-arming logic
|
||||
- Add window state persistence
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
- [ ] Today's remaining notifications stay armed
|
||||
- [ ] Tomorrow's notifications are armed within iOS caps
|
||||
- [ ] Closed-app delivery works reliably
|
||||
- [ ] Window maintenance runs automatically
|
||||
- [ ] Today always armed; tomorrow armed when within iOS cap
|
||||
|
||||
### 1.4 Configuration API Enhancement
|
||||
|
||||
**Priority:** HIGH
|
||||
|
||||
#### Requirements
|
||||
|
||||
- Add `dbPath` configuration option
|
||||
- Implement database path resolution
|
||||
- Add storage mode configuration
|
||||
- **Current State:** No database path configuration exists
|
||||
|
||||
#### Implementation Tasks
|
||||
|
||||
- [ ] **Interface Updates**
|
||||
- Extend `ConfigureOptions` with `dbPath: string`
|
||||
- Add `storage: 'shared'` option
|
||||
- Update validation logic
|
||||
|
||||
- [ ] **Path Resolution**
|
||||
- Implement absolute path handling
|
||||
- Add platform-specific path resolution
|
||||
- Create path validation logic
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
- [ ] `dbPath` can be configured via API
|
||||
- [ ] Path resolution works on all platforms
|
||||
- [ ] Configuration validation prevents invalid paths
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Platform Completion (High Priority)
|
||||
|
||||
**Dependencies:** Phase 1 completion - **CRITICAL:** Phase 2 cannot start until SQLite sharing + TTL enforcement are finished
|
||||
|
||||
### 2.1 iOS Background Tasks Implementation
|
||||
|
||||
**Priority:** HIGH
|
||||
|
||||
#### Requirements
|
||||
|
||||
- `BGTaskScheduler` for T-lead prefetch (see Glossary → T–lead)
|
||||
- Silent push nudge support
|
||||
- Background execution budget management
|
||||
- Schedule prefetch at **T–lead = T − prefetchLeadMinutes** (see Glossary → T–lead)
|
||||
- On wake, perform **one** ETag-aware fetch with **12s** timeout; **never** fetch at delivery
|
||||
- Optionally (re)arm if still within **TTL-at-fire** (see Glossary → TTL)
|
||||
- Single attempt at **T–lead**; **12s** timeout; no delivery-time fetch; (re)arm only if within **TTL-at-fire**. **(Planned)**
|
||||
|
||||
#### Implementation Tasks
|
||||
|
||||
- [ ] **BGTaskScheduler Integration**
|
||||
- Create `DailyNotificationBackgroundTask.swift`
|
||||
- Implement background task registration
|
||||
- Add task expiration handling
|
||||
|
||||
- [ ] **Silent Push Support**
|
||||
- Add silent push notification handling
|
||||
- Implement push-to-background task bridge
|
||||
- Add push token management
|
||||
|
||||
- [ ] **Budget Management**
|
||||
- Implement execution budget tracking
|
||||
- Add budget-aware scheduling
|
||||
- Handle budget exhaustion gracefully
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
- [ ] Background tasks run at T-lead (see Glossary → T–lead)
|
||||
- [ ] Silent push can trigger background execution
|
||||
- [ ] Budget management prevents system penalties
|
||||
- [ ] Background execution works when app is closed
|
||||
- [ ] iOS BGTask best-effort at T–lead; closed-app still delivers via rolling window (see Glossary → Rolling window)
|
||||
|
||||
### 2.2 Android Fallback Completion
|
||||
|
||||
**Priority:** HIGH
|
||||
|
||||
#### Requirements
|
||||
|
||||
- Complete ±10 minute windowed alarm implementation (see Glossary → Windowed alarm)
|
||||
- Finish reboot/time change recovery
|
||||
- Improve exact alarm fallback handling (see Glossary → Exact alarm)
|
||||
- Finalize ±10m windowed alarm; reboot/time-change recovery; deep-link to Exact Alarm permission. **(Planned)**
|
||||
|
||||
#### Implementation Tasks
|
||||
|
||||
- [ ] **Windowed Alarm Implementation**
|
||||
- Complete `scheduleInexactAlarm()` method
|
||||
- Implement ±10 minute window targeting
|
||||
- Add window size configuration
|
||||
|
||||
- [ ] **Recovery Mechanisms**
|
||||
- Complete `BOOT_COMPLETED` receiver
|
||||
- Implement `TIMEZONE_CHANGED` handling
|
||||
- Add `TIME_SET` recovery logic
|
||||
|
||||
- [ ] **Fallback Logic**
|
||||
- Improve exact alarm permission checking
|
||||
- Add graceful degradation to windowed alarms
|
||||
- Implement fallback logging
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
- [ ] Windowed alarms target ±10 minute windows
|
||||
- [ ] Reboot recovery re-arms next 24h
|
||||
- [ ] Time change recovery recomputes schedules
|
||||
- [ ] Fallback works seamlessly
|
||||
- [ ] Android exact permission path verified with fallback ±10m
|
||||
|
||||
### 2.3 Electron Platform Support
|
||||
|
||||
**Priority:** MEDIUM
|
||||
|
||||
#### Requirements
|
||||
|
||||
- Notifications while app is running
|
||||
- Start-on-Login support
|
||||
- Best-effort background scheduling
|
||||
|
||||
#### Implementation Tasks
|
||||
|
||||
- [ ] **Electron Integration**
|
||||
- Create `DailyNotificationElectron.ts`
|
||||
- Implement notification API
|
||||
- Add Start-on-Login support
|
||||
|
||||
- [ ] **Background Limitations**
|
||||
- Document Electron limitations
|
||||
- Implement best-effort scheduling
|
||||
- Add fallback mechanisms
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
- [ ] Notifications work while app is running
|
||||
- [ ] Start-on-Login enables post-reboot delivery
|
||||
- [ ] Limitations are clearly documented
|
||||
- [ ] Best-effort scheduling is implemented
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Network Optimization (Medium Priority)
|
||||
|
||||
**Dependencies:** Phase 1 completion - **CRITICAL:** Phase 3 cannot start until SQLite sharing + TTL enforcement are finished
|
||||
|
||||
### 3.1 ETag Support Implementation
|
||||
|
||||
**Priority:** MEDIUM
|
||||
|
||||
#### Requirements
|
||||
|
||||
- ETag headers in fetch requests
|
||||
- 304 response handling
|
||||
- Network efficiency optimization
|
||||
|
||||
#### Implementation Tasks
|
||||
|
||||
- [ ] **ETag Headers**
|
||||
- Add ETag to fetch requests
|
||||
- Implement ETag storage in database
|
||||
- Add ETag validation logic
|
||||
|
||||
- [ ] **304 Response Handling**
|
||||
- Implement 304 response processing
|
||||
- Add conditional request logic
|
||||
- Handle ETag mismatches
|
||||
|
||||
- [ ] **Network Optimization**
|
||||
- Add request caching
|
||||
- Implement conditional fetching
|
||||
- Add network efficiency metrics
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
- [ ] ETag headers are sent with requests
|
||||
- [ ] 304 responses are handled correctly
|
||||
- [ ] Network efficiency is improved
|
||||
- [ ] Conditional requests work reliably
|
||||
|
||||
### 3.2 Advanced Error Handling
|
||||
|
||||
**Priority:** MEDIUM
|
||||
|
||||
#### Requirements
|
||||
|
||||
- Comprehensive error categorization
|
||||
- Retry logic with exponential backoff
|
||||
- Error reporting and telemetry
|
||||
|
||||
#### Implementation Tasks
|
||||
|
||||
- [ ] **Error Categories**
|
||||
- Define error types and codes
|
||||
- Implement error classification
|
||||
- Add error severity levels
|
||||
|
||||
- [ ] **Retry Logic**
|
||||
- Implement exponential backoff
|
||||
- Add retry limit configuration
|
||||
- Create retry state management
|
||||
|
||||
- [ ] **Telemetry**
|
||||
- Add error reporting
|
||||
- Implement success/failure metrics
|
||||
- Create debugging information
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
- [ ] Errors are properly categorized
|
||||
- [ ] Retry logic works with backoff
|
||||
- [ ] Telemetry provides useful insights
|
||||
- [ ] Debugging information is comprehensive
|
||||
|
||||
### 3.3 Performance Optimization
|
||||
|
||||
**Priority:** LOW
|
||||
|
||||
#### Requirements
|
||||
|
||||
- Database query optimization
|
||||
- Memory usage optimization
|
||||
- Battery usage optimization
|
||||
|
||||
#### Implementation Tasks
|
||||
|
||||
- [ ] **Database Optimization**
|
||||
- Add database indexes
|
||||
- Optimize query performance
|
||||
- Implement connection pooling
|
||||
|
||||
- [ ] **Memory Optimization**
|
||||
- Reduce memory footprint
|
||||
- Implement object pooling
|
||||
- Add memory usage monitoring
|
||||
|
||||
- [ ] **Battery Optimization**
|
||||
- Minimize background CPU usage
|
||||
- Optimize network requests
|
||||
- Add battery usage tracking
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
- [ ] Database queries are optimized
|
||||
- [ ] Memory usage is minimized
|
||||
- [ ] Battery usage is optimized
|
||||
- [ ] Performance metrics are tracked
|
||||
|
||||
---
|
||||
|
||||
## Implementation Guidelines
|
||||
|
||||
### Development Standards
|
||||
|
||||
- **Code Quality:** Follow existing code style and documentation standards
|
||||
- **Testing:** Write unit tests for all new functionality
|
||||
- **Documentation:** Update documentation for all API changes
|
||||
- **Logging:** Add comprehensive logging with proper tagging
|
||||
- **Security:** Follow security best practices for database access
|
||||
|
||||
### Testing Requirements
|
||||
|
||||
- **Unit Tests:** All new methods must have unit tests
|
||||
- **Integration Tests:** Test database sharing functionality
|
||||
- **Platform Tests:** Test on Android, iOS, and Electron
|
||||
- **Edge Cases:** Test TTL violations, network failures, and recovery scenarios
|
||||
|
||||
### Documentation Updates
|
||||
|
||||
- **API Documentation:** Update TypeScript definitions
|
||||
- **Implementation Guide:** Update implementation documentation
|
||||
- **Troubleshooting:** Add troubleshooting guides for common issues
|
||||
- **Examples:** Create usage examples for new features
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Phase 1 Success Criteria
|
||||
|
||||
- [ ] SQLite database sharing works reliably
|
||||
- [ ] TTL-at-fire enforcement prevents stale notifications
|
||||
- [ ] Rolling window ensures closed-app delivery
|
||||
- [ ] Configuration API supports all required options
|
||||
|
||||
### Phase 2 Success Criteria
|
||||
|
||||
- [ ] iOS background tasks run at T-lead
|
||||
- [ ] Android fallback works seamlessly
|
||||
- [ ] Electron notifications work while running
|
||||
- [ ] All platforms support the unified API
|
||||
|
||||
### Phase 3 Success Criteria
|
||||
|
||||
- [ ] ETag support improves network efficiency
|
||||
- [ ] Error handling is comprehensive and robust
|
||||
- [ ] Performance is optimized across all platforms
|
||||
- [ ] System meets all specification requirements
|
||||
|
||||
---
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
### Technical Risks
|
||||
|
||||
- **Database Compatibility:** Test schema version checking thoroughly
|
||||
- **Platform Differences:** Implement platform-specific fallbacks
|
||||
- **Background Execution:** Handle iOS background execution limitations
|
||||
- **Permission Changes:** Monitor Android permission policy changes
|
||||
|
||||
### Implementation Risks
|
||||
|
||||
- **Scope Creep:** Stick to specification requirements
|
||||
- **Testing Coverage:** Ensure comprehensive testing
|
||||
- **Documentation:** Keep documentation up-to-date
|
||||
- **Performance:** Monitor performance impact
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
This roadmap provides a structured approach to completing the Daily Notification Plugin implementation. Phase 1 addresses the critical infrastructure gaps, Phase 2 completes platform-specific functionality, and Phase 3 optimizes the system for production use.
|
||||
|
||||
The implementation should follow the existing code patterns and maintain the high quality standards established in the current codebase. Regular testing and documentation updates are essential for success.
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. Review and approve this roadmap
|
||||
2. Begin Phase 1 implementation
|
||||
3. Set up testing infrastructure
|
||||
4. Create implementation tracking system
|
||||
247
docs/_archive/2025-legacy-doc/notification-system.md
Normal file
247
docs/_archive/2025-legacy-doc/notification-system.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# TimeSafari — Native-First Notification System
|
||||
|
||||
**📝 SANITY CHECK IMPROVEMENTS APPLIED:** This document has been updated to clarify current background fetch infrastructure status and iOS implementation completeness.
|
||||
|
||||
**Status:** Ready for implementation
|
||||
**Date:** 2025-09-07
|
||||
**Author:** Matthew Raymer
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Ship a **single, Native-First** notification system: OS-scheduled **background prefetch at T–lead** + **pre-armed** local notifications. Web-push is retired.
|
||||
|
||||
### What we deliver
|
||||
|
||||
- **Closed-app delivery:** Pre-armed locals fire even if the app is closed.
|
||||
- **Freshness:** One prefetch attempt per slot at **T–lead**; ETag/TTL controls; skip when stale.
|
||||
- **Android precision:** Exact alarms with permission; windowed fallback (±10m) otherwise.
|
||||
- **Resilience:** Re-arm after reboot/time-change (Android receivers; iOS on next wake/silent push).
|
||||
- **Cross-platform:** Same TS API (iOS/Android/Electron). Electron is best-effort while running.
|
||||
|
||||
### Success signals
|
||||
|
||||
- High delivery reliability, minute-precision on Android with permission.
|
||||
- Prefetch budget hit rate at **T–lead**; zero stale deliveries beyond TTL.
|
||||
|
||||
---
|
||||
|
||||
## Strategic Plan
|
||||
|
||||
### Goal
|
||||
|
||||
Deliver 1..M daily notifications with **OS background prefetch at T–lead** *(see Glossary)* and **rolling-window safety** *(see Glossary)* so messages display with fresh content even when the app is closed.
|
||||
|
||||
### Tenets
|
||||
|
||||
- **Reliability first:** OS delivers once scheduled; no JS at delivery time.
|
||||
- **Freshness with guardrails:** Prefetch at **T–lead** *(see Glossary)*; enforce **TTL-at-fire** *(see Glossary)*; ETag-aware.
|
||||
- **Single system:** One TS API; native adapters swap under the hood.
|
||||
- **Platform honesty:** Android exactness via permission; iOS best-effort budget.
|
||||
- **No delivery-time network:** Local notifications display **pre-rendered content only**; never fetch at delivery.
|
||||
|
||||
### Architecture (high level)
|
||||
|
||||
App (Vue/TS) → Orchestrator (policy) → Native Adapters:
|
||||
|
||||
- **SchedulerNative** — AlarmManager (Android) / UNUserNotificationCenter (iOS)
|
||||
- **BackgroundPrefetchNative** — WorkManager (Android) / BGTaskScheduler (+ silent push) (iOS)
|
||||
- **DataStore** — SQLite
|
||||
|
||||
**Storage:** **Current:** SharedPreferences (Android) / UserDefaults (iOS) + in-memory cache (see Glossary → Tiered Storage). **Planned:** one **shared SQLite** file (see Glossary → Shared DB); the app owns schema/migrations; the plugin opens the same path with **WAL** (see Glossary → WAL); background writes are **short & serialized**. *(Keep the "(Planned)" label until Phase 1 ships.)*
|
||||
|
||||
### SQLite Ownership & Concurrency *(Planned)*
|
||||
|
||||
- **One DB file:** The plugin will open the **same path** the app uses (no second DB).
|
||||
- **Migrations owned by app:** The app executes schema migrations and bumps `PRAGMA user_version` (see Glossary → PRAGMA user_version). The plugin **never** migrates; it **asserts** the expected version.
|
||||
- **WAL mode:** Open DB with `journal_mode=WAL`, `synchronous=NORMAL`, `busy_timeout=5000`, `foreign_keys=ON`. WAL (see Glossary → WAL) allows foreground reads while a background job commits quickly.
|
||||
- **Single-writer discipline:** Background jobs write in **short transactions** (UPSERT per slot), then return.
|
||||
- **Encryption (optional):** If using SQLCipher, the **same key** is used by both app and plugin. Do not mix encrypted and unencrypted openings.
|
||||
|
||||
*Note: Currently using SharedPreferences (Android) / UserDefaults (iOS) with in-memory cache. See Implementation Roadmap → Phase 1.1 for migration steps.*
|
||||
|
||||
### Scheduling & T–lead *(Planned)*
|
||||
|
||||
- Arm **rolling window** (see Glossary → Rolling window). **(Planned)**
|
||||
- Exactly **one** online-first fetch at **T–lead** (see Glossary → T–lead) with **12s** timeout; **ETag/304** respected. **(Planned)**
|
||||
- If fresh **and** within **TTL-at-fire** (see Glossary → TTL), (re)arm; otherwise keep prior content. **(Planned)**
|
||||
- If the OS skips the wake, the pre-armed local still fires from cache. **(Planned)**
|
||||
|
||||
*Note: Current implementation has basic scheduling and WorkManager infrastructure (Android) but lacks T–lead prefetch logic, rolling window logic, and iOS background tasks. See Implementation Roadmap → Phase 1-2.*
|
||||
|
||||
### Policies *(Mixed Implementation)*
|
||||
|
||||
- **TTL-at-fire** (see Glossary → TTL): Before arming for T, if `(T − fetchedAt) > ttlSeconds` → **skip**. **(Planned)**
|
||||
- **Android exactness** (see Glossary → Exact alarm): **(Partial)** — permission flow exists; finalize ±10m window & deep-link to settings.
|
||||
- **Reboot/time change:** **(Partial)** — Android receivers partially present; iOS via next wake/silent push.
|
||||
- **No delivery-time network** (see Glossary → No delivery-time network): Local notifications display **pre-rendered content only**; never fetch at delivery. **(Implemented)**
|
||||
|
||||
---
|
||||
|
||||
## Implementation Guide
|
||||
|
||||
### 1) Interfaces (TS stable)
|
||||
|
||||
- **SchedulerNative**: `scheduleExact({slotId, whenMs, title, body, extra})`, `scheduleWindow(..., windowLenMs)`, `cancelBySlot`, `rescheduleAll`, `capabilities()`
|
||||
- **BackgroundPrefetchNative**: `schedulePrefetch(slotId, atMs)`, `cancelPrefetch(slotId)`
|
||||
- **DataStore**: SQLite adapters (notif_contents, notif_deliveries, notif_config)
|
||||
- **Public API**: `configure`, `requestPermissions`, `runFullPipelineNow`, `reschedule`, `getState`
|
||||
|
||||
### DB Path & Adapter Configuration *(Planned)*
|
||||
|
||||
- **Configure option:** `dbPath: string` (absolute path or platform alias) will be passed from JS to the plugin during `configure()`.
|
||||
- **Shared tables:**
|
||||
|
||||
- `notif_contents(slot_id, payload_json, fetched_at, etag, …)`
|
||||
- `notif_deliveries(slot_id, fire_at, delivered_at, status, error_code, …)`
|
||||
- `notif_config(k, v)`
|
||||
- **Open settings:**
|
||||
|
||||
- `journal_mode=WAL`
|
||||
- `synchronous=NORMAL`
|
||||
- `busy_timeout=5000`
|
||||
- `foreign_keys=ON`
|
||||
|
||||
*Note: Currently using SharedPreferences/UserDefaults (see Glossary → Tiered Storage). Database configuration is planned for Phase 1.*
|
||||
|
||||
See **Implementation Roadmap → Phase 1.1** for migration steps and schema.
|
||||
|
||||
**Type (TS) extension** *(Planned)*
|
||||
|
||||
```ts
|
||||
export type ConfigureOptions = {
|
||||
// …existing fields…
|
||||
dbPath: string; // shared DB file the plugin will open
|
||||
storage: 'shared'; // canonical value; plugin-owned DB is not used
|
||||
};
|
||||
```
|
||||
|
||||
*Note: Current `NotificationOptions` interface exists but lacks `dbPath` configuration. This will be added in Phase 1.*
|
||||
|
||||
**Plugin side (pseudo)**
|
||||
|
||||
```kotlin
|
||||
// Android open
|
||||
val db = SQLiteDatabase.openDatabase(dbPath, null, SQLiteDatabase.OPEN_READWRITE)
|
||||
db.execSQL("PRAGMA journal_mode=WAL")
|
||||
db.execSQL("PRAGMA synchronous=NORMAL")
|
||||
db.execSQL("PRAGMA foreign_keys=ON")
|
||||
db.execSQL("PRAGMA busy_timeout=5000")
|
||||
// Verify schema version
|
||||
val uv = rawQuery("PRAGMA user_version").use { it.moveToFirst(); it.getInt(0) }
|
||||
require(uv >= MIN_EXPECTED_VERSION) { "Schema version too old" }
|
||||
```
|
||||
|
||||
```swift
|
||||
// iOS open (FMDB / SQLite3)
|
||||
// Set WAL via PRAGMA after open; check user_version the same way.
|
||||
```
|
||||
|
||||
### 2) Templating & Arming
|
||||
|
||||
- Render `title/body` **before** scheduling; pass via **SchedulerNative**.
|
||||
- Route all arming through **SchedulerNative** to centralize Android exact/window semantics.
|
||||
|
||||
### 3) T–lead (single attempt)
|
||||
|
||||
**T–lead governs prefetch, not arming.** We **arm** one-shot locals as part of the rolling window so closed-app delivery is guaranteed. At **T–lead = T − prefetchLeadMinutes**, the **native background job** attempts **one** 12s ETag-aware fetch. If fresh content arrives and will not violate **TTL-at-fire**, we (re)arm the upcoming slot; if the OS skips the wake, the pre-armed local still fires with cached content.
|
||||
|
||||
- Compute T–lead = `whenMs - prefetchLeadMinutes*60_000`.
|
||||
- `BackgroundPrefetchNative.schedulePrefetch(slotId, atMs=T–lead)`.
|
||||
- On wake: **ETag** fetch (timeout **12s**), persist, optionally cancel & re-arm if within TTL.
|
||||
- Never fetch at delivery time.
|
||||
|
||||
### 4) TTL-at-fire
|
||||
|
||||
**TTL-at-fire:** Before arming for time **T**, compute `T − fetchedAt`. If that exceeds `ttlSeconds`, **do not arm** (skip). This prevents posting stale notifications when the app has been closed for a long time.
|
||||
|
||||
`if (whenMs - fetchedAt) > ttlSeconds*1000 → skip`
|
||||
|
||||
### 5) Android specifics
|
||||
|
||||
- Request `SCHEDULE_EXACT_ALARM`; deep-link if denied; fallback to `setWindow(start,len)` (±10m).
|
||||
- Receivers: `BOOT_COMPLETED`, `TIMEZONE_CHANGED`, `TIME_SET` → recompute & re-arm for next 24h and schedule T–lead prefetch.
|
||||
|
||||
### 6) iOS specifics
|
||||
|
||||
- `BGTaskScheduler` for T–lead prefetch (best-effort). Optional silent push nudge.
|
||||
- Locals: `UNCalendarNotificationTrigger` (one-shots); no NSE mutation for locals.
|
||||
|
||||
### 7) Network & Timeouts
|
||||
|
||||
- Content fetch: **12s** timeout; single attempt at T–lead; ETag/304 respected.
|
||||
- ACK/Error: **8s** timeout, fire-and-forget.
|
||||
|
||||
### 8) Electron
|
||||
|
||||
- Notifications while app is running; recommend **Start-on-Login**. No true background scheduling when fully closed.
|
||||
|
||||
### 9) Telemetry
|
||||
|
||||
- Record `scheduled|shown|error`; ACK deliveries (8s timeout); include slot/times/TZ/app version.
|
||||
|
||||
---
|
||||
|
||||
## Capability Matrix
|
||||
|
||||
| Capability | Android (Native) | iOS (Native) | Electron | Web |
|
||||
|---|---|---|---|---|
|
||||
| Multi-daily locals (closed app) | ✅ | ✅ | ✅ (app running) | — |
|
||||
| Prefetch at T–lead (app closed) | ✅ WorkManager | ⚠️ BGTask (best-effort) | ✅ (app running) | — |
|
||||
| Re-arm after reboot/time-change | ✅ Receivers | ⚠️ On next wake/silent push | ✅ Start-on-Login | — |
|
||||
| Minute-precision alarms | ✅ with exact permission | ❌ not guaranteed | ✅ timer best-effort | — |
|
||||
| Delivery-time mutation for locals | ❌ | ❌ | — | — |
|
||||
| ETag/TTL enforcement | ✅ | ✅ | ✅ | — |
|
||||
| Rolling-window safety | ✅ | ✅ | ✅ | — |
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
### Core
|
||||
|
||||
- **Closed-app delivery:** Armed locals fire at T with last rendered content. No delivery-time network.
|
||||
- **T–lead prefetch:** Single background attempt at **T–lead**; if skipped, delivery still occurs from cache.
|
||||
- **TTL-at-fire:** No armed local violates TTL at T.
|
||||
|
||||
### Android
|
||||
|
||||
- **Exact permission path:** With `SCHEDULE_EXACT_ALARM` → within ±1m; else **±10m** window.
|
||||
- **Reboot recovery:** After reboot, receivers re-arm next 24h and schedule T–lead prefetch.
|
||||
- **TZ/DST change:** Recompute & re-arm; future slots align to new wall-clock.
|
||||
|
||||
### iOS
|
||||
|
||||
- **BGTask budget respected:** Prefetch often runs but may be skipped; delivery still occurs via rolling window.
|
||||
- **Force-quit caveat:** No background execution after user terminate; delivery still occurs if pre-armed.
|
||||
|
||||
### Electron
|
||||
|
||||
- **Running-app rule:** Delivery only while app runs; with Start-on-Login, after reboot the orchestrator re-arms and subsequent slots deliver.
|
||||
|
||||
### Network
|
||||
|
||||
- Content fetch timeout **12s**; ACK/Error **8s**; no retries inside lead; ETag honored.
|
||||
|
||||
### Observability
|
||||
|
||||
- Log/telemetry for `scheduled|shown|error`; ACK payload includes slot, times, device TZ, app version.
|
||||
|
||||
### DB Sharing *(Planned)*
|
||||
|
||||
- **Shared DB visibility:** A background prefetch writes `notif_contents`; the foreground UI **immediately** reads the same row.
|
||||
- **WAL overlap:** With the app reading while the plugin commits, no user-visible blocking occurs.
|
||||
- **Version safety:** If `user_version` is behind, the plugin emits an error and does not write (protects against partial installs).
|
||||
|
||||
*Note: Currently using SharedPreferences/UserDefaults with in-memory cache. SQLite sharing is planned for Phase 1.*
|
||||
|
||||
---
|
||||
|
||||
## Web-Push Cleanup
|
||||
|
||||
Web-push functionality has been retired due to unreliability. All web-push related code paths and documentation sections should be removed or marked as deprecated. See `web-push-cleanup-guide.md` for detailed cleanup steps.
|
||||
|
||||
---
|
||||
|
||||
*This document consolidates the Native-First notification system strategy, implementation details, capabilities, and acceptance criteria into a single comprehensive reference.*
|
||||
@@ -0,0 +1,252 @@
|
||||
# iOS Prefetch Plugin Testing and Validation Enhancements - Applied
|
||||
|
||||
**Date:** 2025-11-15
|
||||
**Status:** ✅ Applied to codebase
|
||||
**Directive Source:** User-provided comprehensive enhancement directive
|
||||
|
||||
## Summary
|
||||
|
||||
This document tracks the application of comprehensive enhancements to the iOS prefetch plugin testing and validation system. All improvements from the directive have been systematically applied to the codebase.
|
||||
|
||||
---
|
||||
|
||||
## 1. Technical Correctness Improvements ✅
|
||||
|
||||
### 1.1 Robust BGTask Scheduling & Lifecycle
|
||||
|
||||
**Applied to:** `ios/Plugin/DailyNotificationBackgroundTaskTestHarness.swift`
|
||||
|
||||
**Enhancements:**
|
||||
- ✅ **Validation of Scheduling Conditions:** Added validation to ensure `earliestBeginDate` is at least 60 seconds in future (iOS requirement)
|
||||
- ✅ **Simulator Error Handling:** Added graceful handling of Code=1 error (expected on simulator) with clear logging
|
||||
- ✅ **One Active Task Rule:** Implemented `cancelPendingTask()` method to enforce only one prefetch task per notification
|
||||
- ✅ **Debug Verification:** Added `verifyOneActiveTask()` helper method to verify only one task is pending
|
||||
- ✅ **Schedule Next Task at Execution:** Updated handler to schedule next task IMMEDIATELY at start (Apple best practice)
|
||||
- ✅ **Expiration Handler:** Enhanced expiration handler to ensure task completion even on timeout
|
||||
- ✅ **Completion Guarantee:** Added guard to ensure `setTaskCompleted()` is called exactly once
|
||||
- ✅ **Error Handling:** Enhanced error handling with proper logging and fallback behavior
|
||||
|
||||
**Code Changes:**
|
||||
- Enhanced `schedulePrefetchTask()` with validation and one-active-task rule
|
||||
- Updated `handlePrefetchTask()` to follow Apple's best practice pattern
|
||||
- Added `cancelPendingTask()` and `verifyOneActiveTask()` methods
|
||||
- Improved `PrefetchOperation` with failure tracking
|
||||
|
||||
### 1.2 Enhanced Scheduling and Notification Coordination
|
||||
|
||||
**Applied to:** Documentation in `IOS_TEST_APP_REQUIREMENTS.md`
|
||||
|
||||
**Enhancements:**
|
||||
- ✅ Added "Technical Correctness Requirements" section
|
||||
- ✅ Documented unified scheduling logic requirements
|
||||
- ✅ Documented BGTask identifier constant verification
|
||||
- ✅ Documented concurrency considerations for Phase 2
|
||||
- ✅ Documented OS limits and tolerance expectations
|
||||
|
||||
---
|
||||
|
||||
## 2. Testing Coverage Expansion ✅
|
||||
|
||||
### 2.1 Edge Case Scenarios and Environment Conditions
|
||||
|
||||
**Applied to:** `doc/test-app-ios/IOS_PREFETCH_TESTING.md`
|
||||
|
||||
**Enhancements:**
|
||||
- ✅ **Expanded Edge Case Table:** Added comprehensive table with 7 scenarios:
|
||||
- Background Refresh Off
|
||||
- Low Power Mode On
|
||||
- App Force-Quit
|
||||
- Device Timezone Change
|
||||
- DST Transition
|
||||
- Multi-Day Scheduling (Phase 2)
|
||||
- Device Reboot
|
||||
- ✅ **Test Strategy:** Each scenario includes test strategy and expected outcome
|
||||
- ✅ **Additional Variations:** Documented battery vs plugged, force-quit vs backgrounded, etc.
|
||||
|
||||
### 2.2 Failure Injection and Error Handling Tests
|
||||
|
||||
**Applied to:** `doc/test-app-ios/IOS_PREFETCH_TESTING.md` and `IOS_TEST_APP_REQUIREMENTS.md`
|
||||
|
||||
**Enhancements:**
|
||||
- ✅ **Expanded Negative-Path Tests:** Added 8 new failure scenarios:
|
||||
- Storage unavailable
|
||||
- JWT expiration
|
||||
- Timezone drift
|
||||
- Corrupted cache
|
||||
- BGTask execution failure
|
||||
- Repeated scheduling calls
|
||||
- Permission revoked mid-run
|
||||
- ✅ **Error Handling Section:** Added comprehensive error handling test cases to test app requirements
|
||||
- ✅ **Expected Outcomes:** Each failure scenario includes expected plugin behavior
|
||||
|
||||
### 2.3 Automated Testing Strategies
|
||||
|
||||
**Applied to:** `doc/test-app-ios/IOS_PREFETCH_TESTING.md`
|
||||
|
||||
**Enhancements:**
|
||||
- ✅ **Unit Tests Section:** Added comprehensive unit test strategy:
|
||||
- Time calculations
|
||||
- TTL validation
|
||||
- JSON mapping
|
||||
- Permission check flow
|
||||
- BGTask scheduling logic
|
||||
- ✅ **Integration Tests Section:** Added integration test strategies:
|
||||
- Xcode UI Tests
|
||||
- Log sequence validation
|
||||
- Mocking and dependency injection
|
||||
- ✅ **BGTask Expiration Coverage:** Added test strategy for expiration handler
|
||||
|
||||
---
|
||||
|
||||
## 3. Validation and Verification Enhancements ✅
|
||||
|
||||
### 3.1 Structured Logging and Automated Log Analysis
|
||||
|
||||
**Applied to:** `doc/test-app-ios/IOS_PREFETCH_TESTING.md`
|
||||
|
||||
**Enhancements:**
|
||||
- ✅ **Structured Log Output (JSON):** Added JSON schema examples for:
|
||||
- Success events
|
||||
- Failure events
|
||||
- Cycle complete summary
|
||||
- ✅ **Log Validation Script:** Added complete `validate-ios-logs.sh` script with:
|
||||
- Sequence marker detection
|
||||
- Automated validation logic
|
||||
- Usage instructions
|
||||
- ✅ **Distinct Log Markers:** Documented log marker requirements
|
||||
|
||||
### 3.2 Enhanced Verification Signals
|
||||
|
||||
**Applied to:** `doc/test-app-ios/IOS_PREFETCH_TESTING.md` and `IOS_TEST_APP_REQUIREMENTS.md`
|
||||
|
||||
**Enhancements:**
|
||||
- ✅ **Telemetry Counters:** Documented all expected counters:
|
||||
- `dnp_prefetch_scheduled_total`
|
||||
- `dnp_prefetch_executed_total`
|
||||
- `dnp_prefetch_success_total`
|
||||
- `dnp_prefetch_failure_total{reason="NETWORK|AUTH|SYSTEM"}`
|
||||
- `dnp_prefetch_used_for_notification_total`
|
||||
- ✅ **State Integrity Checks:** Added verification methods:
|
||||
- Content hash verification
|
||||
- Schedule hash verification
|
||||
- Persistence verification
|
||||
- ✅ **Persistent Test Artifacts:** Added JSON schema for test run artifacts
|
||||
- ✅ **UI Indicators:** Added requirements for status display and operation summary
|
||||
- ✅ **In-App Log Viewer:** Documented Phase 2 enhancement for QA use
|
||||
|
||||
### 3.3 Test Run Result Template Enhancement
|
||||
|
||||
**Applied to:** `doc/test-app-ios/IOS_PREFETCH_TESTING.md`
|
||||
|
||||
**Enhancements:**
|
||||
- ✅ **Enhanced Template:** Added fields for:
|
||||
- Actual execution time vs scheduled
|
||||
- Telemetry counters
|
||||
- State verification (content hash, schedule hash, cache persistence)
|
||||
- ✅ **Persistent Artifacts:** Added note about test app saving summary to file
|
||||
|
||||
---
|
||||
|
||||
## 4. Documentation Updates ✅
|
||||
|
||||
### 4.1 Test App Requirements
|
||||
|
||||
**Applied to:** `doc/test-app-ios/IOS_TEST_APP_REQUIREMENTS.md`
|
||||
|
||||
**Enhancements:**
|
||||
- ✅ **Technical Correctness Requirements:** Added comprehensive section covering:
|
||||
- BGTask scheduling & lifecycle
|
||||
- Scheduling and notification coordination
|
||||
- ✅ **Error Handling Expansion:** Added 7 new error handling test cases
|
||||
- ✅ **UI Indicators:** Added requirements for status display, operation summary, and dump prefetch status
|
||||
- ✅ **In-App Log Viewer:** Documented Phase 2 enhancement
|
||||
- ✅ **Persistent Schedule Snapshot:** Enhanced with content hash and schedule hash fields
|
||||
|
||||
### 4.2 Testing Guide
|
||||
|
||||
**Applied to:** `doc/test-app-ios/IOS_PREFETCH_TESTING.md`
|
||||
|
||||
**Enhancements:**
|
||||
- ✅ **Edge Case Scenarios Table:** Comprehensive table with test strategies
|
||||
- ✅ **Failure Injection Tests:** 8 new negative-path scenarios
|
||||
- ✅ **Automated Testing Strategies:** Complete unit and integration test strategies
|
||||
- ✅ **Validation Enhancements:** Log validation script, structured logging, verification signals
|
||||
- ✅ **Test Run Template:** Enhanced with telemetry and state verification fields
|
||||
|
||||
---
|
||||
|
||||
## 5. Code Enhancements ✅
|
||||
|
||||
### 5.1 Test Harness Improvements
|
||||
|
||||
**File:** `ios/Plugin/DailyNotificationBackgroundTaskTestHarness.swift`
|
||||
|
||||
**Changes:**
|
||||
- Enhanced `schedulePrefetchTask()` with validation and one-active-task enforcement
|
||||
- Added `cancelPendingTask()` method
|
||||
- Added `verifyOneActiveTask()` debug helper
|
||||
- Updated `handlePrefetchTask()` to follow Apple best practices
|
||||
- Enhanced `PrefetchOperation` with failure tracking
|
||||
- Improved error handling and logging throughout
|
||||
|
||||
**Key Features:**
|
||||
- Validates minimum 60-second lead time
|
||||
- Enforces one active task rule
|
||||
- Handles simulator limitations gracefully
|
||||
- Schedules next task immediately at execution start
|
||||
- Ensures task completion even on expiration
|
||||
- Prevents double completion
|
||||
|
||||
---
|
||||
|
||||
## 6. Files Modified
|
||||
|
||||
1. ✅ `ios/Plugin/DailyNotificationBackgroundTaskTestHarness.swift` - Enhanced with technical correctness improvements
|
||||
2. ✅ `doc/test-app-ios/IOS_PREFETCH_TESTING.md` - Expanded testing coverage and validation enhancements
|
||||
3. ✅ `doc/test-app-ios/IOS_TEST_APP_REQUIREMENTS.md` - Added technical correctness requirements and enhanced error handling
|
||||
|
||||
---
|
||||
|
||||
## 7. Next Steps
|
||||
|
||||
### Immediate (Phase 1)
|
||||
- [ ] Implement actual prefetch logic using enhanced test harness as reference
|
||||
- [x] Create `validate-ios-logs.sh` script ✅ **COMPLETE** - Script created at `scripts/validate-ios-logs.sh`
|
||||
- [ ] Add UI indicators to test app
|
||||
- [ ] Implement persistent test artifacts export
|
||||
|
||||
### Phase 2
|
||||
- [ ] Wire telemetry counters to production pipeline
|
||||
- [ ] Implement in-app log viewer
|
||||
- [ ] Add automated CI pipeline integration
|
||||
- [ ] Test multi-day scenarios with varying TTL values
|
||||
|
||||
---
|
||||
|
||||
## 8. Validation Checklist
|
||||
|
||||
- [x] Technical correctness improvements applied to test harness
|
||||
- [x] Edge case scenarios documented with test strategies
|
||||
- [x] Failure injection tests expanded
|
||||
- [x] Automated testing strategies documented
|
||||
- [x] Structured logging schema defined
|
||||
- [x] Log validation script provided ✅ **COMPLETE** - Script created at `scripts/validate-ios-logs.sh`
|
||||
- [x] Enhanced verification signals documented
|
||||
- [x] Test run template enhanced
|
||||
- [x] Documentation cross-referenced and consistent
|
||||
- [x] Code follows Apple best practices
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **Main Directive:** `doc/directives/0003-iOS-Android-Parity-Directive.md`
|
||||
- **Testing Guide:** `doc/test-app-ios/IOS_PREFETCH_TESTING.md`
|
||||
- **Test App Requirements:** `doc/test-app-ios/IOS_TEST_APP_REQUIREMENTS.md`
|
||||
- **Test Harness:** `ios/Plugin/DailyNotificationBackgroundTaskTestHarness.swift`
|
||||
- **Glossary:** `doc/test-app-ios/IOS_PREFETCH_GLOSSARY.md`
|
||||
|
||||
---
|
||||
|
||||
**Status:** All enhancements from the directive have been systematically applied to the codebase. The plugin is now ready for Phase 1 implementation with comprehensive testing and validation infrastructure in place.
|
||||
|
||||
Reference in New Issue
Block a user