Update field handling guidelines and version to alpha2
- Enhanced Date/Time Handling with null/sentinel date logic (1900-01-01) - Added 'See Notes' display for sentinel dates with related note fields - Documented date entry normalization and validation rules - Added Boolean Field Handling guidelines - Added Calculated Fields documentation (Active, Due_Date_Counter) - Added Due_Date_ASAP field specification for urgent job tracking - Added Pending Schema Updates section - Version bump to 1.0.0-alpha2
This commit is contained in:
+131
@@ -0,0 +1,131 @@
|
||||
# Project Rules for AI Assistants
|
||||
|
||||
This file contains project-specific guidance for AI assistants working on the Job-List application.
|
||||
|
||||
## Field Handling Guidelines
|
||||
|
||||
### Date/Time Handling
|
||||
|
||||
**Storage Format (PocketBase Database):**
|
||||
- All date/time fields must be stored as **ISO 8601 UTC format**
|
||||
- Example: `2025-12-21T18:30:00.000Z`
|
||||
- **Null dates**: Use sentinel value `1900-01-01T00:00:00.000Z` to represent null/empty dates
|
||||
|
||||
**Display Format (Frontend/UI):**
|
||||
- Timezone: **US Central Standard Time (CST/CDT)**
|
||||
- Time: **12-hour format** with am/pm (e.g., `6:30 pm`)
|
||||
- Date: **Short US format** MM/dd/yyyy (e.g., `12/21/2025`)
|
||||
|
||||
**Null/Empty Date Display:**
|
||||
- Sentinel date (1900-01-01) with **no related note field** → display as **empty/blank** field
|
||||
- Sentinel date (1900-01-01) with **related note field populated** → display **"See Notes"**
|
||||
- Example: If `Due_Date` is sentinel and `Due_Date_Notes` has content, show "See Notes"
|
||||
- Empty frontend field → store as sentinel date (1900-01-01) in PocketBase
|
||||
|
||||
**Date Entry and Normalization:**
|
||||
- Dates can be entered via **datepicker** (preferred) or **manual text entry**
|
||||
- Manual entries must be normalized to full MM/dd/yyyy format:
|
||||
- `1/1` → `01/01/2026` (add year based on logical context)
|
||||
- `12/1` → `12/01/2025` (use current year if month hasn't passed)
|
||||
- **Confirmation required** for manual entries: Show prompt "Did you mean MM/dd/yyyy?" before saving
|
||||
- **Reject invalid dates** with error message explaining:
|
||||
- Invalid format or date that doesn't fit normalization logic
|
||||
- Suggest using related note field for explanations (e.g., `Due_Date_Notes` for `Due_Date`)
|
||||
- **Validation**: Only allow valid dates OR completely empty - no partial/invalid entries
|
||||
|
||||
**Conversion Rules (Bidirectional):**
|
||||
- **Frontend → Backend**: Convert user input from CST → ISO UTC before saving to PocketBase
|
||||
- **Backend → Frontend**: Convert PocketBase UTC data → CST for display (or "See Notes" for sentinel with notes)
|
||||
- **Updates**: Any date/time change from either frontend or backend must trigger conversion and sync to maintain consistency across the application
|
||||
|
||||
### Boolean Field Handling
|
||||
|
||||
**Storage Format (PocketBase Database):**
|
||||
- Stored as boolean values: `true` or `false`
|
||||
- `null` values must be converted to `false`
|
||||
|
||||
**Display Format (Frontend/UI):**
|
||||
- Rendered as checkboxes
|
||||
- Checked = `true`
|
||||
- Unchecked = `false`
|
||||
|
||||
**Conversion Rules (Bidirectional):**
|
||||
- **Frontend → Backend**: Checkbox state (checked/unchecked) → boolean (`true`/`false`) → stored in PocketBase
|
||||
- **Backend → Frontend**: PocketBase boolean value → checkbox state (checked/unchecked)
|
||||
- **Updates**: Any change to checkbox state or boolean value must sync bidirectionally to maintain consistency
|
||||
|
||||
### Calculated Fields
|
||||
|
||||
#### Active Field (Boolean - Read-Only)
|
||||
|
||||
**Trigger:**
|
||||
- Automatically calculated when `Job_Status` field changes on the frontend
|
||||
|
||||
**Calculation Logic:**
|
||||
- `Active` = `true` if `Job_Status` equals any of:
|
||||
- "Estimating"
|
||||
- "Est Sent"
|
||||
- "Est Hold"
|
||||
- "Follow Up"
|
||||
- "Awarded"
|
||||
- "In Progress"
|
||||
- "Billed In Progress"
|
||||
- `Active` = `false` for all other `Job_Status` values
|
||||
|
||||
**Frontend Behavior:**
|
||||
- Display as **read-only** (checkbox or indicator)
|
||||
- Automatically recalculate whenever `Job_Status` changes
|
||||
- Sync calculated value to PocketBase after update
|
||||
|
||||
#### Due_Date_Counter Field (Text - Read-Only)
|
||||
|
||||
**Trigger:**
|
||||
- Automatically calculated when `Due_Date` or `Due_Date_ASAP` field changes on the frontend
|
||||
- Does NOT recalculate on `Job_Status` changes
|
||||
|
||||
**Calculation Logic:**
|
||||
1. If `Job_Status` ≠ "Estimating" → **"N/A"**
|
||||
2. If `Due_Date_ASAP` = true → **"ASAP"**
|
||||
3. If `Due_Date` is blank/sentinel (1900-01-01) → **blank/empty**
|
||||
4. If `Due_Date` < Today → **"Passed due"**
|
||||
5. If `Due_Date` = Today → **"Due today"**
|
||||
6. Else → Calculate days remaining: **"[X] day"** (singular) or **"[X] days"** (plural)
|
||||
|
||||
**Frontend Behavior:**
|
||||
- Display as **read-only text field**
|
||||
- Automatically recalculate whenever `Due_Date` or `Due_Date_ASAP` changes
|
||||
- Sync calculated value to PocketBase after update
|
||||
|
||||
#### Due_Date_ASAP Field (Boolean)
|
||||
|
||||
**Purpose:**
|
||||
- Mark jobs as urgent/ASAP with timestamp tracking
|
||||
|
||||
**Behavior When Checked:**
|
||||
- System automatically sets `Due_Date` to **TODAY's date** (system-generated timestamp)
|
||||
- `Due_Date` field displays **"ASAP"**
|
||||
- `Due_Date_Counter` displays **"ASAP"**
|
||||
- Enables tracking: Days since ASAP was marked using the captured date
|
||||
|
||||
**Behavior When Unchecked:**
|
||||
- `Due_Date` reverts to blank/sentinel (1900-01-01) or allows manual date entry
|
||||
- Normal date display and counter calculation resume
|
||||
|
||||
**Design Rationale:**
|
||||
- **ASAP scenario**: Captures specific timestamp for urgent items requiring immediate attention
|
||||
- **Blank/No Due Date scenario**: Uses sentinel (1900-01-01) + `created_date` for flexible/TBD timing
|
||||
- Key difference: ASAP provides explicit urgency tracking vs. general aging for non-urgent items
|
||||
|
||||
## Pending Schema Updates
|
||||
|
||||
**Fields to Add:**
|
||||
- `Due_Date_Notes` (text field) - Explanatory notes for Due_Date
|
||||
- `Start_Date_Notes` (text field) - Explanatory notes for Start_Date
|
||||
- `Due_Date_ASAP` (boolean) - Flag for marking jobs as urgent/ASAP with timestamp tracking
|
||||
|
||||
**Action Items:**
|
||||
- Review current schema against planned fields
|
||||
- Identify any other date fields that need corresponding note fields
|
||||
- Implement field additions in PocketBase
|
||||
- Update frontend forms and display logic
|
||||
- Update Due_Date_Counter calculation logic to incorporate Due_Date_ASAP field
|
||||
Reference in New Issue
Block a user