E-Map 平面圖管理案例研究

本案例研究透過完整功能範例展示規格框架：為影像監控平台新增平面圖管理（E-Map）能力。

高階規格（提案）

提案捕捉業務意圖、範圍與影響評估。

# Change Proposal: E-Map Floor Plan Management

## Why

Organizations managing surveillance deployments across multi-floor buildings
need visual context to understand device placement and quickly access cameras
based on physical location. Current system provides logical organization
(groups/sites) but lacks visual floor plan mapping.

## What Changes

- Floor plan upload and storage (PNG, JPG, SVG)
- Device placement on floor plans with drag-and-drop
- Multiple floor plans per group (multi-floor buildings)
- Zone/area definition with custom labels
- Click-to-view functionality (device icon → live video)
- Role-based access control (Admin edit, others view-only)
- GraphQL API for floor plan operations

## Impact

### Affected Specs
- NEW: spatial-context/emap-management
- MODIFIED: authorization/rbac-permissions (add floor plan permissions)
- MODIFIED: device-management/metadata (add position attributes)

### Breaking Changes
- None (additive feature)

### Migration
- No data migration required
- Feature flag for gradual rollout

關鍵特性：

• 在「什麼」之前回答「為什麼」
• 明確識別受影響的規格
• 評估破壞性變更與遷移需求

設計文件

設計文件捕捉架構決策與理由及權衡。

# Design Document: E-Map Floor Plan Management

## Decisions

### Decision 1: Percentage-Based Positioning

**Choice:** Store device positions as percentage coordinates (0-100%)
rather than absolute pixel coordinates.

**Rationale:**
- Floor plans displayed at different resolutions across devices
- Percentage-based positioning scales naturally with image resizing
- Simplifies rendering logic across web and mobile

**Alternatives Considered:**
- Pixel-based: Would require recalculating positions on resize
- Grid-based: Would limit precision

**Trade-offs:**
- Minor rounding errors at extreme zoom (acceptable)

### Decision 2: Embedded Device Positions

**Choice:** Store DevicePositions as JSON within FloorPlan record,
not separate table.

**Rationale:**
- Typical floor plans have 5-50 devices (fits single record)
- Single-item operations reduce database costs
- Simplified queries (no joins)

**Trade-offs:**
- Record size limit (~200 devices per floor plan)
- Acceptable for use case; can migrate if needed

### Decision 3: Image Storage Strategy

**Choice:** Object storage with presigned URLs (1-hour expiry).

**Rationale:**
- Cost-effective for binary storage
- Secure temporary access without backend proxy
- Scales to millions of images

## Risks

### Risk 1: Large Images
Users may upload oversized floor plans causing slow loads.

**Mitigation:**
- 10MB file size limit
- Server-side compression (max 4000x4000)
- Thumbnails in list view

關鍵特性：

• 每個決策遵循 選擇 → 理由 → 替代方案 → 權衡
• 識別風險與緩解措施
• 有技術深度但無實作細節

領域規格

領域規格使用基於情境的格式定義需求。

# Spatial Context: E-Map Management

## Requirement: Floor Plan Upload

The system SHALL allow authorized users to upload floor plan images.

### Scenario: Upload valid floor plan image
- WHEN user uploads PNG, JPG, or SVG file
- AND file size is less than 10MB
- AND dimensions between 500x500 and 8000x8000 pixels
- THEN system SHALL store image in object storage
- AND create FloorPlan record with metadata
- AND return FloorPlanID and image URL

### Scenario: Reject oversized image
- WHEN user uploads image exceeding 10MB
- THEN system SHALL reject with error "FILE_TOO_LARGE"
- AND display "Floor plan image must be smaller than 10MB"

## Requirement: Device Placement

The system SHALL allow positioning devices on floor plans.

### Scenario: Place device on floor plan
- WHEN user drags device icon to position on floor plan
- THEN system SHALL store position as (x%, y%) coordinates
- AND position SHALL persist in FloorPlan.DevicePositions
- AND device icon SHALL appear at position when displayed

### Scenario: View device from floor plan
- WHEN user clicks device icon on floor plan
- THEN system SHALL display popover with device name and status
- AND provide "View Live" button to open video stream

## Requirement: Role-Based Access

### Scenario: Admin can edit floor plans
- WHEN user with Admin role accesses floor plan
- THEN system SHALL display editor controls
- AND allow modification operations

### Scenario: Viewer has read-only access
- WHEN user with Viewer role accesses floor plan
- THEN system SHALL display floor plan in read-only mode
- AND hide editing controls
- BUT allow clicking devices to view feeds (if permitted)

關鍵特性：

• WHEN/THEN 情境格式（機器可解析）
• SHALL/SHOULD/MAY 需求層級
• 依能力區域分組

實作任務

從規格衍生的任務，依領域組織。

# Implementation Tasks: E-Map Floor Plan Management

