✎ dx:プロジェクト一覧:36協定:start [COLORS-wiki]

編集して保存をクリックしてください。Wikiの構文については syntax を参考にしてください。当然のことですが、この文書の質を向上させる場合のみ編集してください。もし編集方法や構文を練習したいのであれば playground を利用してください。

====== 36協定チェック ======

MFクラウド勤怠の「月別データ」xlsxを読み込み、36協定のチェック結果を出力する社内ツール。
PHP標準機能のみで動作し、外部ライブラリ・データベース不要。

===== ⚠ 取り扱い注意 =====

従業員の勤怠情報を扱います。

* **このリポジトリはPrivateのまま運用してください**
* `master.csv`（氏名を含む）と `.htpasswd` は `.gitignore` で除外済み。**コミットしないでください**
* 公開ディレクトリに置く場合は、必ずBasic認証またはIP制限をかけてください

===== セットアップ =====

==== 1. サーバーに配置 ====

<code>
/36kyotei/
  ├─ index.php
  ├─ master.csv     ← サーバー上で管理（Git管理外）
  ├─ .htaccess      ← アクセス制限
  └─ .htpasswd
</code>

`genpass.php` をアップロードしてブラウザで開き、ID・パスワードを入力すると `.htaccess` と `.htpasswd` を自動生成します。

**設定後は genpass.php と check.php を削除してください。**

エックスサーバーの場合は、サーバーパネルの「アクセス制限」機能を使うほうが確実です。

==== 2. 所属係マスタ ====

`master.csv.example` をコピーして `master.csv` を作り、サーバーに置きます。

画面からアップロードすることもできます（「サーバーに保存して次回から使う」にチェックすると保存されます）。

<code csv>
氏名,所属部,所属係
山田 太郎,第一事業部,設計1係
</code>

文字コードは自動判定（UTF-8 / UTF-8 BOM / Shift_JIS）。

Excelで編集して保存したCSVがそのまま使えます。

`master.csv` が無い場合は、勤怠データの「役職」列（例：`設計1係　担当`）から係名を自動判定します。

===== GitHub Actions で自動デプロイ =====

`main` にプッシュすると、PHPの構文チェックを通してから **rsync over SSH** でサーバーに反映します。

==== Secrets の登録 ====

**Settings → Secrets and variables → Actions → New repository secret** で登録します。

==== SSH鍵の作り方 ====

エックスサーバーは**公開鍵認証のみ**（パスワード認証は不可）、ポートは **10022** です。

* サーバーパネル →「SSH設定」→「+公開鍵を登録」
* ラベルを入力し「登録して秘密鍵をダウンロードする」
* ダウンロードした `.key` をテキストエディタで開き、全文をコピーして `SSH_KEY` に貼り付け

**秘密鍵はGitHubのSecrets欄以外に貼り付けないでください。**
メールやチャットに載せた場合は、必ず鍵を再発行してください。

==== 接続確認 ====

登録前に手元で確認できます。

<code bash>
# Mac / Windows(PowerShell) 共通
ssh -i "秘密鍵のパス" -p 10022 サーバーID@ホスト名 "pwd; ls -d 配置先の相対パス"
</code>

`/home/サーバーID` とフォルダ名が返ってくれば、`DEPLOY_PATH` はその2つをつなげたものになります。

==== デプロイされないファイル ====

`master.csv` `.htaccess` `.htpasswd` `data/` `*.xlsx` および Docker・CI関連ファイルは除外されます。

**`--delete` は使っていないため、サーバー上のファイルが自動デプロイで消えることはありません。**

==== ワークフローの流れ ====

<code>
構文チェック → SSH設定の確認 → SSH鍵を配置 → 接続テスト → rsyncで同期 → 鍵の後片付け
</code>

Secretsが未登録の場合は失敗せず、警告を出してスキップします。

`DEPLOY_PATH` が絶対パスでない、または末尾スラッシュが無い場合は転送前にエラーで停止します。

==== 手動実行 ====

Actions タブ → Deploy to Xserver → Run workflow

