feat: Initial v0.9 release with API Key authentication
## 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
This commit is contained in:
accusys
@@ -0,0 +1,323 @@
|
||||
# 文件修改管理規範 v1.0
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-22 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 概述
|
||||
|
||||
本文檔定義 Momentry 專案的文件修改流程，確保不同工具/模型對文件的一致性理解，防止誤修改並保留完整的修改紀錄。
|
||||
|
||||
### 1.1 適用範圍
|
||||
|
||||
- 所有 `.md` 文件（技術文檔、安裝指南、API 文件等）
|
||||
- 所有 `.rs` 文件（Rust 源代碼）
|
||||
- 所有 `.sh` 文件（Shell 腳本）
|
||||
- 所有 `.yaml` / `.yml` 文件（配置文件）
|
||||
- 所有 `.json` 文件（配置及數據文件）
|
||||
|
||||
### 1.2 核心原則
|
||||
|
||||
1. **先讀後改**：修改前必須完整閱讀相關文件
|
||||
2. **預檢清單**：修改前執行預檢查步驟
|
||||
3. **變更對照**：修改後必須比對差異
|
||||
4. **驗證確認**：變更後執行驗證測試
|
||||
5. **完整紀錄**：所有修改必須記錄於版本歷史
|
||||
|
||||
---
|
||||
|
||||
## 2. 修改前預檢清單
|
||||
|
||||
### 2.1 文件閱讀要求
|
||||
|
||||
修改文件前，必須完成以下閱讀：
|
||||
|
||||
| 步驟 | 項目 | 說明 |
|
||||
|------|------|------|
|
||||
| 1 | 閱讀完整文件 | 不可僅閱讀部分章節 |
|
||||
| 2 | 理解文件用途 | 確認文件的目標讀者 |
|
||||
| 3 | 確認現有術語 | 使用一致的術語和命名 |
|
||||
| 4 | 查閱相關文件 | 確認相關聯的文件 |
|
||||
|
||||
### 2.2 預檢問題清單
|
||||
|
||||
在修改前回答以下問題：
|
||||
|
||||
```
|
||||
□ 1. 此修改是否影響其他文件？
|
||||
□ 2. 此修改是否與現有規範衝突？
|
||||
□ 3. 此修改是否需要更新版本歷史？
|
||||
□ 4. 此修改是否需要新增測試？
|
||||
□ 5. 此修改是否需要通知相關人員？
|
||||
□ 6. 此修改是否有破壞性變更（Breaking Change）？
|
||||
```
|
||||
|
||||
### 2.3 預檢命令
|
||||
|
||||
修改前執行以下命令確認現有狀態：
|
||||
|
||||
```bash
|
||||
# 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 預修改彙報格式
|
||||
|
||||
在執行修改前，必須先彙報以下內容：
|
||||
|
||||
```markdown
|
||||
## 檔案
|
||||
`<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 對照：
|
||||
|
||||
```bash
|
||||
git diff <file_path>
|
||||
```
|
||||
|
||||
### 4.2 變更類型分類
|
||||
|
||||
| 類型 | 標記 | 說明 |
|
||||
|------|------|------|
|
||||
| 新增 | `+` | 新增內容 |
|
||||
| 刪除 | `-` | 刪除內容 |
|
||||
| 修改 | `~` | 修改內容 |
|
||||
| 移動 | `↕` | 移動位置 |
|
||||
| 格式 | `@` | 格式變更 |
|
||||
|
||||
### 4.3 變更確認清單
|
||||
|
||||
```
|
||||
□ 1. diff 輸出已確認
|
||||
□ 2. 變更符合預期
|
||||
□ 3. 無意外變更
|
||||
□ 4. 版本歷史已更新
|
||||
□ 5. 其他關聯文件已檢查
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 驗證流程
|
||||
|
||||
### 5.1 自動化驗證
|
||||
|
||||
修改後執行以下自動化檢查：
|
||||
|
||||
```bash
|
||||
# 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 範例
|
||||
|
||||
```bash
|
||||
# 文檔更新
|
||||
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 工具修改文件前，必須：
|
||||
|
||||
1. **完整閱讀**：閱讀完整文件（不可只讀取部分）
|
||||
2. **理解語境**：理解文件的用途和目標讀者
|
||||
3. **查閱相關**：查閱相關聯文件確保一致性
|
||||
4. **提出計畫**：修改前先提出變更計畫供確認
|
||||
|
||||
### 7.2 修改後確認
|
||||
|
||||
AI 工具修改文件後，必須：
|
||||
|
||||
1. **展示差異**：顯示修改的 diff 內容
|
||||
2. **說明變更**：解釋每項變更的目的
|
||||
3. **執行驗證**：執行相關的 lint/test 命令
|
||||
4. **更新歷史**：更新版本歷史表
|
||||
|
||||
### 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 |
|
||||
Reference in New Issue
Block a user