momentry_core/docs/DOCS_STANDARD.md

# 文件創建規範

| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-18 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-18 | 創建文件規範 | Warren | OpenCode / MiniMax M2.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`

---

## 附錄：文件類型參考

| 前綴 | 用途 | 位置 |
|------|------|------|
| `INSTALL_` | 服務安裝指南 | `/docs/` |
| `DEVELOP_` | 開發指南 | `/docs/` |
| `*_SPEC.md` | 規格定義 | `/docs/` |
| `*_DESIGN.md` | 設計文件 | `/docs/` |
| `API_REFERENCE.md` | API 參考文件 | `/docs/` |
| `README.md` | 專案總覽 | `/` |
| `AGENTS.md` | AI 代理指令 | `/` |
| `CHANGELOG.md` | 變更日誌 | `/` |