全域需求儲存庫

本提案建立一個集中式、產品導向的需求儲存庫，作為跨平台（Web、iOS、Android、Backend）所有產品需求的單一事實來源。AI 代理在實作前存取此儲存庫以理解功能規格，確保跨平台一致性並減少需求碎片化。

核心洞察： 分散在平台特定文件中的需求會導致實作分歧。一個單一的、AI 可存取的需求儲存庫讓代理能從相同的事實來源在所有端點生成一致的程式碼。

問題陳述

當前狀態：碎片化的需求

團隊回饋的證據

痛點	影響
平台特定 PRD	每個團隊維護自己對需求的詮釋
需求版本控制	PRD 變更與程式碼變更無關聯
跨平台不一致	同一功能在不同平台有不同行為
AI 脈絡碎片化	代理只看到本地需求，錯失全局
重複規格	同一需求文件化 4+ 次且有變異

根本問題

每個 AI 代理只看到其平台的詮釋，導致：

不一致的功能實作
某些平台遺漏邊界情況
衝突的 API 合約
冗餘的規格工作

提議解決方案：全域需求儲存庫

目標架構

核心原則

產品中心組織：需求按產品分組，而非平台
單一事實來源：一個規範需求，平台特定補充
API 優先合約：後端 API 與需求一起定義
AI 原生格式：具機器可讀中繼資料的結構化 Markdown
版本關聯：需求變更連結到實作 PR
跨產品引用：跨產品邊界的共享概念和依賴關係

儲存庫結構

目錄佈局

requirement-store/
├── CLAUDE.md                       # AI 代理指引
├── README.md                       # 人類概覽
├── .schema/
│   ├── requirement.schema.json    # 需求文件 schema
│   ├── api-contract.schema.json   # API 合約 schema
│   └── ux-spec.schema.json        # UX 規格 schema
│
├── products/
│   ├── vsaas/
│   │   ├── _product.md            # 產品概覽
│   │   ├── features/
│   │   │   ├── device-management/
│   │   │   │   ├── requirement.md      # 核心需求（所有平台）
│   │   │   │   ├── api-contract.md     # 後端 API 規格
│   │   │   │   ├── ux-spec.md          # UX/UI 規格
│   │   │   │   ├── test-cases.md       # 驗收標準
│   │   │   │   └── platforms/
│   │   │   │       ├── web.md          # Web 特定備註
│   │   │   │       ├── ios.md          # iOS 特定備註
│   │   │   │       └── android.md      # Android 特定備註
│   │   │   │
│   │   │   └── video-playback/
│   │   │       └── ...
│   │   │
│   │   └── shared/
│   │       ├── device-identity.md     # 跨功能領域概念
│   │       └── authentication.md
│   │
│   └── vortex/
│       └── ...
│
├── shared/                           # 跨產品共享概念
│   ├── domains/
│   │   ├── user-identity.md         # 跨產品使用者/帳戶概念
│   │   ├── organization.md          # 組織/租戶階層
│   │   ├── permissions.md           # RBAC/權限模型
│   │   └── notifications.md         # 通知模式
│   │
│   ├── integrations/
│   │   ├── sso.md                   # SSO 整合需求
│   │   ├── billing.md               # 計費/訂閱處理
│   │   └── analytics.md             # 跨產品分析
│   │
│   └── ux-patterns/
│       ├── navigation.md            # 跨產品導航
│       ├── branding.md              # 品牌一致性需求
│       └── accessibility.md         # 無障礙需求
│
├── contracts/
│   ├── api-standards.md           # API 設計標準
│   ├── error-codes.md             # 全域錯誤碼註冊表
│   └── data-models.md             # 共享資料模型定義
│
└── templates/
    ├── requirement.template.md
    ├── api-contract.template.md
    └── platform-notes.template.md

需求文件結構

markdown

id: req-device-management
title: 裝置管理
product: vsaas
version: 2.3.0
status: approved
priority: high
created: 2025-01-15
updated: 2025-11-28
authors:
  - pm@company.com
reviewers:
  - tech-lead@company.com
platforms:
  - web
  - ios
  - android
