軟件工程個人作業 03：項目文檔規範與版本控制實踐

軟件工程個人作業 03：項目文檔規範與版本控制實踐

作業目標

掌握軟件工程中核心文檔的編寫規範，熟練使用 Git 進行版本控制與團隊協作，建立規範的項目交付流程。

核心內容

1. 需求規格說明書（SRS）編寫

• 採用 IEEE 830 標準結構：引言、總體描述、具體需求、附錄。
• 功能需求採用「用例圖 + 用例描述」雙重表達，非功能需求量化指標（性能、安全、可用性）。
• 需求變更管理：建立變更請求單（CR），經 CCB 評審後納入基線。

2. 設計文檔規範

• 概要設計：系統架構圖（分層/微服務）、模塊劃分、接口定義（API 契約）、數據庫 ER 圖、部署拓撲。
• 詳細設計：類圖、序列圖、狀態機圖、關鍵演算法偽代碼、異常處理策略。
• 文檔即代碼：使用 PlantUML / Mermaid 文本化繪圖，納入版本庫與代碼同步更新。

3. Git 工作流實踐

# 主分支策略：Git Flow 簡化版
# main / master  - 生產就緒代碼，僅接受 release/hotfix 合併
# develop        - 集成分支，功能分支合併目標
# feature/*      - 功能開發分支，從 develop 拉取，完成後 PR 合回 develop
# release/*      - 發布準備分支，僅修復 Bug、調整配置
# hotfix/*       - 線上緊急修復，從 main 拉取，合回 main 並同步 develop

• 提交信息規範：<type>(<scope>): <subject>（如 feat(auth): add OAuth2 login）。
• Code Review 強制：所有合併需通過至少 1 人審批，CI 自動化檢測（測試覆蓋率、靜態分析）。

4. 持續集成 / 持續部署（CI/CD）

• Pipeline 階段：代碼檢出 → 依賴安裝 → 單元測試 → 代碼質量掃描 → 構建鏡像 → 部署測試環境 → 自動化驗收測試 → 手動審批 → 部署生產。
• 環境隔離：開發、測試、預發、生產環境配置外部化（ConfigMap / Consul / Nacos）。

交付物清單

自我評估與反思

1. 文檔滯後於代碼：下階段引入「文檔即代碼」強制機制，PR 模板加入文檔更新檢查項。
2. 分支管理混亂：推行 Trunk-Based Development 簡化流程，減少長生命周期分支。
3. 測試覆蓋率不足：設置門檻 80%+，集成測試覆蓋核心業務鏈路。

參考資源

• IEEE 830-1998 軟件需求規格說明書推薦做法
• Pro Git v2 官方中文版
• Martin Fowler 持續集成經典論文