specdojo 0.6.0 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/agents/specdojo-orchestrator.md +3 -2
- package/CHANGELOG.md +193 -0
- package/README.md +2 -2
- package/dist/catalog/build.js +24 -1
- package/dist/catalog/plan.js +1 -1
- package/dist/catalog/scaffold.js +4 -1
- package/dist/commands/agent.js +33 -0
- package/dist/commands/init.js +6 -1
- package/dist/commands/night-orchestrator.js +6 -4
- package/dist/commands/orchestrator.js +10 -1
- package/dist/dashboard/dashboard-timeline.js +18 -16
- package/dist/dashboard/dashboard.js +612 -259
- package/dist/dashboard/epic-plan.js +81 -0
- package/dist/dashboard/exec-records.js +16 -20
- package/dist/dashboard/routines.js +8 -6
- package/dist/dashboard/timeline-build.js +5 -9
- package/dist/dashboard/timeline.js +9 -4
- package/dist/devcontainer/command.js +18 -0
- package/dist/devcontainer/host-script.js +21 -0
- package/dist/devcontainer/scaffold.js +22 -3
- package/dist/docs/frontmatter-namespace.js +1 -48
- package/dist/docs/yaml-pages.js +125 -3
- package/dist/exec/agent-config.js +22 -0
- package/dist/exec/agent-plan.js +3 -2
- package/dist/exec/antigravity-session.js +154 -0
- package/dist/exec/commands.js +69 -21
- package/dist/exec/commit-hook-skips.js +78 -0
- package/dist/exec/core.js +19 -7
- package/dist/exec/events.js +159 -8
- package/dist/exec/evidence.js +64 -16
- package/dist/exec/handoff.js +9 -13
- package/dist/exec/limit.js +1 -1
- package/dist/exec/mechanical-result.js +45 -0
- package/dist/exec/migrate-records.js +249 -0
- package/dist/exec/parent-validation.js +160 -12
- package/dist/exec/pipeline-state.js +27 -5
- package/dist/exec/plan-markdownlint.js +89 -0
- package/dist/exec/plans-condense-findings.js +89 -0
- package/dist/exec/plans-core.js +24 -17
- package/dist/exec/plans-generation.js +52 -25
- package/dist/exec/plans-grade-findings.js +8 -3
- package/dist/exec/plans-kata-findings.js +61 -0
- package/dist/exec/plans-planning.js +3 -3
- package/dist/exec/plans-storage.js +12 -24
- package/dist/exec/register-resume.js +69 -42
- package/dist/exec/register.js +26 -22
- package/dist/exec/repo-integration-sync.js +8 -4
- package/dist/exec/repo-integration.js +21 -1
- package/dist/exec/reporter.js +121 -23
- package/dist/exec/results.js +85 -24
- package/dist/exec/review-completion.js +47 -0
- package/dist/exec/review-kata.js +109 -0
- package/dist/exec/run/agent-pipeline.js +75 -6
- package/dist/exec/run/agent.js +20 -7
- package/dist/exec/run/in-place.js +69 -32
- package/dist/exec/run/job.js +81 -24
- package/dist/exec/run/lifecycle-commands.js +264 -43
- package/dist/exec/run/mode-shared.js +11 -3
- package/dist/exec/run/register-command.js +12 -10
- package/dist/exec/run/register-core.js +20 -13
- package/dist/exec/run/register-mode.js +12 -12
- package/dist/exec/run/register-post-review.js +21 -9
- package/dist/exec/run/register-resume.js +28 -18
- package/dist/exec/run/register-state.js +10 -7
- package/dist/exec/run/register-worktree.js +60 -30
- package/dist/exec/run/schedule-mode.js +26 -6
- package/dist/exec/run/schedule-prepare.js +228 -45
- package/dist/exec/run/schedule-task.js +132 -25
- package/dist/exec/run/shared.js +4 -3
- package/dist/exec/run/trailing-records.js +35 -0
- package/dist/exec/run-records.js +2 -0
- package/dist/exec/strategy.js +1 -0
- package/dist/exec/trailing-records.js +242 -0
- package/dist/exec/trial-commands.js +3 -2
- package/dist/exec/validate-records-commit.js +110 -0
- package/dist/exec/validate-records.js +148 -0
- package/dist/exec/worktree-command.js +29 -16
- package/dist/exec/worktree-ops-commit.js +118 -59
- package/dist/exec/worktree-ops-lifecycle.js +77 -44
- package/dist/exec/worktree-ops-merge.js +13 -2
- package/dist/exec/worktree-ops.js +2 -2
- package/dist/exec/worktree.js +19 -2
- package/dist/grade/apply.js +32 -6
- package/dist/grade/command-inspect.js +2 -2
- package/dist/grade/command-run.js +2 -0
- package/dist/grade/command-shared.js +1 -1
- package/dist/grade/core.js +18 -5
- package/dist/grade/markdown.js +3 -3
- package/dist/grade/pipeline-state.js +15 -11
- package/dist/grade/plan.js +37 -17
- package/dist/grade/result.js +3 -3
- package/dist/grade/run.js +23 -3
- package/dist/grade/target-discovery.js +17 -4
- package/dist/grade/targets.js +12 -11
- package/dist/job/job.js +31 -17
- package/dist/job/noop.js +104 -0
- package/dist/register/core.js +2 -0
- package/dist/register/create-commands.js +28 -3
- package/dist/register/deliverable-target.js +9 -1
- package/dist/register/epic.js +104 -26
- package/dist/register/event-merge.js +3 -0
- package/dist/register/events.js +4 -0
- package/dist/register/external-project.js +3 -0
- package/dist/register/item.js +6 -0
- package/dist/register/maintenance-commands.js +4 -1
- package/dist/register/planning.js +7 -14
- package/dist/register/register.js +74 -32
- package/dist/register/track-domains.js +34 -0
- package/dist/register/track-plan.js +78 -0
- package/dist/register/transition-commands.js +8 -0
- package/dist/register/work-table.js +64 -0
- package/dist/review/grade.js +35 -13
- package/dist/routine/definition.js +4 -3
- package/dist/routine/failure.js +30 -0
- package/dist/routine/routine.js +56 -32
- package/dist/routine/storage.js +33 -0
- package/dist/schedule/schedule.js +1 -0
- package/dist/schedule/strategy-generate-document.js +26 -14
- package/dist/schedule/strategy-generate-scope.js +17 -45
- package/dist/schedule/strategy-generate.js +33 -3
- package/dist/schedule/strategy-profiles.js +86 -12
- package/dist/shared/agent-types.js +2 -0
- package/dist/shared/condense-records.js +25 -0
- package/dist/shared/deprecation.js +8 -0
- package/dist/shared/document-metadata.js +20 -0
- package/dist/shared/finding-cause.js +20 -0
- package/dist/shared/frontmatter-namespace.js +48 -0
- package/dist/shared/git.js +149 -15
- package/dist/shared/grade-result.js +17 -1
- package/dist/shared/local-state.js +20 -0
- package/dist/shared/markdownlint-config.js +8 -3
- package/dist/shared/plan-conventions.js +129 -0
- package/dist/shared/plan-templates.js +57 -41
- package/dist/shared/provider-scaffold.js +2 -0
- package/dist/shared/run-records.js +224 -0
- package/dist/shared/specdojo-config.js +39 -21
- package/dist/shared/specdojo-gitignore.js +1 -0
- package/dist/shared/text.js +65 -5
- package/dist/shared/timeline-index.js +2 -0
- package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +11 -2
- package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +4 -74
- package/docs/ja/specdojo/exec-templates/xep-condense-template.md +50 -0
- package/docs/ja/specdojo/exec-templates/xep-draft-template.md +17 -5
- package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +16 -3
- package/docs/ja/specdojo/exec-templates/xep-recipe-guided-template.md +15 -5
- package/docs/ja/specdojo/exec-templates/xep-recipe-maintenance-template.md +6 -0
- package/docs/ja/specdojo/exec-templates/xep-register-template.md +1 -1
- package/docs/ja/specdojo/exec-templates/xep-rulebook-maintenance-template.md +6 -0
- package/docs/ja/specdojo/exec-templates/xep-sample-maintenance-template.md +6 -0
- package/docs/ja/specdojo/exec-templates/xep-template-maintenance-template.md +6 -0
- package/docs/ja/specdojo/exec-templates/xer-condense-template.md +25 -0
- package/docs/ja/specdojo/exec-templates/xp-common-conventions-template.md +50 -0
- package/docs/ja/specdojo/exec-templates/xrp-common-conventions-template.md +30 -0
- package/docs/ja/specdojo/guides/branch-workflow-guide.md +1 -1
- package/docs/ja/specdojo/guides/docs-editing-guide.md +48 -0
- package/docs/ja/specdojo/guides/docs-structure-guide.md +48 -15
- package/docs/ja/specdojo/guides/exec-config-guide.md +61 -28
- package/docs/ja/specdojo/guides/exec-operation-guide.md +61 -13
- package/docs/ja/specdojo/guides/exec-worktree-guide.md +20 -11
- package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +4 -2
- package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +92 -55
- package/docs/ja/specdojo/guides/project-move-guide.md +381 -0
- package/docs/ja/specdojo/guides/quick-start-guide.md +589 -807
- package/docs/ja/specdojo/guides/register-operation-guide.md +26 -4
- package/docs/ja/specdojo/guides/remote-host-development-guide.md +33 -4
- package/docs/ja/specdojo/guides/review-guide.md +22 -19
- package/docs/ja/specdojo/guides/routine-operation-guide.md +14 -8
- package/docs/ja/specdojo/guides/ryu-guide.md +23 -13
- package/docs/ja/specdojo/guides/schedule-design-guide.md +7 -4
- package/docs/ja/specdojo/guides/schedule-operation-guide.md +41 -3
- package/docs/ja/specdojo/guides/specdojo-overview-guide.md +5 -4
- package/docs/ja/specdojo/guides/timeline-design-guide.md +27 -144
- package/docs/ja/specdojo/guides/use-case-guide.md +471 -74
- package/docs/ja/specdojo/recipes/bac-recipe.md +94 -0
- package/docs/ja/specdojo/recipes/bes-recipe.md +105 -0
- package/docs/ja/specdojo/recipes/br-recipe.md +84 -0
- package/docs/ja/specdojo/recipes/cdfd-overview-recipe.md +88 -86
- package/docs/ja/specdojo/recipes/cdfd-uc-recipe.md +108 -122
- package/docs/ja/specdojo/recipes/cnd-recipe.md +125 -0
- package/docs/ja/specdojo/recipes/cpd-recipe.md +126 -0
- package/docs/ja/specdojo/recipes/cxd-recipe.md +145 -0
- package/docs/ja/specdojo/recipes/ifd-recipe.md +134 -0
- package/docs/ja/specdojo/recipes/ifx-cmd-recipe.md +135 -86
- package/docs/ja/specdojo/recipes/ifx-index-recipe.md +130 -0
- package/docs/ja/specdojo/recipes/pm-organization-recipe.md +29 -26
- package/docs/ja/specdojo/recipes/pm-plan-recipe.md +35 -26
- package/docs/ja/specdojo/recipes/pm-quality-management-plan-recipe.md +38 -28
- package/docs/ja/specdojo/recipes/pm-raci-recipe.md +39 -31
- package/docs/ja/specdojo/recipes/pm-roles-recipe.md +26 -28
- package/docs/ja/specdojo/recipes/prj-assumptions-constraints-dependencies-recipe.md +10 -8
- package/docs/ja/specdojo/recipes/prj-comparison-of-alternatives-recipe.md +18 -17
- package/docs/ja/specdojo/recipes/stsd-recipe.md +100 -62
- package/docs/ja/specdojo/recipes/sysd-critical-flows-recipe.md +106 -0
- package/docs/ja/specdojo/recipes/sysd-cross-cutting-policy-recipe.md +137 -0
- package/docs/ja/specdojo/recipes/sysd-index-recipe.md +122 -0
- package/docs/ja/specdojo/references/command-reference.md +146 -99
- package/docs/ja/specdojo/references/deliverables-reference.md +9 -4
- package/docs/ja/specdojo/references/directory-layout-reference.md +3 -2
- package/docs/ja/specdojo/references/specdojo-config-reference.md +17 -16
- package/docs/ja/specdojo/rulebooks/bac-rulebook.md +72 -290
- package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +212 -79
- package/docs/ja/specdojo/rulebooks/bds-rulebook.md +138 -154
- package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +147 -59
- package/docs/ja/specdojo/rulebooks/bes-rulebook.md +100 -96
- package/docs/ja/specdojo/rulebooks/br-rulebook.md +88 -108
- package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +126 -211
- package/docs/ja/specdojo/rulebooks/cdfd-d2-rulebook.md +367 -0
- package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +6 -5
- package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +96 -100
- package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +38 -47
- package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +132 -106
- package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +102 -68
- package/docs/ja/specdojo/rulebooks/cdt-rulebook.md +152 -0
- package/docs/ja/specdojo/rulebooks/cld-rulebook.md +9 -184
- package/docs/ja/specdojo/rulebooks/clis-rulebook.md +187 -0
- package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +93 -247
- package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +104 -241
- package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +124 -257
- package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +87 -98
- package/docs/ja/specdojo/rulebooks/dct-rulebook.md +9 -7
- package/docs/ja/specdojo/rulebooks/dec-rulebook.md +2 -1
- package/docs/ja/specdojo/rulebooks/dss-rulebook.md +193 -0
- package/docs/ja/specdojo/rulebooks/gl-rulebook.md +100 -54
- package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +69 -252
- package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +91 -76
- package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +252 -226
- package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +118 -40
- package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +11 -11
- package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +9 -9
- package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +4 -4
- package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +11 -11
- package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +11 -11
- package/docs/ja/specdojo/rulebooks/mm-rulebook.md +4 -3
- package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +34 -29
- package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +8 -8
- package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +2 -2
- package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +50 -56
- package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +46 -55
- package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +57 -54
- package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +50 -65
- package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +2 -2
- package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +70 -97
- package/docs/ja/specdojo/rulebooks/pr-rulebook.md +2 -1
- package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +47 -56
- package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +61 -135
- package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +116 -32
- package/docs/ja/specdojo/rulebooks/sf-rulebook.md +118 -61
- package/docs/ja/specdojo/rulebooks/sld-rulebook.md +152 -57
- package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +51 -39
- package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +101 -46
- package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +72 -329
- package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +74 -263
- package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +78 -195
- package/docs/ja/specdojo/rulebooks/tml-rulebook.md +4 -9
- package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +3 -4
- package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +3 -3
- package/docs/ja/specdojo/rulebooks/uis-rulebook.md +140 -143
- package/docs/ja/specdojo/samples/bac-sample.md +106 -21
- package/docs/ja/specdojo/samples/bdd-sample.yaml +143 -35
- package/docs/ja/specdojo/samples/bds-sample.md +100 -21
- package/docs/ja/specdojo/samples/bes-index-sample.md +59 -20
- package/docs/ja/specdojo/samples/bes-sample.md +80 -21
- package/docs/ja/specdojo/samples/br-sample.md +68 -14
- package/docs/ja/specdojo/samples/ccd-sample.md +81 -19
- package/docs/ja/specdojo/samples/cdfd-overview-sample.md +248 -140
- package/docs/ja/specdojo/samples/cdfd-sample.md +172 -99
- package/docs/ja/specdojo/samples/cdfd-uc-sample.md +130 -97
- package/docs/ja/specdojo/samples/cdsd-sample.md +89 -20
- package/docs/ja/specdojo/samples/cdt-sample.md +116 -0
- package/docs/ja/specdojo/samples/cld-sample.md +3 -30
- package/docs/ja/specdojo/samples/clis-sample.md +132 -0
- package/docs/ja/specdojo/samples/cnd-sample.md +127 -21
- package/docs/ja/specdojo/samples/cpd-sample.md +136 -22
- package/docs/ja/specdojo/samples/cxd-sample.md +108 -22
- package/docs/ja/specdojo/samples/dct-index-sample.yaml +63 -17
- package/docs/ja/specdojo/samples/dss-sample.md +175 -0
- package/docs/ja/specdojo/samples/gl-sample.yaml +50 -14
- package/docs/ja/specdojo/samples/ifd-sample.md +105 -21
- package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +91 -60
- package/docs/ja/specdojo/samples/ifx-file-sample.md +462 -21
- package/docs/ja/specdojo/samples/ifx-index-sample.yaml +87 -19
- package/docs/ja/specdojo/samples/pm-members-sample.yaml +37 -13
- package/docs/ja/specdojo/samples/pm-organization-sample.md +52 -20
- package/docs/ja/specdojo/samples/pm-plan-sample.md +84 -26
- package/docs/ja/specdojo/samples/pm-quality-management-plan-sample.md +55 -22
- package/docs/ja/specdojo/samples/pm-raci-sample.md +69 -28
- package/docs/ja/specdojo/samples/pm-roles-sample.yaml +13 -12
- package/docs/ja/specdojo/samples/prj-assumptions-constraints-dependencies-sample.md +50 -26
- package/docs/ja/specdojo/samples/prj-comparison-of-alternatives-sample.md +89 -62
- package/docs/ja/specdojo/samples/sf-index-sample.md +89 -20
- package/docs/ja/specdojo/samples/sf-sample.md +121 -21
- package/docs/ja/specdojo/samples/sld-sample.md +107 -21
- package/docs/ja/specdojo/samples/stsd-sample.md +54 -26
- package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +166 -21
- package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +178 -21
- package/docs/ja/specdojo/samples/sysd-index-sample.md +82 -21
- package/docs/ja/specdojo/samples/tml-sample.yaml +4 -1
- package/docs/ja/specdojo/samples/uis-sample.md +164 -20
- package/docs/ja/specdojo/standards/document-metadata-standard.md +33 -4
- package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +3 -1
- package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +1 -0
- package/docs/ja/specdojo/templates/bac-template.md +76 -0
- package/docs/ja/specdojo/templates/bes-template.md +56 -0
- package/docs/ja/specdojo/templates/br-template.md +64 -0
- package/docs/ja/specdojo/templates/cdfd-overview-template.md +161 -83
- package/docs/ja/specdojo/templates/cdfd-template.md +81 -54
- package/docs/ja/specdojo/templates/cdfd-uc-template.md +130 -89
- package/docs/ja/specdojo/templates/cnd-template.md +137 -0
- package/docs/ja/specdojo/templates/cpd-template.md +129 -0
- package/docs/ja/specdojo/templates/cxd-template.md +105 -0
- package/docs/ja/specdojo/templates/dct-data-model-cdt-template.yaml +40 -0
- package/docs/ja/specdojo/templates/dct-data-model-cld-template.yaml +7 -14
- package/docs/ja/specdojo/templates/dct-index-template.md +9 -20
- package/docs/ja/specdojo/templates/dct-project-management-template.yaml +5 -1
- package/docs/ja/specdojo/templates/ifd-template.md +86 -0
- package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +44 -28
- package/docs/ja/specdojo/templates/ifx-index-template.yaml +40 -0
- package/docs/ja/specdojo/templates/opr-template.md +2 -4
- package/docs/ja/specdojo/templates/pm-organization-template.md +9 -3
- package/docs/ja/specdojo/templates/pm-plan-template.md +4 -4
- package/docs/ja/specdojo/templates/pm-quality-management-plan-template.md +17 -9
- package/docs/ja/specdojo/templates/pm-raci-template.md +24 -13
- package/docs/ja/specdojo/templates/pm-roles-template.yaml +3 -2
- package/docs/ja/specdojo/templates/prj-assumptions-constraints-dependencies-template.md +6 -3
- package/docs/ja/specdojo/templates/prj-comparison-of-alternatives-template.md +22 -19
- package/docs/ja/specdojo/templates/stsd-template.md +46 -21
- package/docs/ja/specdojo/templates/sysd-critical-flows-template.md +94 -0
- package/docs/ja/specdojo/templates/sysd-cross-cutting-policy-template.md +122 -0
- package/docs/ja/specdojo/templates/sysd-index-template.md +89 -0
- package/docs/specdojo/lib/yaml-metadata.cjs +7 -0
- package/docs/specdojo/schemas/v1/bdd.schema.yaml +25 -57
- package/docs/specdojo/schemas/v1/condense-records.schema.yaml +26 -0
- package/docs/specdojo/schemas/v1/dct.schema.yaml +10 -0
- package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +3 -0
- package/docs/specdojo/schemas/v1/esil.schema.yaml +7 -141
- package/docs/specdojo/schemas/v1/exec-common.schema.yaml +3 -0
- package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +54 -3
- package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +3 -0
- package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +14 -0
- package/docs/specdojo/schemas/v1/exec-result-frontmatter.schema.yaml +18 -0
- package/docs/specdojo/schemas/v1/finding-cause.schema.yaml +22 -0
- package/docs/specdojo/schemas/v1/grade-pipeline-state.schema.yaml +1 -1
- package/docs/specdojo/schemas/v1/grade-result.schema.yaml +2 -0
- package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +65 -5
- package/docs/specdojo/schemas/v1/ifx-index.schema.yaml +142 -0
- package/docs/specdojo/schemas/v1/register-events.schema.yaml +2 -0
- package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +17 -1
- package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +1 -0
- package/package.json +6 -3
- package/templates/antigravity/README.md +19 -46
- package/templates/antigravity/exec-defaults-snippet.yaml +5 -6
- package/templates/antigravity/orchestrator.md +3 -2
- package/templates/antigravity/settings.edit.json +73 -0
- package/templates/antigravity/settings.orchestrator.json +15 -0
- package/templates/antigravity/settings.report.json +7 -0
- package/templates/antigravity/settings.review.json +7 -0
- package/templates/claude/agents/specdojo-orchestrator.md +3 -2
- package/templates/codex/agents/specdojo-orchestrator.toml +3 -2
- package/templates/codex/orchestrator.md +3 -2
- package/templates/devcontainer/remote-host/devcontainer-tmux.sh +217 -0
- package/templates/devcontainer/remote-host/specdojo-tmux.sh.sample +8 -96
- package/templates/devcontainer/remote-host/ssh-config.sample +3 -1
- package/templates/devcontainer/tmux.conf +6 -0
- package/templates/init-agent-members.yaml +1 -0
- package/templates/init-exec-defaults.yaml +1 -1
- package/templates/opencode/agents/specdojo-orchestrator.md +3 -2
|
@@ -2,37 +2,182 @@
|
|
|
2
2
|
specdojo:
|
|
3
3
|
id: specdojo:sysd-critical-flows-sample
|
|
4
4
|
type: architecture
|
|
5
|
-
status:
|
|
5
|
+
status: ready
|
|
6
|
+
owner: ARC
|
|
6
7
|
rulebook: specdojo:sysd-critical-flows-rulebook
|
|
8
|
+
part_of: []
|
|
9
|
+
based_on: []
|
|
7
10
|
---
|
|
8
11
|
|
|
9
|
-
#
|
|
12
|
+
# 駄菓子屋きぬや 販売管理システム重要フロー
|
|
10
13
|
|
|
11
|
-
## 1.
|
|
14
|
+
## 1. 概要(対象・運用方針)
|
|
12
15
|
|
|
13
|
-
|
|
16
|
+
単一店舗・タブレット1台で、店主代表と家族利用者代表が販売を記録して店番を引き継ぐ。[[specdojo:prj-overview-sample|プロジェクト概要]] の「まず記録する」方針に対応し、会計要求から受付照合、確定後のレシート保存・印字回復までを扱う。境界を誤ると二重売上や二重請求につながるため、重要フローをこの2件に絞る。商品閲覧、明細入力、在庫分析は対象外とし、追加候補は統合・置換を判断して最大5件に収める。
|
|
14
17
|
|
|
15
|
-
|
|
18
|
+
_ASSUMPTION_: [[specdojo:clis-sample|販売管理 CLI 仕様]] と同じ学習用の現金販売 CLI を扱い、本部売上サービスへの送信、端末への販売控え・レシート保存、USB 直結プリンタへの同期印字を前提とする。通常のタブレット画面、つけ販売、キャッシュレス決済、オフライン販売の継続は本例の対象外。本部の受付照会・重複排除契約を未整備のまま自動再送しない。
|
|
16
19
|
|
|
17
|
-
|
|
18
|
-
- 前提: プロジェクト文脈は handbook の共通方針に準拠する
|
|
19
|
-
- 参照: `../rulebooks/sysd-critical-flows-rulebook.md`
|
|
20
|
+
公開対象は設計条件と架空の検証ケースであり、実際の顧客名・購入履歴・つけ残高・認証情報を含めない。開発担当 DEV が設計を更新し、技術メンター ARC が境界、同行レビュー担当 QE が期待結果、店番を担う家族利用者代表が操作と引継ぎを確認する。人間の店主代表 PO が業務条件・実運用・公開の最終判断を行う。
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
設計索引 `kinuya-sysd-index`、取引状態仕様 `kinuya-stsd-sale` は未同梱の架空参照名で、SU-01で追跡する。本例の「会計確定」は本部受付とローカル販売実績の保存が確認できた状態、「照合待ち」は受付の成否を断定できない状態を指す。正式な状態体系は状態仕様へ委譲する。
|
|
22
23
|
|
|
23
|
-
|
|
24
|
-
- 必須観点: 対象、条件、判定基準、責任者
|
|
24
|
+
## 2. 重要フロー一覧(最大5件)
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
| Flow ID | フロー名 | 事故論点 | 利用者・運用者(Role code) | 放置時の業務影響 | 期待効果・選定理由 |
|
|
27
|
+
| ------- | ------------------------------ | ------------------------ | ------------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
28
|
+
| scf-001 | 会計確定と受付結果の照合 | 冪等・応答欠落・部分成功 | 店番担当、店主代表 PO、開発担当 DEV | 売上の二重計上や受付済み取引の取消で、閉店時の照合負荷が増える | 同じ取引の記録を一件に保つ。閲覧より金銭・引継ぎへの影響が大きい |
|
|
29
|
+
| scf-002 | 確定後のレシート保存と印字回復 | 外部コマンド障害・再実行 | 店番担当、運用助言 OPS、開発担当 DEV | 印字失敗を会計失敗と誤認して再請求し、または紙の控えを失う | 売上と印字の結果を分ける。通常表示と異なり外部機器の結果確認が必要 |
|
|
27
30
|
|
|
28
|
-
|
|
29
|
-
| ------------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
|
|
30
|
-
| ドキュメント | 重要フロー | 最小サンプル |
|
|
31
|
-
| 目的 | “読まないと事故る”フローだけを可視化し、実装・テスト・運用の共通理解を作る | specdojo:deliverables-reference 準拠 |
|
|
32
|
-
| 主な内容 | 最大5フロー(冪等/補償/非同期/順序/整合性/外部I/F障害など)について、境界・永続化点・再実行性・失敗時挙動を図または箇条書きで定義 | 要点のみ記載 |
|
|
31
|
+
## 3. フロー詳細(IDごと)
|
|
33
32
|
|
|
34
|
-
|
|
33
|
+
図の実線は同期の処理・読み書き・要求応答、破線は中断後の照合や人間による後続対応を示す。本例に非同期キューはない。システム内部の処理、端末保存、外部サービス/機器、人間を subgraph で分ける。
|
|
35
34
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
35
|
+
### 3.1. scf-001: 会計確定と受付結果の照合
|
|
36
|
+
|
|
37
|
+
- **目的・起動**: 店番担当が明細・請求額・預かり金を確認して会計を要求したとき、売上を一度だけ確定する。
|
|
38
|
+
- **範囲・入出力**: 入力は取引 ID、確定する明細、預かり金。出力は本部受付結果、ローカル販売実績、釣銭と確定表示、または照合待ち。明細訂正と印字は対象外。
|
|
39
|
+
|
|
40
|
+
```mermaid
|
|
41
|
+
flowchart LR
|
|
42
|
+
subgraph H[人間]
|
|
43
|
+
U[店番担当]
|
|
44
|
+
O[店主代表 PO]
|
|
45
|
+
end
|
|
46
|
+
subgraph C[販売管理CLI内部]
|
|
47
|
+
V[会計入力確認 / 取引ID]
|
|
48
|
+
S[本部登録と結果判定]
|
|
49
|
+
Q[受付照合]
|
|
50
|
+
end
|
|
51
|
+
subgraph L[端末ファイル]
|
|
52
|
+
T[(取引状態 / 同一取引ID)]
|
|
53
|
+
D[(販売控え / 受付結果)]
|
|
54
|
+
end
|
|
55
|
+
subgraph X[外部本部売上サービス]
|
|
56
|
+
A[(受付記録 / 取引IDと受付ID)]
|
|
57
|
+
end
|
|
58
|
+
U -->|会計要求| V
|
|
59
|
+
V -->|明細と送信開始を保存| T
|
|
60
|
+
T --> S
|
|
61
|
+
S -->|同一取引IDで送信| A
|
|
62
|
+
A -->|受付応答| S
|
|
63
|
+
S -->|受付確認後の保存| D
|
|
64
|
+
D -->|保存確認後の確定表示| U
|
|
65
|
+
S -.->|応答欠落なら照合待ち| Q
|
|
66
|
+
O -.->|受付と控えの照合判断| Q
|
|
67
|
+
Q -->|受付状況の照会| A
|
|
68
|
+
A -->|照会結果| Q
|
|
69
|
+
Q -->|受付済みなら控え回復| D
|
|
70
|
+
Q -->|未受付を確認した同じ取引だけ再開| S
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
- **永続化点**: 送信前に取引 ID と送信対象の明細を保存できなければ本部を呼ばない。送信開始を記録した取引は、再起動後も照合対象とする。本部受付記録とローカル販売実績の両方を確認して初めて確定表示を許す。販売実績保存後・表示前の中断では保存済み結果を再表示し、本部へ再登録しない。
|
|
74
|
+
- **整合性・再実行**: 本部と端末の保存は一つのトランザクションにできないため、部分成功を取引 ID で照合して回復する。会計要求後は明細を固定し、端末上で同じ取引の確定処理を重ねない。受付済みなら記録を回復し、未受付と確認できた場合だけ同じ取引の送信を再開する。確認不能なら照合待ちを保つ。排他・保存の実現方法は SU-01、本部契約と再送条件は SU-02 で確定する。
|
|
75
|
+
- **失敗・補償**: 入力不正は送信前に訂正する。応答欠落・保存失敗では明細と受付情報を保持し、店主代表 PO と開発担当 DEV が照合する。受付済み売上を取引ファイルの削除や確定前取消で戻さない。返品・確定後訂正は別の業務判断へ渡す。
|
|
76
|
+
- **受入 KA-01**: 店番担当は「確定」「照合待ち」を見分けられる。同行レビュー担当 QE は同一取引の繰り返し操作でも本部売上一件、端末控え一件になることを確認し、店主代表 PO は照合待ちからの引継ぎを判断できる。
|
|
77
|
+
|
|
78
|
+
### 3.2. scf-002: 確定後のレシート保存と印字回復
|
|
79
|
+
|
|
80
|
+
- **目的・起動**: 会計確定後に取引の控えを印字し、印字だけの失敗を回復できるようにする。
|
|
81
|
+
- **範囲・入出力**: 入力は保存済み販売実績、出力はレシートファイルと印字結果。売上の再送・再会計は含めない。
|
|
82
|
+
|
|
83
|
+
```mermaid
|
|
84
|
+
flowchart LR
|
|
85
|
+
subgraph L[端末ファイル]
|
|
86
|
+
D[(販売控え / 取引ID)]
|
|
87
|
+
R[(レシート / 取引ID)]
|
|
88
|
+
B[(試行開始 / 取引IDと試行識別子)]
|
|
89
|
+
E[(印字結果 / 同じ試行識別子)]
|
|
90
|
+
end
|
|
91
|
+
subgraph C[販売管理CLI内部]
|
|
92
|
+
G[控え生成]
|
|
93
|
+
P[印刷起動準備]
|
|
94
|
+
K[終了報告の検証]
|
|
95
|
+
end
|
|
96
|
+
subgraph X[外部印刷コマンドと機器]
|
|
97
|
+
A[印刷処理 / 対象取引]
|
|
98
|
+
end
|
|
99
|
+
subgraph H[人間]
|
|
100
|
+
U[店番担当]
|
|
101
|
+
V[開発担当 DEV]
|
|
102
|
+
end
|
|
103
|
+
D --> G
|
|
104
|
+
G -->|送信前保存| R
|
|
105
|
+
R --> P
|
|
106
|
+
P -->|起動前に試行開始を保存| B
|
|
107
|
+
B -->|開始保存成功後だけ同期起動| A
|
|
108
|
+
A -->|終了と対象取引の報告| K
|
|
109
|
+
K -->|検証した結果を保存| E
|
|
110
|
+
E -->|会計確定と印字結果を表示| U
|
|
111
|
+
U -.->|紙面と機器を確認| V
|
|
112
|
+
V -.->|復旧後に保存控えだけ再印刷| P
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
- **永続化点・整合性・再実行**: レシートと試行開始を保存してから印刷を起動し、終了後に結果を保存する。試行識別子は呼出し元の記録であり、プリンタの重複排除キーではない。開始記録だけ残る中断、終了報告の不正、結果保存の失敗は結果不明とし、紙面確認前に再印刷しない。印字完了は終了成功と対象取引の完了報告の両方で判定する。
|
|
116
|
+
- **失敗・保持・補償・再開**: レシートまたは開始記録を保存できなければ印刷せず、販売実績を保持して DEV が保存先を復旧する。自動再試行は [[specdojo:ifx-cmd-sample|レシート印刷コマンド連携仕様]] の送信前ビジーと確認できた場合に限り、上限・待機・同時起動制約も同契約へ委ねる。その他の失敗や結果不明は店番担当が紙面を確認し、DEV が復旧する。既に出た紙は取り消せないため、必要な手動再印刷は保存控えだけを使い、会計・本部登録を再実行しない。
|
|
117
|
+
- **受入 KA-02**: 店番担当は印字未完了でも会計が確定済みであること、保持控えと次の手を確認できる。QE は印刷失敗後の回復で売上件数が増えず、結果不明時に自動再印刷されないことを確認する。
|
|
118
|
+
|
|
119
|
+
## 4. 観測性と運用連携
|
|
120
|
+
|
|
121
|
+
### 4.1. 検知と責任
|
|
122
|
+
|
|
123
|
+
外部本部 API には内部 `trace_id` を受け渡す契約が未整備で、USB 印字にも分散 trace の受渡し先がないため、本例では分散 trace を採用しない。代替として下表のキーを用い、CLI がフロー ID、actor、時刻、処理結果、停止段階を記録する。本部との相関契約の確認は SU-02、印字試行記録の保存方式は SU-01 で追跡する。公開ログには明細・顧客情報・認証情報を含めない。
|
|
124
|
+
|
|
125
|
+
| Flow ID | 相関キーと追跡範囲 | 検知条件・閾値の正本 | 実装動作 | 人間の一次対応・照会先 |
|
|
126
|
+
| ------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------- | ----------------------------------------------------------- |
|
|
127
|
+
| scf-001 | 取引 ID → 本部受付 ID → 端末販売実績。受付 ID 未取得時も取引 ID を保持 | 本書「会計確定と受付結果の照合」:一件でも受付不明・保存失敗・重複を検出 | 確定表示と新しい会計を保留し、同じ取引の記録を保持 | 店番担当 → PO が照合、技術調査は DEV → ARC |
|
|
128
|
+
| scf-002 | 取引 ID → 保存レシート → 呼出し元の試行識別子 → 終了報告・紙面確認 | 本書「確定後のレシート保存と印字回復」:一件でも保存失敗・印字未完了・結果不明を検出 | 会計結果を維持し、印字警告と保持先を表示 | 店番担当が紙面確認、DEV が復旧、運用助言 OPS が引継ぎを確認 |
|
|
129
|
+
|
|
130
|
+
上記は本例のイベント条件で、営業時間外の通知先や応答期限は未決である。SU-03を解消するまで常駐監視や無人復旧があるとは扱わない。
|
|
131
|
+
|
|
132
|
+
### 4.2. 管理記録への引渡し
|
|
133
|
+
|
|
134
|
+
| 条件・対象 | 記録種別 | 担当Role code・対応方針 | 報告・判断先 |
|
|
135
|
+
| ------------------------------------------------- | -------------- | -------------------------------------------------- | ------------------------------------------------ |
|
|
136
|
+
| 受付不明、重複、保存失敗、印字未完了(両フロー) | issue | DEV が取引 ID、停止段階、保持状態、業務影響を報告 | PM が課題記録へ接続、PO が照合結果を判断 |
|
|
137
|
+
| 本部契約・復旧手順・通知条件の未整備(SU-01〜03) | risk | PM が受入への影響を記録し、OPS/ARC が補完案を提示 | PO が運用保留または代替手順の採否を判断 |
|
|
138
|
+
| 自動再送・印刷方式の追加変更(両フロー) | change-request | ARC/DEV が条件と費用、検証への影響を提示 | PM が計画へ反映し、PO が採否を判断 |
|
|
139
|
+
| 照合・運用留保・公開可否の結論(両フロー) | decision | PM が PO の結論・根拠・対象差分を保存 | `KIN-DEC-01`(会計)、`KIN-DEC-02`(印字・公開) |
|
|
140
|
+
|
|
141
|
+
## 5. 関連ドキュメント導線(SDI/テスト/運用/DEC)
|
|
142
|
+
|
|
143
|
+
### 5.1. 正本と変更影響
|
|
144
|
+
|
|
145
|
+
架空の参照名はすべて未同梱であり、実在する実装・自動テストとして示すものではない。
|
|
146
|
+
|
|
147
|
+
| Flow ID | 実装・設定の一意な参照先 | 変更時の契約・schema・生成物・CLI・互換性 | 運用・判断への導線 |
|
|
148
|
+
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
|
|
149
|
+
| scf-001 | `kinuya-sysd-index` の会計保存・排他、`kinuya-stsd-sale` の確定・照合待ち、`ifx-api-kinuya-sales.yaml` の受付・照会 | `kinuya-session-schema` と `kinuya-sales-record-schema`、販売控え、[[specdojo:clis-sample\|販売管理 CLI 仕様]] の確定・停止表示。旧控えの照合と未解決取引の再開を維持 | `kinuya-opr-sale-reconciliation`、SU-01/02/03、`KIN-DEC-01` |
|
|
150
|
+
| scf-002 | [[specdojo:ifx-cmd-sample\|レシート印刷コマンド連携仕様]] の `execution`・`error_handling`、呼出し元の保存方式は `kinuya-sysd-index` の印字試行記録 | `kinuya-receipt-format-schema`、生成レシート、CLI の印字警告。既存控えの再印刷と開始記録だけの旧試行の判定を維持 | `kinuya-opr-reprint`、SU-01/03、`KIN-DEC-02` |
|
|
151
|
+
|
|
152
|
+
### 5.2. 検証への引渡し
|
|
153
|
+
|
|
154
|
+
以下は本例内で定義する手動シナリオ ID であり、実行済みの証跡ではない。QE が DEV と試験用受付・印刷先を用意し、架空の取引だけで実施する。内部の保存・表示境界は ITC、外部本部・印刷契約との境界は ETC に分ける。自動テストファイル・コマンド・schema 検査の確定は SU-02 へ渡し、未同梱の CLI を実行可能とは扱わない。
|
|
155
|
+
|
|
156
|
+
| 検証ID / フロー | 実在する確認先・実行方法 | 対象条件 | 期待結果・失敗判定 |
|
|
157
|
+
| ----------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
158
|
+
| etc-kinuya-cf-01 / scf-001(KA-01) | 本表の手動シナリオ:正常会計後に同じ取引を再要求し、本部・端末を照合 | 同じ取引 ID の繰返し、同時確定要求 | 売上一件・控え一件で pass。二重登録・明細変更のまま再送は fail |
|
|
159
|
+
| etc-kinuya-cf-02 / scf-001(KA-01) | 本表の手動シナリオ:試験用本部で応答を欠落させ、PO/DEV が照合 | 受付済み/未受付/確認不能を個別に用意 | 受付済みは控え回復だけ、未受付は同じ取引で再開、確認不能は保留で pass。照合前再送・取消・新規取引への置換は fail |
|
|
160
|
+
| itc-kinuya-cf-03 / scf-001(KA-01) | 本表の手動シナリオ:各保存点で書込み失敗または停止を注入し、再起動 | 送信前保存、本部受付後の控え保存、控え保存後・表示前 | 送信前保存失敗は本部呼出しゼロ、受付後は照合待ち、保存済みは再表示だけで pass。先行確定・保持消失・再登録は fail |
|
|
161
|
+
| etc-kinuya-cf-04 / scf-002(KA-02) | 本表の手動シナリオ:試験用印刷先の終了・診断・報告を切り替え、店番担当が紙面確認 | 送信前ビジー/送信後失敗/時間切れ/報告欠落・対象不一致 | ビジーだけ契約内で有限再試行。他は警告し紙面確認まで再印刷せず、売上件数不変で pass。契約上限超過・結果不明の自動再印刷は fail |
|
|
162
|
+
| itc-kinuya-cf-05 / scf-002(KA-02) | 本表の手動シナリオ:保存失敗、印字後の中断を注入し、保持記録から復旧 | レシート・試行開始の保存失敗、起動後・結果保存前の中断 | 保存失敗は印刷起動ゼロ、開始記録だけなら結果不明、回復は保存控えのみで pass。会計取消・本部再送・無確認の印字済み判定は fail |
|
|
163
|
+
|
|
164
|
+
### 5.3. 未決事項と後続作業
|
|
165
|
+
|
|
166
|
+
SU は本書内の追跡 ID であり、登録済み課題や Schedule の task ではない。PM は各判断時期までに計画・管理記録へ移し、実 ID を本表へ戻す。
|
|
167
|
+
|
|
168
|
+
| ID / 対象 | 未充足事項・依存とScheduleへの影響 | 作業単位・依存順・担当Role code | 完了条件・判断時期・登録先 |
|
|
169
|
+
| ---------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
|
|
170
|
+
| SU-01 / 両フロー | 索引・状態仕様・保存構造・排他方式が未同梱。実装入力と開始記録の耐中断性が未確定 | ARC/DEV が「正本と変更影響」の未同梱正本を整備 → QE が境界・用語・保存前後のケースを照合 | 実装着手前に正本を接続し、二重確定防止と途中保存の回復方法を説明できること。PM が issue と依存作業を計画 |
|
|
171
|
+
| SU-02 / 両フロー | 本部契約と自動テスト・検査コマンドは未整備。会計受入と自動再送を保留、印字も実機未検証 | SU-01 → ARC/DEV が受付・照会・重複排除と相関契約を定義 → QE が「検証への引渡し」の ITC/ETC 全件を実施 | 会計・印字の受入前に KA-01/02 の結果と検査コマンドを追跡可能にし、PO が採否判断。PM が risk、検証不足を issue へ |
|
|
172
|
+
| SU-03 / 両フロー | 照合・再印刷 OPR、通知先・応答期限が未整備。店番交代時の復旧と運用開始を保留 | SU-01/02 の結果 → OPS/DEV が二つの OPR と通知条件を作成 → 家族利用者代表と QE が保持記録からの引継ぎを確認 | 運用開始前に照会先・紙面確認・再開条件まで到達でき、PO が運用可否を判断。PM が risk/必要な change-request を記録 |
|
|
173
|
+
|
|
174
|
+
### 5.4. 承認対象と公開前条件
|
|
175
|
+
|
|
176
|
+
| 判断対象 | 設計確認担当と合意事項 | 人間の承認責任・確定条件 |
|
|
177
|
+
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
178
|
+
| scf-001 | ARC/DEV が保存・排他と本部契約、QE が KA-01 と `etc-kinuya-cf-01`・`etc-kinuya-cf-02`・`itc-kinuya-cf-03` の検証結果、PM が SU-01〜03 の影響を提示 | PO が確定・照合待ち・取消の境界を承認。受付不明のまま再送する経路は受入不可 |
|
|
179
|
+
| scf-002 | DEV/QE が KA-02 と `etc-kinuya-cf-04`・`itc-kinuya-cf-05` の検証結果、OPS と家族利用者代表が紙面確認・再印刷の引継ぎを提示 | PO が会計と印字の分離、有限再試行、結果不明時の手動確認を承認 |
|
|
180
|
+
|
|
181
|
+
公開/`ready` 昇格前に ARC が構造・参照、QE が上表の期待結果と実績の区別、OPS が非公開記録の除外と運用導線、PM が SU の解消または留保の影響と判断記録を確認する。PO が対象差分に対する人間の承認を残し、設計例の公開と実運用の可否を別々に判断する。
|
|
182
|
+
|
|
183
|
+
本例は設計文書としての完成例であり、未同梱の契約や手順の存在・実装成功を表さない。人間の判断を得るまで `draft` を維持する。
|
|
@@ -2,37 +2,194 @@
|
|
|
2
2
|
specdojo:
|
|
3
3
|
id: specdojo:sysd-cross-cutting-policy-sample
|
|
4
4
|
type: architecture
|
|
5
|
-
status:
|
|
5
|
+
status: ready
|
|
6
6
|
rulebook: specdojo:sysd-cross-cutting-policy-rulebook
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
#
|
|
9
|
+
# 駄菓子屋きぬや 販売処理の横断ルール
|
|
10
10
|
|
|
11
|
-
## 1.
|
|
11
|
+
## 1. 概要(適用範囲・優先順位)
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
店主代表と家族利用者代表が、通信や印字の失敗後も会計の確定状態を取り違えず店番を引き継げるよう、販売処理に共通する制約を定める。[[specdojo:prj-overview-sample|プロジェクト概要]] の「まず記録する」方針に対し、二重登録の防止と保存記録からの回復で寄与する。欠品削減や仕入れ判断の規則は本書では定めない。
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
対象は単一店舗・現金販売の CLI、ローカル取引保存、本部の商品照会・売上登録、外部レシート印刷コマンドとする。販売の操作・表示は [[specdojo:clis-sample|販売管理 CLI 仕様]] を参照する。つけ管理、キャッシュレス決済、複数店舗、無人会計、オフライン同期は対象外である。RDBMS のトランザクションは非該当だが、ファイルと本部受付の不整合は対象に含む。
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
- 前提: プロジェクト文脈は handbook の共通方針に準拠する
|
|
19
|
-
- 参照: `../rulebooks/sysd-cross-cutting-policy-rulebook.md`
|
|
17
|
+
_ASSUMPTION_: タブレット1台で店番担当が操作する学習用 CLI の設計例であり、通常利用のタブレット画面とは別の操作例である。本文でコード表記する契約・設定・計画の参照名は未同梱の架空正本とし、実運用の承認や実装済みを示さない。値・構文・構造はそれらの正本と既存の連携仕様へ委ね、ここでは停止・保持・照合の判断を定める。
|
|
20
18
|
|
|
21
|
-
|
|
19
|
+
競合時は個人情報の保護、会計・受付状態の保存、回復可能性、処理速度の順で判断する。印字成功は会計確定の前提にしない。結果不明を成功や未受付へ読み替えない。
|
|
22
20
|
|
|
23
|
-
|
|
24
|
-
- 必須観点: 対象、条件、判定基準、責任者
|
|
21
|
+
### 1.1. 利用・確認・承認責務
|
|
25
22
|
|
|
26
|
-
|
|
23
|
+
| Role・担当 | 合意・確認対象 |
|
|
24
|
+
| ------------------------- | ------------------------------------------------------ |
|
|
25
|
+
| ARC・技術メンター | 外部連携と保存の境界、横断制約、例外の影響を確認 |
|
|
26
|
+
| DEV・開発担当 | 実装・設定・記録契約の整合と途中状態の照合を担当 |
|
|
27
|
+
| QE・同行レビュー担当 | 同じ取引の二重受付、時間切れ、保存失敗の期待結果を確認 |
|
|
28
|
+
| OPS・店舗運営アドバイザー | 店番交代時の照合・障害連絡・保存記録の扱いを確認 |
|
|
29
|
+
| PM | 未整備契約・受入作業の担当、依存、期限を追跡 |
|
|
30
|
+
| PO・店主代表(人間) | 会計の保留・確定の業務判断と運用開始可否を最終承認 |
|
|
27
31
|
|
|
28
|
-
|
|
29
|
-
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
|
|
30
|
-
| ドキュメント | 横断ルール | 最小サンプル |
|
|
31
|
-
| 目的 | 実装全体に影響する共通ルールをSSOT化し、各所の実装ブレを防ぐ | specdojo:deliverables-reference 準拠 |
|
|
32
|
-
| 主な内容 | エラー形式/例外分類、タイムアウト・リトライ、冪等キー、トランザクション境界、ログ/監査ログ、トレーシング、セキュリティ(認証・認可の実装原則)、バージョニング、設定の上書き階層 | 要点のみ記載 |
|
|
32
|
+
## 2. ルール一覧(ID/カテゴリ/要約/必須度)
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
| Rule ID | Category | Summary | Level | Owner |
|
|
35
|
+
| ----------- | ------------- | ---------------------------------------- | -------- | --------- |
|
|
36
|
+
| scp-ERR-001 | Error | 会計未実施・結果不明・印字警告を区別する | MUST | DEV |
|
|
37
|
+
| scp-IDM-001 | Idempotency | 同じ取引の受付結果を照合してから再送する | MUST | ARC / DEV |
|
|
38
|
+
| scp-TIM-001 | Timeout | 連携ごとに時間上限と打切りの境界を決める | MUST | DEV / OPS |
|
|
39
|
+
| scp-RET-001 | Retry | 副作用のない失敗だけを上限内で再試行する | MUST | ARC |
|
|
40
|
+
| scp-LOG-001 | Logging | 診断と会計監査を分け秘密情報を保存しない | MUST | OPS |
|
|
41
|
+
| scp-TRC-001 | Tracing | 取引から受付・保存・印字を追跡する | MUST | DEV |
|
|
42
|
+
| scp-SEC-001 | Security | 認証値の出力・永続化 | MUST NOT | DEV / OPS |
|
|
43
|
+
| scp-CFG-001 | Configuration | 店舗条件と認証設定を分離して解決する | MUST | DEV |
|
|
44
|
+
| scp-MOD-001 | Module | 会計確定と印字の責務を分離する | MUST | ARC |
|
|
35
45
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
46
|
+
### 2.1. 適合確認の順序と時機
|
|
47
|
+
|
|
48
|
+
本例は設計済み・実装未確認の完成例であり、次表は検証計画への入力である。実施済みの証拠ではない。作業の実 ID は架空の計画 `kinuya-sales-schedule` の整備時に接続する。
|
|
49
|
+
|
|
50
|
+
| 確認群 | Rule ID | 現状 | 依存・確認タイミング | 担当 |
|
|
51
|
+
| ------------- | ---------------------------------- | -------------------- | -------------------------------- | --------- |
|
|
52
|
+
| K1 設定・境界 | CFG-001、MOD-001、SEC-001 | 規定済み・実装未確認 | Q-K1 / Q-K3 整備後、起動前に確認 | DEV / ARC |
|
|
53
|
+
| K2 受付・回復 | ERR-001、IDM-001、TIM-001、RET-001 | 規定済み・実装未確認 | K1 後、通信連携の受入前 | DEV / QE |
|
|
54
|
+
| K3 引継ぎ | LOG-001、TRC-001 | 規定済み・実装未確認 | K2 後、店番交代の受入前 | OPS / QE |
|
|
55
|
+
|
|
56
|
+
短縮 Rule ID には `scp-` を補う。店舗条件・受付契約・時間上限が未確定のまま K2 を合格としない。QE は各群で対象ケースがすべて期待結果を満たすことを確認し、不一致を issue、未実施を未確認として記録する。
|
|
57
|
+
|
|
58
|
+
## 3. 各ルール詳細(ID単位)
|
|
59
|
+
|
|
60
|
+
### 3.1. scp-ERR-001: 失敗分類と利用者の次の手
|
|
61
|
+
|
|
62
|
+
- **Rule(MUST)**: 会計要求前の失敗は未実施、要求後の応答欠落は結果不明、確定後の印字失敗は警告として分ける。会計確定は本部受付とローカル販売実績の保存を確認して通知する。対象取引・保持記録・次の確認先を表示する。
|
|
63
|
+
- **Rationale(意図)**: 店番担当が同じ売上を登録し直したり、印字失敗を理由に会計を取り消したりしないため。
|
|
64
|
+
- **Scope(適用範囲)**: 明細追加、会計要求、ローカル保存、印字。
|
|
65
|
+
- **Enforcement(検証)**: K2 で送信前失敗は明細保持、送信後の無応答は照合待ち、印字失敗は会計維持を確認する。終了コードは CLI リファレンスを照合する。
|
|
66
|
+
- **Exception(例外)**: なし。原因を分類できなければ保留して店主代表へ渡す。
|
|
67
|
+
- **References(参照)**: [[specdojo:clis-sample|販売管理 CLI 仕様]] の「代表的な表示と利用者の次の手」、架空正本 `kinuya-cli-reference`。
|
|
68
|
+
|
|
69
|
+
### 3.2. scp-IDM-001: 受付照合と保存境界
|
|
70
|
+
|
|
71
|
+
- **Rule(MUST)**: 売上登録の再送前に、元の取引番号で本部受付とローカル記録を照合する。受付済みは記録を回復し、未受付を確認できた場合だけ同じ取引で再開する。照合不能なら保留する。受付済み・結果不明の取引をファイル削除や新しい取引番号で初期化しない。
|
|
72
|
+
- **Rationale(意図)**: 通信切断後の二重会計と、受付済み売上の取消を防ぐ。
|
|
73
|
+
- **Scope(適用範囲)**: 本部売上登録、応答欠落、保存失敗後の回復。
|
|
74
|
+
- **Enforcement(検証)**: K2 で「本部受付済み・応答欠落」「未受付」「照合不能」「受付後の保存失敗・再起動」を入力し、それぞれ記録回復・同一取引での再開・保留・元取引の照合待ちになることを確認する。破損・部分保存から成功通知や新しい取引を作らない。
|
|
75
|
+
- **Exception(例外)**: 契約で重複排除が保証されても、本書の受入前に自動再送を追加しない。変更は店主代表の decision を必要とする。
|
|
76
|
+
- **References(参照)**: 架空正本 `ifx-api-kinuya-sales.yaml`、`kinuya-sales-record-schema`、`kinuya-recovery-procedure`。
|
|
77
|
+
|
|
78
|
+
### 3.3. scp-TIM-001: 連携の時間切れ
|
|
79
|
+
|
|
80
|
+
- **Rule(MUST)**: 商品照会・売上登録には実行設定、印字には印刷連携仕様の時間上限を適用し、時間切れでは待機を打ち切る。印刷の子プロセスと子孫を終了し、不完全な標準出力を成功結果に採用しない。終了を確認できない間は再起動せず、売上登録の時間切れを未受付と断定しない。
|
|
81
|
+
- **Rationale(意図)**: 操作を無期限に占有せず、遅れて完了する外部処理を重ねないため。
|
|
82
|
+
- **Scope(適用範囲)**: 本部 HTTP 連携と `receipt-print`。
|
|
83
|
+
- **Enforcement(検証)**: K2 で各 attempt の上限直前・到達時と終了不能を注入する。上限直前の正常応答は採用し、到達時の照会は明細未追加、会計は照合待ち、印字は会計維持・控え保持・印字状態不明とする。印字が遅れて完了しても自動再起動せず、紙面確認へ渡す。
|
|
84
|
+
- **Exception(例外)**: 本部連携の上限値は Q-K1、印刷の実機停止確認は Q-K3 の受入保留とする。
|
|
85
|
+
- **References(参照)**: 架空正本 `kinuya-execution-policy` の `products.timeout_ms`・`sales.timeout_ms`(ミリ秒、attempt ごと)。印刷の上限・終了対象は [[specdojo:ifx-cmd-sample|レシート印刷コマンド連携仕様]] の `execution.timeout_seconds`(秒)と `error_handling.timeout_action` を正とする。
|
|
86
|
+
|
|
87
|
+
### 3.4. scp-RET-001: 再試行の許可範囲
|
|
88
|
+
|
|
89
|
+
- **Rule(MUST)**: 商品照会の一時的な接続失敗・時間切れと、印刷連携仕様で送信前の一時ビジーと識別できる失敗だけを、各正本の回数・待機上限内で自動 retry する。照会は明細未追加、印刷は送信前であることを前提に、同じ要求を使う。認証・権限拒否、入力不正、会計登録、印字結果不明には自動 retry を適用しない。別店舗や別の登録先への fallback は行わない。
|
|
90
|
+
- **Rationale(意図)**: 読取処理の回復と副作用の重複防止を両立させるため。
|
|
91
|
+
- **Scope(適用範囲)**: 商品照会、本部売上登録、印字。
|
|
92
|
+
- **Enforcement(検証)**: K2 で一時失敗、認証・権限拒否、上限到達、汎用の印刷失敗を注入する。許可条件だけが上限内で再試行され、照会の上限では明細未追加、印刷の上限では警告・控え保持となることを確認する。同じ印刷終了コードでも送信前ビジーを識別できなければ再起動せず、会計登録・結果不明は手動照合へ進む。
|
|
93
|
+
- **Exception(例外)**: 未登録商品は接続障害に分類しない。店番担当がコードを訂正する。
|
|
94
|
+
- **References(参照)**: 照会は架空正本 `kinuya-execution-policy` の `products.retry.max_attempts`(初回を含む)・`products.retry.max_backoff_ms`(待機1回の上限、ミリ秒)、値の確定は Q-K1。印刷は [[specdojo:ifx-cmd-sample|レシート印刷コマンド連携仕様]] の失敗分類と `error_handling.retry`(回数の数え方・待機列を含む)に従う。
|
|
95
|
+
|
|
96
|
+
### 3.5. scp-LOG-001: 診断と監査
|
|
97
|
+
|
|
98
|
+
- **Rule(MUST)**: 接続・プロセス失敗の診断と、取引の開始・受付・保存・回復判断の監査を区別する。認証値・顧客氏名・生の通信本文を診断ログへ保存しない。保留会計・未印字・記録保存不能は起動元の店番担当へ通知し、未解消の取引を店番交代時の確認対象に残す。
|
|
99
|
+
- **Rationale(意図)**: 店番交代時の照合を助け、個人情報を障害調査経由で拡散させないため。
|
|
100
|
+
- **Scope(適用範囲)**: CLI ログ、販売実績、照合記録。将来のつけ台帳は含めない。
|
|
101
|
+
- **Enforcement(検証)**: K3 で認証値を模した値の非記録、実行主体・時刻・取引・処理結果の追跡、保存不能時の警告を確認する。店番担当が未解消取引を検知して店主代表へ渡せることを実演する。保持期間・閲覧範囲・定期確認間隔の受入は Q-K2 で行う。
|
|
102
|
+
- **Exception(例外)**: 調査目的でも無加工の秘密情報を保存しない。
|
|
103
|
+
- **References(参照)**: 架空正本 `kinuya-audit-record-schema`、`kinuya-log-policy`。
|
|
104
|
+
|
|
105
|
+
### 3.6. scp-TRC-001: 取引と外部処理の相関
|
|
106
|
+
|
|
107
|
+
- **Rule(MUST)**: 同じ取引番号から本部受付、ローカル控え、印字の要求と結果を追跡する。印字の試行は元の売上と区別し、外部側に共通 trace がなくても親の起動・終了を関連付ける。
|
|
108
|
+
- **Rationale(意図)**: 保留会計と未印字の控えを次の店番が取り違えないため。
|
|
109
|
+
- **Scope(適用範囲)**: 会計・保存・印字・再印刷の照合記録。
|
|
110
|
+
- **Enforcement(検証)**: K3 で異なる二取引と同一取引の印字再試行を追い、売上受付を再実行せず対象の控えだけへ到達できることを確認する。
|
|
111
|
+
- **Exception(例外)**: 印刷側の実紙面は記録だけで断定せず、店番担当が確認する。
|
|
112
|
+
- **References(参照)**: 架空正本 `kinuya-audit-record-schema`、[[specdojo:clis-sample|販売管理 CLI 仕様]] の引継ぎ操作。
|
|
113
|
+
|
|
114
|
+
### 3.7. scp-SEC-001: 認証情報の秘匿
|
|
115
|
+
|
|
116
|
+
- **Rule(MUST NOT)**: `KINUYA_API_KEY` の値を起動引数・画面・ログ・販売控え・店舗設定へ出力・保存すること、および認証不要な印刷コマンドへ引き渡すこと。
|
|
117
|
+
- **Rationale(意図)**: 控えの共有やエラー報告から本部認証が漏れることを防ぐ。
|
|
118
|
+
- **Scope(適用範囲)**: 本部連携の起動、失敗表示、保存記録、印刷 adapter の権限境界。
|
|
119
|
+
- **Enforcement(検証)**: K1 で本部連携の認証未設定時は認証設定不足として停止し、模擬認証値を設定した場合は表示・ログ・保存先・印刷プロセスの環境に値が現れないことを確認する。印刷 adapter は控えを読取専用で渡し、OS 権限拒否時に権限を自動拡大しないことも確認する。
|
|
120
|
+
- **Exception(例外)**: なし。認証設定の管理者は開発担当、実運用の権限承認者は店主代表とする。
|
|
121
|
+
- **References(参照)**: 架空正本 `kinuya-cli-reference` の認証設定、`kinuya-access-policy`。印刷の認証不要・デバイス権限・読取範囲は [[specdojo:ifx-cmd-sample|レシート印刷コマンド連携仕様]]。
|
|
122
|
+
|
|
123
|
+
### 3.8. scp-CFG-001: 設定の解決と反映
|
|
124
|
+
|
|
125
|
+
- **Rule(MUST)**: 店舗条件は各コマンド起動時に `config/store-config.yaml` の指定を schema の既定値より優先して解決し、当該コマンド中は固定する。ファイル欠落時は既定値、不正内容なら停止する。認証は環境からだけ受け、CLI 指定や店舗設定で上書きしない。次の起動で設定が変わっても、保持済み取引の金額や受付状態を暗黙に書き換えない。
|
|
126
|
+
- **Rationale(意図)**: 隠れた設定上書きによる価格・接続先の混乱を防ぐ。
|
|
127
|
+
- **Scope(適用範囲)**: 店舗条件、本部接続、認証の初期解決。
|
|
128
|
+
- **Enforcement(検証)**: K1 でファイルなし・既定値と異なる正当な設定・破損・認証欠落を与え、既定値採用・指定値採用・停止・停止をそれぞれ確認する。実行中の変更は当該コマンドへ混入せず、次の起動で反映する。保持済み取引と新設定が両立しなければ保留し、店主代表へ照合を依頼する。
|
|
129
|
+
- **Exception(例外)**: 不正設定を削除して既定値で回避する運用は採用しない。
|
|
130
|
+
- **References(参照)**: 架空正本 `kinuya-store-config-schema`、`kinuya-cli-reference`。具体値は転載しない。
|
|
131
|
+
|
|
132
|
+
### 3.9. scp-MOD-001: 会計と印字の境界
|
|
133
|
+
|
|
134
|
+
- **Rule(MUST)**: CLI は操作と表示、販売処理は受付と保存、印刷 adapter は保存済み控えの印字を担当する。印刷コマンドには控えの読取だけを許し、売上登録を呼び出さず、印刷の失敗で確定済み会計を巻き戻さない。OS 権限拒否時に adapter が権限を自動拡大しない。
|
|
135
|
+
- **Rationale(意図)**: 印字の復旧を会計の再実行から分離するため。
|
|
136
|
+
- **Scope(適用範囲)**: CLI・販売処理・保存・印刷 adapter 間の呼出し。
|
|
137
|
+
- **Enforcement(検証)**: K1 で境界の呼出し検査、K2 で印刷失敗を注入し、会計維持と控え保持、売上送信なしを確認する。
|
|
138
|
+
- **Exception(例外)**: 境界変更は技術メンターが影響を整理し、店主代表へ判断を依頼する。
|
|
139
|
+
- **References(参照)**: 架空正本 `kinuya-module-map`、[[specdojo:ifx-cmd-sample|レシート印刷コマンド連携仕様]]。
|
|
140
|
+
|
|
141
|
+
## 4. 例外(DECリンク)
|
|
142
|
+
|
|
143
|
+
### 4.1. 例外の入口
|
|
144
|
+
|
|
145
|
+
承認済み例外はない。例外追加時は対象 Rule ID、理由・影響、期限、店主代表の判断、復帰条件を架空の決定簿 `kinuya-decision-log` で管理し、本書から接続する。期限到来時は ARC が通常規則への復帰を確認し、QE の再検証結果を PM が追跡する。送信前ビジーの再試行は通常規則であり、通信不調や用紙切れを例外の根拠にしない。
|
|
146
|
+
|
|
147
|
+
### 4.2. 報告と追跡
|
|
148
|
+
|
|
149
|
+
| 事象 | 記録先・種別 | 報告・追跡責務 |
|
|
150
|
+
| -------------------------------- | ----------------------------- | ------------------------------------------------------------------------ |
|
|
151
|
+
| 二重受付・保存失敗等の実発生 | `kinuya-register` の issue | 店番担当が対象取引を開発担当へ報告、DEV が調査、PM が追跡、QE が解消確認 |
|
|
152
|
+
| 未確定契約による受入遅延の可能性 | 同登録簿の risk | 技術メンターが影響提示、PM が依存・期限を追跡 |
|
|
153
|
+
| 自動再送等の方式変更 | 同登録簿の change と decision | 開発担当が案、同行レビュー担当が検証、店主代表が採否判断 |
|
|
154
|
+
|
|
155
|
+
問い合わせ・障害の窓口は開発担当とし、店番担当は取引番号と秘匿化済みの診断を渡す。ARC は Rule ID を維持して改訂・廃止を管理し、置換時は後継を示す。PM が関連設計・テスト・運用への追従作業を登録し、公開・互換性への影響を人間の PO へ提示する。
|
|
156
|
+
|
|
157
|
+
## 5. 関連ドキュメント導線(SYSD/SYSD-CF/NFR/OPD/OPR/DEC)
|
|
158
|
+
|
|
159
|
+
### 5.1. 正本と運用への入口
|
|
160
|
+
|
|
161
|
+
| 対象 | 参照 | 用途・状態 |
|
|
162
|
+
| ---------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------- |
|
|
163
|
+
| 操作・失敗の意味 | [[specdojo:clis-sample\|販売管理 CLI 仕様]] | 実在する完成例。会計と印字の結果、保持状態と次の手 |
|
|
164
|
+
| 印刷の外部境界 | [[specdojo:ifx-cmd-sample\|レシート印刷コマンド連携仕様]] | 実在する完成例。入出力、時間上限、失敗分類と再試行の正本 |
|
|
165
|
+
| 設定・契約・検証 | `kinuya-system-design-index`、`kinuya-sales-test-plan` | 未同梱。架空正本の所在と K1〜K3 のケース・実施証跡への入口 |
|
|
166
|
+
| 非機能・運用 | `kinuya-execution-policy`、`kinuya-log-policy`、`kinuya-recovery-procedure` | 未同梱。時間・retry 上限、保持・監視・回復の正本 |
|
|
167
|
+
| 判断・作業 | `kinuya-register`、`kinuya-decision-log`、`kinuya-sales-schedule` | 未同梱。課題・リスク・変更・判断・作業進捗を追跡 |
|
|
168
|
+
|
|
169
|
+
### 5.2. 変更影響と再検証
|
|
170
|
+
|
|
171
|
+
検証コマンドは学習例の架空 repository ルートで実行する想定であり、本 repository の実行証跡ではない。未同梱のため実行可能性の確認は Q-K3 に残す。
|
|
172
|
+
|
|
173
|
+
| 確認群 | 更新・追従する対象 | 検証コマンド・対象 |
|
|
174
|
+
| ------ | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
175
|
+
| K1 | 開発担当が設定 schema、公開 CLI 案内、adapter 依存を同期。設定変更の既定値・移行案内を更新 | 架空 script `npm run check:contracts`。設定 schema 検証と境界検査。欠落・破損・上書き・反映時点、秘密非記録・権限・売上呼出し禁止を各規則の期待結果と照合 |
|
|
176
|
+
| K2 | 開発担当が連携契約・保存 schema・回復手順を同期。既存控えの読込互換性を維持 | 架空 script `npm run test:sales-recovery`。受付後応答欠落・時間と回数の上限・保存失敗後の再起動・送信前ビジーと汎用印刷失敗を注入し、各規則の期待結果を確認 |
|
|
177
|
+
| K3 | OPS が引継ぎ・保持・閲覧・連絡手順を更新。DEV が記録形式を変えたら旧記録の移行も確認 | 架空 script `npm run test:sales-audit` と店番交代の実演。取引の相関、秘密非記録、紙面照合と引継ぎを確認 |
|
|
178
|
+
|
|
179
|
+
## 6. 未決事項と公開前確認
|
|
180
|
+
|
|
181
|
+
### 6.1. 判断待ちと後続への影響
|
|
182
|
+
|
|
183
|
+
未同梱の正本を整備したうえで受入する設計例である。Q-K ID は論点 ID であり、発行済みチケットではない。PM は次の計画更新時かつ各判断期限までに登録簿と `kinuya-sales-schedule` へ接続する。
|
|
184
|
+
|
|
185
|
+
| ID・作成対象 | 判断者・担当 | 判断期限 | 影響・当面の扱い | 次アクションと解消条件 |
|
|
186
|
+
| -------------------------------- | ------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
187
|
+
| Q-K1: 本部受付契約・実行制約 | ARC / DEV が案、PO が判断 | K1 着手前 | _UNDECIDED_: scp-IDM-001 / scp-TIM-001 / scp-RET-001 の本部照合・時間・retry 値が未確定。K1 の前提と通信失敗経路の受入を保留 | PM が issue と作業を起票。DEV が設定キー・値・単位・待機方式と回復契約を整え、QE がテスト計画へ境界・重複防止を接続。印刷は既存の連携仕様を使用 |
|
|
188
|
+
| Q-K2: 監視・保持・回復手順 | OPS が案、PO が判断 | K3 着手前 | _UNDECIDED_: scp-LOG-001 / scp-TRC-001 / scp-SEC-001 の定期確認間隔、保存期間、閲覧権限、窓口の具体的な連絡手段が未確定。引継ぎの受入を保留 | PM が依存 risk と整備作業を登録。OPS が運用設計・回復手順を整え、QE と検知・照合・引継ぎを実演。PO が運用負荷と留保範囲を判断 |
|
|
189
|
+
| Q-K3: 正本・検証 script と互換性 | DEV が整備、QE が確認 | 正本・script は K1 着手前、全検証は運用開始判断前 | _TODO_: 未同梱の正本・script を整備して全規則の実装適合を確認する。実機停止・紙面と旧控えの互換性も未検証 | PM が issue と作業を登録。DEV が設計索引・テスト計画と実コマンドを接続。QE が K1→K2→K3 の証跡を確認し、PM が実 ID と完了証跡を接続 |
|
|
190
|
+
|
|
191
|
+
### 6.2. 公開・昇格の判断条件
|
|
192
|
+
|
|
193
|
+
- 技術メンターと開発担当が全規則を実装・契約へ照合し、未確認を解消または対象外の理由付きで明示する。
|
|
194
|
+
- 同行レビュー担当と OPS が K1〜K3 の結果、失敗時の保持、秘密非記録、取引・印字の照合と次の店番への引継ぎを確認する。
|
|
195
|
+
- PM が判断待ちの担当・期限・作業依存・実 ID を接続し、人間の店主代表(PO)が承認・期限付き留保・差し戻しを選ぶ。留保には範囲・期限・再確認責任を決定簿へ記録する。外部公開に秘密値・顧客情報を含めないことも PO が確認し、公開と `ready` 昇格を最終判断する。agent は `draft` を維持する。
|
|
@@ -2,37 +2,98 @@
|
|
|
2
2
|
specdojo:
|
|
3
3
|
id: specdojo:sysd-index-sample
|
|
4
4
|
type: architecture
|
|
5
|
-
status:
|
|
5
|
+
status: ready
|
|
6
6
|
rulebook: specdojo:sysd-index-rulebook
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
#
|
|
9
|
+
# 駄菓子屋きぬや 販売管理 CLI システム設計索引(SYSD Index)
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
店番担当が販売を記録し、開発担当が会計・保存・印刷の変更先を探せるよう、設計の正本(SSOT: Single Source of Truth)への入口を集約する。詳細な値・構文・構造は各正本へ委ねる。
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
## 1. 概要(対象範囲・更新責任)
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
対象は単一店舗・現金販売の CLI `kinuya-pos`、取引・売上・レシートのローカル記録、本部の商品・売上 API との接続、外部印刷コマンドへの依頼である。通常利用のタブレット画面とは別の学習用 CLI を店舗端末1台で人が操作する。会計確定と印字完了を区別し、通信結果不明の取引を未登録と断定しない。通常操作と停止時の引継ぎは [[specdojo:clis-sample|販売管理 CLI 仕様]] を参照する。つけ販売、在庫調整、EC、複数店舗管理、本格会計連携は本索引の対象外である。
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
- 前提: プロジェクト文脈は handbook の共通方針に準拠する
|
|
19
|
-
- 参照: `../rulebooks/sysd-index-rulebook.md`
|
|
17
|
+
_ASSUMPTION_: 以下のコード・schema・script のパスと検証ケースは、完成した索引の粒度を示す架空リポジトリの設定であり、本リポジトリには同梱しない。パス・コマンドの基準はそのリポジトリルートとする。実在する sample へのリンクは記述例の参照であり、架空ファイルの存在や採用技術の合意を示すものではない。
|
|
20
18
|
|
|
21
|
-
|
|
19
|
+
| ロール | 更新・確認・承認の対象 |
|
|
20
|
+
| --------------------------- | ----------------------------------------------------------------------------------------- |
|
|
21
|
+
| 技術メンター(ARC / PM) | ARC として接続境界と索引を更新し、PM として未整備の契約に伴う後続作業と依存関係を管理する |
|
|
22
|
+
| 開発担当(DEV) | CLI、API クライアント、保存 schema、生成・検証コマンドを更新する |
|
|
23
|
+
| 店舗運営アドバイザー(OPS) | ログ設定、手動照合・再印刷の手順、障害時の引継ぎを更新する |
|
|
24
|
+
| 同行レビュー担当(QE) | 正常販売、保存失敗、通信結果不明、印字警告のケースと期待結果を確認する |
|
|
25
|
+
| 店主代表(PO) | 結果不明の取引を保留する扱い、運用負担、未決事項の留保と公開可否を承認する |
|
|
22
26
|
|
|
23
|
-
-
|
|
24
|
-
- 必須観点: 対象、条件、判定基準、責任者
|
|
27
|
+
略語は、SYSD が System Design(システム設計)、C4 が構成を段階的に示す図法、NFR が Non-Functional Requirements(非機能要件)、OPD / OPR が Operations Policy and Design / Operations Procedure(運用方針・設計 / 運用手順)、DEC が Decision Record(判断記録)を表す。
|
|
25
28
|
|
|
26
|
-
##
|
|
29
|
+
## 2. SSOT 一覧(表形式)
|
|
27
30
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
31
|
+
| 種別 | SSOT(正本) | 参照先 | 更新責任 | 検証方法・備考 |
|
|
32
|
+
| ------------------ | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
33
|
+
| 公開操作・内部 API | CLI 定義。内部 HTTP API は非該当(端末上の CLI のみ) | `src/cli/kinuya-pos.ts`、`kinuya-cli-reference`、[[specdojo:clis-sample\|販売管理 CLI 仕様]] | DEV / ARC | `npm run typecheck` と `tests/cli/sales.test.ts`。構文・終了コード値はリファレンスを正とする |
|
|
34
|
+
| 外部 API | 商品照会・売上登録の契約 | `contracts/products.openapi.yaml`、`contracts/sales.openapi.yaml`、`src/infra/head-office.ts` | ARC / DEV | `npm run lint:api`。受付照会・重複排除契約は公開前の未決事項 |
|
|
35
|
+
| 非同期連携 | ブローカー・AsyncAPI は非該当(要求・応答による連携) | `src/infra/head-office.ts` | ARC / DEV | 結果不明は保存記録と本部受付の照合へ渡す。自動再送を前提にしない |
|
|
36
|
+
| DB schema・移行 | RDBMS・SQL migration は非該当(ファイル保存)。取引・販売控えの schema と移行処理 | `schemas/session.schema.json`(`kinuya-session-schema`)、`schemas/sales-record.schema.json`(`kinuya-sales-record-schema`)、`src/storage/migrate-records.ts` | DEV | `npm run validate:records` と `tests/storage/migration.test.ts`。旧形式の読込と再移行時の重複なしを確認 |
|
|
37
|
+
| レシート形式 | 保存・印刷に共通のレシート形式(DB の代替となるファイル契約) | `schemas/receipt-format.schema.json`(`kinuya-receipt-format-schema`) | DEV / OPS | `npm run validate:records` と `tests/infra/printer.test.ts`。保存済み控えと印刷入力が同じ形式に適合することを確認 |
|
|
38
|
+
| モジュール境界 | CLI、取引処理、保存、本部接続、印刷アダプター | `src/cli/`、`src/sales/`、`src/storage/`、`src/infra/`、`eslint.config.js` | ARC / DEV | `npm run lint`。取引処理から直接プリンタを操作しない |
|
|
39
|
+
| 設定・実行構成 | 店舗設定・環境変数の読込と設定 schema | `config/store-config.yaml`、`schemas/store-config.schema.json`(`kinuya-store-config-schema`)、`src/config/load.ts` | DEV / OPS | `npm run validate:config`。秘密値を表示・ログへ出力しない。設定破損時は停止する |
|
|
40
|
+
| 外部コマンド | 印刷契約とアダプター | [[specdojo:ifx-cmd-sample\|レシート印刷コマンド連携仕様]]、`src/infra/printer.ts` | DEV / OPS | `tests/infra/printer.test.ts` で成功・用紙切れ・時間切れを検証 |
|
|
41
|
+
| Job・定期処理 | 非該当(店番担当が対話操作する範囲) | [[specdojo:clis-sample\|販売管理 CLI 仕様]] | PO / OPS | 閉店集計・自動同期の追加は別の要求・運用判断を必要とする |
|
|
42
|
+
| 監視・ログ・通知 | 構造化ログとローカル障害表示。常駐 APM・外部通知は初期例では非該当 | `config/logging.json`、`schemas/audit-event.schema.json`、`src/infra/logger.ts` | OPS / DEV | `tests/ops/logging.test.ts`。対象取引・停止原因・照合待ちを残し、秘密値を記録しない。有人確認で運用可能かは PO 承認待ち |
|
|
43
|
+
| ソース管理・CI | ブランチ・PR の統合規約、ワークフロー、ローカル検査設定 | `docs/development/contributing.md`、`.github/workflows/ci.yml`、`package.json` | DEV / QE | DEV が PR を作成し、QE の検査確認後に統合する。CI で lint、schema、テスト、ビルドの成功を確認 |
|
|
33
44
|
|
|
34
|
-
##
|
|
45
|
+
## 3. 自動生成物(生成コマンド/生成先/閲覧先)
|
|
35
46
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
|
47
|
+
次の生成物は直接編集せず、入力正本を変えて再生成する。取引データや売上控えは業務記録であり、設計から再生成するファイルには含めない。
|
|
48
|
+
|
|
49
|
+
| 生成物 | 入力元(SSOT) | 生成コマンド | 生成先 | 閲覧先・更新タイミング |
|
|
50
|
+
| -------------------- | ----------------------------------------------------------------- | -------------------------- | ---------------------------------------- | ---------------------------------------------------- |
|
|
51
|
+
| API クライアント型 | `contracts/products.openapi.yaml`、`contracts/sales.openapi.yaml` | `npm run api:generate` | `src/generated/api-types.ts` | IDE と型検査。いずれかの契約変更時に生成 |
|
|
52
|
+
| 保存レコード型 | `schemas/session.schema.json`、`schemas/sales-record.schema.json` | `npm run records:generate` | `src/generated/record-types.ts` | 保存・読込処理。取引・販売控えの schema 変更時に生成 |
|
|
53
|
+
| CLI 構文リファレンス | `src/cli/kinuya-pos.ts` | `npm run docs:cli` | `docs/reference/kinuya-cli-reference.md` | `kinuya-cli-reference`。コマンド定義変更時に生成 |
|
|
54
|
+
| 配布 CLI | `src/`、生成済み型 | `npm run build` | `dist/` | 店舗端末へ導入する配布物。リリース時に生成 |
|
|
55
|
+
|
|
56
|
+
## 4. 変更の入口(典型ケース)
|
|
57
|
+
|
|
58
|
+
コマンドは架空リポジトリのルートで実行する。下表は変更時の検証手順であり、実行済みの証跡ではない。テストコマンドは各対象ファイルの全ケース成功、静的検査・生成・ビルドは終了コード `0` を合格とする。
|
|
59
|
+
|
|
60
|
+
| 変更トリガー | 最初に更新する SSOT | 追従する生成物・関連文書 | 検証対象ケース・実行コマンド・期待結果 |
|
|
61
|
+
| ---------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
62
|
+
| 本部 API 契約の変更 | `contracts/products.openapi.yaml` または `contracts/sales.openapi.yaml`、`src/infra/head-office.ts` | API 型、販売操作仕様、照合手順 | `npm run lint:api`、`npm run api:generate`、`npm run test:integration -- tests/infra/head-office.test.ts`。商品未登録で明細を増やさず、正常受付で同じ取引を1件だけ記録し、売上応答欠落では保持記録を照合待ちにする |
|
|
63
|
+
| 保存形式・移行の変更 | `schemas/session.schema.json`、`schemas/sales-record.schema.json`、`src/storage/migrate-records.ts` | 保存レコード型、復旧手順 | `npm run records:generate`、`npm run validate:records`、`npm run test:unit -- tests/storage/migration.test.ts tests/storage/recovery.test.ts`。旧形式を読み、再移行で販売記録を重複させない。容量不足・権限拒否で保存に失敗したときは取引番号・保存済み範囲・本部受付状態を残し、売上を再登録しない |
|
|
64
|
+
| CLI・設定の変更 | `src/cli/kinuya-pos.ts`、`schemas/store-config.schema.json` | CLI リファレンス、[[specdojo:clis-sample\|販売管理 CLI 仕様]] | `npm run docs:cli`、`npm run validate:config`、`npm run test:unit -- tests/cli/sales.test.ts`。設定破損で会計要求前に停止し、正常会計では本部受付とローカル保存を確認して完了を表示する |
|
|
65
|
+
| 印刷連携・レシート形式の変更 | 外部印刷契約、`schemas/receipt-format.schema.json`、`src/infra/printer.ts` | [[specdojo:ifx-cmd-sample\|レシート印刷コマンド連携仕様]]、再印刷手順 | `npm run validate:records`、`npm run test:integration -- tests/infra/printer.test.ts`。正常時は控えと印字対象が一致し、用紙切れ・時間切れ・結果の対象不一致では警告と控えを残す。結果不明を自動再印刷せず、売上を再送しない |
|
|
66
|
+
| Job・定期処理の新設 | 別途合意する要求と実行定義(現状は非該当) | 本索引、運用手順、対象処理のテスト | PO が必要性を判断後、DEV / OPS が検証コマンドと正常・重複起動・失敗保持の期待結果を定義する。未定義のまま導入完了としない |
|
|
67
|
+
| ログ・通知の変更 | `config/logging.json`、`schemas/audit-event.schema.json` | 障害引継ぎ手順、監視判断記録 | `npm run test:unit -- tests/ops/logging.test.ts`。停止原因・対象取引・照合待ちが記録され、認証値を含まない。外部通知導入時は通知先・一次対応も別途受入確認する |
|
|
68
|
+
| 正本の移動・廃止 | 移動する定義ファイルと `package.json` の入力パス | 本索引、生成型、操作仕様、復旧手順、対象テスト、CI | DEV が参照元のパスを検索して後継へ更新し、影響する表中の生成・検証コマンドを実行する。旧パス参照が残らず、後継から同じ出力を生成できることを QE が確認する。ARC は設計導線、OPS は運用手順、PM は後続作業を更新する |
|
|
69
|
+
|
|
70
|
+
全変更で `npm run lint`、`npm run typecheck`、`npm run build` を実行し、型と配布物への影響も確認する。
|
|
71
|
+
|
|
72
|
+
## 5. 関連ドキュメント導線(C4 / NFR / OPD / DEC 等)
|
|
73
|
+
|
|
74
|
+
| 区分 | ドキュメント | 役割・参照目的 | 状態・備考 |
|
|
75
|
+
| ------------------ | -------------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
|
76
|
+
| プロジェクト定義 | [[specdojo:prj-overview-sample\|駄菓子屋きぬや プロジェクト概要]] | 日々の記録を継続する目的と単一店舗の前提を確認する | 例を参照可能。本索引は学習用 CLI の範囲に限定 |
|
|
77
|
+
| 操作仕様 | [[specdojo:clis-sample\|販売管理 CLI 仕様]] | 店番担当の操作、停止理由、結果不明時の引継ぎ | 例を参照可能。構文・設定・保存の正本は架空リポジトリ側 |
|
|
78
|
+
| 外部コマンド契約 | [[specdojo:ifx-cmd-sample\|レシート印刷コマンド連携仕様]] | 会計と印刷の責任分界、応答・時間切れの扱い | 例を参照可能。実機受入は未実施 |
|
|
79
|
+
| 構成・システム設計 | `kinuya-cxd`、`kinuya-sysd-critical-flows` | 本部・保存・印刷の境界と会計の重要経路 | 未作成。当面は本索引と操作仕様を参照 |
|
|
80
|
+
| 業務・データ契約 | `kinuya-sales-flow`、`ifx-api-kinuya-products.yaml`、`ifx-api-kinuya-sales.yaml` | 商品照会と売上登録・照合契約への接続 | 未作成。API 連携仕様は各 `contracts/` 正本への導線と責任分界を記す予定。構造は転載しない。受付回復の合意は未了 |
|
|
81
|
+
| 非機能・運用 | `kinuya-nfr-index`、`kinuya-opd-monitoring`、`kinuya-opr-recovery` | 停止時の保留、有人監視、復旧と再印刷 | 未作成。有人確認の負担と運用可否が承認待ち |
|
|
82
|
+
| テスト・判断記録 | `kinuya-test-index`、`kinuya-dec-recovery` | 対象ケースと回復方式の承認記録 | 未作成。現状は本索引の変更経路をテスト設計の入力にする |
|
|
83
|
+
|
|
84
|
+
## 6. 未決事項・変更影響・公開前確認
|
|
85
|
+
|
|
86
|
+
### 6.1. 未決事項と後続作業への影響
|
|
87
|
+
|
|
88
|
+
| 項目・対象 | 現状と影響範囲 | 担当ロール | 解消条件・次アクション |
|
|
89
|
+
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
90
|
+
| API の結果照合・回復 | _UNDECIDED_: 受付照会・重複排除・保存失敗後の回復契約が未合意。結果不明の取引は自動再送できない | ARC / DEV / PO | 公開前に契約と回復手順を整え、QE が受付済み・未受付・応答欠落の期待結果を確認する。API 正本、生成型、関連導線を更新 |
|
|
91
|
+
| 有人監視と通知 | _UNDECIDED_: 常駐監視・外部通知を持たず、店番担当が停止表示とログを確認する構成案。見逃しと参加負荷を評価できていない | OPS / PO | 店主代表が試行時の確認負担を評価し、公開前に有人方式の可否を判断。通知を追加するなら設定・手順・受入ケースを更新 |
|
|
92
|
+
| 詳細仕様・記録の索引 | _TODO_: 関連ドキュメント導線で未作成とした構成・業務・非機能・運用・テスト・判断記録がない。現状は本索引と操作・印刷仕様を代替参照とし、詳細設計の確認を保留する | ARC / OPS / QE / PM | 公開前に ARC が構成・業務・非機能、OPS が運用、QE がテストを整備し、PM が後続作業を管理する。ARC は本索引をリンクへ更新し、判断記録に PO の留保・承認結果を残す |
|
|
93
|
+
| 印刷の実機受入 | _TODO_: 用紙切れ・時間切れ時の紙面照合、二重印字の可能性を未確認 | DEV / QE / OPS | 店舗端末で会計再実行なしの控え確認・再印刷を検証し、運用手順へ反映してから公開判断へ渡す |
|
|
94
|
+
|
|
95
|
+
### 6.2. 公開・昇格前の確認条件
|
|
96
|
+
|
|
97
|
+
- ARC / DEV は架空参照を実案件の正本へ置き換え、API・保存・設定・監視の所在と生成コマンドを確認する。静的検査、対象ケース、ビルドが前記の期待結果を満たす。
|
|
98
|
+
- OPS / QE は通信結果不明、保存失敗、印字警告の引継ぎが同じ取引を追跡できることと、有人確認の負担を評価する。
|
|
99
|
+
- 人間の店主代表(PO)が回復契約、監視方式、未作成文書の留保可否を判断する。本例は `draft` のままとし、記載した構成案を業務判断の確定として扱わない。
|