法蘭雞的學習筆記: AI 實作股票系統

第一部分：步驟大綱 (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 將會長這樣：

Plaintext

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 安裝腳本並執行。

Bash

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 立即生效。

Bash

source ~/.bashrc

(註：若您使用 zsh，請執行 source ~/.zshrc)

3.3 安裝 Node.js v20 (LTS)

執行位置：~ (家目錄)
指令意圖：安裝 Node.js 第 20 版 (長期支援版本)。

Bash

nvm install 20

參數說明：
- install 20: 下載並安裝 v20 系列的最新版本 (例如 v20.11.0)。安裝後會自動設為預設使用版本。
檢核機制：分別檢查 Node 與 NPM 的版本。
Bash
node -v && npm -v
預期輸出範例： v20.x.x 10.x.x (對應的 npm 版本)

安裝 .NET 9 SDK

請在 `backend` 資料夾或回到家目錄執行皆可。

步驟 1：下載並執行安裝腳本

執行位置：目前的目錄
指令意圖：下載微軟官方腳本，賦予執行權限，並要求它安裝 .NET 9 通道 (Channel) 的最新版。

Bash

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 的路徑寫入您的個人設定檔，並立即載入。

Bash
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 應該都好了。

指令意圖：一次檢查兩個環境。

Bash

node -v && dotnet --version

預期輸出：

Plaintext

v20.19.6
9.0.101 (或類似的 9.0.x 版本號)

步驟 1: 專案初始化與資料庫環境

意圖： 建立專案資料夾，並透過 Docker 啟動 SQL Server，確保資料庫就緒。

使用原本 ai-workspace 裡面的 SQL Server

# 現有的 docker-compose.yml (無需大改)

networks:

ai_mesh:

driver: bridge

name: shared_ai_network # [建議新增] 明確指定網路名稱，方便別人連進來

檢核機制：

指令：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 能否運行。

Bash
# 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。

Bash
# 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 db
- Terminal 2 (WSL): 啟動後端
  Bash
  cd ~/projects/stock-system/backend dotnet watch --project StockSystem.Api/StockSystem.Api.csproj --urls "http://localhost:5000"
  (說明: dotnet watch 支援熱重載，改 C# code 會自動重啟)
- Terminal 3 (WSL): 啟動前端
  Bash
  cd ~/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。

YAML
# ~/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 容器。

環境變數 (.env): 新專案的 .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-system
- Project URL: 保持預設 (通常是您的帳號名)。
- Visibility: Private 或 Internal 皆可。
- 重要： 取消勾選 "Initialize repository with a README" (因為我們本地已經有檔案了)。
按下 Create project。

第二步：設定 `.gitignore` (非常關鍵！)

在把程式碼推上去之前，我們必須告訴 Git 忽略那些暫存檔 (如 node_modules, bin, obj)，否則您的 Git 倉庫會變得巨大且混亂。

請在 WSL 終端機 (~/projects/stock-system 目錄下) 執行以下指令，這會自動產生一個針對 C# 和 React 的忽略清單：

Bash
# 確保在專案根目錄
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 終端機 繼續執行：

Bash

# 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 中建立一個 Stock Entity (欄位包含：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 開始。

法蘭雞的學習筆記

2026年1月12日星期一

AI 實作股票系統 - 環境建置

第一部分：步驟大綱 (Outline)

第二部分：資料夾結構圖 (Folder Structure)

第三部分：詳細指令與檢核機制

步驟 0: 安裝 .NET 9 SDK 和 Node.js

安裝 Node.js (v20+) 使用 NVM

安裝 .NET 9 SDK

請在 `backend` 資料夾或回到家目錄執行皆可。

步驟 1：下載並執行安裝腳本

步驟 2：設定環境變數 (關鍵步驟)

步驟 3：最終檢核

現在 Node.js 和 .NET 9 應該都好了。
指令意圖：一次檢查兩個環境。
Bash
`node -v && dotnet --version`
預期輸出：
Plaintext
`v20.19.6 9.0.101 (或類似的 9.0.x 版本號)`

步驟 1: 專案初始化與資料庫環境

步驟 2: 建置 .NET 9 WebAPI 後端

步驟 3: 建置 React + Vite 前端

步驟 4: 整合啟動 (開發模式)

新專案的 `docker-compose.yml` (股票系統)

這樣做如何達成您的需求？

第一步：在 GitLab 網頁上建立「空專案」

第二步：設定 `.gitignore` (非常關鍵！)

第三步：初始化 Git 並推送到 GitLab

1. 設定 Git 作者身分 (請依喜好修改引號內內容)

🔐 關於驗證 (如果跳出輸入帳密)

複製貼上給 Cursor 的提示詞 (Prompt)：

沒有留言:

張貼留言

標籤

網誌存檔

2026年1月12日 星期一

AI 實作股票系統 - 環境建置

第一部分：步驟大綱 (Outline)

第二部分：資料夾結構圖 (Folder Structure)

第三部分：詳細指令與檢核機制

步驟 0: 安裝 .NET 9 SDK 和 Node.js

安裝 Node.js (v20+) 使用 NVM

安裝 .NET 9 SDK

請在 backend 資料夾或回到家目錄執行皆可。

步驟 1：下載並執行安裝腳本

步驟 2：設定環境變數 (關鍵步驟)

步驟 3：最終檢核

現在 Node.js 和 .NET 9 應該都好了。指令意圖：一次檢查兩個環境。Bashnode -v && dotnet --version 預期輸出：Plaintextv20.19.6 9.0.101 (或類似的 9.0.x 版本號)

步驟 1: 專案初始化與資料庫環境

步驟 2: 建置 .NET 9 WebAPI 後端

步驟 3: 建置 React + Vite 前端

步驟 4: 整合啟動 (開發模式)

新專案的 docker-compose.yml (股票系統)

這樣做如何達成您的需求？

第一步：在 GitLab 網頁上建立「空專案」

第二步：設定 .gitignore (非常關鍵！)

第三步：初始化 Git 並推送到 GitLab

1. 設定 Git 作者身分 (請依喜好修改引號內內容)

🔐 關於驗證 (如果跳出輸入帳密)

複製貼上給 Cursor 的提示詞 (Prompt)：

沒有留言:

張貼留言

2026年1月12日星期一

請在 `backend` 資料夾或回到家目錄執行皆可。

現在 Node.js 和 .NET 9 應該都好了。
指令意圖：一次檢查兩個環境。
Bash
`node -v && dotnet --version`
預期輸出：
Plaintext
`v20.19.6 9.0.101 (或類似的 9.0.x 版本號)`

新專案的 `docker-compose.yml` (股票系統)

第二步：設定 `.gitignore` (非常關鍵！)