docs: @mandujs/query 래퍼 도입 기획서 추가

[RaptBliss]

요약

• TanStack Query 포크가 아닌 Mandu 최적 thin wrapper 전략의 도입 기획서를 추가했습니다.
• 문서 경로: docs/plans/16_mandu_query_wrapper_plan.md

포함 내용

• 배경/목표/비목표
• 핵심 원칙 (Upstream First, Thin Wrapper)
• MVP API 제안 (ManduQueryProvider, route key helper, SSR hydrate/dehydrate, SSE invalidation)
• 단계별 실행 계획 (Phase 0~4)
• KPI/리스크/Exit Criteria

기대 효과

• Mandu 프로젝트에서 query/mutation/cache/invalidation 패턴 표준화
• SSR + island + realtime 조합의 재현성과 운영 품질 향상
• TanStack 업스트림 생태계를 유지하면서 Mandu DX 강화

[gemini-code-assist]

Summary of Changes

Hello @RaptBliss, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

이 PR은 Mandu 프로젝트의 데이터 패칭 및 캐싱 전략을 표준화하기 위한 @mandujs/query 래퍼 도입 기획서를 추가합니다. TanStack Query의 강력한 기능을 활용하되, Mandu 환경에 특화된 규칙과 헬퍼를 제공하는 얇은 래퍼를 통해 개발자 경험과 운영 일관성을 향상시키는 것이 주된 목적입니다. 특히 SSR, Island 아키텍처 및 실시간 데이터 동기화 시나리오에서 발생할 수 있는 문제들을 해결하고, 표준화된 접근 방식을 제시하여 프로젝트 전반의 품질을 높이는 데 기여할 것입니다.

Highlights

• @mandujs/query 래퍼 도입 기획서 추가: TanStack Query를 포크하는 대신, Mandu 프로젝트에 최적화된 얇은 래퍼 전략을 제안하는 기획서가 추가되었습니다.
• 데이터 패칭 패턴 표준화: Mandu 앱 내에서 데이터 패칭, 캐시, 무효화 패턴을 표준화하고 SSR, Island, 실시간(SSE) 환경에서의 일관성을 개선하는 것을 목표로 합니다.
• MVP API 제안: ManduQueryProvider, route key 헬퍼, SSR hydrate/dehydrate, SSE invalidation 등 핵심 API 제안이 포함되어 있습니다.

Changelog

• docs/plans/16_mandu_query_wrapper_plan.md
  • Mandu Query Wrapper 도입 기획서가 추가되었습니다.

Activity

• 현재까지 기록된 활동이 없습니다.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

이 PR은 @mandujs/query 도입을 위한 잘 구조화되고 포괄적인 기획서를 추가합니다. TanStack Query 위에 얇은 래퍼를 만드는 전략은 Mandu 프로젝트 내 표준화를 이루면서도 업스트림 생태계를 활용하는 좋은 접근 방식입니다. 문서는 배경, 목표, API 설계, 그리고 출시 계획을 명확하게 설명하고 있습니다. API 설계와 기본 동작을 더욱 명확히 하여 기획의 완성도를 높일 수 있는 몇 가지 사소한 제안을 리뷰 코멘트에 남겼습니다. 전반적으로 개발을 효과적으로 이끌어줄 훌륭한 기획 문서입니다.

[gemini-code-assist]

getRouteQueryKey 함수의 scope 파라미터의 역할이 명확하지 않습니다. 이 파라미터가 어떻게 사용되는지에 대한 간단한 설명이나 예시를 추가하면 좋을 것 같습니다. 예를 들어, 같은 라우트 내에서 다른 데이터 집합('list', 'detail' 등)을 구분하기 위한 것인지 명시해주면 개발자들이 사용법을 더 잘 이해하는 데 도움이 될 것입니다.

[gemini-code-assist]

기획서에 재시도는 idempotent한 쿼리에만 적용된다고 명시된 점이 좋습니다. 하지만 래퍼가 쿼리의 idempotent 여부를 어떻게 판단할지에 대한 설명이 부족합니다. useManduQuery의 옵션으로 명시적으로 전달하는 방식을 제안하는 것이 좋습니다. 예를 들어, useManduQuery({ ..., retry: 2, isIdempotent: true })와 같이 API를 설계하면 계약이 명확해지고 더 안전한 사용을 유도할 수 있습니다. 이 내용을 4) 제안 API (MVP) 섹션에 추가하면 기획이 더 견고해질 것입니다.

[coderabbitai]

Warning

Rate limit exceeded

@konamgil has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 29 minutes and 57 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 4f8a0ae and ff13514.

📒 Files selected for processing (1)

• docs/plans/16_mandu_query_wrapper_plan.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/mandu-query-wrapper-plan

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}