egg/PROJECT-CONTORL
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

spec: update api consistency

Browse Source 
Align optimistic locking conflict payload, update websocket docs, and adjust tests.
This commit is contained in:
beabigegg
2026-01-11 16:54:28 +08:00
parent f5f870da56
commit 2cb591ef23
9 changed files with 131 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
openspec/changes/update-api-consistency/design.md Normal file
View File

@@ -0,0 +1,30 @@
## 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?