Repository Guidelines

Project Structure & Module Organization

This is a Java 21, Spring Boot 3.4 Gradle application. Production code lives under src/main/java/com/hlab/yanalyst. Keep feature entities, repositories, services, controllers, and DTOs in domain/<feature>/; shared configuration, scheduling, errors, and response types belong in global/. Cross-feature integrations are in service/, while page controllers and general APIs are in web/.

Templates are in src/main/resources/templates, browser assets in src/main/resources/static, and application configuration in src/main/resources/application*.yml. Tests mirror production packages under src/test/java; fixtures belong in src/test/resources. Design notes and implementation plans live in docs/superpowers/.

Build, Test, and Development Commands

Use the checked-in Gradle wrapper; on Windows run:

.\gradlew.bat bootRun: start the UI and API at http://localhost:8088.
.\gradlew.bat test: run the JUnit 5 test suite.
.\gradlew.bat test --tests "com.hlab.yanalyst.domain.channel.SrtFormatterTest": run one test class.
.\gradlew.bat build: compile, test, and create the application artifact.
.\gradlew.bat clean build: rebuild from clean output.

Coding Style & Naming Conventions

Use four-space indentation and standard Java conventions: PascalCase types, camelCase members, and lowercase packages. Name Spring components by responsibility (ChannelService, FeedController, ChannelRepository) and DTOs with a Dto suffix. Use existing ApiResponse<T> wrappers for JSON endpoints. Keep Thymeleaf pages consistent with layout/base.html and reuse static/css/variables.css. No formatter is enforced, so match nearby code.

Testing Guidelines

Tests use JUnit 5, Spring Boot Test, and Mockito. Name test classes <Subject>Test and test methods for observable behavior, such as parsesShortLink. Add unit tests for parsing and domain logic; use Spring context tests only when integration behavior requires them. There is no explicit coverage threshold, but changed logic should include regression coverage.

Commit & Pull Request Guidelines

Recent commits use short prefixes such as feat: and docs:, followed by a concise Korean description. Keep each commit scoped to one change. Pull requests should explain the purpose, summarize implementation and verification, link relevant issues or design documents, and include screenshots for Thymeleaf/CSS changes. Call out configuration or database-schema effects explicitly.

Security & Configuration

Copy application-local.yml.example to the ignored application-local.yml for local settings. Never commit database credentials, API keys, Google OAuth files, tokens/, logs, downloads, or generated media. Use environment variables such as DB_URL, DB_USERNAME, DB_PASSWORD, and YOUTUBE_API_KEY.

2.8 KiB Raw Blame History