sub2api/docs/superpowers/work-logs/2026-04-23-portal-frontend-revamp.md

门户前端调整工作记录

时间窗口：2026-04-19 ～ 2026-04-23 范围：sub2api 项目前端门户页（公开访问的 5 页：Landing / Docs / Login / Register / Pricing） 目标：完成多语言切换、新增 Pricing 页、消除导航栏抖动、清理对外不应展示的技术细节

---

阶段一：门户多语言 + Pricing 页

问题：门户 4 页（Landing / Docs / Login-narrative / Register-narrative）当时是 fidelity-port 自 Claude Design zip 的，约 100+ 处中文硬编码在 template 里。Pricing 页未实现。i18n 框架（vue-i18n）虽然到位，但门户页基本没用上。

做了什么：

1. 新建 components/puro/PuroLocaleSwitcher.vue —— 深色科技风的语言切换器，复用 setLocale() 核心，与 puro.css 设计 token 对齐（区别于 admin 用的 LocaleSwitcher.vue）
2. 抽取 4 页所有中文到 i18n key（landing.*、docs.*、auth.narrative.* 命名空间），同步生成英文翻译；总计约 130 个 leaf key
3. 新增 /pricing 路由 + views/pricing/PricingView.vue（约 500 行）+ components/puro/PricingCalculator.vue 子组件
4. Pricing 页从一开始就 i18n-native（约 100 个 key），含 4 档定价 tier、cost calculator、12 工具 grid、10 FAQ、final CTA
5. 关键决策（写进 spec 锁定）：
   • 定价数字使用 zip 的 $9.9 / $29.9 / $99 作为占位，配 // preview · 最终定价以开售为准 标签
   • 未实现的功能（priority scheduling、zero-log mode）配 SOON 灰标签，不删除展示
   • Binding 卡片暂指 /register；联系商务用 mailto:contact@puro.im
   • Cost calculator 算法照搬 zip JS（puro = official × 0.3），配 // estimated · 以实际计费为准 标签
   • 移除 zip 中的 注册送 $5 测试积分 文案（Stage 1 决策）

执行方式：subagent-driven-development（Plan 文件 docs/superpowers/plans/2026-04-20-portal-i18n-pricing.md，10 个任务，3 个 subagent 实现 + 1 次回归修复）

已合并 PR：#2 → main 77bb69b2

---

阶段二：Nav 抖动修复

问题：用户报告点击导航栏「产品/定价/文档」切换时元素位置发生轻微抖动。

根因分析：

第一直觉是 active class 引起的字体 weight 变化。grep CSS 后发现并非如此 —— .active 只改 color 不影响布局。

真正原因是：当前 Landing/Docs/Pricing 三个 View 各自在 template 里写了一份完整的 nav（包括按钮文案）。Vue Router 切换路由时销毁整棵 view 组件树（含 nav），重新挂载下一个。虽然视觉上"看似同一个 nav"，实际是三份独立拷贝被替换。

进一步发现两份拷贝间有差异：

• Docs 的注册 CTA 文案是 注册（2 字符）；Landing/Pricing 是 免费试用 →（5+1 字符）—— 按钮宽度不同
• Docs 的英文 Product（单数）vs 其他两页的 Products（复数）
• Pricing 的「定价」用 <a href="#" class="active"> —— 点击会 scroll to top 且 URL 改成 /pricing#

做了什么（分两步）：

步骤 1（短期） —— 文案统一：把三份 nav 的内容对齐到完全一致

• docs.nav.signup: 注册 → 免费试用 →
• docs.nav.products (en): Product → Products
• PricingView 的 <a href="#"> → <router-link to="/pricing">
• commit 779005e1

步骤 2（结构性修复） —— 抽 PortalLayout：

• 新建 components/layout/PortalLayout.vue —— 包含 nav + <router-view /> + footer
• 路由改为嵌套结构：/、/docs、/pricing 作为 PortalLayout 的子路由
• 三个 View 删掉各自的 nav / footer / bg-glow / .puro-page 包装
• 新增 portal.nav.* i18n 命名空间，删除原来的 landing.nav.* / docs.nav.* / pricing.nav.* 三份重复
• router-link 用 active-class="active" prop 替代硬编码 class
• scrollBehavior 加上 hash 锚点跳转（offset 80px 绕 sticky nav）
• commit e7f3fe5b

结果：路由切换时 Nav 不再卸载重挂，真·SPA 行为。

已合并 PR：#3 → main 291e3bfe

---

阶段三：对外内容清理

Pass 1：删除 iShare 引用

• 用户要求：项目目前定位是独立运营，不要在前端展示 iShare 相关字样
• 影响：docs.sections.getKey.note 一个 key（"未来通过 iShare 入口开放订阅购买"）+ DocsView 对应的 <p class="note">
• commit 623a7518，PR #4 → main 5c4b2980

