specdojo 0.4.7 → 0.5.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.
Files changed (267) hide show
  1. package/.github/agents/specdojo-orchestrator.md +14 -9
  2. package/CHANGELOG.md +46 -0
  3. package/dist/commands/init.js +3 -0
  4. package/dist/commands/night-orchestrator.js +33 -4
  5. package/dist/dashboard/dashboard.js +5 -6
  6. package/dist/dashboard/timeline-build.js +5 -1
  7. package/dist/dashboard/timeline.js +6 -3
  8. package/dist/docs/yaml-pages.js +17 -17
  9. package/dist/exec/core.js +2 -0
  10. package/dist/exec/pipeline-state.js +5 -2
  11. package/dist/exec/plans-core.js +3 -2
  12. package/dist/exec/plans-generation.js +9 -5
  13. package/dist/exec/plans-grade-findings.js +16 -0
  14. package/dist/exec/plans-planning.js +43 -0
  15. package/dist/exec/plans-storage.js +5 -2
  16. package/dist/exec/register.js +16 -1
  17. package/dist/exec/repo-integration-sync.js +9 -0
  18. package/dist/exec/repo-integration.js +17 -2
  19. package/dist/exec/repo-trace.js +17 -4
  20. package/dist/exec/results.js +2 -0
  21. package/dist/exec/run/register-core.js +11 -0
  22. package/dist/exec/run/register-mode.js +19 -1
  23. package/dist/exec/run/register-resume.js +22 -0
  24. package/dist/exec/run/register-worktree.js +23 -0
  25. package/dist/exec/strategy.js +2 -0
  26. package/dist/exec/task-repos.js +18 -4
  27. package/dist/exec/worktree-ops-commit.js +7 -1
  28. package/dist/grade/apply.js +6 -2
  29. package/dist/grade/markdown.js +7 -2
  30. package/dist/grade/plan.js +6 -4
  31. package/dist/register/approach.js +19 -0
  32. package/dist/register/catalog-status.js +49 -0
  33. package/dist/register/core.js +3 -0
  34. package/dist/register/create-commands.js +34 -4
  35. package/dist/register/dependency.js +123 -0
  36. package/dist/register/derivation.js +2 -2
  37. package/dist/register/epic.js +42 -0
  38. package/dist/register/event-merge.js +5 -2
  39. package/dist/register/events.js +4 -0
  40. package/dist/register/external-project.js +4 -0
  41. package/dist/register/item.js +10 -0
  42. package/dist/register/maintenance-commands.js +7 -1
  43. package/dist/register/planning.js +37 -0
  44. package/dist/register/register.js +5 -1
  45. package/dist/register/renumber.js +12 -4
  46. package/dist/register/views.js +55 -4
  47. package/dist/schedule/schedule.js +3 -1
  48. package/dist/schedule/strategy-generate-scope.js +5 -1
  49. package/dist/schedule/strategy-generate.js +1 -0
  50. package/dist/schedule/strategy-profiles.js +1 -1
  51. package/dist/shared/agent-types.js +3 -0
  52. package/dist/shared/grade-result.js +23 -5
  53. package/dist/shared/markdownlint-config.js +38 -0
  54. package/dist/shared/markdownlint-scaffold.js +2 -9
  55. package/dist/shared/specdojo-config.js +10 -3
  56. package/dist/shared/specdojo-gitignore.js +4 -0
  57. package/docs/ja/specdojo/exec-templates/xep-catalog-planning-template.md +24 -0
  58. package/docs/ja/specdojo/exec-templates/xep-strategy-planning-template.md +24 -0
  59. package/docs/ja/specdojo/guides/docs-editing-guide.md +14 -1
  60. package/docs/ja/specdojo/guides/docs-structure-guide.md +10 -8
  61. package/docs/ja/specdojo/guides/exec-operation-guide.md +16 -15
  62. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +19 -1
  63. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +2 -0
  64. package/docs/ja/specdojo/guides/quick-start-guide.md +37 -14
  65. package/docs/ja/specdojo/guides/register-operation-guide.md +44 -15
  66. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +16 -16
  67. package/docs/ja/specdojo/guides/timeline-design-guide.md +37 -33
  68. package/docs/ja/specdojo/recipes/tsd-recipe.md +198 -0
  69. package/docs/ja/specdojo/references/command-reference.md +42 -4
  70. package/docs/ja/specdojo/references/specdojo-config-reference.md +20 -8
  71. package/docs/ja/specdojo/rulebooks/atc-index-rulebook.md +1 -0
  72. package/docs/ja/specdojo/rulebooks/atc-rulebook.md +1 -0
  73. package/docs/ja/specdojo/rulebooks/bac-rulebook.md +5 -4
  74. package/docs/ja/specdojo/rulebooks/bdd-rulebook.md +3 -2
  75. package/docs/ja/specdojo/rulebooks/bds-rulebook.md +4 -3
  76. package/docs/ja/specdojo/rulebooks/bes-index-rulebook.md +8 -7
  77. package/docs/ja/specdojo/rulebooks/bes-rulebook.md +4 -3
  78. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +1 -0
  79. package/docs/ja/specdojo/rulebooks/br-rulebook.md +1 -0
  80. package/docs/ja/specdojo/rulebooks/ccd-mermaid-rulebook.md +1 -0
  81. package/docs/ja/specdojo/rulebooks/cdfd-mermaid-rulebook.md +1 -0
  82. package/docs/ja/specdojo/rulebooks/cdfd-overview-rulebook.md +1 -0
  83. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +1 -0
  84. package/docs/ja/specdojo/rulebooks/cdfd-uc-rulebook.md +1 -0
  85. package/docs/ja/specdojo/rulebooks/cdsd-rulebook.md +3 -2
  86. package/docs/ja/specdojo/rulebooks/cld-rulebook.md +2 -1
  87. package/docs/ja/specdojo/rulebooks/cnd-mermaid-rulebook.md +1 -0
  88. package/docs/ja/specdojo/rulebooks/cnd-rulebook.md +1 -0
  89. package/docs/ja/specdojo/rulebooks/cop-index-rulebook.md +2 -1
  90. package/docs/ja/specdojo/rulebooks/cop-rulebook.md +3 -2
  91. package/docs/ja/specdojo/rulebooks/cpd-mermaid-rulebook.md +1 -0
  92. package/docs/ja/specdojo/rulebooks/cpd-rulebook.md +1 -0
  93. package/docs/ja/specdojo/rulebooks/cstd-rulebook.md +1 -0
  94. package/docs/ja/specdojo/rulebooks/cxd-mermaid-rulebook.md +1 -0
  95. package/docs/ja/specdojo/rulebooks/cxd-rulebook.md +1 -0
  96. package/docs/ja/specdojo/rulebooks/dct-index-rulebook.md +1 -0
  97. package/docs/ja/specdojo/rulebooks/dct-rulebook.md +1 -0
  98. package/docs/ja/specdojo/rulebooks/dec-rulebook.md +1 -0
  99. package/docs/ja/specdojo/rulebooks/dmd-index-rulebook.md +2 -1
  100. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +2 -1
  101. package/docs/ja/specdojo/rulebooks/etc-index-rulebook.md +1 -0
  102. package/docs/ja/specdojo/rulebooks/etc-rulebook.md +1 -0
  103. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +9 -6
  104. package/docs/ja/specdojo/rulebooks/ifd-mermaid-rulebook.md +1 -0
  105. package/docs/ja/specdojo/rulebooks/ifx-api-rulebook.md +3 -1
  106. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +2 -1
  107. package/docs/ja/specdojo/rulebooks/ifx-file-rulebook.md +2 -1
  108. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +2 -0
  109. package/docs/ja/specdojo/rulebooks/ifx-msg-rulebook.md +4 -2
  110. package/docs/ja/specdojo/rulebooks/imp-business-rulebook.md +1 -0
  111. package/docs/ja/specdojo/rulebooks/imp-data-rulebook.md +1 -0
  112. package/docs/ja/specdojo/rulebooks/imp-interface-rulebook.md +1 -0
  113. package/docs/ja/specdojo/rulebooks/imp-operations-rulebook.md +1 -0
  114. package/docs/ja/specdojo/rulebooks/imp-test-rulebook.md +1 -0
  115. package/docs/ja/specdojo/rulebooks/itc-index-rulebook.md +1 -0
  116. package/docs/ja/specdojo/rulebooks/itc-rulebook.md +1 -0
  117. package/docs/ja/specdojo/rulebooks/mip-index-rulebook.md +2 -1
  118. package/docs/ja/specdojo/rulebooks/mm-rulebook.md +1 -0
  119. package/docs/ja/specdojo/rulebooks/mtp-rulebook.md +4 -3
  120. package/docs/ja/specdojo/rulebooks/nfr-availability-rulebook.md +9 -8
  121. package/docs/ja/specdojo/rulebooks/nfr-index-rulebook.md +10 -9
  122. package/docs/ja/specdojo/rulebooks/nfr-integrity-rulebook.md +9 -8
  123. package/docs/ja/specdojo/rulebooks/nfr-maintainability-rulebook.md +9 -8
  124. package/docs/ja/specdojo/rulebooks/nfr-operations-rulebook.md +9 -8
  125. package/docs/ja/specdojo/rulebooks/nfr-performance-rulebook.md +9 -8
  126. package/docs/ja/specdojo/rulebooks/nfr-reliability-rulebook.md +10 -9
  127. package/docs/ja/specdojo/rulebooks/nfr-security-safety-rulebook.md +9 -8
  128. package/docs/ja/specdojo/rulebooks/nfr-usability-rulebook.md +9 -8
  129. package/docs/ja/specdojo/rulebooks/ntp-rulebook.md +7 -6
  130. package/docs/ja/specdojo/rulebooks/opd-index-rulebook.md +1 -0
  131. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +1 -0
  132. package/docs/ja/specdojo/rulebooks/opr-index-rulebook.md +1 -0
  133. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +1 -0
  134. package/docs/ja/specdojo/rulebooks/otp-index-rulebook.md +2 -1
  135. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +2 -1
  136. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +50 -36
  137. package/docs/ja/specdojo/rulebooks/pm-change-request-log-rulebook.md +1 -0
  138. package/docs/ja/specdojo/rulebooks/pm-communication-plan-rulebook.md +1 -0
  139. package/docs/ja/specdojo/rulebooks/pm-issue-log-rulebook.md +1 -0
  140. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +1 -0
  141. package/docs/ja/specdojo/rulebooks/pm-organization-rulebook.md +1 -0
  142. package/docs/ja/specdojo/rulebooks/pm-plan-rulebook.md +1 -0
  143. package/docs/ja/specdojo/rulebooks/pm-quality-management-plan-rulebook.md +1 -0
  144. package/docs/ja/specdojo/rulebooks/pm-raci-rulebook.md +1 -0
  145. package/docs/ja/specdojo/rulebooks/pm-risk-register-rulebook.md +1 -0
  146. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +1 -0
  147. package/docs/ja/specdojo/rulebooks/pr-rulebook.md +1 -0
  148. package/docs/ja/specdojo/rulebooks/prj-assumptions-constraints-dependencies-rulebook.md +1 -0
  149. package/docs/ja/specdojo/rulebooks/prj-charter-rulebook.md +1 -0
  150. package/docs/ja/specdojo/rulebooks/prj-comparison-of-alternatives-rulebook.md +1 -0
  151. package/docs/ja/specdojo/rulebooks/prj-issues-and-approach-rulebook.md +1 -0
  152. package/docs/ja/specdojo/rulebooks/prj-overview-rulebook.md +1 -0
  153. package/docs/ja/specdojo/rulebooks/prj-scope-rulebook.md +1 -0
  154. package/docs/ja/specdojo/rulebooks/prj-stakeholder-register-rulebook.md +1 -0
  155. package/docs/ja/specdojo/rulebooks/prj-success-criteria-and-acceptance-criteria-rulebook.md +1 -0
  156. package/docs/ja/specdojo/rulebooks/sac-rulebook.md +3 -2
  157. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -0
  158. package/docs/ja/specdojo/rulebooks/sf-index-rulebook.md +7 -6
  159. package/docs/ja/specdojo/rulebooks/sf-rulebook.md +4 -3
  160. package/docs/ja/specdojo/rulebooks/sld-rulebook.md +2 -1
  161. package/docs/ja/specdojo/rulebooks/stc-index-rulebook.md +1 -0
  162. package/docs/ja/specdojo/rulebooks/stc-rulebook.md +1 -0
  163. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +1 -0
  164. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +1 -0
  165. package/docs/ja/specdojo/rulebooks/sysd-critical-flows-rulebook.md +2 -1
  166. package/docs/ja/specdojo/rulebooks/sysd-cross-cutting-policy-rulebook.md +9 -8
  167. package/docs/ja/specdojo/rulebooks/sysd-index-rulebook.md +2 -1
  168. package/docs/ja/specdojo/rulebooks/sysd-rulebook.md +1 -0
  169. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +1 -0
  170. package/docs/ja/specdojo/rulebooks/trc-requirements-to-specs-rulebook.md +1 -0
  171. package/docs/ja/specdojo/rulebooks/trc-requirements-to-tests-rulebook.md +1 -0
  172. package/docs/ja/specdojo/rulebooks/tsd-index-rulebook.md +80 -61
  173. package/docs/ja/specdojo/rulebooks/tsd-rulebook.md +111 -63
  174. package/docs/ja/specdojo/rulebooks/tsp-index-rulebook.md +1 -0
  175. package/docs/ja/specdojo/rulebooks/uis-rulebook.md +3 -2
  176. package/docs/ja/specdojo/rulebooks/utc-index-rulebook.md +1 -0
  177. package/docs/ja/specdojo/rulebooks/utc-rulebook.md +1 -0
  178. package/docs/ja/specdojo/samples/atc-index-sample.md +1 -1
  179. package/docs/ja/specdojo/samples/atc-sample.md +1 -1
  180. package/docs/ja/specdojo/samples/bac-sample.md +1 -1
  181. package/docs/ja/specdojo/samples/bdd-sample.yaml +1 -1
  182. package/docs/ja/specdojo/samples/bds-sample.md +1 -1
  183. package/docs/ja/specdojo/samples/bes-index-sample.md +1 -1
  184. package/docs/ja/specdojo/samples/bes-sample.md +1 -1
  185. package/docs/ja/specdojo/samples/ccd-sample.md +1 -1
  186. package/docs/ja/specdojo/samples/cdfd-sample.md +1 -1
  187. package/docs/ja/specdojo/samples/cdfd-uc-sample.md +1 -1
  188. package/docs/ja/specdojo/samples/cdsd-sample.md +1 -1
  189. package/docs/ja/specdojo/samples/cld-sample.md +1 -1
  190. package/docs/ja/specdojo/samples/cnd-sample.md +1 -1
  191. package/docs/ja/specdojo/samples/cop-index-sample.md +1 -1
  192. package/docs/ja/specdojo/samples/cop-sample.md +1 -1
  193. package/docs/ja/specdojo/samples/cpd-sample.md +1 -1
  194. package/docs/ja/specdojo/samples/cstd-sample.md +1 -1
  195. package/docs/ja/specdojo/samples/cxd-sample.md +1 -1
  196. package/docs/ja/specdojo/samples/dmd-index-sample.md +1 -1
  197. package/docs/ja/specdojo/samples/dmd-sample.md +1 -1
  198. package/docs/ja/specdojo/samples/etc-index-sample.md +1 -1
  199. package/docs/ja/specdojo/samples/etc-sample.md +1 -1
  200. package/docs/ja/specdojo/samples/gl-sample.yaml +2 -0
  201. package/docs/ja/specdojo/samples/ifd-sample.md +1 -1
  202. package/docs/ja/specdojo/samples/ifx-api-sample.yaml +1 -0
  203. package/docs/ja/specdojo/samples/ifx-cmd-sample.yaml +1 -1
  204. package/docs/ja/specdojo/samples/ifx-file-sample.md +1 -1
  205. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +1 -0
  206. package/docs/ja/specdojo/samples/ifx-msg-sample.yaml +2 -1
  207. package/docs/ja/specdojo/samples/itc-index-sample.md +1 -1
  208. package/docs/ja/specdojo/samples/itc-sample.md +1 -1
  209. package/docs/ja/specdojo/samples/mtp-sample.md +1 -1
  210. package/docs/ja/specdojo/samples/nfr-availability-sample.md +1 -1
  211. package/docs/ja/specdojo/samples/nfr-index-sample.md +1 -1
  212. package/docs/ja/specdojo/samples/nfr-integrity-sample.md +1 -1
  213. package/docs/ja/specdojo/samples/nfr-maintainability-sample.md +1 -1
  214. package/docs/ja/specdojo/samples/nfr-operations-sample.md +1 -1
  215. package/docs/ja/specdojo/samples/nfr-performance-sample.md +1 -1
  216. package/docs/ja/specdojo/samples/nfr-reliability-sample.md +1 -1
  217. package/docs/ja/specdojo/samples/nfr-security-safety-sample.md +1 -1
  218. package/docs/ja/specdojo/samples/nfr-usability-sample.md +1 -1
  219. package/docs/ja/specdojo/samples/ntp-sample.md +1 -1
  220. package/docs/ja/specdojo/samples/opd-sample.md +1 -1
  221. package/docs/ja/specdojo/samples/opr-sample.md +1 -1
  222. package/docs/ja/specdojo/samples/otp-index-sample.md +1 -1
  223. package/docs/ja/specdojo/samples/otp-sample.md +1 -1
  224. package/docs/ja/specdojo/samples/prj-stakeholder-register-sample.md +1 -1
  225. package/docs/ja/specdojo/samples/sac-sample.md +1 -1
  226. package/docs/ja/specdojo/samples/sf-index-sample.md +1 -1
  227. package/docs/ja/specdojo/samples/sf-sample.md +1 -1
  228. package/docs/ja/specdojo/samples/sld-sample.md +1 -1
  229. package/docs/ja/specdojo/samples/stc-index-sample.md +1 -1
  230. package/docs/ja/specdojo/samples/stc-sample.md +1 -1
  231. package/docs/ja/specdojo/samples/stsd-sample.md +1 -1
  232. package/docs/ja/specdojo/samples/sysd-critical-flows-sample.md +1 -1
  233. package/docs/ja/specdojo/samples/sysd-cross-cutting-policy-sample.md +1 -1
  234. package/docs/ja/specdojo/samples/sysd-index-sample.md +1 -1
  235. package/docs/ja/specdojo/samples/tsd-index-sample.md +22 -16
  236. package/docs/ja/specdojo/samples/tsd-sample.md +241 -21
  237. package/docs/ja/specdojo/samples/tsp-index-sample.md +1 -1
  238. package/docs/ja/specdojo/samples/uis-sample.md +1 -1
  239. package/docs/ja/specdojo/samples/utc-index-sample.md +1 -1
  240. package/docs/ja/specdojo/samples/utc-sample.md +1 -1
  241. package/docs/ja/specdojo/standards/document-metadata-standard.md +28 -3
  242. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +2 -0
  243. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +16 -11
  244. package/docs/ja/specdojo/standards/sample-authoring-standard.md +1 -0
  245. package/docs/ja/specdojo/templates/ifx-cmd-template.yaml +1 -1
  246. package/docs/ja/specdojo/templates/pjr-dependent-items-template.md +22 -0
  247. package/docs/ja/specdojo/templates/pjr-epic-items-template.md +22 -0
  248. package/docs/ja/specdojo/templates/pjr-epic-template.md +44 -0
  249. package/docs/ja/specdojo/templates/pjr-index-template.md +4 -2
  250. package/docs/specdojo/schemas/v1/bdd.schema.yaml +1 -1
  251. package/docs/specdojo/schemas/v1/deliverable-frontmatter.schema.yaml +24 -16
  252. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -1
  253. package/docs/specdojo/schemas/v1/exec-plan-frontmatter.schema.yaml +1 -1
  254. package/docs/specdojo/schemas/v1/gl.schema.yaml +8 -0
  255. package/docs/specdojo/schemas/v1/ifx-cmd.schema.yaml +5 -1
  256. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +2 -1
  257. package/docs/specdojo/schemas/v1/register-events.schema.yaml +18 -0
  258. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +40 -3
  259. package/docs/specdojo/schemas/v1/rulebook-frontmatter.schema.yaml +5 -0
  260. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +5 -0
  261. package/package.json +2 -2
  262. package/templates/antigravity/orchestrator.md +14 -9
  263. package/templates/claude/agents/specdojo-orchestrator.md +14 -9
  264. package/templates/codex/agents/specdojo-orchestrator.toml +14 -9
  265. package/templates/codex/orchestrator.md +14 -9
  266. package/templates/copilot/README.md +2 -1
  267. package/templates/opencode/agents/specdojo-orchestrator.md +14 -9
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:nfr-operations-sample
4
- type: project
4
+ type: requirement
5
5
  status: draft
