docs: DEV-8609 Claude Code向けのドキュメントとコマンドを追加

.claude/commands/sync-api-doc.md

@@ -0,0 +1,190 @@
+---
+description: 公開APIドキュメント（zaico_api_doc）とzaico_webの実装を比較し、スキーマ定義（型、最大文字列長、必須）の不整合を検出・修正する
+---
+
+# 公開APIドキュメント同期コマンド
+
+## 概要
+
+公開APIドキュメント（API Blueprint形式）とzaico_webの実装を比較し、以下の不整合を検出・修正します：
+
+- maxLength（最大文字列長）の定義漏れ・不整合
+- required（必須）の定義漏れ・不整合
+- レスポンス項目の漏れ
+
+## 実行手順
+
+### 1. モデルバリデーションの確認
+
+zaico_webの以下のモデルから`validates`を抽出：
+
+- app/models/inventory.rb
+- app/models/customer.rb
+- app/models/packing_slip.rb
+- app/models/purchase.rb
+- app/models/delivery.rb
+- app/models/purchase_item.rb
+- app/models/inventories_set.rb
+- app/models/inventories_set_item.rb
+- app/models/shipping_client.rb
+- app/models/inventory_attachment.rb
+
+確認項目：
+- `validates :field, presence: true` → required
+- `validates :field, length: { maximum: N }` → maxLength
+
+### 2. DBスキーマの確認
+
+`zaico_web/db/schema.rb`から以下を確認：
+
+- string型カラムの`limit`制約
+- `null: false`制約（モデルバリデーションがない場合の補完）
+
+### 3. jbuilderの確認
+
+`zaico_web/app/views/api/v1/`配下のjbuilderファイルから出力項目を確認：
+
+- inventories/index.json.jbuilder
+- inventories/show.json.jbuilder
+- customers/index.json.jbuilder
+- packing_slips/index.json.jbuilder
+- packing_slips/show.json.jbuilder
+- purchases/index.json.jbuilder
+- purchases/show.json.jbuilder
+- inventories_sets/index.json.jbuilder
+- inventories_sets/show.json.jbuilder
+- inventory_attachments/index.json.jbuilder
+- inventory_group_items/index.json.jbuilder
+- shipping_clients/index.json.jbuilder
+
+### 4. APIドキュメントとの比較
+
+`zaico_api_doc/includes/api/`配下のAPIドキュメントと比較：
+
+- inventories.md
+- customers.md
+- packing_slips.md
+- purchases.md
+- inventories_sets.md
+- inventory_attachments.md
+- inventory_group_items.md
+- shipping_clients.md
+
+### 5. 不整合のレポート
+
+検出した不整合を以下の形式でレポート：
+
+| ファイル | フィールド | 問題 | 現状 | 期待値 |
+|----------|------------|------|------|--------|
+| inventories.md | title | maxLength未定義 | - | 200 |
+| customers.md | name | required未指定 | - | required |
+
+### 6. 修正の実施
+
+レポートに基づき、APIドキュメントを修正：
+
+- maxLengthは説明文に「（最大N文字）」形式で追加
+- requiredは`(string, required)`形式で追加
+- 欠落しているレスポンス項目を追加
+
+## 優先順位
+
+モデルバリデーション > DBスキーマ制約
+
+## 検証
+
+修正後、以下を実行して確認：
+
+```bash
+cd zaico_api_doc && yarn build
+```
+
+## モデルバリデーション参照表
+
+### Inventory
+| フィールド | presence | maxLength | 備考 |
+|------------|----------|-----------|------|
+| user_group | true | 255 | |
+| title | - | 200 | |
+| state | - | 200 | |
+| place | - | 200 | |
+| quantity | - | - | decimal(15,4)：整数部11桁、小数部4桁 |
+| logical_quantity | - | - | decimal(15,4)：整数部11桁、小数部4桁 |
+| code | - | 200 | |
+| category | - | 250 | |
+| optional_attributes | - | 9000 | |
+| group_tag | - | 250 | |
+
+### Customer
+| フィールド | presence | maxLength |
+|------------|----------|-----------|
+| name | true | 100 |
+| zip | - | 7 |
+| address | - | 1000 |
+| building_name | - | 1000 |
+| phone_number | - | 11 |
+| etc | - | 500 |
+| email | - | 200 |
+| num | - | 200 |
+
+### PackingSlip
+| フィールド | presence | maxLength |
+|------------|----------|-----------|
+| num | - | 250 |
+| delivery_date | true (if completed) | - |
+| memo | - | 250 |
+| note | - | 250 |
+| user_group | - | 255 |
+
+### Purchase
+| フィールド | presence | maxLength |
+|------------|----------|-----------|
+| num | - | 250 |
+| purchase_date | true (if purchased) | - |
+| memo | - | 250 |
+| etc | - | 250 |
+| user_group | - | 255 |
+
+### Delivery
+| フィールド | presence | maxLength | 備考 |
+|------------|----------|-----------|------|
+| quantity | - | - | decimal(15,4)：整数部11桁、小数部4桁 |
+| unit_price | - | - | decimal(15,4)：整数部11桁、小数部4桁 |
+| etc | - | 250 | |
+| delivery_date | true (if completed) | - | |
+
+### PurchaseItem
+| フィールド | presence | maxLength | 備考 |
+|------------|----------|-----------|------|
+| quantity | true | - | decimal(15,4)：整数部11桁、小数部4桁 |
+| unit_price | - | - | decimal(15,4)：整数部11桁、小数部4桁 |
+| etc | - | 250 | |
+| purchase_date | true (if purchased) | - | |
+
+### InventoriesSet
+| フィールド | presence | maxLength | 備考 |
+|------------|----------|-----------|------|
+| title | true | 200 | |
+| memo | - | 250 | |
+| code | - | 200 | |
+| price | - | - | decimal(15,4)：整数部11桁、小数部4桁 |
+
+### InventoriesSetItem
+| フィールド | presence | maxLength | 備考 |
+|------------|----------|-----------|------|
+| inventory_id | true | - | |
+| quantity | true | - | decimal(15,4)：整数部11桁、小数部4桁、0より大きい |
+
+### ShippingClient
+| フィールド | presence | maxLength |
+|------------|----------|-----------|
+| name | true | 16 |
+| zip | true | 7 |
+| address | true | 32 |
+| building_name | - | 16 |
+| phone_number | true | 11 |
+
+### InventoryAttachment
+| フィールド | presence | maxLength |
+|------------|----------|-----------|
+| item_file | true | - |

