df50d5e7f8
Archived proposals:
- add-trigger-conditions-weekly-subscription: Trigger conditions and weekly subscription
- update-api-consistency: WebSocket auth, optimistic locking, workload defaults
All implementations were already complete in previous commits (f5f870d).
Updated tasks.md with implementation summary.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
31 lines
2.0 KiB
Markdown
31 lines
2.0 KiB
Markdown
## Context
|
|
The current API behavior is functionally correct but has ambiguities that cause client confusion: WebSocket handshake messaging differs from inline docs, 409 conflict responses are inconsistent for clients, and workload heatmap defaults vary based on calendar edge cases (Sunday).
|
|
|
|
## Goals / Non-Goals
|
|
- Goals:
|
|
- Make WebSocket auth expectations explicit and consistent.
|
|
- Provide a stable, machine-readable conflict response for optimistic locking.
|
|
- Define predictable workload heatmap defaults and edge-case handling.
|
|
- Non-Goals:
|
|
- Full API version migration (/api to /api/v1).
|
|
- Redesign of workload UI or heatmap visualization.
|
|
|
|
## Decisions
|
|
- WebSocket auth handshake: keep first-message authentication; do not require a pre-auth banner. Add explicit invalid-token error message prior to close.
|
|
- Optimistic locking: return a standardized 409 payload containing a human-readable message plus current/provided version fields.
|
|
- Workload defaults: show all accessible users by default (including zero workload); support `hide_empty=true` to exclude them. When `week_start` is omitted and today is Sunday, extend the default week window to include the upcoming week to avoid empty default views.
|
|
- Caching: include `hide_empty` in cache key and cache the default path to keep latency stable.
|
|
|
|
## Risks / Trade-offs
|
|
- Returning more users by default may increase response sizes; cache should offset this.
|
|
- Sunday window extension changes semantics of "current week"; clients must understand the rule.
|
|
- Conflict payload change may require frontend updates if it expects a string-only detail.
|
|
|
|
## Migration Plan
|
|
- Update specs first, then implement backend changes.
|
|
- Update frontend only if new defaults or conflict payloads require parsing changes.
|
|
- Add regression tests for WebSocket auth invalid token, conflict payload shape, and heatmap defaults.
|
|
|
|
## Open Questions
|
|
- Should we add an explicit `auth_required` message before waiting for the auth payload (client UX improvement), or keep the minimal handshake?
|