6
6
  rulebook: specdojo:nfr-operations-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:nfr-performance-sample
4
- type: project
4
+ type: requirement
5
5
  status: draft
6
6
  rulebook: specdojo:nfr-performance-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:nfr-reliability-sample
4
- type: project
4
+ type: requirement
5
5
  status: draft
6
6
  rulebook: specdojo:nfr-reliability-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:nfr-security-safety-sample
4
- type: project
4
+ type: requirement
5
5
  status: draft
6
6
  rulebook: specdojo:nfr-security-safety-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:nfr-usability-sample
4
- type: project
4
+ type: requirement
5
5
  status: draft
6
6
  rulebook: specdojo:nfr-usability-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:ntp-sample
4
- type: project
4
+ type: test
5
5
  status: draft
6
6
  rulebook: specdojo:ntp-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:opd-sample
4
- type: project
4
+ type: operations
5
5
  status: draft
6
6
  rulebook: specdojo:opd-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:opr-sample
4
- type: project
4
+ type: operations
5
5
  status: draft
6
6
  rulebook: specdojo:opr-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:otp-index-sample
4
- type: project
4
+ type: operations
5
5
  status: draft
6
6
  rulebook: specdojo:otp-index-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:otp-sample
4
- type: project
4
+ type: operations
5
5
  status: draft
