universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/locales/zh-TW/core/documentation-writing-standards.md

@@ -0,0 +1,495 @@
+---
+source: ../../../core/documentation-writing-standards.md
+source_version: 1.0.1
+translation_version: 1.0.1
+last_synced: 2025-12-30
+status: current
+---
+
+# 文件撰寫規範
+
+> [English](../../../core/documentation-writing-standards.md) | **繁體中文**
+
+**版本**: 1.0.1
+**最後更新**: 2025-12-24
+**適用範圍**: 所有軟體專案（新建、重構、遷移、維護）
+
+---
+
+## 目的
+
+本標準根據專案類型定義文件需求，並提供各類文件的詳細撰寫指南。
+
+**與其他標準的關係**:
+- 補充 [documentation-structure.md](documentation-structure.md) 所定義的檔案組織
+- 本標準聚焦於**內容需求**和**專案類型對照**
+
+---
+
+## 專案類型與文件對照
+
+### 文件需求矩陣
+
+| 文件 | 新建專案 | 重構 | 遷移 | 維護 | 說明 |
+|----------|:-----------:|:-----------:|:---------:|:-----------:|-------------|
+| **README.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ✅ 必要 | 專案入口 |
+| **ARCHITECTURE.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ⚪ 建議 | 系統架構 |
+| **API.md** | ⚪ 如適用 | ✅ 必要 | ✅ 必要 | ⚪ 建議 | API 規格 |
+| **DATABASE.md** | ⚪ 如適用 | ✅ 必要 | ✅ 必要 | ⚪ 建議 | 資料庫架構 |
+| **DEPLOYMENT.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ⚪ 建議 | 部署指南 |
+| **MIGRATION.md** | ❌ 不需要 | ✅ 必要 | ✅ 必要 | ❌ 不需要 | 遷移計畫 |
+| **ADR/** | ⚪ 建議 | ✅ 必要 | ✅ 必要 | ⚪ 如適用 | 架構決策 |
+| **CHANGELOG.md** | ✅ 必要 | ✅ 必要 | ✅ 必要 | ✅ 必要 | 版本歷史 |
+| **CONTRIBUTING.md** | ⚪ 建議 | ⚪ 建議 | ⚪ 建議 | ⚪ 如適用 | 貢獻指南 |
+
+**圖例**: ✅ 必要 | ⚪ 建議/如適用 | ❌ 不需要
+
+---
+
+### 專案類型說明
+
+#### 🆕 新建專案
+
+從零開始建立的軟體專案。
+
+**必要文件**:
+- README.md - 專案概述、快速開始
+- ARCHITECTURE.md - 設計架構（開發前規劃）
+- DEPLOYMENT.md - 部署流程
+- CHANGELOG.md - 版本歷史
+
+**建議文件**:
+- API.md - 如對外提供 API
+- DATABASE.md - 如使用資料庫
+- ADR/ - 記錄重要技術決策
+
+---
+
+#### 🔄 重構專案
+
+改善既有系統的程式碼結構、架構或技術棧，但不改變外部行為。
+
+**必要文件**:
+- README.md - 更新技術棧說明
+- ARCHITECTURE.md - 新舊架構對比
+- API.md - API 變更說明（如適用）
+- DATABASE.md - Schema 變更說明（如適用）
+- DEPLOYMENT.md - 新部署流程
+- MIGRATION.md - 重構遷移計畫
+- ADR/ - 記錄重構決策
+- CHANGELOG.md - 詳細變更記錄
+
+**重點**:
+- MIGRATION.md 需包含回滾計畫
+- ADR/ 需記錄「為何重構」及「為何選擇此方案」
+
+---
+
+#### 🚚 遷移專案
+
+將系統從一個環境/平台遷移到另一個（如雲端遷移、版本升級）。
+
+**必要文件**:
+- README.md - 新環境說明
+- ARCHITECTURE.md - 新架構圖
+- API.md - API 相容性說明
+- DATABASE.md - 資料遷移說明
+- DEPLOYMENT.md - 新環境部署
+- MIGRATION.md - 遷移步驟與驗證
+- ADR/ - 遷移決策記錄
+- CHANGELOG.md - 遷移變更記錄
+
+**重點**:
+- MIGRATION.md 是核心文件
+- 需包含資料遷移驗證、回滾計畫、整合方通知
+
+---
+
+#### 🔧 維護專案
+
+既有系統的日常維護、Bug 修復、小幅功能增強。
+
+**必要文件**:
+- README.md - 保持更新
+- CHANGELOG.md - 記錄每次變更
+
+**建議文件**:
+- 依變更範圍更新其他文件
+
+---
+
+## 核心原則
+
+> **文件是程式碼的延伸，應與程式碼同等重視。好的文件能減少溝通成本、加速新人上手、降低維護風險。**
+
+### 文件金字塔
+
+```
+                    ┌─────────────┐
+                    │   README    │  ← 入口點，快速概覽
+                    ├─────────────┤
+                 ┌──┴─────────────┴──┐
+                 │   ARCHITECTURE    │  ← 系統總覽
+                 ├───────────────────┤
+              ┌──┴───────────────────┴──┐
+              │  API / DATABASE / DEPLOY │  ← 技術細節
+              ├─────────────────────────┤
+           ┌──┴─────────────────────────┴──┐
+           │    ADR / MIGRATION / CHANGELOG │  ← 變更歷史
+           └───────────────────────────────┘
+```
+
+---
+
+## 文件分類與規範
+
+### 1. 架構文件
+
+#### ARCHITECTURE.md
+
+**用途**: 描述系統整體架構、模組劃分、技術選型
+
+**必要章節**:
+
+| 章節 | 說明 | 必要性 |
+|---------|-------------|----------|
+| 系統概述 | 目的、範圍、主要功能 | 必要 |
+| 架構圖 | 使用 Mermaid 或 ASCII Art | 必要 |
+| 模組說明 | 職責、依賴關係 | 必要 |
+| 技術棧 | 框架、語言、資料庫版本 | 必要 |
+| 資料流程 | 主要業務流程的資料流向 | 必要 |
+| 部署架構 | 生產環境部署拓撲 | 建議 |
+| 設計決策 | 關鍵決策的理由（或連結至 ADR） | 建議 |
+
+**範本結構**:
+
+```markdown
+# 系統架構
+
+## 1. 系統概述
+[系統目的與範圍]
+
+## 2. 架構圖
+[Mermaid 或 ASCII 圖]
+
+## 3. 模組說明
+### 3.1 表現層
+### 3.2 業務邏輯層
+### 3.3 資料存取層
+
+## 4. 技術棧
+| 類別 | 技術 | 版本 |
+|----------|------------|---------|
+
+## 5. 資料流程
+[主要業務流程圖]
+
+## 6. 部署架構
+[部署拓撲圖]
+```
+
+---
+
+### 2. API 文件
+
+#### API.md
+
+**用途**: 記錄對外 API 介面
+
+**必要章節**:
+
+| 章節 | 說明 | 必要性 |
+|---------|-------------|----------|
+| API 概述 | 版本、Base URL、認證方式 | 必要 |
+| 認證方式 | Token 取得、過期時間 | 必要 |
+| 端點列表 | 所有 API 端點 | 必要 |
+| 端點規格 | 每個端點的請求/回應格式 | 必要 |
+| 錯誤碼參考 | 錯誤碼與說明 | 必要 |
+| 程式碼範例 | 常見語言的範例 | 建議 |
+| 速率限制 | API 呼叫頻率限制 | 如適用 |
+
+**端點規格格式**:
+
+```markdown
+### POST /api/v1/resource
+
+描述此端點的功能。
+
+**請求**
+
+| 欄位 | 類型 | 必要 | 說明 |
+|-------|------|----------|-------------|
+| field1 | string | 是 | 說明 |
+| field2 | integer | 否 | 說明 |
+
+**請求範例**
+```json
+{
+  "field1": "value",
+  "field2": 123
+}
+```
+
+**回應**
+
+| 欄位 | 類型 | 說明 |
+|-------|------|-------------|
+| success | boolean | 是否成功 |
+| data | object | 回應資料 |
+
+**回應範例**
+```json
+{
+  "success": true,
+  "data": {}
+}
+```
+
+**錯誤回應**
+| 代碼 | 說明 |
+|------|-------------|
+| 400 | 請求錯誤 |
+| 401 | 未授權 |
+```
+
+---
+
+### 3. 資料庫文件
+
+#### DATABASE.md
+
+**用途**: 記錄資料庫結構、關聯、索引策略
+
+**必要章節**:
+
+| 章節 | 說明 | 必要性 |
+|---------|-------------|----------|
+| 資料庫概述 | 類型、版本、連線資訊 | 必要 |
+| ER 圖 | 實體關聯圖 | 必要 |
+| 資料表列表 | 所有資料表及用途 | 必要 |
+| 資料表規格 | 每個資料表的欄位定義 | 必要 |
+| 索引說明 | 索引策略與效能考量 | 必要 |
+| 遷移腳本 | 腳本位置與執行順序 | 必要 |
+| 備份策略 | 備份頻率、保留期限 | 建議 |
+
+**資料表規格格式**:
+
+```markdown
+### 資料表名稱
+
+資料表用途說明。
+
+**欄位定義**
+
+| 欄位 | 資料類型 | 可空 | 預設值 | 說明 |
+|--------|-----------|----------|---------|-------------|
+| id | bigint | 否 | IDENTITY | 主鍵 |
+| name | varchar(100) | 否 | - | 名稱欄位 |
+| status | tinyint | 否 | 0 | 狀態旗標 |
+
+**索引**
+
+| 索引名稱 | 欄位 | 類型 | 說明 |
+|------------|---------|------|-------------|
+| PK_TableName | id | CLUSTERED | 主鍵 |
+| IX_Status | status, created_at | NONCLUSTERED | 查詢最佳化 |
+
+**關聯**
+
+| 關聯資料表 | 連結欄位 | 關係 |
+|---------------|--------------|--------------|
+| OtherTable | id = other_id | 1:N |
+```
+
+---
+
+### 4. 部署文件
+
+#### DEPLOYMENT.md
+
+**用途**: 記錄部署步驟、環境配置、故障排除
+
+**必要章節**:
+
+| 章節 | 說明 | 必要性 |
+|---------|-------------|----------|
+| 環境需求 | 硬體、軟體、網路需求 | 必要 |
+| 安裝步驟 | 詳細安裝流程 | 必要 |
+| 配置說明 | 配置檔參數說明 | 必要 |
+| 驗證方式 | 如何確認部署成功 | 必要 |
+| 故障排除 | 常見問題與解法 | 必要 |
+| 監控設定 | 健康檢查、日誌位置 | 建議 |
+| 擴展指南 | 如何水平/垂直擴展 | 如適用 |
+
+**配置檔說明格式**:
+
+```markdown
+### config.yaml 設定
+
+| 參數 | 預設值 | 說明 | 範例 |
+|-----------|---------|-------------|---------|
+| db.host | localhost | 資料庫主機 | `192.168.1.100` |
+| db.port | 5432 | 資料庫連接埠 | - |
+| app.timeout | 300 | 請求逾時（秒） | - |
+```
+
+---
+
+### 5. 遷移文件
+
+#### MIGRATION.md
+
+**用途**: 記錄遷移計畫、向後相容策略、回滾程序
+
+**必要章節**:
+
+| 章節 | 說明 | 必要性 |
+|---------|-------------|----------|
+| 遷移概述 | 目標、範圍、時程 | 必要 |
+| 前置準備 | 遷移前需完成的準備 | 必要 |
+| 遷移步驟 | 詳細遷移流程 | 必要 |
+| 驗證清單 | 遷移後驗證項目 | 必要 |
+| 回滾計畫 | 失敗時的回滾步驟 | 必要 |
+| 向後相容 | API/資料庫相容性說明 | 必要 |
+| 整合方通知 | 需通知的外部系統 | 如適用 |
+
+---
+
+### 6. 架構決策記錄 (ADR)
+
+#### docs/ADR/NNN-title.md
+
+**用途**: 記錄重要的架構決策及其理由
+
+**檔案命名**: `NNN-kebab-case-title.md`（例如：`001-use-postgresql.md`）
+
+**必要章節**:
+
+| 章節 | 說明 | 必要性 |
+|---------|-------------|----------|
+| 標題 | 決策名稱 | 必要 |
+| 狀態 | proposed/accepted/deprecated/superseded | 必要 |
+| 背景 | 為何需要此決策 | 必要 |
+| 決策 | 具體決策內容 | 必要 |
+| 後果 | 決策的影響（正面/負面） | 必要 |
+| 替代方案 | 考慮過的其他選項 | 建議 |
+
+**範本**:
+
+```markdown
+# ADR-001: [決策標題]
+
+## 狀態
+已接受
+
+## 背景
+[為何需要此決策...]
+
+## 決策
+[具體決策...]
+
+## 後果
+
+### 正面影響
+- 好處 1
+- 好處 2
+
+### 負面影響
+- 缺點 1
+- 缺點 2
+
+## 替代方案
+1. 方案 A - 因...而拒絕
+2. 方案 B - 因...而拒絕
+```
+
+---
+
+## 品質標準
+
+### 格式要求
+
+| 項目 | 標準 |
+|------|----------|
+| 語言 | 繁體中文 |
+| 編碼 | UTF-8 |
+| 行長度 | 建議 ≤ 120 字元 |
+| 圖表 | 優先使用 Mermaid，次之 ASCII Art |
+| 連結 | 內部連結使用相對路徑 |
+
+### 維護要求
+
+| 項目 | 標準 |
+|------|----------|
+| 同步更新 | 程式碼變更時同步更新文件 |
+| 版本標記 | 文件頂部標記版本與更新日期 |
+| 審查納入 | 程式碼審查需包含文件變更 |
+| 定期檢視 | 每季檢視文件是否過時 |
+
+### 審查清單
+
+提交文件前：
+
+- [ ] 必要章節完整
+- [ ] 無過時或錯誤資訊
+- [ ] 所有連結有效
+- [ ] 範例可執行/正確
+- [ ] 格式符合標準
+
+---
+
+## 文件位置規範
+
+```
+project-root/
+├── README.md                    # 專案入口文件
+├── CONTRIBUTING.md              # 貢獻指南
+├── CHANGELOG.md                 # 變更日誌
+├── .standards/ or .claude/      # 開發標準
+│   ├── documentation-writing-standards.md
+│   └── ...
+└── docs/                        # 文件目錄
+    ├── INDEX.md                 # 文件索引
+    ├── ARCHITECTURE.md          # 架構文件
+    ├── API.md                   # API 文件
+    ├── DATABASE.md              # 資料庫文件
+    ├── DEPLOYMENT.md            # 部署文件
+    ├── MIGRATION.md             # 遷移文件
+    ├── ADR/                     # 架構決策記錄
+    │   ├── 001-xxx.md
+    │   └── ...
+    └── DB/                      # 資料庫腳本
+```
+
+---
+
+## 工具建議
+
+| 用途 | 工具 |
+|---------|-------|
+| Markdown 編輯 | VS Code + Markdown Preview Enhanced |
+| 圖表繪製 | Mermaid / draw.io / PlantUML |
+| API 文件 | OpenAPI (Swagger) / Redoc |
+| ER 圖 | dbdiagram.io / DBeaver |
+
+---
+
+## 相關標準
+
+- [Documentation Structure Standard](documentation-structure.md) - 文件結構標準
+- [Changelog Standards](changelog-standards.md) - 變更日誌標準
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更內容 |
+|---------|------|---------|
+| 1.0.1 | 2025-12-24 | 新增：相關標準章節 |
+| 1.0.0 | 2025-12-10 | 初版文件撰寫標準 |
+
+---
+
+## 授權
+
+本標準以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。