===== ローカル環境の起動 =====

Windows・Mac のどちらでも、**スクリプトを1つ実行するだけ**で起動します。

中身は同じで、動くOSが違うだけです。

Macでは **`bash` を付けて実行してください。**

Windowsで作られたファイルは実行権限が付かないため、`./setup.sh` だと `Permission denied` になることがあります。

気になる場合は一度だけ `chmod +x *.sh` を実行すれば `./setup.sh` でも動きます。

==== 事前に必要なもの ====

<code bash>
# 1) Docker Desktop を公式サイトからインストール
#    ★ Intel版(amd64) と Apple Silicon版(arm64) でインストーラが別です
#      uname -m  →  x86_64 なら Intel / arm64 なら Apple Silicon
#    https://www.docker.com/products/docker-desktop/

# 2) Mac で Homebrew が未導入なら https://brew.sh/

# 3) 以下を実行

brew install git </code>

==== 初回セットアップ ====

=== Mac ===

<code bash>
mkdir -p ~/Docker-work && cd ~/Docker-work
git clone https://github.com/Colors-ryomorita/36kyotei.git
cd 36kyotei
cp .env.example .env
bash setup.sh
</code>

=== Windows（PowerShell） ===

<code powershell>
cd C:\Docker-work
git clone https://github.com/Colors-ryomorita/36kyotei.git
cd 36kyotei
copy .env.example .env
.\setup.bat
</code>

`setup` はDockerの起動確認 → `.env` の作成 → ビルド → 起動確認までを行い、成功するとブラウザが自動で開きます。

**http://localhost:8080**

==== .env の設定 ====

`deploy` と `pull-remote` を使う場合だけ編集します。

ローカル起動だけなら初期値のままで動きます。

<code ini>
APP_PORT=8080                  # ポートを変えたいとき

SSH_HOST=sv637.xbiz.ne.jp      # サーバーパネル →「サーバー情報」
SSH_USER=colorspro             # サーバーID
SSH_PORT=10022
SSH_KEY=docker/ssh/xserver.key # 秘密鍵の置き場所
DEPLOY_PATH=/home/colorspro/example.co.jp/public_html/overtime-check/ </code>

`.env` と秘密鍵は `.gitignore` で除外済みです。

**コミットされません。**

==== 特徴 ====

* ソースをマウントしているので、**index.php を編集して保存 → ブラウザ再読み込みだけで反映**されます。ビルドし直す必要はありません
* `display_errors = On` なので、PHPのエラーが画面にそのまま表示されます
* `data/` フォルダに勤怠xlsxを置くと、画面のプルダウンから選べます
* `.htaccess` が有効（`AllowOverride All`）なので、Basic認証の動作も確認できます

===== チップの種類について（Intel / Apple Silicon） =====

どちらでもそのまま動きます。

`docker-compose.yml` やスクリプトを書き換える必要はありません。

ただし **Docker Desktop のインストーラだけは別物**なので、ここを間違えないでください。

<code bash>
uname -m        # x86_64 → Intel / arm64 → Apple Silicon
</code>

使用しているイメージは両方のCPUに対応しているので、`platform:` の指定は不要です。

^ イメージ ^ Intel (amd64) ^ Apple Silicon (arm64) ^
| `php:8.2-apache` | ✅ | ✅ |

==== Intel Mac で気をつけること ====

<code bash>
# Intel Mac で git / gh が見つからない場合
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc
</code>

==== Apple Silicon で気をつけること ====

特別な設定は要りません。

Rosetta 2 は必須ではありませんが、一部のコマンドラインツールが必要とするため入れておくと無難です。

<code bash>
softwareupdate --install-rosetta
</code>

==== 動作が遅いと感じたら ====

Docker Desktop > Settings > General で **VirtioFS** が選ばれているか確認してください（macOSのファイル共有はこれが一番速いです）。

==== ポート8080が使われている場合 ====

`.env` の `APP_PORT` を変更して `setup` を実行し直してください。

使用中のプロセスは Mac なら `lsof -i :8080`、Windows なら `netstat -ano | findstr :8080` で確認できます。

