forked from jsnbuchanan/crowd-funder-for-time-pwa
docs: reorganize documentation structure with 7-item folder limits
- Create logical sub-folder classification for all documentation - Organize 91 migration files into component-specific folders - Separate user guides, build system, migration, and development docs - Maintain maximum 7 items per folder for easy navigation - Add comprehensive README and reorganization summary - Ensure all changes tracked in git with proper versioning Structure: - user-guides/ (3 items): user-facing documentation - build-system/ (3 items): core, platforms, automation - migration/ (6 items): assessments, testing, templates - development/ (4 items): tools and standards - architecture/, testing/, examples/ (ready for future docs) Total: 24 folders created, all within 7-item limits
This commit is contained in:
Matthew Raymer
405
docs/build-system/automation/auto-run-guide.md
Normal file
405
docs/build-system/automation/auto-run-guide.md
Normal file
@@ -0,0 +1,405 @@
|
||||
# Auto-Run Guide
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-07-12
|
||||
**Status**: 🎯 **ACTIVE** - In Use
|
||||
|
||||
## Overview
|
||||
|
||||
The TimeSafari auto-run system intelligently detects available devices and
|
||||
automatically builds and launches the app on the best available target. It
|
||||
supports Android devices/emulators, iOS devices/simulators, and Electron
|
||||
desktop apps.
|
||||
|
||||
## Features
|
||||
|
||||
### Smart Device Detection
|
||||
- **Android**: Detects real devices vs emulators using ADB
|
||||
- **iOS**: Detects real devices vs simulators using xcrun
|
||||
- **Electron**: Checks for Electron availability
|
||||
- **Priority**: Real devices preferred over simulators/emulators
|
||||
|
||||
### Build Mode Support
|
||||
- **Development**: Default mode for daily development
|
||||
- **Test**: Optimized for testing with test data
|
||||
- **Production**: Production-ready builds
|
||||
|
||||
### Platform Targeting
|
||||
- **All platforms**: Automatically detects and runs on all available
|
||||
- **Specific platform**: Target only iOS, Android, or Electron
|
||||
- **Cross-platform**: Works on macOS, Linux, and Windows
|
||||
|
||||
### Auto-Run Options
|
||||
- **Build + Auto-Run**: Single command to build and launch
|
||||
- **Smart Detection**: Automatically chooses best available target
|
||||
- **Error Handling**: Graceful fallbacks when devices unavailable
|
||||
|
||||
## Usage
|
||||
|
||||
### Auto-Run Script (Recommended)
|
||||
|
||||
```bash
|
||||
# Auto-detect and run on all available platforms (development mode)
|
||||
npm run auto-run
|
||||
|
||||
# Run in test mode
|
||||
npm run auto-run:test
|
||||
|
||||
# Run in production mode
|
||||
npm run auto-run:prod
|
||||
|
||||
# Target specific platforms
|
||||
npm run auto-run:ios
|
||||
npm run auto-run:android
|
||||
npm run auto-run:electron
|
||||
```
|
||||
|
||||
### Build Script Auto-Run
|
||||
|
||||
#### iOS Auto-Run Commands
|
||||
|
||||
```bash
|
||||
# Test build + auto-run
|
||||
npm run build:ios:test:run
|
||||
|
||||
# Production build + auto-run
|
||||
npm run build:ios:prod:run
|
||||
|
||||
# Debug build + auto-run
|
||||
npm run build:ios:debug:run
|
||||
|
||||
# Release build + auto-run
|
||||
npm run build:ios:release:run
|
||||
```
|
||||
|
||||
#### Android Auto-Run Commands
|
||||
|
||||
```bash
|
||||
# Test build + auto-run
|
||||
npm run build:android:test:run
|
||||
|
||||
# Production build + auto-run
|
||||
npm run build:android:prod:run
|
||||
|
||||
# Debug build + auto-run
|
||||
npm run build:android:debug:run
|
||||
|
||||
# Release build + auto-run
|
||||
npm run build:android:release:run
|
||||
```
|
||||
|
||||
#### Electron Auto-Run Commands
|
||||
|
||||
```bash
|
||||
# Development build + auto-run
|
||||
npm run build:electron:dev:run
|
||||
|
||||
# Test build + auto-run
|
||||
npm run build:electron:test:run
|
||||
|
||||
# Production build + auto-run
|
||||
npm run build:electron:prod:run
|
||||
```
|
||||
|
||||
### Advanced Usage
|
||||
|
||||
```bash
|
||||
# Direct script usage with options
|
||||
./scripts/auto-run.sh --test --platform=ios
|
||||
./scripts/auto-run.sh --prod --platform=android
|
||||
./scripts/auto-run.sh --auto # Skip confirmation prompts
|
||||
|
||||
# Build script with auto-run flag
|
||||
./scripts/build-ios.sh --test --auto-run
|
||||
./scripts/build-android.sh --prod --auto-run
|
||||
./scripts/build-electron.sh --test --auto-run
|
||||
|
||||
# Combine options
|
||||
./scripts/auto-run.sh --test --platform=all --auto
|
||||
```
|
||||
|
||||
### Command Line Options
|
||||
|
||||
| Option | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `--test` | Build and run in test mode | `--test` |
|
||||
| `--prod` | Build and run in production mode | `--prod` |
|
||||
| `--platform=PLATFORM` | Target specific platform | `--platform=ios` |
|
||||
| `--auto` | Skip confirmation prompts | `--auto` |
|
||||
| `--auto-run` | Auto-run after build | `--auto-run` |
|
||||
| `--help` | Show help message | `--help` |
|
||||
|
||||
**Platform Options:**
|
||||
- `ios` - iOS devices/simulators only
|
||||
- `android` - Android devices/emulators only
|
||||
- `electron` - Electron desktop app only
|
||||
- `all` - All available platforms (default)
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. Device Detection
|
||||
|
||||
**Android Detection:**
|
||||
```bash
|
||||
# Uses ADB to list devices
|
||||
adb devices
|
||||
|
||||
# Parses output to distinguish:
|
||||
# - Real devices: Physical Android phones/tablets
|
||||
# - Emulators: Android emulator instances
|
||||
```
|
||||
|
||||
**iOS Detection:**
|
||||
```bash
|
||||
# Uses xcrun to list devices
|
||||
xcrun xctrace list devices
|
||||
|
||||
# Parses output to distinguish:
|
||||
# - Real devices: Physical iPhones/iPads
|
||||
# - Simulators: iOS Simulator instances
|
||||
```
|
||||
|
||||
### 2. Build Process
|
||||
|
||||
The script automatically calls the appropriate build commands:
|
||||
|
||||
```bash
|
||||
# Development mode
|
||||
npm run build:ios:dev
|
||||
npm run build:android:dev
|
||||
npm run build:electron:dev
|
||||
|
||||
# Test mode
|
||||
npm run build:ios:test
|
||||
npm run build:android:test
|
||||
npm run build:electron:test
|
||||
|
||||
# Production mode
|
||||
npm run build:ios:prod
|
||||
npm run build:android:prod
|
||||
npm run build:electron:prod
|
||||
```
|
||||
|
||||
### 3. Launch Process
|
||||
|
||||
**Android:**
|
||||
- Real devices: Install APK and launch via ADB
|
||||
- Emulators: Use `npx cap run android`
|
||||
|
||||
**iOS:**
|
||||
- Real devices: Build release version (requires Xcode setup)
|
||||
- Simulators: Use `npx cap run ios`
|
||||
|
||||
**Electron:**
|
||||
- Launch via `npm run electron:start`
|
||||
|
||||
## Examples
|
||||
|
||||
### Development Workflow
|
||||
|
||||
```bash
|
||||
# Quick development run
|
||||
npm run auto-run
|
||||
|
||||
# Output:
|
||||
# ✅ Found 1 real Android device: ABC123DEF456
|
||||
# ✅ Found 1 iOS simulator: iPhone 15 Pro
|
||||
# ✅ Electron: available
|
||||
#
|
||||
# Available targets:
|
||||
# Android: real:ABC123DEF456
|
||||
# iOS: simulator:iPhone 15 Pro
|
||||
# Electron: available
|
||||
#
|
||||
# Continue with auto-run? (y/N): y
|
||||
#
|
||||
# 🔄 Building and running Android (real: ABC123DEF456)...
|
||||
# 🔄 Building and running iOS (simulator: iPhone 15 Pro)...
|
||||
# 🔄 Building and running Electron...
|
||||
#
|
||||
# ✅ Auto-run completed successfully! 3 platform(s) launched.
|
||||
```
|
||||
|
||||
### Test Mode with Build Scripts
|
||||
|
||||
```bash
|
||||
# iOS test build + auto-run
|
||||
npm run build:ios:test:run
|
||||
|
||||
# Android test build + auto-run
|
||||
npm run build:android:test:run
|
||||
|
||||
# Electron test build + auto-run
|
||||
npm run build:electron:test:run
|
||||
|
||||
# Output:
|
||||
# === TimeSafari iOS Build Process ===
|
||||
# 🔄 Building Capacitor version (test)...
|
||||
# 🔄 Syncing with Capacitor...
|
||||
# 🔄 Building iOS app...
|
||||
# 🔄 Auto-running iOS app...
|
||||
# ✅ iOS app launched successfully!
|
||||
# ✅ iOS build completed successfully!
|
||||
```
|
||||
|
||||
### Production Mode
|
||||
|
||||
```bash
|
||||
# Production build and run
|
||||
npm run auto-run:prod
|
||||
|
||||
# Output:
|
||||
# 🔄 Building Android (production)...
|
||||
# 🔄 Building iOS (production)...
|
||||
# 🔄 Building Electron (production)...
|
||||
#
|
||||
# ✅ Auto-run completed successfully! 3 platform(s) launched.
|
||||
```
|
||||
|
||||
## Comparison: Auto-Run Script vs Build Scripts
|
||||
|
||||
### Auto-Run Script (`auto-run.sh`)
|
||||
**Best for:**
|
||||
- Multi-platform development
|
||||
- Quick testing across devices
|
||||
- Automated workflows
|
||||
- CI/CD integration
|
||||
|
||||
**Features:**
|
||||
- Smart device detection
|
||||
- Multi-platform support
|
||||
- Interactive confirmation
|
||||
- Error recovery
|
||||
|
||||
### Build Scripts with `--auto-run`
|
||||
**Best for:**
|
||||
- Single platform development
|
||||
- Specific build configurations
|
||||
- Non-interactive workflows
|
||||
- Build customization
|
||||
|
||||
**Features:**
|
||||
- Platform-specific optimization
|
||||
- Build customization options
|
||||
- Direct control over build process
|
||||
- Integration with existing workflows
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**No devices detected:**
|
||||
```bash
|
||||
# Check Android devices
|
||||
adb devices
|
||||
|
||||
# Check iOS devices (macOS only)
|
||||
xcrun xctrace list devices
|
||||
|
||||
# Check Electron availability
|
||||
which electron
|
||||
```
|
||||
|
||||
**Build failures:**
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
npm run clean:android
|
||||
npm run clean:ios
|
||||
npm run clean:electron
|
||||
|
||||
# Then retry auto-run
|
||||
npm run auto-run
|
||||
```
|
||||
|
||||
**Permission issues:**
|
||||
```bash
|
||||
# Make script executable
|
||||
chmod +x scripts/auto-run.sh
|
||||
|
||||
# Check ADB permissions (Android)
|
||||
adb kill-server
|
||||
adb start-server
|
||||
```
|
||||
|
||||
### Platform-Specific Issues
|
||||
|
||||
**Android:**
|
||||
- Ensure ADB is in PATH
|
||||
- Enable USB debugging on device
|
||||
- Accept device authorization prompt
|
||||
- Check device is in "device" state (not "unauthorized")
|
||||
|
||||
**iOS:**
|
||||
- Requires macOS with Xcode
|
||||
- Ensure Xcode command line tools installed
|
||||
- Check iOS Simulator is available
|
||||
- For real devices: Requires proper certificates
|
||||
|
||||
**Electron:**
|
||||
- Ensure Electron is installed globally or locally
|
||||
- Check Node.js version compatibility
|
||||
- Verify build dependencies are installed
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable verbose logging by modifying the script:
|
||||
|
||||
```bash
|
||||
# Add debug logging to auto-run.sh
|
||||
set -x # Enable debug mode
|
||||
```
|
||||
|
||||
## Integration with CI/CD
|
||||
|
||||
The auto-run script can be integrated into CI/CD pipelines:
|
||||
|
||||
```yaml
|
||||
# Example GitHub Actions workflow
|
||||
- name: Auto-run tests
|
||||
run: |
|
||||
npm run auto-run:test --auto
|
||||
env:
|
||||
# Set environment variables for CI
|
||||
CI: true
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Development Workflow
|
||||
1. **Daily development**: Use `npm run auto-run` for quick testing
|
||||
2. **Testing**: Use `npm run auto-run:test` before commits
|
||||
3. **Production**: Use `npm run auto-run:prod` for final testing
|
||||
4. **Single platform**: Use `npm run build:ios:test:run` for focused work
|
||||
|
||||
### Device Management
|
||||
1. **Keep devices connected**: Reduces detection time
|
||||
2. **Use consistent device names**: Helps with identification
|
||||
3. **Regular cleanup**: Clear old builds and caches
|
||||
|
||||
### Performance Tips
|
||||
1. **Use --auto flag**: Skip prompts in automated workflows
|
||||
2. **Target specific platforms**: Use `--platform=ios` for faster runs
|
||||
3. **Parallel execution**: Script runs platforms in sequence (can be optimized)
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Features
|
||||
- **Parallel execution**: Run multiple platforms simultaneously
|
||||
- **Device selection**: Choose specific devices when multiple available
|
||||
- **Custom build configurations**: Support for custom build modes
|
||||
- **Integration with IDEs**: VS Code and other IDE integration
|
||||
- **Performance monitoring**: Track build and launch times
|
||||
|
||||
### Contributing
|
||||
To add new features or fix issues:
|
||||
1. Modify `scripts/auto-run.sh`
|
||||
2. Update this documentation
|
||||
3. Test on multiple platforms
|
||||
4. Submit pull request
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [iOS Simulator Build and Icons](./ios-simulator-build-and-icons.md)
|
||||
- [Android Build Guide](./android-build-guide.md)
|
||||
- [Electron Build Guide](./electron-build-guide.md)
|
||||
- [Testing Guide](./testing-guide.md)
|
||||
379
docs/build-system/automation/cefpython-implementation-guide.md
Normal file
379
docs/build-system/automation/cefpython-implementation-guide.md
Normal file
@@ -0,0 +1,379 @@
|
||||
# CEFPython Implementation Guide (Revised)
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-07-12
|
||||
**Status**: ✨ **PLANNING** - Ready for Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
This guide outlines the implementation of CEFPython to deliver the TimeSafari Vue.js application as a native desktop experience. It details the integration of Chromium Embedded Framework (CEF) with a Python backend for desktop-specific operations.
|
||||
|
||||
## Architecture
|
||||
|
||||
### High-Level Diagram
|
||||
|
||||
```
|
||||
TimeSafari CEFPython Architecture
|
||||
├── Python Backend (CEFPython)
|
||||
│ ├── CEF Browser Window
|
||||
│ ├── SQLite Database Access
|
||||
│ ├── File System Operations
|
||||
│ └── Native OS Integration
|
||||
├── Vue.js Frontend (Unchanged)
|
||||
│ ├── Existing Components
|
||||
│ ├── Platform Service Integration
|
||||
│ └── Database Operations
|
||||
└── Platform Service Bridge
|
||||
├── CEFPython Platform Service
|
||||
├── IPC Communication
|
||||
└── Native API Exposure
|
||||
```
|
||||
|
||||
### Platform Service
|
||||
|
||||
A TypeScript class will act as the interface between the Vue frontend and the Python backend:
|
||||
|
||||
```typescript
|
||||
export class CEFPythonPlatformService implements PlatformService {
|
||||
async dbQuery(sql: string, params?: any[]): Promise<any[]> {
|
||||
// Call Python backend via IPC
|
||||
}
|
||||
|
||||
async exportData(fileName: string, data: string): Promise<ExportResult> {
|
||||
// Call file export via IPC
|
||||
}
|
||||
|
||||
async getPlatformInfo(): Promise<PlatformInfo> {
|
||||
return {
|
||||
platform: 'cefpython',
|
||||
capabilities: ['sqlite', 'filesystem', 'native-ui']
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Foundation Setup (Week 1)
|
||||
- [ ] Install CEFPython dependencies
|
||||
- [ ] Create Python virtual environment
|
||||
- [ ] Set up development and build tools
|
||||
- [ ] Create and test minimal CEFPython app
|
||||
- [ ] Create IPC and platform service skeleton
|
||||
|
||||
### Phase 2: SQLite Database (Week 2)
|
||||
- [ ] Implement Python SQLite wrapper
|
||||
- [ ] Setup schema initialization
|
||||
- [ ] Bridge database ops over IPC
|
||||
- [ ] Test queries and data integrity
|
||||
|
||||
### Phase 3: Native OS Integration (Week 3)
|
||||
- [ ] Implement file import/export
|
||||
- [ ] Add system tray and notifications
|
||||
- [ ] Test native menu hooks and permissions
|
||||
|
||||
### Phase 4: Build & Packaging (Week 4)
|
||||
- [ ] Create packaging and build scripts
|
||||
- [ ] Integrate with existing npm build
|
||||
- [ ] Automate cross-platform distribution
|
||||
|
||||
## Backend Implementation
|
||||
|
||||
### Main Entry
|
||||
|
||||
```python
|
||||
# main.py
|
||||
import cefpython3.cefpython as cef
|
||||
from platform_service import CEFPythonPlatformService
|
||||
from ipc_bridge import IPCBridge
|
||||
|
||||
class TimeSafariApp:
|
||||
def __init__(self):
|
||||
self.platform_service = CEFPythonPlatformService()
|
||||
self.cef_settings = {
|
||||
"debug": False,
|
||||
"log_severity": cef.LOGSEVERITY_ERROR,
|
||||
"log_file": "cef.log",
|
||||
"multi_threaded_message_loop": True,
|
||||
}
|
||||
|
||||
def initialize(self):
|
||||
cef.Initialize(settings=self.cef_settings)
|
||||
self.browser = cef.CreateBrowserSync(
|
||||
url=f"file://{os.path.abspath('dist/index.html')}"
|
||||
)
|
||||
self.ipc = IPCBridge(self.browser, self.platform_service)
|
||||
|
||||
def run(self):
|
||||
cef.MessageLoop()
|
||||
cef.Shutdown()
|
||||
```
|
||||
|
||||
### Platform Service (Python)
|
||||
|
||||
Handles local database and file system access:
|
||||
|
||||
```python
|
||||
class CEFPythonPlatformService:
|
||||
def __init__(self):
|
||||
self.db_path = self._get_db_path()
|
||||
self._init_schema()
|
||||
|
||||
def db_query(self, sql, params=None):
|
||||
with sqlite3.connect(self.db_path, check_same_thread=False) as conn:
|
||||
conn.row_factory = sqlite3.Row
|
||||
return [dict(row) for row in conn.execute(sql, params or [])]
|
||||
|
||||
def db_exec(self, sql, params=None):
|
||||
with sqlite3.connect(self.db_path, check_same_thread=False) as conn:
|
||||
cur = conn.execute(sql, params or [])
|
||||
conn.commit()
|
||||
return {"changes": cur.rowcount, "lastId": cur.lastrowid}
|
||||
|
||||
def export_data(self, file_name, data):
|
||||
try:
|
||||
path = os.path.join(self._get_downloads(), file_name)
|
||||
with open(path, 'w') as f:
|
||||
f.write(data)
|
||||
return {"success": True, "path": path}
|
||||
except Exception as e:
|
||||
return {"success": False, "error": str(e)}
|
||||
```
|
||||
|
||||
### IPC Bridge
|
||||
|
||||
Handles communication from JavaScript:
|
||||
|
||||
```python
|
||||
class IPCBridge:
|
||||
def __init__(self, browser, platform_service):
|
||||
self.browser = browser
|
||||
self.platform_service = platform_service
|
||||
bindings = cef.JavascriptBindings()
|
||||
bindings.SetFunction("callPython", self.call)
|
||||
self.browser.SetJavascriptBindings(bindings)
|
||||
|
||||
def call(self, name, args):
|
||||
handlers = {
|
||||
"dbQuery": self.platform_service.db_query,
|
||||
"dbExec": self.platform_service.db_exec,
|
||||
"exportData": self.platform_service.export_data
|
||||
}
|
||||
try:
|
||||
return {"success": True, "data": handlers[name](*args)}
|
||||
except Exception as e:
|
||||
return {"success": False, "error": str(e)}
|
||||
```
|
||||
|
||||
## Build & Packaging
|
||||
|
||||
Shell script with build modes:
|
||||
|
||||
```bash
|
||||
npm run build:web:dev
|
||||
./scripts/build-cefpython.sh --dev
|
||||
```
|
||||
|
||||
Includes PyInstaller packaging:
|
||||
|
||||
```bash
|
||||
pyinstaller --onefile --windowed --name TimeSafari main.py
|
||||
```
|
||||
|
||||
## Package.json Integration
|
||||
|
||||
### CEFPython Build Scripts
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
// CEFPython builds
|
||||
"build:cefpython": "./scripts/build-cefpython.sh",
|
||||
"build:cefpython:dev": "./scripts/build-cefpython.sh --dev",
|
||||
"build:cefpython:test": "./scripts/build-cefpython.sh --test",
|
||||
"build:cefpython:prod": "./scripts/build-cefpython.sh --prod",
|
||||
"build:cefpython:package": "./scripts/build-cefpython.sh --prod --package",
|
||||
|
||||
// Legacy aliases
|
||||
"build:desktop:cef": "npm run build:cefpython",
|
||||
"build:desktop:cef:dev": "npm run build:cefpython:dev",
|
||||
"build:desktop:cef:prod": "npm run build:cefpython:prod"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Platform Service Factory Integration
|
||||
|
||||
### Update PlatformServiceFactory
|
||||
|
||||
```typescript
|
||||
// src/services/PlatformServiceFactory.ts
|
||||
export class PlatformServiceFactory {
|
||||
private static instance: PlatformService | null = null;
|
||||
|
||||
public static getInstance(): PlatformService {
|
||||
if (!PlatformServiceFactory.instance) {
|
||||
const platform = process.env.VITE_PLATFORM || "web";
|
||||
|
||||
switch (platform) {
|
||||
case "cefpython":
|
||||
PlatformServiceFactory.instance = new CEFPythonPlatformService();
|
||||
break;
|
||||
case "electron":
|
||||
PlatformServiceFactory.instance = new ElectronPlatformService();
|
||||
break;
|
||||
case "capacitor":
|
||||
PlatformServiceFactory.instance = new CapacitorPlatformService();
|
||||
break;
|
||||
default:
|
||||
PlatformServiceFactory.instance = new WebPlatformService();
|
||||
}
|
||||
}
|
||||
return PlatformServiceFactory.instance;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
```bash
|
||||
cd cefpython
|
||||
pip install -r requirements.txt
|
||||
npm run build:cefpython:dev
|
||||
```
|
||||
|
||||
## Platform Considerations
|
||||
|
||||
### Windows
|
||||
- VC++ Redistributable
|
||||
- Registry for settings
|
||||
|
||||
### macOS
|
||||
- macOS 10.14+
|
||||
- Handle App Sandbox
|
||||
|
||||
### Linux
|
||||
- GTK dependencies
|
||||
- Provide `.desktop` launcher
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- CEF sandboxing
|
||||
- File and IPC validation
|
||||
- Data encryption & key management
|
||||
- Code signing & integrity checks
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### 1. Memory Management
|
||||
|
||||
- Implement proper cleanup
|
||||
- Monitor memory usage
|
||||
- Optimize database queries
|
||||
- Handle large datasets
|
||||
|
||||
### 2. Startup Time
|
||||
|
||||
- Optimize application startup
|
||||
- Implement lazy loading
|
||||
- Cache frequently used data
|
||||
- Minimize initialization overhead
|
||||
|
||||
### 3. Resource Usage
|
||||
|
||||
- Monitor CPU usage
|
||||
- Optimize rendering
|
||||
- Handle background tasks
|
||||
- Implement resource limits
|
||||
|
||||
## Testing
|
||||
|
||||
- Unit tests for each service
|
||||
- Integration for IPC and file access
|
||||
- End-to-end for user workflows
|
||||
|
||||
## Issues & Suggestions for Improvement
|
||||
|
||||
### 1. IPC Registration Missing in Initial Version
|
||||
You must explicitly bind Python functions to JS:
|
||||
```python
|
||||
bindings.SetFunction("callPython", self.call)
|
||||
```
|
||||
|
||||
### 2. Incorrect `IPCBridge` Constructor in Early Draft
|
||||
Original:
|
||||
```python
|
||||
def __init__(self, browser):
|
||||
```
|
||||
Fixed:
|
||||
```python
|
||||
def __init__(self, browser, platform_service):
|
||||
```
|
||||
|
||||
### 3. SQLite Threading Caveat
|
||||
Add `check_same_thread=False` or use a threading queue to avoid crashes from multi-threaded access.
|
||||
|
||||
### 4. No Vue IPC Access Description
|
||||
Specify the frontend JS API for calling Python:
|
||||
```javascript
|
||||
window.callPython('dbQuery', ['SELECT * FROM accounts'])
|
||||
```
|
||||
|
||||
### 5. Missing Cleanup in Unit Tests
|
||||
Add teardown for exported files to avoid clutter and permissions issues.
|
||||
|
||||
### 6. Logging
|
||||
Add `logging` or `structlog` to the Python service and bridge for auditability.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### 1. CEF Initialization Failures
|
||||
|
||||
```bash
|
||||
# Check CEF installation
|
||||
python -c "import cefpython3; print('CEF installed')"
|
||||
|
||||
# Verify dependencies
|
||||
pip list | grep cefpython3
|
||||
```
|
||||
|
||||
#### 2. Database Access Issues
|
||||
|
||||
```bash
|
||||
# Check database permissions
|
||||
ls -la ~/.local/share/timesafari/
|
||||
|
||||
# Verify SQLite installation
|
||||
python -c "import sqlite3; print('SQLite available')"
|
||||
```
|
||||
|
||||
#### 3. Build Failures
|
||||
|
||||
```bash
|
||||
# Clean and rebuild
|
||||
rm -rf cefpython/dist/
|
||||
rm -rf cefpython/build/
|
||||
npm run build:cefpython:dev
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
```python
|
||||
# Enable debug logging
|
||||
cef_settings = {
|
||||
"debug": True,
|
||||
"log_severity": cef.LOGSEVERITY_VERBOSE,
|
||||
"log_file": "cef_debug.log",
|
||||
}
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
This guide offers a clear and technically complete roadmap for integrating CEFPython with TimeSafari. By implementing the suggestions above, the solution will be production-ready with complete platform service integration, desktop capability, and a stable build process.
|
||||
|
||||
**Effort**: 4 weeks
|
||||
**Priority**: Medium
|
||||
**Dependencies**: Python 3.8+, CEFPython
|
||||
**Stakeholders**: Desktop development team, users
|
||||
Reference in New Issue
Block a user