api_version: v2
related_features:
  - device-provisioning
  - device-monitoring
tags:
  - device
  - crud
  - core-feature
# 裝置管理

## 概覽

功能的簡要描述及其業務價值。

## 使用者故事

### US-001：檢視裝置列表
作為**站點管理員**，我想要**檢視我站點中的所有裝置**
以便**一目了然地監控裝置狀態**。

**驗收標準：**
- [ ] 顯示裝置名稱、狀態和最後連線時間
- [ ] 支援超過 100 台裝置的站點分頁
- [ ] 顯示上線/離線指示器
- [ ] 允許按名稱、狀態或最後連線時間排序

## 功能需求

### FR-001：裝置列表擷取
- 系統應為已驗證使用者可存取的站點擷取裝置
- 系統應在 5 秒內回傳裝置狀態
- 系統應支援按站點、狀態和裝置類型篩選

## 非功能需求

### NFR-001：效能
- 裝置列表應在 2 秒內載入最多 500 台裝置
- 搜尋結果應在 500ms 內出現

## 業務規則

### BR-001：裝置限制
- 免費方案：每站點最多 5 台裝置
- 專業方案：每站點最多 50 台裝置
- 企業方案：無限制裝置

## AI 實作備註

@ai-hint 實作裝置列表時，使用基於游標的分頁方式。
@ai-hint 裝置狀態應使用 shared/device-identity.md 的 DeviceStatus 列舉。
@ai-hint 所有裝置操作需要站點層級授權檢查。
@see api-contract.md 取得 API 端點
@see platforms/web.md 取得 Web 特定元件使用

跨平台一致性

共享領域概念

建立所有平台引用的共享定義：

markdown

# products/vsaas/shared/device-identity.md

id: domain-device-identity
type: domain-concept
# 裝置識別

## 術語

| 術語 | 定義 | 使用 |
|------|------|------|
| **DeviceKey** | 系統分配的唯一識別碼 (dk_*) | 所有內部引用、API 呼叫 |
| **DeviceId** | 硬體識別碼（MAC 地址）| 僅裝置探索 |
| **DeviceName** | 使用者定義的顯示名稱 | UI 顯示、面向使用者 |

## 狀態狀態

```mermaid
stateDiagram-v2
    [*] --> Connecting: 註冊
    Connecting --> Online: 已連線
    Connecting --> Error: 失敗
    Online --> Offline: 逾時
    Offline --> Online: 重新連線
    Online --> Error: 致命錯誤
    Error --> Connecting: 重試

AI 指引

@ai-hint 註冊後永遠不要使用 MAC 地址作為識別碼。 @ai-hint DeviceKey 一旦分配即不可變。 @ai-hint 狀態轉換必須遵循狀態圖。


### 跨產品引用

當需求跨越多個產品時，使用明確的跨產品引用：

```markdown
# shared/domains/user-identity.md

id: domain-user-identity
type: cross-product-domain
scope: global
products:
  - vsaas
  - vortex
  - cloud-portal
# 使用者識別

## 概覽

定義跨所有產品共享的統一使用者識別模型。
產品必須引用此文件，而非定義自己的使用者模型。

## 核心概念

| 概念 | 定義 | 產品 |
|------|------|------|
| **UserId** | 全域唯一識別碼 (usr_*) | 所有產品 |
| **AccountId** | 組織識別碼 (acc_*) | 所有產品 |
| **TenantId** | 多租戶隔離鍵 | VSaaS、Vortex |

## 跨產品行為

### 單一登入
- 在產品 A 認證的使用者自動在產品 B 認證
- Session 令牌跨產品邊界有效
- @see shared/integrations/sso.md

### 統一權限
- 權限跨產品遵循階層模型
- 產品特定角色繼承自全域角色
- @see shared/domains/permissions.md

## AI 實作備註

@ai-hint 使用者識別永遠從共享認證服務取得，絕不從產品特定服務。
@ai-hint 實作使用者相關功能時，先檢查 shared/domains/user-identity.md。
@ai-hint 跨產品功能必須使用共享領域概念。

