모여를 만들며 정한 프론트엔드의 기준

function PostsPage() {
  return (
    <VStack gap={6}>
      {/* 제목일까, 프로필일까? Header만으로는 모르겠다. */}
      <PostsHeader />
      {/* 사진? 본문? 목록? 검색창도 이 안에 있나? */}
      <PostsContents />
      {/* 페이지 번호일까, 작성 버튼일까? Footer만으로는 모르겠다. */}
      <PostsFooter />
    </VStack>
  );
}tsx

// QueryBoundary는 Suspense와 오류 경계를 묶은 공통 컴포넌트다.
function PostsPage() {
  const [view, setView] = usePostView();
  const [{ query, status }, setFilters] = usePostFilters();

  return (
    <VStack gap={6}>
      <Heading level={1}>게시물</Heading>

      <Tabs
        value={view}
        onValueChange={(value) => setView(postViewSchema.parse(value))}
      >
        <TabsList>
          <TabsTrigger value={PostView.channelPosts}>채널 게시물</TabsTrigger>
          <TabsTrigger value={PostView.posts}>모여 게시물</TabsTrigger>
        </TabsList>
      </Tabs>

      {match(view)
        .with(PostView.channelPosts, () => (
          <QueryBoundary
            pending={<ChannelPostList.Loading />}
            error={ChannelPostList.Error}
          >
            <ChannelPostList />
          </QueryBoundary>
        ))
        .with(PostView.posts, () => (
          <VStack gap={4}>
            <Input
              aria-label="게시물 검색"
              placeholder="본문으로 검색"
              maxLength={200}
              value={query}
              onChange={(event) =>
                setFilters({ query: event.currentTarget.value })
              }
            />
            <PostStatusInput
              aria-label="게시물 상태"
              value={status}
              onChange={(status) => setFilters({ status })}
            />

            <QueryBoundary
              pending={<PostList.Loading />}
              error={PostList.Error}
              resetKeys={[query, status]}
            >
              <PostList
                filters={{
                  searchText: query.trim() || undefined,
                  statuses: status === "all" ? undefined : [status],
                }}
                pageSize={20}
              />
            </QueryBoundary>
          </VStack>
        ))
        .exhaustive()}
    </VStack>
  );
}tsx

type ExpandedPostView = "channel_posts" | "posts" | "scheduled";

function getPostViewLabel(view: ExpandedPostView) {
  switch (view) {
    case "channel_posts":
      return "채널 게시물";
    case "posts":
      return "모여 게시물";
    default:
      return "모여 게시물"; // 예약 글도 이 이름으로 표시된다.
  }
}ts

import { match } from "ts-pattern";

// 같은 ExpandedPostView 타입을 사용한다.
function getPostViewLabel(view: ExpandedPostView) {
  return match(view)
    .with("channel_posts", () => "채널 게시물")
    .with("posts", () => "모여 게시물")
    // 'scheduled' 분기가 빠져 있어 타입 오류가 난다.
    .exhaustive();
}ts

<div className="flex flex-col gap-4">
  <div className="flex flex-row items-center justify-between gap-2">
    <h2 className="text-title2 text-foreground text-balance">게시물</h2>
    <Button onClick={openComposer}>글쓰기</Button>
  </div>
  <p className="text-body1 text-muted-foreground">
    채널에 올릴 글을 작성하고 예약할 수 있어요.
  </p>
</div>tsx

<VStack gap={4}>
  <HStack justify="between">
    <Heading level={2}>게시물</Heading>
    <Button onClick={openComposer}>글쓰기</Button>
  </HStack>
  <Text color="muted">
    채널에 올릴 글을 작성하고 예약할 수 있어요.
  </Text>
</VStack>tsx

- 배치는 packages/ui의 VStack, HStack, Center, Grid를 우선 사용한다.
- 제목은 Heading, 본문은 Text로 작성하고 공통 간격·글자 토큰을 사용한다.
- 추가 스타일은 className으로 지정하고, 조건부 클래스는 cn으로 조합한다.md

