Guidant AI 後端開發部署手冊¶

目的：讓新進工程師能快速設定並啟動後端服務對象：後端開發人員

1. 基本需求¶

項目	版本 / 說明
Python	3.11.x（`>=3.11,<4`）
PostgreSQL	14+（含 RLS）
Redis	6+
套件管理	Poetry ≥ 2.0
私有套件源	公司內網 Nexus（需連 VPN / 內網）

細部版本與 OS 原生依賴請見〈附錄 A〉。

2. 環境變數（.env）¶

2.1 建立¶

cp .env.sample .env

.env 已列入 .gitignore，嚴禁提交。

2.2 欄位總表¶

🔴 = 新機器必須調整　🟡 = 視情況調整　⚪ = 保持預設即可

執行環境¶

變數	說明	調整
`ENV`	執行環境；本機用 `DEVELOP_PREMISE`	⚪
`DEBUG`	本機開 `true`	⚪
`SYSTEM_NAME`	系統顯示名稱，預設 `Guidant AI`	⚪
`SYSTEM_URL`	前端位址，本機 `http://localhost:5180`	🟡

資料庫¶

變數	說明	調整
`DB_HOST`	DB 主機。共用開發機用 `192.168.50.189`	🟡
`DB_PORT`	`25432`（共用開發機）	⚪
`DB_READ_HOST`	讀取副本，未設定自動 fallback 至 `DB_HOST`	⚪
`DB_NAME`	資料庫名稱，預設 `guidant_ai_dev`	🟡
`DB_SECRET`	JSON 字串：`{ "rds_master_username": "...", "rds_master_password": "..." }`	🔴

Redis¶

變數	說明	調整
`REDIS_HOST`	共用開發機 `192.168.50.189`	🟡
`REDIS_PORT`	`6379`	⚪
`REDIS_DB`	`0`（不同工程師用不同 DB 號避免衝突）	🟡
`REDIS_SSL`	`false`	⚪
`REDIS_SECRET`	JSON：`{ "redis_user_name": "...", "redis_user_password": "..." }`	🔴

認證¶

變數	說明	調整
`JWT_SECRET`	JSON：`{ "jwt_secret": "<uuid>" }`	⚪
`TURNSTILE_SECRET_KEY`	Cloudflare Turnstile；開發用測試金鑰即可	⚪
`MFA_REQUIRED`	`true` / `false`，本機通常 `false`	⚪

檔案路徑¶

變數	說明	調整
`UPLOAD_STATIC_DIR`	相對路徑，預設 `app/static`	⚪
`UPLOAD_DIR`	相對子目錄，預設 `file/upload/issue`	⚪
`UPLOAD_FILE_DIR`	絕對路徑，必改成自己機器的實際路徑	🔴
`SCHEDULE_REPORT_DIR`	絕對路徑，排程報表輸出位置	🔴

Windows 路徑用 C:/Users/xxx/...（斜線）或 C:\\Users\\xxx\\...（雙反斜線）。

其他（選用）¶

變數	說明	調整
`CAMUNDA_REST_URL`	工作流引擎，沒用到可留預設	⚪
`SEND_NOTIFY_MODULES`	`MAIL,DISCORD,TELEGRAM` 逗號分隔	🟡
`TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID`	Telegram 通知	🟡
`DISCORD_WEBHOOK_URL`	Discord 通知	🟡
`UPLOAD_STORAGE_TYPE`	`LOCAL` 或 `MINIO`	🟡
`MINIO_*`	用 MINIO 時才需要	🟡
`ENABLE_MULTI_TENANT`	多租戶啟用旗標，預設 `true`	⚪
`OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GOOGLE_API_KEY`	AI Dashboard 功能才需要，`.env.sample` 是 placeholder 需自行填入	🟡

2.3 最少必改清單¶

新機器首次設定，至少要改這幾個才能啟動：

DB_SECRET={ "rds_master_username": "<帳號>", "rds_master_password": "<密碼>" }
REDIS_SECRET={ "redis_user_name": "<帳號>", "redis_user_password": "<密碼>" }
UPLOAD_FILE_DIR=/your/abs/path/to/compliance-manager-be/app/static/file/upload
SCHEDULE_REPORT_DIR=/your/abs/path/to/reports/

DB / Redis 帳密向團隊索取。

2.4 另一個 .env.test¶

跑 pytest 會讀 .env.test（連測試 DB guidant_ai_test，避免污染開發資料）。平常啟動後端不用動它。

