# 📚 文檔指南 (更新 2025-09-09)

本文檔提供 Drama Ling 專案文檔結構的完整說明。

## 📁 目錄結構 (修正 2025-09-09)

```
docs/
├── 00_starter/             # 專案初始化和模板  
├── 01_requirement/         # 專案需求和規格說明
├── 02_design/              # 設計和使用者體驗文檔
├── 03_development/         # 開發指南和工作流程
├── 04_technical/           # 技術架構和規格說明
└── README.md              # 本文件 - 文檔總覽
```

---

## 📂 目錄詳細說明

### 🚀 `/00_starter` - 專案基礎
**用途**: 包含專案初始化和AI輔助開發所使用的基礎模板和提示詞。

| 檔案名稱                              | 用途                           |
| ------------------------------------- | ------------------------------ |
| `CLAUDE_TEMPLATE.md`                  | Claude AI 互動模板和專案設置   |
| `READ.md`                             | 使用入門模板的說明指引         |
| `business_function_design_prompt.md`  | 生成業務功能設計的 AI 提示詞   |
| `generate_requirements_prompt.md`     | 創建專案需求的 AI 提示詞       |
| `generate_system_structure_prompt.md` | 系統架構生成的 AI 提示詞       |
| `system_detail_prompt.md`             | 詳細系統規格的 AI 提示詞       |
| `system_structured_schema.json`       | 結構化系統設計輸出的 JSON 架構 |

**使用時機**: 這些檔案主要在專案初始化時使用，以及與 AI 助手協作生成文檔和程式碼結構時使用。

---

### 📋 `/01_requirement` - 需求文檔
**用途**: 包含核心專案需求、規格說明和系統設計文檔。**專注於知識管理和規格定義**。

| 檔案名稱                       | 用途                                                              |
| ------------------------------ | ----------------------------------------------------------------- |
| `founding_pitch.md`            | 初始專案提案和商業案例                                            |
| `requirements.md`              | **產品功能需求總覽** - 詳細的產品規格和功能概述                   |
| `user-stories.md`              | **用戶故事和使用場景** - 用戶需求和互動情境                       |
| `business-rules.md`            | **業務邏輯和規則定義** - 核心商業規則和流程                       |
| `acceptance-criteria.md`       | **驗收標準和測試條件** - 功能驗收和品質標準                       |
| `system_structure_design.json` | **結構化系統設計** - 從需求生成，包含模組、功能和UI視圖的JSON格式 |

**關鍵文檔**: `requirements.md` 是產品應該做什麼以及如何運作的唯一真實來源。

---

### 🎨 `/02_design` - 設計規格 (更新 2025-09-09)
**用途**: 涵蓋使用者體驗、視覺設計和互動模式的文檔。**專注於知識管理和規格定義**。

| 檔案名稱                     | 用途                                                |
| ---------------------------- | --------------------------------------------------- |
| `prototype-design-plan.md`   | **原型設計製作計劃** - 雛形畫面開發的完整規劃       |
| `function-specs/`            | **平台別功能規格** - mobile/web/common功能詳細規格  |
| `prototypes/`                | **HTML原型系統** - 可互動的功能演示界面             |
| `ui-ux/`                     | **UI/UX設計系統** - 視覺規範、組件庫、樣式指南      |
| `views/`                     | **UI視圖設計檔案** - 介面設計的視覺化參考           |

**實際子目錄結構**:
- `function-specs/common/` - 跨平台共用規格（API、資料模型、業務規則等）
- `function-specs/mobile/` - 行動端專用功能規格  
- `function-specs/web/` - 網頁端專用功能規格
- `ui-ux/ui-ux-guidelines.md` - 統一的UI/UX設計規範
- `ui-ux/dramaling-ui.css` - Drama Ling設計系統樣式表

**目標讀者**: 設計師、前端開發人員和產品經理。

---

### 👨‍💻 `/03_development` - 開發文檔 (更新 2025-09-09)
**用途**: 為開發人員提供編碼標準、工作流程和專案路線圖的指南。**專注於知識管理和規格定義**。

| 檔案名稱                   | 用途                                                                          |
| -------------------------- | ----------------------------------------------------------------------------- |
| `coding-standards.md`      | **程式碼規範** - Flutter/Dart 和 .NET/C# 的程式碼風格指南、命名慣例和最佳實踐 |
| `architecture-overview.md` | **系統架構概述** - 整體系統架構和設計決策說明                                 |
| `deployment-guide.md`      | **部署流程文檔** - 部署步驟、環境配置和發布流程                               |
| `troubleshooting.md`       | **常見問題排除** - 開發過程中常見問題的解決方案                               |
| `development-workflow.md`  | Git 工作流程、分支策略、程式碼審查流程和開發生命週期                          |
| `project-roadmap.md`       | **開發時程表** - 階段、里程碑和功能交付時程                                   |

**目標讀者**: 所有參與專案的開發人員。

---

### ⚙️ `/04_technical` - 技術規格 (更新 2025-09-09)
**用途**: 技術實作細節、系統架構和整合規格說明。**專注於知識管理和規格定義**。

| 子目錄/檔案                | 用途                                                  |
| -------------------------- | ----------------------------------------------------- |
| `api-specifications.md`    | **API接口文檔** - 完整API規格、端點定義和資料格式     |
| `database-schema.md`       | **資料庫設計文檔** - 資料表結構、關聯和索引設計       |
| `security-requirements.md` | **安全性需求** - 安全標準、認證機制和資料保護         |
| `performance-standards.md` | **效能標準定義** - 效能指標、基準測試和優化準則       |
| `01_architecture/`         | 系統架構設計和決策文檔                                |
| `02_api/`                  | **REST API 文檔** - 完整API規格、端點文檔、Swagger UI |
| `03_frontend/`             | 前端技術規格和實作指南                                |
| `04_mobile/`               | 移動端開發技術規格                                    |
| `05_deployment/`           | 部署流程和環境配置                                    |
| `06_development/`          | **開發過程管理** - 問題追蹤、環境設定和開發工具配置   |
| `07_planning/`             | 技術規劃和決策記錄                                    |