<InputGroup>
  <InputGroupInput
    aria-label="상품 가격"
    placeholder="가격을 입력하세요"
    inputMode="numeric"
    value={productPrice == null ? "" : formatCount(productPrice, locale)}
    onChange={(event) =>
      setProductPrice(parseAmountText(event.currentTarget.value))
    }
  />
  <InputGroupAddon align="inline-end">
    <InputGroupText>원</InputGroupText>
  </InputGroupAddon>
</InputGroup>tsx

<AmountInput
  aria-label="상품 가격"
  value={productPrice}
  onChange={setProductPrice}
  suffix="원"
  placeholder="가격을 입력하세요"
/>tsx

import type { ComponentProps, ReactNode } from "react";

interface AmountInputProps extends Omit<
  ComponentProps<typeof InputGroupInput>,
  "defaultValue" | "inputMode" | "value" | "onChange"
> {
  value?: number | null;
  onChange: (value: number | null) => void;
  suffix?: ReactNode;
}ts

// formatCount는 언어 설정(locale)에 맞춰 숫자에 자릿수 구분을 넣는다.
<InputGroupInput
  {...inputProps}
  inputMode="numeric"
  value={value == null ? "" : formatCount(value, locale)}
  onChange={(event) =>
    onChange(parseAmountText(event.currentTarget.value))
  }
/>tsx

const MAX_AMOUNT_DIGITS = 12;
const NON_DIGIT_PATTERN = /\D/gu;

function parseAmountText(text: string): number | null {
  const digits = text
    .replaceAll(NON_DIGIT_PATTERN, "")
    .slice(0, MAX_AMOUNT_DIGITS);

  return digits.length === 0 ? null : Number(digits);
}ts

import { noop } from "es-toolkit";

// onChange가 optional이면 호출자가 빠뜨려도 통과한다.
const onChange = props.onChange ?? noop;
onChange(12_900); // 함수가 없으면 사용자가 입력해도 값이 바뀌지 않는다.ts

const rows = [
  { id: "text", label: "본문", value: post.text },
  {
    id: "attachments",
    label: "첨부 파일",
    value: `${post.attachments.length}개`,
  },
  { id: "status", label: "게시 상태", value: post.status },
];

rows.map((row) => (
  <PostInfoRow
    key={row.id}
    label={row.label}
    value={
      row.id === "status"
        ? <PostStatusBadge post={post} />
        : row.value
    }
  />
));tsx

// @moyeo/api는 서버와 웹이 함께 쓰는 API 계약 패키지다.
import type { PostRecord } from "@moyeo/api";
import { Card, CardContent } from "@moyeo/ui/components/card";

PostInfoCard.Content = function Content({ post }: { post: PostRecord }) {
  return (
    <Card>
      <CardContent>
        <VStack gap={4}>
          <PostInfoRow label="본문" value={post.text} />
          <PostInfoRow
            label="첨부 파일"
            value={`${post.attachments.length}개`}
          />
          <PostInfoRow
            label="게시 상태"
            // 다른 행은 그대로 두고, 이 값만 바꾼다.
            value={<PostStatusBadge post={post} />}
          />
        </VStack>
      </CardContent>
    </Card>
  );
};tsx

export function PostInfoCard({ post }: { post: PostRecord | null }) {
  if (post == null) {
    return <PostInfoCard.Empty />;
  }

  return <PostInfoCard.Content post={post} />;
}

PostInfoCard.Empty = function Empty() {
  return (
    <Card>
      <CardContent>
        <Message text="목록에서 게시물을 선택해 주세요." />
      </CardContent>
    </Card>
  );
};tsx

import type { ReactNode } from "react";

function PostInfoRow({ label, value }: { label: string; value: ReactNode }) {
  return (
    <VStack gap={1}>
      <Text variant="caption" color="muted">{label}</Text>
      <Text variant="body2" weight="medium">{value}</Text>
    </VStack>
  );
}

function Message({ text }: { text: string }) {
  return (
    <Text variant="body2" color="muted">
      {text}
    </Text>
  );
}tsx

function PostsPage() {
  const [view, setView] = usePostView();
  const [{ query, status }, setFilters] = usePostFilters();

  // 중략
}

