ZVMS 4 (Zhenhai Volunteer Management System 4) is a sophisticated Vue.js-based web application designed for managing volunteer activities and hours tracking at Zhenhai High School. The system represents a complete architectural overhaul from previous versions, transitioning from SQLite to MongoDB and implementing a modern, scalable frontend architecture with comprehensive offline capabilities and mobile-first design.
Frontend Framework & Core Dependencies:
- Vue 3.5.17 with Composition API
- TypeScript 5.8.3 for type safety
- Vite (rolldown-vite) as build tool and development server
- Pinia for state management with persistence
- Vue Router 4.5.1 for navigation
- Vue I18n for internationalization (Chinese & English)
UI Framework & Design:
- Element Plus 2.10.3 as primary UI component library
- Vant 4.9.20 for mobile-optimized components
- UnoCSS for atomic CSS styling
- Chart.js & Vue-ChartJS for data visualization
- Animate.css for animations
Development & Testing:
- Vitest for unit testing
- Cypress for end-to-end testing
- ESLint & Prettier for code quality
- Husky for Git hooks
The application implements comprehensive PWA functionality:
- Service Worker registration with automatic updates
- Offline capability with cached resources
- App manifest for installability on mobile devices
- Background sync for data synchronization
- Push notifications support framework
Authentication System:
- RSA encryption for secure password transmission
- JWT token-based authentication with refresh mechanisms
- Role-based access control with multiple permission levels:
system- System administratoradmin- School administratorauditor- Activity auditordepartment- Department headsecretary- Class secretarystudent- Regular student
User Features:
- Comprehensive user profiles with class affiliations
- Password strength validation with mandatory resets
- Activity history tracking
- Personal volunteer hour summaries
Activity Types & Classifications:
- On-campus activities (校内义工) - 25 hours required
- Off-campus activities (校外义工) - 15 hours required
- Social practice (社会实践) - 18 hours required
- Hybrid activities - Flexible hour allocation
Activity Origins:
- Prize activities - Award-based volunteer work
- Labor activities - School maintenance tasks
- Club activities - Student organization events
- Organization activities - Official student body work
- Tasks - Individual assignments
- Occasions - School ceremonies and events
- Import - Legacy data migration
- Other - Miscellaneous activities
Advanced Features:
- Batch member management with Excel import/export
- Real-time activity statistics with descriptive analytics
- Activity merging capabilities for administrators
- Duration recommendation system based on school regulations
- Approval workflow with multi-level authorization
Group Types:
- Class groups - Academic class management
- Permission groups - Role-based access control
- General groups - Custom organizational units
Management Features:
- User assignment to multiple groups
- Permission inheritance through group membership
- Class-specific activity tracking
- Bulk user operations (create, modify, delete)
- Group statistics and compliance reporting
Comprehensive Time Analysis:
- Individual progress tracking against requirements
- Percentile rankings within grade and group
- Detailed statistical breakdowns (mean, median, mode, variance)
- Compliance monitoring with deficit calculations
- Cross-category hour exchanges with discount algorithms
Reporting & Visualization:
- Interactive charts (bar, doughnut, progress indicators)
- Export capabilities (Excel, CSV formats)
- Real-time dashboard with progress indicators
- Comparative analytics across different time periods
Export System:
- Asynchronous task processing for large datasets
- Multiple format support (Excel, CSV)
- Progress tracking with real-time updates
- Filtered exports by date range, user groups
- Template generation for bulk imports
The application uses Pinia for centralized state management with the following key stores:
User Store (useUserStore):
- Authentication state and user information
- Permission levels and group memberships
- Volunteer hour summaries and progress tracking
- Password reset workflows
Header Store (useHeaderStore):
- Navigation state management
- Mobile/desktop layout switching
- Breadcrumb navigation
Groups Store (useGroupsStore):
- Group information caching
- Permission-based access control
- Class and organizational unit management
RESTful API Design:
- Axios-based HTTP client with interceptors
- JWT token management with automatic refresh
- Error handling with user-friendly notifications
- Request/response transformation for data consistency
- Timeout handling and retry mechanisms
Key API Endpoints:
/api/v2/users/*- User management and authentication/api/v2/activities/*- Activity CRUD operations/api/v2/groups/*- Group management/api/v2/statistics/*- Analytics and reporting/api/v2/time/*- Time tracking and calculations
XueHai Tablet Integration:
- User Agent detection for school-issued Samsung tablets
- Platform-specific feature restrictions for compliance
- Automatic user identification through WebView interface
- Responsive design optimized for tablet form factors
Device Detection Logic:
export const pad = () => {
return result.device.vendor === 'Samsung' && result.os.name === 'Android'
}Supported Tablet Models:
- Samsung SM-P615C, SM-P200, SM-P335
Multi-language Support:
- Chinese (Simplified) - Primary language
- English - Secondary language
- Dynamic language switching with persistent preferences
- Contextual translations for complex UI elements
- Number and date localization
Client-Side Security:
- RSA encryption for sensitive data transmission
- XSS protection through DOMPurify integration
- CSRF protection via HTTP headers
- Input validation with async-validator
- Secure token storage with automatic cleanup
Privacy & Compliance:
- Microsoft Clarity integration for usage analytics
- Data minimization principles in local storage
- Audit logging for administrative actions
- Permission-based data access controls
Vite Configuration:
- Tree shaking for minimal bundle size
- Code splitting for optimal loading
- Legacy browser support through polyfills
- Asset optimization with automatic compression
Bundle Analysis:
- Lazy loading for route-based code splitting
- Component auto-import to reduce bundle bloat
- Icon optimization with unplugin-icons
- CSS purging with UnoCSS
Caching Strategies:
- Service Worker caching for offline functionality
- API response caching with intelligent invalidation
- Asset caching with version-based busting
- State persistence for improved UX
Memory Management:
- Component lifecycle optimization
- Event listener cleanup
- Computed property caching
- Large dataset pagination
Linting & Formatting:
{
"lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix",
"format": "prettier --write src/"
}Git Workflow:
- Conventional commits with Commitizen
- Pre-commit hooks via Husky
- Automated formatting on staged files
- Branch protection with required reviews
Unit Testing:
- Vitest with JSDOM environment
- Component testing with Vue Test Utils
- Mock implementations for API calls
E2E Testing:
- Cypress for integration testing
- Cross-browser compatibility testing
- Mobile viewport testing scenarios
Production Build:
npm run build-only # TypeScript compilation and Vite build
npm run type-check # Standalone type checkingEnvironment Configuration:
- Development: Local API server (localhost:8000)
- Production: HTTPS API endpoint (api.zvms.site)
Current Deployment:
- Vercel for primary hosting
- Netlify as backup deployment
- CDN optimization for global asset delivery
-
Enhanced Mobile Experience
- Native app wrapper with Capacitor
- Push notification implementation
- Offline-first data synchronization
-
Advanced Analytics
- Machine learning for activity recommendations
- Predictive analytics for hour completion
- Advanced data visualization dashboards
-
Integration Expansion
- Third-party calendar integration
- Email notification system
- SMS/messaging platform integration
Areas for Improvement:
- Component library consistency - Standardize on Element Plus vs Vant usage
- API error handling - Implement more granular error recovery
- Testing coverage - Expand unit and integration test suites
- Performance monitoring - Add runtime performance tracking
Monitoring & Observability:
- Error tracking through integrated logging
- Performance metrics via Web Vitals
- User analytics through Clarity integration
ZVMS 4 represents a significant advancement in educational technology for volunteer management. The application successfully balances complex functionality requirements with user experience considerations, providing a robust, scalable, and maintainable solution for volunteer activity tracking and management.
The modern Vue 3 + TypeScript architecture, combined with comprehensive PWA capabilities and mobile-first design, positions the system for long-term sustainability and future enhancements. The strong focus on internationalization, accessibility, and cross-platform compatibility ensures broad usability across diverse user bases.
Key strengths include the sophisticated role-based permission system, comprehensive analytics and reporting capabilities, and the seamless integration with school-specific hardware (XueHai tablets). The system's offline capabilities and progressive web app features make it particularly suitable for educational environments with varying connectivity conditions.
The codebase demonstrates professional software development practices with comprehensive type safety, automated testing, and modern development tooling, making it an excellent foundation for continued development and maintenance.