must be a valid ISO-8601 datetime."` |
+| Control carries `invalidDatetime` error | Same message (covered by the validator path). |
The error is shown only when the control is both `touched || dirty`
AND `invalid`, so the inputs do not flash errors on initial load. After
a successful Save, both controls are reset to untouched/pristine via
`resetTouchedState()` and their `TouchedOrDirty` signals are cleared.
The cross-field `endBeforeStart` error (`general-endBeforeStart`) is
-still emitted from the form-level `superRefine`/validator chain and is
-unchanged — it now sits next to the new per-field messages when the
-user supplies two non-empty values that are out of order.
+emitted by the form-level validator whenever both valid timestamps are
+present and end is not strictly after start. The Event end input also
+receives `aria-invalid="true"`, references both possible error elements,
+and exposes `Event end must be after event start.` as its title.
# Visual elements
@@ -193,7 +189,7 @@ user supplies two non-empty values that are out of order.
| 3 | `frontend/src/app/core/services/admin.service.ts` | `getGeneralSettings()` → `GET /api/v1/admin/general/settings`; `listAdminThemes()` → `GET /api/v1/admin/general/themes`; `updateGeneralSettings()` → `PUT .../settings`; `uploadLogo()` → `POST /api/v1/uploads/logo`. |
| 4 | `backend/src/modules/admin/admin-general.controller.ts` | `AdminGuard` + `@Roles('admin')` on every handler. |
| 5 | `backend/src/modules/admin/general.service.ts` | `getSettings` reads 8 keys via `SettingsService`; `updateSettings` writes all 8, emits `{ topic: 'general', themeKey }` via `SseHubService`. |
-| 6 | `backend/src/modules/admin/dto/general.dto.ts` | `GeneralSettingsSchema` enforces string lengths, `themeKey` enum, per-field ISO-8601 datetime check on `eventStartUtc`/`eventEndUtc` (empty string allowed), and `eventEndUtc > eventStartUtc` via `superRefine`. |
+| 6 | `backend/src/modules/admin/dto/general.dto.ts` | `GeneralSettingsSchema` requires ISO-8601 values for both event-window fields and enforces `eventEndUtc > eventStartUtc` via `superRefine`. |
# Notes
@@ -202,8 +198,11 @@ user supplies two non-empty values that are out of order.
without polling. Other tabs do not auto-refresh settings values.
* The "Event controls" toggle is intentionally a derived display, not
an editable control — adjust the UTC timestamps to change state.
-* All timestamps are stored as ISO-8601 UTC strings in the `setting`
+* All valid timestamps are stored as ISO-8601 UTC strings in the `setting`
table; the UI converts to/from `datetime-local` for display.
+* Both timestamps are required by the General Settings form and API.
+ The `UNCONFIGURED` derived display remains a defensive state for missing
+ or invalid data, but clearing either input makes the form unsavable.
* Saving the form requires the page title and default challenge IP to
be non-empty; the form is `invalid` and Save stays disabled until
they are.
diff --git a/docs/index.md b/docs/index.md
index 03a78f2..e8beaf4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -11,7 +11,7 @@ scoreboard, an event window with a public countdown, theming, and admin
controls.
The docs below are organized by purpose so agents can pull just the slice
-they need. Last regenerated 2026-07-22T13:40:00Z.
+they need. Last regenerated 2026-07-22T14:24:08Z.
# Architecture
@@ -62,9 +62,8 @@ they need. Last regenerated 2026-07-22T13:40:00Z.
navigate the post-login admin area side-nav (General, Challenges,
Players, Blog, System) and reach the enabled child pages.
* [Admin — General Settings](/guides/admin-general-settings.md) - How an
- admin edits platform-wide settings (page title, logo, theme, event
- window, default challenge IP, registrations, welcome Markdown) at
- `/admin/general`.
+ admin edits platform-wide settings, including the required and strictly
+ ordered event window, at `/admin/general`.
* [Admin — Categories](/guides/admin-categories.md) - How an admin lists,
creates, edits, and deletes challenge categories at `/admin/categories`,
including system-row and challenge-attached protection.
diff --git a/frontend/src/app/features/admin/general.component.ts b/frontend/src/app/features/admin/general.component.ts
index aba8f26..048d617 100644
--- a/frontend/src/app/features/admin/general.component.ts
+++ b/frontend/src/app/features/admin/general.component.ts
@@ -10,6 +10,7 @@ import {
datetimeMessage,
deriveEventState,
endAfterStartValidator,
+ endBeforeStartMessage,
isoDatetimeValidator,
normalizePageTitle,
pageTitleMessage,
@@ -113,14 +114,17 @@ import {
type="datetime-local"
formControlName="eventEndUtc"
data-testid="general-eventEnd"
- [attr.aria-invalid]="showEventEndError() || (form.controls.eventEndUtc.touched && !!form.error?.['endBeforeStart']) ? 'true' : null"
- [attr.aria-describedby]="(showEventEndError() || (form.controls.eventEndUtc.touched && !!form.error?.['endBeforeStart'])) ? 'general-eventEnd-error general-endBeforeStart' : null"
+ [attr.aria-invalid]="showEventEndError() || eventEndCrossFieldError() ? 'true' : null"
+ [attr.aria-describedby]="(showEventEndError() || eventEndCrossFieldError())
+ ? 'general-eventEnd-error general-endBeforeStart'
+ : null"
+ [attr.title]="(showEventEndError() ? eventEndMessage() : eventEndCrossFieldError() ? endBeforeStartMessage : null)"
/>
@if (showEventEndError()) {
{{ eventEndMessage() }}
}
- @if (form.controls.eventEndUtc.touched && form.error?.['endBeforeStart']) {
- Event end must be after event start.
+ @if (eventEndCrossFieldError()) {
+ {{ endBeforeStartMessage }}
}
@@ -256,6 +260,10 @@ export class AdminGeneralComponent implements OnInit {
datetimeMessage('Event end', this.eventEndValue(), this.form.controls.eventEndUtc.errors),
);
+ readonly eventEndCrossFieldError = computed(
+ () => !!this.form.errors?.['endBeforeStart'],
+ );
+
constructor() {
this.form.controls.welcomeMarkdown.valueChanges
.pipe(takeUntilDestroyed(this.destroyRef))
diff --git a/frontend/src/app/features/admin/general.pure.ts b/frontend/src/app/features/admin/general.pure.ts
index 0db8f5d..781bb32 100644
--- a/frontend/src/app/features/admin/general.pure.ts
+++ b/frontend/src/app/features/admin/general.pure.ts
@@ -67,7 +67,6 @@ export function toIsoUtc(local: string): string {
export function isoDatetimeValidator(ctrl: { value: string | null | undefined }): { invalidDatetime: true } | null {
const v = ctrl?.value ?? '';
- if (v === '') return null;
const t = Date.parse(v);
return Number.isFinite(t) ? null : { invalidDatetime: true };
}
@@ -81,8 +80,10 @@ export function datetimeMessage(
return `${fieldLabel} must be a valid ISO-8601 datetime.`;
}
const v = value ?? '';
- if (v !== '' && !Number.isFinite(Date.parse(v))) {
+ if (!Number.isFinite(Date.parse(v))) {
return `${fieldLabel} must be a valid ISO-8601 datetime.`;
}
return null;
}
+
+export const endBeforeStartMessage = 'Event end must be after event start.';
diff --git a/tests/backend/admin-general-event-window.spec.ts b/tests/backend/admin-general-event-window.spec.ts
new file mode 100644
index 0000000..5c5fe02
--- /dev/null
+++ b/tests/backend/admin-general-event-window.spec.ts
@@ -0,0 +1,68 @@
+process.env.NODE_ENV = 'test';
+
+import { GeneralSettingsSchema } from '../../backend/src/modules/admin/dto/general.dto';
+
+const baseValid = {
+ pageTitle: 'OpenVelo',
+ logo: '',
+ welcomeMarkdown: '',
+ themeKey: 'classic',
+ defaultChallengeIp: '127.0.0.1',
+ registrationsEnabled: false,
+};
+
+function withEvent(start: string, end: string) {
+ return { ...baseValid, eventStartUtc: start, eventEndUtc: end };
+}
+
+describe('Admin general settings - event window validation (Job 888)', () => {
+ it('accepts a valid event window', () => {
+ const r = GeneralSettingsSchema.safeParse(
+ withEvent('2026-08-15T10:30:00.000Z', '2026-08-20T18:45:00.000Z'),
+ );
+ expect(r.success).toBe(true);
+ });
+
+ it('rejects an empty eventEndUtc with a per-field message', () => {
+ const r = GeneralSettingsSchema.safeParse(withEvent('2026-08-15T10:30:00.000Z', ''));
+ expect(r.success).toBe(false);
+ if (r.success) return;
+ const endIssue = r.error.issues.find((i) => i.path.join('.') === 'eventEndUtc');
+ expect(endIssue?.message).toBe('eventEndUtc must be a valid ISO-8601 datetime');
+ });
+
+ it('rejects an empty eventStartUtc with a per-field message', () => {
+ const r = GeneralSettingsSchema.safeParse(withEvent('', '2026-08-20T18:45:00.000Z'));
+ expect(r.success).toBe(false);
+ if (r.success) return;
+ const startIssue = r.error.issues.find((i) => i.path.join('.') === 'eventStartUtc');
+ expect(startIssue?.message).toBe('eventStartUtc must be a valid ISO-8601 datetime');
+ });
+
+ it('rejects a non-empty malformed eventEndUtc', () => {
+ const r = GeneralSettingsSchema.safeParse(withEvent('2026-08-15T10:30:00.000Z', 'not-a-date'));
+ expect(r.success).toBe(false);
+ if (r.success) return;
+ const endIssue = r.error.issues.find((i) => i.path.join('.') === 'eventEndUtc');
+ expect(endIssue?.message).toBe('eventEndUtc must be a valid ISO-8601 datetime');
+ });
+
+ it('rejects end equal to start', () => {
+ const ts = '2026-08-15T10:30:00.000Z';
+ const r = GeneralSettingsSchema.safeParse(withEvent(ts, ts));
+ expect(r.success).toBe(false);
+ if (r.success) return;
+ const endIssue = r.error.issues.find((i) => i.path.join('.') === 'eventEndUtc');
+ expect(endIssue?.message).toBe('eventEndUtc must be strictly after eventStartUtc');
+ });
+
+ it('rejects end before start', () => {
+ const r = GeneralSettingsSchema.safeParse(
+ withEvent('2026-08-20T18:45:00.000Z', '2026-08-15T10:30:00.000Z'),
+ );
+ expect(r.success).toBe(false);
+ if (r.success) return;
+ const endIssue = r.error.issues.find((i) => i.path.join('.') === 'eventEndUtc');
+ expect(endIssue?.message).toBe('eventEndUtc must be strictly after eventStartUtc');
+ });
+});
diff --git a/tests/backend/admin-general-service.spec.ts b/tests/backend/admin-general-service.spec.ts
index a54b40c..f7c3416 100644
--- a/tests/backend/admin-general-service.spec.ts
+++ b/tests/backend/admin-general-service.spec.ts
@@ -141,7 +141,7 @@ describe('GeneralSettingsSchema - validation rules', () => {
expect(r.success).toBe(false);
});
- it('accepts empty strings (unconfigured event window) for both datetime fields', () => {
+ it('rejects empty strings for event datetime fields with per-field messages (Job 888)', () => {
const r = GeneralSettingsSchema.safeParse({
pageTitle: 'T',
logo: '',
@@ -152,7 +152,12 @@ describe('GeneralSettingsSchema - validation rules', () => {
defaultChallengeIp: '127.0.0.1',
registrationsEnabled: false,
});
- expect(r.success).toBe(true);
+ expect(r.success).toBe(false);
+ if (r.success) return;
+ const startIssue = r.error.issues.find((i) => i.path.join('.') === 'eventStartUtc');
+ const endIssue = r.error.issues.find((i) => i.path.join('.') === 'eventEndUtc');
+ expect(startIssue?.message).toBe('eventStartUtc must be a valid ISO-8601 datetime');
+ expect(endIssue?.message).toBe('eventEndUtc must be a valid ISO-8601 datetime');
});
});
diff --git a/tests/frontend/admin-general-pure.spec.ts b/tests/frontend/admin-general-pure.spec.ts
index 60b9c27..3d6018d 100644
--- a/tests/frontend/admin-general-pure.spec.ts
+++ b/tests/frontend/admin-general-pure.spec.ts
@@ -165,10 +165,10 @@ describe('pageTitleMessage', () => {
});
describe('isoDatetimeValidator', () => {
- it('returns null for an empty value (unconfigured is allowed)', () => {
- expect(isoDatetimeValidator({ value: '' })).toBeNull();
- expect(isoDatetimeValidator({ value: null })).toBeNull();
- expect(isoDatetimeValidator({ value: undefined })).toBeNull();
+ it('returns { invalidDatetime: true } for an empty value (empty string no longer accepted)', () => {
+ expect(isoDatetimeValidator({ value: '' })).toEqual({ invalidDatetime: true });
+ expect(isoDatetimeValidator({ value: null })).toEqual({ invalidDatetime: true });
+ expect(isoDatetimeValidator({ value: undefined })).toEqual({ invalidDatetime: true });
});
it('returns null for a valid ISO-8601 datetime', () => {
@@ -194,9 +194,9 @@ describe('datetimeMessage', () => {
.toBe('Event start must be a valid ISO-8601 datetime.');
});
- it('returns null for an empty value', () => {
- expect(datetimeMessage('Event start', '', null)).toBeNull();
- expect(datetimeMessage('Event start', '', { invalidDatetime: false as any })).toBeNull();
+ it('returns the per-field error for an empty value (empty is now invalid)', () => {
+ expect(datetimeMessage('Event start', '', null)).toBe('Event start must be a valid ISO-8601 datetime.');
+ expect(datetimeMessage('Event end', '', { invalidDatetime: true })).toBe('Event end must be a valid ISO-8601 datetime.');
});
it('returns null for a valid ISO-8601 datetime', () => {