# 每日報導 APP - 使用者命令日誌

**文件版本**: 1.0
**建立日期**: 2024-12-04
**最後更新**: 2024-12-04
**專案名稱**: 每日報導 APP

---

## 命令索引

- [專案瘦身](#專案瘦身)
- [Git 版本控制](#git-版本控制)
- [Python 環境設定](#python-環境設定)
- [應用程式執行](#應用程式執行)
- [Scrapy 爬蟲執行](#scrapy-爬蟲執行)
- [資料庫操作](#資料庫操作)

---

## 專案瘦身

### 清理 Python 快取檔案
```bash
# 刪除所有 __pycache__ 目錄
find . -type d -name "__pycache__" -exec rm -rf {} +

# 刪除所有 .pyc 檔案
find . -type f -name "*.pyc" -delete
```

### 刪除錯誤目錄和空檔案
```bash
# 刪除錯誤建立的目錄
rm -rf "{app"

# 刪除空檔案
rm null nul
```

### 檢查目錄大小
```bash
# 查看主要目錄大小
du -sh .venv/ app/ tests/ templates/ scripts/ logs/

# 查看所有檔案大小（排序）
du -sh *.md *.html __pycache__ 2>/dev/null | sort -hr
```

---

## Git 版本控制

### 初始化 Git 倉庫
```bash
# 初始化 Git
git init

# 設定使用者資訊
git config user.name "donald"
git config user.email "donald@theaken.com"
```

### 基本 Git 操作
```bash
# 查看狀態
git status

# 查看差異
git diff
git diff <file_name>

# 查看已暫存的變更
git diff --cached <file_name>

# 查看提交記錄
git log
git log -1 --format='%an %ae'
```

### 提交變更
```bash
# 暫存所有變更
git add .
git add -A

# 提交變更
git commit -m "提交訊息"

# 使用 HEREDOC 建立多行提交訊息
git commit -m "$(cat <<'EOF'
提交標題

詳細說明內容...

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
```

### 遠端倉庫操作
```bash
# 檢查遠端設定
git remote -v

# 新增遠端倉庫（使用 Token 認證）
git remote add origin https://donald:9e0a888d1a25bde9cf2ad5dff2bb7ee6d68d6ff0@gitea.theaken.com/donald/daily-news-app.git

# 推送到遠端
git push -u origin master
git push origin master

# 合併提交與推送
git add . && git commit -m "訊息" && git push origin master
```

### Gitea 倉庫管理
```bash
# 使用 API 建立 Gitea 倉庫
curl -X POST "https://gitea.theaken.com/api/v1/user/repos" \
  -H "Authorization: token 9e0a888d1a25bde9cf2ad5dff2bb7ee6d68d6ff0" \
  -H "Content-Type: application/json" \
  -d '{"name":"daily-news-app","description":"企業內部新聞彙整與分析系統","private":false,"auto_init":false}'
```

**Gitea 連線資訊**:
- URL: https://gitea.theaken.com/
- 使用者: donald
- 密碼: !QAZ2wsx
- Token: 9e0a888d1a25bde9cf2ad5dff2bb7ee6d68d6ff0
- 倉庫: https://gitea.theaken.com/donald/daily-news-app

---

## Python 環境設定

### 虛擬環境管理
```bash
# 建立虛擬環境
python -m venv .venv

# 啟動虛擬環境 (Windows PowerShell)
.venv\Scripts\Activate.ps1

# 啟動虛擬環境 (Windows CMD)
.venv\Scripts\activate.bat

# 啟動虛擬環境 (Linux/Mac)
source .venv/bin/activate

# 檢查 Python 版本
python --version
.venv/Scripts/python.exe --version

# 檢查使用的 Python
where python
```

### 套件安裝
```bash
# 安裝所有依賴（使用系統 Python）
python -m pip install -r requirements.txt

# 安裝所有依賴（使用虛擬環境 Python）
.venv/Scripts/python.exe -m pip install -r requirements.txt

# 安裝核心套件
.venv/Scripts/python.exe -m pip install --upgrade lxml beautifulsoup4 httpx fastapi uvicorn sqlalchemy pydantic pydantic-settings python-dotenv

# 安裝其他依賴
.venv/Scripts/python.exe -m pip install pymysql cryptography alembic python-jose[cryptography] passlib[bcrypt] ldap3 google-generativeai openai apscheduler aiosmtplib weasyprint email-validator tenacity pytest pytest-asyncio black isort python-multipart

# 驗證核心套件安裝
python -c "import fastapi, uvicorn, sqlalchemy; print('Core packages installed')"
```

### 套件管理
```bash
# 列出已安裝套件
pip list

# 檢查套件版本
pip show <package_name>

# 升級 pip
python -m pip install --upgrade pip

# 匯出已安裝套件
pip freeze > requirements.txt
```

---

## 應用程式執行

### 基本執行
```bash
# 使用 run.py 啟動應用程式
python run.py

# 使用虛擬環境 Python 啟動
.venv/Scripts/python.exe run.py

# 直接使用 uvicorn 啟動
uvicorn app.main:app --reload

# 指定主機和埠號
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
```

### 背景執行
```bash
# 在背景執行（需要監控輸出）
python run.py &

# 終止背景程序
# 使用 Ctrl+C 或找到 PID 後 kill
```

### 健康檢查
```bash
# 檢查 API 健康狀態
curl http://127.0.0.1:8000/health

# 檢查 API 資訊
curl http://127.0.0.1:8000/api/info

# 開啟 API 文件
# 瀏覽器訪問: http://127.0.0.1:8000/docs
```

### 環境變數設定
```bash
# 複製環境變數範例
cp .env.example .env

# 編輯環境變數
vim .env
# 或使用其他編輯器
notepad .env
```

**必要環境變數**:
```ini
# 資料庫設定
DB_HOST=mysql.theaken.com
DB_PORT=33306
DB_NAME=db_A101
DB_USER=A101
DB_PASSWORD=Aa123456

# 應用程式設定
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-key-here
APP_ENV=development
DEBUG=True
```

---

## Scrapy 爬蟲執行

### 基本執行
```bash
# 進入爬蟲目錄
cd hbr_crawler

# 執行爬蟲（替換 <spider_name> 為實際爬蟲名稱）
scrapy crawl hbr

# 執行爬蟲（通用）
scrapy crawl <spider_name>
```

### 測試模式
```bash
# 測試模式（不追蹤分頁）
scrapy crawl <spider_name> -a test_mode=true

# 指定單一 URL
scrapy crawl <spider_name> -a start_url="https://example.com/article/123"

# 組合參數
scrapy crawl <spider_name> -a test_mode=true -a start_url="https://..."
```

### 輸出設定
```bash
# 輸出到 JSON 檔案
scrapy crawl <spider_name> -o output.json

# 輸出到 CSV 檔案
scrapy crawl <spider_name> -o output.csv

# 輸出到 XML 檔案
scrapy crawl <spider_name> -o output.xml
```

### 除錯與測試
```bash
# 顯示詳細日誌
scrapy crawl <spider_name> --loglevel=DEBUG

# 使用 Scrapy Shell 測試選擇器
scrapy shell "https://example.com/article/123"

# 在 Shell 中測試選擇器
>>> response.css('h1.articleTitle::text').get()
>>> response.css('.authorName::text').get()
>>> response.xpath('//h1/text()').get()

# 檢查 robots.txt
scrapy fetch --nolog https://example.com/robots.txt

# 測試特定頁面
scrapy parse --spider=<spider_name> https://example.com
```

### Scrapy 專案管理
```bash
# 列出所有爬蟲
scrapy list

# 檢視爬蟲設定
scrapy settings --get BOT_NAME

# 建立新爬蟲
scrapy genspider <spider_name> example.com

# 檢查專案結構
scrapy version -v
```

---

## 資料庫操作

### SQLite（開發環境）
```bash
# 初始化 SQLite 資料庫
python scripts/init_db_sqlite.py

# 使用 SQLite 命令列
sqlite3 daily_news_app.db

# SQLite 常用指令
.tables          # 列出所有表
.schema          # 查看表結構
.quit            # 退出
```

### MySQL/MariaDB
```bash
# 連線到資料庫
mysql -h mysql.theaken.com -P 33306 -u A101 -p

# 執行 SQL 檔案
mysql -h mysql.theaken.com -P 33306 -u A101 -p db_A101 < scripts/init.sql

# 備份資料庫
mysqldump -h mysql.theaken.com -P 33306 -u A101 -p db_A101 > backup.sql

# 還原資料庫
mysql -h mysql.theaken.com -P 33306 -u A101 -p db_A101 < backup.sql
```

**資料庫連線資訊**:
- 主機: mysql.theaken.com
- 埠號: 33306
- 資料庫: db_A101
- 使用者: A101
- 密碼: Aa123456

### 常用 SQL 查詢
```sql
-- 查看所有表
SHOW TABLES;

-- 查看表結構
DESCRIBE articles;
DESCRIBE tags;
DESCRIBE article_tags;

-- 查詢文章數量
SELECT COUNT(*) FROM articles;

-- 查詢最新文章
SELECT title, url, publish_date FROM articles ORDER BY publish_date DESC LIMIT 10;

-- 查詢付費文章
SELECT title, url FROM articles WHERE is_paywalled = 1;

-- 查詢特定來源的文章
SELECT COUNT(*) FROM articles WHERE source = 'Digitimes';
```

---

## 開發工具

### 程式碼格式化
```bash
# 使用 Black 格式化
black app/

# 使用 isort 排序 import
isort app/

# 組合使用
black app/ && isort app/
```

### 測試
```bash
# 執行所有測試
pytest tests/ -v

# 執行特定測試檔案
pytest tests/test_crawler.py -v

# 執行測試並顯示覆蓋率
pytest tests/ --cov=app
```

### 日誌查看
```bash
# 查看最新日誌
tail -f logs/app.log

# 查看特定行數
tail -n 100 logs/app.log

# 搜尋日誌中的錯誤
grep "ERROR" logs/app.log
```

---

## Docker 部署（選用）

### Docker Compose
```bash
# 啟動服務
docker-compose up -d

# 查看日誌
docker-compose logs -f app

# 停止服務
docker-compose down

# 重新建置並啟動
docker-compose up -d --build

# 進入容器
docker exec -it daily-news-app bash
```

### Docker 基本操作
```bash
# 建置映像
docker build -t daily-news-app .

# 執行容器
docker run -d -p 8000:8000 --name daily-news-app daily-news-app

# 查看執行中容器
docker ps

# 查看日誌
docker logs -f daily-news-app

# 停止容器
docker stop daily-news-app

# 刪除容器
docker rm daily-news-app
```

---

## 疑難排解

### 常見問題

**1. Import Error: No module named 'fastapi'**
```bash
# 確認使用正確的 Python 環境
which python
# 或 Windows:
where python

# 重新安裝依賴
.venv/Scripts/python.exe -m pip install -r requirements.txt
```

**2. 虛擬環境套件未生效**
```bash
# 確認虛擬環境已啟動
# PowerShell 提示符應該顯示 (.venv)

# 直接使用虛擬環境 Python
.venv/Scripts/python.exe run.py
```

**3. 資料庫連線失敗**
```bash
# 測試資料庫連線
mysql -h mysql.theaken.com -P 33306 -u A101 -p

# 檢查環境變數
cat .env | grep DB_
```

**4. 埠號被佔用**
```bash
# Windows 查看埠號佔用
netstat -ano | findstr :8000

# Linux/Mac 查看埠號佔用
lsof -i :8000

# 終止佔用程序（替換 <PID>）
kill <PID>
```

**5. Git 推送失敗**
```bash
# 檢查遠端設定
git remote -v

# 重新設定遠端 URL
git remote set-url origin https://donald:TOKEN@gitea.theaken.com/donald/daily-news-app.git

# 強制推送（小心使用）
git push -f origin master
```

---

## 快速參考

### 開發流程
```bash
# 1. 啟動虛擬環境
.venv\Scripts\Activate.ps1

# 2. 啟動應用程式
python run.py

# 3. 在另一個終端執行爬蟲
cd hbr_crawler
scrapy crawl hbr

# 4. 提交變更
git add .
git commit -m "更新訊息"
git push origin master
```

### 一鍵清理與重置
```bash
# 清理所有快取和臨時檔案
find . -type d -name "__pycache__" -exec rm -rf {} + && \
find . -type f -name "*.pyc" -delete && \
rm -f null nul
```

### 完整部署流程
```bash
# 1. 安裝依賴
.venv/Scripts/python.exe -m pip install -r requirements.txt

# 2. 設定環境變數
cp .env.example .env
# 編輯 .env

# 3. 初始化資料庫
python scripts/init_db_sqlite.py

# 4. 啟動應用程式
python run.py
```

---

## 附錄

### 套件版本資訊

**核心套件**:
- Python: 3.11+ (已支援 3.13)
- FastAPI: 0.109.0+
- Uvicorn: 0.27.0+
- SQLAlchemy: 2.0.44+
- Pydantic: 2.12.4+

**爬蟲套件**:
- httpx: 0.26.0+
- BeautifulSoup4: 4.12.3+
- lxml: 6.0.2+ (Python 3.13 相容)
- Scrapy: 2.11.0+ (進階爬蟲)

**其他套件**:
- WeasyPrint: 67.0+
- python-jose: 3.5.0+
- passlib: 1.7.4+
- bcrypt: 5.0.0+

### 專案結構
```
daily-news-app/
├── app/                    # 主應用程式
│   ├── api/               # API 端點
│   ├── core/              # 核心設定
│   ├── db/                # 資料庫
│   ├── models/            # 資料模型
│   ├── schemas/           # Pydantic Schema
│   ├── services/          # 商業邏輯
│   └── main.py            # 應用程式入口
├── scripts/               # 工具腳本
├── templates/             # 前端模板
├── tests/                 # 測試檔案
├── logs/                  # 日誌檔案
├── .venv/                 # 虛擬環境
├── .env                   # 環境變數（不納入版控）
├── requirements.txt       # Python 依賴
├── run.py                 # 啟動腳本
└── README.md              # 專案說明
```

---

**文件結束**