導覽

Nitra App UI 是一套建構在 Vue 3 + Quasar（Vite） 上的金融科技單頁應用（SPA）——涵蓋卡片、支付、貸款、費用、onboarding/KYB、團隊管理——並用同一份程式碼支援多品牌（white label）。這份文件帶你從零開始，到能有信心地開發功能。

給誰看

剛加入 Nitra 的前端工程師，以及任何需要一張「一次請求如何變成畫面」地圖的人。你需要 Vue 3 基礎；不需要 Quasar 或 Pinia 經驗——本文會補上。

怎麼讀這份文件

若只能讀一章，讀 §5——它是整份文件的主軸。其餘每一章都是這條路徑上某個角色的細節。§1–4 建立詞彙，§6–11 深入各層，§12 端到端做一個功能，§13–15 為參考。

Page Group 的形狀

page group 是工作的單位。最小的一個（src/pages/ErrorPages/）只有兩個檔案，而這個形狀可以往上擴展：

src/pages/<Group>/
  routes.js            # 此 group 的路由（path、name、component=layout、beforeEnter guards）
  <Name>Page.vue       # 頁面元件（PascalCase，一律 *Page.vue）
  components/          # 只在此 group 內使用的模組元件
  composables/         # （選用）模組層 composable
  i18n/en-US.js        # （選用）此 group 的翻譯字串，合併進全域 bundle

全景圖

這是瀏覽器 SPA，沒有後端那種「三個 process」。取而代之，幾乎所有東西都是一次導航流過的七大角色之一的細節，外加幾個跨切面系統。