// 각 위치의 의미와 타입을 정한다.
type PostViewState = readonly [
  view: PostView,
  setView: (nextView: PostView) => void,
];ts

import { postStatusSchema } from "@moyeo/api";
import { z } from "zod";

const PostView = {
  channelPosts: "channel_posts",
  posts: "posts",
} as const;

const postViewSchema = z.enum(PostView);
type PostView = z.infer<typeof postViewSchema>;

// 'all'은 특정 게시물 상태가 아니라, 상태를 제한하지 않는 보기다.
const postStatusFilterSchema = z.enum(["all", ...postStatusSchema.options]);

const postsSearchSchema = z.object({
  view: postViewSchema
    .default(PostView.channelPosts)
    .catch(PostView.channelPosts),
  status: postStatusFilterSchema.default("all").catch("all"),
  q: z.string().max(200).optional().catch(undefined),
});

type PostsSearch = z.output<typeof postsSearchSchema>;ts

// postsRouteApi로 게시물 라우트의 검색 조건을 읽고 변경한다.
function usePostView(): PostViewState {
  const view = postsRouteApi.useSearch({ select: (search) => search.view });
  const navigate = postsRouteApi.useNavigate();
  const reporter = useErrorReporter();

  const setView = (nextView: PostView) => {
    runInBackground(
      navigate({
        search: (previousSearch) => ({ ...previousSearch, view: nextView }),
      }),
      reporter,
      { source: "navigation", operation: "posts.view" },
    );
  };

  return [view, setView] as const;
}ts

import { useStoredValue } from "@/shared/storage/hooks/use-stored-value";
import {
  createWebStorageStore,
} from "@/shared/storage/utils/create-web-storage-store";

const postViewStore = createWebStorageStore({
  area: "local",
  key: "moyeo.posts.view",
  schema: postViewSchema,
});

function usePostView(): PostViewState {
  const [view, setView] = useStoredValue(postViewStore, PostView.channelPosts);

  return [view, setView];
}ts

await navigate({
  search: (previousSearch) => ({
    ...previousSearch, // 기존 검색어와 보기 선택을 유지한다.
    status: "draft", // 상태만 임시 저장으로 바꾼다.
  }),
  replace: true,
});ts

setFilters({ status: "draft" }); // 검색어를 유지한다.
setFilters({ query: "신메뉴 출시" }); // 임시 저장 조건을 유지한다.ts

import { Link } from "@tanstack/react-router";

<Link
  to="/workspaces/$workspaceId/posts"
  params={{ workspaceId }}
  search={{ view: "posts", status: "draft", q: "신메뉴" }}
>
  임시 저장한 신메뉴 안내 보기
</Link>tsx

"use client";

import { useSearchParams } from "next/navigation";

function PostsPage() {
  const searchParams = useSearchParams();
  const view = searchParams.get("view") ?? "channel_posts";
  // ?view=unknown이면 view는 그대로 "unknown"이다.

  // 중략
}ts

"use client";

import { parseAsStringLiteral, useQueryState } from "nuqs";

function PostsPage() {
  const [view, setView] = useQueryState(
    "view",
    parseAsStringLiteral(["channel_posts", "posts"])
      .withDefault("channel_posts"), // 잘못된 값도 기본 보기로 읽는다.
  );

  // 중략
}ts

// 임시 저장한 글을 보고 싶은데, 페이지 이름부터 알려 줘야 한다.
<PostList
  isDraftPage
  pageSize={20}
/>tsx

// 같은 임시 저장 목록이다. 조회할 상태를 직접 전달한다.
<PostList
  filters={{ statuses: ["draft"] }}
  pageSize={20}
/>tsx

<QueryBoundary
  pending={<PostList.Loading />}
  error={PostList.Error}
>
  <PostList
    filters={{ statuses: ["draft"] }}
    pageSize={20}
  />
</QueryBoundary>tsx

PostList.Loading = () => <ListSkeleton rowCount={3} />;
PostList.Error = (props: FallbackProps) => (
  <QueryState.Error {...props} title="게시물을 불러오지 못했어요" />
);tsx

import { range } from "es-toolkit";