6
6
  rulebook: specdojo:otp-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:prj-stakeholder-register-sample
4
- type: sample
4
+ type: project
5
5
  status: ready
6
6
  rulebook: specdojo:prj-stakeholder-register-rulebook
7
7
  based_on:
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:sac-sample
4
- type: project
4
+ type: requirement
5
5
  status: draft
6
6
  rulebook: specdojo:sac-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:sf-index-sample
4
- type: project
4
+ type: requirement
5
5
  status: draft
6
6
  rulebook: specdojo:sf-index-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:sf-sample
4
- type: project
4
+ type: requirement
5
5
  status: draft
6
6
  rulebook: specdojo:sf-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:sld-sample
4
- type: project
4
+ type: data
5
5
  status: draft
6
6
  rulebook: specdojo:sld-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:stc-index-sample
4
- type: project
4
+ type: test
5
5
  status: draft
6
6
  rulebook: specdojo:stc-index-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:stc-sample
4
- type: project
4
+ type: test
5
5
  status: draft
6
6
  rulebook: specdojo:stc-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:stsd-sample
4
- type: sample
4
+ type: data
5
5
  status: draft
6
6
  rulebook: specdojo:stsd-rulebook
7
7
  based_on:
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:sysd-critical-flows-sample
4
- type: project
4
+ type: architecture
5
5
  status: draft
