Docs

Bundle OKF 0.2 · 4 conceitos · k2works/case-study-cargo-tracker
Open source Repository Open in the app JSON README (API)
About

# Docs

* [adr/](adr/) - 意思決定
* [design/](design/) - 設計
* [operation/](operation/) - 運用
* [reference/](reference/) - リファレンス
Details

Kind: OKF bundles
Topic: No topic detected
Publisher: k2works
Origin: okf_github
Category: dados
Version: 0.2
Last push: 2026-09-09T00:12:38Z
Repository state: ativo
Language: HTML
Added: 2026-09-08 02:24:34
Updated: 2026-09-08 02:24:34
Origin id: k2works/case-study-cargo-tracker:.agents/skills/apply-okf-workspace/iteration-1/eval-2-verify-reviewed-doc/with_skill/outputs/docs_after/index.md
README

# 国際貨物輸送システムのケーススタディ

## 概要

DDD（ドメイン駆動設計）のケーススタディとして、貨物追跡システム（Cargo Tracker）を実装するプロジェクトです。

### 目的

- DDD の戦略的・戦術的設計パターンを実践的に学ぶ
- XP（エクストリームプログラミング）に基づくアジャイル開発を体験する
- TDD（テスト駆動開発）による品質の高いソフトウェア開発を実践する

### ビジネス概要

ある国際貨物輸送会社では、世界中の港湾を結ぶ貨物輸送サービスを提供しています。

荷主が貨物の輸送を依頼すると、予約担当者が貨物の仕様（種別・重量・サイズ）と輸送要件（出発地・目的地・到着期限）を登録します。経路設計者は航海スケジュールを参照しながら最適な輸送ルートを設計し、荷主に提案します。荷主がルートを承認すると予約が確定し、貨物には追跡番号が発行されます。

貨物が港湾に届くと、荷役作業員が積込・荷降し・受領・引取といった荷役作業を行い、その都度作業を記録します。記録された荷役イベントは追跡情報に即座に反映され、荷主はいつでも貨物の現在位置と状態をリアルタイムで確認できます。破損や遅延などの例外が発生した場合も、迅速に対応し荷主に通知します。

貨物が荷受人に届けられると配送完了となり、輸送料金の精算が行われます。

本システムでは、この一連の業務フローを DDD の境界付けられたコンテキスト（Booking・Routing・Handling・Tracking・Shared）に分割して設計・実装します。

### 前提

| ソフトウェア | バージョン | 備考 |
| :----------- | :--------- | :--- |
| nodejs       | 22.x       |      |

## 構成

