CardQuery - Campus Fee Query System

Features

• Email Verification Login: Login using @wku.edu.cn email + verification code
• User Data Management: Automatically store user dormitory information to JSON files
• Scheduled Query System: Automatically query all users' water and electricity bills at 9 AM daily
• Intelligent Push Notifications: Calculate yesterday's usage and push to iOS devices
• Database Storage: SQLite database storage for query history records
• Asynchronous Email Sending: Based on Celery + Redis asynchronous task queue
• APNs Push Service: Asynchronous iOS push notification service
• RESTful API: Provides standardized API interfaces
• Redis Caching: Verification code storage and expiration management
• Data Statistics: Provides user statistics and query history analysis

System Architecture

iOS Client ←→ Flask API ←→ Redis ←→ Celery Worker ←→ SMTP Service

Login Flow

1. iOS client sends email address to API
2. API generates verification code stored in Redis, and sends email asynchronously via Celery
3. User enters verification code for verification
4. User selects dormitory information (building, floor, room)
5. Client sends verification code and dormitory information together to server
6. Server verifies verification code and saves user dormitory information to JSON file
7. Login successful, access granted

Installation and Deployment

Server Deployment

1. Environment Requirements

• Python 3.7+
• Redis server
• SMTP email service (Gmail recommended)

2. Install Dependencies

cd cardQuery
pip install -r requirements.txt

3. Configure Environment Variables

# Copy configuration template
cp doNotUpload.env.example doNotUpload.env

# Edit configuration file with actual values
nano doNotUpload.env

Configuration details:

• SMTP_USER: Gmail email address
• SMTP_PASS: Gmail app-specific password
• REDIS_HOST: Redis server address
• API_PORT: API service port

4. Start Services

# Use startup script (recommended)
python start_server.py

# Or start manually
# Start Celery Worker
celery -A verification_service.celery worker --loglevel=info

# Start Flask API (new terminal)
python app.py

User Data Viewing Tool

# View user registration info and dormitory distribution
python view_users.py

Features provided:

• Total user count statistics
• Building distribution
• Detailed user information list
• Detailed distribution by building and floor

Query History Data Viewing Tool

# View water and electricity bill query history records
python view_query_history.py

Features provided:

• Query record statistics
• Recent query record viewing
• Specific user query history
• Query failure analysis
• Old data cleanup

Scheduled Query Function

• Auto Execution: Automatically query all users' water and electricity bills at 9 AM daily
• Intelligent Push: Automatically calculate yesterday's usage and push notifications to iOS devices
• Anti-Crawling: 20-second interval between users, 10-second interval between electricity/water queries
• Database Storage: Query results stored in SQLite database
• Usage Analysis: Automatically calculate usage difference from yesterday
• Manual Trigger: Support manual query triggering via API
• Progress Display: Real-time display of query progress and estimated time
• Failure Retry: Automatically handle query failures
• Data Cleanup: Automatically clean records older than 90 days

Security Features

• Email Verification: Only allows @wku.edu.cn email login
• Verification Code Expiration: Verification codes expire after 5 minutes
• Local Storage: Sensitive data stored only on local device
• Secure Communication: All network requests use HTTPS encryption

API Interfaces

Send Verification Code

POST /api/send_code
Content-Type: application/json

{
  "email": "student@wku.edu.cn"
}

Verify Code (Simple Version)

POST /api/verify_code
Content-Type: application/json

{
  "email": "student@wku.edu.cn",
  "code": "123456"
}

Verify Code and Save Dormitory Info (Complete Version)

POST /api/verify_code_with_room
Content-Type: application/json

{
  "email": "student@wku.edu.cn",
  "code": "123456",
  "room_info": {
    "building_code": "237",
    "building_name": "Building 4 (Ju Yuan)",
    "floor_code": "2",
    "floor_name": "Floor 2",
    "room_code": "10237201",
    "room_name": "237201"
  }
}

Get User Information

GET /api/user_info/{email}

Get User Statistics

GET /api/users_stats

Get User Query History

GET /api/query_history/{email}

Get Scheduled Task Status

GET /api/scheduler/status

Manual Query Execution

POST /api/scheduler/manual_query
Content-Type: application/json

{
  "email": "student@wku.edu.cn"  // Optional, query all users if empty
}

Save Device Push Token

POST /api/device_token
Content-Type: application/json

{
  "email": "student@wku.edu.cn",
  "device_token": "device push token"
}

Get Device Token Status

GET /api/device_token/{email}

Health Check

GET /api/health

Development Configuration

Gmail SMTP Setup

1. Enable two-factor authentication
2. Generate app-specific password
3. Use app-specific password in environment configuration

Redis Configuration

Ensure Redis service is running properly:

# Start Redis (Ubuntu/CentOS)
sudo systemctl start redis

# Check status
redis-cli ping

Important Notes

1. Environment Isolation: cardQuery (server) and cardQueryApp_ios (client) are independent projects
2. Configuration Files: doNotUpload.env contains sensitive information, do not upload to version control
3. Email Restriction: Only supports @wku.edu.cn suffix email addresses
4. Dormitory Binding: Dormitory information is bound during first login and cannot be modified later; re-register if changes needed
5. Data Backup:
   • User data stored in users_data.json file
   • Query history stored in cardquery_data.db database
   • Please backup these important files regularly
6. Scheduled Tasks: Scheduled query tasks start automatically when server starts, no manual configuration needed
7. Anti-Crawling: System implements 20-second user intervals and 10-second query intervals
8. Push Function: Supports iOS APNs push for yesterday's usage statistics
9. APNs Configuration: Apple push certificates must be configured to use push functionality
10. Query Duration: Large-scale user queries require significant time, please schedule tasks appropriately
11. Database Maintenance: System automatically cleans query records older than 90 days
12. Network Requirements: Ensure client can access server API address

Contributing

Welcome to submit issues and improvement suggestions! Please ensure:

• Follow existing code style
• Add necessary comments and documentation
• Test new feature stability