From 0d2cc2aac0418fe518551ad745fec4bf00eb894f Mon Sep 17 00:00:00 2001
From: chenyuan <chenyuan@example.com>
Date: Thu, 6 Aug 2026 19:47:38 +0800
Subject: [PATCH] docs: specify AI help question flow

---
 .../2026-08-06-ai-help-question-design.md     | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-06-ai-help-question-design.md

diff --git a/docs/superpowers/specs/2026-08-06-ai-help-question-design.md b/docs/superpowers/specs/2026-08-06-ai-help-question-design.md
new file mode 100644
index 0000000..ae287d8
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-06-ai-help-question-design.md
@@ -0,0 +1,34 @@
+# AI 助学问题传递设计
+
+## 目标
+
+使学生在 AI 助学输入框中填写或点击参考提示词填入的问题，真实参与模型生成；每次有效提问均生成一份新的助学建议。
+
+## 请求与校验
+
+- 前端 `POST /api/student/training-tasks/{taskKey}/ai-evaluation/help` 的请求体为 `{ "question": "..." }`。
+- 前端在空白问题时不发送请求，并提示学生输入问题或点击参考提示词。
+- 后端去除首尾空白后校验问题非空，且长度不超过 500 个字符；不符合要求时返回业务错误。
+
+## 模型上下文
+
+后端将以下内容传给 AI：
+
+1. 当前任务的背景、目标、要求；
+2. 学生已保存的实训作答；
+3. 本次学生问题。
+
+问题和作答快照将一起保存到既有的助学作答快照字段，不新增数据库表或字段。
+
+## 重复提问与并发
+
+- 每次通过校验的助学请求都应重新调用模型，并覆盖原有助学报告。
+- 已完成状态不再阻止新的助学请求。
+- `PROCESSING` 状态继续阻止并发调用；并发请求直接返回当前状态。
+- AI 评分接口及其状态规则不作改动。
+
+## 验证
+
+- 后端控制器测试验证问题体被传入服务层。
+- 服务测试验证问题进入模型提示词、已完成的助学记录可重新生成、空问题不调用模型。
+- 前端静态测试验证问题随请求提交，并在空问题时阻止发送。