docs: ファイルの種類についての基本的なレファレンス

Changes

6 changed files (+319/-123)

• .editorconfig
  • @@ -17,6 +17,10 @@
    [*.md] # Markdown では末尾スペース 2 つが改行として扱われる。 trim_trailing_whitespace = true + # dprint の Markdown プラグインが 4 スペースしか指定できない欠陥があるため。 + # TODO: まともなフォーマッタに切り替える。 (exec ベースの何か？) + indent_style = space + indent_size = 4 # YAML は 2 スペース以外のインデントを仕様レベルで読むことができない。 [*.{yml,yaml}]
• docs/mkdocs.yml
  • @@ -39,3 +39,7 @@ slugify: !!python/object/apply:pymdownx.slugs.slugify
    kwds: case: lower - admonition + - pymdownx.superfences: + preserve_tabs: true + - pymdownx.tabbed: + alternate_style: true
• docs/src/directory_structure.md
  • @@ -34,126 +34,3 @@
    - Excel ワークブック (`.xlsx`, `.xlsm` 拡張子) - 旧 Excel ワークブック (`.xls` 拡張子) - JSON (`.json` 拡張子) - - ## ファイルの種類 - - ファイルには勤怠の記録をつける「勤怠記録」と、社員の情報をひとまとめに管理する「社員マスタ」の 2 種類があります。 - - ### 勤怠記録 - - 勤怠記録は社員の出勤や欠勤といった「勤怠区分」の日付ごとのデータです。 - - - [社員 ID](#社員-id) - - [日付](#日付) - - [勤怠区分](#勤怠区分) - - #### 社員 ID - - 社員を一意に識別する文字列です。 - 必ず必要となり、入力されていない場合はその行は無視されます。 - 社員番号などの実際の ID や、ランダムな数字 (例: `A001~A999`)、ハンドルネームなど一意性が確保される限り何を使っても問題ありません。 - - !!! warning "注意" - - Excel などのアプリケーションを使う場合、数値のみの ID を使うと自動書式といった機能の対象になってしまう場合があります。 - アルファベットを先頭につける (例: `X1`, `A25`)、名前を後ろにつける (例: `1-tanaka`) など数値として認識されない ID をつけることを推奨します。 - - #### 日付 - - この行の記録がいつのものなのかを表す日付です。 - 必ず必要となり、入力されていない場合はその行は無視されます。 - サポートされる書式は以下となります (サンプルは共通して 2025年 10月 3日) 。 - - - `YYYY-MM-DD` (`2025-10-03`) - - `YYYY/MM/DD` (`2025/10/03`) - - `YYYY/M/D` (`2025/10/3`) - - 日付は全て Yamori を実行しているコンピュータのタイムゾーンで計算されます。 - 時間を扱わないため異なるタイムゾーンで実行しても同じ結果となります。 - - #### 勤怠区分 - - 実際の勤務予定に対する実績・結果です。 - 出勤率計算式は以下となります。 - - ``` - 出勤率 = 出勤日数 / (出勤日数 + 欠勤日数) - ``` - - ##### 出勤 - - 年次有給休暇付与の際の出勤率計算時に「出勤した」とみなします。 - 以下の文字列は全て出勤として扱われます。 - - - 出勤 - - 出 - - 勤 - - ##### 欠勤 - - 年次有給休暇付与の際の出勤率計算時に「出勤していない」とみなします。 - 以下の文字列は全て欠勤として扱われます。 - - - 欠勤 - - 欠 - - ##### 公休 - - 年次有給休暇付与の際の出勤率計算に含めません。 - 以下の文字列は全て公休として扱われます。 - - - 公休 - - 公 - - 休日 - - 休 - - ##### 年次有給休暇 - - 以下の文字列は全て年次有給休暇として扱われます。 - - - 年次有給休暇 - - 年休 - - 有給休暇 - - 有休 - - 有給 - - 有 - - ##### 特別休暇 - - 法定休暇・休業や特別休暇といった「出勤した」とみなす休日です。 - 以下の文字列は全て特別休暇として扱われます。 - - - 特別休暇 - - 法定休暇 - - 法定休業 - - 特 - - #### サンプル - - | 社員 ID | 日付 | 勤怠区分 | - | ------- | ---------- | -------- | - | A01 | 2025-07-01 | 出勤 | - | A01 | 2025-07-02 | 出勤 | - | A01 | 2025-07-03 | 欠 | - | A01 | 2025-07-04 | 年休 | - | A01 | 2025-07-05 | 公休 | - | A01 | 2025-07-06 | 公休 | - | A01 | 2025-07-07 | 出 | - | ... | ... | ... | - - ### 社員マスタ - - #### 社員 ID - - 社員を一意に識別する文字列です。 - 勤怠記録とマスタデータを紐づけるために必要となります。 - - 詳細は[勤怠区分の説明](#社員-id)を参照してください。 - - #### 名前 - - 社員の表示名です。未指定の場合は社員 ID がそのまま表示されます。 - - #### 年次有給休暇初回付与日 - - 書式は[日付](#日付)と同様です。
