Tirsvad-Udemy-100-days-of-code/026-nato-alphabet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Model Spell a Word: use case diagram, user story, use case and SSD

Browse Source 
Task: MIL-002#1
Refs #8
This commit is contained in:
Tirsvad
2026-10-13 16:39:01 +08:00
parent 530a1f8f2b
commit 1b7da4bcf9
11 changed files with 632 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sqa/reviews/rc-010-ucd-001.md
+66
View File
@@ -0,0 +1,66 @@
# SQA Review Record RC-010: UCD-001
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-010 |
| CrossReference | [UCD-001], [QC-UCD-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Review of UCD-001 | pending |
---
## Artifact Under Review
- Instance reviewed: [UCD-001]
- Checklist used: [QC-UCD-001]
- Scope: full review
- Language and domain: en / it
- Language reviewer: none
- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`)
## Checklist Results
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | Actors are defined with correct UML stereotypes (e.g. `<<System>>`, `<<Actor>>`) | Pass | Actor `<<Actor>>` and system `<<System>>` in the diagram and actor table. |
| 2 | System boundary is clearly drawn and labeled | Pass | The rectangle is labelled "NATO alphabet tool". |
| 3 | Include/extend relationships are used correctly per UML 2.5.1, not as generic "uses" arrows | Pass | No include or extend is used; the Relationships table says so. |
| 4 | Every actor participates in at least one use case (no orphan actors) | Pass | The User takes part in Spell a Word. |
| 5 | Diagram is traceable to a documented stakeholder need | Pass | The actor table cites S01 and S02 from [SA-001]. |
| 6 | Use case names are verb phrases describing actor goals, not internal system operations | Pass | "Spell a Word" is a verb phrase describing the actor's goal. |
| 7 | Diagram is free of implementation detail (e.g. UI widgets, database tables) | Pass | No interface or storage detail. |
| 8 | Actor and use case naming is consistent with corresponding Use Case and User Story documents | Pass | Actor `User` and use case `Spell a Word` are named alike in US-001 and UC-001. |
## Language and Domain Results
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | The Metadata table has a `Language` row and a `Domain` row, and neither is a placeholder | Pass | `Language | en` and `Domain | it` are in the Metadata table. |
| 2 | `Language` is a BCP 47 code and `Domain` is a value from the registry's domain list | Pass | `en` is a BCP 47 code; `it` is in the registry's domain list. |
| 3 | The content (prose and table cells) is written in the stated language | Pass | All prose and table cells are English. Checked by the stand-in reviewer, who reads English. |
| 4 | The register matches the one the registry gives for the artifact type | Pass | The registry gives IT Professional English for this type; the text matches it. |
| 5 | Domain terms are the PO terms of the domain's dictionary, with no synonyms | Pass | No dictionary (`DICT`) exists; the terms user, word, letter and code word are used consistently with no synonyms. Checked by the stand-in; open to challenge. |
| 6 | Metadata keys, section headings, IDs and statuses are in English | Pass | Metadata keys, headings, IDs and statuses are English. |
| 7 | No translated twin (`<name>.<language>.md`) exists beside the document | Pass | No translated twin exists. |
| 8 | A change of language or domain since the previous accepted version has a Version History row and was reviewed again | Pass | First version; no change of language or domain. |
| 9 | A reviewer competent in the domain, and in the language, has confirmed that the domain terms are used correctly | Pass | Software and IT domain, English language; the reviewer stood in for (S01) reads both. A person may challenge this in the run summary. |
| 10 | Abbreviations are spelled out on first use, in the stated language | Pass | Abbreviations are spelled out on first use or are identifiers. |
## Overall Verdict
Go — every Mandatory criterion of QC-UCD-001 and QC-LANG-001 passes.
## Action Items
| Action | Owner | Due |
| --- | --- | --- |
| None | S01 | n/a |
---
[UCD-001]: ../../use-case-diagram.md
[QC-UCD-001]: ../../../framework/qc/artifacts/qc-use-case-diagram.md
docs/sqa/reviews/rc-011-us-001.md
+65
View File
@@ -0,0 +1,65 @@
# SQA Review Record RC-011: US-001
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-011 |
| CrossReference | [US-001], [QC-US-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Review of US-001 | pending |
---
## Artifact Under Review
- Instance reviewed: [US-001]
- Checklist used: [QC-US-001]
- Scope: full review
- Language and domain: en / it
- Language reviewer: none
- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`)
## Checklist Results
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | Follows INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) | Pass | INVEST check line in the document; one story, one console interaction. |
| 2 | Written in "As a / I want / So that" form | Pass | As a / I want / so that. |
| 3 | Clear, testable acceptance criteria are included | Pass | Three Given/When/Then criteria, each a pytest case. |
| 4 | Traceable to a use case or epic | Pass | Traces to [UC-001] and the epic [MIL-002]. |
| 5 | Story is sized to fit within a single iteration | Pass | Fits one iteration. |
| 6 | Story statement avoids technical implementation detail | Pass | No implementation detail. |
| 7 | Role named in the story matches an actor defined in the Use Case Diagram | Pass | Role `User` is the actor of [UCD-001]. |
## Language and Domain Results
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | The Metadata table has a `Language` row and a `Domain` row, and neither is a placeholder | Pass | `Language | en` and `Domain | it` are in the Metadata table. |
| 2 | `Language` is a BCP 47 code and `Domain` is a value from the registry's domain list | Pass | `en` is a BCP 47 code; `it` is in the registry's domain list. |
| 3 | The content (prose and table cells) is written in the stated language | Pass | All prose and table cells are English. Checked by the stand-in reviewer, who reads English. |
| 4 | The register matches the one the registry gives for the artifact type | Pass | The registry gives IT Professional English for this type; the text matches it. |
| 5 | Domain terms are the PO terms of the domain's dictionary, with no synonyms | Pass | No dictionary (`DICT`) exists; the terms user, word, letter and code word are used consistently with no synonyms. Checked by the stand-in; open to challenge. |
| 6 | Metadata keys, section headings, IDs and statuses are in English | Pass | Metadata keys, headings, IDs and statuses are English. |
| 7 | No translated twin (`<name>.<language>.md`) exists beside the document | Pass | No translated twin exists. |
| 8 | A change of language or domain since the previous accepted version has a Version History row and was reviewed again | Pass | First version; no change of language or domain. |
| 9 | A reviewer competent in the domain, and in the language, has confirmed that the domain terms are used correctly | Pass | Software and IT domain, English language; the reviewer stood in for (S01) reads both. A person may challenge this in the run summary. |
| 10 | Abbreviations are spelled out on first use, in the stated language | Pass | Abbreviations are spelled out on first use or are identifiers. |
## Overall Verdict
Go — every Mandatory criterion of QC-US-001 and QC-LANG-001 passes.
## Action Items
| Action | Owner | Due |
| --- | --- | --- |
| None | S01 | n/a |
---
[US-001]: ../../user-stories.md
[QC-US-001]: ../../../framework/qc/artifacts/qc-user-story.md
docs/sqa/reviews/rc-012-uc-001.md
+70
View File
@@ -0,0 +1,70 @@
# SQA Review Record RC-012: UC-001
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-012 |
| CrossReference | [UC-001], [QC-UC-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Review of UC-001 | pending |
---
## Artifact Under Review
- Instance reviewed: [UC-001]
- Checklist used: [QC-UC-001]
- Scope: full review
- Language and domain: en / it
- Language reviewer: none
- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`)
## Checklist Results
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | Consists of a single, concise paragraph summarizing only the primary success scenario | N-A | Format is Fully Dressed, not Brief. |
| 2 | Written as an informal multi-paragraph narrative; may mention some alternate flows without formal structure | N-A | Format is Fully Dressed, not Casual. |
| 3 | All standard sections are present: actors, preconditions, postconditions, main success scenario, alternative/exception flows | Pass | Scope, level, actor, stakeholders, pre- and postconditions, main scenario, extensions, rules and open issues are present. |
| 4 | Preconditions and postconditions are explicitly defined | Pass | Preconditions and postconditions are stated. |
| 5 | Primary actor is explicitly stated | Pass | Primary actor: User. |
| 6 | Stakeholders and their interests are stated | Pass | S01 and S02 with their interests. |
| 7 | Main success scenario is written as clear, numbered steps | Pass | Four numbered steps. |
| 8 | Alternative/exception flows correctly reference `<<include>>`/`<<extend>>` use cases where relevant, per UML 2.5.1 | N-A | No other use case exists, so no include or extend is relevant; the alternative flow 3a is a plain extension. |
| 9 | Explicit business rules are captured per step where applicable, rather than embedded loosely in narrative text | Pass | A Special Requirements table gives a rule per step. |
| 10 | Naming of actors and use case title is consistent with the corresponding Use Case Diagram and User Stories | Pass | Actor and title match [UCD-001] and [US-001]. |
| 11 | Scope/level (e.g. summary, user-goal, subfunction) is explicitly stated | Pass | Level: user-goal; scope: NATO alphabet tool. |
| 12 | Use case is written from the actor's goal perspective, free of UI or implementation detail | Pass | Written from the goal of the User, with no interface detail. |
## Language and Domain Results
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | The Metadata table has a `Language` row and a `Domain` row, and neither is a placeholder | Pass | `Language | en` and `Domain | it` are in the Metadata table. |
| 2 | `Language` is a BCP 47 code and `Domain` is a value from the registry's domain list | Pass | `en` is a BCP 47 code; `it` is in the registry's domain list. |
| 3 | The content (prose and table cells) is written in the stated language | Pass | All prose and table cells are English. Checked by the stand-in reviewer, who reads English. |
| 4 | The register matches the one the registry gives for the artifact type | Pass | The registry gives IT Professional English for this type; the text matches it. |
| 5 | Domain terms are the PO terms of the domain's dictionary, with no synonyms | Pass | No dictionary (`DICT`) exists; the terms user, word, letter and code word are used consistently with no synonyms. Checked by the stand-in; open to challenge. |
| 6 | Metadata keys, section headings, IDs and statuses are in English | Pass | Metadata keys, headings, IDs and statuses are English. |
| 7 | No translated twin (`<name>.<language>.md`) exists beside the document | Pass | No translated twin exists. |
| 8 | A change of language or domain since the previous accepted version has a Version History row and was reviewed again | Pass | First version; no change of language or domain. |
| 9 | A reviewer competent in the domain, and in the language, has confirmed that the domain terms are used correctly | Pass | Software and IT domain, English language; the reviewer stood in for (S01) reads both. A person may challenge this in the run summary. |
| 10 | Abbreviations are spelled out on first use, in the stated language | Pass | Abbreviations are spelled out on first use or are identifiers. |
## Overall Verdict
Go — every applicable Mandatory criterion passes. The task summary of MIL-002 said "brief"; the use case is Fully Dressed so that the system sequence diagram can follow its steps one by one.
## Action Items
| Action | Owner | Due |
| --- | --- | --- |
| None | S01 | n/a |
---
[UC-001]: ../../uc-001/uc.md
[QC-UC-001]: ../../../framework/qc/artifacts/qc-use-case.md
docs/sqa/reviews/rc-013-ssd-001.md
+65
View File
@@ -0,0 +1,65 @@
# SQA Review Record RC-013: SSD-001
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-013 |
| CrossReference | [SSD-001], [QC-SSD-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Review of SSD-001 | pending |
---
## Artifact Under Review
- Instance reviewed: [SSD-001]
- Checklist used: [QC-SSD-001]
- Scope: full review
- Language and domain: en / it
- Language reviewer: none
- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`)
## Checklist Results
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | Input/output messages match the corresponding Use Case's main success scenario step-for-step | Pass | Messages requestWord and spellWord cover steps 1 to 4; the table maps each message to its use case steps. |
| 2 | Actor and System are treated strictly as black boxes (system shown as `:System`) | Pass | The system is `:System`; no internal objects. |
| 3 | Object creation/destruction of the System instance handled explicitly where relevant | Pass | Lifecycle notes state one session per start. |
| 4 | Return values are shown for operations that produce one, using dashed return arrows | Pass | Dashed return arrows for prompt and codeWords. |
| 5 | Alternate/exceptional flows are represented separately (or explicitly out of scope noted) | Pass | The alternate flow 3a has its own diagram. |
| 6 | Message names are verb phrases consistent with the use case's system responsibilities | Pass | requestWord and spellWord are verb phrases. |
| 7 | Diagram references the specific Use Case (name and ID) it depicts | Pass | The Source Use Case section names Spell a Word and [UC-001]. |
## Language and Domain Results
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | The Metadata table has a `Language` row and a `Domain` row, and neither is a placeholder | Pass | `Language | en` and `Domain | it` are in the Metadata table. |
| 2 | `Language` is a BCP 47 code and `Domain` is a value from the registry's domain list | Pass | `en` is a BCP 47 code; `it` is in the registry's domain list. |
| 3 | The content (prose and table cells) is written in the stated language | Pass | All prose and table cells are English. Checked by the stand-in reviewer, who reads English. |
| 4 | The register matches the one the registry gives for the artifact type | Pass | The registry gives IT Professional English for this type; the text matches it. |
| 5 | Domain terms are the PO terms of the domain's dictionary, with no synonyms | Pass | No dictionary (`DICT`) exists; the terms user, word, letter and code word are used consistently with no synonyms. Checked by the stand-in; open to challenge. |
| 6 | Metadata keys, section headings, IDs and statuses are in English | Pass | Metadata keys, headings, IDs and statuses are English. |
| 7 | No translated twin (`<name>.<language>.md`) exists beside the document | Pass | No translated twin exists. |
| 8 | A change of language or domain since the previous accepted version has a Version History row and was reviewed again | Pass | First version; no change of language or domain. |
| 9 | A reviewer competent in the domain, and in the language, has confirmed that the domain terms are used correctly | Pass | Software and IT domain, English language; the reviewer stood in for (S01) reads both. A person may challenge this in the run summary. |
| 10 | Abbreviations are spelled out on first use, in the stated language | Pass | Abbreviations are spelled out on first use or are identifiers. |
## Overall Verdict
Go — every Mandatory criterion of QC-SSD-001 and QC-LANG-001 passes.
## Action Items
| Action | Owner | Due |
| --- | --- | --- |
| None | S01 | n/a |
---
[SSD-001]: ../../uc-001/ssd.md
[QC-SSD-001]: ../../../framework/qc/artifacts/qc-ssd.md
docs/sqa/reviews/rc-014-python-converter.md
+59
View File
@@ -0,0 +1,59 @@
# SQA Review Record RC-014: PY-002
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-014 |
| CrossReference | [PY-002], [QC-PY-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Review of PY-002 | pending |
---
## Artifact Under Review
- Instance reviewed: [PY-002]
- Checklist used: [QC-PY-001]
- Scope: full review
- Language and domain: n/a (technical type)
- Language reviewer: none
- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`)
## Checklist Results
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | ruff rule set N passes; modules snake_case, classes PascalCase, `InvalidWordError` ends in Error. |
| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names state purpose: `generate_phonetic`, `load_nato_dict`, `SpellWordSession`. |
| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | ruff 0.17.0 check and format pass; no suppressions. |
| 4 | Every function and method signature is type-annotated, including `-> None` | Pass | All signatures annotated; mypy --strict passes. |
| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | `InvalidWordError` is raised `from` the KeyError; the console adapter maps only EOFError and KeyboardInterrupt to `InputClosedError`; no bare except. |
| 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults; `path` defaults to None. |
| 7 | Files, locks and connections are managed with context managers | Pass | The CSV is read inside a `with` block. |
| 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | Every module, class, function and constant has a Doxygen docstring; doxygen reports 0 warnings. |
| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | Pass | `print` and `input` are confined to `adapters/console.py` because the console is the program's output; there is no logging and no secret or personal data. |
| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | N-A | No design class diagram exists; MIL-002 plans none (the SSD and use case are the design artifacts). Classes follow the ports in `application/ports.py`. |
| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | 50 tests named for behaviour; `tmp_path` and fakes; no network; order independent. |
| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | Pass | mypy --strict: no issues in 18 files; no `Any`. |
| 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | No runtime dependencies; development tools pinned with `==`. |
| 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | Each literal is defined once in `constants.py`; the letter mapping is defined once in the CSV. |
| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | import-linter contract `Dependencies point inward` is kept; no cycles. |
| 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | Ports are narrow Protocols; the session depends on them, adapters implement them. |
## Overall Verdict
Go — every Mandatory criterion of QC-PY-001 passes or is not applicable (criterion 10: no design class diagram is planned). The signature of `generate_phonetic` takes the alphabet as a second parameter because the domain layer may not read files; the assignment's name is kept.
## Action Items
| Action | Owner | Due |
| --- | --- | --- |
| None | S01 | n/a |
---
[PY-002]: ../../../src/nato_alphabet/main.py
[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md