sudomarcma
6.8 KiB
6.8 KiB
Nilai Clock Client - Android Time Tracking Application
📋 Project Overview
The Nilai Clock Client is a native Android application for worker time tracking, converted from a Vue.js web application using Capacitor. It provides QR code-based clock in/out functionality with background location tracking and comprehensive security features.
Current Status
- ✅ Android: Fully implemented with native features
- ❌ iOS: Not implemented (migration guide available)
- ⚠️ Web: Limited functionality (native features disabled)
📚 Complete Documentation
This project includes comprehensive documentation for development, deployment, and iOS migration:
- PROJECT_DOCUMENTATION.md - Complete project overview and architecture
- API_REFERENCE.md - Comprehensive API documentation
- IOS_MIGRATION_GUIDE.md - Step-by-step iOS migration guide
- ANDROID_IMPLEMENTATION_DETAILS.md - Android-specific details
- DATABASE_SCHEMA.md - Database schema documentation
🚀 Quick Start
Prerequisites
- Node.js: 18.x or higher (tested with 22.14.0)
- Android Studio: Latest version
- MySQL: 5.x database server
- Capacitor CLI: Included in dependencies
Project Setup
# Install dependencies
npm install
# Set up environment configuration
cp .env.example .env
# Edit .env with your configuration
Environment Configuration
Create environment files for different deployment targets:
.env.local-http (Local Development)
DB_HOST=localhost
DB_USER=your_database_user
DB_PASSWORD=your_database_password
DB_NAME=your_database_name
DB_PORT=3306
VITE_API_BASE_URL=http://192.168.36.54:3000
.env.production-server (Production)
DB_HOST=your_production_host
DB_USER=your_production_user
DB_PASSWORD=your_production_password
DB_NAME=your_production_database
DB_PORT=3306
VITE_API_BASE_URL=https://myapp.ouji.com/nilai_clock_api
Development Commands
Frontend Development
# Run frontend only
npm run dev
# Run with HTTPS (for testing native features)
npm run dev:https
Backend Development
# Run backend only
npm run backend
# Run backend with HTTPS
npm run backend:https
Full Stack Development
# Run both frontend and backend
npm run dev:all
# Run both with HTTPS
npm run dev:all:https
Android Development
Build for Android
# Switch to desired environment
npm run switch:local-http # Local HTTP
npm run switch:local-https # Local HTTPS
npm run switch:production # Production
# Build and sync to Android
npm run build:android
# Open in Android Studio
npm run open:android
Quick Build Commands
# Build for local HTTP testing
npm run build:local-http
# Build for local HTTPS testing
npm run build:local-https
# Build for production
npm run build:production
Database Setup
-
Import Schema:
mysql -u username -p database_name < 0709.sql -
Verify Tables:
- workers (user accounts)
- clock_records (time tracking)
- qr_codes (location codes)
- location_updates (background tracking)
- security_alerts (violations)
- security_checks (assessments)
🔧 Development Workflow
1. Code Changes
Make changes to Vue.js components in src/ directory.
2. Test in Browser
npm run dev:all
# Access at http://localhost:5173
3. Build for Android
npm run build:android
npm run open:android
4. Test on Android
- Use Android Studio emulator or physical device
- Test background location functionality
- Verify QR code scanning
- Check security features
📱 Key Features
Worker Features
- QR Code Clock In/Out: Scan QR codes to record attendance
- Background Location Tracking: Continuous monitoring while clocked in
- Attendance History: View personal clock in/out records
- Multi-language Support: English and other languages
- Offline Capability: Works without internet connection
Security Features
- GPS Spoofing Detection: Detects fake GPS applications
- Device Validation: UUID-based device registration
- Geofence Verification: Server-side location validation
- Security Alerts: Real-time violation logging
Technical Features
- Native Android Integration: Capacitor-based native features
- Background Services: Location tracking while app is closed
- Secure Storage: Encrypted local data storage
- API Integration: RESTful backend communication
🏗️ Architecture
Frontend Stack
- Vue 3: Progressive JavaScript framework
- Capacitor: Native runtime for web apps
- Tailwind CSS: Utility-first CSS framework
- Vite: Build tool and development server
Backend Stack
- Node.js + Express: REST API server
- MySQL 5.x: Database with MyISAM engine
- JWT: Authentication tokens
- bcrypt: Password hashing
Native Plugins
- Background Geolocation: Location tracking
- Device Info: Device identification
- Secure Storage: Encrypted preferences
- Camera: QR code scanning
- Local Notifications: Background alerts
🔐 Security Implementation
Anti-Spoofing Measures
- Blacklist-based GPS spoofing app detection
- Root/jailbreak detection
- Device integrity verification
- Real-time security monitoring
Data Protection
- JWT-based authentication
- Encrypted local storage
- HTTPS API communication
- Input validation and sanitization
📊 Production Deployment
Production API
- Endpoint: https://myapp.ouji.com/nilai_clock_api/
- Environment: Production server
- Database: MySQL 5.x with optimized schema
Android Release
- Build production version:
npm run build:production - Open Android Studio:
npm run open:android - Generate signed APK/AAB
- Deploy to Google Play Store
🔍 Troubleshooting
Common Issues
- Background location stops: Check battery optimization settings
- Camera permission denied: Guide user through Android settings
- API connection fails: Verify network configuration and endpoints
Debug Commands
# Check build output
npm run build
# Lint code
npm run lint
# Format code
npm run format
📞 Support
Development Environment
- Local IP: 192.168.36.54 (true local IP)
- VPN IP: 198.18.0.1 (TUN mode)
- Development Server: Usually runs on port 5173
- Backend Server: Usually runs on port 3000
For iOS Development
See IOS_MIGRATION_GUIDE.md for comprehensive iOS implementation guidance.
Note: This is a worker-only Android client application. Managers use the web interface for administrative functions. The app is designed for Android devices and requires specific native features that are not available on web platforms.