chore: archive remaining OpenSpec proposals
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>
This commit is contained in:
beabigegg
@@ -0,0 +1,45 @@
|
||||
## Context
|
||||
需要支援 Trigger 複合條件（AND-only）、群組通知目標，以及「手動訂閱」的週報收件人規則，並同步更新前端操作介面。
|
||||
|
||||
## Goals / Non-Goals
|
||||
- Goals:
|
||||
- 支援多條件 AND-only 觸發器條件
|
||||
- 支援 `due_date`/`start_date`/`custom_fields`（含 formula）與 `before/after/in` 運算子
|
||||
- 支援群組通知目標與去重、排除觸發者
|
||||
- 週報改為手動訂閱且收件人為專案成員（含跨部門）
|
||||
- 前端同版支援條件編輯與訂閱開關
|
||||
- Non-Goals:
|
||||
- 不實作 OR/巢狀條件樹
|
||||
- 不新增 Email 通知通道
|
||||
- 不改動排程時間（維持週五 16:00）
|
||||
|
||||
## Decisions
|
||||
- 條件結構
|
||||
- `field_change` 觸發器支援兩種條件格式：
|
||||
- Legacy: `{ field, operator, value }`
|
||||
- Composite: `{ logic: "and", rules: [ { field, operator, value, field_id? } ] }`
|
||||
- `in` 在日期欄位採 `{ start, end }`，且包含邊界。
|
||||
- `in` 在文字/下拉/人員欄位採用陣列值。
|
||||
- `before/after` 用於日期欄位；`before/after` 也可用於數值類（number/formula）。
|
||||
- 觸發時機
|
||||
- 觸發器於任務/自訂欄位更新時評估。
|
||||
- 規則需同時滿足且至少有一個規則所屬欄位在此次更新中變更，避免無關更新重複觸發。
|
||||
- 通知目標解析
|
||||
- 支援 `assignee`/`creator`/`project_owner`/`project_members`/`department:<id>`/`role:<name>`/`user:<id>`。
|
||||
- `project_members` 包含 owner。
|
||||
- `department`/`role` 解析為組織內所有符合的使用者。
|
||||
- 排除觸發者本人並對收件人去重。
|
||||
- 週報訂閱
|
||||
- 使用 `pjctrl_scheduled_reports` 作為訂閱資料；一位使用者一筆 weekly 訂閱。
|
||||
- 週報僅發送給已訂閱使用者。
|
||||
- 週報內容包含使用者為 owner 或 project member 的所有專案。
|
||||
|
||||
## Risks / Trade-offs
|
||||
- `department`/`role` 可能觸及非專案成員，需確保用戶理解通知範圍。
|
||||
- 自訂欄位（formula）計算可能帶來額外成本，需避免 N+1 查詢。
|
||||
|
||||
## Migration Plan
|
||||
- 無資料庫 schema 變更。
|
||||
|
||||
## Open Questions
|
||||
- 無（已確認 AND-only、日期區間 inclusive、role 自由輸入）。
|
||||
@@ -0,0 +1,17 @@
|
||||
# Change: Trigger Composite Conditions, Group Notifications, Weekly Report Subscriptions
|
||||
|
||||
## Why
|
||||
目前觸發器僅支援單一條件與單一通知對象，無法滿足複合條件與群組通知需求；週報收件人規則亦需改為手動訂閱並涵蓋專案成員。
|
||||
|
||||
## What Changes
|
||||
- 新增 AND-only 複合條件結構，支援 `due_date`/`start_date`/`custom_fields`（含 formula），並加入 `before/after/in` 運算子（日期 `in` 採用區間且包含邊界）。
|
||||
- 通知目標擴充為 `project_members`/`department:<id>`/`role:<name>`/`user:<id>`，並加入去重與排除觸發者規則。
|
||||
- 週報改為「手動訂閱」機制，僅發送給已訂閱的使用者；週報內容涵蓋使用者為 owner 或 project member 的所有專案。
|
||||
- 前端同步支援複合條件編輯、群組通知目標、MySettings 週報訂閱開關。
|
||||
|
||||
## Impact
|
||||
- Affected specs: `automation`
|
||||
- Affected code:
|
||||
- Backend: `backend/app/schemas/trigger.py`, `backend/app/services/trigger_service.py`, `backend/app/api/triggers/router.py`, `backend/app/services/report_service.py`, `backend/app/api/reports/router.py`
|
||||
- Frontend: `frontend/src/components/TriggerForm.tsx`, `frontend/src/components/TriggerList.tsx`, `frontend/src/services/triggers.ts`, `frontend/src/pages/MySettings.tsx`
|
||||
- Tests: trigger conditions/group notifications/weekly report subscription coverage
|
||||
@@ -0,0 +1,117 @@
|
||||
## MODIFIED Requirements
|
||||
### Requirement: Trigger Conditions
|
||||
系統 SHALL 支援多種觸發條件類型，包含欄位變更、時間條件、以及 AND-only 複合條件。欄位變更條件 SHALL 支援 `status_id`、`assignee_id`、`priority`、`due_date`、`start_date` 與 `custom_fields`（含 formula），並支援 `equals`、`not_equals`、`changed_to`、`changed_from`、`before`、`after`、`in` 運算子。日期欄位的 `in` SHALL 使用 `{start, end}` 區間且包含邊界。
|
||||
|
||||
#### Scenario: 欄位變更條件
|
||||
- **GIVEN** 觸發器設定為「當 Status 欄位變更為特定值」
|
||||
- **WHEN** 任務的 Status 欄位變更為該值
|
||||
- **THEN** 觸發器被觸發
|
||||
|
||||
#### Scenario: 時間條件
|
||||
- **GIVEN** 觸發器設定為「每週五下午 4:00」
|
||||
- **WHEN** 系統時間達到設定時間
|
||||
- **THEN** 觸發器被觸發
|
||||
|
||||
#### Scenario: 複合條件
|
||||
- **GIVEN** 觸發器設定為「當 Status = 完成 且 Priority = 高」
|
||||
- **WHEN** 任務同時滿足兩個條件
|
||||
- **THEN** 觸發器被觸發
|
||||
|
||||
#### Scenario: 日期區間條件
|
||||
- **GIVEN** 觸發器設定為「due_date in {start, end}」且區間為含邊界
|
||||
- **WHEN** 任務的 due_date 落在該區間內
|
||||
- **THEN** 觸發器被觸發
|
||||
|
||||
#### Scenario: 自訂欄位（公式）條件
|
||||
- **GIVEN** 觸發器設定為「custom_fields(公式欄位) equals 目標值」
|
||||
- **WHEN** 任務的公式欄位計算值符合目標值
|
||||
- **THEN** 觸發器被觸發
|
||||
|
||||
#### Scenario: Cron 表達式觸發
|
||||
- **GIVEN** 觸發器設定為 cron 表達式 (如 `0 9 * * 1` 每週一早上 9 點)
|
||||
- **WHEN** 系統時間匹配 cron 表達式
|
||||
- **THEN** 系統評估並執行該觸發器
|
||||
- **AND** 記錄執行結果至 trigger_logs
|
||||
|
||||
#### Scenario: 截止日期提醒
|
||||
- **GIVEN** 觸發器設定為「截止日前 N 天提醒」
|
||||
- **WHEN** 任務距離截止日剩餘 N 天
|
||||
- **THEN** 系統發送提醒通知給任務指派者
|
||||
- **AND** 每個任務每個提醒設定只觸發一次
|
||||
|
||||
### Requirement: Trigger Actions
|
||||
系統 SHALL 支援多種觸發動作類型。通知動作 SHALL 支援單人與群組目標（`assignee`、`creator`、`project_owner`、`project_members`、`department:<id>`、`role:<name>`、`user:<id>`），並對收件人去重且排除觸發者本人。
|
||||
|
||||
#### Scenario: 發送通知動作
|
||||
- **GIVEN** 觸發器動作設定為發送通知
|
||||
- **WHEN** 觸發器被觸發
|
||||
- **THEN** 系統發送通知給指定對象
|
||||
- **AND** 通知內容可使用變數（如任務名稱、指派者）
|
||||
|
||||
#### Scenario: 群組通知目標
|
||||
- **GIVEN** 觸發器通知目標為 `project_members` 或 `department:<id>` 或 `role:<name>`
|
||||
- **WHEN** 觸發器被觸發
|
||||
- **THEN** 系統通知所有對應成員
|
||||
- **AND** 去除重複收件人
|
||||
- **AND** 排除觸發者本人
|
||||
|
||||
#### Scenario: 更新欄位動作
|
||||
- **GIVEN** 觸發器動作設定為更新欄位
|
||||
- **WHEN** 觸發器被觸發
|
||||
- **THEN** 系統自動更新指定欄位的值
|
||||
|
||||
#### Scenario: 指派任務動作
|
||||
- **GIVEN** 觸發器動作設定為自動指派
|
||||
- **WHEN** 觸發器被觸發
|
||||
- **THEN** 系統自動將任務指派給指定人員
|
||||
|
||||
### Requirement: Automated Weekly Report
|
||||
系統 SHALL 每週五下午 4:00 自動彙整完整任務清單，發送給已訂閱的專案成員（含跨部門成員）。週報內容 SHALL 以收件人為 owner 或 project member 的專案為範圍。
|
||||
|
||||
#### Scenario: 週報內容完整清單
|
||||
- **GIVEN** 週報生成中
|
||||
- **WHEN** 系統彙整資料
|
||||
- **THEN** 週報包含各專案的：
|
||||
- 本週已完成任務清單（含 completed_at, assignee_name）
|
||||
- 進行中任務清單（含 assignee_name, due_date）
|
||||
- 逾期任務警示（含 due_date, days_overdue）
|
||||
- 阻礙中任務清單（含 blocker_reason, blocked_since）
|
||||
- 下週預計完成任務（含 due_date, assignee_name）
|
||||
- **AND** 不設任務數量上限
|
||||
|
||||
#### Scenario: 週報收件人範圍
|
||||
- **GIVEN** 使用者為專案成員且已開啟週報訂閱
|
||||
- **WHEN** 週報排程執行
|
||||
- **THEN** 使用者收到週報
|
||||
|
||||
#### Scenario: 阻礙任務識別
|
||||
- **GIVEN** 任務有未解除的 Blocker 記錄
|
||||
- **WHEN** 週報查詢阻礙任務
|
||||
- **THEN** 系統查詢 Blocker 表 resolved_at IS NULL 的任務
|
||||
- **AND** 顯示阻礙原因與開始時間
|
||||
|
||||
#### Scenario: 下週預計任務
|
||||
- **GIVEN** 任務的 due_date 在下週範圍內
|
||||
- **WHEN** 週報查詢下週預計任務
|
||||
- **THEN** 系統篩選 due_date >= 下週一 且 < 下週日
|
||||
- **AND** 排除已完成狀態的任務
|
||||
|
||||
## ADDED Requirements
|
||||
### Requirement: Weekly Report Subscription
|
||||
系統 SHALL 提供週報訂閱管理功能，讓使用者手動開啟或關閉週報。
|
||||
|
||||
#### Scenario: 開啟週報訂閱
|
||||
- **GIVEN** 使用者尚未訂閱週報
|
||||
- **WHEN** 使用者在 MySettings 開啟週報訂閱
|
||||
- **THEN** 系統建立或啟用該使用者的 weekly 訂閱
|
||||
|
||||
#### Scenario: 關閉週報訂閱
|
||||
- **GIVEN** 使用者已訂閱週報
|
||||
- **WHEN** 使用者在 MySettings 關閉週報訂閱
|
||||
- **THEN** 系統停用該使用者的 weekly 訂閱
|
||||
- **AND** 後續排程不再發送週報
|
||||
|
||||
#### Scenario: 未訂閱預設行為
|
||||
- **GIVEN** 使用者未開啟週報訂閱
|
||||
- **WHEN** 週報排程執行
|
||||
- **THEN** 使用者不會收到週報
|
||||
@@ -0,0 +1,22 @@
|
||||
## 1. Backend
|
||||
- [x] 1.1 Extend trigger schemas/validation to accept composite conditions and new operators/fields
|
||||
- [x] 1.2 Implement composite condition evaluation (AND-only) with operator semantics and custom field/formula support
|
||||
- [x] 1.3 Extend notify target resolution for group targets, dedup recipients, and exclude triggerer
|
||||
- [x] 1.4 Evaluate triggers on due_date/start_date/custom_field updates
|
||||
- [x] 1.5 Add weekly report subscription API (get/update) and enforce manual subscription
|
||||
- [x] 1.6 Include project members (and owner) in weekly report project scope
|
||||
|
||||
## 2. Frontend
|
||||
- [x] 2.1 Update trigger API types for composite conditions and group targets
|
||||
- [x] 2.2 Update TriggerForm/TriggerList to build AND-only rule lists with date range + custom field inputs
|
||||
- [x] 2.3 Add MySettings weekly report subscription toggle (with API integration)
|
||||
- [x] 2.4 Add i18n strings for new trigger/weekly report UI
|
||||
|
||||
## 3. Tests
|
||||
- [x] 3.1 Backend tests for composite conditions (status+priority, due_date range)
|
||||
- [x] 3.2 Backend tests for custom field (formula) conditions
|
||||
- [x] 3.3 Backend tests for group notification targeting (department/role/project_members) with dedup/exclude
|
||||
- [x] 3.4 Backend tests for weekly report subscription and project-member scope
|
||||
|
||||
## 4. Validation
|
||||
- [x] 4.1 Run targeted pytest in conda and report results
|
||||
@@ -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?
|
||||
@@ -0,0 +1,14 @@
|
||||
# Change: Update API Consistency for WebSocket Auth, Workload Defaults, and Task Locking
|
||||
|
||||
## Why
|
||||
Several API behaviors are currently ambiguous or inconsistent (WebSocket auth handshake messaging, optimistic locking conflict payloads, and workload heatmap defaults). These gaps can confuse clients and reduce product completeness.
|
||||
|
||||
## What Changes
|
||||
- Clarify WebSocket authentication error handling and client expectations.
|
||||
- Standardize optimistic locking conflict responses for task updates.
|
||||
- Define workload heatmap default inclusion rules and Sunday week-window behavior.
|
||||
- Align workload heatmap `hide_empty` defaults and caching behavior.
|
||||
|
||||
## Impact
|
||||
- Affected specs: user-auth, task-management, resource-management
|
||||
- Affected code: backend WebSocket router, task update endpoint, workload service/router, workload cache; frontend workload views may require adjustments depending on default behavior.
|
||||
@@ -0,0 +1,35 @@
|
||||
## MODIFIED Requirements
|
||||
### Requirement: Workload Heatmap UI
|
||||
The system SHALL provide a visual workload heatmap interface for managers.
|
||||
|
||||
#### Scenario: View workload heatmap
|
||||
- **GIVEN** user is logged in as manager or admin
|
||||
- **WHEN** user navigates to /workload page without filters
|
||||
- **THEN** system displays a heatmap showing all accessible users' workload
|
||||
- **AND** users with zero workload are included by default
|
||||
- **AND** each user cell is color-coded by load level (green/yellow/red)
|
||||
|
||||
#### Scenario: Hide empty workloads
|
||||
- **GIVEN** user is viewing the workload page
|
||||
- **WHEN** user enables the hide_empty filter
|
||||
- **THEN** the heatmap excludes users with zero workload
|
||||
|
||||
#### Scenario: Navigate between weeks
|
||||
- **GIVEN** user is viewing the workload page
|
||||
- **WHEN** user clicks previous/next week buttons
|
||||
- **THEN** the heatmap updates to show that week's workload data
|
||||
|
||||
#### Scenario: Default week window on Sunday
|
||||
- **GIVEN** today is Sunday and user opens workload page without selecting week_start
|
||||
- **THEN** the default heatmap window includes tasks due in the upcoming week
|
||||
|
||||
#### Scenario: View user workload details
|
||||
- **GIVEN** user is viewing the workload heatmap
|
||||
- **WHEN** user clicks on a specific user's cell
|
||||
- **THEN** a modal/drawer opens showing that user's task breakdown
|
||||
- **AND** tasks show title, project, time estimate, and due date
|
||||
|
||||
#### Scenario: Filter by department
|
||||
- **GIVEN** user is a system admin
|
||||
- **WHEN** user selects a department from the filter
|
||||
- **THEN** the heatmap shows only users from that department
|
||||
@@ -0,0 +1,16 @@
|
||||
## MODIFIED Requirements
|
||||
### Requirement: Optimistic Locking for Task Updates
|
||||
The system SHALL use optimistic locking to prevent concurrent update conflicts on tasks.
|
||||
|
||||
#### Scenario: Concurrent update detected
|
||||
- **WHEN** user A and user B both load task at version 1
|
||||
- **WHEN** user A saves changes, incrementing version to 2
|
||||
- **WHEN** user B attempts to save with version 1
|
||||
- **THEN** system returns 409 Conflict error
|
||||
- **AND** response includes a human-readable message instructing refresh and retry
|
||||
- **AND** response includes the current and provided version numbers
|
||||
|
||||
#### Scenario: Sequential updates succeed
|
||||
- **WHEN** user loads task at version N
|
||||
- **WHEN** user saves changes with correct version N
|
||||
- **THEN** system accepts update and increments version to N+1
|
||||
@@ -0,0 +1,18 @@
|
||||
## MODIFIED Requirements
|
||||
### Requirement: Secure WebSocket Authentication
|
||||
The system SHALL authenticate WebSocket connections without exposing tokens in URL query parameters.
|
||||
|
||||
#### Scenario: WebSocket connection with token in first message
|
||||
- **WHEN** client connects to WebSocket endpoint without a query token
|
||||
- **THEN** server waits for authentication message containing JWT token
|
||||
- **THEN** server validates token before accepting further messages
|
||||
- **THEN** server sends an authentication acknowledgment message
|
||||
|
||||
#### Scenario: WebSocket connection with invalid token
|
||||
- **WHEN** client sends an invalid or expired token
|
||||
- **THEN** server sends an error message indicating invalid or expired token
|
||||
- **THEN** server closes the connection with an authentication error code
|
||||
|
||||
#### Scenario: WebSocket connection timeout without authentication
|
||||
- **WHEN** client connects but does not send authentication within 10 seconds
|
||||
- **THEN** server closes the connection with appropriate error code
|
||||
@@ -0,0 +1,34 @@
|
||||
## 1. Implementation
|
||||
- [x] 1.1 Update WebSocket auth spec and align server handshake/error messaging with the agreed behavior
|
||||
- [x] 1.2 Update optimistic locking conflict response spec and implement standardized payload
|
||||
- [x] 1.3 Update workload heatmap defaults (hide_empty, week window) and cache behavior
|
||||
- [x] 1.4 Update frontend workload views and API handling if required by new defaults
|
||||
- [x] 1.5 Add/adjust tests for WebSocket auth, conflict responses, and workload heatmap defaults
|
||||
|
||||
---
|
||||
|
||||
## Implementation Summary
|
||||
|
||||
### Changes Made (commit f5f870d)
|
||||
|
||||
1. **WebSocket Auth** (`backend/app/api/websocket/router.py`)
|
||||
- Standardized error codes: 4001 (invalid token), 4003 (access denied), 4004 (not found)
|
||||
- Clear error reasons in WebSocket close messages
|
||||
|
||||
2. **Optimistic Locking** (`backend/app/api/tasks/router.py`)
|
||||
- 409 Conflict response with standardized payload:
|
||||
- `error: "conflict"`
|
||||
- `message`, `current_version`, `provided_version`, `your_version`
|
||||
|
||||
3. **Workload Heatmap** (`backend/app/api/workload/router.py`, `workload_service.py`)
|
||||
- `hide_empty=True` as default
|
||||
- Caching only when `hide_empty=True`
|
||||
- Week bounds handle Sunday correctly (returns previous Monday)
|
||||
|
||||
4. **Frontend** (already aligned)
|
||||
- `workload.ts`: `hideEmpty: boolean = true` default
|
||||
- TaskDetailModal, GanttChart, CalendarView: Handle 409 conflict with conflict banner UI
|
||||
|
||||
5. **Tests** (`backend/tests/test_workload.py`)
|
||||
- Week bounds tests including Sunday handling
|
||||
- Load level calculation tests
|
||||
Reference in New Issue
Block a user