create-specment 0.2.8 → 0.2.9

package/templates/docs/04-internal/policies/pull-request-operation-flow.mdx

@@ -0,0 +1,118 @@
+---
+sidebar_position: 2
+tags:
+  - git
+  - pull request
+---
+# Pull Request運用フロー
+
+## 主な運用フロー
+
+```pumld
+@startuml
+
+skinparam responseMessageBelowArrow true
+autonumber "<b> [00]"
+
+participant local as "branch: feature/ブランチ名"
+participant develop as "branch: develop"
+participant staging as "branch: staging"
+participant main as "branch: main"
+
+develop -> local ** : clone &\ncreate branch feature/ブランチ名
+local -> local: commit changes
+local -> local: create Pull Request & review
+local -> develop: merge feature/ブランチ名 into develop
+local -> local !! : delete feature branch
+
+develop -> develop: CI/CD checks
+develop -> staging: merge develop into staging
+staging -> staging: perform release validation
+staging -> staging: e2e test
+staging -> main: merge staging into main
+
+main -> main: tag version &\nperform release
+@enduml
+```
+
+### 手順
+
+1. \[01\]: developブランチをクローンし、ローカルでfeature/ブランチ名を作成する
+1. \[02\]: feature/ブランチ名でコードを修正しコミットする
+1. \[03\]: feature/ブランチ名内でPull Requestを作成し、レビューを依頼する
+1. \[04\]: レビュー完了後、feature/ブランチ名をdevelopへマージする
+1. \[05\]: feature/ブランチ名を削除する(自動)
+1. \[06\]: developブランチでCI/CDチェックを実行する
+1. \[07\]: developをstagingへマージ
+1. \[08\]: リリース前の検証をする
+1. \[09\]: stagingブランチでE2Eテストを実行する
+1. \[10\]: テスト完了後、stagingをmainへマージし、リリースを実施する
+1. \[11\]: mainブランチでタグを作成し、正式にリリースする
+
+## エンジニアの動き
+
+```pumld
+@startuml
+start
+
+:Issueからfeatureブランチを作成する;
+:コード、テストを実装する;
+#Aquamarine:(A)
+:テストをする;
+
+if (テストは成功したか?) then (はい)
+  :Pull Requestを作成する;
+  :レビュアーを指定する;
+  #LightSkyBlue:(B)
+  :レビューを受ける;
+  
+  if (レビューは承認されたか?) then (はい)
+    :レビュアーがPull Requestをマージする;
+    :Issueをクローズする;
+    stop
+  else (いいえ)
+    :フィードバックに基づいて修正する;
+    :修正をコミットする;
+    #Aquamarine:(A)
+    :再レビューを依頼する;
+    #LightSkyBlue:(B)
+    detach
+  endif
+  
+else (いいえ)
+  :テストが通るように修正する;
+  #Aquamarine:(A)
+  detach
+
+endif
+
+@enduml
+```
+
+## Pull Requestのベストプラクティス
+
+1. **小さくまとめる**: 一つのPRは一つの機能や修正に焦点を当てる
+1. **明確なタイトルと説明**: PRの目的と変更内容を明確に記述する
+1. **テストの実施**: PRを提出する前に必ずテストを実行する
+1. **レビュープロセスの尊重**: レビューコメントに対して建設的に対応する
+1. **マージ前の確認**: マージ前にコンフリクトがないことを確認する
+
+## PRレビューのチェックリスト
+
+### 機能面
+
+1. 要件を満たしているか
+1. エッジケースを考慮しているか
+1. バグやパフォーマンスの問題がないか
+
+### コード品質
+
+1. コードは読みやすく、理解しやすいか
+1. 命名規則に従っているか
+1. コードの重複がないか
+1. セキュリティ上の問題がないか
+
+### ドキュメント
+
+1. コメントやドキュメントが適切か
+1. 必要な場合はドキュメントが更新されているか

package/templates/docs/04-internal/rules/_category_.yaml

@@ -0,0 +1,2 @@
+label: '規約・ルール'
+position: 2

package/templates/docs/04-internal/rules/database.mdx

