Add timeline tracking features with database schema updates

- Introduced new tables `timeline_footprints` and `timeline_activities` to manage employee location data and activity records.
- Updated `company_settings` to include `gps_interval_seconds` and `checkout_warning_radius_meters` for enhanced tracking configuration.
- Implemented foreign key constraints to ensure data integrity between new tables and existing `employees`, `customers`, and `visits` tables.
- Created services and controllers for handling timeline activities and footprints, including ingestion and retrieval of data.
- Enhanced DTOs and validation logic to support new fields and ensure correct data formats in API requests.
- Added unit and integration tests to validate the new functionalities and ensure proper handling of timeline records.
- Created migration scripts to apply the necessary database schema changes for the new features.

test/company-settings.e2e-spec.ts

@@ -107,4 +107,23 @@ describe('Company settings (e2e)', () => {
       (updated.body as { cycleStartDate: number }).cycleStartDate,
     );
   });
+
+  it('upserts timeline tracking settings', async () => {
+    const updated = await request(app.getHttpServer())
+      .patch('/settings')
+      .set('Authorization', `Bearer ${adminAccessToken}`)
+      .send({
+        gpsIntervalSeconds: 15,
+        checkoutWarningRadiusMeters: 300,
+      })
+      .expect(200);
+
+    expect((updated.body as { gpsIntervalSeconds: number }).gpsIntervalSeconds).toBe(
+      15,
+    );
+    expect(
+      (updated.body as { checkoutWarningRadiusMeters: number })
+        .checkoutWarningRadiusMeters,
+    ).toBe(300);
+  });
 });

test/timeline.e2e-spec.ts

