donald/daily-news-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive user command log documentation

Browse Source 
新增完整的使用者命令日誌文件

包含內容：
- 專案瘦身命令
- Git 版本控制操作
- Python 環境設定
- 應用程式執行
- Scrapy 爬蟲執行
- 資料庫操作
- 開發工具使用
- Docker 部署（選用）
- 疑難排解指南
- 快速參考

特色：
- 分類清楚的命令索引
- 實際可執行的命令範例
- Gitea 和資料庫連線資訊
- 常見問題解決方案
- 完整的開發流程參考
- 套件版本資訊

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
donald
2025-12-04 13:03:20 +08:00
parent 7719919dc7
commit 60b00c9568
1 changed files with 636 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

636
user_command_log.md Normal file
View File

@@ -0,0 +1,636 @@
# 每日報導 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 # 專案說明
```
---
**文件結束**