224 lines
9.5 KiB
Markdown
224 lines
9.5 KiB
Markdown
# 📚 文檔指南 (更新 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)
|
||
**用途**: 涵蓋使用者體驗、視覺設計和互動模式的文檔。**專注於知識管理和規格定義**。
|
||
|
||
| 檔案名稱 | 用途 |
|
||
|------|---------|
|
||
| `ui-specifications.md` | **UI設計規範和標準** - 視覺設計標準和介面規範 |
|
||
| `ux-guidelines.md` | **用戶體驗設計指南** - 互動模式和使用者流程 |
|
||
| `component-library.md` | **UI組件庫文檔** - 可重用組件和設計系統 |
|
||
| `design-tokens.md` | **設計令牌和主題系統** - 顏色、字體、間距等設計變量 |
|
||
| `ai-algorithm-specs.md` | AI 分析演算法和語言處理規格 |
|
||
| `business-logic-rules.md` | 核心商業規則和邏輯流程定義 |
|
||
| `content-management-specs.md` | 內容創建、策劃和管理工作流程 |
|
||
| `gamification-mechanics.md` | 遊戲元素、成就和獎勵系統設計 |
|
||
| `ui-ux-guidelines.md` | 視覺設計標準、組件庫和使用者介面指南 |
|
||
| `function-specs/` | 平台別功能規格（mobile/web/common）|
|
||
| `html-prototypes/` | HTML原型和頁面範例 |
|
||
| `views/` | UI視圖設計檔案 |
|
||
|
||
**目標讀者**: 設計師、前端開發人員和產品經理。
|
||
|
||
---
|
||
|
||
### 👨💻 `/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/html-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.0 - 整合文檔層規範，明確定義文檔職責和禁止內容 (2025-09-10) |