@@ -0,0 +1,139 @@
+---
+sidebar_position: 5
+tags:
+  - Database
+---
+import { TBD } from '@site/src/components/TBD';
+
+# データベース
+
+:::tip
+1. 編集中
+1. どんなプロジェクトでも使えるレベルなものにしていきたい
+:::
+
+## オブジェクトの命名規約 {#object-naming}
+### 全般 {#general}
+#### プライマリーキー、外部キー
+1. 各テーブルのプライマリーキーは `id` とし、serial型とする
+1. リレーションする際はこの `id` を使う
+1. プライマリーキーに意味を持たせない
+1. 外部キーとのリレーションはテーブル名 + `_id` とする
+    1. 例
+        1. 親: `class`
+
+            | 論理名   | 物理名 | 型      | コメント       |
+            | -------- | ------ | ------- | -------------- |
+            | id       | **id** | serial  | auto increment |
+            | クラス名 | name   | varchar | -              |
+
+        1. 子: `student`
+
+            | 論理名   | 物理名       | 型      | コメント       |
+            | -------- | ------------ | ------- | -------------- |
+            | id       | id           | serial  | auto increment |
+            | class_id | **class_id** | integer | 外部キー       |
+            | 姓名     | name         | varchar | -              |
+
+#### 日付 / 日時 {#date}
+1. 命名
+    1. 年月日のみの場合は"xx日"、時刻まで必要な場合は"xx日時"とし、明確に使い分ける
+        1. 日にちを表す項目は `受動態_on` となり、date型
+        1. 日時を表す項目は `受動態_at` となり、timestamp型
+1. timestamp型はすべて `timestamp(6) without time zone` とする
+    1. タイムゾーンを持たせない(標準の `UST`)
+1. 例
+    1. 親: `classes`
+
+        | 論理名   | 物理名     | 型        |
+        | -------- | ---------- | --------- |
+        | 締切日   | closed_on  | date      |
+        | 締切日時 | closed_at  | timestamp |
+        | 削除日   | deleted_on | date      |
+        | 削除日時 | deleted_at | timestamp |
+
+### 大文字を使用しない
+1. 物理名は小文字とアンダーバー("_")のみを使用する
+1. テーブル名、カラム名ともに大文字を使用しない
+    1. データベースによっては大文字と小文字を違う文字とみなす場合、みなさない場合があるので小文字で統一する
+
+| OK/NG | 名前         |
+| ----- | ------------ |
+| :o:   | **document** |
+| :x:   | DOCUMENT     |
+| :x:   | Document     |
+
+#### 単語の連結はスネークケース
+1. テーブル名、カラム名ともにスネークケースを使用する
+1. 大文字を使うキャメルケースやパスカルケースは使用禁止
+
+| OK/NG | 名前            |
+| ----- | --------------- |
+| :o:   | **table\_name** |
+| :x:   | tableName       |
+| :x:   | TableName       |
+| :x:   | tablename       |
+| :x:   | table-name      |
+
+### 英語表記
+1. 基本的に単語はローマ字ではなく、英語で書く
+
+### 略名を使用しない
+1. 短くして意味が分からくなるよりは長くて意味がわかる名前にする
+1. ただし、データベースの種類や環境によって文字数が制限される場合は除く
+1. 以下は例外とする
+    1. "数"に関する項目は `_qty` (Quantityの略)を付ける
+    1. 例: `minus_points_qty`
+
+| OK/NG | 名前            |
+| ----- | --------------- |
+| :o:   | **start\_date** |
+| :o:   | **maker\_code** |
+| :x:   | start_dt        |
+| :x:   | maker_cd        |
+
+### テーブル編
+#### 単数形で書く
+
+| OK/NG | 名前         |
+| ----- | ------------ |
+| :o:   | **document** |
+| :x:   | documents    |
+| :o:   | **category** |
+| :x:   | categories   |
+
+#### n:n用テーブル
+1. 接頭語に`map_`を付ける
+
+| OK/NG | 名前                  |
+| ----- | --------------------- |
+| :o:   | **map_user_category** |
+| :x:   | user_category         |
+
+### カラム編
+1. ステータスを保存する項目は状態を含めて書く
+
+| OK/NG | 名前           |
+| ----- | -------------- |
+| :o:   | **is_working** |
+| :o:   | **is_deleted** |
+| :x:   | delete_flag    |
+
+#### flg、kbnなどの略名を使用しない
+1. 例えば"flag"と付いたboolean型にした場合、trueとfalseが見ただけでどちらがonなのかが分からないため
+
+| OK/NG | 名前           |
+| ----- | -------------- |
+| :o:   | **is_deleted** |
+| :x:   | delete_flg     |
+| :x:   | delete_flag    |
+
+### 制約編
+1. ユニーク制約は「テーブル名\_uq\_nn」とする
+1. `_uq` は固定文字。 `nn`はゼロ埋めの連番
+1. 例: `user_uq_01`
+
+### インデックス編
+1. インデックスは「テーブル名\_idx\_nn」とする
+1. `_idx` は固定文字。 `nn`はゼロ埋めの連番
+1. 例: `user_idx_01`