==== SSH鍵を置いたとき ====

Macでは権限を絞らないと ssh が鍵を読み込みません。

<code bash>
chmod 600 docker/ssh/xserver.key
</code>

`setup.sh` と `deploy.sh` は自動で直しますが、手で ssh を叩くときは必要です。

===== フォルダ構成 =====

<code>
36kyotei/
  ├─ index.php              ← 本体
  ├─ check.php              ← 環境チェック（本番では削除）
  ├─ genpass.php            ← 認証ファイル生成（本番では削除）
  ├─ master.csv             ← 所属係マスタ。実名のためGit管理外
  ├─ master.csv.example
  ├─ .env                   ← 環境設定。Git管理外
  ├─ .env.example
  ├─ data/                  ← 勤怠xlsxの置き場。Git管理外
  ├─ docker/
  │    ├─ php.ini
  │    └─ ssh/              ← 秘密鍵の置き場。Git管理外
  ├─ Dockerfile
  ├─ docker-compose.yml
  ├─ setup.bat / setup.sh
  ├─ stop.bat / stop.sh
  ├─ logs.bat / logs.sh
  ├─ lan-access.bat / lan-access.sh
  ├─ pull-remote.bat / pull-remote.sh
  ├─ deploy.bat / deploy.sh
  └─ .github/workflows/
       ├─ ci.yml            ← 構文チェック・起動確認・Dockerビルド
       └─ deploy.yml        ← SSH(rsync)自動デプロイ
</code>

==== 動作環境の差分 ====

ローカルで動けばサーバーでも動きます。

サーバーだけで失敗する場合は、PHPバージョンかアップロード上限が原因のことがほとんどです。

`check.php` で確認してください。

===== CI（GitHub Actions） =====

プッシュのたびに自動で検証します。

いずれかが失敗するとデプロイされません。

===== 使い方 =====

==== MFクラウド勤怠からのエクスポート ====

**全権管理者メニュー ＞ 連携 ＞ エクスポート ＞ 月別データ**

**時間フォーマットは必ず10進数にしてください。**

60進数（`1.30`＝1時間30分）のままだと判定と割り算が狂います。

読み込み時に自動換算しますが、MF側の設定が確実です。

**ファイル名は変更しないでください。**

単月出力には対象年月の列が無いため、ファイル名から対象月を判定しています。

==== 出力 ====

共通で「月別 超過者一覧」（月次基本時間との比較）を出力します。

===== 計算仕様 =====

==== 判定基準 ====

==== 法令との対応 ====

==== 当月の月末見込み ====

<code>
見込みA ＝ 残業時間 ÷ 経過営業日数 × 所定労働日数
見込みB ＝（総労働時間 － 所定時間）÷ 経過営業日数 × 所定労働日数
判定には A と B の大きいほうを使用（安全側）
</code>

見込みBを併用するのは、法定外時間が週単位で確定するため月初〜週の途中では0のままになるためです。

総労働時間－所定時間は初日から反応します。

==== 通算バランス（帳尻） ====

各月の「総労働時間 － 月次基本時間」を積み上げた累計。

ある月に超過しても翌月に下回れば累計は戻ります。

**集計途中の当月は累計から自動的に除外されます。**

含めると全員が大きくマイナスになり、帳尻が合って見えるためです。

月次基本時間の初期値は `MONTHLY_BASE_DEFAULT`（162.67時間＝年間所定労働時間1952時間 ÷ 12）。

画面で変更できます。

===== カスタマイズ（index.php 冒頭の定数） =====

役職が空欄の人も集計対象外になります。

===== 動作要件 =====

* PHP 7.4 以上
* 拡張：`zip` `xml` `mbstring`
* `upload_max_filesize` / `post_max_size` 2MB以上

`check.php` をアップロードして開くと、これらを一括で確認できます。

===== トラブルシューティング =====

編集の概要

注意：本ページを編集した場合、あなたの編集した内容が次のライセンスに従うことに同意したものとみなします： CC0 1.0 Universal