背景與問題

• 現實困境: 直接讓 AI 產出整塊業務代碼，常常與現有架構風格、分層邊界、依賴策略不一致，后續改造成本高；AI 對現實業務語境、領域規則難以精準把握；在既定模板成熟的場景下，代碼生成器往往更快、更整齊。
• 目標: 保持團隊既有架構與工程紀律，發揮 AI 在探索、補全、評審與加速學習上的優勢，降低全周期交付成本。

總體策略：生成器為主干，AI 為增幅器

• 生成器（Generator）作為主干：強約束地輸出骨架與重復性代碼，以模塊/分層/命名/依賴為“軌道”。
• AI 作為增幅器：在“軌道”內進行探索、補全、評審、重構建議與知識蒸餾，避免直接替代主干生成。二者配合，形成“結構確定 + 局部智能”的穩態生產模式。

角色分工（清晰邊界）

• 生成器職責
  • 從 DSL/模型/配置生成項目骨架、實體、DAO、API 契約、DTO、基礎 Service/Controller、前端表單/列表。
  • 嚴格收斂目錄與層次：如 JPA 實體統一落在資源層模塊，按包約定與模板產出；控制器、開放接口放在 API/Gateway 層；公共庫與工具類落在基礎模塊。
  • 以模板升級推動“規范沉淀”，一處改進，全局受益。
• AI 職責
  • 需求梳理、用例設計、邊界場景補全與反例思考。
  • 局部函數實現（小而清晰的單點邏輯）、性能調優建議、異常與重試策略建議。
  • 單元/集成/契約測試補全，變更影響面分析與回歸清單建議。
  • 代碼評審（可讀性、復雜度、耦合度、異常路徑）、重構方案與風險提示。
  • 文檔沉淀（ADR、模塊說明、限界上下文說明、時序/狀態機/ER 草圖）。
• 人類職責
  • 領域建模與 DSL 維護、架構準入與裁剪、業務裁決與優先級、最后的合并把關。

標準工作流（從需求到上線）

1. 以 DSL/配置（如 YAML）描述領域概念、對象關系、接口契約與約束。
2. 通過代碼生成器生成骨架與重復代碼（遵循模塊與分層約定）。
3. 針對“不可模板化”的邊緣邏輯，由 AI 在約束內補全實現（僅限局部函數/方法）。
4. 讓 AI 生成/補全單測與契約測試，并給出覆蓋關鍵路徑的回歸清單。
5. 運行構建與測試（本地/CI），失敗用 AI 協助定位與修復，但仍遵守“只改動最小單元”的原則。
6. AI 生成變更摘要與自檢清單（架構一致性、依賴邊界、復雜度、日志、安全、i18n）。
7. 人工審核后合并；將本次經驗沉淀為模板升級與 Prompt 庫更新。

守護欄（約束協議）

• 分層邊界：禁止跨層調用與反向依賴；倉儲只暴露接口、應用層不直連 ORM；控制器不寫領域規則。
• 目錄約束：實體/DTO/VO/Controller/Service/Repo/Config 各就其位，禁止“即興”新建架構層級。
• 依賴策略：默認不引入新依賴；如確需新增，必須聲明理由、對比與回滾方案。
• 復雜度閾值：函數圈復雜度、嵌套層級與參數個數設上限；超限需拆分并寫測試。
• 風格一致性：日志、異常、國際化、命名、注釋風格對齊基線；變更不重排無關格式。

Prompt 模板庫（可直接復制使用）

A. 架構對齊開發（在現有模塊內補全）

你現在在現有代碼庫內進行“最小化改動”的代碼補全，請嚴格遵守：
- 只在我點名的文件與函數內編輯；禁止新建層/模塊；禁止引入新依賴。
- 分層與目錄約束：- JPA 實體只在資源層的實體模塊內；- Controller 僅放在 API 層；- Service 只編排應用邏輯，不寫 SQL；- Repository 只定義數據訪問接口。
- 輸出內容包含：1) 你將修改的文件清單2) 具體改動（只給出必要片段）3) 架構一致性自檢（逐條對照約束）4) 回歸測試建議（列關鍵路徑與斷言）現在任務：在 {文件路徑}:{函數名} 中實現 {功能要點}，要求 O(變更最小)。
給出實現方案與測試要點。

B. 領域建模與 DSL 同步

基于以下業務描述，產出領域對象、關系、約束與狀態流轉；并給出可合并到生成器的 DSL/YAML 片段：業務描述：{貼上需求/規則/票據}輸出：
- 實體清單（名詞 + 關鍵字段 + 關系）
- 約束（唯一性、枚舉、狀態機、生命周期）
- API 契約草案（接口名、入參、出參、錯誤碼）
- 生成器 DSL/YAML（僅新增或變更的條目）
- 風險與歧義清單（等待澄清的問題）

C. 邊緣邏輯最小實現