引用類型

引用類型	語法	使用案例
同產品	`related_features: [device-provisioning]`	同產品內的功能
跨產品	`cross_product_refs: [vortex/features/device-sync]`	不同產品的功能
共享領域	`cross_product_refs: [shared/domains/user-identity]`	全域領域概念
依賴	`depends_on: [shared/integrations/sso]`	實作前必須完成

依賴圖

跨產品情境

本節詳述常見的跨產品情境以及全域需求儲存庫如何解決它們。

情境 1：共享功能實作

當多個產品需要相同功能時（例如 VSaaS 和 Vortex 之間的裝置共享）：

共享功能的目錄結構：

requirement-store/
├── shared/
│   └── features/
│       └── device-sharing/
│           ├── requirement.md       # 共享業務邏輯
│           ├── api-contract.md      # 產品間 API
│           └── integration-spec.md  # 產品如何整合
│
├── products/
│   ├── vsaas/features/device-management/
│   │   └── requirement.md
│   │       # cross_product_refs: [shared/features/device-sharing]
│   │
│   └── vortex/features/device-sync/
│       └── requirement.md
│           # cross_product_refs: [shared/features/device-sharing]

情境 2：跨產品資料流

當資料在產品間流動時（例如分析彙總）：

markdown

# shared/integrations/analytics.md

id: integration-analytics
type: cross-product-integration
scope: global
products:
  - vsaas
  - vortex
  - cloud-portal
data_flow:
  - source: vsaas
    sink: cloud-portal
    events: [device_added, device_removed, stream_started]
  - source: vortex
    sink: cloud-portal
    events: [sync_completed, sync_failed]
# 跨產品分析整合

## 概覽

定義分析事件如何從產品流向中央 Cloud Portal 儀表板。

## 事件合約

所有產品必須依照此 schema 發送事件：

```typescript
interface AnalyticsEvent {
  eventId: string;           // 唯一事件 ID (evt_*)
  productId: string;         // 來源產品：vsaas | vortex | cloud-portal
  eventType: string;         // 來自產品事件目錄的事件類型
  timestamp: string;         // ISO 8601 UTC
  userId: string;            // 來自 shared/domains/user-identity 的使用者
  accountId: string;         // 來自 shared/domains/organization 的帳戶
  payload: Record<string, unknown>;  // 事件特定資料
}

AI 實作備註

@ai-hint 實作分析時，永遠檢查此文件的事件 schema。 @ai-hint 事件必須包含來自共享領域概念的 userId 和 accountId。 @ai-hint 不要建立產品特定的事件 schema 而不更新此合約。


### 情境 3：跨產品使用者旅程

當使用者旅程跨越多個產品時：

```markdown
# shared/journeys/device-onboarding.md

id: journey-device-onboarding
type: cross-product-journey
scope: global
products:
  - cloud-portal    # 進入點
  - vsaas           # 裝置註冊
  - vortex          # 初始同步
touchpoints:
  - product: cloud-portal
    feature: account-setup
    step: 1
  - product: vsaas
    feature: device-management
    step: 2
  - product: vortex
    feature: device-sync
    step: 3
# 裝置上線旅程

## 旅程概覽

```mermaid
journey
    title 裝置上線
    section Cloud Portal
      註冊: 5: 使用者
      建立組織: 4: 使用者
    section VSaaS
      新增第一台裝置: 3: 使用者, 系統
      設定裝置: 4: 使用者
    section Vortex
      初始同步: 5: 系統
      驗證同步: 4: 使用者

跨產品交接

從	到	交接資料	合約
Cloud Portal	VSaaS	userId, accountId, orgId	shared/domains/user-identity
VSaaS	Vortex	deviceKey, userId	vsaas/shared/device-identity
Vortex	Cloud Portal	syncStatus, deviceKeys	shared/integrations/analytics

AI 實作備註

@ai-hint 每次交接必須保留合約欄位中定義的脈絡。 @ai-hint 使用者不應在產品間重新認證（使用 shared/integrations/sso）。 @ai-hint 旅程放棄事件應追蹤在 shared/integrations/analytics。



## 跨產品治理

### 所有權模型

```mermaid
graph TD
    subgraph "治理結構"
        ARCH[架構公會] --> SHARED[shared/]
        ARCH --> CONTRACTS[contracts/]

        VSAAS_PM[VSaaS PM] --> VP[products/vsaas/]
        VORTEX_PM[Vortex PM] --> VXP[products/vortex/]
        CP_PM[Cloud Portal PM] --> CPP[products/cloud-portal/]

        SHARED --> |審查| VSAAS_PM
        SHARED --> |審查| VORTEX_PM
        SHARED --> |審查| CP_PM
    end

    style ARCH fill:#e8f5e9
    style SHARED fill:#e1f5fe
    style CONTRACTS fill:#e1f5fe

