This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

ICE API Server Specification

Overview

h-1-core Androidアプリ内蔵のREST APIサーバー。Mattermost経由ではなく直接API通信でAndroidアプリを操作・状態確認可能にする。

Address: http://localhost:8080 (Android local, loopback bind)
Via SSH Tunnel: SSH Remote Forward :3000 → Android:8080 → http://gui1:3000

Architecture

GUI/SSH Host ──→ SSH Remote Forward (:3000) ──→ Android :8080 (IceApiServer)
                     ↑                            ↑
               pve1/labo/gui1              h-1-core Android app

ICE = Interactive Control & Examination — Mattermostを介さず直接APIでAndroidアプリを操作する仕組み。

Endpoints

Health & Info

Method	Path	Description
GET	/health	サーバー稼働確認
GET	/ping	簡易PING（/healthと同じ）
GET	/	API情報・エンドポイント一覧

State & Errors

Method	Path	Description
GET	/state	全状態ダンプ（DB・エラー・設定）
GET	/errors	エラー履歴のみ抽出（旧、非推奨）
GET	/api/errors	アプリケーションエラーログ取得
DELETE	/api/errors	アプリケーションエラーログ全削除

GET /api/errors: エラーログ一覧取得

{
  "count": 5,
  "errors": [
    {
      "timestamp": "2024-06-21T08:30:00.000Z",
      "message": "プリセット保存エラー: ...",
      "stackTrace": "...",
      "screen": "ProjectDetailScreen",
      "context": "project_id: xxx, preset: standard"
    }
  ]
}

DELETE /api/errors: エラーログ全削除

{
  "cleared": true
}

Command Execution

Method	Path	Description
POST	/command	DebugConsoleコマンド実行

Request Body:

{
  "command": "system.status",
  "args": []
}

Response:

{
  "command": "system.status",
  "args": [],
  "result": "DB: ..."
}

Database Query

Method	Path	Description
POST	/db/query	SELECT/PRAGMAクエリ実行

Request Body:

{
  "sql": "SELECT * FROM invoices LIMIT 10"
}

Response:

{
  "sql": "SELECT * FROM invoices LIMIT 10",
  "rows": [...],
  "count": 10
}

File System Access (MCP file tools equivalent)

Method	Path	Description
GET	/fs/read?path=xxx	テキストファイル読み込み
POST	/fs/write	ファイル書き込み
GET	/fs/list?path=xxx	ディレクトリ列挙
GET	/fs/download?path=xxx	バイナリファイルダウンロード

GET /fs/read: テキストファイルをJSONで返す（10MB制限）

GET http://localhost:3000/fs/read?path=/data/user/0/com.h1.core/app_flutter/config.json

Response:

{
  "path": "/data/user/0/com.h1.core/app_flutter/config.json",
  "size": 1234,
  "text": true,
  "content": "{...}"
}

POST /fs/write: ファイルに書き込む

{
  "path": "/tmp/test.txt",
  "content": "hello world",
  "isBase64": false
}

GET /fs/list?path=xxx: ディレクトリの中身を列挙

GET http://localhost:3000/fs/list?path=/data/user/0/com.h1.core/app_flutter

Response:

{
  "path": "/data/user/0/...",
  "entries": [
    {"name": "h1_core.db", "size": 52428, "type": "file", "isDirectory": false},
    {"name": "logs", "size": 0, "type": "directory", "isDirectory": true}
  ],
  "count": 2
}

GET /fs/download?path=xxx: バイナリファイルとしてダウンロード

GET http://localhost:3000/fs/download?path=/data/user/0/com.h1.core/app_flutter/h1_core.db

Application API

|| Method | Path | Description | ||--------|------|-------------| || GET | /api/workspace | ワークスペース情報（会社ディレクトリ、DB、SSH、プラグイン） | || GET | /api/commands | DebugConsole登録コマンド一覧 | || GET | /api/db/tables | DBテーブル一覧とレコード数 | || GET | /api/preferences?key=xxx | SharedPreferences取得（key省略で全取得） | || GET | /api/theme | テーマカラー情報 | || GET | /api/projects | プロジェクト一覧 | || POST | /api/projects | プロジェクト更新（gantt_config等） | || POST | /api/projects?action=create | プロジェクト新規作成 |

GET /api/workspace: ワークスペース情報

