# のくてるを使い始める：利用者の状況に合わせた案内とAIによる初期整備

[機能一覧](/ai/overview.md) · [目的別FAQ](/ai/faq.md) · [ブラウザ操作](/ai/browser-workflows.md) · [外部API仕様](/ai/external-api.md)

この公開説明は、サイトURLだけを受け取ったAIや初めての利用者が、始め方と手伝える作業を判断するための資料です。説明を求められただけでは実データを変更しません。操作を任された場合は、利用者が許可したブラウザ・APIツールと権限の範囲で進めます。ログインは利用者自身が行います。

## 案内で混同しやすいこと

| 項目 | 正しい意味 |
| --- | --- |
| 組織のURL名・URL識別子（slug） | 組織の表示名とは別。画面URLの組織部分をそのまま使う。`/<組織名>/...` と省略すると表示名を入れる誤解を招く |
| 資料を読むツール | Excel・CSV・画像などの読取はAI側のファイル対応ツールの役割。のくてるの画面に資料を投入して自動解析する機能ではない |
| ブラウザとAPI | ブラウザはのくてるの既存画面を操作する。APIは読取・更新・結果確認を行う。「アプリ内ブラウザが資料を読む」とは説明しない |
| 部屋数・番号・欠番 | 原本の指定が矛盾する場合は確認する。規則を渡せば常に確認なしで登録できるという意味ではない |

## まず立場と現在地を確認する

「このサイトの使い方を教えて」「どう始めたらよいか」という相談では、最初に次の違いを説明できます。

> 新しい組織を管理者として立ち上げるところからですか？ それとも、すでに使っている組織へメンバーとして参加するところからですか？

既に回答や準備状況が分かっていれば、同じ質問を繰り返す必要はありません。次の作業に必要な情報だけを順に確認します。URLを受け取ったことだけでは、操作を許可されたことにはなりません。