6
6
  rulebook: specdojo:sysd-critical-flows-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:sysd-cross-cutting-policy-sample
4
- type: project
4
+ type: architecture
5
5
  status: draft
6
6
  rulebook: specdojo:sysd-cross-cutting-policy-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:sysd-index-sample
4
- type: project
4
+ type: architecture
5
5
  status: draft
6
6
  rulebook: specdojo:sysd-index-rulebook
7
7
  ---
@@ -6,24 +6,30 @@ specdojo:
6
6
  rulebook: specdojo:tsd-index-rulebook
7
7
  ---
8
8
 
9
- # [技術スタック定義(TSD Index)](../rulebooks/tsd-index-rulebook.md) サンプル
9
+ # 技術スタック一覧(TSD Index)サンプル
10
+
11
+ 本書は、駄菓子屋きぬや販売管理システムの構築・運用で採用する技術スタックと担当責務を一覧化した技術スタック一覧(TSD Index)のサンプルである。店頭タブレット端末およびサーバー実行基盤に必要な技術と、開発・検証・文書化・運用を支えるツールの対象範囲・版・正本を俯瞰し、詳細な設計・設定手順への導線を提供する。
10
12
 
11
13
  ## 1. 技術スタック一覧
12
14
 
13
- | 区分 | 採用技術 | 担当責務 |
14
- | ------------------ | --------------- | -------------------------------------------- |
15
- | 言語 | TypeScript 5.x | フロントエンド・バックエンドの共通実装言語 |
16
- | ランタイム | Node.js 22.x | サーバーサイドの実行環境 |
17
- | Web フレームワーク | Next.js 14.x | 販売・在庫・顧客管理画面の提供とサーバー処理 |
18
- | DB | PostgreSQL 16.x | 販売履歴・在庫・顧客データの永続化 |
19
- | ORM | Prisma 5.x | スキーマ定義・マイグレーション・型安全クエリ |
20
- | コードフォーマット | Prettier 3.x | TypeScript ファイルの書式統一 |
21
- | テスト | Vitest 2.x | ユニットテスト・統合テストの実行環境 |
22
- | ソースコード管理 | GitHub | リポジトリ管理・レビュー・ブランチ戦略 |
23
- | CI/CD | GitHub Actions | テスト自動実行・本番デプロイの自動化 |
24
- | ホスティング | Fly.io | 販売管理サービスのコンテナ実行・ルーティング |
15
+ | 区分 | 採用技術 | 担当責務 | 版・正本 | 適用範囲 |
16
+ | ------------------ | -------------- | --------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------ |
17
+ | 言語 | TypeScript | フロントエンド・バックエンドの共通実装 | 5.x / `package.json`(固定版は `package-lock.json`) | 全環境(必須) |
18
+ | ランタイム | Node.js | サーバーサイド処理および開発ツールの実行環境 | 22.x / `.node-version`、`Dockerfile` | 全環境(必須) |
19
+ | Web フレームワーク | Next.js | 店頭タブレット向けの販売・在庫・つけ管理 UI と API ルートの提供 | 14.x / `package.json`(固定版は `package-lock.json`) | 全環境(必須) |
20
+ | DB | PostgreSQL | 販売履歴、在庫データ、常連客のつけ残高の永続化 | 16.x / `Dockerfile`(詳細設定は [[specdojo:tsd-sample\|詳細定義]]) | 本番・開発(必須) |
21
+ | ORM | Prisma | スキーマ定義、マイグレーション管理、型安全なクエリ実行 | 5.x / `package.json`(固定版は `package-lock.json`) | 本番・開発(必須) |
22
+ | ホスティング | Fly.io | Web アプリケーションおよび DB コンテナの実行ホスティング環境 | - / `fly.toml` | 本番環境(必須) |
23
+ | ソースコード管理 | GitHub | リポジトリ管理、変更履歴の追跡、プルリクエストによるレビュー | - / `https://github.com`(SaaS) | 開発環境(必須) |
24
+ | CI/CD | GitHub Actions | 静的検査・テストの自動実行および本番環境への自動デプロイ | - / `.github/workflows/` | 開発・運用(必須) |
25
+ | テスト | Vitest | 売上計算・つけ残高更新ロジックの単体・統合テスト実行 | 2.x / `package.json`(固定版は `package-lock.json`) | 開発環境(必須) |
26
+ | コードフォーマット | Prettier | TypeScript・Markdown ファイルの書式・コードスタイルの自動統一 | 3.x / `package.json`(固定版は `package-lock.json`) | 開発環境(必須) |
27
+ | 静的解析 | ESLint | TypeScript / JavaScript コードの構文検査と品質規約チェック | 9.x / `package.json`(固定版は `package-lock.json`) | 開発環境(任意) |
28
+ | ドキュメント図解 | Mermaid | 業務フロー図・状態遷移図・構成図のテキスト定義とレンダリング | 11.x / `package.json`(固定版は `package-lock.json`) | 文書化(任意) |
29
+ | エラー監視 | Sentry | 店頭端末および本番環境での例外検知とエラーログ収集 | 8.x / `package.json`(固定版は `package-lock.json`) | 本番環境(任意) |
25
30
 
