docs(rectification): record the surface redo — BUG-505..509, DESIGN.md rectification surface, walkthrough section 8
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JUei7K13cYxLHE3Axe4A45
This commit is contained in:
Jesse_Chen
@@ -200,6 +200,31 @@ The base unit is 4px. Tokens are `--space-1: 4px`, `--space-2: 8px`, `--space-3:
|
||||
- **Surface:** canvas fill, hairline border, `--shadow-elevated`; hover uses the warm card surface. No utility-class shadows.
|
||||
- **Accessibility:** a real button in document order with a visible label matching its accessible name, 44px target, and the focus ring; the icon is decorative.
|
||||
|
||||
### Rectification surface
|
||||
|
||||
The birth-time rectification session is the consultation transcript plus a house board; questions live inside the assistant message that asked them. It shares every waiting vocabulary with the consultation surface; nothing here spins or says "loading" after the reveal.
|
||||
|
||||
- **Reveal:** the surface mounts once per session/Case binding. Opening a Case (homepage card, sidebar row, deep link or refresh) reads the turns and the snapshot in one Case request before the switch, under the same 4-second budget as the home reveal (`RECTIFICATION_OPEN_HYDRATE_TIMEOUT_MS` is `BOOTSTRAP_PREPARE_TIMEOUT_MS`); a session selected at bootstrap is hydrated during the prepare phase. The entry shows a static note meanwhile (card footer “正在打开…”, sidebar row “打开中”, `cursor: progress`) and the previous view stays put. Turns and snapshot are initial state; anything that arrives later is a prop or state update, never a remount. A late or failed read still reveals, with the composer notice “校正记录没有完全加载，可以继续”.
|
||||
- **States** — what the transcript's trailing entry and the composer show:
|
||||
|
||||
| State | Trailing entry | Composer |
|
||||
|---|---|---|
|
||||
| `opening` | live row “正在读取你的出生资料，准备第一个问题…”, then tool labels | disabled, stop visible |
|
||||
| `empty` | “这段校正还没有开始。” and one primary action “开始提问” | enabled |
|
||||
| `question-live` | the asking message carries the embedded card or the spoken stem | enabled, placeholder points at the card |
|
||||
| `question-gap`, retries left | one timeline live row “正在准备下一个问题…”, refetching on a 2s timer up to two retries | enabled |
|
||||
| `question-gap`, retries spent | “没有拿到下一个问题。” and a 44px “重新加载” | enabled |
|
||||
| `choice-pending` | the answered card (`Check` + “已选择”, a top row “正在记录…”) and the same live row from “正在记录本次选择…” through the follow-up turn | disabled, stop visible |
|
||||
| `candidates` | the offer cards under the message that offered them | enabled |
|
||||
| `adopting` | “正在采用 HH:MM…” through the follow-up turn | disabled during the chain |
|
||||
| `confirmed` | “已确认校正时间：HH:MM” | enabled |
|
||||
| `readonly` | “该校正已结束，只能查看历史。” and “再次校正” | disabled |
|
||||
| stopped | the row settles with what streamed; notice “已停止，已生成的内容保留；本次不会扣点。” | enabled |
|
||||
|
||||
- **Rules:** a follow-up turn continues on the live row already in place; `busy` never drops in the middle of a chain. No copy may ask the reader to wait for the server; a gap is a live row with retries, then a reload button. A hydration that timed out is the same gap. A 402 shows “校正点数不足，正在前往兑换…” for 600ms before the page leaves.
|
||||
- **Board:** before any candidate exists the header clock shows the declared birth minute and the body reads “填报出生时间 HH:MM” / “回答几个问题后，这里会显示宫位随时间的变化。”; the column narrows to `minmax(16rem, 18rem)` (`is-board-empty`) and widens once a result arrives. No house table is invented for the declared time; the snapshot API does not provide one.
|
||||
- **Accessibility:** the sidebar opening note sets `aria-busy`; the live row is the timeline row (`role="status"` shimmer label); the reload and start actions are real 44px buttons.
|
||||
|
||||
### Birth time intake
|
||||
|
||||
- **Structure:** birth date, five radio choice rows for time knowledge, then only the time, uncertainty, period, or clue field required by the selected source.
|
||||
@@ -407,6 +432,8 @@ or user IDs.
|
||||
|
||||
Agent 的 live 标记只有 `InlineSpinner` 一种。曾经并存的 canvas 小球（`thinking-orbs`）已移除，不得再引入第二种 live 标记。
|
||||
|
||||
校正面的所有等待复用行内等待：进入前的 hydration 在揭幕之前完成，进入后唯一的等待形态是时间线 live 行（含「正在准备下一个问题…」这一条独立 live 行）。
|
||||
|
||||
首页只揭幕一次。揭幕前的加载屏分两阶段：先取账户、模型目录与会话列表，再并行取当前会话消息、推荐问题、今日星语与校正入口摘要，并预热校正分包；全部就绪或 4 秒预算到期（`BOOTSTRAP_PREPARE_TIMEOUT_MS`）才揭幕。揭幕后不得再出现任何阻塞等待或组件级 spinner：推荐问题未到显示安全默认问题，今日星语未到显示静态文案「今天的星语还没写出来。」（不带 `aria-busy`），校正卡用无摘要文案，内容到达后静默替换。切换到消息尚未缓存的会话时消息区留白并只给 `sr-only` 文案，不转圈；揭幕后按侧栏顺序后台预取最近 5 条会话（`SESSION_PREFETCH_COUNT`）让常见切换零等待。轨道环消失后不得再换一套动效继续等。
|
||||
|
||||
Admin 的 antd `<Spin>` 是独立设计系统，不在此表。
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { readFileSync } from "node:fs";
|
||||
import test from "node:test";
|
||||
|
||||
import { homeSurface as page } from "./home-surface.ts";
|
||||
|
||||
const read = (relativePath: string) => readFileSync(new URL(relativePath, import.meta.url), "utf8");
|
||||
const chat = read("../src/components/rectification-agentic-chat.tsx");
|
||||
const hook = read("../src/hooks/use-rectification-surface.ts");
|
||||
const sessions = read("../src/hooks/use-session-management.ts");
|
||||
const bootstrap = read("../src/lib/home-bootstrap.ts");
|
||||
const starter = read("../src/components/starter-home.tsx");
|
||||
const sidebarRow = read("../src/components/sidebar-session-row.tsx");
|
||||
const board = read("../src/components/rectification-board.tsx");
|
||||
const choiceCard = read("../src/components/rectification-choice-card.tsx");
|
||||
const wrapper = read("../src/components/conversational-birth-time-rectification.tsx");
|
||||
const timeline = read("../src/components/consultation-run-timeline.tsx");
|
||||
const styles = read("../src/app/globals.css");
|
||||
|
||||
test("the rectification surface is revealed once: Case hydration precedes the switch and the key never remounts", () => {
|
||||
// BUG-505: open → hydrate (turns + snapshot, one Case read, deadline) → switch, in that order.
|
||||
assert.match(hook, /const hydration = await hydrateRectificationCase\(opened\.caseId, opened\.sessionId, \{\s*timeoutMs: RECTIFICATION_OPEN_HYDRATE_TIMEOUT_MS,/);
|
||||
const openBody = hook.slice(hook.indexOf("const hydration = await hydrateRectificationCase"), hook.indexOf("void refreshRectificationEntrySummary();"));
|
||||
assert.match(openBody, /setRectificationTurns\(hydration\.turns\);[\s\S]*setRectificationSnapshot\(hydration\.snapshot\);[\s\S]*setActiveSessionId\(opened\.sessionId\);/);
|
||||
assert.match(openBody, /if \(!hydration\.complete\) setComposerNotice\(RECTIFICATION_HYDRATION_INCOMPLETE_NOTICE\);/);
|
||||
assert.doesNotMatch(hook, /void refreshRectificationCase\(opened\.caseId/);
|
||||
// The selection source is read before any await; selectSession resets it synchronously.
|
||||
assert.match(hook, /const selectionSource = sessionSelectionSource\.current;[\s\S]*await fetch\("\/api\/rectification\/cases\/open"/);
|
||||
assert.match(hook, /selectionSource === "user"\) \{\s*writeSessionUrl\(opened\.sessionId, "push"\)/);
|
||||
// selectSession does not switch to a rectification session before its Case is hydrated.
|
||||
assert.match(sessions, /const deferredRectificationSwitch = nextSession\?\.sessionType === "birth_time_rectification"\s*&& nextSession\.id !== rectificationSessionId;/);
|
||||
assert.match(sessions, /if \(!deferredRectificationSwitch\) setActiveSessionId\(sessionId\);/);
|
||||
assert.match(sessions, /if \(!deferredRectificationSwitch && !uiPreview\.current && sessionSelectionSource\.current === "user"\) \{\s*writeSessionUrl\(sessionId, "push"\);/);
|
||||
// Panel: one key per binding, snapshot and turns as initial state, later turns as a prop update.
|
||||
assert.match(page, /key=\{`\$\{rectificationSessionId\}-\$\{rectificationCaseId\}`\}/);
|
||||
assert.doesNotMatch(page, /"ready" : "loading"/);
|
||||
assert.match(page, /initialSnapshot=\{rectificationSnapshot\}/);
|
||||
assert.match(page, /declaredTime=\{rectificationDeclaredTime\}/);
|
||||
assert.match(wrapper, /initialSnapshot: RectificationCaseSnapshotPayload \| null;/);
|
||||
assert.match(chat, /useState\(initialSnapshot !== null\)/);
|
||||
// Later turns fill an empty transcript by render-time adjustment from the previous prop, not an effect.
|
||||
assert.match(chat, /const \[seededTurns, setSeededTurns\] = useState\(initialTurns\);\s*if \(seededTurns !== initialTurns\) \{\s*setSeededTurns\(initialTurns\);\s*if \(messages\.length === 0 && initialTurns\.length > 0\) setMessages\(messagesFromTurns\(initialTurns\)\);/);
|
||||
// No self-fetch on mount; unmount ends the stream and any snapshot read.
|
||||
assert.doesNotMatch(chat, /useEffect\(\(\) => \{\s*const controller = new AbortController\(\);\s*void fetch\(/);
|
||||
assert.match(chat, /useEffect\(\(\) => \(\) => \{\s*runAbort\.current\?\.abort\(\);\s*snapshotAbort\.current\?\.abort\(\);\s*\}, \[\]\);/);
|
||||
});
|
||||
|
||||
test("a rectification session selected at bootstrap is hydrated before the reveal, and popstate defers the same way", () => {
|
||||
// The resume effect runs during the prepare phase, not only after the reveal.
|
||||
assert.match(page, /if \(\(!hydrated && bootstrapPhase === "account"\)\s*\|\| !account/);
|
||||
assert.match(bootstrap, /if \(state\.rectificationApplicable && !state\.rectificationSettled\) return false;/);
|
||||
assert.match(page, /rectificationApplicable: activeSession\?\.sessionType === "birth_time_rectification",\s*rectificationSettled: activeSession\?\.id === rectificationSessionId\s*\|\| rectificationError !== ""\s*\|\| !profileComplete,/);
|
||||
// One deadline constant for hydration and the home reveal.
|
||||
assert.match(read("../src/lib/rectification-surface-state.ts"), /export const RECTIFICATION_OPEN_HYDRATE_TIMEOUT_MS = BOOTSTRAP_PREPARE_TIMEOUT_MS;/);
|
||||
// History navigation goes through selectSession, which defers the switch (locked above).
|
||||
assert.match(sessions, /sessionSelectionSource\.current = "history";\s*selectSession\(requestedId\);/);
|
||||
});
|
||||
|
||||
test("entry feedback is static: card and sidebar row say 正在打开, and nothing spins after the reveal", () => {
|
||||
assert.match(page, /const rectificationCardLabel = rectificationLoading\s*\? RECTIFICATION_OPENING_LABEL/);
|
||||
assert.match(starter, /data-opening=\{rectificationLoading \? "true" : undefined\}/);
|
||||
assert.doesNotMatch(starter, /InlineSpinner/);
|
||||
assert.match(sidebarRow, /aria-busy=\{opening \? true : undefined\}/);
|
||||
assert.match(sidebarRow, /RECTIFICATION_SIDEBAR_OPENING_NOTE/);
|
||||
assert.match(page, /openingSessionId=\{rectificationOpeningSessionId\}/);
|
||||
assert.match(styles, /\.product-entrypoint-card\[data-opening="true"\][^{]*\{ cursor: progress; \}/);
|
||||
assert.match(styles, /\.session-opening-note \{/);
|
||||
// The only spinner inside the chat is a timeline live row (generation), never a loading state.
|
||||
assert.equal((chat.match(/InlineSpinner/g) ?? []).length, 0);
|
||||
assert.match(timeline, /export function ConsultationTimelineLiveRow/);
|
||||
assert.match(chat, /<ConsultationTimelineLiveRow id="question-preparing" label=\{RECTIFICATION_QUESTION_PREPARING_LABEL\} \/>/);
|
||||
});
|
||||
|
||||
test("the question gap is a live row with retries, then a reload; it never tells the reader to wait for the server", () => {
|
||||
assert.doesNotMatch(chat, /等待服务端更新|题目加载失败，请刷新|rectification-composer-status/);
|
||||
assert.doesNotMatch(chat, /showMissingQuestion|showUnavailableQuestion|showQuestionLoadFailed/);
|
||||
assert.match(chat, /const questionGap = rectificationQuestionGapState\(\{/);
|
||||
assert.match(chat, /questionGap === "preparing" && \(/);
|
||||
assert.match(chat, /questionGap === "unavailable" && \(/);
|
||||
assert.match(chat, /RECTIFICATION_QUESTION_UNAVAILABLE_COPY/);
|
||||
assert.match(chat, /RECTIFICATION_QUESTION_RELOAD_LABEL/);
|
||||
assert.match(chat, /useVisibilityAwarePoll\(\{\s*enabled: questionGap === "preparing",\s*intervalMs: RECTIFICATION_QUESTION_RETRY_INTERVAL_MS,/);
|
||||
// Attempts reset in handlers (a question arriving, a turn starting), never in an effect.
|
||||
assert.match(chat, /if \(nextQuestion !== null\) setQuestionRetryAttempts\(0\);/);
|
||||
assert.match(chat, /if \(value\) setQuestionRetryAttempts\(0\);/);
|
||||
assert.doesNotMatch(chat, /useEffect\(\(\) => \{\s*if \(currentQuestion !== null/);
|
||||
// In flow: the gap is the last entry of the transcript, after the message loop, before the saved-time line.
|
||||
const gapIndex = chat.indexOf('{questionGap === "preparing" && (');
|
||||
assert.ok(gapIndex > chat.indexOf("{messages.map((message) => {"));
|
||||
assert.ok(gapIndex < chat.indexOf("{savedTime && savedStatus === \"confirmed\""));
|
||||
assert.match(styles, /\.rectification-question-gap \{/);
|
||||
});
|
||||
|
||||
test("a tapped choice or an adopted candidate keeps one live row through the follow-up turn", () => {
|
||||
// BUG-506: no effect hop, no removed row, busy held across the chain.
|
||||
assert.doesNotMatch(chat, /choiceContinuationPending/);
|
||||
assert.match(chat, /const send = useCallback\(async \(\s*action: "opening" \| "message" \| "read_only",\s*messageText: string,\s*continuation\?: Readonly<\{ reuseAssistantRenderKey: string; label: string \}>,/);
|
||||
assert.match(chat, /if \(!continuation && busy\) return;/);
|
||||
assert.match(chat, /const initialLabel = rectificationInitialLiveLabel\(action, continuation\?\.label\);/);
|
||||
assert.match(chat, /beginLiveRun\(initialLabel\);/);
|
||||
assert.match(chat, /await send\("read_only", "", \{ reuseAssistantRenderKey: assistantRenderKey, label: recordingLabel \}\);/);
|
||||
assert.match(chat, /await send\("read_only", "", \{ reuseAssistantRenderKey: assistantRenderKey, label: adoptingLabel \}\);/);
|
||||
assert.match(chat, /rectificationAdoptingLabel\(candidateTime\)/);
|
||||
assert.doesNotMatch(chat, /current\.filter\(\(message\) => message\.renderKey !== assistantRenderKey\),\s*turns,\s*\)\);/);
|
||||
});
|
||||
|
||||
test("an empty Case with no automatic opening offers a way to start", () => {
|
||||
// BUG-507
|
||||
assert.match(chat, /conversationState === "empty" && \(/);
|
||||
assert.match(chat, /RECTIFICATION_EMPTY_COPY/);
|
||||
assert.match(chat, /onClick=\{startOpeningManually\}>\{RECTIFICATION_EMPTY_ACTION_LABEL\}/);
|
||||
assert.match(chat, /function startOpeningManually\(\) \{\s*if \(readonly \|\| busy \|\| openingStarted\.current\) return;\s*openingStarted\.current = true;/);
|
||||
assert.match(styles, /\.rectification-empty-state \{/);
|
||||
});
|
||||
|
||||
test("stopping keeps what streamed and says so; a 402 explains itself before leaving", () => {
|
||||
assert.match(chat, /if \(raw\.trim\(\)\) setError\(RECTIFICATION_STOPPED_NOTICE\);/);
|
||||
assert.match(chat, /setError\(RECTIFICATION_INSUFFICIENT_CREDITS_NOTICE\);[\s\S]*window\.setTimeout\(\(\) => \{\s*window\.location\.assign\(membershipHref\("rectification"\)\);\s*\}, RECTIFICATION_INSUFFICIENT_CREDITS_REDIRECT_MS\);/);
|
||||
});
|
||||
|
||||
test("the choice card confirms the tap and the board's first state shows the declared minute", () => {
|
||||
// BUG-508
|
||||
assert.match(choiceCard, /<Check aria-hidden="true" \/>/);
|
||||
assert.match(choiceCard, /已选择/);
|
||||
assert.match(choiceCard, /rectification-choice-card__pending/);
|
||||
assert.match(choiceCard, /InlineSpinner size=\{12\}/);
|
||||
assert.match(styles, /\.rectification-choice-card__selected \{/);
|
||||
assert.match(styles, /\.rectification-choice-card__pending \{/);
|
||||
// BUG-509
|
||||
assert.match(board, /declaredTime: string \| null;/);
|
||||
assert.match(board, /rectificationBoardEmptyCopy\(declaredTime\)/);
|
||||
assert.match(board, /rectificationBoardPeekCopy\(result, declaredTime\)/);
|
||||
assert.doesNotMatch(board, /补充经历后，这里会显示当前本命宫位和换升时刻/);
|
||||
assert.match(chat, /\$\{candidateResult \? "" : " is-board-empty"\}/);
|
||||
assert.match(styles, /\.rectification-workspace\.is-board-empty \{\s*grid-template-columns: minmax\(0, 1fr\) minmax\(16rem, 18rem\);/);
|
||||
// The empty modifier is declared before `.is-compact`, so the single-column layout still wins.
|
||||
assert.ok(styles.indexOf(".rectification-workspace.is-board-empty {") < styles.indexOf(".rectification-workspace.is-compact {"));
|
||||
});
|
||||
Reference in New Issue
Block a user