admin/momentry_core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: docs_v1.0 structure

Browse Source 
- API_V1.0.0: 正式 API 文件（spec、release、deploy、test）
- M4_workspace: M4 工作記錄（review、issue、提案）
- M5_workspace: M5 工作記錄（實作、評估、sync）
- AGENTS.md: 專案規則

M5/M4 協作方式：git push/pull 同步 workspace 文件
This commit is contained in:
M5
2026-05-07 23:42:19 +08:00
commit 28e927f7bb
519 changed files with 136077 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

990
docs_v1.0/STANDARDS/DOCS_STANDARD.md Normal file
View File

@@ -0,0 +1,990 @@
---
document_type: "standard_doc"
service: "MOMENTRY_CORE"
title: "文件創建規範"
date: "2026-04-27"
version: "V2.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "docs-standard"
- "ai-agent-friendly"
- "yaml-frontmatter"
- "rag-optimization"
ai_query_hints:
- "查詢 文件創建規範 的內容"
- "文件創建規範 的主要目的是什麼？"
- "如何操作或實施 文件創建規範？"
- "AI Agent 友好規範要求"
- "YAML Frontmatter 必需字段"
- "ai_query_hints 编寫規範"
- "tags 编寫規範"
- "document_type 完整類型列表"
related_documents:
- "STANDARDS/DOCS_STANDARD_IMPROVEMENT_PROPOSAL_2026_03_27.md"
---
# 文件創建規範
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-18 |
| 文件版本 | V2.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件規範 | Warren | OpenCode / MiniMax M2.5 |
| V2.0 | 2026-04-27 | 添加 AI Agent 友好完整規範（10.6-10.12） | OpenCode | GLM-5 |
---
本文檔定義 Momentry Core 專案中文件的命名規範、格式標準和結構要求。
---
## 1. 檔案命名規範
### 命名模式
所有文件必須使用以下命名模式：
| 文件類型 | 模式 | 範例 |
|----------|------|------|
| 安裝指南 | `INSTALL_<NAME>.md` | `INSTALL_POSTGRESQL.md` |
| 開發指南 | `DEVELOP_<NAME>.md` | `DEVELOP_API.md` |
| API 參考 | `API_REFERENCE.md` | `API_REFERENCE.md` |
| 規格文件 | `<NAME>_SPEC.md` | `CHUNK_SPEC.md` |
| 設計文件 | `<NAME>_DESIGN.md` | `CHUNK_DESIGN.md` |
| 服務總覽 | `SERVICES.md` | `SERVICES.md` |
| 其他文件 | `<NAME>.md` | `README.md` |
### 命名規則
- 使用 **大駝峰** (PascalCase) 命名法
- 服務名稱使用 **全大寫** (e.g., `POSTGRESQL`, `SFTPGO`)
- 英文優先，縮寫保持大寫
- 使用底線 `_` 作為單詞分隔符
- 副檔名統一使用 `.md` (Markdown)
### 禁止事項
- 不允許使用中文檔名
- 不允許空格
- 不允許混合大小寫 (如 `Install_PostgreSQL.md`)
---
## 2. 文件結構模板
### 安裝指南結構
```markdown
# <服務名稱> 安裝指南 (部署類型)
## 概述
本文檔說明如何...
---
## 當前狀態
| 項目 | 狀態 |
|------|------|
| <服務名> | ✅ 已安裝 v<版本號> |
| Port | <端口號> |
| ... | ... |
---
## 安裝步驟
### Step 1: <步驟名稱>
<說明內容>
```bash
# 代碼範例
command --option value
```
### Step 2: <步驟名稱>
...
---
## 卸載步驟
### Step 1: <步驟名稱>
...
---
## 故障排除
### <問題名稱>
<解決方案>
---
## 檔案位置
| 類型 | 路徑 | 說明 |
|------|------|------|
| 安裝 | /path/to/install | 說明 |
...
---
## 常用指令
```bash
# 驗證
command verify
# 查看版本
command --version
```
---
## 版本資訊
- 版本: <版本號>
- 安裝日期: <日期>
```
---
### 規格文件結構
```markdown
# <名稱> 規格文件
## 概述
<簡短描述>
---
## 詳細規格
### 1. <功能模組>
#### 欄位定義
| 欄位 | 類型 | 必填 | 說明 |
|------|------|------|------|
| field1 | string | Yes | 說明 |
#### 資料結構
```json
{
"example": "data"
}
```
---
## 限制條件
- <限制1>
- <限制2>
---
## 相關文件
- `RELATED_FILE.md` - 相關說明
```
---
## 3. 格式標準
### Markdown 格式
| 項目 | 標準 |
|------|------|
| 標題層級 | H1 (`#`) → H2 (`##`) → H3 (`###`) |
| 水平線 | 使用 `---` 分隔主要章節 |
| 程式碼區塊 | 使用三個反引號 ``` 並標註語言 |
| 表格 | 使用 `|` 和 `-` 對齊 |
| 強調 | 使用 `**粗體**` 和 `*斜體*` |
### 程式碼區塊語言標註
```bash
# Bash
```bash
command
```
```json
# JSON
```json
{"key": "value"}
```
```rust
# Rust
```rust
fn main() {}
```
```yaml
# YAML
key: value
```
### 表格格式
```markdown
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |
```
### 列表格式
- 使用 `-` 作為無序列表標記
- 使用數字 `1.` 作為有序列表標記
- 縮進使用 2 個空格
---
## 4. 語言規範
### 標題語言
| 區域 | 語言 |
|------|------|
| 主要內容 | 繁體中文 |
| 技術術語 | 英文保留 |
| 命令和代碼 | 英文 |
| 文件標題 | 繁體中文 |
### 常用術語對照
| 英文 | 中文 |
|------|------|
| Install | 安裝 |
| Configure/Config | 配置/設定 |
| Uninstall | 卸載 |
| Troubleshooting | 故障排除 |
| Status | 狀態 |
| Documentation | 文件 |
| Guide | 指南 |
| Overview | 概述 |
| Specification | 規格 |
| Current Status | 當前狀態 |
| Default | 預設 |
| Required | 必填 |
| Optional | 選填 |
| Example | 範例 |
### 標點符號
- 中文內容使用全形標點：`，`、`。`、`：`、`（`、`）`
- 英文/程式內容使用半形標點：`:`、`(`、`)`
- 命令行使用 `` `command` `` 格式
---
## 5. 內容要求
### 必需章節
每份文件必須包含：
1. **標題** - 文件名稱
2. **概述** - 檔案用途說明
3. **版本/狀態資訊** - 當前狀態
4. **檔案位置** - 重要路徑列表
5. **常用指令** - 基本操作命令
### 版本資訊格式
每份文件頂部必須包含以下資訊：
```markdown
| 項目 | 內容 |
|------|------|
| 建立者 | <姓名> |
| 建立時間 | <YYYY-MM-DD> |
| 文件版本 | V1.0 |
```
版本歷史表：
```markdown
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
```
---
### 版本資訊章節格式
```markdown
---
## 版本資訊
- 版本: <版本號>
- 安裝日期: <YYYY-MM-DD>
- 文件更新: <YYYY-MM-DD>
```
### 狀態標記
| 狀態 | 標記 |
|------|------|
| 已安裝 | ✅ 已安裝 v<x.x.x> |
| 未安裝 | ❌ 未安裝 |
| 可選 | ⚙️ 可選 |
| 進行中 | 🔄 進行中 |
---
## 6. 示例文件
### 正確範例
```markdown
# PostgreSQL 安裝指南 (本地部署)
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-18 |
| 文件版本 | V1.0 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
---
## 概述
本文檔說明如何在 macOS 上安裝 PostgreSQL...
---
## 當前狀態
| 項目 | 狀態 |
|------|------|
| PostgreSQL | ✅ 已安裝 v16.2 |
| Port | 5432 |
---
## 安裝步驟
### Step 1: 安裝 PostgreSQL
```bash
brew install postgresql@16
```
### Step 2: 啟動服務
```bash
brew services start postgresql@16
```
---
## 檔案位置
| 類型 | 路徑 |
|------|------|
| 配置文件 | /path/to/config |
| 數據目錄 | /path/to/data |
---
## 版本資訊
- 版本: 16.2
- 安裝日期: 2026-03-01
```
### 錯誤範例
```
❌ PostgreSQL安裝.md # 中文檔名
❌ install-postgresql.md # 全部小寫
❌ Install PostgreSQL.md # 空格
❌ postgresql_install.md # 非標準命名
```
---
## 7. 文件審查清單
創建新文件時，請確認：
- [ ] 檔案命名符合 `INSTALL_*.md` 或其他標準模式
- [ ] 文件包含頂部資訊表（建立者、建立時間、版本）
- [ ] 文件包含版本歷史表
- [ ] 文件包含概述章節
- [ ] 文件包含當前狀態/版本資訊
- [ ] 文件包含檔案位置章節
- [ ] 文件包含常用指令章節
- [ ] 使用統一的 Markdown 格式
- [ ] 使用繁體中文作為主要語言
- [ ] 程式碼區塊標註語言類型
- [ ] 表格格式正確
- [ ] 章節使用 `---` 分隔
### 頂部資訊表範本
```markdown
| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-18 |
| 文件版本 | V1.0 |
```
### 版本歷史表範本
```markdown
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
```
---
## 8. 更新現有文件
當更新現有文件時：
1. 更新 **版本資訊** 中的日期
2. 如有必要，更新版本號
3. 記錄重大變更於 `CHANGELOG.md` 或 `DEVELOPMENT_LOG.md`
---
## 9. 運維紀錄標準
### 9.1 事件嚴重等級定義
| 等級 | 代碼 | 影響描述 | 處理時間目標 | 通知要求 |
|------|------|----------|--------------|----------|
| P0 | 緊急 | 服務完全中斷，影響所有用戶 | 立即處理，1小時內解決 | 立即通知所有相關人員 |
| P1 | 高 | 主要功能不可用，影響多數用戶 | 2小時內開始處理，4小時內解決 | 1小時內通知負責人 |
| P2 | 中 | 次要功能問題，影響部分用戶 | 4小時內開始處理，8小時內解決 | 2小時內通知負責人 |
| P3 | 低 | 輕微問題，不影響核心功能 | 1個工作日內處理 | 工作日內通知 |
| P4 | 資訊 | 諮詢、建議或非緊急問題 | 3個工作日內回應 | 無需緊急通知 |
### 9.2 事件狀態標記
| 狀態 | 標記 | 說明 |
|------|------|------|
| 新報告 | ⏳ 待處理 | 事件剛被報告，尚未分配 |
| 調查中 | 🔍 調查中 | 正在調查根本原因 |
| 處理中 | 🔧 處理中 | 正在實施解決方案 |
| 已解決 | ✅ 已解決 | 問題已解決，待驗證 |
| 已關閉 | 📁 已關閉 | 事件完全關閉 |
| 已歸檔 | 🗄️ 已歸檔 | 事件已歸檔 |
### 9.3 RCA 文件結構模板
#### 必需章節
1. **頂部資訊表** - 建立者、時間、版本、嚴重等級
2. **版本歷史** - 文件變更紀錄
3. **事件摘要** - 問題概述和影響
4. **調查過程** - 詳細調查步驟和發現
5. **根本原因分析** - 主要和次要原因
6. **解決方案與實施** - 具體修復措施
7. **預防措施** - 短期、中期、長期改進
8. **影響評估** - 直接和間接影響
9. **經驗教訓** - 學到的教訓和最佳實踐
10. **相關文件** - 相關參考文件
11. **簽核** - 相關人員確認
#### 可選章節
- 技術細節附錄
- 測試腳本詳解
- 配置參數說明
- 監控指標定義
### 9.4 文件生命周期管理
| 階段 | 目錄 | 說明 |
|------|------|------|
| 進行中 | `[類型]/_active/` | 正在處理的事件/變更 (類型: rca, incidents, changes, plans) |
| 已完成 | `[類型]/_completed/` | 已完成的處理項目 (類型: rca, incidents, changes, plans) |
| 已歸檔 | `[類型]/_archived/` | 超過保留期限的文件 (類型: rca, incidents, changes, plans) |
#### 保留政策
| 文件類型 | 保留期限 | 歸檔策略 |
|----------|----------|----------|
| RCA 文件 | 2 年 | 年度歸檔 |
| 事件報告 | 1 年 | 季度歸檔 |
| 變更紀錄 | 3 年 | 年度歸檔 |
| 維護計畫 | 1 年 | 完成後歸檔 |
---
## 附錄：文件類型參考
| 前綴 | 用途 | 位置 |
|------|------|------|
| `INSTALL_` | 服務安裝指南 | `/docs/` |
| `DEVELOP_` | 開發指南 | `/docs/` |
| `*_SPEC.md` | 規格定義 | `/docs/` |
| `*_DESIGN.md` | 設計文件 | `/docs/` |
| `API_REFERENCE.md` | API 參考文件 | `/docs/` |
| `README.md` | 專案總覽 | `/` |
| `AGENTS.md` | AI 代理指令 | `/` |
| `CHANGELOG.md` | 變更日誌 | `/` |
### 運維紀錄文件類型（新增）
| 前綴 | 用途 | 位置 | 語言 | 狀態標記 |
|------|------|------|------|----------|
| `RCA_` | 根本原因分析 | `/docs/maintenance_records/rca/` | 繁體中文 | P0-P4 |
| `INCIDENT_` | 事件報告 | `/docs/maintenance_records/incidents/` | 繁體中文 | ✅/⏳/❌ |
| `CHANGE_` | 變更紀錄 | `/docs/maintenance_records/changes/` | 繁體中文 | ✅/🔧/⚠️ |
| `MAINTENANCE_` | 維護計畫 | `/docs/maintenance_records/plans/` | 繁體中文 | 📅/🔧/✅ |
| `TEMPLATE_` | 文件模板 | `/docs/maintenance_records/templates/` | 繁體中文 | - |
### 運維紀錄目錄結構
```
docs/maintenance_records/
├── rca/ # 根本原因分析 (RCA_*.md)
│ ├── _active/ # 正在處理的 RCA
│ ├── _completed/ # 已完成的 RCA
│ └── _archived/ # 已歸檔的 RCA
├── incidents/ # 事件報告 (INCIDENT_*.md)
│ ├── _active/ # 正在處理的事件
│ ├── _completed/ # 已完成的事件
│ └── _archived/ # 已歸檔的事件
├── changes/ # 變更紀錄 (CHANGE_*.md)
│ ├── _active/ # 正在處理的變更
│ ├── _completed/ # 已完成的變更
│ └── _archived/ # 已歸檔的變更
├── plans/ # 維護計畫 (MAINTENANCE_*.md)
│ ├── _active/ # 正在處理的計畫
│ ├── _completed/ # 已完成的計畫
│ └── _archived/ # 已歸檔的計畫
└── templates/ # 文件模板 (TEMPLATE_*.md)
```
### 文件名稱格式
- **RCA 文件**: `RCA_<服務名稱>_<問題簡述>_<日期>.md`
- 範例: `RCA_WORDPRESS_TIMEOUT_EXTERNAL_ACCESS_2026_03_27.md`
- **事件報告**: `INCIDENT_<服務名稱>_<事件類型>_<日期>.md`
- 範例: `INCIDENT_POSTGRESQL_CONNECTION_ISSUE_2026_03_26.md`
- **變更紀錄**: `CHANGE_<服務名稱>_<變更類型>_<日期>.md`
- **維護計畫**: `MAINTENANCE_<服務名稱>_<計畫類型>_<日期>.md`
---
## 10. AI Agent 友好規範
### 10.1 雙重格式設計
所有新創建的文件必須包含 **YAML Frontmatter** 和 **Markdown 內容** 兩種格式，以確保 AI Agent 能高效解析，同時人類用戶也能方便閱讀。
| 格式 | 用途 | 優先級 |
|------|------|--------|
| YAML Frontmatter | AI Agent 結構化元數據解析 | 高 (AI 優先) |
| Markdown 內容 | 人類可讀展示 | 中 (人類備用) |
### 10.2 YAML Frontmatter 規範
文件頂部必須包含標準化的 YAML Frontmatter，位於文件開頭的 `---` 之間：
```yaml
---
document_type: "design" | "spec" | "guide" | "plan" | "rca" | "incident"
service: "MOMENTRY_CORE" | "服務名稱"
title: "文件標題"
date: "YYYY-MM-DD"
status: "active" | "completed" | "archived"
current_state: "draft" | "review" | "approved"
owner: "負責人姓名"
created_by: "OpenCode / 姓名"
created_at: "YYYY-MM-DD"
version: "V1.0"
tags:
- "標籤1"
- "標籤2"
related_documents:
- "相關文件.md"
ai_query_hints:
- "查詢提示1"
- "查詢提示2"
---
```
### 10.3 標準化字段定義
| 字段 | 類型 | 必填 | 說明 |
|------|------|------|------|
| document_type | string | Yes | 文件類型 (design, spec, guide, plan, rca, etc.) |
| service | string | Yes | 服務名稱 (全大寫) |
| title | string | Yes | 文件標題 |
| date | string | Yes | 建立/更新日期 |
| status | string | Yes | 生命週期狀態 (active, completed, archived) |
| owner | string | Yes | 負責人 |
| created_by | string | Yes | 建立者 |
| version | string | Yes | 版本號 |
| tags | list | No | 搜尋標籤 (建議填寫以優化 AI 檢索) |
| ai_query_hints | list | No | AI 查詢提示 (說明文件核心內容，優化 RAG 檢索) |
### 10.4 同步要求
YAML Frontmatter 與文件內部的 Markdown 頂部資訊表必須保持數據同步。
當更新文件時，必須同時更新 YAML Frontmatter 和 Markdown 表格。
### 10.5 文件審查清單更新
創建新文件時，除了原有的檢查項目，還必須確認：
- [ ] 文件包含標準 YAML Frontmatter
- [ ] `document_type` 和 `service` 已正確設定
- [ ] `tags` 和 `ai_query_hints` 已填寫相關內容
- [ ] YAML Frontmatter 與 Markdown 頂部資訊表內容一致
---
### 10.6 document_type 完整類型列表
文件類型必須使用以下標準化枚舉值：
| document_type | 中文說明 | 適用場景 | 範例檔名 |
|---------------|----------|----------|----------|
| `standard_doc` | 規範文件 | 定義標準、規則、流程 | `DOCS_STANDARD.md` |
| `architecture_design` | 架構設計 | 系統架構、模組設計 | `JOB_WORKER_IMPLEMENTATION_PLAN.md` |
| `reference_doc` | 參考文件 | API 參考、字段規格 | `PROCESSING_STATUS_JSONB_SPEC.md` |
| `install_guide` | 安裝指南 | 服務安裝步驟 | `INSTALL_POSTGRESQL.md` |
| `develop_guide` | 開發指南 | 開發流程、最佳實踐 | `DEVELOP_API.md` |
| `plan` | 計畫文件 | 實作計畫、時程規劃 | `*_PLAN.md` |
| `rca` | 根本原因分析 | 事件調查、根因分析 | `RCA_*.md` |
| `incident` | 事件報告 | 問題報告、處理紀錄 | `INCIDENT_*.md` |
| `change` | 變更紀錄 | 配置變更、版本更新 | `CHANGE_*.md` |
| `template` | 模板文件 | 文件模板、範本 | `TEMPLATE_*.md` |
| `spec` | 規格文件 | 技術規格、接口定義 | `*_SPEC.md` |
| `design` | 設計文件 | 功能設計、方案設計 | `*_DESIGN.md` |
---
### 10.7 ai_query_hints 编寫規範
#### 10.7.1 编寫原则
| 原則 | 說明 |
|------|------|
| **覆蓋核心問題** | 查詢提示應覆蓋文件的核心內容和常見問題 |
| **使用自然語言** | 提示應使用用戶可能問的自然語言句式 |
| **包含關鍵術語** | 提示應包含文件中的關鍵術語和專有名詞 |
| **多角度覆蓋** | 提示應從不同角度描述文件內容（目的、操作、結構） |
#### 10.7.2 提示句式範本
| 句式類型 | 範本 | 範例 |
|----------|------|------|
| **內容查詢** | `查詢 <文件標題> 的內容` | `查詢 processing_status JSONB 字段規範的內容` |
| **目的查詢** | `<文件標題> 的主要目的是什麼？` | `processing_status JSONB 字段規範的主要目的是什麼？` |
| **操作查詢** | `如何操作或實施 <文件標題>？` | `如何查詢 processing_status JSONB 字段？` |
| **結構查詢** | `<文件標題> 的結構定義` | `processing_status JSONB 結構定義` |
| **字段查詢** | `<關鍵字段> 說明` | `pre_chunks_summary 結構說明` |
| **流程查詢** | `<流程名稱> 流程` | `Agent 進度追蹤流程` |
#### 10.7.3 数量建议
| 项目 | 数量 |
|------|------|
| 最少數量 | 3-5 個查詢提示 |
| 建議數量 | 5-8 個查詢提示 |
| 最多數量 | 10 個查詢提示（避免冗余） |
#### 10.7.4 範例
```yaml
ai_query_hints:
- "查詢 processing_status JSONB 字段規範的內容"
- "processing_status JSONB 結構定義"
- "如何查詢 processing_status JSONB 字段"
- "pre_chunks_summary 結構說明"
- "chunks_summary 結構說明"
- "Agent 進度追蹤字段"
- "processing_status SQL 查詢範例"
- "processing_status Rust 實作範例"
```
---
### 10.8 tags 编寫規範
#### 10.8.1 标签选择原则
| 原則 | 說明 |
|------|------|
| **核心主题** | 标签应反映文件的核心主题 |
| **关键术语** | 标签应包含文件中的关键术语 |
| **分类标签** | 标签应包含文件类型分类（如 `规范`, `设计`, `API`） |
| **技术栈** | 标签应包含涉及的技术栈（如 `rust`, `postgresql`, `jsonb`） |
| **关联模块** | 标签应包含关联的系统模块（如 `processor`, `rule`, `agent`） |
#### 10.8.2 标签命名规范
| 规范 | 說明 |
|------|------|
| **使用小写英文** | 标签统一使用小写英文（便于检索） |
| **使用连字符** | 多词标签使用连字符分隔（如 `ai-agent`） |
| **避免中文标签** | 不建议使用中文标签（AI 检索效率低） |
#### 10.8.3 标签分类建议
| 分类 | 範例标签 |
|------|----------|
| **文件类型** | `standard`, `spec`, `design`, `guide`, `plan`, `rca`, `template` |
| **技术栈** | `rust`, `postgresql`, `redis`, `mongodb`, `qdrant`, `jsonb`, `vector` |
| **系统模块** | `processor`, `rule`, `agent`, `chunk`, `embedding`, `api`, `worker` |
| **核心概念** | `processing-status`, `progress-tracking`, `resume`, `checkpoint` |
| **数据结构** | `pre-chunks`, `chunks`, `frames`, `vectors` |
#### 10.8.4 数量建议
| 项目 | 数量 |
|------|------|
| 最少數量 | 3-5 個标签 |
| 建議數量 | 5-8 個标签 |
| 最多數量 | 10 個标签（避免冗余） |
#### 10.8.5 範例
```yaml
tags:
- "jsonb"
- "processing-status"
- "progress-tracking"
- "processor"
- "rule"
- "agent"
```
---
### 10.9 RAG 檢索優化建議
#### 10.9.1 文件內容結構優化
| 建議 | 說明 |
|------|------|
| **標題清晰** | 使用明確的標題描述文件內容 |
| **段落分明** | 使用 `---` 分隔主要章節，提升段落識別 |
| **表格標準** | 使用標準表格格式，避免嵌套表格 |
| **代碼標註** | 代碼區塊標註語言類型（提升代碼檢索） |
| **避免冗余** | 删除重複內容，降低向量噪音 |
#### 10.9.2 关键术语定义表
建議在文件中包含關鍵術語定義表，提升術語檢索效果：
```markdown
## 關鍵術語定義
| 術語 | 定義 |
|------|------|
| processing_status | JSONB 字段，追蹤處理進度 |
| phase | 當前階段（PROCESSING, COMPLETED, FAILED） |
| pre_chunks_summary | pre_chunks 表絕計（按處理器） |
| chunks_summary | chunks 表絕計（按 Rule） |
```
#### 10.9.3 语义一致性
| 建議 | 說明 |
|------|------|
| **術語統一** | 同一概念使用相同術語（如 `processing_status` 不混用 `status`） |
| **缩写统一** | 同一缩写使用相同形式（如 `ASR` 不混用 `asr`） |
| **避免歧义** | 避免使用多義詞，或明確定義多義詞 |
#### 10.9.4 向量化效果优化
| 建議 | 說明 |
|------|------|
| **段落长度适中** | 单段落建议 100-500 字，避免过长段落 |
| **关键信息前置** | 将关键信息放在段落开头 |
| **避免空内容** | 删除空白章节或占位内容 |
---
### 10.10 related_documents 字段（建議）
#### 10.10.1 字段定义
| 字段 | 類型 | 必填 | 說明 |
|------|------|------|------|
| `related_documents` | list | No | 相關文件列表（建議填寫以建立知識圖谱） |
#### 10.10.2 编寫规范
| 规范 | 說明 |
|------|------|
| **使用相对路径** | 使用相对路径引用文件（如 `REFERENCE/PROCESSING_STATUS_JSONB_SPEC.md`） |
| **包含说明** | 每个引用包含简要说明（可选） |
| **数量适中** | 建议 3-5 个相关文件引用 |
#### 10.10.3 範例
```yaml
related_documents:
- "ARCHITECTURE/JOB_WORKER_IMPLEMENTATION_PLAN.md"
- "REFERENCE/VIDEO_PROCESSING_SPEC.md"
- "ARCHITECTURE/PROCESSING_PIPELINE.md"
- "AI_AGENTS/CORE/AGENT_SPEC.md"
```
---
### 10.11 AI Agent 友好完整範例
以下為符合 AI Agent 友好規範的完整文件範例：
```yaml
---
document_type: "reference_doc"
service: "MOMENTRY_CORE"
title: "processing_status JSONB 字段規範"
date: "2026-04-27"
version: "V1.2"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "jsonb"
- "processing-status"
- "progress-tracking"
- "processor"
- "rule"
- "agent"
ai_query_hints:
- "查詢 processing_status JSONB 字段規範的內容"
- "processing_status JSONB 結構定義"
- "如何查詢 processing_status JSONB 字段"
- "pre_chunks_summary 結構說明"
- "chunks_summary 結構說明"
- "Agent 進度追蹤字段"
- "processing_status SQL 查詢範例"
- "processing_status Rust 實作範例"
related_documents:
- "ARCHITECTURE/JOB_WORKER_IMPLEMENTATION_PLAN.md"
- "REFERENCE/VIDEO_PROCESSING_SPEC.md"
- "ARCHITECTURE/PROCESSING_PIPELINE.md"
---
# processing_status JSONB 字段規範
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-27 |
| 文件版本 | V1.2 |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.2 | 2026-04-27 | 從 VARCHAR 改為 JSONB，支持多層級進度追蹤 | OpenCode | GLM-5 |
---
## 概述
從 V1.2 起，`videos` 表的 `processing_status` 字段改為 **JSONB** 格式。
---
## 關鍵術語定義
| 術語 | 定義 |
|------|------|
| processing_status | JSONB 字段，追蹤處理進度 |
| phase | 當前階段（PROCESSING, COMPLETED, FAILED） |
| pre_chunks_summary | pre_chunks 表絕計（按處理器） |
| chunks_summary | chunks 表絕計（按 Rule） |
---
## 1. JSONB 結構定義
...
```
---
### 10.12 文件審查清單（AI Agent 友好完整版）
創建新文件時，必須確認以下所有檢查項目：
#### 必需項目（P0）
- [ ] 文件包含標準 YAML Frontmatter（位於文件開頭）
- [ ] `document_type` 使用標準化枚舉值（見 10.6）
- [ ] `service` 設為 `MOMENTRY_CORE` 或服務名稱（全大寫）
- [ ] `title` 清晰描述文件內容
- [ ] `date` 使用 YYYY-MM-DD 格式
- [ ] `status` 設為 `active` | `completed` | `archived`
- [ ] `owner` 設為負責人姓名
- [ ] `created_by` 設為建立者姓名
- [ ] `version` 使用 V1.0 格式
#### 建議項目（P1）
- [ ] `tags` 包含 5-8 個標籤（見 10.8）
- [ ] `ai_query_hints` 包含 5-8 個查詢提示（見 10.7）
- [ ] `related_documents` 包含 3-5 個相關文件（見 10.10）
#### 同步要求（P0）
- [ ] YAML Frontmatter 與 Markdown 頂部資訊表內容一致
- [ ] YAML `title` 與 Markdown `#` 標題一致
- [ ] YAML `version` 與 Markdown 文件版本一致
- [ ] YAML `date` 與 Markdown 建立時間一致
#### RAG 優化（P1）
- [ ] 包含關鍵術語定義表（見 10.9.2）
- [ ] 使用標準表格格式
- [ ] 代碼區塊標註語言類型
- [ ] 段落使用 `---` 分隔
- [ ] 術語使用一致（無混用）