flowchart LR
    Boot["boot/
啟動引導"] --> Router["router/
+ guards"]
    Router --> Layouts["layouts/
外殼"]
    Layouts --> Pages["pages/
page groups"]
    Pages --> Stores["stores/
Pinia"]
    Stores --> API["services/api.js
$API"]
    Pages -.使用.-> Composables["composables/
+ helpers/"]
    Stores -.使用.-> Composables
    API --> BE[("nitra-app-api")]
            

跨切面系統（與角色並存）

• i18n（src/i18n/、src/boot/i18n.js）——翻譯；元件用 useI18n()，其餘用 i18n.global（§9）。
• 主題與 white-label（uno.config.js、src/css/<brand>.variables.scss、appSettings.js）——UnoCSS token + 各品牌 build（§9）。
• 權限（permissions.js）——guards 會用到的兩層權限模型（§8）。
• 事件匯流排與全域 dialog（eventEmitter.js、GlobalDialogs.js）——解耦的跨元件溝通（§10）。

跑起來

前置需求

• Node 依 .nvmrc，套件管理一律 Yarn（不用 npm/npx，見 §14）。
• 一組有 GitHub Packages 讀權限的 GITHUB_TOKEN——app 會從 GitHub Packages 拉 @Nitra-Finance/nitra-ui-library 與 docs CLI（§13）。

步驟

yarn setup-npmrc     # 用 GITHUB_TOKEN 從 template 產出 .npmrc（首次安裝前必做）
yarn install         # 從 GitHub Packages 拉 @Nitra-Finance/nitra-ui-library
# 建立 config/.env.development（git-ignored）：API_URL、GITHUB_TOKEN、APP_NAME、VUE_ROUTER_MODE…
yarn sync:docs       # 拉共用 guidelines 到 docs-nitra-fe/（git-ignored，見 §13）
yarn dev             # 開發伺服器（先跑 scripts/css-variables.js，再 quasar dev）

build／env 模型（一定要讀，大家都踩過）

部署目標

• Staging 與 Production → Cloudflare Pages。
• Review Apps → Heroku（index.js/server.js 的 Express server;API base 變成 /api 以保 cookie 同源，見 §7）。

The Page Group

為何以 page 分組，而非以類型

以類型分（所有元件一個資料夾、所有路由另一個），會讓一個功能散落在十幾個資料夾裡。我們改以產品領域分組：Cards 的一切都在 src/pages/CardGroup/。merge conflict 更少，就算長到幾十個 group，程式碼還是好找。

裡面有什麼

每個 group 擁有一個 routes.js（路由定義）與其頁面元件（*Page.vue）。只在群組內用的元件放在它的 components/；跨群組重用的元件升級到全域 src/components/（§11、§14）。

路由是「匯總」的，不是自動發現

沒有自動發現。每個 group 的 routes.js 必須被 import 並 spread 進 src/router/routes.js 的主陣列（:56-101）:

import cardGroupRoutes from 'src/pages/CardGroup/routes';
// …
const routes = [
  ...cardGroupRoutes,
  // …
  ...errorPagesRoutes,   // catch-all 必須放最後（router/routes.js:100）
];

Layout 由 route 的 component 決定，不是 meta

頂層 route 物件的 component 欄位指向一個 layout；它的 children 渲染在該 layout 的 <router-view> 內。這裡沒有 meta.layout 慣例。

{
  path: '/',
  component: () => import('layouts/MainLayout/MainLayout.vue'),  // ← 選 layout
  beforeEnter: [authGuardLoggedInRoute()],                       // ← guard（見 §5/§8）
  children: [ /* 頁面渲染在 MainLayout 內 */ ],
}

★ 導航 / 渲染生命週期

這是後端 request lifecycle 的前端對應版。讀懂一次，其餘每章都能掛回這條路徑。

完整路徑：URL → guard → layout → page → store → $API → render

1. 導航 → 全域 beforeEach

每次導航先進 router 全域 beforeEach，它只切換一個 loading 旗標：setPageLoading(true)（src/router/index.js:46-58）；afterEach 再切回（:55）。登入/權限的判斷不在這裡，而在各 route 的 guard（下一步）。

2. 各 route 的 guards（beforeEnter[]）

每條受保護路由在 beforeEnter 陣列列出 guards，由左到右執行。第一個幾乎都是 authGuardLoggedInRoute()——而它（別被名字誤導）其實在 src/services/auth.js:51-407，不在 routeGuards.js。它扛最重的事：

• 從 cookie 讀 refresh token（auth.js:91）；無 token → next(genRedirectRoute('login', to))（:381,389）。
• 若未快取則載入 authStore.member、organization、rolePermissions（:109-129）。
• 驗證 email/手機確認與 active 狀態（:135-169）。
• 處理 ?organizationId= 切換組織（:175-202）與 onboarding 導向（產品/條款未完成時）（:254-277）。
• 驗證該 org 的 provider 與當前 white-label build 相符；不符則用一次性 token 做整頁跳轉（window.location.href，hard redirect，:207-233）。
• 載入背景資料：非關鍵走 Promise.allSettled（不阻擋），關鍵走 Promise.all（:330,358）。

權限 guards 在它之後跑（它們依賴 member/organization 已被載入，見 §8）。這個順序是強制的，程式碼內有註解（routeGuards.js:45）。

3. Layout → Page 掛載

guards 若 next(),router 解析 route.component（layout,§4）並在其中掛載對應頁面。頁面通常在 onMounted 呼叫 store action 拉資料。頁面不直接呼叫 $API——它走 store（§6）。

4. Store → $API → 後端（含 401 refresh）

src/services/api.js 是唯一的 HTTP 出口。兩件事讓它特別：

• 沒有 request 攔截器。 Authorization header 在 call-site helper（apiPostAuth,api.js:255）掛——它讀 JWT 的 entityType，經 AUTHENTICATION_HEADER_PREFIX 映射成 jwt-member/jwt-martmember/jwt-supermember（api.js:227-241）。withCredentials: true 帶 cookie。
• response 攔截器 + 401 refresh 佇列（api.js:31,46-63,197-）。成功時unwrap response.data，呼叫端直接拿到 body。401 時 refresh:

// api.js — 簡化示意
let isRefreshing = false;
let refreshSubscribers = [];   // refresh 期間撞到 401 的請求,排隊在此
// 第一個 401 設 isRefreshing 並呼叫 refreshAuthToken();其餘 subscribe,
// 等新 token 下來再重送。只 refresh 一次,而非 N 次。

5. Response → store → 響應式渲染

攔截器回傳 response.data;store 寫入響應式狀態；Vue 重繪頁面。錯誤以 error?.response?.data || error 形式（api.js:222）拋出，並透過標準錯誤 UI（ErrorBanner / BasicAlert / useNotifyFailed,§11/§14）呈現——絕不丟原始錯誤。

State 層（Pinia）

所有共用狀態都是 Pinia，且一律 setup 風格（defineStore(id, () => {…})）——不用 options 風格。Pinia 在 src/stores/index.js 建立並掛 Sentry plugin。

Store 名冊

authStore 深入（guards 依賴的那個）

• Token 存在 cookie，不在 store state。 setAccessTokenAndRefreshToken()（authStore.js:191）寫 token 與 refresh-token cookie,sameSite:'Strict'、secure:true，到期時間從 JWT 解出。Admin 與 super-member token 各有自己的 cookie 對（:207-267）。
• Guards 讀 getter，不讀 cookie。 isAuthenticated = !!member.value?.id（:90）;memberOrganization（:102）、rolePermission（:118,reduce 成扁平 {permission: bool}）、checkProvider（:661）、checkBetaUser（:622）。這些就是 §8 guards 會呼叫到的 getter。
• 登出是跨 store reset。 resetSessionStates()（:562）遍歷每個 active Pinia store 並呼叫其選用的 $resetStates()——所以乾淨登出依賴每個 store 都實作該 hook（七個都有）。

狀態持久化模型

狀態不會自動存到 localStorage——重整時由 guards 從 API 重新載入。例外：token（cookie）與 2FA 臨時 session（雙存於 Pinia + sessionStorage，經 hydrateTwoFactorSession() 重建，authStore.js:746）。

API 層（$API）

axios 實例

src/services/api.js:21-24 建立一個 axios 實例。baseURL 是條件式的（:14-19）:Heroku review-app 主機名（/-pr-\d+\.herokuapp\.com$/）用 /api（讓 refresh-token cookie 在 FE Express server 後維持同源）；其餘用 process.env.API_URL。所有請求 withCredentials: true。

一次呼叫怎麼發

$API 是一大棵 resource 物件樹，直接 import（import $API from 'src/services/api.js'）。每個方法委派給 call-site helper:

Header 格式 Authorization: <prefix> <token>——對應後端的 jwt-<type> scheme。

Response 與 error 形狀（呼叫端實際拿到什麼）

• 成功：攔截器回傳 response.data（api.js:34）。所以 await $API.members.read() resolve 的是 body——例如 { member, organization }，不是 axios 外殼。
• 失敗：error?.response?.data || error（api.js:222）。後端形狀是 { success:false, status, error, message }——branch 在機器碼 error，絕不比對人類 message（§14）。

401 refresh 流程

已在 §5 步驟 4 說明。重點：同時只 refresh 一次（isRefreshing + refreshSubscribers,api.js:46-63）；一般 member 只在非 JSON 401 觸發（:197）;super-member 有獨立、平行的佇列（:134-144）；重送用裸 axios.request 繞過攔截器以避免遞迴（:110-131）。

權限與路由守衛

兩層權限

src/composables/permissions.js（usePermissions()）暴露兩個獨立層，皆從 authStore 經 storeToRefs 響應式取得：

1. Member-organization 權限——產品層存取（如 BILLPAY_FULL_ACCESS）。用 checkMemberOrganizationPermission(...) 檢查。
2. Role 權限——細到單一操作的存取權限（如 CARD_CREATE_ALL_CARDS）。用 checkRolePermission(...) 檢查。

物件層級的檢查有層級:ALL > TEAM（同一條管理線，含自己） > SELF > NONE（permissions.js:159-183）。checkCanUpdateMemberCard(member) 之類的 helper 包住它。

各 guard

Guards 是 src/router/routeGuards.js 的 factory（各回傳 (to, from, next) 函式），加上 src/services/auth.js 裡那個大的 session guard:

i18n、主題與 White-Labeling

i18n

• 全域實例在 src/boot/i18n.js;locale bundle 是 src/i18n/en-US/index.js，它import 每個 page group 的 i18n/en-US.js 並 spread 在一起（:8-43）。全域字串用 g[key] 前綴，模組字串用 <module>[key] 前綴。
• 規則：在元件裡 const { t } = useI18n()。在 composable、store、helper、guard（非元件）裡 import { i18n } from 'src/boot/i18n.js'; const { t } = i18n.global。混用會破壞 scope 與 hot-reload（§14）。

主題（UnoCSS）

uno.config.js 擴充 UI library 的 token——import { uiTheme, uiExtendTheme, uiShortcuts } from '@Nitra-Finance/nitra-ui-library/unocss'——再 spread 進 theme、extendTheme、shortcuts（uno.config.js:2,24,43,45）。用對應 token 的 UnoCSS utility class 設計樣式（bg-primary、text-gray-600、gap-4）；罕見的自訂 class 用 BEM（§14）。

White-labeling（一份程式碼，五個品牌）

品牌在 build time 由 APP_NAME 決定（預設 nitra，另有 trueaesthetics、premiereaesthetics、tomo、exponent——constants.js:245-251）。不能 runtime 切換。它切換的東西：

useIsNitraApp()（appSettings.js:130，即 useAppName() === defaultAppName）是元件與 routeGuardNitraApp 用的 runtime 品牌判斷。

跨元件溝通

事件匯流排

src/helpers/eventEmitter.js 是一個小的 EventEmitter class（on/off/emit/once/removeAllListeners），以 Map 支撐。listener 的錯誤會被 catch，所以一個壞 handler 不會中斷整條鏈（:144）。

全域 Dialog

單一 app 層 dialog 由事件驅動，不靠 prop 層層下傳：

• src/utils/eventEmitter.js 匯出 CommonEventEmitter + 事件名（OPEN_GLOBAL_BASIC_DIALOG、CLOSE_GLOBAL_BASIC_DIALOG）。
• src/components/DialogComponents/GlobalDialogs.js（BasicDialogGlobal()）監聽並渲染那唯一一個 dialog。
• App.vue 掛載一次 <BasicDialogGlobal />，旁邊還有 AutoLogoutDialog、PageLinearLoader、UI-library toast stack 與 <router-view />。

import { CommonEventEmitter, COMMON_EVENT_NAMES } from 'src/utils/eventEmitter';
CommonEventEmitter.emit(COMMON_EVENT_NAMES.OPEN_GLOBAL_BASIC_DIALOG, {
  title: '確認', caption: '確定嗎?', onOk: () => {/* … */},
});

一次性、頁面內的 modal，用 Quasar $q.dialog() 或 DialogComponents/ 裡的 RightDialog/CenterDialog/BasicDialog wrapper。

Composables 與 Helpers

界線

• Composable（src/composables/）= 響應式邏輯——用 ref/computed/watch/生命週期。函式名帶 use 前綴（useNotifyFailed）;檔名不帶（notify.js）。
• Helper（src/helpers/）= 純、非響應式工具（logic.js、constants.js）。
• 模組專屬版本放在 page group 下（src/pages/<Group>/composables/）。

你會一直用到的那些

Worked Example：真實 Page Group 端到端

不自己編，直接追一個真實的 group——TeamGroup → Members——走過 §5 的完整生命週期。以下每個檔案都是真的，可對照打開。

/team   → MainLayout · beforeEnter: [authGuardLoggedInRoute()]        (TeamGroup/routes.js:20-28)
  └ /members        → MembersPage.vue                                  (routes.js:30-)
      └ /members/invite → beforeEnter: [routeGuardRolePermissions(ROLE_PERMISSION_GROUP.MEMBERINVITE_INVITE)]

1. Route + guards（src/pages/TeamGroup/routes.js）——component 選 layout，先 session guard,nested route 上掛權限 guard

import { authGuardLoggedInRoute } from 'src/services/auth';                 // routes.js:9
import { routeGuardRolePermissions } from 'src/router/routeGuards';         // routes.js:10
import { ROLE_PERMISSION_GROUP } from 'src/constants/permissions';          // routes.js:15

{
  path: '/team',
  name: PAGES.MENU_ROUTE_NAME.TEAM,
  component: () => import('layouts/MainLayout/MainLayout.vue'),  // layout
  redirect: { name: 'team-members' },
  beforeEnter: [authGuardLoggedInRoute()],                       // 先 session
  children: [{
    name: 'team-members',
    path: 'members',
    component: () => import('src/pages/TeamGroup/MembersPages/MembersPage.vue'),
    children: [{
      name: 'team-member-invite',
      path: 'invite',
      beforeEnter: [routeGuardRolePermissions(ROLE_PERMISSION_GROUP.MEMBERINVITE_INVITE)], // 後權限
    }],
  }],
}

2. 頁面在 onMounted 呼叫 store actions（MembersPages/MembersPage.vue）

import { useI18n } from 'vue-i18n';                                                       // :142
import { useMembersStore } from 'src/pages/TeamGroup/MembersPages/stores/membersStore.js'; // :112
import { useNotifyFailed } from 'src/composables/notify';

const { t } = useI18n();
const membersStore = useMembersStore();
const { getMembers, getMemberOrganizationPermissions } = membersStore;                    // :162

onMounted(async () => {                                                                   // :301-313
  try {
    await Promise.all([getMemberOrganizationPermissions(), getMembers()]);
  } catch (error) {
    useNotifyFailed({ message: error.message });
  }
});

3. Store action 打 $API（MembersPages/stores/membersStore.js）

import $API from 'src/services/api';                                  // :24
export const useMembersStore = defineStore('membersStore', () => {    // :25
  async function getMembers() {                                       // :203-258
    // …組 params…
    const response = await $API.members.query(params);               // 唯一的 HTTP 出口
    // …寫入響應式狀態…
  }
});

4. 用 i18n 渲染

t('members[title]')；字串在 MembersPages/i18n/en-US.js（'members[title]': 'Members'）,spread 進全域 bundle（§9）。

整條鏈，全是真的：TeamGroup/routes.js（guards）→ MembersPage.vue（onMounted）→ membersStore.js（getMembers）→ $API.members.query() → 用 t('members[…]') 響應式渲染——正是 §5 的路徑。

要做你自己的

同樣形狀：新 src/pages/<Group>/ 配一個 routes.js（component 選 layout;authGuardLoggedInRoute() 後接權限 guards）,spread 進 src/router/routes.js 且在 errorPagesRoutes 之前；一個在 onMounted 呼叫 store action 的頁面；一個 action 會打 $API 的 store（全域或模組層）；以及 spread 進 src/i18n/en-US/index.js 的模組 i18n。

AI Agent 與文件系統

三 repo 的關係

flowchart TD
    FED["@Nitra-Finance/nitra-fe-docs
共用 guidelines + AI 工具"]
    UIL["@Nitra-Finance/nitra-ui-library
元件 + UnoCSS tokens + agent-docs"]
    APP["nitra-app-ui
(這個 app)"]
    FED -- "yarn sync:docs (npm CLI)" --> APP
    FED -- "sync" --> UIL
    UIL -- "GitHub Packages import" --> APP
            

• nitra-fe-docs 是共用 guidelines + AI 工具的單一 source of truth，發布為 npm 套件 @Nitra-Finance/nitra-fe-docs。它的 sync CLI（scripts/cli.js → scripts/sync-docs.js）把 docs/en/ 複製進使用端的 docs-nitra-fe/，也同步 .github/、.cursor/、.claude/、.gemini/ template——依 project group 過濾（PROJECT_GROUP_REPOS:APP / UI_LIBRARY / DOCUMENTATION）。本 repo 的 yarn sync:docs = npx @Nitra-Finance/nitra-fe-docs@latest sync（package.json:21）。
• nitra-ui-library 提供共用元件與設計 token，發布到 GitHub Packages。本 app 從 @Nitra-Finance/nitra-ui-library import 元件（UiButton、UiModal…）、從 @Nitra-Finance/nitra-ui-library/unocss import token。它的 agent-docs/figma-component-mapping.md 是 Figma→程式碼映射的 source of truth。
• nitra-app-ui 同時用到上述兩者。

AI 工具

.claude/ 與 .cursor/ 的 rules/skills 是從 nitra-fe-docs 同步、不在各專案 fork（只有 .claude/settings.json 是本地）。.claude/rules/ 定義不可違反的規範（tech stack、code structure、API safety、命名）;skills（/fe-reviewer、/fe-scanner、/fe-verifier…）是任務 playbook。從 Figma 實作時，fe-figma-workflow 規則會先拉 UI-library 元件映射。

慣例速查

技術棧（不可違反）

Vue 3 Composition API + <script setup> only;app 程式碼只用 JavaScript（無 TS）;Pinia（setup 風格）;UnoCSS（自訂 class 用 BEM）；只用 Yarn;ESLint 9 flat + StandardJS（無 Prettier）；測試用 Cypress。

命名

• 元件 PascalCase（BaseButton.vue）；頁面 *Page.vue；群組 *Group//*Pages/;store camelCase+Store;composable 檔名 camelCase 無 use 前綴；composable 函式 use*。
• Props/變數/函式 camelCase;template 事件 kebab-case；布林 is/has/can/should;template ref *Ref；常數 UPPER_SNAKE_CASE;route name kebab-case;CSS BEM kebab-case。

Import

從 src/ 絕對路徑（import X from 'src/...'）；相對路徑只給同層檔案。順序：Vue/Quasar → 元件 → store → composable → service → 常數 → helper → 第三方。

元件

全域、無邏輯、Base* 放 src/components/；模組層、業務命名放 src/pages/<Group>/components/。SFC 區塊順序：<docs> → <template> → <script setup> → <style>。

API 安全

所有 HTTP 走 $API；每次呼叫 try/catch 或 store 集中處理；友善錯誤用 ErrorBanner/BasicAlert/ValidatedField/useNotifyFailed（不丟原始）;branch 在機器碼 error 而非 message;response optional-chain;unmount 時取消 pending 請求。

i18n

字串放 src/i18n/，絕不 inline；元件用 useI18n()，其餘用 i18n.global。

HTTP response 形狀（來自 nitra-app-api）

扁平，無 data 巢狀。成功 { status, success, <具名內容> }；錯誤 { success:false, status, error, message }。列表：page/limit/sort（逗號 list,-=降冪）/filter（逗號=IN），回 total。

附錄

術語表（Glossary）

指令速查

yarn setup-npmrc        # 用 GITHUB_TOKEN 產出 .npmrc（首次安裝前）
yarn dev                # 開發伺服器（先 css-variables.js → quasar dev）
yarn dev:pwa            # PWA 模式開發
yarn build              # 正式 build      |  yarn build:pwa
yarn lint  / lint:fix   # lint（StandardJS）|  yarn lint src/pages/Foo（限定範圍）
yarn cy:open            # Cypress runner
yarn sync:docs          # 拉共用 guidelines 進 docs-nitra-fe/
APP_NAME=tomo yarn build   # build 特定 white-label 品牌

Repo 地圖

Troubleshooting — 常見坑（皆上文驗證過）

• 共用 guidelines 不見 / docs-nitra-fe 是空的 → 跑 yarn sync:docs（它是 git-ignored）。
• yarn install 在 @Nitra-Finance/* 401 → GITHUB_TOKEN/.npmrc 沒設好；跑 yarn setup-npmrc。
• 品牌顏色錯 → scripts/css-variables.js 沒在 Quasar 前跑；用 yarn dev/build script。
• 權限 guard 看到 undefined → 它列在 authGuardLoggedInRoute() 之前；移到後面（§8）。
• 「token 沒 refresh」 → 一般 member 的 refresh 只在非 JSON 401 觸發（api.js:197）。
• 環境變數沒進 app → 它必須在 build time 存在；build.env: process.env 只捕捉當下設定的。

你現在對 Nitra App UI 有了端到端的理解——boot、導航/渲染生命週期、stores、$API、guards/權限、i18n/主題/white-label、跨元件溝通——以及如何用這一切建一個 page group。更深的參考是 README.md 與同步下來的 docs-nitra-fe/ guidelines。歡迎加入。 ↑ 回到頂部