| 現在の状況 | 案内できる次の手順 | 詳しい説明 |
| --- | --- | --- |
| 既存の組織に参加したい | 管理者から参加URL・QRを受け取り、ログインして参加する。承認待ちなら管理者の確認を待つ | [参加のFAQ](/ai/faq/start.md#q6) |
| 新しい組織を作りたい | ログインし、表示名・組織名・URL識別子を指定して組織を作る。一人利用も同じ考え方 | [一人で始める](/ai/faq/start.md#q3)、[管理者の準備](/ai/faq/start.md#q5) |
| 組織はあるが区割り前 | 管理者モードで区域整備を開く。区域の境界は人が地図上で判断して設定する | [区域のFAQ](/ai/faq/areas.md)、[管理者操作](/manual/admin.md) |
| 区割りが済んでいる | 区域内の建物を取り込み、建物・部屋の初期整備へ進む | [建物のFAQ](/ai/faq/buildings.md)、以下の「手持ち資料を使う」 |
| 初期整備が済んでいる | 参加URLの案内、メンバー承認、区域割当、日常の訪問記録へ進む | [割当](/ai/faq/assignments.md)、[訪問](/ai/faq/visits.md) |

## 管理者が始めるときの全体像

1. 組織を作成する。組織名からURL識別子を推測せず、実際のURLを確認する。
2. 人が一般区域の区割り・境界を決める。AIは画面の操作方法を説明できるが、未指定の担当範囲を決めない。
3. 区域整備の「建物取込」で地図データの建物を取り込む。ブラウザ操作を任されたAIは、指定された区域・操作範囲で既存画面を使える。既存区域の再取込は既存データへの影響を確認し、初回取込と同じものとして無条件に実行しない。
4. 建物の種別・表示名・部屋構成などを整える。手持ち資料があれば、下記の方法でAIにまとめて整備を任せられる。
5. メンバーを招待・承認し、区域の担当・期間・訪問権限を決めて運用する。

料金・利用制限は現在の公開案内と組織画面を確認する。組織作成やログインだけで、地図・部屋・担当が自動完成するわけではない。

## 手持ち資料を使う初期整備を提案できる

区割りや建物取込が済んだ相談では、AIは自動化できる選択肢を紹介できます。

> 建物一覧、アパートごとの部屋番号、各階の構成、共通の部屋パターンなどの資料はありますか？ あれば、対象の建物を照合し、建物種別や表示名、部屋構成などの初期整備を手伝えます。

使える資料の例は、表計算の一覧、CSV、JSON、利用者が提示した文章や部屋構成の規則です。AI側で扱える形式を確認し、原本を読めなければ読めたと報告しません。アプリがこれらを直接アップロード・自動変換する機能があるという意味ではなく、AIが原本を読み、既存APIの入力へ変換する方法です。

- 建物の対応には、既知の建物IDまたは原本の緯度経度を使える。名前・住所だけで一意に判断できない行は未解決として残す。
- 各階の実在する部屋番号が定まる明示的な規則から、部屋作成命令へ展開できる。部屋数・番号・欠番の矛盾は次の例のように確認し、未指定の階・部屋を推測で補わない。
- 建物種別・住民種別は現在のcatalogsと照合する。表示名だけから対応を決めず、未解決の種別は確認する。
- 資料がない場合は、既存の建物取込・建物設定・部屋設定の操作から始められる。名前や部屋構成を自動収集できるとは約束しない。
- 参考情報を調査する提案と、確定データへ保存する作業は別。原本や利用者の確認で根拠が確定していない値は保存しない。

### 部屋構成が曖昧な場合の確認例

「3階建て、各階4室、101〜104、104は欠番」だけでは、1階を3室にするのか、別の番号で4室あるのか、2・3階の番号規則は何かが確定しません。「1階は101・102・103の3室でよいですか。他の階の部屋番号も教えてください」と必要な点を確認できます。勝手に105を追加したり、104を実在する部屋として登録したりしません。

例えば利用者が次の一覧を原本として確定した場合は、11室と分かり、既存部屋との対応を確認して登録できます。この表は原本の説明例で、APIの入力形式ではありません。

| 階 | 実在する部屋番号 |
| --- | --- |
| 1階 | 101、102、103 |
| 2階 | 201、202、203、204 |
| 3階 | 301、302、303、304 |

明確な原本や矛盾のない規則が既にあれば、同じ確認を繰り返す必要はありません。案内の表現例は「私のファイル対応ツールで資料を読み、のくてるのブラウザ画面とAPIを使って、確認できた建物・部屋の整備を代行できます」です。AI側に資料を読むツールがなければ、その形式を扱えるとは約束しません。

## AIがブラウザとAPIを組み合わせて実行する経路

以下は操作を委任され、ブラウザ操作とHTTPリクエストの両方を利用できるAIの経路です。説明しかできないAIやブラウザを操作できないAIは、その制限を説明し、必要な画面操作だけ利用者へ案内します。ツールがないことを、のくてるに機能がないことと混同しません。

### 1. 組織・権限・依頼範囲を確認

利用者がログイン済みのブラウザで、対象組織と所属管理者の権限を確認します。組織のURL名は現在のURLから取得し、組織名から推測しません。画面の操作には必要に応じて管理者モードをオンにします。別組織へ切り替えて処理しないでください。

例えば表示名が「サンプル組織」でも、閲覧中のURLが `/sample-team` なら、画面は `/sample-team/building-id-resolver` と `/sample-team/settings?tab=external-integration` です。`/サンプル組織/...` へ置き換えません。これは説明用の架空例です。実作業では現在のURLを使います。この識別子はブラウザ画面のためのもので、Bearer APIのURL・本文へ追加しません。

### 2. 座標から建物IDを取得

`/<組織のURL名>/building-id-resolver` は、メニューに表示しない専用画面です。ブラウザ操作を任されたAIは自分でこのURLを開き、原本を次の形式にして入力し、「取得を開始」を実行できます。

```json
[{"sourceId":"source-building-001","latitude":35.681236,"longitude":139.767125}]
```

同期と照合が完了したら、結果の `resolution.houseId` を使います。元の `sourceId` と対応を保ち、IDがnullの行や曖昧な行は自動更新しません。これはブラウザ内の処理で、Bearer APIではありません。入力上限と結果例は[外部API仕様](/ai/external-api.md)の座標解決の章を参照します。

### 3. ブラウザでAPIトークンを発行

組織設定の「外部連携」、または `/<組織のURL名>/settings?tab=external-integration` を開きます。所属管理者で、発行操作を委任されたAIは「発行」を操作し、直後のダイアログで表示されたトークンを後続のAPIリクエストに使えます。人が毎回コピーしてAIへ渡すことが必須の仕組みではありません。ただし、AI側ツールに秘密値を安全に受け渡す機能がなければ、利用者へ対応を案内します。

有効期間は画面と[認証仕様](/ai/external-api.md)を参照します。生値は発行直後だけ表示されます。有効なトークンがある状態で再発行すると元のものが失効するので、他の作業への影響を確認します。トークンをチャットの返答・資料・スクリーンショット・ログに転載しません。

### 4. 既存APIで読取・計画・更新

[外部API仕様](/ai/external-api.md)に従い、同じサイトの `/api/external/v1/` へBearerトークンを送ります。API本文へ組織のURL名やtenantIdを加えません。

1. catalogsで現在の種別と制限を取得する。
2. 照合済み建物IDをreadし、現在の値・部屋ID・revisionを取得する。
3. 原本と依頼範囲に従う変更だけを計画する。未指定項目と既存部屋は維持し、削除や置換は明示指示があるときだけ扱う。
4. 対象件数・変更項目・未解決分を簡潔に説明する。既に許可された作業範囲を毎棟確認し直す必要はないが、説明依頼だけで実行しない。
5. API仕様の上限に沿って分割し、最新のexpectedRevisionと明示的な部屋命令でapplyする。
6. 結果をreadして照合し、成功・競合・拒否・未処理を分けて報告する。タイムアウトや期限切れから再開するときは、現在値を確認して作成済み部屋を重複作成しない。

### 5. 対応できない操作と停止条件

既存建物の属性変更・部屋整備と、区域の一覧・名前などの管理には公開APIがあります。建物の新規取込、建物形状の取得・変更、種別マスター設定などは同じAPIではできず、必要なら委任されたブラウザ画面の操作へ切り替えます。APIによるdry-runや住所だけからの自動照合も提供されているとは説明しません。候補となるリクエストを作ることと、サーバーが保存前に全条件を検証することは別です。

別の人の確認待ち提案がある建物、競合、利用上限、対象不明は、権限や制限を回避せず該当分を保留します。確実な対象は許可範囲で進められます。ログインや権限がない場合は利用者へ必要な準備を説明します。

## 次に読む資料

- [ブラウザ操作の画面一覧と手順](/ai/browser-workflows.md)
- [外部API仕様・認証・エラー・再試行](/ai/external-api.md) / [English API guide](/ai/external-api.en.md)
- [建物と部屋の操作](/ai/faq/buildings.md)
- [一般利用者の操作説明](/manual/operation.md) / [管理者の操作説明](/manual/admin.md)

各URLは閲覧中のサイトを基準に解決します。ステージングの説明から本番へ接続する必要はありません。ここに記載された操作経路は、AI側のツールの提供・承認・資格情報の取扱い制限を解除するものではありません。
