From 6e948109732a51c23685f447a3a82b49c905c709 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Thu, 23 Jul 2026 20:26:48 +0800
Subject: [PATCH] feat(gui): carry the question detail field over the wire and
 render it

AskUserQuestionItem.detail is part of the user-interaction seam contract
but the web frame schema dropped it and the composer never rendered it
(review r3635427108). askUserQuestionItemSchema now forwards detail, the
composer renders it under the title in the description text style, and
the fixture's multi-select question carries one.
---
 packages/client/connection/src/client/fixture.ts          | 1 +
 .../ui-question/src/client/QuestionComposer.module.css    | 8 ++++++++
 .../client/ui-question/src/client/QuestionComposer.tsx    | 1 +
 .../client/ui-question/tests/question-composer.spec.tsx   | 4 ++++
 packages/host/apiproxy/src/api/events.schema.ts           | 1 +
 5 files changed, 15 insertions(+)

diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index e26b9098a6..d609009bc1 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -307,6 +307,7 @@ export function createFixtureApi(): ApiProxy {
       id: 'signals',
       header: '信号',
       question: '哪些面试信号最重要？',
+      detail: '按当前招聘目标选择；跳过则视为不设偏好。',
       multiSelect: true,
       options: [
         { label: '系统设计' },
diff --git a/packages/client/ui-question/src/client/QuestionComposer.module.css b/packages/client/ui-question/src/client/QuestionComposer.module.css
index 21cd664ee3..e41a76caae 100644
--- a/packages/client/ui-question/src/client/QuestionComposer.module.css
+++ b/packages/client/ui-question/src/client/QuestionComposer.module.css
@@ -59,6 +59,14 @@
   white-space: nowrap;
 }
 
+.detail {
+  margin: 2px 0 0;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 13px;
+  line-height: 20px;
+  font-weight: 400;
+}
+
 .headerActions,
 .footerActions {
   display: flex;
diff --git a/packages/client/ui-question/src/client/QuestionComposer.tsx b/packages/client/ui-question/src/client/QuestionComposer.tsx
index c85d731287..3571263f61 100644
--- a/packages/client/ui-question/src/client/QuestionComposer.tsx
+++ b/packages/client/ui-question/src/client/QuestionComposer.tsx
@@ -171,6 +171,7 @@ function QuestionFlow({ pending }: { pending: PendingQuestion }) {
                 : question.question}</span>
               {question.multiSelect === true && <span className={css.multiSelectHint}>可多选</span>}
             </h2>
+            {question.detail !== undefined && <p className={css.detail}>{question.detail}</p>}
           </div>
           <div className={css.headerActions}>
             <span className={css.progress}>{index + 1} / {questions.length}</span>
diff --git a/packages/client/ui-question/tests/question-composer.spec.tsx b/packages/client/ui-question/tests/question-composer.spec.tsx
index 87e6ad36b4..9a8ac9bb57 100644
--- a/packages/client/ui-question/tests/question-composer.spec.tsx
+++ b/packages/client/ui-question/tests/question-composer.spec.tsx
@@ -27,6 +27,7 @@ const kit = {
 const QUESTIONS = [
   {
     id: 'profile', header: '偏好', question: '选择候选人类型',
+    detail: '按当前空缺岗位的优先级选择。',
     options: [
       { label: '工程落地型 (Recommended)', description: '优先工程交付。' },
       { label: '研究潜力型', description: '优先研究能力。' },
@@ -64,11 +65,14 @@ describe('QuestionComposer', () => {
     expect(screen.getByText('1 / 3')).toBeTruthy()
     expect(screen.getByText('推荐')).toBeTruthy()
     expect(screen.getByText('工程落地型')).toBeTruthy()
+    expect(screen.getByText('按当前空缺岗位的优先级选择。')).toBeTruthy()
     fireEvent.keyDown(screen.getByRole('radio', { name: /工程落地型/ }), { key: 'Enter' })
     expect(respond).not.toHaveBeenCalled()
     fireEvent.click(screen.getByRole('radio', { name: /工程落地型/ }))
 
     expect(screen.getByText('2 / 3')).toBeTruthy()
+    // detail is per-question: the second question carries none.
+    expect(screen.queryByText('按当前空缺岗位的优先级选择。')).toBeNull()
     expect(screen.queryByRole('button', { name: '填写答案' })).toBeNull()
     const custom = screen.getByPlaceholderText('输入你的答案')
     fireEvent.change(custom, { target: { value: '要能独立排查线上问题' } })
diff --git a/packages/host/apiproxy/src/api/events.schema.ts b/packages/host/apiproxy/src/api/events.schema.ts
index 0e7dda1667..6d7e23765c 100644
--- a/packages/host/apiproxy/src/api/events.schema.ts
+++ b/packages/host/apiproxy/src/api/events.schema.ts
@@ -17,6 +17,7 @@ export const askUserQuestionItemSchema = z.object({
   id: z.string(),
   question: z.string(),
   header: z.string().optional(),
+  detail: z.string().optional(),
   options: z.array(z.object({ label: z.string(), description: z.string().optional() })).optional(),
   multiSelect: z.boolean().optional(),
 }) satisfies z.ZodType<Wire<AskUserQuestionItem>>