superport_v2/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

Place all Flutter source in lib/, keeping cross-cutting pieces in lib/core/ (config, constants, services) and feature screens under lib/features/<domain>/. Shared widgets and theming go in lib/widgets/ and lib/theme/. Tests mirror this layout in test/ and, when browser flows matter, integration_test/. Static specs, including the UI breakdown in doc/입출고 대여 폼 정리.md, stay in doc/. Keep assets in assets/ and register them inside pubspec.yaml.

Build, Test, and Development Commands

• flutter pub get — install or refresh package dependencies.
• flutter analyze — static analysis; treat warnings as blockers before review.
• flutter test — run the unit/widget suite; add --coverage when validating overall health.
• flutter run -d chrome --web-renderer canvaskit — local web run matching production rendering.
• dart run build_runner build --delete-conflicting-outputs — regenerate freezed/json_serializable files when models change.

Coding Style & Naming Conventions

Use Flutter’s two-space indentation and run dart format . before committing. Follow the Clean Architecture layering: DTOs/remote in data, domain interfaces/use cases in domain, controllers/widgets in presentation. File names use snake_case.dart; classes use UpperCamelCase; methods and fields use lowerCamelCase. Prefer const constructors/widgets, and use shadcn_ui components (especially ShadTable) for new screens. Register dependencies in lib/injection_container.dart via get_it.

Testing Guidelines

Each feature ships with unit tests (*_test.dart) living beside the source module. Widget tests should verify key flows like list rendering and form validation; leverage WidgetTester with fake data. Integration scenarios covering navigation across the inventory, approval, and reporting flows belong in integration_test/. Target meaningful coverage (≈70% per feature) and ensure CI-friendly seeds by avoiding real API calls.

Commit & Pull Request Guidelines

Commits follow the existing Superport convention: Korean imperative summaries with optional English technical nouns, e.g., "대여 상세 테이블 정렬 수정". For PRs, include (1) a concise summary of user-visible impact, (2) screenshots or GIFs for UI changes, (3) linked issue or JIRA reference, and (4) verification notes (commands run, tests passing). Squash before merge unless release tagging requires history.

Architecture & Environment Notes

Initialize environments via .env.development / .env.production and load them through Environment.initialize() before bootstrapping DI. New data sources should expose repository interfaces in domain/ and rely on the shared ApiClient instance. Do not use mock data in the application; always call the real backend (staging/production as appropriate). If an endpoint is not available, mark the feature as disabled behind a feature flag rather than mocking.

• Frontend behaviour/data models must strictly follow the deployed backend contract. (프론트엔드는 백엔드 API 계약을 절대 우선으로 준수해야 하며, 누락된 기능은 백엔드 수정 요청 후 진행한다.)

---

Language & Communication Policy

• This document (AGENTS.md) and repository guidelines are written in English.
• Assistant responses to users (conversations, task summaries, PR descriptions) must be in Korean by default, unless the user explicitly requests English.
• Code comments must be written in Korean (see “Commenting Policy — Korean”).
• User-facing UI copy is Korean-first unless a requirement states otherwise.
• Identifiers (class/variable/function/file names) remain in English following the naming conventions above.

---

Notification Policy

• Every task completion must trigger a notification via the configured notify.py workflow so users are consistently alerted.

---

SRP & Clean Architecture Enforcement

Apply these principles repo-wide. Use the checklist below during reviews.

• Single Responsibility Principle (SRP)

  • A class/file must have exactly one reason to change.
  • In widgets, separate layout/rendering from state/event handling. Move complex logic to controllers/use cases.
  • Extract form validation, transformations/mapping, sorting/filtering into dedicated utilities/services.
  • Avoid god pages/widgets (split when file > 400 LOC or a build method > 200 LOC).

• Clean Architecture boundaries

  • presentation: views/controllers/state (view models). No business rules or direct data access.
  • domain: entities, repository interfaces, use cases. No framework dependencies.
  • data: DTOs and data sources (API/local) implementing domain interfaces. Never depend on presentation.
  • DI: wire dependencies only in lib/injection_container.dart. No cross-layer back references.

• Dependency rule

  • Allowed direction is presentation → domain → data; never the reverse.
  • domain must not depend on flutter/*, shadcn_ui, or any UI packages.
  • data must not reference presentation. Convert DTOs to domain entities before exposing.

• UI composition (shadcn_ui)

  • Lists: standardize on ShadTable-based components; keep table/column specs in dedicated classes.
  • Forms: separate field widgets, validation logic, and dialog layout; manage form state in a controller.
  • Modals: use SuperportShadDialog consistently with header/body/footer sections.

• Testing

  • presentation: widget tests for rendering, interactions, and validation messages.
  • domain: unit tests for use-case scenarios.
  • data: contract tests for JSON mapping; never hit real network endpoints.

Networking Stack Guidelines

• Use a single ApiClient (Dio wrapper) for all HTTP calls; do not instantiate raw Dio per feature.
• Initialize env via Environment.initialize() before DI, then register ApiClient in lib/injection_container.dart and inject into repositories.
• Attach AuthInterceptor to handle token injection and 401 → refresh → retry. On refresh failure, clear session and navigate to login.
• Standardize query params: page, page_size, q, sort, order, updated_since, include.
• Keep logging in development only and redact secrets (tokens/cookies).

Commenting Policy — Korean

• Write comments in Korean for all public APIs, core logic, and business rules.
  • Public classes/methods: use /// doc comments in Korean (purpose, parameters, returns, exceptions, examples).
  • Complex branches/math/performance: use // line comments to explain intent and rationale.
  • Prefer Korean domain terms; include the English term in parentheses on first mention (e.g., 결재(approval)).
• Don’t: add meaningless comments, let comments drift from code, or mix excessive English.
• Do: document invariants, preconditions, side effects, and failure scenarios explicitly.

File/Function Size Guidelines

• Files over ~400 LOC: consider splitting (widgets/controllers/utils).
• Functions over ~60 LOC: refactor into private helpers.
• Widget tree nesting > 5 levels: extract sub-widgets.

Review Checklist (SRP/Clean)

• Does this file/class have exactly one reason to change?
• Are business rules absent from presentation?
• Does the domain layer avoid dependencies on frameworks/UI packages?
• Does the data layer avoid referencing presentation?
• Is DI centralized in lib/injection_container.dart?
• Are validation/transforms/sort/filter extracted into utilities/services?
• Are comments written in Korean and do they clearly cover intent/constraints/failure cases?