package/templates/docs/04-internal/rules/document-creation-rules.mdx

@@ -0,0 +1,39 @@
+---
+sidebar_position: 3
+---
+# ドキュメント作成ルール
+
+## ファイル命名規則
+1. ファイル名はケバブケースを利用。日本語禁止
+    1. 例
+        `document-creation-rules.mdx`
+1. テンプレートファイル(ファイル名が`_`で始まるもの)がある場合は、該当ファイルをコピーして使用する
+
+## Frontmatter(header yaml)の書き方
+1. 各MDXファイルの先頭には必ずYAMLフロントマターを記述
+1. 必須フィールド
+1. `slug`：URLパス
+1. `title`：ページ見出し
+1. `sidebar_position`：サイドバー表示順
+1. 記述例
+   ```md
+   ---
+   sidebar_position: 1
+   ---
+   ```
+
+## 執筆スタイル
+1. 1ファイル内の文体は「です／ます調」を統一すること
+1. 専門用語や略語を初出時に日本語で説明する
+
+## `_category_.yaml` の書き方
+1. フォルダーをsidebarで日本語表示するために必要
+1. 各ドキュメントフォルダー直下に配置
+1. 必須フィールド
+1. `label`：カテゴリ名
+1. `position`：サイドバー内の並び順(数値)
+1. 記述例
+   ```yaml
+   label: ドキュメント作成
+   position: 1
+   ```

package/templates/docs/04-internal/rules/index.mdx

@@ -0,0 +1,10 @@
+---
+sidebar_position: 1
+---
+# 規約・ルール
+1. [markdown](markdown.mdx)
+1. [databaase](database.mdx)
+1. TypeScript
+    1. Google TypeScript Style Guide
+        1. https://google.github.io/styleguide/tsguide.html
+

package/templates/docs/04-internal/rules/markdown.mdx

