backend: feature 内クリーンアーキ 4 層パッケージ雛形 + shared Open module 新設 (N4 / A-1)

[win2cot]

設計規約 §1.1(2026-05-14 PR #135 で確定)の Spring Modulith feature-by-package + 各 feature 内クリーンアーキ 4 層ハイブリッド構成 の パッケージ雛形(package-info.java + shared Open module) を整える。

本 Issue は元 N4 (#86) の 5 項目を 4 分割した A-1 スコープ(2026-05-29 PR #269 が 52 files / +1085 / -177 まで肥大化したため分割):

• A-1 (本 Issue): 新規 package-info.java 配置 + shared 新設(既存クラス無変更)
• A-2 (backend: 既存クラス(Controller / Repository / Entity)を 4 層パッケージへ移動 (N4 / A-2) #272): 既存 Controller / Repository / Entity を 4 層パッケージへ移動
• B (backend: 基盤(shared/exception + Task POJO/JPA Entity 分離 + Repository ポート) (N4 / B-1) #273): サンプル UseCase GET /api/tasks/{id} の 4 層実証 + DB マイグレーション + 共通例外基底
• C (docs(dev): 新 feature 追加時のテンプレ手順書 docs/dev/feature-template.md 整備 (N4 / C) #274): docs/dev/feature-template.md 整備

A-2/B/C は別 Issue で順次着手(blocks/blocked-by 関係を設定)。

規約準拠の前提

規約 / ADR	内容
設計規約 §1.1	外側 = feature-by-package(xyz.dgz48.tasks.webapi.<feature>、Spring Modulith)。内側 = 各 feature 内に domain / usecase / adapter.{web,persistence,external} / infra の 4 層
ADR-0002	ArchUnit 採用は当面保留。依存方向検証は Spring Modulith ApplicationModules.verify() に集約
ADR-0003	shared は Open module(@ApplicationModule(type = Type.OPEN))、@NamedInterface 不要

やること

1. 既存 4 feature 配下に 4 層パッケージ + package-info.java を配置

security / task / tenant / user の各 feature 配下に以下を配置:

xyz.dgz48.tasks.webapi.<feature>/
  ├─ domain/         POJO、Spring 非依存、JPA アノテーション禁止
  ├─ usecase/        ユースケース・Port 定義・@Transactional 境界
  ├─ adapter/
  │   ├─ web/        REST Controller
  │   └─ persistence/ JPA Entity・Repository

各パッケージに @NullMarked 付き package-info.java を配置(既存 task/domain/package-info.java と同形式)。

A-1 段階の調整:

• adapter.external / infra は本 Issue では作らない(必要 feature が出た Issue 着手時)
• task/domain/package-info.java は main 既存、対象外
• adapter 直下の親 adapter/package-info.java(@NullMarked)も配置

2. shared feature を Open module として新設(ADR-0003)

xyz.dgz48.tasks.webapi.shared/package-info.java:

@NullMarked
@ApplicationModule(type = Type.OPEN)
package xyz.dgz48.tasks.webapi.shared;

import org.jspecify.annotations.NullMarked;
import org.springframework.modulith.ApplicationModule;
import org.springframework.modulith.ApplicationModule.Type;

A-1 では shared 直下の package-info.java のみ。shared/exception/ などのサブパッケージ + DomainException 等は B (#273) で同梱。

3. ModularityTests.verify() が green を維持

既存 webapi/src/test/java/xyz/dgz48/tasks/webapi/ModularityTests.java を維持。A-1 でパッケージ構造を整えた後も ApplicationModules.verify() が CI で green であること。

やらないこと(A-1 では対象外)

• 既存クラス(Controller / Repository / Entity / Exception)の移動 → A-2 (backend: 既存クラス(Controller / Repository / Entity)を 4 層パッケージへ移動 (N4 / A-2) #272)
• JPA Entity と Domain POJO の分離 → B (backend: 基盤(shared/exception + Task POJO/JPA Entity 分離 + Repository ポート) (N4 / B-1) #273)
• task/usecase/GetTaskUseCase.java 等の新規 UseCase 実装 → B (backend: 基盤(shared/exception + Task POJO/JPA Entity 分離 + Repository ポート) (N4 / B-1) #273)
• DB マイグレーション変更(tasks テーブル列追加等) → B (backend: 基盤(shared/exception + Task POJO/JPA Entity 分離 + Repository ポート) (N4 / B-1) #273) または N8 (docs(spec)+impl: 既存usersテーブル記述補正 + ADR-0006 派生スコープ(users 列追加 + JPA + 匿名化 service)(N8) #90)
• docs/dev/feature-template.md 整備 → C (docs(dev): 新 feature 追加時のテンプレ手順書 docs/dev/feature-template.md 整備 (N4 / C) #274)
• shared/exception/DomainException.java 共通例外基底 → B (backend: 基盤(shared/exception + Task POJO/JPA Entity 分離 + Repository ポート) (N4 / B-1) #273)
• ArchUnit 導入 → ADR-0002 で当面保留
• トップレベル domain / usecase / adapter / infrastructure パッケージ作成 → 設計規約 §1.1 違反

受け入れ条件

• security / task / tenant / user の各 feature 配下に domain / usecase / adapter / adapter/web / adapter/persistence パッケージ + @NullMarked 付き package-info.java 配置(task/domain は既存スキップ)
• shared feature 新設、shared/package-info.java に @ApplicationModule(type = Type.OPEN) 設定済
• 既存クラス(task/Task.java / task/TaskController.java / task/TaskRepository.java 等)は移動・変更されていない(A-1 範囲外)
• ApplicationModules.verify() が CI で green
• ArchUnit を導入していない(webapi/build.gradle に archunit-* 依存が無い)
• CI green、UT カバレッジ 80%+

参照

• 起票元: docs/reviews/2026-05-10-scaffold-vs-design-gap-analysis.md §G-5(2026-05-25 docs(reviews): 2026-05-10 gap analysis に規約成立後の方針更新ディスクレーマ追記 #249 でディスクレーマ追記済)
• 規約: docs/specs/設計規約.md §1.1 ハイブリッド構成 / §1.5 shared モジュール
• ADR: docs/adr/0002-defer-archunit-adoption.md / docs/adr/0003-shared-package-as-open-module.md
• 関連 Issue: backend: 既存クラス(Controller / Repository / Entity)を 4 層パッケージへ移動 (N4 / A-2) #272 (A-2、blocked-by 本) / backend: 基盤(shared/exception + Task POJO/JPA Entity 分離 + Repository ポート) (N4 / B-1) #273 (B、blocked-by A-2) / docs(dev): 新 feature 追加時のテンプレ手順書 docs/dev/feature-template.md 整備 (N4 / C) #274 (C、blocked-by B) / docs(spec)+impl: 既存usersテーブル記述補正 + ADR-0006 派生スコープ(users 列追加 + JPA + 匿名化 service)(N8) #90 (N8、blocked-by A-2 に組み替え)
• 経緯: PR feat(task): feature 内クリーンアーキ 4 層パッケージ雛形 + shared Open module 新設 (N4 / A-1) (#86) #269 肥大化(52 files / +1085 / -177)→ 4 分割(2026-05-29、Cowork ブレスト)
• Sub-tracker: [Phase 1 Sprint 0] scaffold ↔ 設計書 v1.4.x 整合実装(2 週間、2026-06-14 〜 06-27) #121 Phase 1 Sprint 0