Skip to content

feat(ui): phase 3 嵌入指南 — helper text、空状态与对话框文案 (#167)#189

Merged
g1331 merged 2 commits into
masterfrom
phase3-ui-embedded-guide
May 26, 2026
Merged

feat(ui): phase 3 嵌入指南 — helper text、空状态与对话框文案 (#167)#189
g1331 merged 2 commits into
masterfrom
phase3-ui-embedded-guide

Conversation

@g1331
Copy link
Copy Markdown
Owner

@g1331 g1331 commented May 25, 2026

范围

完成 issue #167 Phase 3:把 Phase 2 文档站里访客最容易踩到的关键提示反向嵌入管理后台 UI。改动全部落在已有展示位(FormDescription / 空状态文本 / DialogDescription),不新增组件、不新增路由、不引入新依赖。

改动清单

实例表单(CLIProxyAPI)

  • cliproxy-instance-form-dialog.tsx:mode 字段补 FormDescription,引用新增 i18n key fieldModeHint
  • cliproxy.fieldBaseUrlHint / fieldManagementUrlHint:扩充 localhost 陷阱说明,明确容器网络场景必须使用服务名

连通性检测

  • cliproxy-connection-result.tsx:在 result.status === "unreachable" 时复用现有展示位追加一行 testStatus_unreachable_hint,其余状态不显示

空状态文案

key
cliproxy.noInstances 暂无 CLIProxyAPI 实例 写明 sidecar 路径与登记按钮的关系
cliproxy.noAccounts 暂无 OAuth 账号 写明 OAuth 登录与同步两条路径
upstreams.noUpstreamsDesc 点击上方按钮添加第一个上游 说明需要至少一个上游客户端 Key 才能调用
keys.noKeys / noKeysDesc NO API KEYS FOUND 替换占位文案,写明 Bearer Token 调用与受限模式

对话框 description

key 改动
cliproxy.poolUpstreamDialogDescription 解释池上游聚合该实例该服务商全部账号
cliproxy.oauthLoginDescription 写明开始登录 → 浏览器授权 → 自动刷新账号的完整流程
upstreams.deleteUpstreamDesc / deleteUpstreamWarning 客户端 Key 立即无法路由 + 熔断器/统计/日志保留供审计
keys.revokeKeyDesc / revokeKeyWarning 客户端立即 401 + Key 保留供审计 + 需新建 Key 才能恢复

测试

  • tests/components/cliproxy-instance-form-dialog.test.tsx:补一条断言 fieldModeHint / fieldBaseUrlHint / fieldManagementUrlHint 三处 hint 渲染
  • 新增 tests/components/cliproxy-connection-result.test.tsx:覆盖 unreachable 显示 hint、其余三种状态(success / auth_failed / service_error)不显示

本地 pnpm exec tsc --noEmit / pnpm lint / pnpm test:run(148 files, 2494 tests)全过。

i18n 双语对齐

src/messages/zh-CN.jsonsrc/messages/en.json 同步新增 / 修改 14 条 key,关键新 key:fieldModeHinttestStatus_unreachable_hint

与 Phase 2 的边界

Phase 3 严格不写长文:超过两三行的解释一律留在文档站,UI 内只放摘要。本 PR 未引入文档站到 UI 的双向跳转链接(文档锚点暂未统一规划);若后续把 「了解更多」→ 文档站锚点 也嵌入,按 issue 描述也属于 Phase 3 范围内的后续微改。

Closes #167 Phase 3 主体。

Test plan

  • pnpm exec tsc --noEmit
  • pnpm lint
  • pnpm test:run(148 files / 2494 tests pass)
  • CI: Quality / Production Build / Migration Consistency / Proxy Stability / Playwright E2E / codecov 通过

把文档站里访客最容易踩到的点直接塞进管理后台的现有展示位,操作中
无需再跳转文档即可拿到关键提示。

实例表单
- mode 字段补 FormDescription,区分受管 sidecar 与外部服务
- fieldBaseUrlHint / fieldManagementUrlHint 扩充 localhost 陷阱说明,
  明确容器网络场景必须使用服务名

连通性检测
- CliproxyConnectionResult 在 unreachable 状态下额外渲染一行 hint,
  指出 Docker 网络下的服务名规则,复用现有展示位无新增组件

空状态文案
- cliproxy.noInstances / noAccounts:从「暂无 X」改写为「先做什么」
  引导,写明绑定第一个账号或登记 sidecar 的具体路径
- upstreams.noUpstreamsDesc:说明需要至少一个上游客户端 Key 才能调用
- keys.noKeys / noKeysDesc:替换原全大写占位文案,写明 Bearer Token
  调用方式与受限模式

对话框 description
- poolUpstreamDialogDescription:解释池上游聚合该实例下该服务商的
  全部 OAuth 账号
- oauthLoginDescription:写明开始登录、浏览器授权、自动刷新账号的
  完整流程
- deleteUpstreamDesc / Warning:写清「客户端 Key 立即无法路由」与
  「熔断器/统计/日志保留供审计」
- revokeKeyDesc / Warning:写清「客户端立即 401」与「Key 保留供审计、
  需新建 Key 才能恢复」

测试
- cliproxy-instance-form-dialog 增加 mode hint 渲染断言
- 新增 cliproxy-connection-result 测试覆盖 unreachable 时 hint 显示、
  其它三种状态不显示的条件分支

i18n 改动同步覆盖 zh-CN 与 en 两份文件。
@codecov
Copy link
Copy Markdown

codecov Bot commented May 25, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.09%. Comparing base (e262723) to head (8243ed2).
⚠️ Report is 1 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@            Coverage Diff             @@
##           master     #189      +/-   ##
==========================================
+ Coverage   74.05%   74.09%   +0.03%     
==========================================
  Files         147      147              
  Lines       11114    11115       +1     
  Branches     3846     3847       +1     
==========================================
+ Hits         8231     8236       +5     
+ Misses       1682     1677       -5     
- Partials     1201     1202       +1     
Flag Coverage Δ
verify 74.09% <100.00%> (+0.03%) ⬆️
🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…#167)

review 指出两处问题,本次一并修复。

noKeysDesc 事实错误
- 原文引用「受限模式」/「restricted mode」作为创建 Key 表单的标签,
  但 src/components/admin/create-key-dialog.tsx L325-352 实际渲染的
  两个选项标签是 unrestrictedAccess / restrictedAccess,i18n 文案
  分别对应「不限上游」/「指定上游」「Specific Upstreams」,从未出
  现「受限模式」这一字面值。
- 原文还承诺「可以限制可调用的模型或上游」,但 access_mode 字段
  仅控制 upstream_ids 白名单,payload 中没有模型限制,从未限制模型。
- 改为指向真实标签「指定上游」/「Specific Upstreams」,并去掉模型
  限制的虚假能力承诺。

poolUpstreamDialogDescription 语用调整
- zh 删除起句的「一键」,en 删除「in one click」。
- 与 CLAUDE.md 规范书面用语风格保持一致,避免互联网产品宣传腔。

零代码改动,纯 i18n 文案修复;JSON 合法性、tsc、lint、148 files /
2494 tests 全部通过。
@g1331 g1331 merged commit c89f69d into master May 26, 2026
12 checks passed
@g1331 g1331 deleted the phase3-ui-embedded-guide branch May 26, 2026 13:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: 建立文档体系(34 篇 + VitePress 静态站 + UI 内嵌指南)

1 participant