變更管理規則

變更類型	擁有者	審查者	批准
產品功能	產品 PM	技術主管	產品 PM
跨產品引用新增	產品 PM	架構公會	雙方
共享領域變更	架構公會	所有受影響 PM	架構公會 + 所有 PM
合約變更	架構公會	所有產品團隊	架構公會
整合變更	擁有產品 PM	所有消費 PM	所有方

衝突解決

當產品有衝突的需求時：

偵測：CI 驗證 cross_product_refs 的衝突
升級：透過 PR 標籤通知架構公會
解決：與受影響 PM 的聯合會議
文件：決策記錄在 contracts/decisions/

markdown

# contracts/decisions/DEC-001-device-status-naming.md

id: DEC-001
date: 2025-11-15
participants:
  - vsaas-pm@company.com
  - vortex-pm@company.com
  - architect@company.com
status: resolved
# 決策：裝置狀態命名慣例

## 衝突

- VSaaS 使用：`online`、`offline`、`error`
- Vortex 使用：`connected`、`disconnected`、`failed`

## 解決方案

跨所有產品標準化為 VSaaS 命名（`online`、`offline`、`error`）。

## 遷移

- Vortex 在 v3.0 版本前遷移
- 向後相容層持續 2 個版本

## AI 實作備註

@ai-hint 所有裝置狀態使用 `online`、`offline`、`error`。
@ai-hint 舊版 `connected`/`disconnected`/`failed` 已棄用。

跨產品驗證

自動化一致性檢查

typescript

// CI 驗證腳本
interface CrossProductValidator {
  // 驗證所有 cross_product_refs 解析到現有文件
  validateReferences(): ValidationResult[];

  // 檢查共享領域概念是否一致使用
  validateTerminology(): TerminologyReport[];

  // 確保 API 合約不衝突
  validateApiContracts(): ApiConflict[];

  // 驗證旅程接觸點已實作
  validateJourneys(): JourneyGap[];
}

// 範例 CI 輸出
const validationResults = {
  references: {
    total: 45,
    valid: 43,
    broken: [
      'vsaas/features/alerts -> shared/domains/notifications（未找到）',
      'vortex/features/backup -> shared/integrations/storage（已棄用）'
    ]
  },
  terminology: {
    conflicts: [
      {
        term: 'device status',
        usages: [
          { product: 'vsaas', values: ['online', 'offline'] },
          { product: 'vortex', values: ['connected', 'disconnected'] }
        ],
        recommendation: '見 contracts/decisions/DEC-001'
      }
    ]
  }
};

MCP 驗證工具

typescript

// 擴展的 MCP 伺服器驗證工具
const requirementStoreServer = {
  // ... 現有工具 ...

  tools: {
    // 驗證功能的跨產品一致性
    validateCrossProduct: async ({ product, feature }) => {
      const requirement = await readRequirement(product, feature);
      const refs = requirement.frontmatter.cross_product_refs || [];

      const validation = {
        referencesValid: await validateRefs(refs),
        terminologyConsistent: await checkTerminology(requirement),
        apiCompatible: await checkApiCompatibility(product, feature),
        journeyCovered: await checkJourneyImplementation(product, feature)
      };

      return validation;
    },

    // 找出共享變更影響的所有產品
    impactAnalysis: async ({ sharedPath }) => {
      const affectedProducts = await findReferencingProducts(sharedPath);
      const impactedFeatures = await findReferencingFeatures(sharedPath);

      return {
        products: affectedProducts,
        features: impactedFeatures,
        estimatedImpact: calculateImpact(impactedFeatures)
      };
    },

    // 根據內容相似性建議跨產品引用
    suggestReferences: async ({ product, feature }) => {
      const requirement = await readRequirement(product, feature);
      const suggestions = await findSimilarConcepts(requirement);

      return suggestions.map(s => ({
        suggestedRef: s.path,
        reason: s.similarity,
        confidence: s.score
      }));
    }
  }
};

