セキュリティチェックリスト

🌐 言語: 🇻🇳 Tiếng Việt · 🇬🇧 English · 🇯🇵 日本語（現在）

GP247 v3.0 リリースノート — 注文のお金

はじめに

v3.0 では、GP247 が注文に対してお客様が支払ったお金を記録する仕組みを全面的に見直しました。このドキュメントは、v2.1 または v2.2 を運用しているショップオーナーとサイト運営者向けです。アップグレードのために何をすればよいかを説明します。さらに重要な点として、アップグレード後に画面上のどの数字が変わるかも説明します。システムの計算ミスだと誤解しないためです。最後に、プラグイン開発者向けの項目もあります。

アップグレード方法

最初にデータベースをバックアップします。 このバージョンにはデータ変換が含まれます。十分にテストしていますが、問題が起きたときに元に戻せる唯一の方法がバックアップです。これが最も大切な手順です。
ターミナル（Windows では「コマンドプロンプト」）を開き、ウェブサイトのルートフォルダに移動して、次のように入力します。
```
composer update
```
このコマンドは新しいソースコードをダウンロードするだけです。データにはまだ触れません。
続けて次のコマンドを入力し、Enter キーを押します。
```
php artisan gp247:update
```
このコマンドで変更がサイトに適用されます（データ変換、基本データの更新、キャッシュの削除）。成功すると、実行した手順が表示され、エラーの行は表示されません。
以上で完了です。ほかに手動の手順はありません。php artisan migrate を自分で実行する必要はありません。

手順 3 のコマンドは何度実行しても問題ありません。どの変換処理も、2 回目の実行ではそれ以上何も変わらないように作られています。

変更 1 — 注文のお金は 1 つの数字ではなく「台帳」になりました

以前は、各注文には「入金済み」の欄が 1 つあるだけでした。この欄では、お金がいつ、 どの方法で入ったのかがわからず、一部返金も記録できませんでした。

v3.0 からは、入金や返金の 1 回 1 回が、注文の支払い台帳の個別の行になります。行には日付、金額、支払い方法、取引 ID が記録されます。注文の詳細画面では、合計金額の下に、各回を一覧にした支払い履歴が表示されます。

すぐに気づく違いは 3 つあります。

決済ゲートウェイ（PayPal）で支払われた注文が、全額未払いと表示されなくなりました。 以前は、決済ゲートウェイはステータスのラベルを変えるだけで、お金を記録していませんでした。そのため、お客様が実際に支払った注文も未収金の一覧に残り、売上にも計上されませんでした。現在は、ゲートウェイから通知が届いた時点で、お金が正しく記録されます。
一部返金が正しい金額で記録されます。 以前は、10% を返金しただけで注文全体が「返金済み」になり、返金した金額はどこにも保存されませんでした。
「入金済み」欄の使い方が変わりました。 数字を直接編集するのではなく、入金を記録します（金額・日付・支払い方法を入力）。返金したい場合は、返金を記録します。

アップグレード時に、既存の注文の台帳が自動で作成されます。お金のある注文には、それに対応する入金の行が 1 つずつ用意されます。そのため、アップグレード後も「入金済み」の数字は変わりません。

変更 2 — キャッシュフローのレポートは入金日で集計します（数字が変わります）

⚠️ 注意: 最も誤解されやすい変更です。この項目をよく読んでください。

この変更は、InOut プラグイン（キャッシュフローと債権・債務）を使っている場合だけ対象です。

以前は、販売の売上を注文日で集計していました。たとえば、お客様が 7 月に注文して 8 月に支払った場合でも、そのお金は 7 月に計上されていました。つまり、キャッシュフローのレポートが、お金が実際に入った日ではなく注文日を使っていたことになります。

v3.0 からは、売上を入金日で集計します。上の例では、そのお金は 8 月に計上されます。

準備しておくべきこと:

