docs: apply precise fixes for correctness, consistency, and sprintability
Analysis doc improvements: - Unify runtime naming: fix tree diagram cordova.js → capacitor.js - Make manifest receivers explicit: add exported attributes and intent filters - Surface exact-alarm user rule: add decision rule for QA/ops reasoning - Guard Cordova dependency: add note about Cordova shims requirement - Add error surfacing to runtime flow: show validation and use-case error paths - Add auto-generated note to capacitor.plugins.json section Implementation plan improvements: - Add diagnostics button to Phase 1 DoD - Add Doze/Idle case to Test Matrix for false negative prevention - Make unknown field rejection explicit acceptance criterion - Link receivers export policy to Manifest Hygiene checklist - Add event ID requirement to PR checklist for grep-able logs All changes maintain existing structure with surgical precision edits.
This commit is contained in:
Matthew Raymer
@@ -30,6 +30,7 @@ The `/android/app` directory contains a **Capacitor-based Android test applicati
|
||||
4. **Documentation**: Live demonstration of plugin capabilities
|
||||
|
||||
### Architecture Pattern
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Android App Container │
|
||||
@@ -55,6 +56,7 @@ The `/android/app` directory contains a **Capacitor-based Android test applicati
|
||||
## Directory Structure
|
||||
|
||||
### Root Android App Structure
|
||||
|
||||
```
|
||||
android/app/
|
||||
├── build.gradle # App build configuration
|
||||
@@ -68,8 +70,8 @@ android/app/
|
||||
│ │ ├── capacitor.plugins.json
|
||||
│ │ └── public/ # Web application files
|
||||
│ │ ├── index.html # Main test interface
|
||||
│ │ ├── cordova.js # Capacitor runtime
|
||||
│ │ ├── cordova_plugins.js
|
||||
│ │ ├── capacitor.js # Capacitor runtime
|
||||
│ │ ├── capacitor_plugins.js
|
||||
│ │ └── plugins/ # Plugin JavaScript files
|
||||
│ ├── java/
|
||||
│ │ └── com/timesafari/dailynotification/
|
||||
@@ -87,6 +89,7 @@ android/app/
|
||||
## Key Components
|
||||
|
||||
### 1. MainActivity.java
|
||||
|
||||
**Purpose**: Entry point extending Capacitor's BridgeActivity
|
||||
**Location**: `src/main/java/com/timesafari/dailynotification/MainActivity.java`
|
||||
|
||||
@@ -100,16 +103,19 @@ public class MainActivity extends BridgeActivity {
|
||||
```
|
||||
|
||||
**Key Features**:
|
||||
|
||||
- Minimal implementation - Capacitor handles most functionality
|
||||
- Extends `BridgeActivity` for automatic plugin discovery
|
||||
- Provides WebView container for web assets
|
||||
- Handles plugin registration and JavaScript bridge
|
||||
|
||||
### 2. AndroidManifest.xml
|
||||
|
||||
**Purpose**: App configuration, permissions, and component declarations
|
||||
**Location**: `src/main/AndroidManifest.xml`
|
||||
|
||||
**Key Declarations**:
|
||||
|
||||
```xml
|
||||
<!-- App Configuration -->
|
||||
<application android:name="com.timesafari.dailynotification">
|
||||
@@ -121,8 +127,23 @@ public class MainActivity extends BridgeActivity {
|
||||
</activity>
|
||||
|
||||
<!-- Plugin Components -->
|
||||
<receiver android:name="com.timesafari.dailynotification.DailyNotificationReceiver" />
|
||||
<receiver android:name="com.timesafari.dailynotification.BootReceiver" />
|
||||
<receiver
|
||||
android:name="com.timesafari.dailynotification.DailyNotificationReceiver"
|
||||
android:enabled="true"
|
||||
android:exported="false">
|
||||
<intent-filter>
|
||||
<action android:name="com.timesafari.daily.NOTIFICATION" />
|
||||
</intent-filter>
|
||||
</receiver>
|
||||
|
||||
<receiver
|
||||
android:name="com.timesafari.dailynotification.BootReceiver"
|
||||
android:enabled="true"
|
||||
android:exported="true">
|
||||
<intent-filter android:priority="1000">
|
||||
<action android:name="android.intent.action.BOOT_COMPLETED" />
|
||||
</intent-filter>
|
||||
</receiver>
|
||||
</application>
|
||||
|
||||
<!-- Required Permissions -->
|
||||
@@ -134,6 +155,7 @@ public class MainActivity extends BridgeActivity {
|
||||
```
|
||||
|
||||
**Critical Permissions**:
|
||||
|
||||
- `POST_NOTIFICATIONS`: Required for Android 13+ notification posting
|
||||
- `SCHEDULE_EXACT_ALARM`: Required for precise notification timing
|
||||
- `WAKE_LOCK`: Required for background processing
|
||||
@@ -143,7 +165,9 @@ public class MainActivity extends BridgeActivity {
|
||||
### 3. Capacitor Configuration Files
|
||||
|
||||
#### capacitor.config.json
|
||||
|
||||
**Purpose**: Capacitor runtime configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"appId": "com.timesafari.dailynotification",
|
||||
@@ -164,19 +188,23 @@ public class MainActivity extends BridgeActivity {
|
||||
```
|
||||
|
||||
#### capacitor.plugins.json
|
||||
|
||||
**Purpose**: Plugin discovery and registration
|
||||
**Note**: Auto-generated on `npx cap sync` - should not be manually edited
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"name": "DailyNotification",
|
||||
"classpath": "com.timesafari.dailynotification.DailyNotificationPlugin"
|
||||
}
|
||||
{
|
||||
"name": "DailyNotification",
|
||||
"classpath": "com.timesafari.dailynotification.DailyNotificationPlugin"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Web Asset Integration
|
||||
|
||||
### /www Directory Structure
|
||||
|
||||
The `/www` directory (mapped to `assets/public/`) contains the web application that runs inside the Capacitor WebView:
|
||||
|
||||
```
|
||||
@@ -196,12 +224,14 @@ assets/public/
|
||||
**Features**:
|
||||
|
||||
#### 1. User Interface
|
||||
|
||||
- **Modern Design**: Gradient background, responsive layout
|
||||
- **Interactive Buttons**: 12 test functions with visual feedback
|
||||
- **Status Display**: Real-time feedback with color-coded results
|
||||
- **Mobile-Optimized**: Touch-friendly interface
|
||||
|
||||
#### 2. Test Categories
|
||||
|
||||
```javascript
|
||||
// Plugin Testing
|
||||
- testPlugin() // Basic plugin availability
|
||||
@@ -225,6 +255,7 @@ assets/public/
|
||||
```
|
||||
|
||||
#### 3. Plugin Integration
|
||||
|
||||
```javascript
|
||||
// Plugin Access Pattern
|
||||
window.DailyNotification = window.Capacitor.Plugins.DailyNotification;
|
||||
@@ -240,6 +271,7 @@ window.DailyNotification.scheduleDailyNotification({
|
||||
```
|
||||
|
||||
#### 4. Error Handling
|
||||
|
||||
- **Visual Feedback**: Color-coded status indicators
|
||||
- **Error Messages**: Detailed error reporting
|
||||
- **Graceful Degradation**: Fallback behavior for missing features
|
||||
@@ -247,15 +279,18 @@ window.DailyNotification.scheduleDailyNotification({
|
||||
## Plugin Integration
|
||||
|
||||
### Plugin Discovery Process
|
||||
|
||||
1. **Capacitor Startup**: Loads `capacitor.plugins.json`
|
||||
2. **Plugin Registration**: Discovers `DailyNotificationPlugin` class
|
||||
3. **JavaScript Bridge**: Creates `window.Capacitor.Plugins.DailyNotification`
|
||||
4. **Method Exposure**: Exposes `@PluginMethod` annotated methods
|
||||
|
||||
### Plugin Class Structure
|
||||
|
||||
**Location**: `android/plugin/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.java`
|
||||
|
||||
**Key Methods** (from `@PluginMethod` annotations):
|
||||
|
||||
```java
|
||||
@PluginMethod
|
||||
public void configure(PluginCall call) { ... }
|
||||
@@ -289,15 +324,18 @@ public void openExactAlarmSettings(PluginCall call) { ... }
|
||||
```
|
||||
|
||||
### Supporting Classes (34 files)
|
||||
|
||||
The plugin includes a comprehensive set of supporting classes:
|
||||
|
||||
**Core Components**:
|
||||
|
||||
- `BootReceiver.java` - Handles system boot events
|
||||
- `DailyNotificationReceiver.java` - Handles notification events
|
||||
- `DailyNotificationScheduler.java` - Manages notification scheduling
|
||||
- `DailyNotificationFetcher.java` - Handles content fetching
|
||||
|
||||
**Storage & Database**:
|
||||
|
||||
- `DailyNotificationStorage.java` - Storage abstraction
|
||||
- `DailyNotificationStorageRoom.java` - Room database implementation
|
||||
- `DailyNotificationDatabase.java` - Database definition
|
||||
@@ -305,6 +343,7 @@ The plugin includes a comprehensive set of supporting classes:
|
||||
- `entities/` - Database entities (3 files)
|
||||
|
||||
**Management & Utilities**:
|
||||
|
||||
- `PermissionManager.java` - Permission handling
|
||||
- `ChannelManager.java` - Notification channel management
|
||||
- `DailyNotificationExactAlarmManager.java` - Exact alarm management
|
||||
@@ -312,6 +351,7 @@ The plugin includes a comprehensive set of supporting classes:
|
||||
- `DailyNotificationPerformanceOptimizer.java` - Performance optimization
|
||||
|
||||
**Workers & Background Tasks**:
|
||||
|
||||
- `DailyNotificationWorker.java` - Main background worker
|
||||
- `DailyNotificationFetchWorker.java` - Content fetching worker
|
||||
- `DailyNotificationMaintenanceWorker.java` - Maintenance tasks
|
||||
@@ -321,9 +361,11 @@ The plugin includes a comprehensive set of supporting classes:
|
||||
## Build Configuration
|
||||
|
||||
### app/build.gradle
|
||||
|
||||
**Purpose**: App-level build configuration and dependencies
|
||||
|
||||
**Key Dependencies**:
|
||||
|
||||
```gradle
|
||||
dependencies {
|
||||
// Capacitor Core
|
||||
@@ -340,12 +382,13 @@ dependencies {
|
||||
implementation "androidx.work:work-runtime-ktx:2.9.0"
|
||||
implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
|
||||
|
||||
// Cordova Compatibility
|
||||
// Cordova Compatibility (only if shipping Cordova shims)
|
||||
implementation project(':capacitor-cordova-android-plugins')
|
||||
}
|
||||
```
|
||||
|
||||
**Build Configuration**:
|
||||
|
||||
```gradle
|
||||
android {
|
||||
namespace "com.timesafari.dailynotification"
|
||||
@@ -362,10 +405,12 @@ android {
|
||||
```
|
||||
|
||||
### capacitor.build.gradle
|
||||
|
||||
**Purpose**: Auto-generated Capacitor configuration
|
||||
**Note**: Regenerated on each `npx cap sync` - should not be manually edited
|
||||
|
||||
**Manifest Hygiene (Quick Scan)**
|
||||
|
||||
- [ ] `<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>`
|
||||
- [ ] `<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM"/>` (if you truly need exact)
|
||||
- [ ] `<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>`
|
||||
@@ -376,6 +421,7 @@ android {
|
||||
## Runtime Behavior
|
||||
|
||||
### App Startup Sequence
|
||||
|
||||
1. **Android System**: Launches `MainActivity`
|
||||
2. **Capacitor Initialization**: Loads Capacitor runtime
|
||||
3. **Plugin Discovery**: Scans `capacitor.plugins.json` for plugins
|
||||
@@ -385,6 +431,7 @@ android {
|
||||
7. **Plugin Availability**: `window.Capacitor.Plugins.DailyNotification` becomes available
|
||||
|
||||
### Plugin Method Execution Flow
|
||||
|
||||
```
|
||||
JavaScript Call
|
||||
↓
|
||||
@@ -400,6 +447,7 @@ JavaScript Promise Resolution
|
||||
```
|
||||
|
||||
### Background Processing
|
||||
|
||||
- **WorkManager**: Handles background content fetching
|
||||
- **AlarmManager**: Manages notification scheduling
|
||||
- **BootReceiver**: Reschedules notifications after reboot
|
||||
@@ -408,14 +456,17 @@ JavaScript Promise Resolution
|
||||
## Testing Capabilities
|
||||
|
||||
### Interactive Testing Features
|
||||
|
||||
The test app provides comprehensive testing capabilities:
|
||||
|
||||
#### 1. Plugin Availability Testing
|
||||
|
||||
- **Basic Detection**: Verify plugin is loaded and accessible
|
||||
- **Method Availability**: Check if specific methods are callable
|
||||
- **Error Handling**: Test error conditions and edge cases
|
||||
|
||||
#### 2. Notification Testing
|
||||
|
||||
- **Immediate Notifications**: Test instant notification display
|
||||
- **Scheduled Notifications**: Test time-based notification scheduling
|
||||
- **Reminder Testing**: Test daily reminder functionality
|
||||
@@ -545,6 +596,10 @@ This architecture serves as both a practical testing tool and a reference implem
|
||||
|
||||
**Status Matrix MUST include:** `postNotificationsGranted`, `exactAlarmGranted`, `channelEnabled`, `batteryOptimizationsIgnored`, `canScheduleNow`.
|
||||
|
||||
### Exact-Alarm Decision Rule (User-Visible)
|
||||
If `SCHEDULE_EXACT_ALARM` is **granted** → schedule with `setExactAndAllowWhileIdle`.
|
||||
If **denied or quota-limited** → schedule via WorkManager (exp backoff + jitter) and surface `E_EXACT_ALARM_DENIED` (with "Degraded timing — Doze may delay" hint).
|
||||
|
||||
## Permission & Settings Truth Table
|
||||
|
||||
| Symptom | Likely Cause | Action |
|
||||
@@ -569,6 +624,11 @@ graph TD
|
||||
G --> H
|
||||
H --> I[NotificationReceiver]
|
||||
I --> J[UI Update]
|
||||
|
||||
%% Error paths
|
||||
C -->|Validation Error| K[Canonical Error]
|
||||
D -->|Use-case Error| K
|
||||
K --> L[JavaScript Promise Rejection]
|
||||
```
|
||||
|
||||
## Cordova vs Capacitor Assets – Accuracy Note
|
||||
|
||||
@@ -532,7 +532,7 @@ public class SecureNetworkClient {
|
||||
```
|
||||
|
||||
#### Key Features
|
||||
- **Export Control**: Minimize exported components
|
||||
- **Export Control**: Minimize exported components (see Manifest Hygiene checklist)
|
||||
- **Permission Requirements**: Require permissions for exported components
|
||||
- **Intent Validation**: Validate incoming intents
|
||||
- **Security Review**: Regular security audits
|
||||
@@ -862,6 +862,7 @@ interface ScheduleResponse {
|
||||
- [ ] Returns stable error codes with hints
|
||||
- [ ] Maps native exceptions to canonical errors
|
||||
- [ ] Provides user-friendly error messages
|
||||
- [ ] Rejects unknown keys with single joined message
|
||||
|
||||
### Reliability
|
||||
- [ ] Reboot scenarios reliably deliver notifications
|
||||
@@ -916,6 +917,7 @@ By following this plan, the test app will become more maintainable, reliable, an
|
||||
- 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.
|
||||
- "Copy Diagnostics (JSON)" button functional.
|
||||
|
||||
### Phase 2 DoD
|
||||
- Test UI split into modular scenarios with fixtures.
|
||||
@@ -942,6 +944,7 @@ By following this plan, the test app will become more maintainable, reliable, an
|
||||
- [ ] Logs include event IDs (start/finish/error)
|
||||
- [ ] Status Matrix field(s) updated if capability changed
|
||||
- [ ] Runbooks section touched if behavior changed
|
||||
- [ ] No new events without ID (keeps logs grep-able)
|
||||
|
||||
## Test Matrix
|
||||
|
||||
@@ -951,6 +954,7 @@ By following this plan, the test app will become more maintainable, reliable, an
|
||||
| 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 |
|
||||
| Doze idle window | scheduleDailyNotification | Device in idle | Fallback path taken; logged `EVT_DOZE_FALLBACK_TAKEN`; no crash |
|
||||
|
||||
## Error Codes (canonical)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user