daily-news-app/user_command_log.md

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

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

---

命令索引

• 專案瘦身
• Git 版本控制
• Python 環境設定
• 應用程式執行
• Scrapy 爬蟲執行
• 資料庫操作

---

專案瘦身

清理 Python 快取檔案

# 刪除所有 __pycache__ 目錄
find . -type d -name "__pycache__" -exec rm -rf {} +

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

刪除錯誤目錄和空檔案

# 刪除錯誤建立的目錄
rm -rf "{app"

# 刪除空檔案
rm null nul

檢查目錄大小

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

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

---

Git 版本控制

初始化 Git 倉庫

# 初始化 Git
git init

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

基本 Git 操作

# 查看狀態
git status

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

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

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

提交變更

# 暫存所有變更
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
)"

遠端倉庫操作

# 檢查遠端設定
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 倉庫管理

# 使用 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 環境設定

虛擬環境管理

# 建立虛擬環境
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

套件安裝

# 安裝所有依賴（使用系統 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')"

套件管理

# 列出已安裝套件
pip list

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

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

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

---

應用程式執行

基本執行

# 使用 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

背景執行

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

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

健康檢查

# 檢查 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

環境變數設定

# 複製環境變數範例
cp .env.example .env

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

必要環境變數:

# 資料庫設定
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 爬蟲執行

基本執行

# 進入爬蟲目錄
cd hbr_crawler

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

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

測試模式

# 測試模式（不追蹤分頁）
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://..."

輸出設定

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

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

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

除錯與測試

# 顯示詳細日誌
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 專案管理

# 列出所有爬蟲
scrapy list

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

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

# 檢查專案結構
scrapy version -v

---

資料庫操作

SQLite（開發環境）

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

# 使用 SQLite 命令列
sqlite3 daily_news_app.db

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

MySQL/MariaDB

# 連線到資料庫
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 查詢

-- 查看所有表
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';

---

開發工具

程式碼格式化

# 使用 Black 格式化
black app/

# 使用 isort 排序 import
isort app/

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

測試

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

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

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

日誌查看

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

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

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

---

Docker 部署（選用）

Docker Compose

# 啟動服務
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 基本操作

# 建置映像
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'

# 確認使用正確的 Python 環境
which python
# 或 Windows:
where python

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

2. 虛擬環境套件未生效

# 確認虛擬環境已啟動
# PowerShell 提示符應該顯示 (.venv)

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

3. 資料庫連線失敗

# 測試資料庫連線
mysql -h mysql.theaken.com -P 33306 -u A101 -p

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

4. 埠號被佔用

# Windows 查看埠號佔用
netstat -ano | findstr :8000

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

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

5. Git 推送失敗

# 檢查遠端設定
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

---

快速參考

開發流程

# 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

一鍵清理與重置

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

完整部署流程

# 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              # 專案說明

---

文件結束