各期間の売上が以前の数字と変わります。 これはより正確な数字であり、エラーではありません。
アップグレード日より前のデータは、以前の方法のままです。 古い注文の実際の入金日は記録されていません（以前は保存する場所がありませんでした）。そのため、アップグレード時に古い注文のお金は 注文作成日で記録されます。これは以前の集計方法とまったく同じです。したがって境目は アップグレードした日になります。それより前は以前どおり、それ以降は実際の入金日で集計されます。
アップグレード前に期間を締めておくか、直近の期間のレポートを印刷／エクスポートして照合に備えることをおすすめします。

手動の入金伝票を注文に紐づけられるようになりました

「出納帳」画面の入金／出金伝票の作成フォームに、**「対象注文」**という欄が追加されました。そのお金がある注文のものであれば、その注文を選んでください。お金は別の伝票にはならず、注文の台帳に入ります。

理由: 出納帳の入金合計には、販売の売上と手動の入金伝票の両方が含まれます。同じお金が注文にも手動の入金伝票にもあると、二重に計上されてしまいます。以前は（決済ゲートウェイがお金を記録しなかったため）経理担当者がほぼ必ず手動で伝票を作る必要があったので、この状況はとても起きやすいものでした。

そのお金がどの注文にも属さない場合（注文前の手付金、古い債権の回収など）は、その欄を空欄のままにしてください。お客様に未払いの注文があるときだけシステムが注意を表示しますが、保存はできます。

変更 3 — 支払いステータスの 1 段階のずれを解消しました

以前は、支払いステータスが実際より 1 段階低く表示される不具合がありました。 全額支払い済みの注文が「一部支払い」、返金が必要な注文が「支払い済み」と表示され、未払いの注文が文字ではなく数字の 0 と表示されることもありました。そのため、InOut の未収金の一覧も、誤った対象を抽出していました。

v3.0 からは正しく表示され、アップグレード時に古いデータも自動で修正されます。知っておくべき点が 1 つあります。

システムが修正するのは、金額からステータスが明確にわかる注文だけです。金額が入力されていないのに、管理者が手動で「支払い済み」にした注文は、意図的にそのまま残します。それは人による判断であり、自動で推定し直すとその判断が消えてしまうからです。

金額を入力せずに「支払い済み」にする運用をしていた場合、その注文は以前のラベルのままですが、「入金済み」は 0 になります。数字をそろえたい場合は、それらの注文に入金を記録してください。

変更 4 — 割引は税金を計算する前に差し引くようになりました

⚠️ 注意: 2 種類のクーポンで影響が異なります。使っている種類の説明を読んでください。まとめて説明すると、半分の方にとって誤りになります。

以前は、元の価格で税金を計算してから割引を差し引いていました。つまり、お客様は割引された部分にも税金を負担しており、注文に保存される税額は、誰も支払っていない価格に対する税金でした。

v3.0 からは、先に割引を差し引き、残りの金額に税金をかけます。これは VAT/GST の一般的な慣行どおりです。

パーセント割引のクーポン → 合計金額は変わりません

修正されるのは税額だけです。例: 注文 100、税率 10%、10% 割引クーポンの場合:

	税金	割引	お客様の支払額
以前	10	11	99
v3.0 から	9	10	99

お客様の支払額は以前とまったく同じです。ただし、以前は税金を 1 多く申告していたことになります。修正されるのはその部分です。

定額割引のクーポン → お客様の支払額が少なくなります

例: 注文 100、税率 10%、20 の割引クーポンの場合:

	税金	割引	お客様の支払額
以前	10	20	90
v3.0 から	8	20	88

税金が残りの 80 にだけかかるようになったためです。これはお客様の目に見える変更です。 定額割引のクーポンを使っている場合、注文 1 件あたりの売上が以前より少し下がります。

パーセント割引がお客様に不利な端数処理をしなくなりました

端数処理の不具合により、パーセント割引が告知した割合より少なく割り引かれることがありました。 236 の 10% 割引で、23.60 ではなく 23 しか差し引かれませんでした。誤差は常にショップ側に有利で、パーセント割引を使ったすべての注文で起きていました。現在は修正されています。

一部返品を正しく計算できるようになりました

