From 791a02fed48c11c8551af24e2e929eb0443389a2 Mon Sep 17 00:00:00 2001
From: chenyuan <chenyuan@example.com>
Date: Fri, 7 Aug 2026 15:14:42 +0800
Subject: [PATCH] docs: specify product development factors step four

---
 ...roduct-development-factors-step4-design.md | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-07-product-development-factors-step4-design.md

diff --git a/docs/superpowers/specs/2026-08-07-product-development-factors-step4-design.md b/docs/superpowers/specs/2026-08-07-product-development-factors-step4-design.md
new file mode 100644
index 0000000..619cc07
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-07-product-development-factors-step4-design.md
@@ -0,0 +1,48 @@
+# 产品开发关键因素第 4 步设计
+
+## 目标
+
+为学生端“产品开发关键因素”实训补齐第 4 步总结页。学生结合案例资料及前三步分析，填写成功产品与失败产品的关键因素；两个输入都完成后提交整个任务。
+
+## 范围与约束
+
+- 仅修改学生端页面及学生答案校验接口；不调整教师端、任务配置端或其他模块。
+- 在当前 `codex/product-development-factors-step3` 隔离分支继续开发，因此最终功能分支包含第 3、4 步，后续一次性合并。
+- 不新增数据库表或字段：第 4 步内容使用现有答案记录的 `step4Answer`，进度保持为 `currentStep: 4`。
+- 最终提交动作固定使用 `saveAction: "SUBMIT"` 与 `submitted: true`；不得在提交成功后跳转至不存在的下一步。
+
+## 学生页面
+
+当 `currentStep === 3` 时，显示说明：“结合案例信息及前述步骤，分析案例资料中产品一成功的关键因素是什么，产品二失败的关键因素是什么。”
+
+展示两个大文本框：
+
+1. 产品成功的关键因素
+2. 产品失败的关键因素
+
+两个输入去除首尾空白后都必须有内容。提交按钮为“提交任务”，并提供既有“清空填写”按钮。草稿、保存答案加载和导出内容均包含第 4 步；清空操作同时清除前四步。
+
+提交成功后保留在第 4 步，显示“任务提交成功”。重复点击时沿用现有 `saving` 防抖；接口校验失败时显示服务端错误信息。
+
+## 前端数据流
+
+- 使用 `stepFourForm` 保存 `successFactors`、`failedFactors`。
+- `buildDraft` 添加 `stepFour`；加载 `step4Answer` 与本地草稿时恢复该表单。
+- 点击提交先请求第 4 步校验接口，再保存 `{ step4Answer, currentStep: 4, submitted: true, saveAction: "SUBMIT" }`。
+- 演示模式和正式模式都必须执行两个字段非空的同一规则。
+
+## 后端校验接口
+
+新增 `POST /api/student-training-answers/product-development-factors/step-4/validate`。
+
+- 仅允许已登录、`roleId == 4` 的学生调用；未登录返回 401，非学生返回 403。
+- 请求体包含 `successFactors` 和 `failedFactors`。
+- 两个字段去除空白后都必须非空。
+- 合法请求返回 `{ valid: true, message: "校验通过" }`；空字段返回明确的 400 错误信息。
+
+## 测试
+
+- 后端服务测试覆盖：合法提交、成功/失败关键因素为空、非学生身份。
+- 控制器测试覆盖：接口把认证学生与请求参数传给第 4 步校验服务并返回结果。
+- 前端静态契约测试覆盖：第 4 步文本框、`step4Answer`、校验 API、最终 `SUBMIT` 保存动作和演示校验。
+- 最终运行后端 `mvn -B test` 和前端静态契约测试、生产构建。