ユーザー向けガイドの整備

README.ja.md

@@ -29,6 +29,10 @@
 <!-- TODO: 配置エディタとビュアーのスクリーンショット -->
 <div align="center"><img src="docs/images/haizu_demo.gif" width="800"></div>
 
+## 主な機能
+
+**→ [操作マニュアル](docs/guide/index.ja.md)** — 画面ごとの使い方を手順で説明しています。
+
 ## はじめかた
 
 Node.js 24.18 以上（[`.nvmrc`](.nvmrc) 参照）、pnpm 10 以上、Docker が必要です。
@@ -81,6 +85,7 @@ http://localhost:3000 を開き、サインアップから会社（組織）を
 
 | | |
 |---|---|
+| [docs/guide/](docs/guide/index.ja.md) | 操作マニュアル。画面ごとの機能と操作手順 *(日本語・英語)* |
 | [docs/architecture.ja.md](docs/architecture.ja.md) | 知らずに触ると壊す設計判断 |
 | [docs/domain/](docs/domain/) | ドメイン知識。概念ごとに1ファイル |
 | [CONTRIBUTING.ja.md](CONTRIBUTING.ja.md) | 開発コマンド・規約・PR の出し方 |

README.md

@@ -30,6 +30,10 @@ On a factory or warehouse floor, someone decides every day which worker stands a
 
 <div align="center"><img src="docs/images/haizu_demo.gif" width="800"></div>
 
+## Features
+
+**→ [User guide](docs/guide/index.md)** — how to use each screen, step by step.
+
 ## Getting started
 
 You need Node.js 24.18+ (see [`.nvmrc`](.nvmrc)), pnpm 10+, and Docker.
@@ -82,6 +86,7 @@ Set them in `apps/web/.env` (copied from `apps/web/.env.example`). There is no p
 
 | | |
 |---|---|
+| [docs/guide/](docs/guide/index.md) | User guide: what each screen does and how to operate it *(English + Japanese)* |
 | [docs/architecture.md](docs/architecture.md) | Design decisions you will break if you don't know them |
 | [docs/domain/](docs/domain/) | Domain knowledge, one file per concept *(English + Japanese)* |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | Development commands, conventions, and how to open a PR |

docs/guide/assignment.ja.md

