---
source: ../../../templates/reverse-spec-template.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-01-19
status: current
---

# [SPEC-XXX] [功能名稱]（反向工程）

**版本**: 1.0.0
**最後更新**: 2026-01-19

> ⚠️ **此規格由現有程式碼反向工程而來**
>
> - **分析日期**: YYYY-MM-DD
> - **分析路徑**: `path/to/code`
> - **分析者**: [AI/人員名稱]
>
> 標記為 `[未知]` 的區塊需要人類確認後，此規格才算完成。

---

## 人類審查清單

在認為此規格完成之前，請驗證：

### 準確性
- [ ] 所有 `[已確認]` 項目已對照實際程式碼驗證
- [ ] 來源引用（file:line）正確
- [ ] 沒有捏造的 API、設定或行為

### 推斷驗證
- [ ] 所有 `[推斷]` 項目已審查準確性
- [ ] 不正確的推斷已更正或移除
- [ ] 推斷的推理合理

### 必要人類輸入
- [ ] `動機` 區塊已完成（為什麼此功能存在）
- [ ] `風險` 區塊已完成（潛在故障模式）
- [ ] `範圍外` 區塊已驗證（刻意排除的內容）
- [ ] `使用者故事` / 商業背景已新增

### 最終簽核
- [ ] 原始開發者已審查（如果可用）
- [ ] 產品負責人已核准商業背景
- [ ] 所有 `[未知]` 標籤已解決或確認

---

## 摘要

[已確認] 程式碼功能的簡要描述。

- [來源: 程式碼] `primary_file.ts:start-end`

<!-- 範例：
[已確認] 此模組透過 JWT 權杖提供使用者認證，支援登入、登出和權杖更新操作。

- [來源: 程式碼] src/controllers/AuthController.ts:1-150
- [來源: 程式碼] src/services/AuthService.ts:1-200
-->

---

## 動機

[未知] **需要人類輸入**

回答這些問題：

1. **為什麼要建立此功能？**
   <!-- 它解決什麼問題？商業驅動力是什麼？ -->

2. **誰請求了此功能？**
   <!-- 產品負責人、客戶、內部團隊？ -->

3. **它解決什麼使用者問題？**
   <!-- 使用者痛點、工作流程改善 -->

4. **原始時程/背景是什麼？**
   <!-- 何時建立？有任何相關背景嗎？ -->

---

## 使用者故事

[未知] **需要人類輸入**

```
身為 [使用者類型]，
我想要 [動作/功能]，
以便 [效益/價值]。
```

<!-- 範例：
身為已註冊的使用者，
我想要用我的電子郵件和密碼登入，
以便我可以存取我的個人儀表板和資料。
-->

---

## 詳細設計

### 架構概覽

[已確認/推斷] 從程式碼提取的高層級架構。