• docs/src/サポートされるファイル/勤怠記録.md (new)
  • @@ -0,0 +1,52 @@
    + <!-- + SPDX-License-Identifier: AGPL-3.0-only + Copyright 2025 Shota FUJI + + This program is free software: you can redistribute it and/or modify it under the terms + of the GNU Affero General Public License as published by the Free Software Foundation, + either version 3 of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along + with this program. If not, see <http://www.gnu.org/licenses/>. + --> + + 労働者の出勤や欠勤といった "勤怠区分" を日付・労働者ごとに記録したデータです。 + + === "行方式" + + 行方式ではひとつの行に 1 労働者の 1 日分の勤怠区分を記録します。 + + !!! example "例" + + | 社員 ID | 日付 | 勤怠区分 | + | ------- | ---------- | ------------ | + | A01 | 2025-07-01 | 出勤 | + | A01 | 2025-07-02 | 出勤 | + | A01 | 2025-07-03 | 欠勤 | + | A01 | 2025-07-04 | 年次有給休暇 | + | B01 | 2025-07-01 | 公休 | + | B01 | 2025-07-02 | 公 | + | B01 | 2025-07-03 | 出 | + | B01 | 2025-07-04 | 有休 | + | ... | ... | ... | + + === "行列方式 (シフト表方式)" + + <!-- TODO: もっとうまい言い回しに変える --> + + 行列方式では `行 = 労働者` `列 = 日付` として組み合わせで記録します。 + + !!! example "例" + + | 社員 ID | 2025-07-01 | 2025-07-02 | 2025-07-03 | 2025-07-04 | ... | + | ------- | ---------- | ---------- | ---------- | ------------ | --- | + | A01 | 出勤 | 出勤 | 欠勤 | 年次有給休暇 | ... | + | B01 | 公休 | 公 | 出 | 有休 | ... | + + !!! info "未記載事項" + + 各列や行、ヘッダや書式について
