Kuroco Admin Api

# API探索パターン

## 探索の3つの方法

### 1. advise: AI支援（推奨）

やりたいことを自然言語で伝えると、呼ぶべきAPIと手順をAIが回答:

```bash
kuroco-admin advise "記事を新しく作成したい" --json
```

レスポンスの `steps` にmt/ct/http_method/mode/endpointが含まれる。
- `endpoint`, `api_spec` → システム自動生成（正確、ハルシネーションなし）
- `summary`, `description`, `body_example` → AI生成

### 2. discover: モジュール/コントローラ一覧

```bash
# 全体概要
kuroco-admin discover --json

# 特定モジュールの詳細
kuroco-admin discover --mt topics --json
```

**レスポンス構造:**
```json
{
  "modules": [
    {
      "mt": "topics",
      "controllers": [
        { "ct": "topics_list", "url": "..." },
        { "ct": "topics_edit", "url": "..." }
      ]
    }
  ],
  "services": [...]
}
```

### 3. help: フィールドスキーマ

```bash
kuroco-admin help topics/topics_edit --json
```

JSON Schema形式で `data.request.properties` にフィールド定義、`data.request.required` に必須フィールドを返す。

**ext_colを含むスキーマが必要な場合:**

```bash
kuroco-admin exec --param MODE=schema --mt topics --ct topics_edit --param topics_group_id=99 --json
```

---

## 使い分け

| 方法 | 用途 |
|------|------|
| **advise**（推奨） | やりたいことからAPI手順をAIが提案（mt/ctが不明な場合） |
| **discover** | プログラム的にモジュール/コントローラを列挙 |
| **help** | 特定コントローラのフィールド定義・型・必須項目を確認 |

---

## モジュール関係マップ

主要な親子関係。親のIDが子の操作に必須:

```
TopicsGroup → Topics         (topics_group_id 必須)
MemberGroup → Member         (group_id 必須)
InquiryForm → InquiryMessage (inquiry_id 必須)
TagCategory → Tag            (tag_category_id 必須)
```

親の一覧を先に確認:

```bash
kuroco-admin exec topics/topics_group_list --columns topics_group_id,group_nm --json
```

**操作のコツ:**
- Topics操作前にTopicsGroupのlistで利用可能なグループを確認
- Member操作前にMemberGroupで所属グループを確認
- 不明な場合はdiscoverまたはadviseで必須パラメータを確認

---

## ページネーション

```bash
# 1ページ目
kuroco-admin exec topics/topics_list --param "topics_group_id[]=1" --param cnt=20 --param pageID=1 --json

# 2ページ目
kuroco-admin exec topics/topics_list --param "topics_group_id[]=1" --param cnt=20 --param pageID=2 --json
```

レスポンスの `pageInfo`:
```json
{
  "totalCnt": 150,
  "perPage": 20,
  "totalPageCnt": 8,
  "pageNo": 1
}
```

---

## 並列実行

独立したAPI呼び出しは複数の Bash tool call を同時に発行して並列実行可能:

```bash
# 別々のBash tool callで同時発行
kuroco-admin exec topics/topics_group_list --columns topics_group_id,group_nm --json
kuroco-admin exec member/member_group_list --columns group_id,group_nm --json
```


# CLI コマンドリファレンス

## グローバルオプション

| オプション | 説明 |
|-----------|------|
| `--json` | JSON形式で出力（AI agent・パイプ処理向け） |
| `--verbose` | HTTPリクエスト/レスポンスの詳細をstderrに出力 |

---

## login

認証してセッションを保存。

```bash
kuroco-admin login --url https://example.g.kuroco-mng.app
```

**オプション:**
- `--url <url>` (必須): Kuroco管理画面のURL

**動作:**
1. メールアドレスとパスワードを対話的に入力
2. `/management/login/login/` にPOST
3. セッションCookieを `~/.kuroco-admin/cookies.txt` に保存（mode 0o600）
4. 設定を `~/.kuroco-admin/config.json` に保存（mode 0o600）
5. `whoami` で認証を確認

---

## whoami

現在のセッション情報を表示。

```bash
kuroco-admin whoami --json
```

**レスポンス:**
```json
{
  "success": true,
  "data": {
    "member_id": 123,
    "name1": "太郎",
    "name2": "山田",
    "group_ids": [1, 2],
    "expiresAt": "2026-03-05T00:00:00+09:00",
    "status": "ok"
  },
  "errors": []
}
```

---

## discover

利用可能なモジュール・コントローラ・サービスを一覧。

```bash
# 全モジュール
kuroco-admin discover --json

# 特定モジュールのみ
kuroco-admin discover --mt topics --json
```

**オプション:**
- `--mt <module>` (任意): モジュールでフィルタ

**レスポンス:**
```json
{
  "success": true,
  "data": {
    "modules": [
      {
        "mt": "topics",
        "controllers": [
          { "ct": "topics_list", "url": "..." },
          { "ct": "topics_edit", "url": "..." }
        ]
      }
    ],
    "services": [...]
  },
  "errors": []
}
```

---

## help (schema)

コントローラ/サービスのスキーマ取得。

```bash
# コントローラのスキーマ
kuroco-admin help topics/topics_edit --json

# サービスのスキーマ
kuroco-admin help Email/send --json
```

**引数:**
- `[target]`: `module/controller` 形式（例: `topics/topics_edit`）。大文字開始の `Model/method` 形式（例: `Email/send`）はサービスのスキーマ取得に使用。

> **注意:** `exec` でのAPI実行では常に `mt/ct` 形式（小文字）を使用すること。`model/method` 形式はHTMLが返却される場合がある。`help`（スキーマ取得）ではどちらの形式も安全に使用可能。

**レスポンス:**
JSON Sche