@@ -0,0 +1,148 @@
+---
+sidebar_position: 2
+tags:
+  - Markdown
+---
+# Markdown
+## 基本 {#basic}
+### 章立て {#chapter}
+1. 例
+    ```markdown
+    # 章タイトル
+    ## 章タイトルごとに"#"を増やす。最大で5章まで
+    1. 実用的には3、4階層が妥当
+    1. 深すぎる階層が多くなる場合は抽象度を再検討する
+    ```
+1. 章のひとつ上の行は空行にする
+    1. ただし、更に上の行が章の場合は空行不要
+    1. 例
+        ```markdown
+        # 本タイトル
+        ## サブタイトル1。本タイトルとサブタイトルの間に空行は不要
+        1. 箇条書き例
+
+        ## サブタイトル2。上の行は章ではないため、空行を入れる
+        1. 箇条書き例
+        ```
+
+### 箇条書き {#itemization}
+1. 仕様を会話で伝える際、番号であったほうが伝えやすいので数値になるように `1. ` を使用する
+1. 数値はレンダリング時に連番になるので、2番目以降でもすべて `1. ` とする
+1. 例
+    ```markdown
+    1. 1つ目
+    1. 2つ目でも "1. "
+        1. インデントは半角スペース4つ。タブ文字禁止
+        1. 2つ目でも "1. "
+    ```
+1. 例のレンダリング結果
+    1. 1つ目
+    1. 2つ目でも "1. "
+        1. インデントは半角スペース4つ。タブ文字禁止
+        1. 2つ目でも "1. "
+1. VSCode利用時にインクリメントされてしまう場合は以下の設定にする
+    ```json title="settings.json"
+    "markdown.extension.orderedList.marker": "one",
+    ```
+
+### 強調表示 {#highlighting}
+1. 以下を参考
+    1. 公式Docusaurus - Markdown Features: https://docusaurus.io/docs/markdown-features
+
+:::note
+1. 斜体(italic)も使えるけど、あまり見やすいと思えないので、仕様としては使わないようにしたい
+:::
+
+### その他 {#other}
+1. 使えるemoji。絵文字
+    1. 参考: WebFX - [EMOJI CHEAT SHEET](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md)
+
+## 応用 {#application}
+### 他ドキュメントへのリンク {#link-to-other-documents}
+1. 別のドキュメントファイルへのリンクは相対パスで書く
+
+```markdown
+1. 同じ階層なら > [別のmdx](other.mdx)
+1. 子階層 > [カレントにあるフォルダー内のファイル](subfolder/dummy.mdx)
+1. 別階層 > [親をたどって書く](../rules/markdown.mdx)
+```
+
+### 詳細表示 {#details}
+1. htmlの記述と同じ
+1. 例
+    ```mdx-code-block
+    <details>
+      <summary>ここをクリックして開閉</summary>
+      <div>
+        <div>詳細はここに書く</div>
+        \
+        <details>
+          <summary>ネストして書くこともできる</summary>
+          <div>
+            :grinning::smile::grin::laughing::blush::wink:
+          </div>
+        </details>
+      </div>
+    </details>
+    ```
+1. 例のレンダリング結果
+    <details>
+      <summary>ここをクリックして開閉</summary>
+      <div>
+        <div>詳細はここに書く</div>
+        \
+        <details>
+          <summary>ネストして書くこともできる</summary>
+          <div>
+            :grinning::smile::grin::laughing::blush::wink:
+          </div>
+        </details>
+      </div>
+    </details>
+
+### コードブロック {#code-block}
+1. \`\`\`(バッククォート3つ)で囲うとコードブロックになる
+1. 使えるコードは以下を参照
+    1. prismjs.com - [Supported languages](https://prismjs.com/#supported-languages)
+1. `{`、`}` で囲うとその行がハイライト表示される
+1. `title=` を追加するとタイトル表示できる
+    1. ハイライトとtitleを続けて書く場合は区切りとして半角スペースが必要
+1. 例
+    ```md
+        ```nim {4-6,8} title="sample.nim" showLineNumbers
+        import tables, strutils
+
+        var wordFrequencies = initCountTable[string]()
+        for line in stdin.lines:
+        for word in line.split(", "):
+          wordFrequencies.inc(word)
+
+        echo "The most frequent word is '", wordFrequencies.largest, "'"
+    ```
+
+1. 例のレンダリング結果
+    ```nim {4-6,8} title="sample.nim" showLineNumbers
+    import tables, strutils
+
+    var wordFrequencies = initCountTable[string]()
+    for line in stdin.lines:
+    for word in line.split(", "):
+      wordFrequencies.inc(word)
+
+    echo "The most frequent word is '", wordFrequencies.largest, "'"
+    ```
+
+## docusaurus用 {#for-docusaurus}
+### 強調記号 {#emphasis-added}
+1. アンダーバー(`_`)やアスタリスクなどを使う時、強調表示されてしまうので円マークorバックスラッシュ(`\`)を使って回避する
+    1. `_Italic_` {'>'} _Italic_
+    1. `\_Italic\_` {'>'} \_Italic\_
+
+### 不等号 {#inequality-sign}
+1. `<`、`>` を使うとhtmlタグ扱いでエラーとなる場合があるので以下の方法を使って回避する
+    1. 全角不等号を使う
+        1. :x:: `<強調したい文言>`
+        1. :o:: `＜強調したい文言＞`
+    1. `{'`、`'}` で括る
+        1. :x:: `abc <= 100`
+        1. :o:: `abc {'<='} 100`

package/templates/docs/04-internal/rules/review-process.mdx

@@ -0,0 +1,32 @@
+---
+sidebar_position: 4
+---
+# レビュープロセス
+
+## モブプログラミング推奨
+1. チーム全員でリアルタイムにコードを確認し、知識を共有する  
+1. その場でフィードバックを行い、修正や改善を即時反映する
+
+## 設計との照合
+1. 実装が設計書どおりに実現されているか確認する  
+1. 設計書の該当セクションとコード箇所を突き合わせる
+
+## 設計の妥当性確認
+1. 設計に漏れや誤りがないかレビューする  
+1. 要件やユースケースの抜け漏れ、前提条件の過不足をチェックする
+
+## エラー／警告対応
+1. コンパイルエラーやリンター警告がすべて解消されているか確認する  
+1. CIパイプラインでのビルド失敗やテストエラーがないかチェックする
+
+## コード品質
+1. 可読性・保守性の高いコードになっているか確認する  
+1. 冗長なロジックや複雑度の高い箇所を適切にリファクタリングする
+
+## issueチェックリスト
+1. issueに紐づくチェックリスト項目（テスト、ドキュメント更新など）がすべて完了しているか確認する  
+1. 必要に応じて新たなテストケースやドキュメントを追加する
+
+## 命名規則
+1. 変数名・関数名がプロジェクトの命名規則に沿っているか確認する  
+1. 一貫性があり意図が明確な名前付けになっているかチェックする

package/templates/docs/04-internal/screens/_category_.yaml

@@ -0,0 +1,2 @@
+label: '画面'
+position: 5

package/templates/docs/04-internal/screens/dashboard.mdx

@@ -0,0 +1,17 @@
+---
+sidebar_position: 4
+---
+import { TBD } from '@site/src/components/TBD';
+
+# ダッシュボード
+## ファイル
+<!-- 1. frontend/src/routes/[dashboard.svelte](../../../../frontend/src/routes/dashboard.svelte) -->
+
+## 概要
+1. <TBD/>
+
+## 画面イメージ
+1. <TBD/>
+
+## 項目説明
+1. <TBD/>

package/templates/docs/04-internal/screens/index.mdx

@@ -0,0 +1,20 @@
+---
+id: index
+sidebar_position: 1
+hide_table_of_contents: true
+---
+import { TBD } from '@site/src/components/TBD';
+
+# 画面定義
+## 画面一覧
+
+| Physical name              | Logical name   | Summyry | Comment |
+| -------------------------- | -------------- | ------- | ------- |
+| [login](login.mdx)         | ログイン       | -       |         |
+| └ registration             | 新規登録       | -       |         |
+| └ update-password          | パスワード更新 | -       |         |
+| [menu](menu.mdx)           | メニュー       | -       |         |
+| [dashboard](dashboard.mdx) | ダッシュボード | -       |         |
+
+## 画面遷移
+<TBD/>

package/templates/docs/04-internal/screens/login.mdx

@@ -0,0 +1,18 @@
+---
+sidebar_position: 2
+---
+import { TBD } from '@site/src/components/TBD';
+
+# ログイン
+## ファイル
+<!-- 1. frontend/src/routes/[login.svelte](../../../../frontend/src/routes/login.svelte) -->
+
+## 概要
+1. ログイン画面
+1. セッションなし
+
+## 画面イメージ
+1. <TBD/>
+
+## 項目説明
+1. <TBD/>

package/templates/docs/04-internal/screens/menu.mdx

@@ -0,0 +1,17 @@
+---
+sidebar_position: 3
+---
+import { TBD } from '@site/src/components/TBD';
+
+# メニュー
+## ファイル
+<!-- 1. frontend/src/routes/[menu.svelte](../../../../frontend/src/routes/menu.svelte) -->
+
+## 概要
+1. メニュー画面
+
+## 画面イメージ
+1. <TBD/>
+
+## 項目説明
+1. <TBD/>

package/templates/docs/04-internal/tables/_category_.yaml

@@ -0,0 +1,2 @@
+label: 'テーブル定義'
+position: 6

package/templates/docs/04-internal/tables/customer_details.mdx

@@ -0,0 +1,35 @@
+---
+sidebar_position: 3
+hide_table_of_contents: true
+---
+import TOCInline from '@theme/TOCInline';
+
+# customer_details - 会員詳細
+
+<details>
+  <summary>目次</summary>
+
+  <TOCInline toc={toc} />
+</details>
+
+## 説明 {#description}
+1. xxxの会員詳細
+1. 会員の電話番号、住所など
+
+## 表領域(schema) {#schema}
+1. `public`
+
+## 定義 {#definition}
+
+| Physical name    | Logical name | Type      | Digit | Not null | Default value     | Comment |
+| ---------------- | ------------ | --------- | ----: | :------: | ----------------- | ------- |
+| id               | ID           | serial    |     - |   :o:    |                   |         |
+| customer_id      | 顧客ID       | varchar   |   100 |   :o:    |                   |         |
+| phone_number     | 電話番号     | varchar   |    12 |   :o:    |                   |         |
+| postal_code      | 郵便番号     | varchar   |     8 |   :o:    |                   |         |
+| address_1        | 住所1        | varchar   |   500 |   :o:    |                   |         |
+| address_2        | 住所2        | varchar   |   500 |   :o:    |                   |         |
+| created_id       | 作成者ID     | integer   |     - |   :o:    |                   |         |
+| created_at       | 作成日時     | timestamp |     - |   :o:    | current_timestamp |         |
+| last_modified_id | 更新者ID     | integer   |     - |   :o:    |                   |         |
+| last_modified_at | 更新日時     | timestamp |     - |   :o:    | current_timestamp |         |

package/templates/docs/04-internal/tables/customers.mdx

@@ -0,0 +1,35 @@
+---
+sidebar_position: 2
+hide_table_of_contents: true
+---
+import TOCInline from '@theme/TOCInline';
+
+# customers - 会員
+
+<details>
+  <summary>目次</summary>
+
+  <TOCInline toc={toc} />
+</details>
+
+## 説明 {#description}
+1. xxxの会員
+
+## 表領域(schema) {#schema}
+1. `public`
+
+## 定義 {#definition}
+
+| Physical name      | Logical name | Type      | Digit | Not null | Default value     | Comment                      |
+| ------------------ | ------------ | --------- | ----: | :------: | ----------------- | ---------------------------- |
+| id                 | ID           | serial    |     - |   :o:    |                   |                              |
+| login_id           | ログインID   | varchar   |   255 |   :o:    |                   |                              |
+| customer_number    | 顧客番号     | varchar   |   100 |   :o:    |                   |                              |
+| password_encrypted | パスワード   | varchar   |   255 |   :o:    |                   |                              |
+| is_enabled         | is有効       | boolean   |     - |   :o:    | true              | true:有効<br/>false:無効     |
+| is_withdrawn       | is退会       | boolean   |     - |   :o:    | false             | true:退会済<br/>false:未退会 |
+| withdrawn_at       | 退会日時     | timestamp |     - |    -     |                   |                              |
+| created_id         | 作成者ID     | integer   |     - |    -     |                   |                              |
+| created_at         | 作成日時     | timestamp |     - |   :o:    | current_timestamp |                              |
+| last_modified_id   | 更新者ID     | integer   |     - |   :o:    |                   |                              |
+| last_modified_at   | 更新日時     | timestamp |     - |   :o:    | current_timestamp |                              |

package/templates/docs/04-internal/tables/index.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+hide_table_of_contents: true
+---
+# テーブル定義
+## テーブル一覧
+
+| Physical name                             | Logical name | Schema | Comment |
+| ----------------------------------------- | ------------ | ------ | ------- |
+| [customers](customers.mdx)                | 会員         | public |         |
+| └[customer_details](customer_details.mdx) | 会員詳細     | public |         |