@@ -0,0 +1,69 @@
+# 配置決め
+
+日々の運用の中心です。「この日・このシフトで、誰をどこに立たせるか」を決めます。
+
+[English](assignment.md) · [マニュアル目次に戻る](index.ja.md)
+
+## できること
+
+- **日付** と **シフト**、そしてエリアを選ぶ
+- 未配置リストから従業員をスポットへドラッグ（またはタップ）で配置する
+- 未配置リストを **名前** や **タグ** で絞り込む
+- **下書き保存** する、または **確定する** で現場に公開する
+- 確定済みの配置を **更新する** / **下書きに戻す**
+
+この画面の背後にあるルール： [docs/domain/assignment.md](../domain/assignment.md)
+
+## 配置決めの前提
+
+前提は2つあり、足りない場合は画面が教えてくれます。
+
+| 表示されるメッセージ | 対処 |
+|---|---|
+| *勤務体制（シフト）が未登録です* | [設定](settings.ja.md#働き方シフト設定)でシフトを登録する |
+| *この日付に適用される規格がありません* | [配置エディタ](editor.ja.md)で、適用開始日をその日以前にして規格を公開する |
+
+つまずきやすいのは2つ目です。規格が**下書き**のままのエリアは配置決めできません。公開して初めてここに現れます。
+
+## 操作手順
+
+1. 配置決め一覧で日付とシフトを選びます。エリアごとに配置状況と規格バージョンが表示されます。**配置する →** を押します。
+
+<div align="center"><img src="../images/guide/assignment/list-ja.png" width="800"></div>
+
+2. 左の **未配置の従業員** に、まだ配置されていない有効な従業員が並びます。**名前で検索** や **タグで絞り込み** で絞れます。
+
+<div align="center"><img src="../images/guide/assignment/initial-ja.png" width="800"></div>
+
+3. 配置します。
+   - 従業員をスポットへ **ドラッグ** する、または
+   - 従業員を **タップ** してからスポットをタップする
+
+<div align="center"><img src="../images/guide/assignment/assign-ja.png" width="800"></div>
+
+4. 解除するには、スポットをタップして **配置を解除** を選ぶか、未配置リストへドラッグして戻します。
+5. 途中でやめるときは **下書き保存**。確定してよければ **確定する** を押します。確認ダイアログに日付・シフト・エリア・配置人数が表示されます。
+
+<div align="center"><img src="../images/guide/assignment/fixed-ja.png" width="800"></div>
+
+ヘッダーには進捗（*配置済み 12 / 20*）と使用中の規格バージョンが表示されます。
+
+## 下書きと確定の違い
+
+| 状態 | ビュアーに表示 | ホームでの表示 |
+|---|---|---|
+| 下書き | されない | *下書きあり* |
+| 確定済み | **される** | 配置済み |
+
+現場に配置を見せるのは「確定」の操作です。確定するまでは自分にしか見えていません。
+
+確定すると **確定済み** バッジが付きます。その後も **更新する**（編集して再確定）や、**下書きに戻す**（ビュアーから取り下げる）ができます。
+
+<div align="center"><img src="../images/guide/assignment/fixed-budge-ja.png" width="800"></div>
+
+## 注意点
+
+- 未配置リストに出るのは **有効** な従業員だけです。[従業員](employees.ja.md)画面で無効にすると候補に出なくなります。
+- 1スポットに配置できるのは1人だけです。
+- 後から[シフト設定](settings.ja.md#働き方シフト設定)を変更すると、変更・削除したシフトで作成中の**下書き**は、設定を保存した時点で破棄されます。確定済みの配置は破棄されません。代わりに、影響を受けた日の配置決め画面に注意書きが表示され、当時確定した内容を保持している[配置履歴](history.ja.md)へ誘導されます。
+- 配置決めを作成・編集できるのは **管理者** と **拠点管理者** だけです。

docs/guide/assignment.md

@@ -0,0 +1,69 @@
+# Assignment
+
+The daily loop: for this date and this shift, who stands where.
+
+[日本語](assignment.ja.md) · [Back to guide index](index.md)
+
+## What you can do
+
+- Pick a **date** and a **shift**, then an area
+- Drag (or tap) employees from the unplaced list onto spots
+- Filter the unplaced list by **name** or by **tag**
+- Save as a **draft**, or **Confirm** to publish it to the floor
+- **Revert to draft** / **Update** a placement you already confirmed
+
+The rules behind this screen: [docs/domain/assignment.md](../domain/assignment.md).
+
+## Before you can assign
+
+Two prerequisites, and the screen tells you which one is missing:
+
+| Message | What to do |
+|---|---|
+| *Work system (shifts) not registered* | Register shifts in [settings](settings.md#shifts) |
+| *No spec applies to this date* | Publish a spec in the [layout editor](editor.md) with an effective date on or before this date |
+
+The second one catches people out: an area with a *draft* spec is not assignable. Publishing is what makes it appear here.
+
+## Steps
+
+1. On the assignment list, choose the date and shift. Each area shows its placement status and spec version. Press **Assign →**.
+
+<div align="center"><img src="../images/guide/assignment/list.png" width="800"></div>
+
+2. On the left, **Unplaced employees** lists everyone active who isn't placed yet. Narrow it with **Search by name** or **Filter by tag**.
+
+<div align="center"><img src="../images/guide/assignment/initial.png" width="800"></div>
+
+3. Place people:
+   - **Drag** an employee onto a spot, or
+   - **Tap** the employee, then tap the spot.
+
+<div align="center"><img src="../images/guide/assignment/assign.png" width="800"></div>
+
+4. To undo one: tap the spot and choose **Unassign**, or drag the person back onto the unplaced list.
+5. **Save draft** to stop halfway. **Confirm** when the placement is final.
+
+<div align="center"><img src="../images/guide/assignment/fixed.png" width="800"></div>
+
+The header shows progress (*Placed 12 / 20*) and which spec version is in use.
+
+## Draft vs confirmed
+
+| State | Visible in the viewer | Shown on Home as |
+|---|---|---|
+| Draft | No | *Has draft* |
+| Confirmed | **Yes** | placed |
+
+Confirming is the step that shows the placement to the floor. Until then it's yours alone.
+
+After confirming, the placement is marked **Confirmed**. You can still **Update** it (edit and re-confirm), or **Revert to draft** to pull it back off the viewer.
+
+<div align="center"><img src="../images/guide/assignment/fixed-budge.png" width="800"></div>
+
+## Notes
+
+- Only **active** employees appear in the unplaced list. Deactivate someone in [Employees](employees.md) and they stop being offered.
+- Each spot holds exactly one person.
+- If you change [shift settings](settings.md#shifts) later, drafts in progress for the changed or deleted shifts are discarded when you save the settings. Confirmed placements are not touched — instead, the assignment screen for an affected day shows a notice pointing you at the [history](history.md), which preserves what was actually confirmed at the time.
+- Only **Admin** and **Site Admin** can create or edit assignments.

docs/guide/editor.ja.md

@@ -0,0 +1,94 @@
+# 配置エリア（配置エディタ）
+
+フロアを描く画面です。図面画像と、人が立つスポットを定義します。配置や図面の変更はバージョンで管理します。
+
+[English](editor.md) · [マニュアル目次に戻る](index.ja.md)
+
+## できること
+
+- **配置エリア** を作成する（拠点内の作業エリア1つ。「検収室」「ラインA」など）
+- **図面** 画像をアップロードし、サイズを調整する
+- **配置スポット** を置く。1スポット＝1人が立つ位置
+- **下書き保存** し、**適用開始日** を指定してバージョンとして **公開** する
+- 後日レイアウトが変わったら、過去の配置決めを壊さずに **新しいバージョン** を作る
+
+用語の定義は [docs/domain/layout_spec.md](../domain/layout_spec.md) にあります。
+
+## 操作手順
+
+### エリアを作る
+
+1. **＋ エリアを追加** で **エリア名** を入力し、**追加する**。
+
+<div align="center"><img src="../images/guide/editor/add-area-ja.png" width="800"></div>
+
+2. エリア一覧には、図面の有無（**図面あり** / **図面なし**）、規格の状態（**公開中** / **下書き**）、スポット数が表示されます。
+
+<div align="center"><img src="../images/guide/editor/list-ja.png" width="800"></div>
+
+### 図面をアップロードする
+
+エリアを開き、右のパネルで操作します。
+
+1. **図面** の **画像をアップロード** から画像を選びます。
+2. 必要なら **サイズ** を調整します。**画像を変更** で差し替え、**図面を削除** で取り除けます。
+
+図面は任意で、なくてもスポットは置けます。ただしモニター上で配置を読み取りやすくするために、アップロードすることを推奨します。
+
+<div align="center"><img src="../images/guide/editor/empty-floor-image-ja.png" width="800"></div>
+<div align="center"><img src="../images/guide/editor/floor-image-ja.png" width="800"></div>
+
+### スポットを置く
+
+1. **＋ 配置スポット** でスポットを追加します。
+2. ドラッグで位置を調整します。右下のハンドルをドラッグするか、パネルの **大きさ** でサイズを変更できます。
+3. パネルの **配置スポットの設定** で **ラベル** を付けます。現場はこのラベルで位置を識別します。
+4. **スポットを削除** で削除できます。
+
+<div align="center"><img src="../images/guide/editor/spot-ja.png" width="800"></div>
+
+1エリアあたり **最大100スポット** です。
+
+### 公開する
+
+1. **下書き保存** は、公開せずに作業内容を保存します。保存していない変更は残りません。
+2. **この規格を公開** でダイアログが開きます。**適用開始日**（必須）を設定し、**公開する** を押します。
+
+<div align="center"><img src="../images/guide/editor/publish-ja.png" width="800"></div>
+
+<div align="center"><img src="../images/guide/editor/draft-save-ja.png" width="800"></div>
+
+**配置決めとビュアーが使うのは公開済みバージョンだけです。** ある日付に対しては「適用開始日がその日以前で、最も新しい公開済みバージョン」が使われます。したがって、どれだけ作り込んでも下書きのままではこれらの画面から見えません。
+
+**公開を取り消す** と公開済みバージョンを下書きに戻せますが、これは配置決めでまだ使われていない場合に限ります。
+
+## バージョン：使用中のレイアウトを変更する
+
+一度でも配置決めに使われたバージョンは凍結され、編集・削除・公開取り消しができなくなります。これは意図的な仕様で、過去の配置決め（と[配置履歴](history.ja.md)）を正しく保つためです。
+
+そうしたレイアウトを変更するには次のようにします。
+
+1. **＋ 現在を複製して新バージョン** で、現在の規格を新しいバージョンに複製します。
+2. スポットを編集します。
+3. 新しいレイアウトを適用したい日を **適用開始日** として公開します。
+
+適用開始日より前の日付は引き続き古いバージョンを参照し、その日以降が新しいバージョンになります。
+
+注意点が2つあります。
+
+- 複製した時点ではバージョンは**まだ作られません**。編集後に **保存または公開** して初めて新バージョンとして記録されます。保存せずに離れると何も残りません。
+- **最新でない**バージョンを公開しても、配置決め・ビュアーには反映されません（エディタが警告します）。解決ルールが「その日以前で最も新しい公開済みバージョン」を選ぶため、古いバージョンが勝つことはありません。使用中の内容を変えたい場合は、新しいバージョンを作ってください。
+
+<div align="center"><img src="../images/guide/editor/new-version-ja.png" width="800"></div>
+
+## エリアを削除する
+
+**エリアを削除** すると、図面・全バージョン・全スポットが削除され、元に戻せません。
+
+そのエリアのバージョンが**1つでも**配置決めで使われている場合、エリアは削除できません（ボタンにその旨が表示されます）。使われていない個別バージョンだけを削除することもできません。ただし未公開の下書きは無害なので、そのまま放置して構いません。
+
+## 注意点
+
+- **保存しない限り変更は反映されません。** キャンバス上の状態は作業中のコピーです。
+- 2人が同時に編集した場合は、後から保存した内容で上書きされます。
+- 編集できるのは **管理者** と **拠点管理者** だけです。

docs/guide/editor.md

@@ -0,0 +1,93 @@
+# Layout areas (the placement editor)
+
+Where you draw the floor: a plan image, and the spots people stand on. You do this once per area, then only rarely again.
+
+[日本語](editor.ja.md) · [Back to guide index](index.md)
+
+## What you can do
+
+- Create **placement areas** (one work area within the site: "Inspection room", "Line A", …)
+- Upload a **floor plan** image and size it
+- Place **placement spots** — one spot is one position for one person
+- Save a **draft**, then **publish** it as a version with an **effective date**
+- Create a **new version** later, when the layout changes, without disturbing past assignments
+
+The vocabulary is defined in [docs/domain/layout_spec.md](../domain/layout_spec.md).
+
+## Steps
+
+### Create an area
+
+1. **＋ Add area**, enter an **Area name** (e.g. "Loading dock"), then **Add**.
+
+<div align="center"><img src="../images/guide/editor/add-area.png" width="800"></div>
+
+2. The area list shows each area's plan status (**Has plan** / **No plan**), spec status (**Published** / **Draft**), and spot count.
+
+<div align="center"><img src="../images/guide/editor/list.png" width="800"></div>
+
+### Upload a floor plan
+
+In the area, open the right-hand panel:
+
+1. **Upload image** under **Floor plan**, and pick the image.
+2. Adjust **Size** if needed. **Change image** replaces it, **Delete floor plan** removes it.
+
+The floor plan is optional — you can place spots without one — but it's what makes the placement legible on the monitor.
+
+<div align="center"><img src="../images/guide/editor/empty-floor-image.png" width="800"></div>
+<div align="center"><img src="../images/guide/editor/floor-image.png" width="800"></div>
+
+### Place spots
+
+1. **＋ Placement spot** adds a spot.
+2. Drag it into position. Drag the handle at its bottom-right to resize, or set **Size** in the panel.
+3. Give it a **Label** (the panel's **Placement spot settings**). The label is how the floor identifies the position.
+4. **Delete spot** removes it.
+
+Up to **100 spots** per area.
+
+<div align="center"><img src="../images/guide/editor/spot.png" width="800"></div>
+
+### Publish
+
+1. **Save draft** keeps your work without publishing. Nothing you haven't saved is kept.
+2. **Publish this spec** opens a dialog. Set the **Effective date** (required), then **Publish**.
+
+<div align="center"><img src="../images/guide/editor/publish.png" width="800"></div>
+<div align="center"><img src="../images/guide/editor/draft-save.png" width="800"></div>
+
+**Assignment and the viewer only use published versions.** For a given date they use the newest published version whose effective date is on or before that date. So a draft, however complete, is invisible to them.
+
+**Unpublish** reverts a published version to draft — but only if no assignment uses it yet.
+
+## Versions: changing a layout that's already in use
+
+Once a version has been used in an assignment, it is frozen: it can't be edited, deleted, or unpublished. This is deliberate — it's what keeps past assignments (and [history](history.md)) truthful.
+
+To change such a layout:
+
+1. **＋ Duplicate current as new version** — this copies the current spec into a new version.
+2. Edit the spots.
+3. Publish it with an **effective date** from which the new layout applies.
+
+Dates before that effective date keep resolving to the old version. Dates on or after it get the new one.
+
+Two things surprise people here:
+
+- Duplicating does **not** create the version immediately. The new version is only recorded once you **save or publish** after editing. Leave without saving and nothing remains.
+- Publishing a version that is **not the latest** has no effect on assignment or the viewer — the editor warns you about this. Resolution picks the *newest* published version on or before the date, so an older one never wins. If you want to change what's in use, create a new version.
+
+<div align="center"><img src="../images/guide/editor/new-version.png" width="800"></div>
+
+## Deleting an area
+
+**Delete area** removes the floor plan, every version, and every spot, irreversibly.
+
+If **any** version of the area has ever been used in an assignment, the area can't be deleted (the button says so). Individual unused versions can't be deleted either — but an unpublished draft is harmless, so you can simply leave it.
+
+## Notes
+
+- **Changes aren't reflected unless you save.** The canvas is a working copy.
+- On concurrent edits by two people, last write wins.
+- Only **Admin** and **Site Admin** can edit. General users can only view; "other" can't open the screen at all.