# AI Backlog Generator

[![npm version](https://badge.fury.io/js/ai-backlog.svg)](https://badge.fury.io/js/ai-backlog)
[![npm downloads](https://img.shields.io/npm/dm/ai-backlog.svg)](https://www.npmjs.com/package/ai-backlog)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

一個使用 AI 技術從會議文件自動生成 backlog 項目並直接寫入 Google Sheets 的 CLI 工具。

## 功能特色

- 📄 支援多種檔案格式：PDF、Word (.docx)、純文字檔案
- 🔗 支援 Google Docs 連結解析
- 🤖 使用 OpenAI API 智慧分析會議內容
- ⚡ 自動區分前端/後端 backlog 項目
- � 直接輸出到 Google Sheets，自動建立新工作表
- �📋 包含 Area、Iteration、MoSCoW 欄位供後續管理
- 🔍 每個 backlog 項目都能追溯到原文片段
- ⚙️ 可配置的 AI 模型和參數

## 安裝

```bash
npm install -g ai-backlog
```

或者在專案中本地安裝：

```bash
npm install ai-backlog
```

> 📖 **完整使用指南**：請參閱 [USAGE.md](./USAGE.md) 獲得詳細的安裝和使用說明

## 快速開始

### 🚀 互動式設定（推薦）

```bash
# 執行互動式配置設定精靈
ai-backlog --setup
```

這會引導您完成所有必要的設定，包括：
- OpenAI API Key
- AI 模型選擇  
- Google 憑證檔案路徑
- Google Sheets URL
- 進階選項（保留字、自訂 prompt 等）

### 手動配置

如果您偏好手動設定，首次使用時工具會建立 `ai_backlog.config.js` 配置檔案：

```javascript
module.exports = {
  // OpenAI API Key (必填)
  apiKey: process.env.OPENAI_API_KEY || '你的-openai-api-key',
  
  // Google Sheets URL (必填 - 用於輸出 backlog)
  googleSheetUrl: 'https://docs.google.com/spreadsheets/d/your-sheet-id/edit',
  
  // Google API 憑證檔案路徑 (必填)
  googleCredentials: './path/to/credentials.json',
  
  // 使用的模型
  model: 'gpt-4o', // 或 'gpt-4-turbo', 'gpt-3.5-turbo'
  
  // 保留字 - 在分析時需要特別注意的詞彙
  keepPhrases: [
    '使用者體驗',
    '效能優化',
    '安全性',
    // ... 更多保留字
  ],
  
  // AI 參數設定
  maxTokens: 4000,
  temperature: 0.1
};
```

### 環境變數設定

您也可以使用環境變數設定 API Key：

```bash
export OPENAI_API_KEY="your-openai-api-key"
```

## 使用方法

### 基本用法

```bash
# 解析本地檔案並寫入 Google Sheets
ai-backlog ./meeting-notes.pdf

# 解析 Google Docs 並寫入 Google Sheets
ai-backlog "https://docs.google.com/document/d/your-doc-id/edit"

# 使用自訂配置檔案
ai-backlog ./meeting-notes.txt -c ./custom-config.js
```

### 指令參數

```bash
# 基本使用
ai-backlog [檔案路徑或URL] [選項]

# 配置管理
ai-backlog --setup              # 互動式配置設定精靈
ai-backlog --show-config        # 顯示配置檔案位置
ai-backlog --edit-config        # 快速編輯全域配置檔案

# 自訂配置
ai-backlog input.pdf -c custom-config.js  # 使用自訂配置檔案
```

**選項說明：**
- `[input]`: 會議檔案路徑或 Google Docs 連結
- `--setup`: 執行互動式配置設定精靈（首次使用推薦）
- `--show-config`: 顯示配置檔案查找位置和狀態
- `--edit-config`: 在編輯器中開啟全域配置檔案
- `-c, --config <path>`: 指定自訂配置檔案路徑

## 支援的檔案格式

- **PDF**: `.pdf` 檔案
- **Word**: `.docx` 檔案  
- **純文字**: `.txt`, `.md` 檔案
- **Google Docs**: 透過連結存取

## 輸出格式

工具會生成包含以下結構的 JSON 檔案：

```json
[
  {
    "title": "建立使用者登入功能",
    "type": "frontend",
    "description": "開發使用者登入頁面，包含帳號密碼欄位、驗證機制和錯誤提示。",
    "acceptance_criteria": [
      "使用者輸入錯誤帳號密碼時需顯示明確的錯誤訊息",
      "成功登入後自動導向到使用者的首頁",
      "支援記住我功能，7天內免重新登入"
    ],
    "effort": 5,
    "effort_analysis": "包含 UI 設計、表單驗證、錯誤處理和狀態管理，屬於中等複雜度的功能",
    "source_text": "會議中討論需要建立使用者登入功能，要求有清楚的錯誤訊息和記住我功能",
    "ai_suggestions": "建議考慮加入雙因子認證或密碼強度檢查，以提升安全性"
  },
  {
    "title": "實作使用者認證 API",
    "type": "backend", 
    "description": "建立使用者認證相關的後端 API，包含登入驗證、JWT token 生成和驗證。",
    "acceptance_criteria": [
      "提供 POST /api/auth/login 端點進行使用者驗證",
      "成功驗證後回傳 JWT token 和使用者基本資訊",
      "實作 token 過期和刷新機制"
    ],
    "effort": 8,
    "effort_analysis": "需要設計資料庫認證邏輯、JWT 實作、安全性考量和錯誤處理，複雜度較高",
    "source_text": "需要後端 API 支援登入驗證，包含 JWT token 機制",
    "ai_suggestions": ""
  }
]
```
    "effort": 8,
    "effort_analysis": "需要實作加密、JWT 機制、資料庫查詢和安全性考量，較為複雜"
  }
]
```

### 欄位說明

- **title**: Backlog 項目標題
- **type**: 類型 (`frontend`, `backend`, `fullstack`)
- **description**: 詳細描述
- **acceptance_criteria**: 驗收條件陣列
- **effort**: 工作量評估 (費波那契數列: 1, 2, 3, 5, 8, 13, 21)
- **effort_analysis**: 工作量評估的說明

## Google Docs 整合

### 公開文件

對於公開的 Google Docs，工具會嘗試直接存取內容。

### 私人文件

對於私人文件，您需要：

1. 到 [Google Cloud Console](https://console.cloud.google.com/) 建立專案
2. 啟用 Google Docs API
3. 建立服務帳戶並下載憑證 JSON 檔案
4. 在配置檔案中設定憑證路徑：

```javascript
module.exports = {
  // ... 其他設定
  googleCredentials: './path/to/your/credentials.json'
};
```

## 開發

### 本地開發

```bash
# 複製專案
git clone <repository-url>
cd ai-backlog

# 安裝依賴
npm install

# 執行
node src/cli.js [arguments]
```

### 測試

```bash
npm test
```

## 授權

MIT License

## 貢獻

歡迎提交 Issue 和 Pull Request！

## 支援

如有問題或建議，請在 GitHub Issues 中提出。