docs: design dynamic training steps

docs/superpowers/specs/2026-08-01-dynamic-training-steps-design.md

@@ -0,0 +1,36 @@
+# Dynamic Training Steps Design
+
+## Goal
+
+Allow every training task to have any number of editable steps. Teachers can add, rename, reorder, and delete steps. Students can open, fill, save, and submit every added step without losing the existing specialised training forms.
+
+## Step Model
+
+`TrainingTask.steps` remains JSON text for database compatibility, but new writes use an array of objects:
+
+```json
+[
+  { "id": "builtin-1", "name": "选定产品", "kind": "builtin" },
+  { "id": "custom-a1b2", "name": "竞品补充调研", "kind": "custom" }
+]
+```
+
+Existing string arrays remain readable. They are normalized to deterministic `legacy-<position>` IDs until a teacher saves the task, after which the object form is stored. The service no longer truncates or pads step counts.
+
+## Teacher and Management Editors
+
+Both task editors display one row per step with a text field, a delete button, and an add-step button. At least one step is required. The displayed sequence is the stored sequence; task count remains fixed, but step count does not.
+
+## Student Experience
+
+Built-in steps keep their existing specialised forms. The mapping follows stable step IDs, not the array position, so renaming or reordering does not attach a specialised form to the wrong step. Deleting a built-in step hides that form.
+
+Every custom step is exposed through a shared student step workspace. It has a step title, a rich text/long-text answer field, optional attachment upload, save, and submit controls. A shared task-step launcher is rendered for student task routes so custom steps are reachable from every task without duplicating the workspace across the existing specialised pages.
+
+## Persistence and Compatibility
+
+The four legacy answer fields are retained for existing specialised pages. A new `dynamic_step_answers` JSON field on the student answer record stores custom answers by stable step ID, including text, uploaded attachment metadata, save time, and submitted state. Existing student records remain valid. The task-level submitted state and scoring flow remain unchanged.
+
+## Validation and Verification
+
+Backend tests cover arbitrary step counts, no padding/truncation, and preservation of stable IDs. Frontend tests cover add/delete editing and the custom-step workspace save payload. Browser verification will add a custom step to a teacher task, open it as a student, save text and an attachment, reload it, and confirm the saved answer remains available.