first commit

2026-10-05 07:40:28 +08:00
commit 5a7ac2e5d9
1 changed files with 111 additions and 0 deletions
@@ -0,0 +1,111 @@
+# Nestly
+
+Nestly 是一個以 Go 打造的房地產系統。後端使用 [chi](https://github.com/go-chi/chi) 作為 HTTP 路由器，網頁介面不依賴任何前端框架，直接以 Go 標準庫 `html/template` 進行 server-side rendering（SSR），樣式採用 [Tailwind CSS](https://tailwindcss.com)（standalone CLI 建置，無需 Node.js）。
+
+## 特色
+
+- **輕量技術棧**：chi 路由器、`html/template` 模板引擎與 GORM，不引入前端打包工具或 JavaScript 框架
+- **Server-side rendering**：頁面由後端直接輸出完整 HTML，first paint 快、SEO 友善
+- **Tailwind CSS**：以 standalone CLI 掃描模板產生最小化的 CSS，模板與靜態資源透過 `go:embed` 內嵌，部署只需單一執行檔
+- **中介軟體架構**：利用 chi 內建的 middleware（logger、recoverer 等）與自訂 middleware 處理日誌、錯誤還原與驗證
+- **巢狀路由**：以 chi 的 `Route` 組織資源導向的 URL 結構
+
+## 技術棧
+
+| 項目 | 說明 |
+|------|------|
+| 語言 | Go 1.26+ |
+| 路由 | [chi v5](https://github.com/go-chi/chi) |
+| 模板 | 標準庫 `html/template`（`go:embed` 內嵌） |
+| 樣式 | [Tailwind CSS](https://tailwindcss.com) v4（standalone CLI 建置） |
+| ORM | [GORM](https://gorm.io)（gorm.io/gorm） |
+| 資料庫 | SQLite（開發環境，[glebarez/sqlite](https://github.com/glebarez/sqlite) 純 Go driver；PostgreSQL 規劃中） |
+| Session | HMAC-SHA256 簽名 cookie（`internal/auth`） |
+
+## 快速開始
+
+### 環境需求
+
+- Go 1.26 以上
+- Tailwind standalone CLI（已放在 `tools/tailwindcss`；或自行[下載](https://tailwindcss.com/blog/standalone-cli)對應平台的執行檔）
+
+### 安裝與執行
+
+```bash
+# 取得專案
+git clone <repository-url>
+cd nestly
+
+# 安裝依賴
+go mod download
+
+# 編譯 CSS 並執行
+make css
+make run
+```
+
+伺服器預設啟動於 `http://localhost:3000`，可透過環境變數調整：
+
+| 環境變數 | 預設 | 說明 |
+|----------|------|------|
+| `PORT` | `3000` | 監聽埠號 |
+| `DB_DSN` | `nestly.db` | SQLite 資料庫檔案路徑 |
+| `SESSION_SECRET` | 開發用預設值（會印出警告） | session cookie 的 HMAC 簽章密鑰 |
+| `COOKIE_SECURE` | `false` | 設為 `true` 時 cookie 僅經 HTTPS 傳送 |
+
+首次啟動會自動建立示範帳號 **demo@nestly.test**（密碼 `nestly1234`），可直接至 `/login` 試用登入流程。
+
+### Tailwind CSS 開發流程
+
+- 來源檔：`web/static/src/input.css`；編譯產物：`web/static/css/app.css`（已列入版本控制，執行檔內嵌此檔）
+- 修改模板中的 class 後執行 `make css` 重新編譯；開發時可用 `make watch` 自動重建
+
+## 專案結構
+
+```text
+nestly/
+├── main.go                 # 程式進入點：初始化資料庫、session 與路由
+├── internal/
+│   ├── auth/               # HMAC 簽名 cookie session
+│   ├── handlers/           # HTTP handlers（每個資源一個檔案）
+│   ├── models/             # 資料結構與資料存取
+│   ├── storage/            # 資料庫連線
+│   ├── templates/          # html/template 模板渲染邏輯
+│   └── middleware/         # 自訂 chi middleware（規劃中）
+├── web/
+│   ├── web.go              # go:embed 內嵌模板與靜態資源
+│   ├── templates/          # HTML 模板（layout.html + pages/*.html）
+│   └── static/             # 靜態資源（src/input.css → css/app.css）
+├── tools/                  # 開發工具（tailwindcss standalone CLI）
+├── Makefile
+├── go.mod
+└── README.md
+```
+
+## 路由
+
+目前完成與規劃中的路由：
+
+| 方法 | 路徑 | 說明 |
+|------|------|------|
+| GET | `/` | 首頁（顯示登入狀態） |
+| GET | `/login` | 登入頁面 |
+| POST | `/login` | 登入（驗證成功建立 session） |
+| POST | `/logout` | 登出（清除 session） |
+| GET | `/properties` | 物件列表（支援搜尋、篩選、分頁，規劃中） |
+| GET | `/properties/{id}` | 物件詳細資訊（規劃中） |
+| GET | `/properties/new` | 新增物件表單（規劃中） |
+| POST | `/properties` | 建立物件（規劃中） |
+| GET | `/properties/{id}/edit` | 編輯物件表單（規劃中） |
+| PUT | `/properties/{id}` | 更新物件（規劃中） |
+| DELETE | `/properties/{id}` | 刪除物件（規劃中） |
+
+## 開發
+
+```bash
+make css          # 編譯 Tailwind CSS
+make watch        # 監看並自動重建 CSS
+make run          # 啟動開發伺服器
+go vet ./...      # 靜態檢查
+make test         # 執行測試
+```