Pre-Commit Hooks

yaml

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: validate-cross-product-refs
        name: 驗證跨產品引用
        entry: scripts/validate-refs.js
        language: node
        files: 'products/.*/features/.*/requirement\.md$'

      - id: check-shared-terminology
        name: 檢查共享術語
        entry: scripts/check-terminology.js
        language: node
        files: '\.md$'

      - id: api-contract-compatibility
        name: API 合約相容性
        entry: scripts/check-api-compat.js
        language: node
        files: 'api-contract\.md$'

AI 代理整合

CLAUDE.md 模板

markdown

# 需求儲存庫 - AI 指引

## 目的

此儲存庫是所有產品需求的單一事實來源。
實作任何功能前，請查閱相關需求文件。

## 尋找需求

1. 導航到 `products/{product}/features/{feature}/`
2. 閱讀 `requirement.md` 取得業務需求
3. 閱讀 `api-contract.md` 取得 API 規格
4. 閱讀 `platforms/{platform}.md` 取得平台特定備註

## 實作前

1. 搜尋功能：products/{product}/features/{feature-name}/
2. 完整閱讀 requirement.md
3. 檢查 frontmatter 中的相關功能
4. 審查 products/{product}/shared/ 中的共享概念
5. 驗證 API 合約與你的實作匹配

## 跨平台一致性