26
- ## 2. 補足
31
+ ## 2. 補足・詳細への導線
27
32
 
28
- - DB の詳細設定・バージョン固定手順は `tsd-database.md` を参照。
29
- - ホスティング構成・デプロイ手順は `tsd-hosting.md` を参照。
33
+ - データベース(PostgreSQL)の詳細設定・接続認証・Prisma 連携・バックアップ手順は、[[specdojo:tsd-sample|データベース詳細定義(TSD)サンプル]] を参照。本サンプルの詳細 TSD の題材として位置づける。
34
+ - ホスティング環境(Fly.io)の構成・デプロイ手順は、`tsd-hosting.md` を参照(未作成のため仮置き)。
35
+ - CI/CD パイプライン(GitHub Actions)のワークフロー構成・シークレット管理は、`tsd-ci.md` を参照(未作成のため仮置き)。
@@ -1,38 +1,258 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:tsd-sample
4
- type: project
4
+ type: architecture
5
5
  status: draft
6
6
  rulebook: specdojo:tsd-rulebook
7
+ part_of:
8
+ - specdojo:tsd-index-sample
7
9
  ---
8
10
 
9
- # [技術スタック一覧](../rulebooks/tsd-rulebook.md) サンプル
11
+ # データベース(PostgreSQL / Prisma)技術スタック詳細定義(TSD)サンプル
10
12
 
11
- ## 1. 目的と適用範囲
13
+ 本書は、駄菓子屋きぬや販売管理システムにおいて、販売履歴、在庫データ、および常連客のつけ残高を安全かつ確実に永続化するためのデータベース基盤(PostgreSQL 16.x)および ORM(Prisma 5.x)の構成・設定・運用手順を定義した技術スタック詳細定義(TSD)のサンプルである。
12
14
 
13
- 本書は、システムで採用する技術(言語、フレームワーク、DB、メッセージ基盤、キャッシュ等)を、一覧として定義するための最小サンプルである。
15
+ ## 1. 概要と位置づけ
14
16
 
15
- ## 2. 入力情報
17
+ ### 1.1. 目的とビジネス価値
16
18
 
17
- - 対象: 駄菓子屋の販売管理システム
18
- - 前提: プロジェクト文脈は handbook の共通方針に準拠する
19
- - 参照: `../rulebooks/tsd-rulebook.md`
19
+ - **目的**: 駄菓子屋きぬやの業務運営で最重要となる「販売記録」「在庫データ」「常連客のつけ残高」をデータ破損や消失なく確実に永続化し、店頭タブレット端末から安定して読み書きできるデータ実行基盤を確立する。
20
+ - **ビジネス価値・運用上の利点**: 店主代表の記憶や紙の帳簿に依存していた販売・つけ管理をシステム化することで、つけ残高の確認時間を1分以内に短縮し、記録漏れによる金銭トラブルや人気商品の欠品・過剰在庫を防止する。
21
+ - **ユーザー価値**: 来店した地域の子どもたちや常連客に対し、正確な会計とつけ残高の確認を待たせることなく提供できる。
20
22
 
21
- ## 3. 記述内容
23
+ ### 1.2. 対象範囲と責務境界
22
24
 
23
- - 主な内容: プログラミング言語、フレームワーク、ミドルウェア など
24
- - 必須観点: 対象、条件、判定基準、責任者
25
+ | 区分 | 対象範囲・責務 | 主な内容 |
26
+ | -------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
27
+ | スコープ内(対象) | データベース実行基盤と接続設定 | PostgreSQL 16.x のコンテナ構成、Prisma 5.x 連携設定、接続プール、永続ボリューム、バックアップ |
28
+ | スコープ内(対象) | 開発・本番の環境整合 | ローカル Docker 環境と本番コンテナ環境のパラメータ統一、マイグレーション適用手順 |
29
+ | スコープ外(対象外) | アプリケーション詳細設計 | 個別機能のビジネスロジック、詳細 API 仕様、SQL 全文([[specdojo:tsd-rulebook\|TSD ルールブック]] 禁止事項準拠) |
30
+ | スコープ外(対象外) | クライアント端末の管理 | 店頭タブレット端末の OS 設定、Wi-Fi 機器の物理配線およびネットワークハードウェア管理 |
25
31
 
26
- ## 4. 最小記述例
32
+ ### 1.3. 他文書との関係
27
33
 