range(3).map((index) => (
  <Skeleton key={index} className="h-4 w-20" />
));tsx

function PostList({ filters, pageSize = 20 }: PostListProps) {
  const { workspaceId } = workspaceRouteApi.useParams();
  const orpc = useOrpc();
  const { data } = useSuspenseInfiniteQuery(
    postListInfiniteOptions(orpc, { workspaceId, ...filters, limit: pageSize }),
  );
  const posts = data.pages.flatMap((page) => page.items);

  // 중략
}tsx

import type { InfiniteData } from "@tanstack/react-query";
import type { ListPostsInput, PostList as PostListOutput } from "@moyeo/api";

interface PostListProps {
  // 공유 요청 타입에서 목록의 사용처가 정할 조건만 받는다.
  filters?: Pick<ListPostsInput["query"], "searchText" | "statuses">;
  pageSize?: number;
}

// [첫 페이지의 글들], [다음 페이지의 글들] → 하나의 게시물 목록
function selectPosts(data: InfiniteData<PostListOutput>) {
  return data.pages.flatMap((page) => page.items);
}

function PostList({ filters, pageSize = 20 }: PostListProps) {
  const { workspaceId } = workspaceRouteApi.useParams();
  const orpc = useOrpc();
  const { data: posts, fetchNextPage } = useSuspenseInfiniteQuery({
    // 조회 조건에 맞는 캐시 키와 다음 페이지 설정을 만든다.
    ...postListInfiniteOptions(orpc, {
      workspaceId,
      ...filters,
      limit: pageSize,
    }),
    select: selectPosts,
  });

  // 중략
}tsx

import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute(
  // _authenticated와 _app는 URL에 나타나지 않는 레이아웃이다.
  "/_authenticated/workspaces/$workspaceId/_app/posts",
)({
  validateSearch: postsSearchSchema,
  loaderDeps: ({ search }) => ({
    view: search.view,
    query: search.q ?? "", // 검색어가 없으면 빈 입력으로 다룬다.
    status: search.status,
  }),
  loader: async ({ context, params, deps }) => {
    if (deps.view !== "posts") {
      return;
    }

    await context.queryClient.infiniteQuery(
      postListInfiniteOptions(context.orpc, {
        workspaceId: params.workspaceId,
        searchText: deps.query.trim() || undefined,
        statuses: deps.status === "all" ? undefined : [deps.status],
        limit: 20,
      }),
    );
  },
});ts

// 서버의 게시물 응답
const postDetailSchema = z.object({
  id: z.string(),
  text: z.string(),
});

// 서버 정의가 바뀌어도 이 타입은 그대로 남는다.
type PostResponse = { id: string; text: string };ts

import { oc } from "@orpc/contract";
import { openapi } from "@orpc/openapi";
import { z } from "zod";

// packages/api: 게시물 응답 중 ID와 본문만 남겼다.
export const postDetailSchema = z.object({
  id: z.string(),
  text: z.string(),
});

export type PostRecord = z.infer<typeof postDetailSchema>;

export const getPostContract = oc
  .meta(openapi({
    method: "GET",
    path: "/workspaces/{workspaceId}/posts/{postId}",
    inputStructure: "detailed", // params를 HTTP 경로에 연결한다.
  }))
  .input(
    z.object({
      params: z.object({
        workspaceId: z.string(),
        postId: z.string(),
      }),
    }),
  )
  .output(postDetailSchema);ts

function PostArticle() {
  const { workspaceId, postId } = postDetailRouteApi.useParams();
  const orpc = useOrpc();
  const { data: post } = useSuspenseQuery(
    orpc.publishing.getPost.queryOptions({
      input: { params: { workspaceId, postId } },
    }),
  );

  // 응답 타입을 따로 적지 않아도 본문이 문자열임을 알 수 있다.
  return <Text>{post.text}</Text>;
}tsx

function ChannelConnectButton() {
  const role = useWorkspaceAccessContext(
    (context) => context.currentMembership.role,
  );

  // 중략
  const canConnect = role === "owner" || role === "admin";

  return <Button disabled={!canConnect}>채널 연결</Button>;
}tsx

