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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user