28
- | 項目 | 値 | 備考 |
29
- | ------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------ |
30
- | ドキュメント | [技術スタック一覧](../rulebooks/tsd-rulebook.md) | 最小サンプル |
31
- | 目的 | システムで採用する技術(言語、フレームワーク、DB、メッセージ基盤、キャッシュ等)を、一覧として定義する | specdojo:deliverables-reference 準拠 |
32
- | 主な内容 | プログラミング言語、フレームワーク、ミドルウェア など | 要点のみ記載 |
34
+ - [[specdojo:tsd-index-sample|技術スタック一覧(TSD Index)サンプル]]: 駄菓子屋きぬや販売管理システム全体の採用技術一覧および各技術領域への導線(本書の上位一覧)。
35
+ - `tsd-hosting.md`: Fly.io 上のアプリケーション実行環境およびネットワーク基盤の構成定義(未作成のため仮置き)。
36
+ - `tsd-ci.md`: GitHub Actions による自動テストおよび本番デプロイワークフローの定義(未作成のため仮置き)。
33
37
 
34
- ## 5. 未解決事項
38
+ ### 1.4. 役割と責任
35
39
 
36
- | 論点 | 処理方針 |
37
- | -------------- | ------------------------ |
38
- | 要件詳細の補強 | 実案件適用時に具体化する |
40
+ - **所有権・アーキテクチャ責任(ARC)**: データベース構成、接続方式、技術制約、および全体アーキテクチャとの整合性担保。
41
+ - **業務要件確認(PO / 店主代表)**: 保存対象データ項目の充足性、運用停止許容時間、および業務継続性の承認。
42
+ - **実装・マイグレーション(DEV / 開発担当)**: Prisma スキーマ設計、マイグレーションスクリプト作成、および接続検証の実施。
43
+ - **運用・バックアップ管理(OPS / 運用アドバイザー)**: 定期バックアップ運用の設計、障害監視、およびリカバリ手順の確立。
44
+ - **技術助言(技術メンター)**: 構成設計のレビュー、接続プーリングおよびリソースチューニングへの助言。
45
+
46
+ ## 2. 対象環境と前提条件
47
+
48
+ ### 2.1. 実行環境と責務分界
49
+
50
+ | 実行場所 | 役割 | 実行ホスト / 基盤 | 主な実行プロセス |
51
+ | ---------- | -------------------------- | ------------------------------ | -------------------------------------------------- |
52
+ | 開発環境 | ローカル開発・検証 | 開発端末(macOS / Linux) | Docker Compose(PostgreSQL 16.x)、Node.js 22.x |
53
+ | 本番環境 | 永続データ保管・クエリ処理 | Fly.io(東京リージョン `nrt`) | Fly Postgres コンテナ、永続ボリューム(NVMe 10GB) |
54
+ | 接続元環境 | アプリケーションサーバー | Fly.io(東京リージョン `nrt`) | Next.js サーバープロセス、Prisma Client 5.x |
55
+
56
+ ### 2.2. 前提条件と必要リソース
57
+
58
+ - **ランタイム前提**: Node.js 22.x(サーバーサイド実行環境および開発環境)。
59
+ - **コンテナ前提**: Docker 26.x 以上、Docker Compose v2.x(ローカル環境用)。
60
+ - **CPU / メモリリソース**:
61
+ - 開発環境: 最小 512MB RAM、1 vCPU。
62
+ - 本番環境: 最小 1GB RAM、1 Shared CPU(店頭タブレット1台からの同時アクセスに対して十分な余裕を確保)。
63
+ - **ストレージ**: 10GB 永続ボリューム(年間データ増加量予測約 100MB に対して10年分以上の容量を確保)。
64
+ - **ネットワーク権限**: ポート 5432(PostgreSQL)への内部通信許可。外部インターネットへの直接ポート開放は禁止し、内部ネットワークまたは暗号化通信経由でのみアクセスを許可。
65
+
66
+ ## 3. 全体構成と接続経路
67
+
68
+ 店頭タブレット端末からデータベースに至る接続経路と責務境界を以下に示す。
69
+
70
+ ```mermaid
71
+ graph LR
72
+ subgraph Client["店頭端末(クライアント)"]
73
+ Tablet["店頭タブレット<br/>Next.js UI"]
74
+ end
75
+
76
+ subgraph Server["Fly.io アプリケーション環境"]
77
+ App["Next.js Server / API<br/>(Node.js 22.x)"]
78
+ PrismaClient["Prisma Client 5.x<br/>(Connection Pool)"]
79
+ end
80
+
81
+ subgraph Database["Fly.io データベース環境"]
82
+ PG["PostgreSQL 16.x<br/>(Port 5432)"]
83
+ Volume[("永続 Volume<br/>(10GB NVMe)")]
84
+ end
85
+
86
+ Tablet -->|HTTPS / 443| App
87
+ App --> PrismaClient
88
+ PrismaClient -->|"TCP / SSL (Port 5432)"| PG
89
+ PG --- Volume
90
+ ```
91
+
92
+ - 店頭タブレットは Web ブラウザを通じて Next.js サーバーに HTTPS(ポート 443)で接続し、データベースへ直接アクセスしない。
93
+ - Next.js サーバー内の Prisma Client がコネクションプールを介して PostgreSQL(ポート 5432)へ接続する。
94
+ - 本番環境では Fly.io のプライベート 6PN(WireGuard)メッシュネットワークを利用し、暗号化された安全な内部経路で通信を行う。
95
+
96
+ ## 4. 採用技術と設定値
97
+
98
+ ### 4.1. 採用設定一覧
99
+
100
+ PostgreSQL および Prisma の採用設定を以下に定義する。
101
+
102
+ | 対象・用途 | 設定項目 | 採用値・版 | 適用範囲 | 理由・制約 | 反映・確認方法 |
103
+ | ------------------ | ------------------------------------- | ---------------- | ---------------- | --------------------------------------------------------------------- | --------------------------------------- |
104
+ | DB エンジン | バージョン | PostgreSQL 16.x | 全環境 | 長期サポート版であり、JSON 処理性能と耐障害性に優れるため | `SELECT version();` で確認 |
105
+ | 接続ライブラリ | バージョン | Prisma 5.x | 全環境 | 型安全なクエリ生成と TypeScript 5.x との親和性のため | `package.json` および `npx prisma -v` |
106
+ | 文字コード | `client_encoding` / `server_encoding` | `UTF8` | 全環境 | 商品名や常連客名の日本語文字化けを防止するため | `SHOW server_encoding;` |
107
+ | タイムゾーン | `timezone` | `Asia/Tokyo` | 全環境 | 店舗の営業時間および日次売上集計を日本標準時で統一するため | `SHOW timezone;` |
108
+ | 接続数制限 | `max_connections` | `50` | 本番環境 | メモリ枯渇を防ぎつつ、Web サーバーからの同時接続を許容するため | `SHOW max_connections;` |
109
+ | コネクションプール | `connection_limit` | `10` | アプリケーション | 店舗端末1台運用のアクセス規模に適合させ、余剰接続を抑制するため | `DATABASE_URL` のクエリパラメータで設定 |
110
+ | 共有バッファ | `shared_buffers` | `256MB` | 本番環境 | 割り当てメモリ 1GB のうち 25% をデータキャッシュに充当するため | `SHOW shared_buffers;` |
111
+ | スロークエリ監視 | `log_min_duration_statement` | `1000`(ミリ秒) | 本番環境 | 1秒以上を要するクエリを検知し、店頭端末の画面フリーズを未然に防ぐため | サーバーログ出力を確認 |
112
+
113
+ ### 4.2. 採用値・推奨値・未決事項の区別
114
+
115
+ - **採用値(固定)**: PostgreSQL 16.x、Prisma 5.x、文字コード `UTF8`、タイムゾーン `Asia/Tokyo`。店舗の基本仕様として確定。
116
+ - **推奨値(調整可能)**: `connection_limit=10`、`shared_buffers=256MB`。小規模店舗での運用実績を踏まえて推奨するが、アクセス傾向に応じて見直し可能。
117
+ - **未決事項(検討中)**: _UNDECIDED_: 年末年始や繁忙期における一時的なメモリ拡張ポリシー(日次売上件数の実測推移をもとに運用フェーズで判断)。
118
+
119
+ ### 4.3. 接続情報と機密情報の管理
120
+
121
+ - 秘密情報(パスワード・接続トークン等)はリポジトリのソースコードや設定ファイルに直接記載しない。
122
+ - 接続文字列の書式(プレースホルダー):
123
+ - 開発環境: `postgresql://<DEV_USER>:<DEV_PASSWORD>@localhost:5432/<DEV_DB>?schema=public`
124
+ - 本番環境: `postgresql://<PROD_USER>:<PROD_PASSWORD>@<PROD_HOST>:5432/<PROD_DB>?sslmode=require&connection_limit=10`
125
+ - 機密情報の管理方法:
126
+ - ローカル開発環境: `.env` ファイルに記述し、`.gitignore` で Git 管理から除外。テンプレートは `.env.example` で共有する。
127
+ - 本番環境: Fly.io のシークレット管理(`fly secrets set DATABASE_URL=...`)に暗号化保存し、環境変数としてコンテナに注入する。
128
+
129
+ ## 5. 導入と初期設定
130
+
131
+ ### 5.1. 開発環境の初期構築手順
132
+
133
+ ローカル開発環境でのコンテナ起動からマイグレーション適用までの手順を示す。
134
+
135
+ 1. **DB コンテナの起動**:
136
+
137
+ 作業ディレクトリ直下の Docker Compose を使用してコンテナを起動する。
138
+
139
+ ```bash
140
+ # PostgreSQL コンテナの起動
141
+ docker compose up -d postgres
142
+ ```
143
+
144
+ 2. **環境変数ファイルの準備**:
145
+
146
+ テンプレートから `.env` を作成し、接続パラメータを設定する。
147
+
148
+ ```bash
149
+ cp .env.example .env
150
+ # .env 内の DATABASE_URL をローカル接続情報に合わせて編集
151
+ ```
152
+
153
+ 3. **Prisma スキーマのマイグレーション適用**:
154
+
155
+ 定義済みスキーマからマイグレーションを実行し、テーブル群を生成する。
156
+
157
+ ```bash
158
+ npx prisma migrate dev --name init
159
+ ```
160
+
161
+ 4. **初期シードデータの投入**:
162
+
163
+ 駄菓子商品マスターおよび初期店舗設定データを投入する。
164
+
165
+ ```bash
166
+ npx prisma db seed
167
+ ```
168
+
169
+ ### 5.2. スキーマ変更とマイグレーションの運用
170
+
171
+ - スキーマ変更時は必ずマイグレーションファイルを作成し、バージョン管理に含める。
172
+ - **変更影響と互換性方針**:
173
+ - 本番稼働中の列の削除や型変更は即時実行せず、互換フェーズ(新列追加 → アプリケーション移行 → 旧列削除)の 2 段階で適用する。
174
+ - 本番デプロイ時は CI/CD パイプライン内で `npx prisma migrate deploy` を自動実行し、マイグレーション適用の成否を確認した後にアプリケーションコンテナを切り替える。
175
+
176
+ ## 6. 動作確認と切り分け
177
+
178
+ PostgreSQL および Prisma の正常性を確認するための手順と判定基準を以下に定義する。
179
+
180
+ ### 6.1. 動作確認一覧表
181
+
182
+ | 確認対象 | 実行場所・方法 | 期待結果 | 失敗時の確認先 |
183
+ | --------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
184
+ | コンテナ起動状態 | 開発端末: `docker compose ps postgres`<br/>本番環境: `fly status --app kinuyo-db` | 状態が `Up` または `running` であり、予期せぬ再起動が発生していないこと | Docker デーモンの稼働状態、Fly.io プラットフォームステータス、コンテナ割り当てメモリ量 |
185
+ | ネットワーク疎通 | 開発端末 / サーバー: `nc -zv <HOST> 5432` | ポート 5432 への接続が `open` または `succeeded` と表示されること | ファイアウォール設定、Fly.io 内部プライベートネットワーク設定、セキュリティグループ |
186
+ | DB 認証・接続 | 開発端末 / サーバー: `psql -h <HOST> -U <USER> -d <DB> -c "SELECT 1;"` | 実行結果として `1` が返却されること | `DATABASE_URL` のユーザー名・パスワード、PostgreSQL の `pg_hba.conf` 認証設定 |
187
+ | Prisma マイグレーション状態 | アプリケーション環境: `npx prisma migrate status` | `Database schema is up to date` と表示され、未適用のマイグレーションがないこと | `prisma/migrations` ディレクトリの内容、DB 内の `_prisma_migrations` テーブル |
188
+ | CRUD 動作検証 | アプリケーション環境: 単体テスト実行 `npm run test:unit -- tests/db/connection.test.ts` | テスト用レコード(商品・つけ残高)の作成・取得・更新・削除がすべて PASS すること | Prisma Client 生成状態(`npx prisma generate`)、トランザクションタイムアウト設定 |
189
+
190
+ ## 7. 継続利用と運用・バックアップ
191
+
192
+ ### 7.1. データの永続化と再起動時の挙動
193
+
194
+ - Fly.io の永続ボリューム(10GB)を `/var/lib/postgresql/data` にマウントして使用する。
195
+ - コンテナの再デプロイ、再起動、またはホストマシンのメンテナンス時にもデータは失われず保持される。
196
+ - 一時的なメモリ領域(セッション情報、クエリキャッシュ)は再起動時に初期化されるが、販売記録・つけ残高の正本データには影響を与えない。
197
+
198
+ ### 7.2. 定期バックアップ手順
199
+
200
+ 日次でのデータ保護を行うため、以下のバックアップ運用を実施する。
201
+
202
+ 1. **日次論理バックアップ**:
203
+
204
+ 深夜の店舗休業時間帯(午前 3:00)に自動スクリプトで `pg_dump` を実行する。
205
+
206
+ ```bash
207
+ # バックアップ実行コマンド例
208
+ pg_dump -h <HOST> -U <USER> -d <DB> -F c -b -v -f "/backups/kinuyo-db-$(date +%Y%m%d).dump"
209
+ ```
210
+
211
+ 2. **バックアップ保管ポリシー**:
212
+
213
+ 生成されたダンプファイルは暗号化のうえ、外部クラウドストレージへ自動転送する。日次データは過去30日分、月末データは過去1年分を保持する。
214
+
215
+ 3. **リカバリ手順**:
216
+
217
+ データ破損や誤操作発生時は、以下の手順で特定時点のバックアップからリストアする。
218
+
219
+ ```bash
220
+ # リストア実行コマンド例
221
+ pg_restore -h <HOST> -U <USER> -d <DB> -v --clean --if-exists "/backups/kinuyo-db-<TARGET_DATE>.dump"
222
+ ```
223
+
224
+ ## 8. 制約事項とトラブルシュート
225
+
226
+ ### 8.1. 既知の制約事項
227
+
228
+ - **オフライン時の制限**: 店頭タブレットがネットワーク不通となった場合、PostgreSQL への直接書き込みは行えない。端末側ブラウザの一時退避領域(IndexedDB)に販売記録を保持し、再接続時に順次同期する構成を前提とする。
229
+ - **同時接続数上限**: 本構成の同時接続数は最大 50(実効推奨 10)に制限されている。店頭端末以外の外部ツールや分析スクリプトを大量並行実行してはならない。
230
+
231
+ ### 8.2. トラブルシューティングガイド
232
+
233
+ 障害発生時の主な症状、原因、および切り分け・回避手順を以下に示す。
234
+
235
+ | 症状 | 主な原因 | 切り分け手順 | 回避・復旧方法 |
236
+ | ------------------------------------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
237
+ | 接続タイムアウト<br/>(`P1001: Can't reach database server`) | DB コンテナの停止、または内部ネットワークの疎通不全 | 1. `fly status` で DB コンテナの稼働を確認<br/>2. `nc -zv` でポート 5432 の疎通を確認 | コンテナが停止している場合は `fly apps restart kinuyo-db` で再起動する。ネットワーク不通時は Fly.io ステータスを確認する |
238
+ | マイグレーションロックエラー<br/>(`Migration is locked`) | 前回のマイグレーション失敗によるロックの残留 | `_prisma_migrations` テーブルの `applied_steps_count` と `finished_at` を確認 | `npx prisma migrate resolve` を実行してロックを解除し、不整合のあるステップを手動で調整する |
239
+ | コネクション枯渇<br/>(`remaining connection slots are reserved`) | ゾンビ接続の残留、または接続リーク | `SELECT count(*), state FROM pg_stat_activity GROUP BY state;` を実行 | アイドル状態の不要な接続を `SELECT pg_terminate_backend(pid);` で切断し、Prisma Client の接続解放漏れを修正する |
240
+ | メモリ不足停止<br/>(`Out of Memory: Killed process`) | 大量データの一括取得、またはメモリリーク | `fly logs` で `OOM killed` メッセージの有無を確認 | 取得クエリにページネーション(`take` / `skip`)を適用し、必要に応じて Fly.io のコンテナメモリを 2GB へスケールアップする |
241
+
242
+ ## 9. 未解決事項と解決経路
243
+
244
+ 本定義を `ready` ステータスへ昇格させるために解決すべき課題および運用上の未決事項を以下に示す。
245
+
246
+ ### 9.1. 未解決事項一覧表
247
+
248
+ | 課題 ID | 論点 | 影響 | 意思決定基準・判断期日 | 解決経路・アクション | 担当 Role |
249
+ | ---------- | ---------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------- |
250
+ | `ISSUE-01` | 店頭オフライン時のつけ・販売データ同期プロトコルの策定 | ネットワーク不通時に店頭で記録したつけ残高の更新順序と競合解決 | 同期失敗率 0.1% 未満をテスト環境で実証(期日: 結合テスト着手前) | DEV が端末側 IndexedDB 一時退避と復旧時の一括トランザクション送信プロトタイプを作成し、ARC がレビュー | DEV / ARC |
251
+ | `ISSUE-02` | 本番自動バックアップ保管先の外部クラウドストレージ選定 | 障害時の復旧即時性と長期保管の月額運用コスト | 月額費用 500 円以内で暗号化・ライフサイクル設定が可能であること(期日: 本番運用開始2週間前) | OPS が Cloudflare R2 および AWS S3 を比較検証し、PO(店主代表)の費用承認を得る | OPS / PO |
252
+ | `ISSUE-03` | 繁忙期(駄菓子屋祭りイベント等)における一時的スケールアップ基準 | 集中アクセス時の店頭画面レスポンス遅延の防止 | 店頭端末の会計完了待機時間が 3 秒を超える確率を 0% に抑制(期日: 総合リハーサル前) | 疑似負荷テストを実施し、CPU 使用率 80% 超過時のメモリ増設手順(1GB → 2GB)を OPS が手順化 | OPS / DEV |
253
+
254
+ ### 9.2. ready ステータス達成基準
255
+
256
+ - `ISSUE-01` から `ISSUE-03` について、合意された解決経路に沿って検証が完了し、担当 Role による合意が得られていること。
257
+ - 「6. 動作確認と切り分け」に定義されたすべての検証項目がステージング環境で PASS し、エラーなく再現可能であることが確認されていること。
258
+ - ARC によるアーキテクチャレビューおよび PO による運用方針の最終承認が完了していること。
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:tsp-index-sample
4
- type: project
4
+ type: test
5
5
  status: draft
6
6
  rulebook: specdojo:tsp-index-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:uis-sample
4
- type: project
4
+ type: ui
5
5
  status: draft
6
6
  rulebook: specdojo:uis-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:utc-index-sample
4
- type: project
4
+ type: test
5
5
  status: draft
6
6
  rulebook: specdojo:utc-index-rulebook
7
7
  ---
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  specdojo:
3
3
  id: specdojo:utc-sample
4
- type: project
4
+ type: test
5
5
  status: draft
6
6
  rulebook: specdojo:utc-rulebook
7
7
  ---