請僅在 {文件路徑}:{函數名} 內實現以下邏輯：{邏輯描述}。
約束：
- 不改其他函數，不新增依賴，不改變公共接口簽名。
- 控制復雜度：最多兩層分支，必要時早返回；為空/異常/邊界優先處理。
- 提供 3 個單元測試用例，覆蓋正常、邊界、異常路徑。
- 產出“自檢清單”（日志、異常、并發、性能要點）。

D. 代碼評審與重構建議

下面是本次變更的 diff（或關鍵文件片段）。請按以下維度給出審查結論與可執行的最小重構建議：
- 架構與分層一致性
- 可讀性與命名
- 復雜度與邊界處理
- 性能與資源釋放
- 日志、異常與可觀測性
- 安全與多租戶/權限輸出：
1) 問題列表（按嚴重級別排序）
2) 可直接粘貼的最小重構代碼片段
3) 回歸風險與測試建議

E. 故障定位與修復

給定以下錯誤堆棧/日志/SQL，請在不新增依賴的前提下，給出最小修復方案：
- 根因分析（鏈路 + 證據）
- 修復思路（最小改動）
- 具體修改片段（限定在 {文件路徑}）
- 回歸測試與監控點

F. 文檔沉淀（ADR/模塊說明）

請根據這次需求與變更，產出一份 ADR：
- 背景與動機
- 備選方案對比（取舍理由）
- 決策與影響面
- 遷移/回滾策略
- 后續工作與度量指標

與代碼生成器的協同

• 模板為王：將通用實踐推進到模板（如 Controller/Service/Repo/DTO/前端 CRUD 模板）。模板升級即團隊升級。
• DSL 收斂：統一在一處維護領域詞匯表、對象屬性與 API 契約；AI 輸出的 DSL 片段經人審后并入生成器配置。
• Schema-first：優先以 OpenAPI/AsyncAPI/Avro 等契約驅動，生成器產出骨架，AI 生成契約測試與示例。

減少偏差的具體做法

• 小步提交：AI 只處理一個函數或一個文件的局部，配套 2-3 個用例。
• 顯式拒絕：當請求超出約束（跨層、添依賴、大改簽名），AI 應先拒絕并給出替代路徑。
• 回歸快跑：保存一組“金樣本”用例，AI 修改后先本地跑，CI 再跑；覆蓋率門檻可由 AI 給出補測建議。
• 固定示例：給 AI 提供項目內“代表性樣例文件”，作為風格與邊界的錨點。

現實業務知識的注入

• 語義注入：把內部術語表、狀態機、時序圖、規則表放入上下文；要求 AI 在輸出前列出“未知項”和“假設”。
• 上下文包：為 AI 預打包“架構約束 + 目錄約定 + 命名規范 + DSL 摘要”，作為每次對話的前置輸入。

在你項目中的落地清單（可執行）

• 目錄與分層：固化“實體/DAO/Service/Controller/DTO/VO/前端頁面”的落位規則；以 pre-commit 檢查違規路徑。
• 模板沉淀：把常見的查詢、分頁、審計字段、軟刪除、異常處理、日志切面、統一響應，寫進生成器模板。
• Prompt 庫：將上文模板存入 documents/ai/prompt/，按業務域分目錄；每次評審后更新。
• PR 模板：新增 PR 模板，強制“架構一致性自檢 + 回歸清單 + 監控點”。
• CI 守護：風格檢查 + 單測 + 契約測試 + 違規路徑掃描（例如禁止實體出現在錯誤模塊）。

結論

• 最優解不是“全靠 AI”或“完全不用 AI”，而是“生成器守住工程與架構的秩序，AI 放大探索、補全與評審的效率”。
• 以“強約束 + 小步快跑 + 模板沉淀 + 語義注入”的方法，能把 AI 變成可控、可度量的生產力，而非一次性的“靈感”。

附：最小可行用法（15 分鐘上手）

1. 用生成器產出實體/DAO/Service/Controller 骨架。
2. 讓 AI 只在某個 Service 的“單個函數”里補齊特定業務邏輯。
3. 讓 AI 寫 3 個單測用例，覆蓋正常/邊界/異常；本地跑通。
4. 讓 AI 給出自檢清單與回歸建議；人工核查后合并。

面向 nb-mall 的項目結構對齊（定制落地指南）

模塊職責與產出路徑映射

• resources/business-resource（領域資源層）
  • 放置 JPA 實體、Repository 接口、領域枚舉與基礎轉換器。
  • 注意：依據你的偏好，JPA 實體應統一放在該模塊下，避免分散在其他模塊[[memory:3731451]]。
• apis/business-api（開放接口層）
  • 放置對外 REST Controller、DTO/VO、入參校驗對象與裝配器（Assembler/Converter）。
  • 不直接訪問 ORM，依賴應用服務抽象或 Facade。