割引は、比率に応じて各明細行に配分されるようになりました。割引クーポンを使った注文で、お客様が 1 つの商品を返品した場合、どの割引がその商品の分なのかをシステムが正確に把握できます。以前は「注文全体で 60,000 割引」としかわからず、返品する商品にいくら属するのかが不明だったため、 過剰に返金しやすい状態でした。

アップグレード時に古い注文にも割引が配分されますが、それらの金額は一切変わりません。そのため、古い注文では各明細行に割引があるのに、税額は割引前の税金のままになります。これは データの破損ではありません。証憑で発行済みの数字であり、修正すると、その注文について行ったすべての会計照合が崩れてしまいます。

変更 5 — 機密データの暗号化（3.0.3 から）

gp247/core 3.0.3 から、データベースに保存される機密情報（SMTP パスワード、Google Captcha のシークレット、OAuth クライアントシークレット、プラグインのライセンス）は、保存時に暗号化 されます（enc:v2:… の形式で保存され、平文ではなくなりました）。それ以前のバージョンでは、これらの値を平文で保存していました。

運用者にとって重要な点:

GP247 は .env 内の専用の鍵 GP247_ENCRYPTION_KEY を使います。これは APP_KEY とは別です。そのため、APP_KEY を変更／再生成してもシークレットは壊れません。インストール直後に専用の鍵を設定することをおすすめします。未設定の場合は一時的に APP_KEY を使い、gp247:doctor が設定を促します。
鍵の変更は必ずコマンドで行います（php artisan gp247:encryption-key-rotate。新しい鍵ですべてを暗号化し直します）。手動で編集しないでください。手動で編集すると、古いシークレットがすべて読めなくなります。
古いサイトをアップグレードする場合: 既存のシークレットは、アップグレード用マイグレーション（gp247:update）の実行時に自動で暗号化されます。残りは遅延処理で暗号化されます（保存し直すと暗号化されます）。

詳細（鍵を変更する手順、鍵を失ったときの復旧、開発者向けの他テーブルの列の暗号化）は、機密データの暗号化を参照してください。

条件と制約（操作の前に確認）

入金または返金を記録するとき

金額は 0 より大きくなければなりません — 0 の金額は、実際にお金が動いたことになりません。逆方向を記録したい場合は返金機能を使ってください。マイナスの数字は入力しないでください。
締められた会計期間には記録できません（その期間に属する日付の場合。InOut を使っている場合のみ）— 締めた期間の数字が知らないうちに変わらないようにするためです。

決済ゲートウェイから入金の通知が届いたとき

システムはゲートウェイから返された金額をそのまま記録します。その金額が注文合計と異なる場合も同じです。差がある場合、注文は一部支払いの状態になり、照合できるようにログが記録されます。システムは金額を合わせるための端数処理をしません。それは実際に存在するずれを隠すことになるからです。
同じ取引の通知が何度届いても、記録されるのは 1 回だけです。 決済ゲートウェイは通知を再送することがありますが、お金が二重に加算されることはありません。

割引クーポンを適用するとき

割引は商品代金（税抜き）を超えることはできません — 商品の価値より多く割り引くと注文の合計がマイナスになり、後続のどの画面でも処理できません。超えた金額を入力すると、商品代金と同じ額に切り詰められます。

InOut で手動の入金伝票を作成するとき

注文を選ぶと、お金は注文の台帳に入ります。伝票は追加で作成されません。 1 つのお金が 2 か所に存在しないようにするためです。

プラグイン開発者向け

自作のプラグインに影響する可能性のある変更は 2 つです。

