
# 監査

監査は、エンティティが保存されるときに 4 種類のプロパティを埋めます。作成された時刻、最後に変更された時刻、作成した者、最後に変更した者です。プロパティにアノテーションを付け、構成クラスに `@EnableDataAuditing()` を付けて監査を有効にします。

## 使う理由

「この行を誰がいつ変更したか?」は、ほとんどすべてのテーブルについて問われます。これらの値をすべてのサービスで設定するのは忘れやすく、値もばらつきます (あるサービスはローカル時刻を、別のサービスは UTC を使う)。監査を使えば、リポジトリがすべての `save` で、一つの時計と現在のユーザーの一つの情報源から、それらを設定します。

## 例

```dart
@Table('books')
class Book {
  Book({this.id, required this.title});

  @Id()
  int? id;

  String title;

  @CreatedDate()
  DateTime? createdAt;      // 挿入時の時刻。その後は保たれる

  @LastModifiedDate()
  DateTime? modifiedAt;     // 各保存の時刻

  @CreatedBy()
  String? createdBy;        // 挿入時の監査者

  @LastModifiedBy()
  String? modifiedBy;       // 各保存時の監査者
}

@Configuration()
@EnableDataAuditing()
class AuditingSetup {}

// 誰が操作しているか: セキュリティコンテキスト、リクエスト、ジョブ名などから読む。
@Component()
class CurrentUser implements AuditorAware<String> {
  @override
  String? getCurrentAuditor() => 'librarian';
}
```

```dart
final saved = await books.save(Book(title: 'Dune'));
print(saved.createdBy);   // librarian
print(saved.createdAt == saved.modifiedAt); // true: 挿入でも「最終変更」の値が設定される
```

## アノテーション

| アノテーション | 型 | 設定されるタイミング |
|---|---|---|
| `@CreatedDate()` | `DateTime` | 挿入時。その後は保たれる |
| `@LastModifiedDate()` | `DateTime` | 各保存時 (`modifyOnCreate` なら挿入時にも) |
| `@CreatedBy()` | 監査者の型 | 挿入時。その後は保たれる |
| `@LastModifiedBy()` | 監査者の型 | 各保存時 (`modifyOnCreate` なら挿入時にも) |

## @EnableDataAuditing

| 属性 | デフォルト | 意味 |
|---|---|---|
| `auditorAwareRef` | `''` | `AuditorAware` の Bean の名前。唯一のものなら空。 |
| `dateTimeProviderRef` | `''` | `DateTimeProvider` の Bean の名前。唯一のものなら空。なければシステムの時計。 |
| `setDates` | `true` | `@CreatedDate` と `@LastModifiedDate` を設定するかどうか。`false` では監査者のプロパティだけを設定する。 |
| `modifyOnCreate` | `true` | 挿入時にも `@LastModifiedDate` と `@LastModifiedBy` を作成時の値に設定するかどうか。 |

`@EnableDataAuditing` がなければ、アノテーションは何もしません。`auditingHandler` の Bean は、それを持つ Bean がある場合にだけ存在します。

## 監査者と時計

- **`AuditorAware<T>`** は、同期的に、または `Future` で `getCurrentAuditor()` に答えます。`null` の答え (誰もログインしていない) は、プロパティをそのままにします。
- **`DateTimeProvider`** は時計です。デフォルトは `DateTime.now` です。テストで時刻を固定するには Bean を宣言します。

```dart
@Configuration()
class TestClock {
  @Bean()
  DateTimeProvider dateTimeProvider() =>
      DateTimeProvider(() => DateTime.utc(2026, 3, 1, 10));
}
```

## 知っておくべきこと

- **`save` が返すものを使ってください。** `final` の監査プロパティを持つエンティティは新しい値でコピーされるため、渡したインスタンスは変わりません。
- **データベースのカスケードは監査されません。** `@OnDelete(OnDeleteAction.setNull)` で変更された行は、リポジトリの `save` を通りません ([参照とキー](references.md) を参照)。
- **`JdbcTemplate` の文は監査されません。** `@Modifying` のクエリも同様です。監査はリポジトリの `save` の一部です。

## Spring (Java) との対応

```java
@Configuration
@EnableJdbcAuditing(auditorAwareRef = "currentUser")
class AuditingSetup {}

@Component
class CurrentUser implements AuditorAware<String> {
  public Optional<String> getCurrentAuditor() { return Optional.of("librarian"); }
}
```

アノテーションは `@EnableJdbcAuditing` ではなく `@EnableDataAuditing` です。`getCurrentAuditor` は `Optional` ではなく、nullable な値 (またはその `Future`) を返します。

## 関連項目

- [エンティティ](entities.md)
- [リポジトリ](repositories.md)
