第一部分：步驟大綱 (Outline)
環境準備 (WSL2 & Docker)
確認 WSL2 Ubuntu 環境。
配置 Docker Compose 以運行 SQL Server (作為資料庫) 和未來的 Seq (日誌) 或其他服務。
建立專案根目錄。
後端專案建置 (.NET 9 WebAPI)
使用 .NET CLI 建立 Solution 與 WebAPI 專案。
加入必要的 Nuget 套件 (EF Core, SQL Server)。
配置
appsettings.json連接 Docker 中的資料庫。建立 Dockerfile (後端)。
前端專案建置 (React + Vite + Tailwind)
使用 npm (create-vite) 建立前端專案。
初始化 Tailwind CSS 與 shadcn/ui (UI 元件庫)。
配置
vite.config.ts設定 Proxy (解決開發跨域問題)。建立 Dockerfile (前端)。
整合與啟動 (Docker Compose)
編寫
docker-compose.yml整合 DB、Backend、Frontend。啟動服務並驗證連線。
第二部分：資料夾結構圖 (Folder Structure)
您執行完所有步驟後，您的專案結構 ~/projects/stock-system 將會長這樣：
stock-system/ # [專案根目錄]
├── docker-compose.yml # [核心] 定義 DB, Backend, Frontend 如何一起啟動
├── .env # [設定] 存放資料庫密碼等環境變數
├── backend/ # [.NET WebAPI 後端目錄]
│ ├── StockSystem.sln # Solution 檔案
│ ├── StockSystem.Api/ # 主 API 專案
│ │ ├── Dockerfile # 後端映像檔定義
│ │ ├── Program.cs # 程式進入點
│ │ ├── Controllers/ # API 接口
│ │ └── appsettings.json # DB 連線字串設定
│ └── StockSystem.Core/ # (選用) 放置純邏輯或 DTO
├── frontend/ # [React 前端目錄]
│ ├── Dockerfile # 前端映像檔定義 (通常是 Nginx 用於 Production)
│ ├── package.json
│ ├── vite.config.ts # 前端設定 (含 Proxy)
│ ├── src/
│ │ ├── App.tsx
│ │ ├── main.tsx
│ │ └── components/ # UI 元件
│ └── index.html
└── data/ # [自動生成] SQL Server 的資料掛載目錄 (不進版控)
第三部分：詳細指令與檢核機制
執行環境說明：
所有指令請在 WSL2 (Ubuntu) 的終端機中執行。
請確保您已安裝
.NET 9 SDK和Node.js (v20+)在 WSL2 中 (非 Windows Host)。您目前的目錄假設為使用者家目錄
~。
步驟 0: 安裝 .NET 9 SDK 和 Node.js
安裝 Node.js (v20+) 使用 NVM
使用 NVM (Node Version Manager) 是開發者的最佳實踐，因為它允許您在不需要 sudo 的情況下安裝全域套件，且方便切換版本。
3.1 下載並安裝 NVM
執行位置：
~(家目錄)指令意圖：從 GitHub 下載 NVM 安裝腳本並執行。
curl -C - -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
參數說明：
curl: 傳輸工具。-C -: (續載參數) 自動從上次中斷處繼續下載。-o-: 將下載內容直接輸出到標準輸出 (stdout)，以便後面的| bash執行。| bash: 將下載的腳本內容傳遞給 bash 執行。
3.2 啟用 NVM 環境變數
安裝完後，需要重新載入設定檔才能使用 nvm 指令。
執行位置：
~(家目錄)指令意圖：重新讀取
.bashrc設定檔，使 NVM 立即生效。
source ~/.bashrc
(註：若您使用 zsh，請執行 source ~/.zshrc)
3.3 安裝 Node.js v20 (LTS)
執行位置：
~(家目錄)指令意圖：安裝 Node.js 第 20 版 (長期支援版本)。
nvm install 20
參數說明：
install 20: 下載並安裝 v20 系列的最新版本 (例如 v20.11.0)。安裝後會自動設為預設使用版本。
檢核機制： 分別檢查 Node 與 NPM 的版本。
Bashnode -v && npm -v預期輸出範例：
v20.x.x10.x.x(對應的 npm 版本)
安裝 .NET 9 SDK
請在 backend 資料夾或回到家目錄執行皆可。
步驟 1：下載並執行安裝腳本
執行位置：目前的目錄
指令意圖：下載微軟官方腳本，賦予執行權限，並要求它安裝 .NET 9 通道 (Channel) 的最新版。
Bashwget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
chmod +x ./dotnet-install.sh
./dotnet-install.sh --channel 9.0
參數說明：
wget ... -O ...: 下載並存檔為 dotnet-install.sh。
chmod +x: 讓腳本變成可執行檔。
--channel 9.0: 指示腳本去抓取 9.0 系列的最新穩定版 (STS)。
執行後預期結果：螢幕會跑一段下載進度條，最後顯示 Installation finished successfully.。
執行位置：目前的目錄
指令意圖：下載微軟官方腳本，賦予執行權限，並要求它安裝 .NET 9 通道 (Channel) 的最新版。
wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
chmod +x ./dotnet-install.sh
./dotnet-install.sh --channel 9.0
參數說明：
wget ... -O ...: 下載並存檔為dotnet-install.sh。chmod +x: 讓腳本變成可執行檔。--channel 9.0: 指示腳本去抓取 9.0 系列的最新穩定版 (STS)。
執行後預期結果：螢幕會跑一段下載進度條，最後顯示 Installation finished successfully.。
步驟 2：設定環境變數 (關鍵步驟)
因為是手動安裝，終端機目前還不知道 dotnet 指令在哪裡，我們需要把它加到 .bashrc。
執行位置：任何位置
指令意圖：將 .NET 的路徑寫入您的個人設定檔，並立即載入。
echo 'export DOTNET_ROOT=$HOME/.dotnet' >> ~/.bashrc
echo 'export PATH=$PATH:$HOME/.dotnet:$HOME/.dotnet/tools' >> ~/.bashrc
source ~/.bashrc
參數說明：
echo '...' >> ~/.bashrc: 將引號內的文字「附加」到檔案最後一行。DOTNET_ROOT: 告訴依賴 .NET 的工具 (如 IDE) 核心檔案在哪。PATH: 告訴終端機去哪裡找dotnet這個指令。
步驟 3：最終檢核
現在 Node.js 和 .NET 9 應該都好了。
指令意圖：一次檢查兩個環境。
node -v && dotnet --version
預期輸出：
Plaintextv20.19.6 9.0.101 (或類似的 9.0.x 版本號)
步驟 1: 專案初始化與資料庫環境
檢核機制：
指令：
docker ps預期結果：看到
stock-db狀態為Up。指令：
docker logs stock-db預期結果：看到日誌最後顯示 "SQL Server is now ready for client connections"。
步驟 2: 建置 .NET 9 WebAPI 後端
意圖： 建立 C# 後端專案，安裝 EF Core，並測試 API 能否運行。
# 1. 建立後端目錄並進入
mkdir backend
cd backend
# 2. 建立 Solution 和 WebAPI 專案
# 參數: -n 指定名稱, -o 指定輸出目錄
dotnet new sln -n StockSystem
dotnet new webapi -n StockSystem.Api -o StockSystem.Api
dotnet sln add StockSystem.Api/StockSystem.Api.csproj
# 3. 進入 API 專案目錄安裝套件
cd StockSystem.Api
# 意圖: 安裝 EF Core SQL Server 驅動與工具
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.EntityFrameworkCore.Tools# 安裝 CORS 套件 (避免瀏覽器擋住前端連線)
dotnet add package Microsoft.AspNetCore.Cors
# 4. 設定 HTTPS 開發憑證 (讓瀏覽器信任 Localhost)
dotnet dev-certs https --trust
# 5. 回到 backend 根目錄試跑
cd ..
# 參數: --project 指定執行的專案
dotnet run --project StockSystem.Api/StockSystem.Api.csproj --urls "http://localhost:5000"
檢核機制：
指令：(保持上述指令執行，開啟新的 WSL 終端機)
curl http://localhost:5000/weatherforecast預期結果：看到回傳一串 JSON 天氣資料。
(檢核完畢後可在原視窗按
Ctrl+C停止後端)
步驟 3: 建置 React + Vite 前端
意圖： 建立現代化前端，並配置 Proxy 以便呼叫後端 API。
# 1. 回到專案根目錄
cd ~/projects/stock-system
# 2. 建立前端專案 (使用 Vite 樣板)
# 參數: frontend 是目錄名, --template react-ts 表示使用 React + TypeScript
npm create vite@latest frontend -- --template react-ts
# 3. 進入目錄並安裝依賴
cd frontend
npm install
# 4. 安裝 Tailwind CSS (現代化樣式)# 讓您的開發最順暢，且讓 Cursor (AI) 能準確生成程式碼，# 強烈建議強制使用 Tailwind CSS v3。# 目前的 AI 模型對 v3 的支援度是最完美的，v4 的設定方式變動太大，AI 容易寫錯。
npm install -D tailwindcss@3.4.17 postcss autoprefixer
npx tailwindcss init -p
# 5. 修改 tailwind.config.js (讓 Tailwind 掃描檔案)
# 意圖: 覆蓋設定檔，指定 content 路徑
cat <<EOF > tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
content: [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
],
theme: {
extend: {},
},
plugins: [],
}
EOF
# 6. 在 src/index.css 加入 Tailwind 指令
echo "@tailwind base; @tailwind components; @tailwind utilities;" > src/index.css
# 7. 設定 Vite Proxy (關鍵步驟：讓前端開發時能連到後端)
# 意圖: 修改 vite.config.ts，將 /api 開頭的請求轉發到 http://localhost:5000
cat <<EOF > vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
// https://vitejs.dev/config/
export default defineConfig({
plugins: [react()],
server: {
proxy: {
'/api': {
target: 'http://localhost:5000',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
}
}
}
})
EOF
檢核機制：
指令：
npm run dev預期結果：看到 "Local: http://localhost:5173/"。
開啟 Windows 瀏覽器訪問
http://localhost:5173，應看到 Vite + React 預設畫面。
步驟 4: 整合啟動 (開發模式)
意圖： 現在您有資料庫 (Docker)、後端 (C#)、前端 (Node.js)。在開發階段，我們通常手動啟動前後端，資料庫常駐 Docker。
啟動順序：
Terminal 1 (WSL): 確保資料庫活著
docker compose up -d dbTerminal 2 (WSL): 啟動後端
Bashcd ~/projects/stock-system/backend dotnet watch --project StockSystem.Api/StockSystem.Api.csproj --urls "http://localhost:5000"(說明:
dotnet watch支援熱重載，改 C# code 會自動重啟)Terminal 3 (WSL): 啟動前端
Bashcd ~/projects/stock-system/frontend npm run dev
Cursor 開發設定 (下一步)：
現在您可以用 Cursor 打開
~/projects/stock-system資料夾。提示 Cursor (使用 Qwen3-Coder): 「這是我的專案結構，Backend 是 .NET 9 WebAPI，Frontend 是 React+Vite。請幫我修改 Backend 的 Program.cs 來連線 Docker 中的 SQL Server...」
新專案的 docker-compose.yml (股票系統)
在您的新專案資料夾 (~/projects/stock-system) 中，建立一個新的 compose 檔。這個檔案只包含股票系統的服務，並掛載到上面的 shared_ai_network。
# ~/projects/stock-system/docker-compose.yml
services:
# 1. .NET Backend
backend:
build: ./backend
container_name: stock_api
ports:
- "5000:8080"
environment:
# 直接使用現有 SQL Server 的 container_name
- ConnectionStrings__DefaultConnection=Server=sql_srv;Database=StockDB;User Id=sa;Password=${SQL_PASSWORD};TrustServerCertificate=True;
# 連線到現有的 SGLang 用於財報分析
- AI_SERVICE_URL=http://sglang_srv:30000/v1
networks:
- stock_net # 內部網路
- shared_ai_network # [關鍵] 連線到外部的 AI 基礎設施
# 2. React Frontend (開發時可用 Node，正式部署用 Nginx)
frontend:
build: ./frontend
container_name: stock_web
ports:
- "5173:5173" # Vite 開發埠
environment:
- VITE_API_URL=http://localhost:5000
networks:
- stock_net
networks:
stock_net:
driver: bridge
# 定義外部網路，讓這個專案能抓到 sql_srv 和 sglang_srv
shared_ai_network:
external: true
這樣做如何達成您的需求？
關於 SQL Server:
不用開新容器。 您的 .NET Backend 透過 shared_ai_network 直接連線到 sql_srv。
資料隔離： 您只需要在現有的 SQL Server 中 CREATE DATABASE StockDB，這與其他資料庫（如果有）是分開的。
關於 AI 財報分析 (SGLang):
不用重複下載模型。
您的 .NET Backend 程式碼中，會使用 Semantic Kernel 或 HttpClient 發送請求給 http://sglang_srv:30000/v1。
因為都在 Docker 網路內，速度極快 (vibe coding 體驗)。
關於 Nginx:
在開發階段（目前），其實不需要 Nginx。直接用 npm run dev (Vite) 的容器即可。
等您要「正式發布」這套系統給自己長期使用時，才將前端 build 成靜態檔放入 Nginx 容器。
關於 SQL Server:
不用開新容器。 您的 .NET Backend 透過
shared_ai_network直接連線到sql_srv。資料隔離： 您只需要在現有的 SQL Server 中
CREATE DATABASE StockDB，這與其他資料庫（如果有）是分開的。
關於 AI 財報分析 (SGLang):
不用重複下載模型。
您的 .NET Backend 程式碼中，會使用
Semantic Kernel或HttpClient發送請求給http://sglang_srv:30000/v1。因為都在 Docker 網路內，速度極快 (vibe coding 體驗)。
關於 Nginx:
在開發階段（目前），其實不需要 Nginx。直接用
npm run dev(Vite) 的容器即可。等您要「正式發布」這套系統給自己長期使用時，才將前端 build 成靜態檔放入 Nginx 容器。
.env 只需要存 SQL_PASSWORD (跟原本的一樣) 即可。把程式碼版控起來，是開發系統最重要的一步。
由於您的 GitLab 是架設在本地 Docker (http://localhost:8929)，我們可以直接透過 HTTP 協定將 WSL 裡的程式碼推上去。
請依照以下三個步驟操作：
第一步：在 GitLab 網頁上建立「空專案」
開啟瀏覽器，進入您的 GitLab：
http://localhost:8929(登入帳號通常是
root，密碼是您當初設定的，或者是您後來建立的帳號)
點選 New Project (或右上角的
+號 -> New project/repository)。選擇 Create blank project。
填寫資訊：
Project name:
stock-systemProject URL: 保持預設 (通常是您的帳號名)。
Visibility: Private 或 Internal 皆可。
重要： 取消勾選 "Initialize repository with a README" (因為我們本地已經有檔案了)。
按下 Create project。
第二步：設定 .gitignore (非常關鍵！)
在把程式碼推上去之前，我們必須告訴 Git 忽略 那些暫存檔 (如 node_modules, bin, obj)，否則您的 Git 倉庫會變得巨大且混亂。
請在 WSL 終端機 (~/projects/stock-system 目錄下) 執行以下指令，這會自動產生一個針對 C# 和 React 的忽略清單：
# 確保在專案根目錄
cd ~/projects/stock-system
# 建立 .gitignore 檔案，排除不必要的暫存檔
cat <<EOF > .gitignore
# --- Cursor / VS Code ---
.vscode/
.idea/
*.code-workspace
# --- OS ---
.DS_Store
Thumbs.db
# --- Node.js (Frontend) ---
frontend/node_modules/
frontend/dist/
frontend/.env
frontend/.env.local
frontend/npm-debug.log*
frontend/yarn-debug.log*
frontend/yarn-error.log*
# --- .NET (Backend) ---
backend/bin/
backend/obj/
backend/.vs/
backend/Properties/launchSettings.json
*.user
[Dd]ebug/
[Rr]elease/
appsettings.Development.json
EOF
注意： 我沒有把
.env加入忽略，因為這是您本地的練習環境。但如果是正式專案，建議把含有密碼的.env也加入.gitignore。
第三步：初始化 Git 並推送到 GitLab
請在 WSL 終端機 繼續執行：
# 1. 初始化 Git 倉庫
git init
1. 設定 Git 作者身分 (請依喜好修改引號內內容)
Bash# 設定您的名字 (會顯示在 GitLab 的提交歷史中)
git config --global user.name "Frankie"
# 設定您的 Email (建議設定成跟您 GitLab 帳號相同的 Email，這樣頭像才會正確顯示)
git config --global user.email "frankie@example.com"
說明： --global 表示這台 WSL 所有的專案都預設使用這個身分。
# 2. 將所有檔案加入暫存區 (這時候會自動套用 .gitignore)
git add .
# 3. 提交第一次版本
git commit -m "Initial commit: React Frontend + .NET 9 Backend setup"
# 4. 設定分支名稱為 main (現在標準都用 main 而非 master)
git branch -M main
# 5. 加入遠端倉庫 (請將 <您的帳號> 替換成您的 GitLab 帳號，通常是 root)
# 如果您不確定，看瀏覽器網址列，例如 http://localhost:8929/root/stock-system
git remote add origin http://localhost:8929/root/stock-system.git
# 6. 推送上去
git push -u origin main
🔐 關於驗證 (如果跳出輸入帳密)
當您執行 git push 時，它會要求輸入 Username 和 Password：
Username: 輸入您的 GitLab 帳號 (例如
root)。Password:
您可以輸入您的 登入密碼。
或者，因為您之前提過有 GitLab PAT (Personal Access Token)，這裡直接貼上那個
glpat-...開頭的 Token 也是最安全的方式。
請切換到 Cursor 視窗：
確認 Cursor 開啟的是
stock-system資料夾。按下
Ctrl + I(Composer) 開啟對話框。複製貼上 下面這段提示詞，讓 AI 幫您把「空殼」變成「股票系統」：
我已完成專案初始化，現在要開始開發功能。
環境資訊：
Frontend: React + Vite + Tailwind CSS v3 (已啟動於 port 5173)。
Backend: .NET 9 WebAPI (已啟動於 port 5000)。
Database: SQL Server 2022 (Docker container:
sql_srv, port 1433, sa密碼:7788@7788)。任務 1 - 後端基礎建設：
請修改
Program.cs，註冊 SQL Server DbContext，並設定 CORS 允許http://localhost:5173。建立
Data/AppDbContext.cs和Models/Stock.cs(欄位: Id, Symbol, Name, Price, ChangePercentage)。請提供我「執行 Migration」的終端機指令，我要建立資料庫。
任務 2 - API 開發：
建立
StocksController，實作 GET (列表) 和 POST (新增) 功能。任務 3 - 前端串接：
修改
App.tsx，用 Tailwind 畫一個深色模式的股票表格。使用
fetch('/api/stocks')抓取資料並顯示。請一步步執行，先從「任務 1」開始寫程式碼。
複製貼上給 Cursor 的提示詞 (Prompt)：
我正在開發一個股票投資紀錄系統。
目前的專案結構：
Backend: .NET 9 WebAPI (位於
/backend)，已安裝 EF Core SQL Server。Frontend: React + Vite + TypeScript + Tailwind CSS (位於
/frontend)。Database: Docker 運行的 SQL Server 2022 (連線字串在 appsettings.json，密碼是
7788@7788)。請幫我完成以下「第一階段開發」任務：
後端 (C#):
在
StockSystem.Api中建立一個StockEntity (欄位包含：Id, Symbol(代號), Name(名稱), Exchange(交易所), CurrentPrice(現價))。設定 EF Core 的
AppDbContext並在Program.cs中註冊 SQL Server 連線。執行 Migration 建立資料表 (請告訴我需要執行的指令)。
建立
StocksController提供基本的 CRUD API。前端 (React):
在
App.tsx中建立一個簡單的介面。使用
fetch呼叫/api/stocks(Vite Proxy 已設定好指向後端)。用 Tailwind CSS 畫一個現代化的表格顯示股票清單。
增加一個「新增股票」的按鈕與表單。
請一步步引導我，先從後端設定與 Migration 開始。
