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

@@ -41,7 +41,7 @@ The `/android/app` directory contains a **Capacitor-based Android test applicati
├─────────────────────────────────────────────────────────────┤
│ Web Assets (/www) │
│ ├── index.html (Test Interface) │
│ ├── cordova.js (Capacitor Runtime)
│ ├── capacitor.js (Capacitor Runtime) │
│ └── plugins/ (Plugin JavaScript) │
├─────────────────────────────────────────────────────────────┤
│ Native Plugin Integration │
@@ -182,8 +182,8 @@ The `/www` directory (mapped to `assets/public/`) contains the web application t
```
assets/public/
├── index.html # Main test interface (549 lines)
├── cordova.js # Capacitor runtime
├── cordova_plugins.js # Plugin JavaScript bridge
├── capacitor.js # Capacitor runtime
├── capacitor_plugins.js # Plugin JavaScript bridge
└── plugins/ # Plugin JavaScript files
```
@@ -513,3 +513,52 @@ The `/android/app` portion of the DailyNotification plugin represents a well-arc
The integration between the web assets (`/www`) and native Android code through Capacitor's bridge system creates a seamless testing environment that allows developers to validate plugin functionality in real-time while providing an intuitive interface for non-technical users to test and understand the plugin's capabilities.
This architecture serves as both a practical testing tool and a reference implementation for integrating the DailyNotification plugin into other applications.
## Assumptions & Versions
| Topic | Value | Notes |
|---|---|---|
| Android min/target SDK | 24 / 35 | Align with `compileSdkVersion`/`targetSdkVersion`. |
| Capacitor | v5.x | Confirm web asset naming (`capacitor.js` vs Cordova shims). |
| WorkManager | 2.9.0 | Matches Gradle deps listed. |
| Room | 2.6.1 | Matches Gradle deps listed. |
| Exact Alarms | Tiramisu+ | Requires user grant on many OEMs. |
## Bridge Surface (Summary)
- `scheduleDailyNotification(req: {time, title, body, sound, priority}) -> {success, scheduledAt?, error?}`
- `checkPermissionStatus() -> {postNotificationsGranted, exactAlarmGranted, batteryOptIgnored, channelEnabled, ...}`
- `openChannelSettings() -> {opened: boolean}`
- `openExactAlarmSettings() -> {opened: boolean}`
- `requestNotificationPermissions() -> {granted: boolean, permissions: {...}}`
- `getNotificationStatus() -> {isEnabled, isScheduled, nextNotificationTime, ...}`
## Permission & Settings Truth Table
| Symptom | Likely Cause | Action |
|---|---|---|
| No notification posts | `POST_NOTIFICATIONS` denied | Call `requestNotificationPermissions()` |
| Fires late/misses | No exact alarm grant / Doze | `openExactAlarmSettings()` or fallback to WorkManager |
| Silent notifications | Channel disabled/low importance | `openChannelSettings()` then retest |
| Battery optimization kills | App not whitelisted | Guide user to battery optimization settings |
| Boot reschedule fails | `RECEIVE_BOOT_COMPLETED` denied | Check manifest receiver registration |
## Runtime Flow Diagram
```mermaid
graph TD
A[JavaScript Call] --> B[Capacitor Bridge]
B --> C[@PluginMethod]
C --> D[Use Case Handler]
D --> E{Alarm vs WorkManager}
E -->|Exact Alarm| F[AlarmManager]
E -->|Fallback| G[WorkManager]
F --> H[BootReceiver]
G --> H
H --> I[NotificationReceiver]
I --> J[UI Update]
```
## Cordova vs Capacitor Assets Accuracy Note
> **Note:** If using pure Capacitor v5, the web runtime is `capacitor.js`. If Cordova compatibility is enabled, `cordova.js/cordova_plugins.js` will appear; otherwise remove those references here for accuracy.