feat: 빠른배틀(오늘의 배틀) — API 연동 + 화면/세로페이저/공유/ChatRoom 진입 + 댓글 진영 버그 수정

AGENTS.md

@@ -498,6 +498,39 @@ public struct PreVoteFeature {
 - 파일 위치: `Projects/Presentation/<모듈>/Sources/<도메인>/Model/<TypeName>.swift`
 - 레퍼런스: `Projects/Presentation/Chat/Sources/Vote/Model/ShareItem.swift`, `Projects/Presentation/Chat/Sources/Vote/Model/ShareContent.swift`
 
+#### 🧰 공통 유틸 — `Utill` 모듈 + `Type+.swift` 네이밍 (필수)
+
+도메인/화면에 종속되지 않는 **순수 유틸** (숫자 포맷, 문자열 분할, 날짜 변환 등) 은 Feature 안에 private helper 로 두지 말고 **`Shared/Utill` 모듈에 타입 확장**으로 분리한다. 여러 모듈(Chat / Home / Auth / Hifi 등)에서 공용으로 쓴다.
+
+```swift
+// ✅ 올바른 패턴 — Utill 모듈의 타입 확장. 파일명은 `Type+.swift` (기능 접미사 없음, 한 타입당 한 파일)
+// Projects/Shared/Utill/Sources/Extension/Int+.swift
+public extension Int {
+  var decimalFormatted: String { ... }   // 1340 → "1,340"
+}
+
+// Projects/Shared/Utill/Sources/Extension/String+.swift
+public extension String {
+  func splitIntoSentences() -> [String] { ... }
+}
+
+// 사용처: import Utill 후 그대로
+import Utill
+let count = likeCount.decimalFormatted
+let lines = script.text.splitIntoSentences()
+
+// ❌ 금지 — Feature/View 안에 private static helper 로 중복 선언
+private static func formattedCount(_ n: Int) -> String { ... }   // ← Utill 로 이동
+private static func splitSentences(_ t: String) -> [String] { ... } // ← Utill 로 이동
+```
+
+규칙:
+- **Extension 파일 네이밍은 항상 `Type+.swift`** — 확장 대상 타입 + `+` 만 (기능 접미사 없음). 한 타입 확장은 한 파일에 모은다 (`Int+.swift`, `String+.swift`, `UUID+.swift`, `Color+.swift`, `View+.swift`). 기존 `ShapeStyle+.swift`, `UIColor+.swift` 와 동일 규칙.
+- 순수 유틸 (Foundation 만 의존, UI/도메인 무관) → `Projects/Shared/Utill/Sources/Extension/` 에 둔다
+- 쓰는 모듈은 `.Shared(implements: .Utill)` 의존성 추가 후 `import Utill`
+- DesignSystem 전용 확장(컬러/폰트/모디파이어)은 DesignSystem 모듈에 두되 파일명은 동일하게 `Type+.swift`
+- 레퍼런스: `Projects/Shared/Utill/Sources/Extension/Int+.swift`, `String+.swift`, `UUID+.swift`
+
 #### ⚡ AsyncAction — `Result { try await }` + `mapError` + 단일 `Response` Inner 액션
 
 `do/catch + 별도 Loaded / Failed 액션` 분리하지 말고, `Result` 로 감싸서 단일 `xxxResponse(Result<Success, AuthError>)` Inner 액션으로 보낸다. State 캡쳐는 `[키 = state.xxx]` 형태.

Plugins/DependencyPlugin/ProjectDescriptionHelpers/TargetDependency+Module/Modules.swift

@@ -25,12 +25,12 @@ public extension ModulePath {
     case MainTab
     case Home
     case Chat
-
+    case Hifi
+    case Web
+    case Battle
 
     public static let name: String = "Presentation"
 
-      case Hifi
-      case Web
   }
 }
 

Projects/App/Sources/Reducer/AppReducer.swift