```
┌─────────────────────────────────────────────────────────────┐
│                        元件圖                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  [描述主要元件及其關係]                                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

- [來源: 程式碼] `src/architecture/` 或從 imports 推斷

### 元件詳情

#### 元件 1: [名稱]

[已確認] 元件職責描述。

- **位置**: `path/to/component`
- **相依性**: 相依性清單
- **關鍵方法**:
  - `methodName()` - 描述
  - `anotherMethod()` - 描述

- [來源: 程式碼] `file.ts:lines`

#### 元件 2: [名稱]

[已確認/推斷] 描述。

- [來源: 程式碼] `file.ts:lines`

### 資料模型

#### 模型: [實體名稱]

[已確認] 資料結構定義。

| 欄位 | 類型 | 必要 | 描述 |
|------|------|------|------|
| id | string | 是 | 主要識別碼 |
| field1 | type | 是/否 | [已確認] 描述 |
| field2 | type | 是/否 | [推斷] 描述 |

- [來源: 程式碼] `src/models/EntityName.ts:lines`

### API / 介面

#### 端點/方法 1

[已確認] `METHOD /path/to/endpoint`

**參數**:
| 名稱 | 位置 | 類型 | 必要 | 描述 |
|------|------|------|------|------|
| param1 | path/query/body | type | 是/否 | 描述 |

**請求 Body**（如適用）:
```json
{
  "field": "value"
}
```

**回應**:
```json
{
  "result": "value"
}
```

**錯誤代碼**:
| 代碼 | 描述 |
|------|------|
| 400 | [推斷] 錯誤請求 |
| 401 | [已確認] 未授權 |

- [來源: 程式碼] `src/controllers/Controller.ts:lines`

### 設定

[已確認] 從程式碼提取的設定。

| 設定 | 預設值 | 描述 | 來源 |
|------|--------|------|------|
| SETTING_1 | value | 描述 | [來源: 程式碼] config.ts:5 |
| SETTING_2 | value | 描述 | [來源: 程式碼] .env.example:10 |

---

## 驗收標準

### 從測試提取

[推斷] 從測試案例推導的驗收標準：

#### 功能區域 1

- [ ] [推斷] 從 `test_should_do_something` 的標準（test_file.ts:10）
- [ ] [推斷] 從 `test_should_handle_error` 的標準（test_file.ts:25）

#### 功能區域 2

- [ ] [推斷] 從測試分析的標準

- [來源: 程式碼] `src/tests/feature.test.ts`

### 覆蓋率缺口

[未知] 以下區域缺乏測試覆蓋率：

| 區域 | 風險等級 | 建議 |
|------|----------|------|
| 錯誤處理 | 🟡 中 | 修改前新增測試 |
| 邊界案例 | 🔴 高 | 需要文件化 |

---

## 相依性

### 外部相依性

[已確認] 來自 package.json/requirements.txt 的相依性：

| 套件 | 版本 | 用途 |
|------|------|------|
| package1 | ^1.0.0 | 描述 |
| package2 | ^2.0.0 | 描述 |

- [來源: 程式碼] `package.json:lines`

### 內部相依性

[已確認] 內部模組相依性：

| 模組 | 相依於 | 類型 |
|------|--------|------|
| AuthService | UserRepository | 執行時期 |
| UserController | AuthService, UserService | 執行時期 |

---

## 風險

[未知] **需要人類輸入**

### 技術風險

| 風險 | 可能性 | 影響 | 緩解措施 |
|------|--------|------|---------|
| <!-- 新增技術風險 --> | 低/中/高 | 低/中/高 | <!-- 緩解策略 --> |

### 商業風險

| 風險 | 可能性 | 影響 | 緩解措施 |
|------|--------|------|---------|
| <!-- 新增商業風險 --> | 低/中/高 | 低/中/高 | <!-- 緩解策略 --> |

### 已知問題 / 技術債

[未知] 記錄分析期間發現的任何已知問題：

| 問題 | 嚴重性 | 備註 |
|------|--------|------|
| <!-- 新增問題 --> | 低/中/高 | <!-- 額外背景 --> |

---

## 範圍外

[未知] **需要人類輸入**

此功能刻意不包含什麼？

- [ ] <!-- 項目 1 - 這是刻意排除的嗎？ -->
- [ ] <!-- 項目 2 -->

---

## 歷史背景

[未知] **需要人類輸入**

### 設計決策

| 決策 | 理由 | 日期 | 決策者 |
|------|------|------|--------|
| <!-- 決定了什麼 --> | <!-- 為什麼 --> | <!-- 何時 --> | <!-- 誰 --> |

### 權衡取捨

| 權衡 | 選擇的選項 | 替代方案 | 原因 |
|------|-----------|---------|------|
| <!-- 權衡描述 --> | <!-- 選擇了什麼 --> | <!-- 拒絕了什麼 --> | <!-- 為什麼 --> |

---

## 相關資源

### 程式碼參考

| 資源 | 路徑 | 描述 |
|------|------|------|
| 主要實作 | `src/path/to/main` | 主要程式碼位置 |
| 測試 | `src/tests/path` | 測試檔案 |
| 設定 | `src/config/path` | 設定檔案 |

### 文件

[未知] 現有文件（如果有）：

- [ ] README: `path/to/readme`（存在/缺失）
- [ ] API 文件: `path/to/docs`（存在/缺失）
- [ ] 架構: `path/to/arch`（存在/缺失）

### 相關規格

- [ ] [SPEC-XXX] 相關功能（如果有）

---

## 分析元資料

| 屬性 | 值 |
|------|-----|
| **分析者** | [AI 助手 / 人員名稱] |
| **分析日期** | YYYY-MM-DD |
| **工具/方法** | `/reverse-spec` 命令 |
| **程式碼版本** | Git commit hash 或版本 |
| **分析檔案數** | N 個檔案 |
| **程式碼行數** | N 行 |

### 確定性摘要

| 確定性等級 | 數量 | 百分比 |
|-----------|------|--------|
| [已確認] | N | X% |
| [推斷] | N | X% |
| [未知] | N | X% |

---

## 版本歷史

| 版本 | 日期 | 變更 | 作者 |
|------|------|------|------|
| 1.0.0 | YYYY-MM-DD | 初始反向工程規格 | [名稱] |

---

## 附錄：原始分析資料

<details>
<summary>點擊展開程式碼分析輸出</summary>

```
<!-- 在此貼上原始分析輸出供參考 -->
```

</details>