ShopOrderTotal::PAID の値が 2 から 3 に変わりました（同じグループの 3 つの定数もそれに合わせてずれています）。これらはもともと誤っていました（shop_payment_status テーブルと 1 段階ずれていました）。そのままにしておくほうが危険です。プラグインで payment_status を比較している場合は、ShopPaymentStatus::{UNPAID, PARTIAL, PAID, REFUND} を使ってください。
決済プラグインは ShopOrder::recordPayment() / recordRefund() に移行してください。 processPaymentPaid() は引き続き動作します（@deprecated を付けています）。ただし、表現できるのは「全額入金」だけです。手付金も一部入金も扱えず、取引 ID も持たないため、再度呼び出したときに 重複を防げません。新しい 2 つの関数は、金額・支払い方法・取引 ID・入金日を受け取ります。
shop_order_detail に discount と tax_rate の 2 列が追加されました。 2 列目は見た目のためのものではありません。以前は、注文明細には税金の金額だけが保存され、税率は商品側にありました。そのため、 (a) 割引で課税ベースが変わったときに税金を再計算できず、(b) 誰かが商品の税率を変更しただけで、古い注文の税額が変わることがありました。現在は、税率が証憑上で確定されます。
管理画面の明細行の税金入力欄は、入力した金額から算出した税率を保存するようになりました。 金額は以前どおり入力できますが、その数字は今後、本物の税金と同じように課税ベースに応じて伸縮します。判断の原則: 割引があっても変わらない項目は other_fee であり、tax ではありません。
コードで割引を配分する必要がある場合は、gp247_allocate_discount() を使ってください。自分で分割し直さないでください。端数は正確に 1 か所に寄せる必要があり、それによって Σ 各明細行の割引 が常に注文の割引と一致します。

ステータスのラベルはテーブル（ShopPaymentStatus::getIdAll()）から取得してください。番号に基づいてハードコードしないでください。管理者はステータス名を変更できます。

よくある質問（Q&A）

Q1: アップグレードの前に何をすればよいですか？

→ データベースをバックアップしてください。InOut を使っている場合は、アップグレード後の照合のために、直近の期間のキャッシュフローレポートをエクスポート／印刷しておくことをおすすめします。

Q2: アップグレード後、先月の売上が以前の数字と違います。システムの計算ミスですか？

→ いいえ。売上は注文日ではなく入金日で集計されるようになりました（変更 2 を参照）。こちらがより正確な数字です。

Q3: 古い注文の「入金済み」の数字は失われますか？

→ いいえ。アップグレード時に、お金のある注文ごとに対応する入金の行が自動で作成されるため、数字はそのまま残ります。

Q4: パーセント割引のクーポンを使っています。お客様の支払額は変わりますか？

→ いいえ。合計金額は以前とまったく同じです。修正されるのは税額だけです（以前は多く申告していました）。定額のクーポンでは、お客様の支払額が少なくなります（変更 4 を参照）。

Q5: 手動で「支払い済み」にした注文は変更されますか？

→ いいえ。システムはそれらの注文を意図的にそのまま残します。自動で変更すると、あなたの判断が消えてしまうからです。入金を記録するまで、「入金済み」が 0 になるだけです。

Q6: 「入金済み」欄を直接編集できなくなったのはなぜですか？

→ 1 つの数字では、お金がいつ、どの方法で入ったのかがわからないからです。現在は入金を 1 件ずつ記録し、それぞれに日付があります。これが、キャッシュフローレポートを正しい期間で集計するための条件です。

Q7: InOut プラグインを使っていない場合、影響はありますか？

→ 変更 2 の影響はありません。変更 1 と変更 3 は適用されます。

Q8: 古い注文で各明細行に割引が表示されていますが、税額が合わないように見えます。不具合ですか？

→ いいえ。アップグレードでは、古い注文の金額を意図的に一切変えていません。そのため、税額は割引前の税金のままです。これは証憑で発行済みの数字です。明細行への配分は、一部返品を正しく計算するためだけのものです。

Q9: v2.1 より古いバージョンを使っている場合はどうなりますか？

→ サポートされるアップグレード経路は v2.1 からです。v2.1 または v2.2 のサイトは、v3.0 に直接アップグレードできます。 v2.1 より古いサイトは、先に v2.1 にアップグレードしてから v3.0 にしてください。

Q10: アップグレード後、お金が正しく記録されたかどうかは、どうやって確認しますか？

→ 支払い済みの注文を開き、合計金額の下にある支払い履歴を確認します。正しい金額と日付の入金の行があり、「残額」が 0 になっていれば正しく記録されています。

_{📅 最終更新: 2026-10-22 · ✍️ 作成者 (Author): GP247}