431
docs_v1.0/STANDARDS/DOCS_STANDARD_IMPROVEMENT_PROPOSAL_2026_03_27.md Normal file
View File

@@ -0,0 +1,431 @@
---
document_type: "standard_doc"
service: "MOMENTRY_CORE"
title: "文件創建規範改善建議"
date: "2026-03-27"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
- "文件創建規範改善建議"
ai_query_hints:
- "查詢 文件創建規範改善建議 的內容"
- "文件創建規範改善建議 的主要目的是什麼？"
- "如何操作或實施 文件創建規範改善建議？"
---
# 文件創建規範改善建議
| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-03-27 |
| 文件版本 | V1.0 |
| 提案狀態 | 🔧 部分實施 (階段1完成) |
---
## 版本歷史
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-27 | 創建提案文件 | OpenCode | deepseek-reasoner |
---
## 概述
本文檔針對現有的 `DOCS_STANDARD.md` 提出改善建議，主要解決以下問題：
1. **缺少運維文件類型規範** - 無 `RCA_`、`INCIDENT_` 等前綴定義
2. **維護紀錄管理缺失** - 無專門目錄結構規範
3. **事件分類不完整** - 無事件嚴重等級、處理流程規範
---
## 問題分析
### 現有規範不足之處
#### 1. 文件類型前綴不完整
**現狀** (`DOCS_STANDARD.md` 第45-46行)：
| 前綴 | 用途 | 位置 |
|------|------|------|
| `INSTALL_` | 服務安裝指南 | `/docs/` |
| `DEVELOP_` | 開發指南 | `/docs/` |
| `*_SPEC.md` | 規格定義 | `/docs/` |
| `*_DESIGN.md` | 設計文件 | `/docs/` |
| `API_REFERENCE.md` | API 參考文件 | `/docs/` |
**缺失的前綴**：
| 前綴 | 用途 | 建議位置 |
|------|------|----------|
| `RCA_` | 根本原因分析 | `/docs/maintenance_records/` |
| `INCIDENT_` | 事件報告 | `/docs/maintenance_records/` |
| `CHANGE_` | 變更紀錄 | `/docs/maintenance_records/` |
| `MAINTENANCE_` | 維護計畫 | `/docs/maintenance_records/` |
#### 2. 目錄結構規範缺失
**現狀**：所有文件統一存放在 `/docs/` 目錄
**問題**：
- 運維文件與技術文件混雜
- 難以查找特定類型文件
- 缺乏生命周期管理
**建議結構**：
```
docs/
├── installation/ # 安裝指南
├── development/ # 開發指南
├── api/ # API 文件
├── specifications/ # 規格文件
├── designs/ # 設計文件
└── maintenance_records/ # 運維紀錄 (新增)
├── rca/ # 根本原因分析
├── incidents/ # 事件報告
├── changes/ # 變更紀錄
└── plans/ # 維護計畫
```
#### 3. 事件處理流程缺失
**現狀**：無事件報告、處理、歸檔規範
**缺失內容**：
- 事件嚴重等級定義 (P0-P4)
- 事件處理時間目標 (SLA)
- 根本原因分析模板
- 事件歸檔流程
---
## 具體改善建議
### 建議 1：擴充文件類型前綴
#### 新增前綴定義
建議在 `DOCS_STANDARD.md` 第45-46行後添加：
| 前綴 | 用途 | 位置 | 語言 | 狀態標記 |
|------|------|------|------|----------|
| `RCA_` | 根本原因分析 | `/docs/maintenance_records/rca/` | 繁體中文 | P0-P4 |
| `INCIDENT_` | 事件報告 | `/docs/maintenance_records/incidents/` | 繁體中文 | ✅/⏳/❌ |
| `CHANGE_` | 變更紀錄 | `/docs/maintenance_records/changes/` | 繁體中文 | ✅/🔧/⚠️ |
| `MAINTENANCE_` | 維護計畫 | `/docs/maintenance_records/plans/` | 繁體中文 | 📅/🔧/✅ |
#### 文件名稱格式
**事件文件命名**：
```
RCA_<服務名稱>_<問題簡述>_<日期>.md
INCIDENT_<服務名稱>_<事件類型>_<日期>.md
```
**範例**：
```
RCA_WORDPRESS_TIMEOUT_EXTERNAL_ACCESS_2026_03_27.md
INCIDENT_POSTGRESQL_CONNECTION_ISSUE_2026_03_26.md
```
### 建議 2：建立維護紀錄目錄規範
#### 目錄結構
```markdown
## 目錄結構規範
### 運維紀錄目錄 (`/docs/maintenance_records/`)
| 子目錄 | 用途 | 文件範例 |
|--------|------|----------|
| `rca/` | 根本原因分析 | `RCA_*.md` |
| `incidents/` | 事件報告 | `INCIDENT_*.md` |
| `changes/` | 變更紀錄 | `CHANGE_*.md` |
| `plans/` | 維護計畫 | `MAINTENANCE_*.md` |
| `templates/` | 文件模板 | `TEMPLATE_*.md` |
### 文件生命周期管理
| 階段 | 目錄 | 說明 |
|------|------|------|
| 進行中 | `[類型]/_active/` | 正在處理的事件/變更 (類型: rca, incidents, changes, plans) |
| 已完成 | `[類型]/_completed/` | 已完成的處理項目 (類型: rca, incidents, changes, plans) |
| 已歸檔 | `[類型]/_archived/` | 超過保留期限的文件 (類型: rca, incidents, changes, plans) |
```
#### 保留政策
| 文件類型 | 保留期限 | 歸檔策略 |
|----------|----------|----------|
| RCA 文件 | 2 年 | 年度歸檔 |
| 事件報告 | 1 年 | 季度歸檔 |
| 變更紀錄 | 3 年 | 年度歸檔 |
| 維護計畫 | 1 年 | 完成後歸檔 |
### 建議 3：定義事件嚴重等級
#### 嚴重等級定義
建議在規範中添加以下內容：
```markdown
## 事件嚴重等級定義
| 等級 | 代碼 | 影響描述 | 處理時間目標 | 通知要求 |
|------|------|----------|--------------|----------|
| P0 | 緊急 | 服務完全中斷，影響所有用戶 | 立即處理，1小時內解決 | 立即通知所有相關人員 |
| P1 | 高 | 主要功能不可用，影響多數用戶 | 2小時內開始處理，4小時內解決 | 1小時內通知負責人 |
| P2 | 中 | 次要功能問題，影響部分用戶 | 4小時內開始處理，8小時內解決 | 2小時內通知負責人 |
| P3 | 低 | 輕微問題，不影響核心功能 | 1個工作日內處理 | 工作日內通知 |
| P4 | 資訊 | 諮詢、建議或非緊急問題 | 3個工作日內回應 | 無需緊急通知 |
```
#### 事件狀態標記
| 狀態 | 標記 | 說明 |
|------|------|------|
| 新報告 | ⏳ 待處理 | 事件剛被報告，尚未分配 |
| 調查中 | 🔍 調查中 | 正在調查根本原因 |
| 處理中 | 🔧 處理中 | 正在實施解決方案 |
| 已解決 | ✅ 已解決 | 問題已解決，待驗證 |
| 已關閉 | 📁 已關閉 | 事件完全關閉 |
| 已歸檔 | 🗄️ 已歸檔 | 事件已歸檔 |
### 建議 4：標準化 RCA 文件模板
#### RCA 文件必需章節
建議在規範中添加以下模板：
```markdown
## RCA 文件結構模板
### 必需章節
1. **頂部資訊表** - 建立者、時間、版本
2. **版本歷史** - 文件變更紀錄
3. **事件摘要** - 問題概述和影響
4. **調查過程** - 詳細調查步驟和發現
5. **根本原因分析** - 主要和次要原因
6. **解決方案與實施** - 具體修復措施
7. **預防措施** - 短期、中期、長期改進
8. **影響評估** - 直接和間接影響
9. **經驗教訓** - 學到的教訓和最佳實踐
10. **相關文件** - 相關參考文件
11. **簽核** - 相關人員確認
### 可選章節
- 技術細節附錄
- 測試腳本詳解
- 配置參數說明
- 監控指標定義
```
---
## 實施計畫
### 階段 1：立即實施 (1-3 天)
| 任務 | 負責人 | 預計工時 | 依賴項 |
|------|--------|----------|--------|
| 1. 創建 `docs/maintenance_records/` 目錄結構 | OpenCode | 0.5h | 無 |
| 2. 遷移現有運維文件到新目錄 | OpenCode | 1h | 任務 1 |
| 3. 更新 `DOCS_STANDARD.md` 添加新前綴 | OpenCode | 1h | 無 |
| 4. 創建 RCA 文件模板 | OpenCode | 0.5h | 無 |
### 階段 2：短期實施 (1-2 週)
| 任務 | 負責人 | 預計工時 | 依賴項 |
|------|--------|----------|--------|
| 5. 建立事件嚴重等級處理流程 | Warren | 4h | 任務 3 |
| 6. 創建事件報告模板 | Warren | 2h | 任務 3 |
| 7. 建立文件生命周期管理腳本 | OpenCode | 3h | 任務 1 |
| 8. 培訓團隊新規範 | Warren | 2h | 任務 5-6 |
### 階段 3：長期優化 (1-2 月)
| 任務 | 負責人 | 預計工時 | 依賴項 |
|------|--------|----------|--------|
| 9. 實現自動化事件追蹤 | OpenCode | 8h | 任務 7 |
| 10. 建立監控與警報集成 | OpenCode | 12h | 任務 9 |
| 11. 定期審查和優化流程 | Warren | 4h/月 | 任務 8 |
---
## 預期效益
### 管理效益
| 效益 | 說明 | 衡量指標 |
|------|------|----------|
| **快速問題定位** | 標準化文件結構便於查找 | 平均查找時間減少 50% |
| **知識傳承** | 完整紀錄便於新成員學習 | 新人上手時間減少 30% |
| **流程標準化** | 統一處理流程提高效率 | 事件處理時間減少 25% |
| **風險降低** | 系統性預防措施減少重複問題 | 重複問題發生率降低 40% |
### 技術效益
| 效益 | 說明 | 衡量指標 |
|------|------|----------|
| **文件一致性** | 統一格式提高可讀性 | 文件評分提高 (1-5 分) |
| **自動化潛力** | 結構化數據便於自動處理 | 自動化覆蓋率 70%+ |
| **分析基礎** | 標準化數據利於趨勢分析 | 月度報告生成時間減少 60% |
### 合規效益
| 效益 | 說明 | 相關標準 |
|------|------|----------|
| **審計追蹤** | 完整變更和事件紀錄 | ISO 27001, SOC 2 |
| **責任歸屬** | 清晰的人員和時間紀錄 | ITIL, COBIT |
| **風險管理** | 系統性風險識別和緩解 | NIST CSF |
---
## 風險與緩解措施
### 實施風險
| 風險 | 影響 | 概率 | 緩解措施 |
|------|------|------|----------|
| 團隊接受度低 | 新規範未被採納 | 中 | 1. 逐步實施 2. 提供培訓 3. 收集反饋 |
| 文件維護負擔 | 增加團隊工作量 | 低 | 1. 提供模板 2. 自動化工具 3. 簡化流程 |
| 遷移複雜度高 | 現有文件混亂 | 中 | 1. 分批遷移 2. 保持向後兼容 3. 工具輔助 |
### 技術風險
| 風險 | 影響 | 概率 | 緩解措施 |
|------|------|------|----------|
| 目錄結構衝突 | 現有鏈接失效 | 低 | 1. 符號鏈接 2. 重定向 3. 逐步替換 |
| 自動化工具不穩定 | 依賴新工具風險 | 中 | 1. 備用方案 2. 逐步上線 3. 充分測試 |
---
## 相關文件
| 文件 | 用途 | 位置 |
|------|------|------|
| DOCS_STANDARD.md | 現有文件規範 | `docs_v1.0/STANDARDS/DOCS_STANDARD.md` |
| RCA_WORDPRESS_*.md | RCA 文件範例 | `docs/maintenance_records/` |
| SERVICES.md | 服務管理文件 | `docs_v1.0/REFERENCE/SERVICES.md` |
---
## 審核與批准
### 審核人員
| 角色 | 姓名 | 部門 | 審核狀態 | 意見 |
|------|------|------|----------|------|
| 技術審核 (AI) | OpenCode | AI 技術部 | ✅ 技術審核通過 | 詳見審核報告 `REVIEW_DOCS_STANDARD_IMPROVEMENT_2026_03_27.md` |
| 技術負責人 | Warren | 技術部 | ⏳ 待審核 | |
| 運維負責人 | (待指定) | 運維部 | ⏳ 待審核 | |
| 文件管理員 | (待指定) | 管理部 | ⏳ 待審核 | |
### 批准流程
1. **技術審核** - 確認技術可行性和完整性
2. **運維審核** - 確認運維流程實用性
3. **管理批准** - 最終批准和資源分配
4. **實施部署** - 按照實施計畫執行
---
## 附錄
### 文件模板示例
#### RCA 文件模板 (簡化版)
```markdown
# RCA_<服務>_<問題>_<日期>.md
| 項目 | 內容 |
|------|------|
| 建立者 | |
| 建立時間 | |
| 文件版本 | V1.0 |
| 嚴重等級 | P0-P4 |
---
## 事件摘要
| 項目 | 內容 |
|------|------|
| 事件標題 | |
| 影響服務 | |
| 發現時間 | |
| 解決時間 | |
| 影響範圍 | |
---
## 根本原因分析
### 主要原因
| 原因 | 證據 | 影響 |
|------|------|------|
| | | |
### 解決方案
| 方案 | 實施步驟 | 驗證方法 |
|------|----------|----------|
| | | |
---
## 簽核
| 角色 | 簽核狀態 | 日期 |
|------|----------|------|
| 分析員 | | |
| 負責人 | | |
```
#### 事件報告模板
```markdown
# INCIDENT_<服務>_<類型>_<日期>.md
| 項目 | 內容 |
|------|------|
| 報告者 | |
| 報告時間 | |
| 嚴重等級 | P0-P4 |
| 當前狀態 | ⏳/🔍/🔧/✅ |
---
## 事件詳情
| 項目 | 內容 |
|------|------|
| 事件描述 | |
| 影響範圍 | |
| 重現步驟 | |
| 預期行為 | |
| 實際行為 | |
---
## 處理進度
| 時間 | 操作 | 人員 | 狀態 |
|------|------|------|------|
| | | | |
```
---
**提案結束** - 請審核並提供反饋