feat: implement audit trail alignment (soft delete & permission audit)

- Task Soft Delete:
  - Add is_deleted, deleted_at, deleted_by fields to Task model
  - Convert DELETE to soft delete with cascade to subtasks
  - Add include_deleted query param (admin only)
  - Add POST /api/tasks/{id}/restore endpoint
  - Exclude deleted tasks from subtask_count

- Permission Change Audit:
  - Add user.role_change event (high sensitivity)
  - Add user.admin_change event (critical, triggers alert)
  - Add PATCH /api/users/{id}/admin endpoint
  - Add role.permission_change event type

- Append-Only Enforcement:
  - Add DB triggers for audit_logs immutability (manual for production)
  - Migration 008 with graceful trigger failure handling

- Tests: 11 new soft delete tests (153 total passing)
- OpenSpec: fix-audit-trail archived, fix-realtime-notifications & fix-weekly-report proposals added

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
beabigegg
2025-12-30 06:58:30 +08:00
parent 95c281d8e1
commit 10db2c9d1f
18 changed files with 1455 additions and 12 deletions

View File

@@ -0,0 +1,45 @@
# Change: Fix Audit Trail Alignment
## Why
現行實作與 audit-trail spec 有以下差距:
1. 任務刪除為硬刪除spec 要求軟刪除 (`is_deleted` 欄位)
2. 權限變更未記錄 `user.permission_change` 事件
3. 資料庫層未強制 append-only可被 UPDATE/DELETE
## What Changes
- **Task Model** - 新增 `is_deleted``deleted_at``deleted_by` 欄位
- **Task API** - 刪除改為軟刪除,查詢預設過濾已刪除
- **User/Role API** - 權限/角色變更時記錄 `user.permission_change` 事件
- **Migration** - 新增 Task 軟刪除欄位、設定 audit_logs 表 triggers 防止 UPDATE/DELETE
## Impact
- Affected specs: `audit-trail`
- Affected code:
- `backend/app/models/task.py` - 新增軟刪除欄位
- `backend/app/api/tasks/router.py` - 修改刪除邏輯與查詢過濾
- `backend/app/api/users/router.py` - 新增權限變更審計
- `backend/migrations/versions/` - 新增遷移
## Implementation Phases
### Phase 1: Task Soft Delete
- 新增 Task 軟刪除欄位
- 修改 delete_task 為軟刪除
- 修改查詢過濾已刪除任務
- 新增 restore_task API (可選)
### Phase 2: Permission Change Audit
- 角色指派變更記錄
- 權限更新記錄
- is_system_admin 變更記錄
### Phase 3: Append-Only Enforcement
- DB trigger 防止 UPDATE/DELETE
- 驗證 checksum 機制
## Dependencies
- audit-trail (已完成)
## Technical Decisions
- 軟刪除使用 `is_deleted` boolean 而非時間戳,簡化查詢
- DB trigger 使用 BEFORE UPDATE/DELETE RAISE EXCEPTION