• docs/src/サポートされるファイル/年次有給休暇付与テーブル.md (new)
  • @@ -0,0 +1,123 @@
    + <!-- + SPDX-License-Identifier: AGPL-3.0-only + Copyright 2025 Shota FUJI + + This program is free software: you can redistribute it and/or modify it under the terms + of the GNU Affero General Public License as published by the Free Software Foundation, + either version 3 of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along + with this program. If not, see <http://www.gnu.org/licenses/>. + --> + + 年次有給休暇の付与テーブル (以降「付与テーブル」) は年次有給休暇を付与するタイミングで何日付与するかを決定する、勤続年数と年次有給休暇の付与日数の対応表です。 + + !!! example "例" + + | 名前 | 1回目 | 2回目 | 3回目 | 4回目 | 5回目 | 6回目 | 7回目以降 | 適用開始日 | + | ---- | ----- | ----- | ----- | ----- | ----- | ----- | --------- | ---------- | + | 週5 | 10 | 11 | 12 | 14 | 16 | 18 | 20 | | + | 週4 | 7 | 8 | 9 | 10 | 12 | 13 | 15 | | + | ... | ... | ... | ... | ... | ... | ... | ... | ... | + + !!! example "法定最低日数 (2025-08-02現在).csv" + + ```csv + 名前,1回目,2回目,3回目,4回目,5回目,6回目,7回目以降,適用開始日 + 週5,10,11,12,14,16,18,20 + 週4,7,8,9,10,12,13,15 + 週3,5,6,6,8,9,10,11 + 週2,3,4,4,5,6,6,7 + 週1,1,2,2,2,3,3,3 + ``` + + 各労働者にここで定義された付与テーブルのどれかを割り当てることで、システムが付与日数や残日数を計算できるようになります。 + + !!! warning "法令で最低日数が定められています" + + 付与テーブルを定義する際は法令で定められている最低日数を下回らないようにしましょう。 + + - [労働基準法 - 第三十九条 年次有給休暇](https://laws.e-gov.go.jp/law/322AC0000000049#Mp-Ch_4-At_39) + - [労働基準法施工規則 - 第二十四条の三](https://laws.e-gov.go.jp/law/322M40000100023#Mp-At_24_3) + - [厚生労働省発行リーフレット](https://www.mhlw.go.jp/new-info/kobetu/roudou/gyousei/dl/140811-3.pdf) + + 運用中に付与テーブルへの変更が必要になった場合、**既存の行の内容を変更しないでください**。 + 過去の計算も変わってしまうため、 [適用開始日](#適用開始日) を設定した新しい行を追加してください。 + + === "Excel ブック" + + 指定するフォルダ内のブックにシートを作成し、 1 行目に以下を貼り付けてください。 + ファイル名やシート名の指定はありません。 + + ```tsv + 名前 1回目 2回目 3回目 4回目 5回目 6回目 7回目以降 適用開始日 + ``` + + 1 行目の内容によって付与テーブルかどうか判断するため、 **1 行目の内容は変更しないでください**。 + + === "CSV/TSV" + + 指定するフォルダ内にファイルを作成し、ヘッダ行に以下を貼り付けてください。 + ファイル名の指定はありません。 + + === "CSV" + + ```csv + 名前,1回目,2回目,3回目,4回目,5回目,6回目,7回目以降,適用開始日 + ``` + + === "TSV" + + ```tsv + 名前 1回目 2回目 3回目 4回目 5回目 6回目 7回目以降 適用開始日 + ``` + + ヘッダ行の内容によって付与テーブルかどうか判断するため、 **ヘッダ行のテキストは変更しないでください**。 + + ## 列の種類 + + 付与テーブルの列は `適用開始日` を除き全て必須です。 + 入力されていない列がある場合や、付与テーブルが一つも定義されていない場合は処理が中断されます。 + + ### 名前 + + 付与テーブルの名前です。 + 労働者のマスタデータ内から参照するため、簡潔でわかりやすい名前にしましょう。 + + ### 1~6回目 + + 各付与回に付与する日数です。 + 数字、もしくは数字 + `日` (例: `10日`) が指定できます。 + + ### 7回目以降 + + 7 回目以降の付与日数です。 + 数字、もしくは数字 + `日` (例: `20日`) が指定できます。 + + 7 回目以降も日数を増やしていく場合は付与日数の上書き機能を利用してください。 + + ### 適用開始日 + + ある時点から付与テーブルの内容を変更する場合に利用する列です。 + 運用中に付与テーブルに対して変更が必要な場合、その変更の適用開始日を入力してください。 + + !!! example "例" + + 例えば以下のような付与テーブルがある場合、 + + | 名前 | 1回目 | ... | 適用開始日 | + | ---- | ----- | --- | ---------- | + | 週5 | 10 | ... | | + | 週4 | 7 | ... | | + | 週5 | 11 | ... | 2025-09-01 | + | ... | ... | ... | ... | + + 2025/08/31 に `週5` の労働者に対して 1 回目の年次有給休暇付与が行われた場合の日数は 10 日となり、 + 2025/09/01 に同様の付与が行われた場合は 11 日となります。 + + Yamori は過去のデータも再計算を行うため、直接付与テーブルを変更してしまうと過去の実績も変わってしまいます。 + そのため、運用中に法令改正や会社の制度に変更があった場合は**必ず新しい行として追加してください**。
