mdjournal 1.0.14 → 1.0.16

package/README.md

@@ -1,209 +1,332 @@
-# mdJournal サーバー
+# mdJournal
 
-Markdown形式の日報データを管理するREST APIサーバーです。
+**Markdown日報を視覚的に管理するダッシュボードアプリケーション**
 
-## 起動方法
+[![npm version](https://img.shields.io/npm/v/mdjournal.svg)](https://www.npmjs.com/package/mdjournal)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-```bash
-# 依存関係のインストール
-npm install
-
-# 開発モードで起動（ホットリロード有効）
-npm run dev
+<p align="center">
+  <img src="docs/screenshot.png" alt="mdJournal Screenshot" width="800">
+</p>
 
-# ビルド
-npm run build
+## ✨ 特徴
 
-# 本番モードで起動
-npm start
-```
+- 📅 **カレンダービュー** - 月表示で稼働時間を可視化
+- ⏱️ **タイムライン** - 計画と実績を並べて表示、ドラッグ&ドロップで編集
+- ✅ **TODO管理** - プロジェクト別・ステータス別のタスク管理
+- 📝 **Markdown編集** - 慣れ親しんだMarkdown形式でデータを管理
+- 🔗 **外部連携** - Git commit/push、Slack投稿
 
-## CLI コマンド
+---
 
-### サーバー起動
+## 🚀 まずは試してみる
 
 ```bash
-# サンプルデータで起動
+# サンプルデータで起動（インストール不要）
 npx mdjournal
 
-# 設定ファイルを指定して起動
-npx mdjournal ./mdjournal.config.yaml
-npx mdjournal -c ./mdjournal.config.yaml
-
-# ポートを指定して起動
-npx mdjournal -p 8080
+# ブラウザが自動で開きます（http://localhost:3001）
 ```
 
-### バリデーション（フォーマット検証）
+これだけでサンプル日報を使ってダッシュボードを体験できます。
 
-日報ファイルが仕様に準拠しているか検証します。
+---
+
+## 📦 セットアップ
+
+自分の日報を管理するためのセットアップ手順です。
+
+### 1. 日報用ディレクトリを作成
 
 ```bash
-# ディレクトリ内の全.mdファイルを検証
-npx mdjournal validate ./data
+mkdir my-journal
+cd my-journal
+```
 
-# 特定の年度のみ検証
-npx mdjournal validate ./data/2020
+### 2. 設定ファイルを作成
 
-# 厳格モード（警告もエラーとして扱う）
-npx mdjournal validate ./data --strict
+```yaml
+# mdjournal.config.yaml
+projects: ./config/projects.yaml
+routines: ./config/routines.yaml
+reports: ./data
 
-# 詳細出力（修正提案を含む）
-npx mdjournal validate ./data --verbose
+timeline:
+  snapMinutes: 15         # ドラッグ時のスナップ単位（分）
+  defaultStartHour: 8     # 表示開始時刻
+  defaultEndHour: 20      # 表示終了時刻
 
-# JSON形式で出力（CI/CD連携用）
-npx mdjournal validate ./data --json
+server:
+  port: 3001
+```
+
+### 3. プロジェクト定義を作成
+
+```yaml
+# config/projects.yaml
+projects:
+  - code: P01
+    name: 社内業務
+    color: "#52c41a"
 
-# 利用可能なルール一覧を表示
-npx mdjournal validate --rules
+  - code: P02
+    name: プロジェクトA
+    color: "#1890ff"
 
-# 特定のルールをスキップ
-npx mdjournal validate ./data --skip separator-line,location-subsection
+  - code: P03
+    name: プロジェクトB
+    color: "#722ed1"
 ```
 
-### 統計情報（frontmatter）再集計
+### 4. ルーチン定義を作成（オプション）
+
+毎週決まった予定がある場合、ルーチンとして登録しておくと便利です。
+
+```yaml
+# config/routines.yaml
+routines:
+  weekly:
+    monday:
+      - time: "09:00"
+        project: P01
+        task: 週次定例会議
+      - time: "10:00"
+        project: P02
+        task: プロジェクトA 朝会
+
+    friday:
+      - time: "17:00"
+        project: P01
+        task: 週報作成
+```
+
+### 5. ディレクトリ構成
 
-日報ファイルにfrontmatter（統計情報）を付与または再集計します。
+最終的にこのような構成になります：
+
+```
+my-journal/
+├── mdjournal.config.yaml    # メイン設定ファイル
+├── config/
+│   ├── projects.yaml        # プロジェクト定義
+│   └── routines.yaml        # ルーチン定義
+└── data/                    # 日報が保存される場所
+    └── 2025/
+        └── 01/
+            ├── 2025-01-06.md
+            └── 2025-01-07.md
+```
+
+### 6. 起動
 
 ```bash
-# ディレクトリ内の全.mdファイルにfrontmatterを付与・更新
-npx mdjournal stats ./data
+npx mdjournal ./mdjournal.config.yaml
+```
 
-# 変更内容のプレビュー（実際には更新しない）
-npx mdjournal stats ./data --dry-run
-
-# 詳細出力
-npx mdjournal stats ./data --verbose
-
-# バリデーションを事前実行（エラーがあるファイルはスキップ）
-npx mdjournal stats ./data --validate
-
-# JSON形式で出力
-npx mdjournal stats ./data --json
-```
-
-#### frontmatterフィールド
-
-| フィールド | 型 | 説明 |
-|-----------|-----|------|
-| `planHours` | number | 計画時間の合計（時間） |
-| `resultHours` | number | 実績時間の合計（時間） |
-| `todoCount` | integer | TODO総数 |
-| `todoCompleted` | integer | 完了TODO数 |
-| `todoInProgress` | integer | 進行中TODO数 |
-| `projectHours` | object | プロジェクト別実績時間（時間） |
-| `updatedAt` | string | 最終更新日時（ISO 8601形式） |
-
-#### バリデーションルール
-
-| ルールコード | 説明 |
-|------------|------|
-| `header-format` | 日報ヘッダーの形式チェック |
-| `separator-line` | セクション区切り線（=====）の検出 |
-| `location-subsection` | 場所サブセクション（### [home]）の検出 |
-| `schedule-item-format` | PLAN/RESULT項目の形式チェック |
-| `time-format` | 時刻形式のチェック |
-| `todo-list-marker` | TODOリストマーカーの統一チェック |
-| `todo-inline-project` | TODO行内のプロジェクトコード検出 |
-| `todo-deadline-format` | 期限の括弧形式検出 |
-| `nested-todo` | ネストされたTODO検出 |
-| `required-sections` | 必須セクションの存在チェック |
-
-## 環境変数
-
-| 変数名 | 説明 | デフォルト値 |
-|--------|------|-------------|
-| `PORT` | サーバーポート | `3001` |
-| `CONFIG_REPORTS` | 日報ディレクトリのパス | `./sample/reports` |
-| `CONFIG_PROJECTS` | プロジェクト設定ファイルのパス | `./sample/config/projects.yaml` |
-| `CONFIG_ROUTINES` | ルーチン設定ファイルのパス | `./sample/config/routines.yaml` |
-| `CORS_ORIGIN` | CORSで許可するオリジン | `http://localhost:5173` |
-| `GOOGLE_CLIENT_ID` | Google OAuth Client ID | - |
-| `GOOGLE_CLIENT_SECRET` | Google OAuth Client Secret | - |
-
-## API エンドポイント
-
-| メソッド | エンドポイント | 説明 |
-|---------|---------------|------|
-| GET | `/api/reports/:date` | 日報取得 |
-| PUT | `/api/reports/:date` | 日報保存 |
-| DELETE | `/api/reports/:date` | 日報削除 |
-| GET | `/api/calendar` | カレンダー用集計データ取得 |
-| GET | `/api/calendar/months` | 日報が存在する年月リスト取得 |
-| GET | `/api/config` | 設定取得 |
-| PUT | `/api/config` | 設定更新 |
-| GET | `/api/gcal/events` | Googleカレンダー予定取得 |
-| GET | `/api/health` | ヘルスチェック |
-
-## ディレクトリ構造
-
-```
-server/
-├── src/
-│   ├── index.ts          # エントリーポイント
-│   ├── cli.ts            # CLIエントリーポイント
-│   ├── routes/           # APIルーター
-│   │   ├── reports.ts    # 日報API
-│   │   ├── calendar.ts   # カレンダーAPI
-│   │   ├── config.ts     # 設定API
-│   │   └── gcal.ts       # Googleカレンダー連携API
-│   ├── types/            # 型定義
-│   │   └── index.ts
-│   └── utils/            # ユーティリティ
-│       ├── markdown.ts   # Markdownパーサー
-│       ├── fileManager.ts # ファイル管理
-│       ├── validator.ts  # フォーマットバリデーター
-│       └── git.ts        # Git連携
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-## 日報ファイル形式
-
-日報ファイルはYAML frontmatter + Markdown形式で保存されます。
-詳細は [markdown-format-spec.md](../docs/markdown-format-spec.md) を参照してください。
+日報ファイルはダッシュボードから自動的に作成されます。
 
-```markdown
----
-planHours: 8.0
-resultHours: 7.5
-todoCount: 5
-todoCompleted: 2
-todoInProgress: 1
-projectHours:
-  P99: 2.5
-  P34: 3.0
-updatedAt: 2025-12-18T17:30:00+09:00
 ---
-# [日報] サンプル太郎 2025-12-18
+
+## 📝 日報の書き方
+
+日報は以下のようなMarkdown形式です。ダッシュボードで編集できますが、テキストエディタで直接編集することもできます。
+
+```markdown
+# [日報] 山田太郎 2025-01-06
 
 ## [PLAN]
-* 08:30 [P99] タスク確認
-* 09:00
+
+* 08:30 [P01] タスク確認・朝会
+* 09:00 [P02] プロジェクトA 開発
+* 12:00
+* 13:00 [P03] プロジェクトB MTG
+* 15:00 [P02] プロジェクトA 開発
+* 18:00
 
 ## [RESULT]
-* 08:30 [P99] タスク確認
-* 09:00
+
+* 08:30 [P01] タスク確認・朝会
+* 09:00 [P02] プロジェクトA 開発
+* 12:00
+* 13:00 [P03] プロジェクトB MTG（延長）
+* 16:00 [P02] プロジェクトA 開発
+* 19:00
 
 ## [TODO]
 
-### P99
-- [ ] @2025-12-20 !!! 重要タスク
-- [*] !! 進行中タスク
-- [x] 完了タスク
-- [-] 保留タスク
+### P01
+- [ ] @2025-01-10 !!! 重要なタスク
+- [*] !! 進行中のタスク
+
+### P02
+- [x] 完了したタスク
+- [-] 保留中のタスク
 
 ## [NOTE]
-自由記述メモ
+
+本日のメモや振り返りをここに記載。
 ```
 
-## 開発
+### タイムライン記法
+
+```
+* HH:MM [プロジェクトコード] タスク内容
+* HH:MM                              ← 終了時刻のみ（空き時間の終わり）
+```
+
+- `[PLAN]` セクション: 予定
+- `[RESULT]` セクション: 実績
+
+### TODOの書き方
+
+```markdown
+- [ ] 未着手のタスク
+- [*] 進行中のタスク
+- [x] 完了したタスク
+- [-] 保留中のタスク
+```
+
+#### 期日と優先度
+
+```markdown
+- [ ] @2025-01-10 期日付きタスク
+- [ ] !!! 優先度：高
+- [ ] !!  優先度：中
+- [ ] !   優先度：低
+- [ ] @2025-01-10 !!! 期日＋優先度の組み合わせ
+```
+
+---
+
+## 🔗 外部連携
+
+### Git連携
+
+日報ディレクトリがGitリポジトリの場合、ダッシュボードの保存ボタンから直接commit/pushできます。
+
+```bash
+# 日報ディレクトリをGitリポジトリ化
+cd my-journal
+git init
+git remote add origin <your-repo-url>
+```
+
+### Slack連携
+
+日報をSlackチャンネルに投稿できます。
+
+```yaml
+# mdjournal.config.yaml に追加
+slack:
+  enabled: true
+  webhookUrl: ${SLACK_WEBHOOK_URL}  # 環境変数から取得
+  channel: "#daily_report"
+```
+
+環境変数の設定:
+
+```bash
+export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."
+```
+
+### 保存ダイアログ
+
+保存ボタンから開くダイアログで、保存範囲を選択できます：
+
+1. **保存のみ** - ローカルファイルに保存
+2. **Commitまで** - 保存 + Git commit
+3. **Pushまで** - 保存 + commit + push
+4. **Slack投稿** - 上記 + Slackに投稿（Slack連携が有効な場合）
+
+---
+
+## 🛠️ CLIコマンド
 
 ```bash
-# TypeScriptの型チェック
-npx tsc --noEmit
+# サーバー起動
+npx mdjournal [config.yaml]
+
+# 日報ファイルのバリデーション
+npx mdjournal validate ./data
+npx mdjournal validate ./data --verbose  # 詳細表示
+npx mdjournal validate ./data --strict   # 厳格モード
+
+# 統計情報の再集計（frontmatter更新）
+npx mdjournal stats ./data
+npx mdjournal stats ./data --dry-run     # プレビューのみ
+
+# 設定ファイルの検証
+npx mdjournal config ./mdjournal.config.yaml
+```
+
+---
+
+## ⚙️ 設定リファレンス
+
+### タイムライン設定
 
-# ESLint
-npm run lint
+```yaml
+timeline:
+  hourHeight: 60          # 1時間あたりの高さ（px）
+  maxHours: 36            # 最大表示時間
+  defaultStartHour: 8     # デフォルト開始時刻
+  defaultEndHour: 20      # デフォルト終了時刻
+  snapMinutes: 15         # スナップ単位（分）
 ```
+
+### プロジェクト定義
+
+```yaml
+# config/projects.yaml
+projects:
+  - code: P01             # タイムラインで使用するコード
+    name: 社内業務         # 表示名
+    fullName: 社内管理・雑務  # フルネーム（オプション）
+    color: "#52c41a"      # 表示色
+    category: internal    # カテゴリID（オプション）
+    active: true          # アクティブフラグ（デフォルト: true）
+
+categories:               # カテゴリ定義（オプション）
+  - id: internal
+    name: 社内業務
+    color: "#52c41a"
+```
+
+### ルーチン定義
+
+```yaml
+# config/routines.yaml
+routines:
+  # 週次ルーチン
+  weekly:
+    monday:
+      - time: "09:00"
+        project: P01
+        task: 週次定例
+
+  # 月次ルーチン
+  monthly:
+    start_of_month:       # 月初
+      - project: P01
+        task: 経費精算
+    end_of_month:         # 月末
+      - project: P01
+        task: 月次レポート
+
+  # 四半期ルーチン
+  quarterly:
+    - months: [3, 6, 9, 12]
+      tasks:
+        - project: P01
+          task: 四半期レビュー
+```
+
+---
+
+## 📄 ライセンス
+
+MIT License
+
+---
+
+**mdJournal** - Markdownで日報をもっと便利に