3. Poetry¶

3.1 是什麼¶

Poetry 是 Python 的套件 + 虛擬環境管理工具（類似 Node 的 npm）。本專案用它： - 管理依賴（pyproject.toml + poetry.lock） - 自動建立 .venv/ - 從公司內網 Nexus 下載 jedi-* 內部套件

3.2 安裝 Poetry¶

# macOS / Linux
curl -sSL https://install.python-poetry.org | python3 -

# Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

驗證：

poetry --version   # 需 ≥ 2.0

3.3 常用指令¶

目的	指令
安裝 / 還原依賴	`poetry install`
新增套件	`poetry add <pkg>`
新增指定版本	`poetry add jedi-oscal@0.0.11`
移除套件	`poetry remove <pkg>`
更新單一套件	`poetry update <pkg>`
執行指令（免啟 venv）	`poetry run <cmd>`
啟用 shell	`source .venv/bin/activate`

3.4 首次設定¶

git clone <repo-url> compliance-manager-be
cd compliance-manager-be

# 安裝所有依賴（包含 jedi-* 內部套件）
poetry install

# 建 .env（欄位說明見第 2 章）
cp .env.sample .env

.venv/ 由 Poetry 自動在專案內建立（poetry.toml 已設 virtualenvs.in-project = true）。環境壞掉時用 rm -rf .venv && poetry install 重建即可。

4. 啟動服務¶

預設 port 8000。啟動後開啟 http://localhost:8000/swagger-ui/ 可看到 API 文件。

4.1 啟動主程式（`main_app.py`）¶

一般開發用這個就夠了：

poetry run python main_app.py

4.2 啟動成功檢查¶

Log 出現 Load module from api: api.<module>
瀏覽器打得開 http://localhost:8000/swagger-ui/

4.3 Socket 版本（附屬，非必要）¶

只有當開發 / 測試 WebSocket 相關功能（例如問卷協同編輯）時才需要啟動：

poetry run python main_socketio.py

一般開發不需要跑這個，跑 main_app.py 即可。兩者擇一啟動，不能同時跑在同一個 port。

4.4 直接用 .venv 執行（免 `poetry run`）¶

Poetry 已把虛擬環境建在 .venv/，可直接呼叫裡面的 Python：

方式 A：啟用 venv 後執行

# macOS / Linux
source .venv/bin/activate
python main_app.py

# Windows (PowerShell)
.venv\Scripts\Activate.ps1
python main_app.py

方式 B：直接指定 .venv 的 Python（免啟用）

# macOS / Linux
./.venv/bin/python main_app.py

# Windows
.\.venv\Scripts\python.exe main_app.py

方式 B 最適合寫成 script 或 IDE 的 run config，不用每次 activate。要跑 Socket 版本時，把 main_app.py 換成 main_socketio.py 即可。

4.5 IDE 執行設定¶

PyCharm¶

Interpreter：Preferences → Project → Python Interpreter → 齒輪 → Add Interpreter → Existing → 選 <專案>/.venv/bin/python（Windows：.venv\Scripts\python.exe）
Run Config：Run/Debug Configurations → + → Python
Script path：main_app.py（需 WebSocket 時改 main_socketio.py）
Working directory：專案根目錄
環境變數：裝 EnvFile plugin → Run Config 的 EnvFile 頁籤 → 勾 Enable EnvFile → 加入 .env

VSCode¶

Interpreter：Cmd/Ctrl + Shift + P → Python: Select Interpreter → 選 .venv 裡的那個

.vscode/launch.json（主用 App，附 Socket 版本供切換）：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "App (main)",
      "type": "debugpy",
      "request": "launch",
      "program": "${workspaceFolder}/main_app.py",
      "cwd": "${workspaceFolder}",
      "envFile": "${workspaceFolder}/.env",
      "console": "integratedTerminal",
      "justMyCode": false
    },
    {
      "name": "SocketIO (WebSocket only)",
      "type": "debugpy",
      "request": "launch",
      "program": "${workspaceFolder}/main_socketio.py",
      "cwd": "${workspaceFolder}",
      "envFile": "${workspaceFolder}/.env",
      "console": "integratedTerminal",
      "justMyCode": false
    }
  ]
}

建議 extensions：Python、Pylance、Even Better TOML

4.6 i18n 編譯（首次或修改 .po 後必做）¶

poetry run pybabel compile -d app/translations

附錄¶

附錄 A：技術棧總覽¶