CLAUDE.md

@@ -0,0 +1,38 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ZAICO API Documentation repository - generates interactive HTML documentation from Markdown API specifications using Aglio (API Blueprint format). Published at https://zaicodev.github.io/zaico_api_doc/
+
+## Development Commands
+
+```bash
+# Install dependencies (requires Node.js v16)
+yarn
+
+# Development server with auto-reload (localhost:3005)
+yarn dev
+
+# Build production HTML (outputs to dist/index.html)
+yarn build
+```
+
+## Architecture
+
+- **api.md**: Main entry point using API Blueprint FORMAT: 1A syntax. Includes all API endpoint files via `<!-- include(...) -->` directives.
+- **includes/authorization.md**: Authentication documentation (Bearer token)
+- **includes/api/*.md**: Individual API endpoint documentation files (inventories, purchases, packing_slips, customers, etc.)
+- **dist/index.html**: Generated HTML output (committed to repo)
+
+## Adding New API Endpoints
+
+1. Create a new file in `includes/api/` following API Blueprint format
+2. Add `<!-- include(includes/api/your_new_file.md) -->` to `api.md`
+3. Use `# Group` for resource grouping, `## Endpoint [/path]` and `### HTTP_METHOD` for endpoints
+4. Define request/response with `+ Request`, `+ Response`, `+ Parameters`, `+ Attributes`
+
+## Deployment
+
+GitHub Actions automatically builds and deploys to GitHub Pages when commits are pushed to `master` branch. The workflow is defined in `.github/workflows/gh-pages.yml`.

includes/api/customers.md

@@ -108,32 +108,32 @@
 ## Data Structures
 ### CustomersView
 + id: 1 (number) - レコードID
-+ name: `取引先A` (string) - 取引先名
-+ email: `zaico@example.com` (string) - メールアドレス
-+ name_postfix: `様` (string) - 敬称
-+ zip: `1234567` (string) - 郵便番号
-+ address: `東京都港区` (string) - 住所
-+ building_name: `港ビル` (string) - 建物名・部屋番号
-+ phone_number: `08012345678` (string) - 電話番号
-+ etc: `取引先` (string) - 備考
++ name: `取引先A` (string) - 取引先名（最大100文字）
++ email: `zaico@example.com` (string) - メールアドレス（最大200文字）
++ name_postfix: `様` (string) - 敬称（最大10文字）
++ zip: `1234567` (string) - 郵便番号（最大7文字）
++ address: `東京都港区` (string) - 住所（最大1000文字）
++ building_name: `港ビル` (string) - 建物名・部屋番号（最大1000文字）
++ phone_number: `08012345678` (string) - 電話番号（最大11文字）
++ etc: `取引先` (string) - 備考（最大500文字）
 + fax_number: `5678` (string) - FAX番号
 + category: `東京` (string) - カテゴリ
 + `customer_type`: `packing_slip` (string) - 入出庫区分
-+ num: `1` (string) - 取引先No.
++ num: `1` (string) - 取引先No.（最大200文字）
 
 ### CustomerCreateParams
-+ name: `取引先A` (string) -  取引先名
-+ email: `zaico@example.com` (string) - メールアドレス
-+ name_postfix: `様` (string) - 敬称
-+ zip: `1234567` (string) - 郵便番号
-+ address: `東京都港区` (string) - 住所
-+ building_name: `港ビル` (string) - 建物名・部屋番号
-+ phone_number: `08012345678` (string) - 電話番号
-+ etc: `取引先` (string) - 備考
++ name: `取引先A` (string, required) - 取引先名（最大100文字）
++ email: `zaico@example.com` (string) - メールアドレス（最大200文字）
++ name_postfix: `様` (string) - 敬称（最大10文字）
++ zip: `1234567` (string) - 郵便番号（最大7文字）
++ address: `東京都港区` (string) - 住所（最大1000文字）
++ building_name: `港ビル` (string) - 建物名・部屋番号（最大1000文字）
++ phone_number: `08012345678` (string) - 電話番号（最大11文字）
++ etc: `取引先` (string) - 備考（最大500文字）
 + fax_number: `5678` (string) - FAX番号
 + category: `東京` (string) - カテゴリ
 + `customer_type`: `purchase` (string) - 入出庫区分
-+ num: `1` (string) - 取引先No.
++ num: `1` (string) - 取引先No.（最大200文字）
 
 ### CustomerCreateSuccessfully
 + code: 200 (number) - コード
@@ -142,18 +142,18 @@
 + data_id: 1 (number) - レコードID
 
 ### CustomerUpdateParams
-+ name: `取引先A` (string) -  取引先名
-+ email: `zaico@example.com` (string) - メールアドレス
-+ name_postfix: `様` (string) - 敬称
-+ zip: `1234567` (string) - 郵便番号
-+ address: `東京都港区` (string) - 住所
-+ building_name: `港ビル` (string) - 建物名・部屋番号
-+ phone_number: `08012345678` (string) - 電話番号
-+ etc: `取引先` (string) - 備考
++ name: `取引先A` (string) - 取引先名（最大100文字）
++ email: `zaico@example.com` (string) - メールアドレス（最大200文字）
++ name_postfix: `様` (string) - 敬称（最大10文字）
++ zip: `1234567` (string) - 郵便番号（最大7文字）
++ address: `東京都港区` (string) - 住所（最大1000文字）
++ building_name: `港ビル` (string) - 建物名・部屋番号（最大1000文字）
++ phone_number: `08012345678` (string) - 電話番号（最大11文字）
++ etc: `取引先` (string) - 備考（最大500文字）
 + fax_number: `5678` (string) - FAX番号
 + category: `東京` (string) - カテゴリ
 + `customer_type`: `packing_slip` (string) - 入出庫区分
-+ num: `1` (string) - 取引先No.
++ num: `1` (string) - 取引先No.（最大200文字）
 
 ### CustomerUpdateSuccessfully
 + code: 200 (number) - コード

includes/api/inventories.md

@@ -185,20 +185,20 @@
 + message: `Data was successfully deleted.` (string) - メッセージ
 
 ### InventoryUpdateParams
-+ title: `在庫データ` (string, required) - 在庫データタイトル
-+ quantity: 10 (string) - 数量
++ title: `在庫データ` (string, required) - 在庫データタイトル（最大200文字）
++ quantity: 10 (string) - 数量（整数部11桁、小数部4桁）
 + unit: `個` (string) - 単位
-+ category: `製品` (string) - カテゴリ
-+ state: `新品` (string) - 状態
-+ place: `ZAICO倉庫` (string) - 保管場所
++ category: `製品` (string) - カテゴリ（最大250文字）
++ state: `新品` (string) - 状態（最大200文字）
++ place: `ZAICO倉庫` (string) - 保管場所（最大200文字）
 + etc: `備考` (string) - 備考
-+ group_tag: `グループタグ` (string) - グループタグ（フルプランのみ）
-+ user_group: `ユーザーグループ` (string) - ユーザーグループ(カンマ区切りで複数指定可)
-+ code: `tw201800000000` (string) - バーコードの値
++ group_tag: `グループタグ` (string) - グループタグ（フルプランのみ）（最大250文字）
++ user_group: `ユーザーグループ` (string) - ユーザーグループ(カンマ区切りで複数指定可)（最大255文字）
++ code: `tw201800000000` (string) - バーコードの値（最大200文字）
 + item_image: `base64-encoded-image` (string)
 + stocktake_attributes
-  + checked_at: `2018-03-27T09:38:19+09:00` (string) - 棚卸日
-+ optional_attributes (array[object], fixed-type)
+  + checked_at: `2018-03-27T09:38:19+09:00` (string) - 棚卸日（ISO 8601形式）
++ optional_attributes (array[object], fixed-type) - 追加項目（最大9000文字）
     + (object)
         + name: `追加項目名` (string) - 追加項目名
         + value: `追加項目値` (string) - 追加項目値
@@ -228,31 +228,32 @@
 
 ### InventoriesViews
 + id: 1 (number) - ID
-+ title: `在庫データ` (string) - 在庫データタイトル
-+ quantity: 10 (string) - 数量
-+ logical_quantity: 10 (string) - 予定フリー在庫数（フルプランのみ）
++ title: `在庫データ` (string) - 在庫データタイトル（最大200文字）
++ quantity: 10 (string) - 数量（整数部11桁、小数部4桁）
++ logical_quantity: 10 (string) - 予定フリー在庫数（フルプランのみ）（整数部11桁、小数部4桁）
 + unit: `個` (string) - 単位
-+ category: `製品` (string) - カテゴリ
-+ state: `新品` (string) - 状態
-+ place: `ZAICO倉庫` (string) - 保管場所
++ category: `製品` (string) - カテゴリ（最大250文字）
++ categories (array[string]) - カテゴリの配列（categoryをカンマ分割した配列）
++ state: `新品` (string) - 状態（最大200文字）
++ place: `ZAICO倉庫` (string) - 保管場所（最大200文字）
 + etc: `備考` (string) - 備考
-+ group_tag: `グループタグ` (string) - グループタグ（フルプランのみ）
-+ code: `tw201800000000` (string) - バーコードの値
++ group_tag: `グループタグ` (string) - グループタグ（フルプランのみ）（最大250文字）
++ code: `tw201800000000` (string) - バーコードの値（最大200文字）
 + item_image (object)
   + url: `itemimageurl` (string) - 画像URL
 + stocktake_attributes
-  + checked_at: `2018-03-27T09:38:19+09:00` (string) - 棚卸日
-+ optional_attributes (array[object],fixed-type)
+  + checked_at: `2018-03-27T09:38:19+09:00` (string) - 棚卸日（ISO 8601形式）
++ optional_attributes (array[object],fixed-type) - 追加項目（最大9000文字）
   + (object)
     + name: `追加項目名` (string) - 追加項目名
     + value: `追加項目値` (string) - 追加項目値
 + quantity_management_attributes
   + order_point_quantity: 5 (string) - 発注点
-+ created_at: `2018-03-27T09:38:19+09:00` (string) - 作成日
-+ updated_at `2018-03-27T09:38:19+09:00` (string) - 更新日
++ created_at: `2018-03-27T09:38:19+09:00` (string) - 作成日（ISO 8601形式）
++ updated_at `2018-03-27T09:38:19+09:00` (string) - 更新日（ISO 8601形式）
 + create_user_name: `田村 太郎` (string) - 作成者
 + update_user_name: `田村 次郎` (string) - 更新者
-+ user_group: `基本グループ` (string) - ユーザーグループ
++ user_group: `基本グループ` (string) - ユーザーグループ（最大255文字）
 + is_quantity_auto_conversion_by_unit: `1` (string) - 単位換算するかどうか。"1"なら単位換算する、"0"なら単位換算しない
 + quantity_auto_conversion_by_unit_name: `箱` (string) - 単位換算後の単位名
 + quantity_auto_conversion_by_unit_factor: `12` (string) - 単位換算係数