docs: add operational sections to Android app analysis and implementation plan

- Add 5 surgical sections to android-app-analysis.md:
  * Assumptions & Versions table (Android SDK, Capacitor, WorkManager, Room, Exact Alarms)
  * Bridge Surface summary with method I/O shapes
  * Permission & Settings Truth Table (symptoms → actions)
  * Runtime Flow Diagram (mermaid)
  * Cordova vs Capacitor assets accuracy note

- Add 6 execution rails to android-app-improvement-plan.md:
  * Phase DoD blocks for PR gating
  * RACI for multi-contributor PRs
  * PR Checklist template
  * Test Matrix from scenarios
  * Error Code Canon table
  * Operational Runbooks stubs

- Fix accuracy: correct 'cordova.js' references to 'capacitor.js'
- Make Status Matrix required fields explicit (5 specific fields)
- Keep existing structure intact, minimal churn approach
This commit is contained in:
Matthew Raymer
2025-10-24 10:09:00 +00:00
parent 9ff5a8c588
commit 0a1e6a16f5
2 changed files with 119 additions and 4 deletions

View File

@@ -830,7 +830,7 @@ interface ScheduleResponse {
## Acceptance Criteria
### Status Matrix
- [ ] Reports all relevant runtime capabilities
- [ ] Reports all relevant runtime capabilities (postNotifications, exactAlarms, channelEnabled, batteryOptIgnored, canScheduleNow)
- [ ] Shows live channel state
- [ ] Provides actionable buttons for issues
- [ ] Exports diagnostics as JSON
@@ -886,3 +886,69 @@ This implementation plan provides a structured approach to improving the DailyNo
The phased approach allows for incremental improvements while ensuring each phase delivers value. The acceptance criteria provide clear success metrics for each improvement area.
By following this plan, the test app will become more maintainable, reliable, and user-friendly while providing a solid foundation for future enhancements.
## Phase DoD (Definition of Done)
### Phase 1 DoD
- Status Matrix renders 5 fields: postNotifications, exactAlarms, channelEnabled, batteryOptIgnored, canScheduleNow.
- Input schema rejects bad `time`, long `title/body`, wrong `priority`.
- Boot reschedule idempotent (no dup rows, migration fence).
- @PluginMethod bodies ≤ 25 LOC, delegate to use-cases.
### Phase 2 DoD
- Test UI split into modular scenarios with fixtures.
- Instrumentation tests cover channel disabled and exact alarm denied paths.
- Structured logging with event IDs for all operations.
- Error handling returns canonical error codes.
### Phase 3 DoD
- Security hardening implemented (HTTPS enforcement, input validation).
- Performance optimizations deployed (lazy loading, backoff strategy).
- Complete documentation with runbooks and API reference.
- Diagnostics system operational with health checks.
## RACI
- Owner: Android plugin maintainer
- Review: Mobile lead
- Consult: QA (instrumented tests), Web (bridge TS)
- Inform: Docs
## PR Checklist (copy/paste into PR template)
- [ ] Input validated at bridge boundary (unit tested)
- [ ] Use-case class created/updated (no logic in @PluginMethod)
- [ ] Logs include event IDs (start/finish/error)
- [ ] Status Matrix field(s) updated if capability changed
- [ ] Runbooks section touched if behavior changed
## Test Matrix
| Scenario | Method(s) | Setup | Expected |
|---|---|---|
| Immediate notify | scheduleDailyNotification | Channel ON, perms granted | Success + toast seen |
| Channel disabled path | isChannelEnabled/openChannelSettings | Disable channel | Canonical `E_CHANNEL_DISABLED` |
| Exact alarm denied path | openExactAlarmSettings | Revoke exact alarm | Fallback path taken; logged `DOZE_FALLBACK` |
| Boot reschedule | BootReceiver | Reboot emulator | One (not duplicate) schedule restored |
## Error Codes (canonical)
| Code | Meaning | Hint |
|---|---|---|
| E_INVALID_TIME | HH:mm invalid | Use 24h HH:mm |
| E_TITLE_TOO_LONG | >100 chars | Trim title |
| E_BODY_TOO_LONG | >500 chars | Trim body |
| E_PERMISSION_DENIED | Missing POST_NOTIFICATIONS | Request permission |
| E_CHANNEL_DISABLED | Channel blocked/low importance | Open channel settings |
| E_EXACT_ALARM_DENIED | No exact alarm | Open exact alarm settings / fallback |
| E_DOZE_LIMIT | Throttled by Doze | Expect delays; fallback taken |
## Runbooks
### No notifications fire
Checks → Fix → Verify (matrix first, then perms, channel, exact alarm).
### Duplicates after reboot
Check storage for orphan schedule rows; verify idempotent rescheduler logs.
### Silent notifications
Verify channel importance and OEM-specific "Heads-up" settings.