• docs/src/サポートされるファイル/社員マスタ.md (new)
  • @@ -0,0 +1,136 @@
    + <!-- + SPDX-License-Identifier: AGPL-3.0-only + Copyright 2025 Shota FUJI + + This program is free software: you can redistribute it and/or modify it under the terms + of the GNU Affero General Public License as published by the Free Software Foundation, + either version 3 of the License, or (at your option) any later version. + + This program is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A + PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along + with this program. If not, see <http://www.gnu.org/licenses/>. + --> + + 社員の一覧を管理するファイルです。 + + !!! example "例" + + | 社員 ID | 名前 | 初回付与日 | 付与テーブル名 | 適用開始日 | + | ------- | --------- | ---------- | -------------- | ---------- | + | A01 | 田中 太郎 | 2020-01-01 | 週5 | | + | B01 | 鈴木 花子 | 2020-01-01 | 週4 | | + | B01 | 鈴木 花子 | 2020-01-01 | 週5 | 2022-02-22 | + | ... | ... | ... | ... | ... | + + "田中 太郎" は 2020/01/01 を初回として "週5" の日数の年次有給休暇が付与されます。 + + "鈴木 花子" は 2020/01/01 を初回として 2022/02/21 までは "週4" として年次有給休暇が付与され、 + 2022/02/22 からは "週5" として付与されます。 + + ## 読み込み条件 + + ファイル名もしくは Excel ブックのシート名に以下の文字列が*含まれている*場合、社員マスタとして読み込みます。 + + - 社員マスタ + - 社員一覧 + - 労働者マスタ + - 労働者一覧 + + Excel ブックのファイル名の場合は含まれているシートを全て社員マスタとして読み込みます。 + 社員マスタ以外のシートが含まれる場合はファイル名を条件から外れるものにし、シート名に上記の文字列を含めてください。 + + ## 列の種類 + + 以下の列は必須となります。 + + - [社員 ID](#社員-id) + - [年次有給休暇初回付与日](#年次有給休暇初回付与日) + - [年次有給休暇付与テーブル名](#年次有給休暇付与テーブル名) + + ### 社員 ID + + 労働者を一意に識別する文字列です。 + 社員番号などの実際の ID やランダムな文字列、ハンドルネームなど一意性が確保される限り書式は問いません。 + 重複する社員 ID が見つかった場合は処理が中断されます。 + + 社員 ID として扱われる列名は以下のとおりです。 + + - 労働者ID + - 労働者 ID + - 社員ID + - 社員 ID + - 社員番号 + - ID + - id + + 上記の列名のうち 2 つ以上が同時に存在する場合、上記の表における表示順の高いものが優先して利用されます。 + + ### 名前 + + 労働者の表示名です。 + 未指定の場合は [社員 ID](#社員-id) が表示されます。 + + 名前として扱われる列名は以下のとおりです。 + + - 労働者名 + - 社員名 + - 表示名 + - 名前 + + 上記の列名のうち 2 つ以上が同時に存在する場合、上記の表における表示順の高いものが優先して利用されます。 + + ### 年次有給休暇初回付与日 + + この労働者に対して最初に有給休暇を付与する日付です。 + 法令では入社から半年以内に付与することが義務付けられています。 + + 年次有給休暇初回付与日として扱われる列名は以下のとおりです。 + + - 年次有給休暇初回付与日 + - 有給休暇初回付与日 + - 初回付与日 + + <!-- TODO: 日付の書式に関する独立したページを作る --> + + 有効な日付の書式は以下となります。 + + - `YYYY-MM-DD` (例: `2013-05-26`) + - `YYYY/MM/DD` (例: `2013/05/26`) + - `YYYY/M/D` (例: `2013/5/26`) + + 時間も含まれている場合、時間部分は無視されます (切り捨て)。 + 時間とタイムゾーンが含まれている場合は実行コンピュータ上のタイムゾーンに換算してから時間を切り捨てます。 + + ### 年次有給休暇付与テーブル名 + + この労働者に有給休暇を付与する際の日数計算に用いるテーブルの名前です。 + [年次有給休暇付与テーブル](./年次有給休暇付与テーブル.md) で定義された[名前](./年次有給休暇付与テーブル.md#名前)を指定してください。 + + 年次有給休暇付与テーブル名として扱われる列名は以下のとおりです。 + + - 年次有給休暇付与テーブル名 + - 有給休暇付与テーブル名 + - 付与テーブル名 + - 付与テーブル + + ### 適用開始日 + + ある時点から労働者の内容を変更する場合に利用する列です。 + 運用中に労働者に対して変更が必要な場合、その変更の適用開始日を入力してください。 + + !!! example "例" + + 週4 勤務の "鈴木 花子" が 2025/05/01 から週5 勤務に変わる場合、 + + | 社員 ID | 名前 | 初回付与日 | 付与テーブル名 | 適用開始日 | + | ------- | --------- | ---------- | -------------- | ---------- | + | B01 | 鈴木 花子 | 2020-01-01 | 週4 | | + | B01 | 鈴木 花子 | 2020-01-01 | 週5 | 2025-05-01 | + + とすることで過去のデータに影響を与えることなく変更できます。 + + Yamori は過去のデータも再計算を行うため、社員マスタを変更してしまうと過去の実績も最新の労働者情報で計算されてしまいます。 + そのため、運用中に労働者に対する変更を行う場合は、必ず変更後の情報を**新しい行として追加してください**。