EntrepreneurAgenda

企業家國際演講會 Club Management 系統：帳號密碼或 Microsoft 帳號登入、議程產生、角色安排、會員與分會管理、Pathways 目錄、社群發文（AI 文案／生圖、發布到 FB／IG／Threads），以及讓 AI 助理透過 MCP 操作系統。

架構

層	技術	說明
前端	Next.js 15 + React 19（App Router，app/）	每個頁面一個 app/<route>/page.js；middleware.js 在 edge 驗登入 cookie。package.json 的 overrides 把 Next 鎖死的 postcss／nanoid 拉到已修補的版本
前端 → 後端	/svc/* 代理（app/svc/**）	瀏覽器只拿得到 httpOnly 的 auth_token cookie，代理在伺服器端把它轉成 Authorization: Bearer 送到 FastAPI。前端一律用 lib/api.js 的 apiJson()
後端	FastAPI（api/index.py，單一檔案）	所有 /api/*、OAuth 與 MCP 端點；Vercel 上是 Python serverless function
資料庫	Neon PostgreSQL，Alembic 管 schema	見「Database Migration」
檔案	Cloudflare R2（Vercel）／Azure Blob（Azure VM）	前端拿 presigned URL 直傳。設了 AZURE_STORAGE_ACCOUNT／AZURE_STORAGE_CONTAINER 就用 Blob，見「檔案儲存：R2 與 Azure Blob」

專案結構

EntrepreneurAgenda/
├── app/                      # Next.js 頁面（App Router）
│   ├── layout.js / globals.css
│   ├── login/                # 登入 / 自行註冊 / Microsoft 登入與申請（支援 ?next= 回跳）
│   ├── home/                 # 會務 Dashboard
│   ├── agenda/               # 議程表產生器（公開網址是 /index，見 next.config.mjs）
│   ├── roles/                # 角色安排（多場例會 × 角色矩陣，角色來自 lib/meetingRoles.json）
│   ├── social/               # 社群發文
│   ├── member/               # 會員管理
│   ├── club/                 # 分會管理（品牌、版型設定、社群帳號、分會 AI 金鑰）
│   ├── machines/             # 機台管理（電子名牌配對、綁定會員）
│   ├── pathways/             # Pathways 目錄管理（system_admin）
│   ├── change-password/      # 修改密碼 / 首次登入強制改密碼
│   ├── oauth/authorize/      # MCP 客戶端的 OAuth 同意畫面
│   ├── settings/             # 每位使用者的設定：個人資料、登入方式、已授權的應用程式
│   └── svc/                  # 同源代理：cookie → Bearer → FastAPI
│       ├── [...path]/route.js
│       └── auth/
│           ├── {login,logout,register}/route.js    # 登入時把 JWT 寫成 httpOnly cookie
│           └── microsoft/{start,callback}/route.js # Microsoft 登入：state / PKCE / nonce cookie、回呼後設 cookie
├── components/Sidebar.js     # 側邊選單
├── lib/
│   ├── api.js                # apiFetch / apiJson（打 /svc/*）
│   ├── auth.js               # 角色輔助函式、applyRoleUI()
│   ├── agendaTemplates.js    # 議程版型引擎（AGENDA_TEMPLATES + 每版型 manifest / 預設素材 / 語言能力）
│   ├── postTemplates.js      # 社群海報版型
│   ├── socialPlatforms.js    # 各平台字數、圖片規則（資料在 socialPlatforms.json，後端也讀）
│   ├── pathways.js           # Pathways 目錄載入與查詢
│   ├── rolesSheet.js         # 角色表 Google Sheet 匯入解析
│   └── memberAutocomplete.js # 會員自動完成（下拉建議 + 可自由輸入）
├── public/media/             # 靜態圖片（各版型預設 logo / QR）
│   ├── toastmasters_logo.png
│   ├── Entrepreneur/  ChillHiHigh/  China/
├── middleware.js             # 未登入導向 /login；/api、/svc、/.well-known 放行
├── next.config.mjs           # 舊 .html 網址轉址、/index → /agenda
├── api/index.py              # FastAPI（本地開發 & 正式環境共用）
├── api/_postgen/             # 受控貼文引擎（整併自 PostGenerator；底線開頭，Vercel 不會當成 function）
├── tests/                    # pytest：引擎單元測試 + 對測試資料庫的 API／MCP 測試
├── requirements.txt          # Python 套件
├── package.json              # Node 套件（next / react / jose）
├── vercel.json               # /api/* 與 /.well-known/* 交給 api/index.py
├── alembic.ini
├── .env                      # 本地環境變數（不進版控）
└── migrations/
    ├── env.py                # 讀取 DATABASE_URL
    └── versions/             # 0001 … 0017，見「Database Migration」

---

重大架構變更（v2）

members 資料表已廢棄。 每位 user 就是一位 club member，level 直接存在 users 資料表。

舊版	新版
members 獨立資料表	改為 users.level 欄位
自行註冊即可登入	自行註冊 → pending，需管理員審核
無首次改密機制	admin 建立帳號後 must_change_pw=true，首次登入強制改密碼
/api/members	由 /api/users 取代

---

議程版型引擎（分會專屬版型）

每個分會可擁有自己的品牌與獨立的議程版型。版型與其所有相關設定（欄位、預設素材、語言能力）集中定義於 lib/agendaTemplates.js，是單一事實來源——新增/調整版型基本上只動這個檔案（＋樣式）。

版型物件（AGENDA_TEMPLATES[key]）

屬性	說明
key / label	版型代號（對應 clubs.template_key）與下拉顯示名稱
render(data, club, ctx)	產出 HTML（回傳字串＝單頁；字串陣列＝多頁）
langToggle	false → 隱藏語言切換並固定 fixedLang（見「語言能力」）
fixedLang / bilingualNames	固定渲染語言；bilingualNames 讓成員姓名顯示「English 中文」
assetDefaults	分會未上傳時的預設圖（key 用 logo_url / fb_qr_url…）
fieldDefaults	預設值（如 timeRange / venue）
settings	版型專屬欄位 manifest（見下）

輔助函式：templateAssetDefaults(key)、templateFieldDefaults(key)、applyTmplVisibility(root, key)。

運作方式

• app/agenda/page.js 渲染時 getActiveClub() 解析目前分會 → 依 template_key 取版型 → render() 產出 HTML，外層套 .tmpl-<key> class。
  • system_admin：版型 / 品牌取自議程上方「所屬分會」下拉（從 /home 點「新建議程」會以 ?club_id= 自動帶入所選分會）。
  • club_admin / club_member：自動取自己所屬分會。
• 品牌與版型為即時解析（不快照進 agendas.data）。
  • ✅ 編輯分會品牌後，該分會所有議程自動套用新資料。
  • ⚠️ 變更某分會的 template_key 會讓其既有議程也改用新版型呈現。
• 未設定欄位的 fallback 鏈：分會設定 → 該版型 fieldDefaults / assetDefaults → 標準版預設。預設圖集中於 media/Entrepreneur/（企業家）與 media/ChillHiHigh/（Chill Hi High）。

語言能力（依版型）

• standard / entrepreneur：提供中/英切換（設定選單的「語言」）。
• chillhihigh：中英混用，隱藏「語言」切換、固定渲染語言，且成員姓名顯示「English 中文」。
• app/agenda/page.js 於 updatePreview() 依版型旗標顯示/隱藏「語言」選單並 pin 語言。

版型專屬欄位 manifest（template.settings）

每個版型專屬欄位只在 manifest 宣告一次，/club（app/club/page.js）的「版型設定」modal 會據此動態產生欄位（含填值與存檔）：

{ key, label, type:'text|textarea|image', store:'column|setting',
  group:'basic|template', section, row, placeholder }

• store：column = 存 clubs 頂層欄位（如 charter_no）；setting = 存 clubs.settings JSONB。
• group：basic（分會管理頁「編輯」視窗）/ template（「版型」視窗）。分會列表每列有「編輯」「版型」兩顆按鈕，開啟同一 modal 的兩種檢視。
• 圖片欄位透過既有 /api/upload/presign 延後上傳；未上傳時預覽顯示 assetDefaults。
• 存檔採 merge-based：以現有分會記錄為基底，只覆寫當前版型 manifest 管的欄位（後端 PUT 為 full-replace，避免洗掉他版型欄位）。

目前 clubs.settings 內的鍵：

• 表頭/結尾：slogan（標語）、transit（交通）、closingLine（結尾句）
• 議程資訊：timeRange（預設時間；日期仍動態帶入當日）、venue（預設地點）、scheduleZh / scheduleEn（會議日期行，隨語言顯示；標準版 fallback 到 t('meetingSchedule')）
• 第二頁宣傳後頁：upcomingMeetings、specialEvent、membershipFee、ig_qr_url、page2_hero_url、page2_img2_url

This is the beginning of the README. Read the rest at the original. Read the full README ↗