**關鍵文檔**: `02_api/` 目錄中的API文檔作為前端和後端團隊之間的契約。

---

## 📋 文檔層核心原則 (新增 2025-09-10)

### 🎯 核心職責
**docs/ 目錄專注於知識管理和規格定義**

所有 docs/ 目錄下的文檔都應該：
- 定義「是什麼」(What) 和「如何做」(How)
- 提供規格、標準和指南
- 作為參考文檔和知識庫
- 保持相對穩定，不頻繁變動

### ❌ docs/ 不應該包含

以下內容**不應該**出現在 docs/ 目錄中：

- **具體任務分配** - 屬於 TASKS.md 或 projects/
- **時程安排和里程碑** - 屬於專案管理層
- **個人待辦事項** - 屬於任務管理層  
- **專案進度追蹤** - 屬於專案管理層
- **實施細節規劃** - 屬於任務執行層
- **臨時性討論記錄** - 屬於會議記錄或溝通工具
- **狀態更新和進度報告** - 屬於專案管理工具

### ✅ 正確的內容分層

| 內容類型            | 正確位置               |
| ------------------- | ---------------------- |
| 產品規格和需求      | `docs/01_requirement/` |
| 設計標準和指南      | `docs/02_design/`      |
| 技術架構和 API 規格 | `docs/04_technical/`   |
| 編碼規範和流程      | `docs/03_development/` |
| 具體任務和待辦事項  | `TASKS.md`             |
| 專案執行計畫        | `projects/[專案名].md` |
| 進度追蹤和狀態更新  | 專案管理工具           |

---

## 🎯 如何使用這個文檔

### 新團隊成員 (更新 2025-09-09)
1. **從這裡開始**: 閱讀這個 `README.md` 文檔總覽
2. **了解產品**: 閱讀 `/01_requirement/requirements.md`
3. **學習技術棧**: 查看 `/04_technical/01_architecture/`
4. **遵循開發流程**: 學習 `/03_development/development-workflow.md`
5. **遵守編碼標準**: 查看 `/03_development/coding-standards.md`

### 前端開發人員 (更新 2025-09-09)
- 主要文檔: `/02_design/ui-ux-guidelines.md`, `/04_technical/03_frontend/`
- API 契約: `/04_technical/02_api/`
- 編碼標準: `/03_development/coding-standards.md`
- 功能規格: `/02_design/function-specs/`

### 後端開發人員 (更新 2025-09-09)
- 主要文檔: `/04_technical/02_api/`, `/04_technical/01_architecture/`
- 商業邏輯: `/02_design/business-logic-rules.md`
- 部署指南: `/04_technical/05_deployment/`

### 產品經理 (更新 2025-09-09)
- 主要文檔: `/01_requirement/requirements.md`, `/03_development/project-roadmap.md`
- 設計規格: `/02_design/` 目錄下的所有檔案
- 進度追蹤: `/03_development/project-roadmap.md`

### 設計師 (更新 2025-09-09)
- 主要文檔: `/02_design/ui-ux-guidelines.md`, `/02_design/gamification-mechanics.md`
- 內容策略: `/02_design/content-management-specs.md`
- 功能規格: `/02_design/function-specs/`
- 原型參考: `/02_design/prototypes/`

---

## 🔄 文檔維護

### 何時更新 (更新 2025-09-09)
- **需求變更**: 更新 `/01_requirement/requirements.md` 並重新生成 `system_structure_design.json`
- **API 變更**: 更新 `/04_technical/02_api/` 目錄中相關檔案
- **設計更新**: 更新 `/02_design/` 目錄中相關檔案
- **新功能**: 更新 `/03_development/project-roadmap.md` 中的路線圖
- **架構變更**: 更新 `/04_technical/01_architecture/` 中相關文檔

### 責任歸屬 (更新 2025-09-09)
- **產品團隊**: `/01_requirement/` 和 `/02_design/` 目錄
- **工程團隊**: `/04_technical/` 和 `/03_development/` 目錄
- **AI/DevOps**: `/00_starter/` 目錄（模板維護）

---

## 🔍 快速參考

| 尋找...            | 前往...                                   |
| ------------------ | ----------------------------------------- |
| 要建構什麼功能     | `/01_requirement/requirements.md`         |
| API 端點和資料格式 | `/04_technical/02_api/`                   |
| 系統架構           | `/04_technical/01_architecture/`          |
| UI 設計標準        | `/02_design/ui-ux-guidelines.md`          |
| 如何貢獻程式碼     | `/03_development/development-workflow.md` |
| 開發時程表         | `/03_development/project-roadmap.md`      |
| 功能規格           | `/02_design/function-specs/`              |
| 部署流程           | `/04_technical/05_deployment/`            |

---

## 📞 技術支援

如果您需要任何文檔的說明：
- 📧 Email: dev@dramaling.com
- 💬 Slack: #dev-support  
- 📱 Issues: [GitHub Issues](https://github.com/JettCheng/DramaLingApp/issues)

---

**最後更新**: 2025-09-10 ✅  
**版本**: 3.0.1 - 重新定義06_development目錄職責，明確開發過程管理範疇 (2025-09-10)