Pass 2：移除 footer 技术细节

• 用户要求：不要透露项目技术开发细节
• 删除：更新日志 链接（指向 Gitea commits）、git.puro.im 链接、GitHub ↗ 链接、fork of Wei-Shaw/sub2api 字样
• footer-meta 简化为 © 2026 puro.im
• 同步删除 linkChangelog i18n key
• commit 2b6b5fc6，PR #5 → main 8be87883

---

关键文件清单

新增：

• frontend/src/components/puro/PuroLocaleSwitcher.vue
• frontend/src/components/puro/PricingCalculator.vue
• frontend/src/components/layout/PortalLayout.vue
• frontend/src/views/pricing/PricingView.vue

修改（重点）：

• frontend/src/router/index.ts —— 加 /pricing、嵌套路由、scrollBehavior
• frontend/src/i18n/locales/{zh,en}.ts —— 新增 portal/landing/docs/pricing/auth.narrative 命名空间
• frontend/src/views/{landing,docs,pricing}/*View.vue —— 全量 i18n 化 + 移除各自 nav/footer
• frontend/src/views/auth/{Login,Register}View.vue —— narrative slot i18n 化
• frontend/src/components/layout/AuthLayout.vue —— 添加右上角语言切换器槽位

---

commit / PR 索引

阶段	commit	描述
一	e711a203	feat(i18n): add PuroLocaleSwitcher
一	63288818	mount switcher in Landing/Docs/AuthLayout
一	fc7e2767	landing i18n keys + EN
一	73b39807	docs + auth narrative i18n
一	13bdd8f8	restore dashboard link in models.note
一	b989c503	PricingView + calculator
一	77bb69b2	Merge PR #2 → main
二	779005e1	unify signup CTA
二	e7f3fe5b	extract PortalLayout
二	291e3bfe	Merge PR #3 → main
三	623a7518	remove iShare mention
三	5c4b2980	Merge PR #4 → main
三	2b6b5fc6	footer remove tech details
三	8be87883	Merge PR #5 → main

---

部署链路

每次 merge 到 main 后：

1. Gitea webhook 触发 Drone CI
2. Drone 运行 docker build + 推镜像
3. VPS 上 docker compose 拉取新镜像 + 重启
4. 总耗时约 3–5 分钟

每次部署完成的验证手段（curl）：

1. 取 https://ai.puro.im/ 主 HTML，对比 /assets/index-*.js 文件名 hash 是否变化（Vite 内容寻址）
2. fetch 新 chunk grep 关键字符串确认新代码上线
3. 5 个门户路由全部 200

---

遗留事项 / 下次可继续

门户层面

1. 浏览器实测 nav 持久化无抖动（用户已确认部署，肉眼验证待做）
2. 翻译效果打磨（用户浏览后发现的不自然处随时改）
3. Pricing 数字 / 功能列表定稿（从 preview 转正式）
4. 后端 SOON 标记的功能落地：zero-log mode、priority scheduling
5. Pricing FAQ 中的 24 小时上线新模型 等承诺类文案核实

Admin / User 页面（之前搁置的两个决策）

• 决策 1：Admin reskin 深度（A 全局换肤 / B 深度 port 两页 / C 全量重写）
• 决策 2：User-facing 页面 vs Admin 页面优先级
• 推荐路径：Phase 2.1 全局换肤 → 2.2 user pages → 2.3 admin pages

仓库卫生

• backend/config.prod.yaml、backend/sub2api-linux、LOCAL_SETUP_NOTES.md 在某次意外的 git add -A 中被提交到 main。
• 用户判断：因 Gitea 是私有的，先不处理；仅要求前端层面不展示敏感信息（已通过 footer 清理实现）。
• 建议：下次添加配置 / 二进制类文件前，往 .gitignore 补规则（backend/config.*.yaml、backend/sub2api-* 等），避免再次误提。

---

经验教训

1. 不要 git add -A —— 主 worktree 里有累积的本地文件（生产配置、二进制、笔记），一次性 stage 会把这些都带进 commit。后续都用 git add <具体文件>。
2. 设计稿里的 nav = 3 份独立 HTML ≠ Vue 应该 3 份独立 template —— port 设计稿到 SPA 时，要把跨页共享的部分（nav、footer、layout shell）一开始就抽到 layout 组件。
3. Subagent 报告"我做完了"≠ 真的做对了 —— 73b39807 提交里 subagent 静默删掉了 <router-link> 退化成纯文本。事后 grep 读 commit diff 才发现。下次 subagent 处理 i18n 抽取时，prompt 里要明确"原始 HTML 标签如 <a>/<code>/<router-link> 必须保留，使用 <i18n-t> 命名 slot"。
4. fidelity port 优先靠 <i18n-t> + 命名 slot，不要把带行内标签的句子拍平成纯文本 —— 这点已经写进下次的 i18n 提示模板中。