function ChannelConnectButton() {
  const availability = useWorkspaceAccessContext(
    (context) => context.actions.connectChannel,
  );

  // 중략
  return (
    <ActionButton
      availability={availability}
      reasonMessages={CHANNEL_CONNECT_REASON_MESSAGES}
    >
      채널 연결
    </ActionButton>
  );
}tsx

const needsPolling = publications.some((publication) =>
  ["publishing", "retry_wait", "unconfirmed"].includes(publication.status) ||
  (publication.status === "scheduled" &&
    publication.schedule != null &&
    Date.parse(publication.schedule.scheduledAt) - nowMs < 2 * 60_000),
);ts

import type { PublicationListItem } from "@moyeo/api";

const POLLING_WINDOW_MS = 2 * 60_000;

export function isInProgress(publication: PublicationListItem) {
  return ["publishing", "retry_wait", "unconfirmed"].includes(
    publication.status,
  );
}

export function isScheduleDueSoon(
  publication: PublicationListItem,
  nowMs: number,
) {
  const { status, schedule } = publication;

  if (status !== "scheduled" || schedule == null) {
    return false;
  }

  const remainingMs = Date.parse(schedule.scheduledAt) - nowMs;
  return remainingMs < POLLING_WINDOW_MS;
}

export const PublicationPolicy = {
  shouldPoll(publication: PublicationListItem, nowMs: number) {
    return (
      isInProgress(publication) ||
      isScheduleDueSoon(publication, nowMs) 
    );
  },
};ts

const needsPolling = publications.some((publication) =>
  PublicationPolicy.shouldPoll(publication, nowMs),
);ts

import { createPublicationListItemFixture } from "@moyeo/api/testing";
import { expect, it } from "vitest";
import { PublicationPolicy } from "./publication.model";

it("예약 시각이 2분 미만으로 남으면 다시 확인한다", () => {
  // Given
  const nowMs = Date.parse("2026-10-11T00:00:00Z");
  // 나머지 필수값은 테스트용 생성 함수가 채운다.
  const publication = createPublicationListItemFixture({
    status: "scheduled",
    scheduledAt: "2026-10-11T00:01:59Z",
  });

  // When
  const shouldPoll = PublicationPolicy.shouldPoll(publication, nowMs);

  // Then
  expect(shouldPoll).toBe(true);
});ts

async function hashBlob(blob: Blob) {
  const fileBytes = await blob.arrayBuffer();
  const digest = await crypto.subtle.digest("SHA-256", fileBytes);

  return Array.from(new Uint8Array(digest), (byte) =>
    byte.toString(16).padStart(2, "0"),
  ).join("");
}ts

import { createSHA256 } from "hash-wasm";

async function hashBlobInChunks(blob: Blob, signal?: AbortSignal) {
  const hasher = await createSHA256();
  hasher.init();

  const chunkBytes = 8 * 1_024 * 1_024;

  for (let offset = 0; offset < blob.size; offset += chunkBytes) {
    signal?.throwIfAborted();

    // 전체 파일 대신 이번에 계산할 8MiB만 읽는다.
    const chunkBuffer = await blob
      .slice(offset, offset + chunkBytes)
      .arrayBuffer();
    hasher.update(new Uint8Array(chunkBuffer));
  }

  signal?.throwIfAborted();
  return hasher.digest("hex");
}ts

function PostComposer() {
  // 중략
  function applySuggestion(suggestedText: string) {
    // 응답을 기다리는 사이 수정한 본문도 덮어쓴다.
    form.setValue("baseText", suggestedText);
  }
  // 중략
}ts

type DraftSnapshot = {
  text: string;
  channelId: string;
};

function resolveSuggestedText(
  requestedDraft: DraftSnapshot,
  currentDraft: DraftSnapshot,
  suggestedText: string,
) {
  const isUnchanged =
    requestedDraft.text === currentDraft.text &&
    requestedDraft.channelId === currentDraft.channelId;

  return isUnchanged ? suggestedText : currentDraft.text;
}ts

const scheduleInput = {
  scheduledLocalDate: "2026-11-01",
  scheduledLocalTime: "01:30",
  scheduledTimeZone: "America/New_York",
};ts