- [構築](#構築)
- [配置](#配置)
- [運用](#運用)
- [開発](#開発)

## 詳細

### Quick Start

```bash
npm install
npm start
```

### 構築

```bash
claude mcp add -s project memory -- npx @modelcontextprotocol/server-memory
claude mcp add -s project codex -- npx @openai/codex mcp-server
```

#### ralph-loopの導入

- Claude Code 起動後、/plugin を実行

- 検索ボックスで ralph-loop を探して選択

- インストールするスコープを選ぶ（ユーザー / プロジェクト / ローカル）

- Claude Code を再起動

- コマンドで実行

```powershell
/ralph-loop "<プロンプト>" --max-iterations <数値> --completion-promise "<完了テキスト>"
```

#### AI アシスタント（Skills）

`.claude/skills/` ディレクトリに定義された Skills により、AI アシスタントがタスクに応じた専門的な指示を自動的に読み込みます。Progressive Disclosure（段階的開示）により、必要なスキルのみがコンテキストに展開されます。

Skills 一覧は [CLAUDE.md の Skills 体系](CLAUDE.md#skills-体系) を参照してください。

新しいスキルの追加・改善には `/skill-creator` プラグインを使用します。テスト・評価・最適化を含むスキル作成ワークフローが自動化されます。

**[⬆ back to top](#構成)**

### 配置

#### GitHub Pages セットアップ

1. **GitHub リポジトリの Settings を開く**
    - リポジトリページで `Settings` タブをクリック

2. **Pages 設定を開く**
    - 左サイドバーの `Pages` をクリック

3. **Source を設定**
    - `Source` で `Deploy from a branch` を選択
    - `Branch` で `gh-pages` を選択し、フォルダは `/ (root)` を選択
    - `Save` をクリック

4. **初回デプロイ**
    - main ブランチにプッシュすると GitHub Actions が自動実行
    - Actions タブでデプロイ状況を確認

**[⬆ back to top](#構成)**

### 運用

#### ドキュメントの編集

1. ローカル環境でMkDocsサーバーを起動
   ```
   docker-compose up mkdocs
   ```
   または、Gulpタスクを使用:
   ```
   npm run docs:serve
   ```

2. ブラウザで http://localhost:8000 にアクセスして編集結果をプレビュー

3. `docs/`ディレクトリ内のMarkdownファイルを編集

4. 変更をコミットしてプッシュ
   ```
   git add .
   git commit -m "ドキュメントの更新"
   git push
   ```

#### Gulpタスクの使用

プロジェクトには以下のGulpタスクが用意されています：

##### MkDocsタスク

- MkDocsサーバーの起動:
  ```
  npm run docs:serve
  ```
  または
  ```
  npx gulp mkdocs:serve
  ```

- MkDocsサーバーの停止:
  ```
  npm run docs:stop
  ```
  または
  ```
  npx gulp mkdocs:stop
  ```

- MkDocsドキュメントのビルド:
  ```
  npm run docs:build
  ```
  または
  ```
  npx gulp mkdocs:build
  ```

##### 作業履歴（ジャーナル）タスク

- すべてのコミット日付の作業履歴を生成:
  ```
  npm run journal
  ```
  または
  ```
  npx gulp journal:generate
  ```

- 特定の日付の作業履歴を生成:
  ```
  npx gulp journal:generate:date --date=YYYY-MM-DD
  ```
  (例: `npx gulp journal:generate:date --date=2023-04-01`)

生成された作業履歴は `docs/journal/` ディレクトリに保存され、各ファイルには指定された日付のコミット情報が含まれます。

#### GitHub Container Registry

このプロジェクトでは、GitHub Container Registry（GHCR）を使用して開発コンテナイメージを管理しています。

##### 自動ビルド・プッシュ

タグをプッシュすると、GitHub Actions が自動的にコンテナイメージをビルドし、GHCR にプッシュします。

```bash
# タグを作成してプッシュ
git tag 0.0.1
git push origin 0.0.1
```

##### イメージの取得・実行

GHCR からイメージを取得して実行するには：

```bash
# イメージをプル
docker pull ghcr.io/k2works/case-study-cargo-tracker:latest

# または特定バージョン
docker pull ghcr.io/k2works/case-study-cargo-tracker:0.0.1

# コンテナを実行
docker run -it -v $(pwd):/srv ghcr.io/k2works/case-study-cargo-tracker:latest
```

または、docker-compose を使用してローカルでビルド・実行することもできます：

```bash
# 開発環境を起動して中に入る
docker-compose run --rm dev bash
```

認証が必要な場合は、以下のコマンドでログインします：

```bash
# GitHub Personal Access Token でログイン
echo $GITHUB_TOKEN | docker login ghcr.io -u <username> --password-stdin
```

##### 権限設定

- リポジトリの Settings → Actions → General で `Read and write permissions` を設定
- `GITHUB_TOKEN` に `packages: write` 権限が付与されています

##### Dev Container の使用

VS Code で Dev Container を使用する場合：

1. VS Code で「Dev Containers: Reopen in Container」を実行
2. または「Dev Containers: Rebuild and Reopen in Container」で再ビルド

**[⬆ back to top](#構成)**

### 開発

#### Nix による開発環境

Nix を使用して、再現可能な開発環境を構築できます。

##### 準備

1. [Nix をインストール](https://nixos.org/download.html)します。
2. Flakes を有効にします（`~/.config/nix/nix.conf` に `experimental-features = nix-command flakes` を追加）。

##### 環境の利用

- **デフォルト環境（共通ツール）に入る:**
  ```bash
  nix develop
  ```

- **Node.js 環境に入る:**
  ```bash
  nix develop .#node
  ```

- **Python/MkDocs 環境に入る:**
  ```bash
  nix develop .#python
  ```

環境から抜けるには `exit` を入力します。

##### 依存関係の更新

```bash
nix flake update
```

**[⬆ back to top](#構成)**

## 参照
Docs

About

Details

README

More