類別	技術	版本
語言	Python	3.11（`>=3.11,<4`）
套件管理	Poetry	≥ 2.0
Web Framework	Flask	3.1.0
REST 擴充	flask-restful / flask-apispec	0.3.10+ / 0.11.4
WebSocket	Flask-SocketIO + eventlet	5.3.6 / 0.36.1
ORM	SQLAlchemy	2.0.37
DB Driver	psycopg / psycopg-binary	3.2.4
DB	PostgreSQL（已啟用 RLS）	14+
Cache / PubSub	Redis	6+
DI	dependency-injector	4.48.1
Auth	Flask-JWT-Extended	4.7.1
Schema / Serialization	marshmallow / flask-marshmallow	3.23.2 / 1.2.1
i18n	flask-babel / babel	4.0+ / 2.17+
設定載入	python-dotenv	1.0.1

附錄 B：專案架構（DDD 分層）¶

compliance-manager-be/
├── core/            # Flask extensions、app factory
├── api/             # HTTP Route（只做邊界，不碰 DB）
├── app/             # Application Service（@transaction，編排業務）
├── domain/          # Entity / Repository Interface / Domain Service
├── infra/           # SQLAlchemy Model / Repository 實作
├── di_containers/   # 依賴注入容器
├── common/          # 共用 middleware / util / error code
├── config/          # 環境設定、模組註冊、DI 掃描
├── main_app.py      # 主要入口（一般 REST）
└── main_socketio.py # 附屬入口（含 WebSocket）

層級	可做	不可做
`api/`	解析 request、呼叫 app service、序列化 response	查 DB、import ORM model
`app/`	編排業務、`@transaction` 管 session	直接 import ORM model 查 DB
`domain/`	定義 repository interface、領域服務	依賴 infra 層
`infra/`	使用 ORM model、SQLAlchemy query	—

完整規範見 CLAUDE.md。

附錄 C：核心功能套件¶

C.1 公司內部 `jedi-*` 套件¶

從公司 Nexus 安裝，提供跨專案共用的業務能力：

套件	用途
`jedi-common`	通用工具、session / auth context、error handler、基礎 Model
`jedi-auth`	認證授權（JWT、使用者、組織、租戶）
`jedi-login`	登入流程
`jedi-mfa`	多因子認證
`jedi-captcha`	圖形驗證
`jedi-oscal`	OSCAL 合規框架（Catalog / Profile / SSP / AP / AR / POA&M）
`jedi-project`	專案管理基礎
`jedi-flow-engine`	工作流引擎
`jedi-survey`	問卷（Folder / Survey / Page / Question + 版本 + i18n）
`jedi-bulletin`	公告
`jedi-notification`	通知派送
`jedi-issue`	問題 / 工單
`jedi-file-upload`	檔案上傳（本地 / MinIO）
`jedi-resource-store`	資源儲存抽象
`jedi-device`	裝置管理
`jedi-log`	日誌
`jedi-system-menu`	系統選單
`jedi-system-config`	系統設定

C.2 文件 / 檔案處理¶

套件	用途
`weasyprint`	HTML → PDF（需 pango / cairo 原生依賴）
`pymupdf` / `pdfplumber`	PDF 解析
`pytesseract`	OCR（需 tesseract 原生依賴）
`Pillow`	影像處理
`lxml` / `xmltodict`	XML 處理
`pandas`	表格資料處理

C.3 AI 整合¶

套件	用途
`openai`	OpenAI API
`anthropic`	Anthropic Claude API
`google-generativeai`	Google Gemini API

C.4 其他¶

套件	用途
`pyotp` / `qrcode`	TOTP / 二維碼（MFA 相關）
`python-gitlab` / `PyGithub`	Git 平台整合
`ldap3`	LDAP 認證
`pydantic`	資料驗證
`pyyaml`	YAML 解析

C.5 測試¶

套件	用途
`pytest`	測試框架
`pytest-html` / `allure-pytest`	測試報表
`testcontainers`	整合測試用容器（DB / Redis）

完整套件清單見 pyproject.toml。

附錄 D：Flask Extensions¶

所有 Flask extension 集中於 core/extensions.py：

from core.extensions import jwt, socketio, docs, redis_client, logger

Extension	用途
`jwt`	JWT 驗證（Flask-JWT-Extended）
`socketio`	WebSocket（Flask-SocketIO，僅 `main_socketio.py` 啟用）
`docs`	Swagger UI / apispec
`redis_client`	Redis 連線
`logger`	統一 logger