# apps/server/Dockerfile의 실행 단계
ENV TZ=UTCdockerfile

import { z } from "zod";

// packages/env/src/server/fields/process.fields.ts 중 일부
export const processFields = {
  TZ: z.literal("UTC", "TZ는 UTC여야 합니다.").default("UTC"),
};ts

function ScheduledPostTime({
  scheduledAt,
}: { scheduledAt: string }) {
  return (
    <time dateTime={scheduledAt}>
      {new Date(scheduledAt)
        .toLocaleString()}
    </time>
  );
}tsx

function ScheduledPostTime({
  scheduledAt,
}: { scheduledAt: string }) {
  const { locale, timeZone } = useAuthContext(
    (context) => context.preferences,
  );

  return (
    <time dateTime={scheduledAt}>
      {new Date(scheduledAt).toLocaleString(
        locale,
        { timeZone },
      )}
    </time>
  );
}tsx

function ScheduledPostTime({
  scheduledAt,
}: { scheduledAt: string }) {
  const viewer = useAuthContext(
    (context) => context.preferences,
  );
  // 서버와 첫 클라이언트 렌더링이 공유한다.
  const nowAt = useNowAt();

  return (
    <time dateTime={scheduledAt}>
      {formatUpcomingInstant(
        nowAt,
        scheduledAt,
        viewer,
      )}
    </time>
  );
}tsx

import {
  notificationStreamEventSchema,
  watchNotificationsInputSchema,
} from "@moyeo/api";
import { asyncIteratorObject, oc } from "@orpc/contract";

export const watchNotificationsContract = oc
  .input(watchNotificationsInputSchema)
  // 공유 스키마로 스트림의 각 이벤트를 검사한다.
  .output(asyncIteratorObject(notificationStreamEventSchema));ts

import type { WorkspaceChangedEvent } from "@moyeo/api";
import { consumeAsyncIterator } from "@orpc/client";
import type { OrpcQueryUtils } from "@/api/create-api-client";

function subscribeToPostChanges(
  orpc: OrpcQueryUtils,
  signal: AbortSignal,
  onPostsChanged: (change: WorkspaceChangedEvent) => void,
) {
  return consumeAsyncIterator(
    orpc.notification.watchNotifications.call(
      { query: { scopes: ["publishing"] }, headers: {}, body: undefined },
      { signal },
    ),
    {
      onEvent(event) {
        if (event.type !== "publishing_changed") {
          return;
        }

        // 게시물 ID와 작업 공간을 담은 이벤트만 갱신 함수에 전달한다.
        onPostsChanged(event);
      },
    },
  );
}ts

function handleScheduleSubmit() {
  gtag("event", "post_schedule_submitted", {
    mode: "fixed_time",
    channel_count: selectedChannels.length, // GA에 맞춘 속성 이름이다.
  });

  // 중략
}ts

import { z } from "zod";

const analyticsEventSchema = z.strictObject({
  name: z.literal("post_schedule_submitted"),
  mode: z.enum(["next_available", "fixed_time", "publish_now"]),
  channelCount: z.int().positive(), // 게시 대상 채널은 한 개 이상이다.
});

type AnalyticsEvent = z.infer<typeof analyticsEventSchema>;ts

function PostComposer() {
  const analytics = useAnalytics();

  // 중략

  function handleScheduleSubmit() {
    // 요청 제출을 기록한다. 외부 SNS의 게시 완료를 뜻하지 않는다.
    analytics.track({
      name: "post_schedule_submitted",
      mode: "fixed_time",
      channelCount: selectedChannels.length,
    });

    // 중략
  }

  // 중략
}ts

interface AnalyticsProvider {
  track(event: AnalyticsEvent): void;
}

function createAnalytics(provider: AnalyticsProvider) {
  return {
    track(event: AnalyticsEvent) {
      const result = analyticsEventSchema.safeParse(event);
      if (!result.success) {
        return;
      }

      try {
        provider.track(result.data);
      } catch {
        // 분석 호출의 실패가 게시나 결제를 막지 않게 한다.
      }
    },
  };
}ts