cyc-type-def 5.3.0 → 5.4.0

package/DOCUMENTATION.md

@@ -0,0 +1,425 @@
+# Project Documentation
+
+## 1. Project Overview
+
+This project is a comprehensive TypeScript type definition library designed to serve as the central source of truth for data contracts, domain models, and shared utilities within the ecosystem. It defines the core structures for attendance tracking, pastoral care management, education (MSJ), finance (claims), and user management.
+
+The library is intended to be consumed by other applications (likely frontend and backend services) to ensure type safety and consistency across the system.
+
+## 2. Architecture & Folder Structure
+
+The project is organized into logical domains within the `src` directory:
+
+-   **`src/classes/`**: Contains the core domain models, grouped by functional area.
+    -   `attendance/`: Models related to weekly attendance tracking.
+    -   `attendance-report/`: Models specific to attendance reporting views.
+    -   `education/`: Models for the MSJ education system (classes, students, batches).
+    -   `finance/`: Models for the claims and reimbursement system.
+    -   `flw-up/`: Models for follow-up tracking.
+    -   `pastoral-team/`: Core organizational structure (Sheep, CG, Cluster, Small Team).
+    -   `user-management/`: Application user definitions and assignments.
+    -   `*.ts` (Root): Shared base classes and generic application types (AppUser, AppPage, Base).
+-   **`src/constants/`**: Holds system-wide constants, enums, and configuration values.
+-   **`src/util/`**: Provides shared utility functions for common operations like date formatting and sorting.
+
+## 3. Core Domain Types
+
+### 3.1. Base Abstractions
+
+#### `Base`
+*File: `src/classes/Base.ts`*
+
+The foundational interface for all persistent entities in the system.
+
+```typescript
+export interface Base {
+  id: string;               // Unique identifier
+  deleted: boolean;         // Soft delete flag
+  createdAt?: number;       // Timestamp of creation
+  createdBy?: string;       // User ID who created the record
+  updatedAt?: number;       // Timestamp of last update
+  updatedBy?: string;       // User ID who last updated the record
+  remark?: string;          // Optional remarks/notes
+}
+```
+
+#### `Device`
+*File: `src/classes/Device.ts`*
+*Extends: `Base`*
+
+Represents a user device, likely for tracking app versions or device-specific settings.
+
+```typescript
+export interface Device extends Base {
+  version?: number;         // App version number on the device
+}
+```
+
+### 3.2. Pastoral Team Domain
+*Folder: `src/classes/pastoral-team/`*
+
+This domain models the organizational hierarchy: Cluster -> Small Team (ST) -> Connect Group (CG) -> Sheep (Member).
+
+#### `Sheep`
+*File: `src/classes/pastoral-team/Sheep.ts`*
+*Implements: `Base`*
+
+Represents a member of the church. This is a central entity linked to attendance, education, and pastoral care.
+
+**Properties:**
+-   **Pastoral Info:**
+    -   `st: string`: Small Team ID.
+    -   `cluster: string`: Cluster ID.
+    -   `cg: string`: Connect Group ID.
+    -   `status: string`: Membership status (e.g., 'OM', 'NB').
+    -   `discipler?: string`: ID of the discipler.
+-   **Personal Info:**
+    -   `name: string`: Full name.
+    -   `age?: number`: Age.
+    -   `birthday?: number`: Birthday timestamp.
+    -   `isBaptised?: boolean`: Baptism status.
+    -   `dtBaptism?: number`: Baptism date timestamp.
+    -   `contact?: string`: Contact number.
+    -   `gender?: string`: Gender.
+    -   `nric?: string`: National ID.
+    -   `address?: string`: Residential address.
+-   **Attendance & System:**
+    -   `attCnt: number`: Attendance count (likely for statistics).
+    -   `hideAtt?: boolean`: Flag to hide from attendance lists.
+    -   `show: boolean`: Flag to show in MSJ progress tracker.
+    -   `arrFlwUpCnt?: number[]`: Array of follow-up counts (not submitted).
+    -   `msj?: Map<String, MsjStudBatch>`: Map of MSJ student batches.
+    -   `msjRecords?: Map<String, MsjStudBatch[]>`: Historical MSJ records.
+
+#### `CG` (Connect Group)
+*File: `src/classes/pastoral-team/CG.ts`*
+*Implements: `Base`*
+
+Represents a Connect Group.
+
+**Properties:**
+-   `name: string`: Group name.
+-   `st: string`: Parent Small Team ID.
+-   `cluster: string`: Parent Cluster ID.
+-   `cglCnt?: number`: Count of CGLs (Connect Group Leaders).
+-   `sglCnt?: number`: Count of SGLs (Section Group Leaders).
+-   `cglName?: string`: Name of the CGL.
+-   `rptRowIdx?: number`: Row index for attendance reports.
+
+#### `SmallTeam`
+*File: `src/classes/pastoral-team/SmallTeam.ts`*
+*Implements: `Base`*
+
+Represents a Small Team, which contains multiple CGs.
+
+**Properties:**
+-   `name: string`: Team name.
+-   `cluster: string`: Parent Cluster ID.
+
+#### `Cluster`
+*File: `src/classes/pastoral-team/Cluster.ts`*
+*Implements: `Base`*
+
+Represents a Cluster, the highest level of the local organizational hierarchy.
+
+**Properties:**
+-   `name: string`: Cluster name.
+
+### 3.3. Attendance Domain
+*Folder: `src/classes/attendance/`*
+
+Models for tracking weekly service and CG attendance.
+
+#### `Attendance`
+*File: `src/classes/attendance/Attendance.ts`*
+*Extends: `Title`*
+
+Represents the attendance record for a specific week (Title) within a specific context (CG, Small Team, Cluster).
+
+**Properties:**
+-   `idTitle: string`: Reference to the Title (week).
+-   `idCg: string`: ID of the CG.
+-   `idSt: string`: ID of the Small Team.
+-   `idCluster: string`: ID of the Cluster.
+-   `timestamp: number`: Submission timestamp.
+-   `timeTaken?: number`: Time taken to fill attendance (seconds).
+-   `arrSessionAttendance: SessionAttendance[]`: Detailed attendance per session.
+
+**Key Methods:**
+-   `setSessionAttendance(arrSession: Session[])`: Initializes or updates session attendance records, preserving existing data where possible.
+-   `deepCopySessionAttendance(...)`: Creates a deep copy of session attendance arrays.
+-   `clearArrAttSheep(...)`: Filters out sheep that don't belong to the specified CG.
+
+#### `SessionAttendance`
+*File: `src/classes/attendance/SessionAttendance.ts`*
+*Extends: `Session`*
+
+Stores attendance data for a specific session (e.g., "Service", "CG Meeting").
+
+**Properties:**
+-   `arrSheep: AttSheep[]`: List of members and their attendance status.
+-   `input: string`: Search input filter.
+-   `sky: DisplayAttendance`: Aggregated stats for "Sky" method.
+-   `ground: DisplayAttendance`: Aggregated stats for "Ground" method.
+-   `total: DisplayAttendance`: Total aggregated stats.
+-   `cntAbs: number`: Count of absentees.
+-   `desAbs: string`: Description/Names of absentees.
+
+**Key Methods:**
+-   `sortedArrAttSheep()`: Returns `arrSheep` sorted by attendance status and name.
+-   `calc()`: Calculates all statistics (sky, ground, total) and descriptions.
+-   `getCnt(status, attType)`: Helper to count sheep by status and method.
+
+#### `AttSheep`
+*File: `src/classes/attendance/SessionAttendance.ts`*
+
+Represents a single member's attendance status within a session.
+
+**Properties:**
+-   `idSheep: string`: ID of the sheep.
+-   `name: string`: Name of the sheep.
+-   `status: string`: Membership status.
+-   `attended: boolean`: Whether they attended.
+-   `absReason: string`: Reason for absence.
+-   `method: string`: Attendance method (Sky/Ground).
+
+#### `Title`
+*File: `src/classes/attendance/Title.ts`*
+*Extends: `Base`*
+
+Represents a Week or Event Title (e.g., "Week 1", "Special Service").
+
+**Properties:**
+-   `startDt: number`: Start timestamp.
+-   `endDt: number`: End timestamp.
+-   `code: string`: Unique code for the title.
+-   `arrSession: Session[]`: Defined sessions for this title.
+
+#### `Session`
+*File: `src/classes/attendance/Session.ts`*
+*Extends: `Base`*
+
+Definition of a session type.
+
+**Properties:**
+-   `code: string`: Session code.
+-   `desc: string`: Description.
+-   `seq: number`: Sequence number.
+-   `type: string`: Session type.
+-   `needAbsReason: boolean`: Whether absence reason is required.
+
+#### `DisplayAttendance`
+*File: `src/classes/attendance/SessionAttendance.ts`*
+
+Aggregated attendance statistics class.
+
+**Properties:**
+-   `cntOM`, `cntNB`, `cntAC`, `cntNF`, `cntRNF`: Counts for each status.
+-   `desOM`, `desNB`, ...: Comma-separated names for each status.
+-   `total`: Sum of all counts.
+
+### 3.4. Education (MSJ) Domain
+*Folder: `src/classes/education/`*
+
+Models for the "My Sheep Journey" (MSJ) education system.
+
+#### `MsjClassType`
+*File: `src/classes/education/MsjClassType.ts`*
+*Extends: `Base`*
+
+Defines a type of class (e.g., "Beginner Class").
+
+**Properties:**
+-   `title: string`: Class title.
+-   `seq?: number`: Sequence.
+-   `defaultMinAtt?: number`: Default minimum attendance required.
+-   `labelEn`, `labelZh`: localized labels.
+
+#### `MsjClassBatch`
+*File: `src/classes/education/MsjClassBatch.ts`*
+*Extends: `Base`*
+
+Represents a specific intake or batch of a class type.
+
+**Properties:**
+-   `idMsjClassType: string`: Reference to Class Type.
+-   `yearTimestamp`, `monthTimestamp`: Timing info.
+-   `numOfClass: number`: Total number of lessons.
+-   `minAtt?: number`: Minimum attendance required to pass.
+-   `sheetName?: string`: Related Google Sheet name (implied).
+
+#### `MsjStudBatch`
+*File: `src/classes/education/MsjStudBatch.ts`*
+*Extends: `Base`*
+
+Link between a Student (Sheep) and a Class Batch.
+
+**Properties:**
+-   `idSheep: string`: Student ID.
+-   `idBatch: string`: Batch ID.
+-   `completed?: boolean`: Completion status.
+-   `proceed?: boolean`: Whether they can proceed to next level.
+-   `attendance?: MsjStudClass[]`: Attendance records for lessons.
+-   `status?: string`: Enrollment status.
+-   `joinStatus?: string`: e.g., First Timer, Companion.
+-   `regUuid?: string`: Registration UUID.
+
+#### `MsjStudClass`
+*File: `src/classes/education/MsjStudClass.ts`*
+
+Attendance record for a single lesson within a batch for a student.
+
+**Properties:**
+-   `idClass?: string`: Class ID.
+-   `attended: boolean`: Presence.
+-   `classNo: number`: Lesson number.
+-   `replaced?: boolean`: If make-up class.
+-   `absReason?: string`: Absence reason.
+-   `markBy?: string`: User ID who marked attendance.
+-   `markAt?: number`: Timestamp.
+
+### 3.5. Finance Domain
+*Folder: `src/classes/finance/`*
+
+#### `Claim`
+*File: `src/classes/finance/Claim.ts`*
+*Extends: `Base`*
+
+Represents a financial claim/reimbursement request.
+
+**Properties:**
+-   `type: ClaimType`: Type of claim (Birthday, Refreshment, etc.).
+-   `cgs: string[]`: List of involved CG IDs.
+-   `amount?: number`: Claim amount.
+-   `payableSheepId: string`: ID of person to be reimbursed.
+-   `payableName: string`: Name of person to be reimbursed.
+-   `bankAcc`, `bankName`, `bankHolder`: Bank details.
+-   `receiptUrl?: string[]`: URLs of receipt images.
+-   `status: string`: Current status (Pending, Submitted, etc.).
+-   `receiptCollected: boolean`: Admin verification flag.
+-   `distributed: boolean`: Payment distribution flag.
+
+### 3.6. User Management
+*Folder: `src/classes/user-management/`* & *`src/classes/AppUser.ts`*
+
+#### `AppUser`
+*File: `src/classes/AppUser.ts`*
+
+Represents a logged-in user of the application.
+
+**Properties:**
+-   `id: string`: User ID.
+-   `name: string`: Display name.
+-   `phoneNum: string`: Login identifier.
+-   `permission: string`: Role/Permission level (e.g., 'Super user', 'CGL').
+-   `pastoral_team?: PastoralTeam`: Context (CG, Cluster, ST) for the user.
+-   `permissions?: string[]`: Granular permissions.
+-   `assigned_cg?: AssignedCG[]`: Specific CGs assigned to this user.
+-   `idSheep?: string`: Link to the Sheep profile of this user.
+
+#### `AppPage`
+*File: `src/classes/AppPage.ts`*
+
+Configuration for navigation items/pages.
+
+**Properties:**
+-   `title`, `url`, `icon`: Display and routing info.
+-   `canAccess`: Boolean flag.
+-   `permissions`: Array of roles allowed to access.
+-   `isSecure`: Whether login is required.
+
+## 4. Utility Types & Functions
+
+### `common.util.ts`
+-   `cgNum(cgName: string): number`: Extracts the numeric part of a CG name (e.g., "CG10" -> 10).
+
+### `date.util.ts`
+-   `formatDateDDMMYY(date: Date)`: Formats date as "YYMMDD".
+-   `parseYYMMDD(str: string)`: Parses "YYMMDD" into a Date object.
+-   `isDateInRangeIgnoreYear(d, start, end)`: Checks if a date falls within a range, ignoring the year (useful for recurring annual events/cycles).
+-   `getAge(timestamp)`: Calculates age.
+-   `getDayMonthSortKey(timestamp)`: Generates a sortable key based on month and day.
+
+### `sort.util.ts`
+-   `compareCG(a: CG, b: CG)`: Comparator function to sort CG objects numerically by name.
+
+## 5. Constants & Enums
+
+### `src/constants/status.constant.ts`
+-   `LIST_STATUS`: `['OM', 'NB', 'AC', 'NF', 'RNF']` - Defines the standard membership statuses.
+
+### `src/constants/claim.constant.ts`
+-   `ClaimType`: Enum for `BIRTHDAY`, `REFRESHMENT`, `OUTREACH`, `VENUE`.
+-   `ClaimStatus`: Enum for `PENDING`, `RECEIPT_COLLECTED`, `SUBMITTED`, `DISTRIBUTED`.
+
+### `src/constants/method.constant.ts`
+-   `METHOD`: Constants for attendance methods: `SKY` ('S'), `GROUND` ('G'), `TOTAL` ('T').
+
+### `src/constants/msj.constant.ts`
+-   `MsjJoinStatus`: Enum for `FIRST_TIMER`, `COMPANION`, `REFRESH`.
+-   `MsjJoinStatusInfo`: Metadata (labels) for join statuses.
+
+### `src/constants/permission.constant.ts`
+-   `PERMISSION`: Constants for roles: `SUPER_USER`, `TL`, `SCGL`, `CGL`, `FL`, `WM`, `PASTORAL_ADMIN`, `ST_ADMIN`.
+
+### `src/constants/click.constant.ts`
+-   `ClickAction`: Enum for tracking user actions (Page visits, Function usage).
+
+### `src/constants/dialog.constant.ts`
+-   `DialogAction`: Enum for `EDIT`, `ADD`.
+
+## 6. Cross-Module Relationships
+
+1.  **Attendance <-> Pastoral Team**:
+    -   `Attendance` records are linked to `CG`, `SmallTeam`, and `Cluster` via IDs.
+    -   `SessionAttendance` contains `AttSheep` objects, which are lightweight representations of `Sheep` specifically for attendance.
+    -   `Attendance.clearArrAttSheep` filters sheep based on the `CG` structure.
+
+2.  **Education <-> Pastoral Team**:
+    -   `MsjStudBatch` links a `Sheep` (student) to a `MsjClassBatch` (course).
+    -   `MsjClassBatch` is defined by a `MsjClassType`.
+
+3.  **Finance <-> Pastoral Team**:
+    -   `Claim` is linked to multiple `CG`s (`cgs: string[]`).
+    -   `Claim` is linked to a `Sheep` (`payableSheepId`) who made the payment.
+
+4.  **User Management <-> Pastoral Team**:
+    -   `AppUser` can be linked to a `Sheep` profile (`idSheep`).
+    -   `AppUser` has a `PastoralTeam` context (CG/ST/Cluster) defining their scope of authority.
+
+## 7. Type Dependency Map
+
+```mermaid
+graph TD
+    Base --> Sheep
+    Base --> CG
+    Base --> Cluster
+    Base --> SmallTeam
+    Base --> Claim
+    Base --> MsjClassBatch
+    Base --> MsjClassType
+    Base --> MsjStudBatch
+    Base --> Session
+    Base --> Title
+    Base --> Device
+
+    Sheep --> AttSheep
+    Sheep --> ReportSheep
+    Sheep --> MsjStudBatch
+
+    Attendance -- extends --> Title
+    Attendance -- contains --> SessionAttendance
+    SessionAttendance -- extends --> Session
+    SessionAttendance -- contains --> AttSheep
+    SessionAttendance -- contains --> DisplayAttendance
+
+    Claim -- uses --> ClaimType
+    Claim -- uses --> DisplayAttendance
+
+    MsjClassBatch -- references --> MsjClassType
+    MsjStudBatch -- references --> MsjClassBatch
+    MsjStudBatch -- contains --> MsjStudClass
+
+    AppUser -- references --> AssignedCG
+    AppUser -- references --> PastoralTeam
+```

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "cyc-type-def",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "DOCUMENTATION.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",