• gates/admin（網關/聚合層）
  • 統一鑒權、路由轉發、跨域與限流等橫切能力；避免業務邏輯侵入。
• code-generator（模板與 DSL）
  • src/main/resources/config/*.yml 維護領域 DSL；template/jpa/*.ftl、template/vue/*.ftl 產出后端與前端骨架。
• front/（多端前端）
  • admin/：后臺運營端（Vue）。
  • pos/：門店/收銀端（Vue）。
  • front/：C 端站點（Nuxt）。
  • uniapp/：移動端（uni-app）。

建議的代碼生成落位規則

• 實體與 Repository → resources/business-resource
• Controller/DTO/VO/Converter → apis/business-api
• 前端 CRUD 頁面與表單 → front/admin（如為運營端）
• 若為 POS/移動端需求 → 同步生成到 front/pos 或 front/uniapp

標準開發流（結合現有結構）

1. 在 code-generator/resources/config/*.yml 中完善 DSL（實體、字段、約束、接口契約、前端元數據）。
2. 運行生成器產出骨架：
   • 后端：實體/Repository → business-resource；Controller/DTO → business-api。
   • 前端：列表/表單/路由 → front/admin（或目標端）。
3. 對“不可模板化”的業務細節：僅在指定 Service 或函數中做最小改動；禁止跨層訪問與新增依賴。
4. 讓 AI 生成/補全對應單元測試與契約測試（針對 business-api 的接口）。
5. 本地與 CI 運行構建、測試；失敗時用 AI 輔助定位，但只做最小修改。
6. 評審時按“守護欄”逐條自檢；將共性的改進沉淀回 code-generator 模板與 DSL。

與生成器的聯動建議（nb-mall 實踐）

• 在模板固化以下約定：
  • 審計字段（創建/修改人與時間、租戶/組織、軟刪除）。
  • 統一返回體、異常編碼、分頁與排序約束、統一日志與攔截器。
  • DTO/VO 命名規則與轉換器（如 MapStruct 或手寫裝配器）。
• 在 DSL 文件加入前端元數據：
  • 字段顯示名、校驗規則、枚舉映射、字典/級聯選擇、搜索條件、列寬與排序。
  • 由此驅動 front/admin 自動生成表單/列表/路由與權限點。

針對各端的差異化指引

• front/admin：偏 CRUD + 運營工作臺。優先使用生成器產出頁面骨架與表單校驗。
• front/pos：交互流程固定、離線/并發要求更高。生成器負責骨架，AI 輔助補全緩存/并發邊界與設備適配細節。
• front/uniapp：注意端能力差異與網絡狀態波動。生成器產出頁面與接口封裝，AI 補充狀態管理與降級策略。
• front/front (Nuxt)：靜態化與 SEO 需求更強。生成器產出基礎頁面/路由，AI 補全數據獲取策略與性能細節（預取/緩存）。

nb-mall 定制 Prompt 模板（可直接復制）

【后端-對齊補全】

只在以下邊界內補全代碼：
- 實體/Repository：resources/business-resource
- Controller/DTO/VO/Converter：apis/business-api
- 禁止新增依賴與跨層訪問；不改變公共接口簽名。任務：在 {文件路徑}:{函數名} 內實現 {功能要點}，給出：
1) 最小實現代碼片段
2) 架構一致性自檢（分層/依賴/異常/日志）
3) 3 個用例（正常/邊界/異常），標注斷言點

【前端-頁面骨架增強】

基于生成器已產出的頁面骨架（位于 front/admin 或目標端），
請在不引入新依賴前提下補全：
- 表單校驗、字典/枚舉映射、搜索條件組合、分頁與排序
- 交互細節：提交/并發/錯誤提示/重試
- E2E 場景清單與關鍵斷言

【DSL 協同】

根據以下業務描述，補充 code-generator/resources/config 的 DSL 片段：
- 實體與字段（含約束/索引/默認值/枚舉）
- API 契約（入參/出參/錯誤碼）
- 前端元數據（表單項、校驗、字典、搜索項、列配置）
并指出歧義點與待澄清問題。

CI/CD 與守護腳本建議

• 在 PR 檢查中加入“路徑守護”：禁止實體/Repository 出現在非 business-resource 模塊，禁止 Controller 出現在非 business-api。
• 啟用契約測試（OpenAPI 校驗）與接口變更告警。
• 前端構建加入路由/權限點掃描與 i18n 缺失校驗。

15 分鐘落地（nb-mall 版）

1. 在 code-generator/resources/config/*.yml 新增/修改領域 DSL。
2. 生成代碼：后端落位到 business-resource 與 business-api，前端落位到 front/admin。
3. 僅在目標函數中做最小實現；用 AI 生成 3 個用例并本地跑通。
4. 提交 PR，走“路徑守護 + 單測 + 契約測試”檢查；評審后合并，并把共性補充回模板與 DSL。