docs: add downstream key ui and site link plan
This commit is contained in:
ciat-777
@@ -0,0 +1,67 @@
|
|||||||
|
# Downstream Key UI And Site Links Design
|
||||||
|
|
||||||
|
**Goal:** Unify the downstream key page with the restrained management-console style already used by the sites and accounts pages, and make site entry points behave consistently across pages.
|
||||||
|
|
||||||
|
**Context**
|
||||||
|
|
||||||
|
The current downstream key page is functionally rich but visually heavier than the rest of the console. It relies on dense inline styling and presents summary, filters, and row content with a stronger dashboard tone than the nearby management pages.
|
||||||
|
|
||||||
|
At the same time, site references are inconsistent. The accounts page already exposes a hoverable, clickable site badge that navigates back to site management with focus context. Other pages such as models, proxy logs, token routes, and downstream keys do not consistently reuse that interaction.
|
||||||
|
|
||||||
|
**User-Approved Direction**
|
||||||
|
|
||||||
|
- Align downstream key visuals with the existing `站点管理 / 连接管理` style.
|
||||||
|
- Reuse the same site button interaction already present on the accounts page.
|
||||||
|
- Prefer direct reuse over inventing a new visual pattern.
|
||||||
|
|
||||||
|
## Design
|
||||||
|
|
||||||
|
### 1. Downstream key page visual alignment
|
||||||
|
|
||||||
|
Keep the data model and operations unchanged, but reduce the visual mismatch:
|
||||||
|
|
||||||
|
- Keep the existing `page-header`, `card`, and `data-table` structure.
|
||||||
|
- Restyle summary/filter regions to read like management controls rather than dashboard hero sections.
|
||||||
|
- Preserve the drawer/details flow, but make the main list view feel closer to `Sites.tsx` and `Accounts.tsx`.
|
||||||
|
- Replace repeated ad-hoc chip/button styling where possible with the same badge/link language already used elsewhere.
|
||||||
|
|
||||||
|
This is intentionally a presentation cleanup, not a workflow redesign.
|
||||||
|
|
||||||
|
### 2. Shared site button behavior
|
||||||
|
|
||||||
|
Extract the accounts page site badge behavior into a reusable component:
|
||||||
|
|
||||||
|
- Same hover affordance.
|
||||||
|
- Same visual style.
|
||||||
|
- Same navigation target: `/sites?focusSiteId=<id>`.
|
||||||
|
- Graceful fallback when `siteId` is missing or invalid.
|
||||||
|
|
||||||
|
Pages to update:
|
||||||
|
|
||||||
|
- `src/web/pages/Models.tsx`
|
||||||
|
- `src/web/pages/ProxyLogs.tsx`
|
||||||
|
- `src/web/pages/TokenRoutes.tsx`
|
||||||
|
- `src/web/pages/DownstreamKeys.tsx`
|
||||||
|
|
||||||
|
The `Sites.tsx` page itself continues to use direct external URL links, because those links serve a different purpose.
|
||||||
|
|
||||||
|
### 3. Testing approach
|
||||||
|
|
||||||
|
Cover the change with focused UI tests:
|
||||||
|
|
||||||
|
- One shared component test for hover/click navigation behavior.
|
||||||
|
- Page-level regression tests where existing snapshots/assertions are already present.
|
||||||
|
- Keep tests narrow: validate that site labels render with the shared class/behavior and navigate to the focused site management route.
|
||||||
|
|
||||||
|
## Risks
|
||||||
|
|
||||||
|
- `TokenRoutes.tsx` contains multiple kinds of site labels; only labels intended to behave like the accounts page should be converted.
|
||||||
|
- `DownstreamKeys.tsx` may not currently expose enough site metadata in every row; if site links are only meaningful in detail regions, apply the shared component there instead of forcing low-value links into the table.
|
||||||
|
- Visual cleanup should not destabilize mobile layout or row actions.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- The downstream key page looks consistent with the restrained management-console pages.
|
||||||
|
- Site entry points in models, proxy logs, token routes, and downstream keys match the accounts page interaction.
|
||||||
|
- Hover and navigation behavior are consistent.
|
||||||
|
- Existing relevant tests pass, and new tests cover the shared site link behavior.
|
||||||
@@ -0,0 +1,160 @@
|
|||||||
|
# Downstream Key UI And Site Links Implementation Plan
|
||||||
|
|
||||||
|
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||||
|
|
||||||
|
**Goal:** Restyle the downstream key page to match the restrained management-console pages and standardize site buttons across pages using the accounts page interaction.
|
||||||
|
|
||||||
|
**Architecture:** Introduce one shared site link component based on the accounts page behavior, then update each affected page to consume it. Refactor downstream key layout styling toward existing `card`, `badge`, and `data-table` patterns without changing backend behavior.
|
||||||
|
|
||||||
|
**Tech Stack:** React, TypeScript, React Router, Vitest, React Test Renderer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 1: Extract the shared site button
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Create: `src/web/components/SiteBadgeLink.tsx`
|
||||||
|
- Test: `src/web/components/site-badge-link.test.tsx`
|
||||||
|
- Modify: `src/web/pages/Accounts.tsx`
|
||||||
|
- Modify: `src/web/index.css`
|
||||||
|
|
||||||
|
**Step 1: Write the failing test**
|
||||||
|
|
||||||
|
Add a component test that renders a site badge link and asserts:
|
||||||
|
- it renders the site name,
|
||||||
|
- it has the shared interactive class,
|
||||||
|
- clicking navigates to `/sites?focusSiteId=<id>`.
|
||||||
|
|
||||||
|
**Step 2: Run test to verify it fails**
|
||||||
|
|
||||||
|
Run: `npm test -- src/web/components/site-badge-link.test.tsx`
|
||||||
|
|
||||||
|
Expected: FAIL because the component does not exist yet.
|
||||||
|
|
||||||
|
**Step 3: Write minimal implementation**
|
||||||
|
|
||||||
|
- Create a small component that wraps `Link` from `react-router-dom`.
|
||||||
|
- Accept `siteId`, `siteName`, and optional badge class props.
|
||||||
|
- Reproduce the accounts page badge-link styling and fallback behavior.
|
||||||
|
- Move the accounts page site badge rendering to this component.
|
||||||
|
- Add any missing shared CSS class if accounts currently relies on page-local styling.
|
||||||
|
|
||||||
|
**Step 4: Run test to verify it passes**
|
||||||
|
|
||||||
|
Run: `npm test -- src/web/components/site-badge-link.test.tsx src/web/pages/accounts.segmented-connections.test.tsx`
|
||||||
|
|
||||||
|
Expected: PASS
|
||||||
|
|
||||||
|
**Step 5: Commit**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add src/web/components/SiteBadgeLink.tsx src/web/components/site-badge-link.test.tsx src/web/pages/Accounts.tsx src/web/index.css
|
||||||
|
git commit -m "refactor: extract shared site badge link"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Task 2: Apply the shared site button across affected pages
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `src/web/pages/Models.tsx`
|
||||||
|
- Modify: `src/web/pages/ProxyLogs.tsx`
|
||||||
|
- Modify: `src/web/pages/TokenRoutes.tsx`
|
||||||
|
- Modify: `src/web/pages/DownstreamKeys.tsx`
|
||||||
|
- Test: `src/web/pages/Models.marketplace-text.test.tsx`
|
||||||
|
- Test: `src/web/pages/tokenRoutes.group-collapse.test.tsx`
|
||||||
|
- Test: `src/web/pages/DownstreamKeys.test.tsx`
|
||||||
|
|
||||||
|
**Step 1: Write failing assertions**
|
||||||
|
|
||||||
|
Add or update tests to assert the affected pages render the shared site button class and, where practical, point to the focused site management route.
|
||||||
|
|
||||||
|
**Step 2: Run test to verify it fails**
|
||||||
|
|
||||||
|
Run: `npm test -- src/web/pages/Models.marketplace-text.test.tsx src/web/pages/tokenRoutes.group-collapse.test.tsx src/web/pages/DownstreamKeys.test.tsx`
|
||||||
|
|
||||||
|
Expected: FAIL because the pages still use inconsistent site rendering.
|
||||||
|
|
||||||
|
**Step 3: Write minimal implementation**
|
||||||
|
|
||||||
|
- Replace page-local site label rendering with `SiteBadgeLink`.
|
||||||
|
- Only convert labels that represent navigable management-site references.
|
||||||
|
- Preserve non-site filters, external URLs, and unrelated badges.
|
||||||
|
|
||||||
|
**Step 4: Run test to verify it passes**
|
||||||
|
|
||||||
|
Run: `npm test -- src/web/pages/Models.marketplace-text.test.tsx src/web/pages/tokenRoutes.group-collapse.test.tsx src/web/pages/DownstreamKeys.test.tsx src/web/pages/ProxyLogs.server-driven.test.tsx`
|
||||||
|
|
||||||
|
Expected: PASS
|
||||||
|
|
||||||
|
**Step 5: Commit**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add src/web/pages/Models.tsx src/web/pages/ProxyLogs.tsx src/web/pages/TokenRoutes.tsx src/web/pages/DownstreamKeys.tsx src/web/pages/Models.marketplace-text.test.tsx src/web/pages/tokenRoutes.group-collapse.test.tsx src/web/pages/DownstreamKeys.test.tsx
|
||||||
|
git commit -m "feat: unify site badge navigation across pages"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Task 3: Restyle downstream keys page
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `src/web/pages/DownstreamKeys.tsx`
|
||||||
|
- Test: `src/web/pages/DownstreamKeys.test.tsx`
|
||||||
|
- Modify: `src/web/index.css`
|
||||||
|
|
||||||
|
**Step 1: Write failing assertions**
|
||||||
|
|
||||||
|
Add focused assertions for the downstream keys page structure where needed, such as shared management-page card classes, reduced bespoke styling hooks, or the new site badge placement.
|
||||||
|
|
||||||
|
**Step 2: Run test to verify it fails**
|
||||||
|
|
||||||
|
Run: `npm test -- src/web/pages/DownstreamKeys.test.tsx`
|
||||||
|
|
||||||
|
Expected: FAIL after adding assertions that reflect the updated restrained layout.
|
||||||
|
|
||||||
|
**Step 3: Write minimal implementation**
|
||||||
|
|
||||||
|
- Reduce the page’s dashboard-like presentation.
|
||||||
|
- Align summary, filters, and batch action sections with the same management-console card language used in sites/accounts.
|
||||||
|
- Reuse shared badge/link patterns instead of one-off visual treatments where practical.
|
||||||
|
- Keep operations, data fetching, and drawer behavior unchanged.
|
||||||
|
|
||||||
|
**Step 4: Run test to verify it passes**
|
||||||
|
|
||||||
|
Run: `npm test -- src/web/pages/DownstreamKeys.test.tsx`
|
||||||
|
|
||||||
|
Expected: PASS
|
||||||
|
|
||||||
|
**Step 5: Commit**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add src/web/pages/DownstreamKeys.tsx src/web/pages/DownstreamKeys.test.tsx src/web/index.css
|
||||||
|
git commit -m "style: align downstream key page with management UI"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Task 4: Final verification
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: none
|
||||||
|
|
||||||
|
**Step 1: Run targeted verification**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
- `npm test -- src/web/components/site-badge-link.test.tsx`
|
||||||
|
- `npm test -- src/web/pages/DownstreamKeys.test.tsx`
|
||||||
|
- `npm test -- src/web/pages/Models.marketplace-text.test.tsx`
|
||||||
|
- `npm test -- src/web/pages/tokenRoutes.group-collapse.test.tsx`
|
||||||
|
- `npm test -- src/web/pages/ProxyLogs.server-driven.test.tsx`
|
||||||
|
- `npm test -- src/web/pages/accounts.segmented-connections.test.tsx`
|
||||||
|
|
||||||
|
Expected: PASS
|
||||||
|
|
||||||
|
**Step 2: Run broader sanity verification if time permits**
|
||||||
|
|
||||||
|
Run: `npm test -- src/web/App.sidebar.test.ts src/web/App.sidebar-mobile.test.tsx`
|
||||||
|
|
||||||
|
Expected: PASS
|
||||||
|
|
||||||
|
**Step 3: Commit final polish**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add -A
|
||||||
|
git commit -m "test: verify downstream key UI and site link consistency"
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user