宿泊イベント用自動部屋割りツール Osuwariマニュアル 日本語訳風

# はじめに
Osuwariは，宿泊を伴うイベントの部屋割り担当者の作業にかかる労力を軽減するために開発したツールです。
このツールは宿泊するイベント参加者の部屋を自動で割り当てる機能を持っています。
このツールはもともと，SWEST（Summer Workshop on Embedded System Technologies)の参加者の部屋割り用ツールとして作成された経緯を持っています。
このツールの主目的は，臨時追加やキャンセル，条件変更といった要望（これらの要請は，どういう訳か部屋割り確定直前に増大する有意な傾向が観測されている）の調整時に割当漏れや二重割当といったミスが混入しないようにすることです。副次的には，部屋割り担当者による思惑（特定参加者への優遇，ゴマすり行為，依怙贔屓，陰謀，策謀，不順な感情の表出など）を排除することです。これにより参加者の公平性の向上をもたらすことでしょう。

Osuwariは犬への命令の言葉で"сидеть"（英語では"Sit")を意味する日本語です。
ツールとは，ほとんど何の関係もありませんが，筆者は柴犬と呼ばれる日本原産の犬種が大好きです。(https://ru.wikipedia.org/wiki/%D0%A1%D0%B8%D0%B1%D0%B0-%D0%B8%D0%BD%D1%83)
（訳注：ツールの機能と名前には特に関連は無いようです，強いて言うなら"部屋割り"と"おすわり"の語彙の末尾が同じという点）

一部の人からマニュアルが分かり辛いという指摘があったので、さらにわかり辛くしました。:smile: 
下手な日本語訳風な文章になっているのはわざとです。

SWESTについてはこちらを御覧ください。

https://swest.toppers.jp/

# コードの保存場所

https://github.com/Grandge/Osuwari

# おさらい
あなたが，このツールの内容について学ぶ前によく使う用語をおさらいしておこうと思う。
（筆者も含めて）少なくない数の人々が，どちらが行(Row)でどちらが列(Column)なのか分からなくなる事があるので，その確認です。
![rowcolumn.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/58419/c62aeeb8-5e92-08c5-4b6e-3619a4ae0fac.gif)
![namelist.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/58419/c875491c-f380-a5a7-4c17-c1fda2db159f.gif)

# 使い方
複数のファイルを持ち込むか用意する必要があります。
## 共通項目
### ファイル形式
Osuwariで使用するファイルはエンコードがUTF-8のcsv形式のファイルである必要があります。
### 固定項目（行）
１行目はIDとみなされます。
IDは数値ではなくても良い（文字列扱い）ですが，ユニークである必要があります。

## 名簿ファイル
参加者の一覧用のファイルです。
最低限参加者を一位に識別するIDと，参加者名の列が必要です。
### 固定項目（列）
１列目はIDとみなされます。（見出しは何であっても良い，ツールは見出し名を使用しない）
### 可変項目（列）
見出し名の先頭が*(半角アスタリスク）である場合，レイアウトの際に出力項目となります。
（下記のサンプルファイルでは，参加者の氏名（性）列と氏名（名）列を出力する設定となっています）
また，見出し行がグループファイルで定義したグループ名と同じ列はグループ所属設定列とみなします。（グループについては後述）
![namelist.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/58419/c875491c-f380-a5a7-4c17-c1fda2db159f.gif)


## 区画定義ファイル
区画定義ファイルは，割当可能な宿泊施設の部屋と割当結果出力の際の位置を定義します。
### 固定項目（行）
名称，人数，優先グループ，X,Yの行は固定項目で変更はできません。
固定項目以外の行にツール利用者のメモや追加の情報があっても良い，ツールはこれらの行を無視する。
![compartment.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/58419/c1127fc7-335f-3fd3-8363-392dad37058f.gif)
### 項目について
- 名称：名簿のIDと同様にユニークである必要がある
- 人数：区画に割り当て可能な最大人数，数値(半角)である必要がある
- 優先グループ：優先的に割り当てるグループの名称（グループの名称はグループ定義ファイルで定義されたものを使用する）
優先グループは，そのグループが割り当てられる際に優先的に割り当てるだけで，他のグループのメンバーの割当を排他するものではありません。完全に排他したい場合は，優先グループのグループを排他属性にし，優先度を高くして先に割当を済ましてしまい，他のグループの番のときには，その排他グループメンバーがすでに使用している状態にします。（排他グループのメンバーがいると，他のグループのメンバーを割り当てることが出来ない）
- X：割当結果出力の際の出力起点のX座標（開始行）
- Y：割当結果出力の際の出力起点のY座標（開始列）


## グループ定義ファイル
### 固定項目（行）
名称，排他，集合，分散，除外，優先度の行は固定項目で変更はできません。
固定項目以外の行にツール利用者のメモや追加の情報があっても良い，ツールはこれらの行を無視する。
![group.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/58419/db142f59-6606-9305-3be9-ce6308219570.gif)
### 項目について
- 名称：名簿のIDと同様にユニークである必要がある
- 排他，集合，分散，除外はグループ属性です。TRUEの時グループの属性として有効とみなします。
- 排他：他のグループのメンバーと同室にならないように割り当てようとします
- 集合：同じグループのメンバーが同室になるように割り当てようとします
- 分散：この属性のグループはなるべく別室になるように割り当てようとします
- 除外：この属性のついたグループに所属するメンバーは部屋に割当てません。（名簿には乗っているがキャンセルや宿泊無しといった用途で使用）
- 優先度：割当を開始する優先度です，小さな数値のグループから優先的に割当を開始します。
区画定義ファイルの優先グループにグループ名称が定義されている場合，割当の際に優先的にその区画に割り当てようとします。


# 操作方法

![osuwari01.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/58419/7de45f39-b518-d0dd-8847-98aa1789c87a.gif)

## 設定ファイルの読み込み

- プロジェクトファイル：名簿ファイル，グループファイル，区画ファイル，割当結果を関連付けて保存するためのファイル。ファイルのフルパスを直接入力するか，入力ボックスをダブルクリックすることでファイル選択ダイアログからファイルを指定します。
- 名簿ファイル：名簿ファイルを指定。ファイルのフルパスを直接入力するか，入力ボックスをダブルクリックすることでファイル選択ダイアログからファイルを指定します。
- グループファイル：グループ定義ファイルを指定。ファイルのフルパスを直接入力するか，入力ボックスをダブルクリックすることでファイル選択ダイアログからファイルを指定します。
- 区画ファイル：区画定義ファイルを指定。ファイルのフルパスを直接入力するか，入力ボックスをダブルクリックすることでファイル選択ダイアログからファイルを指定します。

## 割当の実行

上記の操作で設定ファイルを全て指定したら割当を実行できます。
メニューから割当/割当の実行を選択するか、割当結果タブに移動しダブルクリックすることで割当が実行されるます。

### エラー

割当時に、何らかのエラーが発生した場合、下部にあるテキストボックスに内容が表示されます。

### 結果の保存

割当が成功したなら、メニューの 割当/レイアウトを名前つけて保存を選択することで csvファイル形式で保存することができます。