Add the plan baseline: business case, stakeholders, plan, design and milestones

Business Case, Stakeholder Analysis, Project Plan, use case chain (UCD, US, UC, DM, SSD, OC, SD, DCD, DICT), three ADRs, milestones MIL-001 to MIL-007, the traceability matrix and 22 review records (autonomous mode, AI as stand-in for S01).
2026-10-14 21:33:25 +08:00
parent 97eec837a4
commit c3fbcbcfaf
49 changed files with 3484 additions and 0 deletions
@@ -0,0 +1,98 @@
+# Operation Contracts: Study Flash Cards
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | OC-001 |
+| CrossReference | [SSD-001], [DM-001], [DICT-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | pending |
+
+---
+
+The turn-over of the card after 3000 ms is started by the system's own timer, not by a message from the Learner, so it has no contract; it is realized in [SD-001].
+
+## Contract: startStudySession
+
+| Item | Value |
+| --- | --- |
+| Operation | `startStudySession(): CardDto \| None` |
+| Traces to | `startStudySession` in [SSD-001] |
+| Domain Model concepts | Study Session, Words To Learn, Word List, Flash Card ([DM-001]); IT terms `StudySession`, `Deck`, `Vocabulary`, `Card` ([DICT-001]) |
+
+**Preconditions**
+
+- A `Vocabulary` exists in the word list file.
+
+**Postconditions**
+
+- A `StudySession` instance was created.
+- A `Deck` instance was created and associated with the `StudySession`.
+- The `Deck` holds the cards of the progress file when it exists, otherwise a copy of the cards of the `Vocabulary`.
+- When the `Deck` is not empty, `StudySession.current_card` was set to a card of the `Deck` and a `CardDto` of it is returned; otherwise `current_card` is `None` and `None` is returned.
+
+**Exceptions**
+
+| Condition (failing precondition) | Outcome |
+| --- | --- |
+| The word list file does not exist | `VocabularyNotFoundError` is raised; no session is created |
+| The word list or progress file has no header of two cells, or a row with other than two cells | `VocabularyFormatError` is raised; no session is created and no file is changed |
+
+## Contract: markKnown
+
+| Item | Value |
+| --- | --- |
+| Operation | `markKnown(): None` |
+| Traces to | `markKnown` in [SSD-001] |
+| Domain Model concepts | Study Session, Words To Learn, Flash Card ([DM-001]); IT terms `StudySession`, `Deck`, `Card` ([DICT-001]) |
+
+**Preconditions**
+
+- A `StudySession` exists and its `current_card` is not `None`.
+
+**Postconditions**
+
+- The `Card` of `current_card` was removed from the `Deck` (the association was destroyed).
+- The `Deck` was stored in the progress file.
+- `StudySession.current_card` was set to `None`.
+
+**Exceptions**
+
+| Condition (failing precondition) | Outcome |
+| --- | --- |
+| `current_card` is `None` (no card is shown) | Nothing is changed and nothing is stored |
+
+## Contract: markUnknown
+
+| Item | Value |
+| --- | --- |
+| Operation | `markUnknown(): CardDto \| None` |
+| Traces to | `markUnknown` in [SSD-001] |
+| Domain Model concepts | Study Session, Words To Learn, Flash Card ([DM-001]); IT terms `StudySession`, `Deck`, `Card` ([DICT-001]) |
+
+**Preconditions**
+
+- A `StudySession` exists.
+
+**Postconditions**
+
+- `StudySession.current_card` was set to a card of the `Deck` that differs from the previous `current_card` when the `Deck` holds two or more cards, and a `CardDto` of it is returned.
+- When the `Deck` is empty, `current_card` is `None` and `None` is returned.
+- The `Deck` and the progress file are unchanged.
+- The Malay word of the new `current_card` was passed to the `SpeechPort`.
+
+**Exceptions**
+
+| Condition (failing precondition) | Outcome |
+| --- | --- |
+| The `Deck` is empty | `None` is returned; nothing is spoken |
+
+---
+
+[SSD-001]: ./ssd.md
+[DM-001]: ../domain-model.md
+[DICT-001]: ../dictionary.md
+[SD-001]: ./sd.md