# 📚 文檔指南 (更新 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)