cola-attendance

中文 | English

An open-source attendance and duty scheduling system for real-world shift scenarios, including:

• Organization and permission management (department, user, role, menu)
• Scheduling (shift definitions and duty schedules)
• Attendance (devices, punch records, attendance results)
• Rule engine (DSL/SpEL)
• Scheduled jobs and E2E automation scripts

This project is refactored from a production legacy attendance system.
The roadmap also includes AI assistant, duty bulletin/public board, and data analytics sub-systems.

0. First Things First

What this repository is

• A runnable full-stack system (attendance-backend + attendance-frontend)
• Not just a docs/demo repo: docs and scripts are support materials for the running product
• The rule engine is an integrated production module, used in real attendance result calculation

What problem it solves

• Replace manual attendance tracking in small and medium-sized organizations
• Standardize scheduling, punch-in/out ingestion, attendance result generation, and rule-based judgment
• Provide an extensible base for organizations that need customizable attendance rules

30-second understanding

• If you only run backend + database, you can already use the core APIs and Swagger
• If you also run frontend, you get an end-to-end usable admin UI
• If you run scripts in scripts/, you can validate the full attendance flow automatically

Fastest way to run

# 1) optional: set host ports when 3306/8080 are occupied
# export MYSQL_PORT=3308
# export BACKEND_PORT=18082

# 2) start backend + mysql
docker compose up -d

# 3) open swagger
# default: http://localhost:8080/swagger-ui.html
# custom:  http://localhost:<BACKEND_PORT>/swagger-ui.html

1. Tech Stack

• Backend: Spring Boot 3, JDK 21, MyBatis-Plus, Spring Security, JWT
• Frontend: Vue 3, Vite, Element Plus
• Database: MySQL 8+

2. Repository Structure

cola-attendance/
|-- attendance-backend/      # Java backend
|-- attendance-frontend/     # Vue frontend
|-- docs/                    # DB scripts, design docs, E2E docs
|-- scripts/                 # E2E automation (Python + PowerShell)
|-- docker-compose.yml       # Local/demo orchestration
`-- TASKS.md                 # Project task list and progress

3. Core Features

• Auth and access control: JWT-based login, request header uses token
• System module: CRUD for department/user/role/menu, with tree structure support
• Scheduling module: shift management, schedule maintenance, batch scheduling/cancel
• Attendance module: device management, punch records (including Excel import and device callback), attendance results
• Rule engine: configurable attendance decision rules through DSL (SpEL)
• Scheduled jobs:
  • Generate empty attendance records daily at 01:00
  • Run end-of-day supplement daily at 23:55

4. Quick Start (Local Development)

4.1 Prerequisites

• JDK 21
• Maven 3.8+
• MySQL 8+
• Node.js 18+ (frontend only)

4.2 Initialize Database

1. Run schema scripts:
   • docs/attendance-db-schema.sql
   • docs/attendance-db-schema-alter.sql
2. Initialize admin user:
   • attendance-backend/src/main/resources/sql/init-admin.sql

Default admin account:

• Username: admin
• Password: 123456

4.3 Start Backend

cd attendance-backend
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Available after startup:

• Swagger: http://localhost:8080/swagger-ui.html

4.4 Start Frontend (Optional)

cd attendance-frontend
npm install
npm run dev

Default URL: http://localhost:5173
Dev proxy: /api -> http://localhost:8080 (see attendance-frontend/vite.config.js)

5. Docker (Backend + MySQL)

docker compose up -d

Notes:

• Starts mysql and backend
• MySQL first-time init is automatic (runs SQL in /docker-entrypoint-initdb.d):
  • docs/attendance-db-schema.sql
  • docs/attendance-db-schema-alter.sql
  • attendance-backend/src/main/resources/sql/init-admin.sql
• Default host ports:
  • MySQL: 3306 (from ${MYSQL_PORT:-3306})
  • Backend: 8080 (from ${BACKEND_PORT:-8080})
• If ports are occupied on your machine, run with custom ports:

MYSQL_PORT=3308 BACKEND_PORT=18082 docker compose up -d

• Then use:
  • Backend URL: http://localhost:<BACKEND_PORT>
  • Swagger: http://localhost:<BACKEND_PORT>/swagger-ui.html
• If you need to re-run DB init scripts, remove volume and recreate:

docker compose down -v
docker compose up -d

6. E2E Full-Flow Test

Install dependencies:

pip install -r scripts/requirements.txt

Run one full cycle:

.\scripts\full_link_cycle.ps1 -Cycles 1 -Date 2025-02-05 -SampleCount 5 -ReportDir logs

Flow includes:

• Cleanup test data
• Auto scheduling
• Punch simulation and rule triggering
• End-of-day supplement
• Correctness verification with report output

Details: docs/e2e-attendance-test.md

7. Key Environment Variables

Use environment variables for sensitive values:

Variable	Description	Example
JWT_SECRET	JWT signing secret (required in production, recommended >= 32 chars)	replace-with-random-secret
JWT_EXPIRATION_MS	Token expiration in milliseconds	86400000
SPRING_DATASOURCE_URL	JDBC URL	jdbc:mysql://mysql:3306/attendance?...
SPRING_DATASOURCE_USERNAME	DB username	root
SPRING_DATASOURCE_PASSWORD	DB password	strong-password

Script-related:

• COLA_ATTENDANCE_BASE_URL: backend base URL for E2E scripts (default http://localhost:8080)

8. API Usage Convention

• Login endpoint: POST /system/auth/login
• Put login token into request header: token: <jwt>

9. Project Status

Completed:

• Main capabilities in system, schedule, attendance, and rule-engine modules
• E2E automation scripts and docs

Enhancement backlog: TASKS.md

10. Contributing and License

• Contributing guide: CONTRIBUTING.md
• License: LICENSE