模組設計文件生成規範

啟動流程

資訊收集

1. 已提供前後端程式碼路徑 + 前端地址 → 直接開始
2. 只提供了部分資訊：
   • 缺前端程式碼路徑 → 詢問前端專案根目錄
   • 缺後端程式碼路徑 → 詢問後端專案根目錄
   • 缺前端地址 → 讀完程式碼後詢問
3. 都沒提供 → 先詢問前後端程式碼路徑，讀完程式碼後再詢問前端地址

登入處理

訪問前端頁面時若需要登入：詢問租戶（如有）、使用者名稱、密碼，獲取後登入再繼續。

第一步：深度閱讀前端程式碼

目標目錄：<前端專案>/src/views/<模組路徑>/

逐一閱讀每個模組的：

• 列表頁 index.vue：提取搜尋欄位、表格列、操作按鈕（新增/編輯/刪除/匯出/提交稽核等）、分頁邏輯
• 表單頁 XxxForm.vue：提取所有表單欄位（欄位名、型別、是否必填、校驗規則）、子表結構、多標籤頁
• 詳情頁 detail.vue：提取展示欄位、子表展示
• API 檔案 src/api/<模組>.ts：提取所有介面路徑、請求引數、響應結構

重點理解：

• 欄位的中文標籤（label）→ 用於表結構"說明"列
• 必填校驗（required）→ 用於表結構"是否必填"列
• 下拉選項值（options）→ 用於表結構"備註"列（列舉值說明）
• 子表元件 → 對應資料庫子表

第二步：深度閱讀後端程式碼

目標目錄：<後端專案>/<模組目錄>/

逐一閱讀：

• DO/Entity XxxDO.java：提取所有欄位（欄位名、型別、註解、註釋）→ 核心表結構來源
• 建表 SQL（如有）：直接提取欄位定義、約束、索引、註釋
• Controller XxxController.java：提取所有介面路徑、HTTP方法、引數
• Service XxxService.java / XxxServiceImpl.java：理解業務邏輯、狀態流轉、關聯操作
• BPM Listener XxxBpmStatusListener.java（如有）：理解審批流程、狀態變更邏輯
• VO/DTO（如有）：補充前端展示欄位與後端欄位的對映關係

重點理解：

• 主表與子表的關聯關係（外部索引鍵欄位）
• 狀態欄位的列舉值含義
• 審批流程的觸發條件和狀態變更
• 必填約束（NOT NULL）

第三步：訪問前端頁面截圖

使用 agent-browser 逐一訪問每個功能頁面，截圖儲存到 screenshots/ 目錄：

每個模組至少截：列表頁 + 表單頁 + 詳情頁。

第四步：整理設計素材

在輸出目錄建立 notes/design_notes.md，按模組整理：

• 模組功能描述（一段話）
• 業務流程步驟（文字列表，參考 Service/Listener 邏輯）
• 頁面欄位清單（來自前端程式碼）
• 表結構（來自 DO + SQL，7列格式）
• 實現類路徑清單

第五步：生成 Word 設計文件

使用 Python python-docx 生成，參考指令碼：scripts/build_design_doc.py 報告格式詳見：references/doc-format.md

文件結構：

封面（系統名 + 模組名 + 生成時間，居中）
目錄（Word TOC 域，1-3級，右鍵更新域）
1. 模組簡介        ← Heading 1
   模組範圍、前端路由、後端介面字首、程式碼位置
2. 功能模組詳細設計  ← Heading 1
   2.x 子模組名     ← Heading 2
       2.x.1 功能描述與業務流程  ← Heading 3
           功能說明段落
           流程步驟列表（• 步驟1 → 步驟2 → ...）
       2.x.2 頁面截圖           ← Heading 3
           列表頁截圖 + 圖注
           表單頁截圖 + 圖注（多標籤頁逐一截圖）
           詳情頁截圖 + 圖注
       2.x.3 資料表結構         ← Heading 3
           主表（7列表格）
           子表1（7列表格）
           子表2（7列表格）...
       2.x.4 實現類             ← Heading 3
           前端檔案路徑列表
           後端檔案路徑列表
3. 總結說明        ← Heading 1

表結構7列格式（必須嚴格遵守）： | 欄位名 | 說明 | 型別 | 是否必填 | 預設值 | 約束 | 備註 |

• 欄位名：資料庫欄位名（snake_case）
• 說明：中文含義（來自前端label或後端註釋）
• 型別：資料庫型別（varchar(N)/bigint/tinyint/text/datetime/date/decimal等）
• 是否必填：是/否
• 預設值：NULL / 具體值 / AUTO_INCREMENT
• 約束：PRIMARY KEY / UNIQUE / INDEX / 空
• 備註：列舉值說明（如 0草稿1稽核中2已通過）、關聯說明、特殊說明

執行原則

1. 先讀程式碼，再看頁面 — 程式碼是權威，頁面是驗證
2. 表結構必須完整 — 主表+所有子表，一個不漏
3. 流程描述要具體 — 不能只寫"支援新增編輯刪除"，要寫清楚每一步的觸發條件和結果
4. 截圖要對應 — 每張截圖放在對應模組的"頁面截圖"小節下，圖注清晰
5. 欄位說明要準確 — 列舉值、關聯關係、特殊約束都要在備註列說明清楚
6. 輸出目錄結構：

   workspace/outputs/<模組>-design-doc-<日期>/
   ├── notes/design_notes.md
   ├── screenshots/
   │   ├── 00-login-page.png
   │   └── ...
   └── <系統名>-<模組名>-設計文件-<日期>.docx

   7w4.net小蔥技能站收錄全網優質技能，值得收藏。

這是一個功能定位明確的文件生成工具，能夠根據程式碼和頁面自動生成規範的 Word 設計文件。整體質量良好，流程設計完整，格式規範詳細，適合需要快速輸出技術文件的場景。優點是觸發時機清晰、工作步驟明確、輸出格式統一。主要不足是使用門檻略高，需要一定的程式碼閱讀能力，且缺少使用案例參考，新手可能需要一定學習成本才能上手使用。