#前端架构

状态: 2026-06-06 verify(基于 studio-website-monorepo/apps/web 实查)

怎么读:

• 没 context:Layer 1(30 秒)
• 改前端代码:Layer 1 + Layer 2(5 分钟)
• debug 数据流 / 认证:Layer 3
• 改部署 / 加环境:Layer 4
• 找 file:line:页面 / Query hook / Pinia 速查表

图例:Mental Model 配色统一 — 紫 = 外部 / 蓝 = 前端节点 / 绿 = 后端 / 黄 = 认证横切 / 灰 = 观测横切

---

#Layer 1 — Mental Model(30 秒)

前端是什么?跟谁通信?

一句话:前端是纯 Vue 3 SPA。Cloudflare Pages 只托管静态文件,不跑业务逻辑;所有数据请求走 studio-api(AWS Lambda + Hono);认证走 Cognito + JWT。

---

#Layer 2 — 五层架构(5 分钟)

代码怎么分层?数据从上到下怎么流?

#各层职责速查

---

#Layer 3 — 数据流时序 + 认证

用户访问 Dashboard 这一刻发生什么?

关键边界:

• 缓存命中 = 0 网络请求,直接从 TanStack Query 返回
• 缓存未命中 = Axios 自动加 Authorization: Bearer {token} → studio-api → 写入缓存 → Vue 反应式更新
• 401 自动刷新 = Axios 响应拦截器最多重试 3 次
• 认证: AWS Cognito 通过 aws-amplify;JWT 存 localStorage(auth store)绕过 pinia-plugin-persistedstate

---

#Layer 4 — 部署

前端怎么部署到 3 个环境?

关键事实(从 .github/workflows/ + apps/web/wrangler.toml verify):

• 纯 Wrangler CLI 部署,不走 CF Pages git integration
• 3 个 workflow: deploy-test.yml(push 到 main 自动) / deploy-preprod.yml(workflow_dispatch + push release/pre)/ deploy-prod.yml(workflow_dispatch 手动 + 输 "prod" 二次确认)
• 3 个 CF Pages project: studio-test / studio-pre / studio
• 3 个域名: studio-test.retaintive.ai / studio-pre.retaintive.ai / studio.retaintive.ai
• build 命令: bun run build → wrangler pages deploy dist --project-name={env}

---

#页面速查(Layer 3a)

改某个页面 / 找页面文件位置时查。基于 find src/pages -name "*.vue" 实查共 174 文件。

#认证页面(无侧边栏,blank 布局)

#侧边栏 Operational 分组(default 布局)

#侧边栏 Settings 分组(default 布局)

#系统页面 + Disabled / Cleanup

Disabled / WIP: src/pages/users/index.vue.disabled(与 /access-management 可能重叠)、src/pages/help-center.vue.disabled(stub)。Cleanup 候选: activity-timeline-old/ 与 lead-tracker-old/ 目录仍存在,未启用。

---

#Query Hook 速查(Layer 3b)

改 cache strategy / 加新 hook / debug 缓存失效时查。src/composables/queries/ 共 38 个 hook 文件(2026-05-29 ls 实查)。另有多个非 query composable 分散在 src/composables/ 根,处理 UI 状态(如 useCalendar、useDashboardMetrics、useStaffPerformance),不走 TanStack 缓存。

("—" = 该 hook 未显式设置 staleTime,使用 TanStack Query 默认值 0。)

---

#Pinia Store 速查(Layer 3c)

改全局状态 / debug 多 tab 持久化时查。pinia-plugin-persistedstate 默认 storage 在 src/plugins/pinia/index.ts:9 设为 sessionStorage(tab 生命周期内持久)。只有 auth store 直接用 localStorage.* API 手动持久,绕开了 plugin。

---

#观测(横切)

• Sentry @sentry/vue: error tracking;src/utils/sentry.ts(env detection + user context);disabled on localhost
• 自建 Session Analytics: src/utils/sentry-analytics.ts 定义 SessionAnalytics + FeatureCategory enum(DASHBOARD / CALL_ANALYSIS / FILTERS / EXPORTS …);上报到 Sentry breadcrumb / context
• 不是每个按钮都 log — 只 log feature usage(用了哪个功能 / 切了哪个 store / 导出了什么)+ error path

Sentry 接入 / metric 上报细节: 见 system-design/observability.md(待新建,跟踪后续 reorg)

---

#技术栈速查

---

#Legacy