## 1. Backend Foundation
- [ ] 1.1 Define database schema for FloorPlan entity
- [ ] 1.2 Create domain model (FloorPlan, DevicePosition, Zone)
- [ ] 1.3 Implement repository interface and storage adapter
- [ ] 1.4 Add unit tests (target: 70% coverage)

## 2. API Layer
- [ ] 2.1 Define GraphQL schema (types, queries, mutations)
- [ ] 2.2 Implement resolvers with authorization checks
- [ ] 2.3 Add integration tests for API endpoints

## 3. Image Storage
- [ ] 3.1 Implement image upload with validation
- [ ] 3.2 Generate presigned URLs for retrieval
- [ ] 3.3 Configure lifecycle policy for cleanup

## 4. Authorization
- [ ] 4.1 Add floor plan permissions to policy
- [ ] 4.2 Implement group-based access checks
- [ ] 4.3 Add authorization unit tests

## 5. Frontend - List View
- [ ] 5.1 Create route and view component
- [ ] 5.2 Implement floor plan list with thumbnails
- [ ] 5.3 Add search/filter functionality
- [ ] 5.4 Connect to GraphQL queries

## 6. Frontend - Editor
- [ ] 6.1 Create canvas component with zoom/pan
- [ ] 6.2 Implement drag-and-drop device placement
- [ ] 6.3 Implement zone drawing tool
- [ ] 6.4 Add auto-save with debouncing

## 7. Testing
- [ ] 7.1 Unit tests for components and stores
- [ ] 7.2 E2E tests for critical flows
- [ ] 7.3 Authorization edge case tests

## 8. Documentation
- [ ] 8.1 API documentation
- [ ] 8.2 User guide section

關鍵特性：

• 編號以供引用與追蹤
• 依領域/元件分組
• 直接從規格衍生
• 可行動且原子化

規格可追溯性

E-Map 功能展示完整可追溯性：

意圖：「組織需要視覺平面圖對應」
    │
    ├── 提案（proposal.md）
    │   └── 識別 3 個受影響規格
    │
    ├── 設計文件（design.md）
    │   └── 7 個架構決策含理由
    │
    ├── 領域規格
    │   ├── spatial-context/emap-management（NEW）
    │   ├── authorization/rbac-permissions（MODIFIED）
    │   └── device-management/metadata（MODIFIED）
    │
    └── 實作任務（tasks.md）
        └── 8 個任務群組，約 40 個個別任務

每個實作任務透過領域規格、設計決策與高階提案追溯回原始意圖。此可追溯性啟用：

• 影響分析： 需求變更 → 識別受影響任務
• 稽核軌跡： 為何寫這段程式碼？ → 追溯到規格
• AI 脈絡： 代理接收完整規格鏈進行實作

部署後洞察

Phase 0 部署後，PM 立即要求進行 Phase 0.5+ 深度功能開發。快速擴展的關鍵洞察：

洞察 1：規格框架啟用快速回應

• PM 使用已建立的 Why/What/How 範本結構化複雜擴展請求
• AI 在數小時內（而非數週）產生完整功能需求
• 驗收條件品質匹配資深工程師輸出

洞察 2：知識庫倍增 AI 效能

• AI 可存取格式的競品分析（Verkada、Avigilon Alta）提供功能設計參考
• 脈絡工程（結構化提示、領域知識）對品質輸出至關重要

洞察 3：缺乏理由的現場回饋產生缺口

• 雪梨回饋驗證 MVP 但缺乏優先順序理由
• 沒有記錄的需求來源，難以證明範疇決策

洞察 4：E-Map 作為平台元件

• 平面圖有潛力成為核心功能，取代 Site 成為主要導航
• 開發團隊缺乏修改 Site 規格的權限
• 跨團隊規格可見性將啟用架構演進

洞察 5：開發過程中發現的規格缺口

• 產品規格缺少資源限制（如每站點最大平面圖數量）— 實作時才發現
• 原始規格無分析/遙測規劃 — 追蹤事件為可選但對產品決策有價值
• 建議：規格範本應包含「限制與約束」及「遙測事件」區塊

洞察 6：功能需求缺乏業務理由導致設計盲點

• PM 在最初規格討論時提出在 Floorplan/GlobalView 加入即時 Alarm 通知功能
• 然而無法清楚說明為何需要此功能，而非教育使用者透過既有的 Alarm 頁面處理事件
• 技術層面的問題：僅依賴 Web Frontend 開啟該頁面時捕捉事件並非一個覆蓋率高的策略
  • 使用者未開啟頁面時事件會遺漏
  • 無法保證即時性與可靠性
  • 與既有 Alarm 系統的職責劃分不明確
• 建議：規格範本應包含「既有替代方案分析」區塊，要求說明為何現有功能無法滿足需求

另一個案例： WebAuthn Passkey