實作功能時：
- 跨所有平台遵循相同的 requirement.md
- 平台差異僅放在 platforms/{platform}.md
- API 呼叫必須完全匹配 api-contract.md
- 使用 shared/*.md 中的共享領域術語

MCP 資源提供者

typescript

// requirement-store MCP server
const requirementStoreServer = {
  resources: {
    list: async ({ product, feature }) => {
      // 列出產品/功能的所有需求
      return requirements.map(req => ({
        uri: `req://${product}/${feature}/${req.id}`,
        name: req.title,
        mimeType: 'text/markdown',
        metadata: {
          version: req.version,
          status: req.status,
          platforms: req.platforms
        }
      }))
    }
  },
  tools: {
    getRequirement: async ({ product, feature }) => {
      // 回傳完整需求及所有相關文件
      return {
        requirement: await readFile(`products/${product}/features/${feature}/requirement.md`),
        apiContract: await readFile(`products/${product}/features/${feature}/api-contract.md`),
        platforms: await readPlatformDocs(product, feature)
      }
    }
  }
}

實作工作流程

功能開發流程

需求-程式碼關聯

markdown

# 在程式碼 PR 描述中

## 需求引用

- 需求：[req-device-management v2.3.0](../requirement-store/products/vsaas/features/device-management/requirement.md)
- API 合約：[api-device-management v2.3.0](../requirement-store/products/vsaas/features/device-management/api-contract.md)

## 已實作使用者故事

- [x] US-001：檢視裝置列表
- [x] US-002：新增裝置
- [ ] US-003：編輯裝置（下一個 PR）

## 偏差備註

無 - 實作完全遵循需求。

遷移策略

階段 1：模板與試點（第 1 個月）

[ ] 建立需求文件模板
[ ] 設定 requirement-store 儲存庫
[ ] 遷移 1 個功能（device-management）作為試點
[ ] 文件化 AI 代理整合模式

階段 2：新功能（第 2-3 個月）

[ ] 所有新功能從 requirement-store 開始
[ ] 要求所有 PR 中有需求引用
[ ] 訓練 PM 需求格式
[ ] 實作 MCP 資源提供者

階段 3：遷移（第 4-6 個月）

[ ] 優先遷移活躍功能
[ ] 轉換現有 Confluence PRD
[ ] 棄用平台特定需求文件
[ ] 完整 AI 代理整合

成功指標

指標	目標	如何測量
跨平台一致性	>95%	功能對等審計
需求覆蓋率	100% 活躍功能	儲存庫 vs 程式庫差異
AI 需求存取	<1s	MCP 工具延遲
PR-需求連結	100%	PR 模板合規性
需求新鮮度	<30 天	更新日期監控

要避免的反模式

1. 平台優先需求

問題： 從單一平台角度撰寫需求。

為何失敗： 其他平台改裝需求，導致不一致。

替代做法： 撰寫平台無關需求，另外加入平台備註。

2. API 後設計

問題： 在前端實作開始後才定義 API。

為何失敗： 前端做假設，後端不同，整合中斷。

替代做法： API 合約與需求一起定義，在實作前。

3. 陳舊需求

問題： 實作變更時需求未更新。

為何失敗： AI 代理根據過時規格生成程式碼。

替代做法： 任何變更規格的程式碼 PR 需要需求 PR。

4. 重複定義

問題： 同一概念在多個功能中有不同定義。

為何失敗： AI 得到衝突脈絡，生成不一致程式碼。

替代做法： 擷取到 shared/*.md，從功能引用。

相關： AI 代理友善知識庫 | 返回： 提案概覽

參考資料

Model Context Protocol (MCP) - Anthropic 的 AI 工具整合協定
RFC 9457 - HTTP API 的問題詳情規範
Claude Code 文件 - CLAUDE.md AI 指引檔案的官方文件
API-First Design - Swagger 的 API 優先開發指南

全域需求儲存庫 ​

問題陳述 ​

當前狀態：碎片化的需求 ​

團隊回饋的證據 ​

根本問題 ​

提議解決方案：全域需求儲存庫 ​

目標架構 ​

核心原則 ​

儲存庫結構 ​

目錄佈局 ​

需求文件結構 ​

跨平台一致性 ​

共享領域概念 ​

AI 指引 ​

引用類型 ​

依賴圖 ​

跨產品情境 ​

情境 1：共享功能實作 ​

情境 2：跨產品資料流 ​

AI 實作備註 ​

跨產品交接 ​

AI 實作備註 ​

變更管理規則 ​

衝突解決 ​

跨產品驗證 ​

自動化一致性檢查 ​

MCP 驗證工具 ​

Pre-Commit Hooks ​

AI 代理整合 ​

CLAUDE.md 模板 ​

MCP 資源提供者 ​

實作工作流程 ​

功能開發流程 ​

需求-程式碼關聯 ​

遷移策略 ​

階段 1：模板與試點（第 1 個月） ​

階段 2：新功能（第 2-3 個月） ​

階段 3：遷移（第 4-6 個月） ​

成功指標 ​

要避免的反模式 ​

1. 平台優先需求 ​

2. API 後設計 ​

3. 陳舊需求 ​

4. 重複定義 ​

參考資料 ​

全域需求儲存庫

問題陳述

當前狀態：碎片化的需求

團隊回饋的證據

根本問題

提議解決方案：全域需求儲存庫

目標架構

核心原則

儲存庫結構

目錄佈局

需求文件結構

跨平台一致性

共享領域概念

AI 指引

引用類型

依賴圖

跨產品情境

情境 1：共享功能實作

情境 2：跨產品資料流

AI 實作備註

跨產品交接

AI 實作備註

變更管理規則

衝突解決

跨產品驗證

自動化一致性檢查

MCP 驗證工具

Pre-Commit Hooks

AI 代理整合

CLAUDE.md 模板

MCP 資源提供者

實作工作流程

功能開發流程

需求-程式碼關聯

遷移策略

階段 1：模板與試點（第 1 個月）

階段 2：新功能（第 2-3 個月）

階段 3：遷移（第 4-6 個月）

成功指標

要避免的反模式

1. 平台優先需求

2. API 後設計

3. 陳舊需求

4. 重複定義

參考資料