@@ -0,0 +1,183 @@
+import { INestApplication } from '@nestjs/common';
+import { Test, TestingModule } from '@nestjs/testing';
+import { eq } from 'drizzle-orm';
+import request from 'supertest';
+import { App } from 'supertest/types';
+import { AppModule } from '../src/app.module';
+import { configureApp } from '../src/common/configure-app';
+import { DateTime } from '../src/common/value-objects/date-time/date-time';
+import { DRIZZLE, type DrizzleDB } from '../src/database/database.module';
+import {
+  privilegeDetails,
+  privilegeKeys,
+  privileges,
+  users,
+} from '../src/database/schema';
+import { PRIVILEGE_ACTIONS } from '../src/modules/privileges/privilege-action';
+import { registerAndActivate } from './helpers/activate-user';
+
+describe('Timeline (e2e)', () => {
+  let app: INestApplication<App>;
+  let db: DrizzleDB;
+
+  const password = 'password123';
+  const adminUsername = `tl_admin_${Date.now()}`;
+  const otherUsername = `tl_other_${Date.now()}`;
+
+  let adminAccessToken: string;
+  let adminUserId: string;
+  let otherAccessToken: string;
+  let employeeId: string;
+
+  beforeAll(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    configureApp(app, {
+      NODE_ENV: 'test',
+      SWAGGER_ENABLED: 'false',
+    });
+    await app.init();
+    db = app.get(DRIZZLE);
+
+    const admin = await registerAndActivate(app, db, adminUsername, password);
+    adminAccessToken = admin.accessToken;
+    adminUserId = admin.userId;
+
+    const other = await registerAndActivate(app, db, otherUsername, password);
+    otherAccessToken = other.accessToken;
+
+    const now = Date.now();
+    const [priv] = await db
+      .insert(privileges)
+      .values({
+        name: 'Timeline Admin',
+        code: `TL_ADMIN_${now}`,
+        status: 'active',
+        createdAt: now,
+        updatedAt: now,
+        createdBy: adminUserId,
+        updatedBy: adminUserId,
+      })
+      .returning();
+
+    const keys = await db.select().from(privilegeKeys);
+    await db.insert(privilegeDetails).values(
+      keys.flatMap((key) =>
+        PRIVILEGE_ACTIONS.map((action) => ({
+          privilegeId: priv.id,
+          privilegeKeyId: key.id,
+          action,
+          value: true,
+        })),
+      ),
+    );
+    await db
+      .update(users)
+      .set({ privilegeId: priv.id, updatedAt: Date.now() })
+      .where(eq(users.id, adminUserId));
+
+    const login = await request(app.getHttpServer())
+      .post('/auth/login')
+      .send({ username: adminUsername, password })
+      .expect(200);
+    adminAccessToken = (login.body as { accessToken: string }).accessToken;
+
+    await request(app.getHttpServer())
+      .patch('/settings')
+      .set('Authorization', `Bearer ${adminAccessToken}`)
+      .send({
+        cycleStartDate: '2026-01-05',
+        gpsIntervalSeconds: 10,
+        checkoutWarningRadiusMeters: 250,
+      })
+      .expect(200);
+
+    const suffix = Date.now().toString().slice(-6);
+    const employee = await request(app.getHttpServer())
+      .post('/employees')
+      .set('Authorization', `Bearer ${adminAccessToken}`)
+      .send({
+        code: `TL_E_${suffix}`,
+        name: 'Timeline Tester',
+        phone: '+6281234567891',
+        position: 'sales',
+        status: 'active',
+        userId: adminUserId,
+      })
+      .expect(201);
+    employeeId = (employee.body as { id: string }).id;
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('returns timeline config for mobile attendance privilege', async () => {
+    const response = await request(app.getHttpServer())
+      .get('/timeline/config')
+      .set('Authorization', `Bearer ${adminAccessToken}`)
+      .expect(200);
+
+    expect(response.body).toEqual({
+      gpsIntervalSeconds: 10,
+      checkoutWarningRadiusMeters: 250,
+    });
+  });
+
+  it('forbids timeline config without permission', async () => {
+    await request(app.getHttpServer())
+      .get('/timeline/config')
+      .set('Authorization', `Bearer ${otherAccessToken}`)
+      .expect(403);
+  });
+
+  it('ingests footprints and returns them on admin timeline query', async () => {
+    const recordedAt = DateTime.fromUnixMs(Date.now()).startOfDay().value + 3_600_000;
+
+    const ingest = await request(app.getHttpServer())
+      .post('/timeline/footprints')
+      .set('Authorization', `Bearer ${adminAccessToken}`)
+      .send({
+        points: [
+          { latitude: -6.2, longitude: 106.8, recordedAt },
+          { latitude: -6.201, longitude: 106.801, recordedAt: recordedAt + 5000 },
+        ],
+      })
+      .expect(201);
+
+    expect((ingest.body as { inserted: number }).inserted).toBe(2);
+
+    const today = DateTime.fromUnixMs(Date.now()).startOfDay().format().slice(0, 10);
+    const day = await request(app.getHttpServer())
+      .get('/timeline')
+      .query({ date: today, employeeId })
+      .set('Authorization', `Bearer ${adminAccessToken}`)
+      .expect(200);
+
+    const body = day.body as {
+      date: string;
+      footprints: Array<{ latitude: number; longitude: number }>;
+      activities: unknown[];
+    };
+    expect(body.date).toBe(today);
+    expect(body.footprints.length).toBeGreaterThanOrEqual(2);
+    expect(body.activities).toEqual([]);
+  });
+
+  it('returns activities-only timeline for the current user', async () => {
+    const today = DateTime.fromUnixMs(Date.now()).startOfDay().format().slice(0, 10);
+    const me = await request(app.getHttpServer())
+      .get('/timeline/me')
+      .query({ date: today })
+      .set('Authorization', `Bearer ${adminAccessToken}`)
+      .expect(200);
+
+    const body = me.body as { date: string; activities: unknown[] };
+    expect(body.date).toBe(today);
+    expect(Array.isArray(body.activities)).toBe(true);
+    expect(body).not.toHaveProperty('footprints');
+  });
+});