{
  "company_dir": "/data/user/0/.../company",
  "db_path": "/data/user/0/.../h1_core.db",
  "db_exists": true,
  "db_size_bytes": 524288,
  "ssh_dir": "/data/user/0/.../company/.ssh",
  "ssh_config_exists": true,
  "ssh_private_key_exists": true,
  "ssh_public_key_exists": true,
  "plugins": [
    {"id": "documents", "name": "Documents", "enabled": true},
    ...
  ]
}

GET /api/db/tables: DBテーブル一覧

{
  "tables": [
    {"table": "documents", "count": 150},
    {"table": "projects", "count": 25},
    ...
  ],
  "count": 10
}

GET /api/projects: プロジェクト一覧

{
  "count": 25,
  "cardColorLight": "#FFFFFFFF",
  "projects": [
    {
      "id": "xxx",
      "name": "案件A",
      "status": "active",
      "customer_name": "顧客X",
      "type": "sales",
      "pipeline_stage": "見積",
      "progress": 50,
      "total_amount": 1000000,
      "start_date": "2024-01-01",
      "end_date": "2024-03-31",
      "contract_months": 3,
      "cardColor": "#FFFFFFFF",
      "isLost": false
    },
    ...
  ]
}

POST /api/projects: プロジェクト更新（gantt_config等）

{
  "project_id": "xxx",
  "gantt_config": "{\"id\":\"standard\",\"name\":\"標準フロー\",\"tasks\":[...]}"
}

Response:

{
  "updated": true,
  "project_id": "xxx",
  "gantt_config": "{...}"
}

POST /api/projects?action=create: プロジェクト新規作成

{
  "name": "販売アシスト1号開発",
  "gantt_preset": "software_development",
  "start_date": "2024-06-21",
  "contract_months": 6
}

Response:

{
  "created": true,
  "project_id": "xxx",
  "name": "販売アシスト1号開発",
  "gantt_preset": "software_development"
}

Security Notes

• loopbackIPv4にバインド（外部から直接アクセス不可）
• SSHトンネル経由で外部公開
• /fs/writeは開発用、本番での使用を想定していない
• DBクエリはSELECT/PRAGMAのみ許可

CLI Usage Examples

# Health check
curl http://localhost:3000/health

# Get full state dump
curl http://localhost:3000/state | jq .

# Get application error logs
curl http://localhost:3000/api/errors | jq .

# Clear application error logs
curl -X DELETE http://localhost:3000/api/errors

# List app directory
curl "http://localhost:3000/fs/list?path=/data/user/0/com.h1.core/app_flutter" | jq .

# Query database
curl -X POST http://localhost:3000/db/query \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT count(*) FROM invoices"}' | jq .

# Execute debug command
curl -X POST http://localhost:3000/command \
  -H "Content-Type: application/json" \
  -d '{"command": "documents.stats", "args": []}' | jq .

# Read a file
curl "http://localhost:3000/fs/read?path=/data/user/0/com.h1.core/app_flutter/config.json" | jq .

# Get workspace info
curl http://localhost:3000/api/workspace | jq .

# Get projects
curl http://localhost:3000/api/projects | jq .

# Update project gantt config (using file for complex JSON)
cat > /tmp/gantt.json << 'EOF'
{
  "project_id": "xxx",
  "gantt_config": "{\"id\":\"standard\",\"name\":\"標準フロー\",\"tasks\":[{\"id\":\"estimation\",\"label\":\"見積\",\"documentType\":\"estimation\",\"isCustom\":false},{\"id\":\"order\",\"label\":\"受注\",\"documentType\":\"order\",\"isCustom\":false},{\"id\":\"delivery\",\"label\":\"納品\",\"documentType\":\"delivery\",\"isCustom\":false},{\"id\":\"invoice\",\"label\":\"請求\",\"documentType\":\"invoice\",\"isCustom\":false}]}"
}
EOF
curl -X POST http://localhost:3000/api/projects \
  -H "Content-Type: application/json" \
  -d @/tmp/gantt.json | jq .

# Create software development project
curl -X POST "http://localhost:3000/api/projects?action=create" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "販売アシスト1号開発",
    "gantt_preset": "software_development",
    "start_date": "2024-06-21",
    "contract_months": 6
  }' | jq .

# Check for errors after update
curl http://localhost:3000/api/errors | jq .