383201cacd
## v0.9.20260325_144654 ### Features - API Key Authentication System - Job Worker System - V2 Backup Versioning ### Bug Fixes - get_processor_results_by_job column mapping Co-authored-by: OpenCode
8.7 KiB
8.7 KiB
文件修改管理規範 v1.0
| 項目 | 內容 |
|---|---|
| 建立者 | Warren |
| 建立時間 | 2026-03-22 |
| 文件版本 | V1.0 |
1. 概述
本文檔定義 Momentry 專案的文件修改流程，確保不同工具/模型對文件的一致性理解，防止誤修改並保留完整的修改紀錄。
1.1 適用範圍
- 所有
.md文件（技術文檔、安裝指南、API 文件等） - 所有
.rs文件（Rust 源代碼） - 所有
.sh文件（Shell 腳本） - 所有
.yaml/.yml文件（配置文件） - 所有
.json文件（配置及數據文件）
1.2 核心原則
- 先讀後改：修改前必須完整閱讀相關文件
- 預檢清單：修改前執行預檢查步驟
- 變更對照：修改後必須比對差異
- 驗證確認：變更後執行驗證測試
- 完整紀錄：所有修改必須記錄於版本歷史
2. 修改前預檢清單
2.1 文件閱讀要求
修改文件前，必須完成以下閱讀：
| 步驟 | 項目 | 說明 |
|---|---|---|
| 1 | 閱讀完整文件 | 不可僅閱讀部分章節 |
| 2 | 理解文件用途 | 確認文件的目標讀者 |
| 3 | 確認現有術語 | 使用一致的術語和命名 |
| 4 | 查閱相關文件 | 確認相關聯的文件 |
2.2 預檢問題清單
在修改前回答以下問題：
□ 1. 此修改是否影響其他文件？
□ 2. 此修改是否與現有規範衝突？
□ 3. 此修改是否需要更新版本歷史？
□ 4. 此修改是否需要新增測試？
□ 5. 此修改是否需要通知相關人員？
□ 6. 此修改是否有破壞性變更（Breaking Change）？
2.3 預檢命令
修改前執行以下命令確認現有狀態：
# 1. 確認 git 狀態
git status
# 2. 檢查相關文件的最新版本
git log -3 --oneline <file_path>
# 3. 查看現有版本歷史
cat docs/<file>.md | grep -A 20 "版本歷史"
3. 文件修改流程
3.1 標準修改流程
┌─────────────────────────────────────────────────────────────┐
│ Step 1: 閱讀 │
│ ├─ 完整閱讀目標文件 │
│ └─ 閱讀相關聯文件 │
├─────────────────────────────────────────────────────────────┤
│ Step 2: 預檢 │
│ ├─ 回答預檢問題清單 │
│ └─ 執行預檢命令 │
├─────────────────────────────────────────────────────────────┤
│ Step 3: 規劃 │
│ ├─ 說明修改內容 │
│ └─ 列出變更差異 │
├─────────────────────────────────────────────────────────────┤
│ Step 4: 修改 │
│ ├─ 執行修改 │
│ └─ 更新版本歷史 │
├─────────────────────────────────────────────────────────────┤
│ Step 5: 驗證 │
│ ├─ 執行 lint/format 檢查 │
│ └─ 執行相關測試 │
├─────────────────────────────────────────────────────────────┤
│ Step 6: 提交 │
│ └─ 撰寫清晰的 commit message │
└─────────────────────────────────────────────────────────────┘
3.2 預修改彙報格式
在執行修改前，必須先彙報以下內容：
## 檔案
`<file_path>`
## 修改原因
<說明修改的目的>
## 變更內容
```diff
- <刪除的內容>
+ <新增的內容>
版本歷史更新
| 版本 | 日期 | 內容 | 操作人 | 工具/模型 |
|---|---|---|---|---|
| Vx.x | YYYY-MM-DD | <修改說明> | <操作者> | <使用的工具> |
### 3.3 版本歷史格式
每個文件頂部必須包含版本歷史表：
```markdown
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-15 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
| V1.1 | 2026-03-22 | 更新內容 | Warren | OpenCode / big-pickle |
4. 變更對照
4.1 diff 對照
修改後必須提供 diff 對照：
git diff <file_path>
4.2 變更類型分類
| 類型 | 標記 | 說明 |
|---|---|---|
| 新增 | + |
新增內容 |
| 刪除 | - |
刪除內容 |
| 修改 | ~ |
修改內容 |
| 移動 | ↕ |
移動位置 |
| 格式 | @ |
格式變更 |
4.3 變更確認清單
□ 1. diff 輸出已確認
□ 2. 變更符合預期
□ 3. 無意外變更
□ 4. 版本歷史已更新
□ 5. 其他關聯文件已檢查
5. 驗證流程
5.1 自動化驗證
修改後執行以下自動化檢查：
# Rust 文件
cargo fmt -- --check
cargo clippy --lib
cargo test --lib
# Python 文件
ruff check <files>
ruff format --check <files>
# Markdown 文件
markdownlint <files>
# Shell 文件
shellcheck -S error <files>
5.2 手動驗證清單
□ 1. 文件語法正確
□ 2. 連結有效
□ 3. 格式一致
□ 4. 術語一致
□ 5. 版本歷史完整
□ 6. 變更記錄清晰
6. 提交規範
6.1 Commit Message 格式
<type>: <subject>
<body>
<footer>
6.2 Type 類型
| Type | 說明 |
|---|---|
feat |
新功能 |
fix |
錯誤修復 |
refactor |
重構 |
docs |
文檔更新 |
style |
格式變更 |
test |
測試相關 |
chore |
維護工作 |
6.3 Commit Message 範例
# 文檔更新
git commit -m "docs: update INSTALL_MONGODB.md with LaunchAgent instructions
- Add LaunchDaemon plist installation steps
- Update management commands section
- Add version history entry
Closes: #xxx"
# 配置文件更新
git commit -m "fix: remove duplicate mongodb entry in monitor_config.yaml
The backup section had two mongodb entries which caused confusion.
Removed the duplicate config entry at line 408-414."
7. AI 工具修改額外規範
7.1 修改前確認
AI 工具修改文件前，必須：
- 完整閱讀：閱讀完整文件（不可只讀取部分）
- 理解語境：理解文件的用途和目標讀者
- 查閱相關：查閱相關聯文件確保一致性
- 提出計畫：修改前先提出變更計畫供確認
7.2 修改後確認
AI 工具修改文件後，必須：
- 展示差異：顯示修改的 diff 內容
- 說明變更：解釋每項變更的目的
- 執行驗證：執行相關的 lint/test 命令
- 更新歷史：更新版本歷史表
7.3 禁止事項
AI 工具禁止以下行為：
□ 未閱讀完整文件即進行修改
□ 未經確認直接執行大規模修改
□ 未提供 diff 即提交變更
□ 未更新版本歷史
□ 未執行驗證即聲稱完成
□ 擅自刪除其他工具/模型添加的內容
□ 無視現有文件規範
8. 審查清單
8.1 提交前審查
□ 1. 修改內容已完整閱讀
□ 2. 預檢問題清單已回答
□ 3. diff 對照已確認
□ 4. 版本歷史已更新
□ 5. 自動化驗證已通過
□ 6. 手動驗證清單已完成
□ 7. Commit message 符合規範
□ 8. 無敏感資訊泄露
8.2 Code Review 關注點
- 修改是否影響現有功能？
- 修改是否與專案規範一致？
- 是否有遺漏的關聯修改？
- 測試是否足夠？
- 文檔是否同步更新？
9. 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|---|---|---|---|---|
| V1.0 | 2026-03-22 | 創建文件 | Warren | OpenCode / big-pickle |