@@ -236,7 +236,7 @@ public struct AppReducer: Sendable {
   private func handleScopeNavigation(action: ScopeAction) -> Effect<Action> {
     switch action {
     case .splash(.view(.onAppear)):
-      return .send(.view(.presentAuth))
+      return .none
 
     case .splash(.delegate(.presentAuth)):
       return .run { send in

Projects/Data/API/Sources/Battle/BattleAPI.swift

@@ -6,6 +6,7 @@
 import Foundation
 
 public enum BattleAPI {
+  case today
   case detail(battleId: Int)
   case preVote(battleId: Int)
   case postVote(battleId: Int)
@@ -17,6 +18,8 @@ public enum BattleAPI {
 
   public var description: String {
     switch self {
+    case .today:
+      return "today"
     case let .detail(battleId):
       return "\(battleId)"
     case let .preVote(battleId):

Projects/Data/Model/Sources/Battle/DTO/BattleDetailDataDTO.swift

@@ -35,7 +35,8 @@ public struct BattleOptionDTO: Decodable {
   public let stance: String
   public let representative: String
   public let imageUrl: String
-  public let tags: [BattleTagDTO]
+  // today 배틀 옵션 응답엔 tags 가 없으므로 옵셔널.
+  public let tags: [BattleTagDTO]?
 }
 
 public struct BattleTagDTO: Decodable {

Projects/Data/Model/Sources/Battle/DTO/TodayBattleDataDTO.swift

@@ -0,0 +1,15 @@
+//
+//  TodayBattleDataDTO.swift
+//  Model
+//
+//  `GET /api/v1/battles/today` 응답 DTO. 아이템은 BattleInfoDTO 재사용.
+//
+
+import Foundation
+
+public struct TodayBattlePageDataDTO: Decodable {
+  public let items: [BattleInfoDTO]
+  public let totalCount: Int
+}
+
+public typealias TodayBattlePageResponseDTO = BaseResponseDTO<TodayBattlePageDataDTO>

Projects/Data/Model/Sources/Battle/Mapper/BattleDetailDataDTO+.swift

@@ -46,7 +46,7 @@ public extension BattleOptionDTO {
       stance: stance,
       representative: representative,
       imageUrl: imageUrl,
-      tags: tags.map { $0.toDomain() }
+      tags: (tags ?? []).map { $0.toDomain() }
     )
   }
 }

Projects/Data/Model/Sources/Battle/Mapper/TodayBattleDataDTO+.swift

@@ -0,0 +1,16 @@
+//
+//  TodayBattleDataDTO+.swift
+//  Model
+//
+
+import Entity
+import Foundation
+
+public extension TodayBattlePageDataDTO {
+  func toDomain() -> TodayBattlePage {
+    TodayBattlePage(
+      items: items.map { $0.toDomain() },
+      totalCount: totalCount
+    )
+  }
+}

Projects/Data/Repository/Sources/Battle/BattleRepositoryImpl.swift

@@ -24,6 +24,18 @@ public final class BattleRepositoryImpl: BattleInterface, @unchecked Sendable {
     self.provider = provider
   }
 
+  public func fetchTodayBattles() async throws -> TodayBattlePage {
+    let dto: TodayBattlePageResponseDTO = try await provider.request(.today)
+
+    guard let data = dto.data else {
+      let message = dto.error?.message ?? "오늘의 배틀 응답이 비어 있습니다"
+      Log.error("[BattleRepositoryImpl] empty todayBattles payload: \(message)")
+      throw BattleError.backendError(message)
+    }
+
+    return data.toDomain()
+  }
+
   public func fetchBattle(battleId: Int) async throws -> BattleDetail {
     let dto: BattleDetailResponseDTO = try await provider.request(
       .detail(battleId: battleId)

Projects/Data/Service/Sources/Battle/BattleService.swift

@@ -11,6 +11,7 @@ import Foundations
 import AsyncMoya
 
 public enum BattleService {
+  case today
   case detail(battleId: Int)
   case preVote(battleId: Int, body: PreVoteRequest)
   case postVote(battleId: Int, body: PreVoteRequest)
@@ -29,6 +30,8 @@ extension BattleService: BaseTargetType {
 
   public var urlPath: String {
     switch self {
+    case .today:
+      return BattleAPI.today.description
     case let .detail(battleId):
       return BattleAPI.detail(battleId: battleId).description
     case let .preVote(battleId, _):
@@ -54,7 +57,7 @@ extension BattleService: BaseTargetType {
 
   public var method: Moya.Method {
     switch self {
-    case .detail, .scenario, .voteStats, .perspectives, .myPerspective, .recommendations:
+    case .today, .detail, .scenario, .voteStats, .perspectives, .myPerspective, .recommendations:
       return .get
     case .preVote, .postVote, .createPerspective:
       return .post
@@ -63,6 +66,8 @@ extension BattleService: BaseTargetType {
 
   public var parameters: [String: Any]? {
     switch self {
+    case .today:
+      return nil
     case .detail:
       return nil
     case let .preVote(_, body):

Projects/Domain/DomainInterface/Sources/Battle/BattleInterface.swift

@@ -8,6 +8,7 @@ import Foundation
 import WeaveDI
 
 public protocol BattleInterface: Sendable {
+  func fetchTodayBattles() async throws -> TodayBattlePage
   func fetchBattle(battleId: Int) async throws -> BattleDetail
   func submitPreVote(
     battleId: Int,

Projects/Domain/DomainInterface/Sources/Battle/DefaultBattleRepositoryImpl.swift

@@ -9,6 +9,10 @@ import Foundation
 public struct DefaultBattleRepositoryImpl: BattleInterface {
   public init() {}
 
+  public func fetchTodayBattles() async throws -> TodayBattlePage {
+    TodayBattlePage(items: [], totalCount: 0)
+  }
+
   public func fetchBattle(battleId _: Int) async throws -> BattleDetail {
     BattleDetail(
       battleInfo: BattleInfo(

Projects/Domain/Entity/Sources/Battle/TodayBattlePage.swift

@@ -0,0 +1,21 @@
+//
+//  TodayBattlePage.swift
+//  Entity
+//
+//  `GET /api/v1/battles/today` 응답 도메인 모델. 아이템은 BattleInfo 재사용.
+//
+
+import Foundation
+
+public struct TodayBattlePage: Equatable {
+  public let items: [BattleInfo]
+  public let totalCount: Int
+
+  public init(
+    items: [BattleInfo],
+    totalCount: Int
+  ) {
+    self.items = items
+    self.totalCount = totalCount
+  }
+}

Projects/Domain/Entity/Sources/Home/Scenario/BattleScenario+.swift

@@ -0,0 +1,22 @@
+//
+//  BattleScenario+Timeline.swift
+//  Entity
+//
+//  시나리오 타임라인 계산.
+//
+
+import Foundation
+
+public extension BattleScenario {
+  /// 노드 시작 시간(초) = 노드 내 대사 startTimeMs 최소값.
+  func nodeStartTime(for nodeId: Int) -> TimeInterval {
+    guard let node = nodes.first(where: { $0.nodeId == nodeId }) else { return 0 }
+    return TimeInterval(node.scripts.map(\.startTimeMs).min() ?? 0) / 1000
+  }
+
+  /// 노드 종료 시간(초) = 노드 시작 + audioDuration.
+  func nodeEndTime(for node: ScenarioNode) -> TimeInterval {
+    let start = TimeInterval(node.scripts.map(\.startTimeMs).min() ?? 0) / 1000
+    return start + TimeInterval(node.audioDuration)
+  }
+}

Projects/Presentation/Chat/Sources/Vote/Model/ShareContent.swift → Projects/Domain/Entity/Sources/Share/ShareContent.swift

@@ -1,8 +1,9 @@
 //
 //  ShareContent.swift
-//  Chat
+//  Entity
 //
 //  공유 시트에 실어 보낼 컨텐츠 묶음. 카드 스냅샷(우선) + 썸네일(fallback) + 본문 텍스트 + URL.
+//  (PreVote / 오늘의 배틀 등 공용)
 //
 
 import Foundation

Projects/Presentation/Chat/Sources/Vote/Model/ShareItem.swift → Projects/Domain/Entity/Sources/Share/ShareItem.swift

@@ -1,8 +1,8 @@
 //
 //  ShareItem.swift
-//  Chat
+//  Entity
 //
-//  공유 시트 트리거. `.sheet(item:)` 에 바로 바인딩한다.
+//  공유 시트 트리거. `.sheet(item:)` 에 바로 바인딩한다. (PreVote / 오늘의 배틀 등 공용)
 //
 
 import Foundation

Projects/Domain/UseCase/Sources/Battle/BattleUseCase.swift

@@ -15,6 +15,10 @@ public struct BattleUseCaseImpl: BattleInterface {
 
   public init() {}
 
+  public func fetchTodayBattles() async throws -> TodayBattlePage {
+    return try await battleRepository.fetchTodayBattles()
+  }
+
   public func fetchBattle(battleId: Int) async throws -> BattleDetail {
     return try await battleRepository.fetchBattle(battleId: battleId)
   }

Projects/Presentation/Battle/Project.swift

@@ -0,0 +1,20 @@
+import DependencyPackagePlugin
+import DependencyPlugin
+import Foundation
+import ProjectDescription
+import ProjectTemplatePlugin
+
+let project = Project.makeAppModule(
+  name: "Battle",
+  bundleId: .appBundleID(name: ".Battle"),
+  product: .staticFramework,
+  settings: .settings(),
+  dependencies: [
+    .Presentation(implements: .Chat),
+    .Shared(implements: .Shared),
+    .Domain(implements: .UseCase),
+    .SPM.composableArchitecture,
+    .SPM.tcaFlow,
+  ],
+  sources: ["Sources/**"]
+)