refactor(blog): 발행 정책 중앙화

dev-wooyeon · dev-wooyeon · commit 0f3d8063f50d · 2026-07-22T15:12:48.000+09:00
공개 Tech 글의 리뷰 하한과 featured 자격을 policy 모듈의 실행 기준으로 통합했습니다.

글별 큐레이션 데이터는 meta.json에 유지하고 ADR로 경계를 기록했습니다.
diff --git a/blog/services/policy.test.ts b/blog/services/policy.test.ts
@@ -1,9 +1,16 @@
 // @vitest-environment node
 
 import { describe, expect, it } from 'vitest';
-import type { FeedData, QualityReview } from '@/blog/model/types';
+import type { FeedData } from '@/blog/model/types';
 import { getAllFeedSlugs, getSortedFeedData } from './post-repository';
-import { filterVisiblePosts, isPostVisible } from './publication-policy';
+import {
+  filterVisiblePosts,
+  getCoreTechReviewAverage,
+  isEligibleForFeaturedPost,
+  isPostVisible,
+  meetsPublicTechReviewThreshold,
+  PUBLICATION_POLICY,
+} from './policy';
 
 const FEATURED_SLUGS = [
   'ctr-pipeline',
@@ -12,17 +19,6 @@ const FEATURED_SLUGS = [
   'msa-domain-workspace-submodule',
 ];
 
-function readCoreAverage(review: QualityReview | undefined): number | null {
-  const scores = [review?.philosophy, review?.design, review?.implementation];
-
-  if (scores.some((score) => typeof score !== 'number')) {
-    return null;
-  }
-
-  const [philosophy, design, implementation] = scores as number[];
-  return (philosophy + design + implementation) / 3;
-}
-
 function describePost(post: FeedData): string {
   return `${post.slug} (${post.title})`;
 }
@@ -40,6 +36,34 @@ describe('publication policy', () => {
     expect(filterVisiblePosts([privatePost, publicPost])).toEqual([publicPost]);
   });
 
+  it('keeps editorial thresholds in the policy module', () => {
+    expect(
+      meetsPublicTechReviewThreshold({
+        philosophy: 3.5,
+        design: 3.5,
+        implementation: 3.5,
+      })
+    ).toBe(true);
+    expect(meetsPublicTechReviewThreshold({})).toBe(false);
+
+    expect(
+      isEligibleForFeaturedPost({
+        category: 'Tech',
+        qualityReview: {
+          brandFit: PUBLICATION_POLICY.featured.minimumBrandFit,
+        },
+      })
+    ).toBe(true);
+    expect(
+      isEligibleForFeaturedPost({
+        category: 'Life',
+        qualityReview: {
+          brandFit: PUBLICATION_POLICY.featured.minimumBrandFit,
+        },
+      })
+    ).toBe(false);
+  });
+
   it('keeps every private post out of public listings and static paths', () => {
     const allPosts = getSortedFeedData({ includePrivate: true });
     const privatePosts = allPosts.filter(
@@ -70,17 +94,17 @@ describe('publication policy', () => {
     const offenses = getSortedFeedData()
       .filter((post) => post.category === 'Tech')
       .flatMap((post) => {
-        const average = readCoreAverage(post.qualityReview);
+        const average = getCoreTechReviewAverage(post.qualityReview);
 
-        if (average === null) {
-          return [
-            `${describePost(post)}: qualityReview core scores are incomplete`,
-          ];
-        }
+        if (!meetsPublicTechReviewThreshold(post.qualityReview)) {
+          if (average === null) {
+            return [
+              `${describePost(post)}: qualityReview core scores are incomplete`,
+            ];
+          }
 
-        if (average <= 3) {
           return [
-            `${describePost(post)}: core average ${average.toFixed(2)} <= 3.0`,
+            `${describePost(post)}: core average ${average.toFixed(2)} <= ${PUBLICATION_POLICY.publicTech.minimumCoreReviewAverageExclusive.toFixed(1)}`,
           ];
         }
 
@@ -93,26 +117,9 @@ describe('publication policy', () => {
   it('requires featured posts to meet branding thresholds', () => {
     const featuredPosts = getSortedFeedData().filter((post) => post.featured);
     const offenses = featuredPosts.flatMap((post) => {
-      const brandFit = post.qualityReview?.brandFit;
-      const currentOffenses: string[] = [];
-
-      if (post.category !== 'Tech') {
-        currentOffenses.push(
-          `${describePost(post)}: featured posts must be Tech`
-        );
-      }
-
-      if (post.series) {
-        currentOffenses.push(
-          `${describePost(post)}: featured posts must not be series`
-        );
-      }
-
-      if (typeof brandFit !== 'number' || brandFit < 4) {
-        currentOffenses.push(`${describePost(post)}: brandFit must be >= 4.0`);
-      }
-
-      return currentOffenses;
+      return isEligibleForFeaturedPost(post)
+        ? []
+        : [`${describePost(post)}: does not meet featured criteria`];
     });
 
     expect(featuredPosts.map((post) => post.slug).sort()).toEqual(
diff --git a/blog/services/policy.ts b/blog/services/policy.ts
@@ -0,0 +1,76 @@
+import type { FeedData, QualityReview } from '@/blog/model/types';
+
+export const PUBLICATION_POLICY = {
+  publicTech: {
+    minimumCoreReviewAverageExclusive: 3,
+  },
+  featured: {
+    category: 'Tech',
+    minimumBrandFit: 4,
+  },
+} as const;
+
+const CORE_TECH_REVIEW_FIELDS = [
+  'philosophy',
+  'design',
+  'implementation',
+] as const;
+
+export interface PublicationQueryOptions {
+  includePrivate?: boolean;
+}
+
+export function isPostVisible(
+  post: Pick<FeedData, 'visibility'>,
+  options: PublicationQueryOptions = {}
+): boolean {
+  return options.includePrivate || post.visibility === 'public';
+}
+
+export function filterVisiblePosts<T extends Pick<FeedData, 'visibility'>>(
+  posts: T[],
+  options: PublicationQueryOptions = {}
+): T[] {
+  return posts.filter((post) => isPostVisible(post, options));
+}
+
+export function getCoreTechReviewAverage(
+  review: QualityReview | undefined
+): number | null {
+  const scores = CORE_TECH_REVIEW_FIELDS.map((field) => review?.[field]);
+  const numericScores = scores.filter(
+    (score): score is number => typeof score === 'number'
+  );
+
+  if (numericScores.length !== CORE_TECH_REVIEW_FIELDS.length) {
+    return null;
+  }
+
+  return (
+    numericScores.reduce((sum, score) => sum + score, 0) / numericScores.length
+  );
+}
+
+export function meetsPublicTechReviewThreshold(
+  review: QualityReview | undefined
+): boolean {
+  const average = getCoreTechReviewAverage(review);
+
+  return (
+    average !== null &&
+    average > PUBLICATION_POLICY.publicTech.minimumCoreReviewAverageExclusive
+  );
+}
+
+export function isEligibleForFeaturedPost(
+  post: Pick<FeedData, 'category' | 'qualityReview' | 'series'>
+): boolean {
+  const brandFit = post.qualityReview?.brandFit;
+
+  return (
+    post.category === PUBLICATION_POLICY.featured.category &&
+    !post.series &&
+    typeof brandFit === 'number' &&
+    brandFit >= PUBLICATION_POLICY.featured.minimumBrandFit
+  );
+}
diff --git a/blog/services/post-repository.ts b/blog/services/post-repository.ts
@@ -6,7 +6,7 @@ import {
   filterVisiblePosts,
   isPostVisible,
   type PublicationQueryOptions,
-} from './publication-policy';
+} from './policy';
 
 const postsDirectory = path.join(process.cwd(), 'posts');
 const isProduction = process.env.NODE_ENV === 'production';
diff --git a/blog/services/publication-policy.ts b/blog/services/publication-policy.ts
diff --git a/docs/README.md b/docs/README.md
@@ -46,6 +46,7 @@ Last updated: 2026-07-22
 - `docs/adr/0045-use-team-context-in-resume-company-column.md`
 - `docs/adr/0046-use-main-as-the-primary-branch.md`
 - `docs/adr/0047-isolate-publication-policy.md`
+- `docs/adr/0048-centralize-blog-publication-rules.md`
 - `docs/blog-quality-guide.md`
 - `docs/content-publication-candidates.md`
 - `docs/database/db-schema.md`
diff --git a/docs/adr/0048-centralize-blog-publication-rules.md b/docs/adr/0048-centralize-blog-publication-rules.md
@@ -0,0 +1,38 @@
+# 0048. 블로그 발행 규칙을 단일 policy 모듈로 확장한다
+
+Date: 2026-07-22
+Status: Accepted
+
+## 배경
+
+ADR 0047은 public/private visibility 판단을 `publication-policy.ts`로 분리했다.
+그러나 공개 Tech 글의 core 점수 하한과 featured 자격 조건은 테스트 안에 남아
+있어, 사람이 읽는 guide와 실행되는 검증의 기준값을 함께 바꿔야 했다.
+
+## 결정
+
+- `blog/services/publication-policy.ts`를 `blog/services/policy.ts`로 바꾼다.
+- `policy.ts`는 visibility, 공개 Tech 글의 core 리뷰 하한, featured 자격 조건을
+  함께 소유한다.
+- `meta.json`은 글별 visibility, 점수, featured 선택을 계속 소유한다. featured
+  slug 목록이나 series의 현재 공개 상태를 policy에 복제하지 않는다.
+- frontmatter의 값 범위 검증은 입력 schema 책임으로, 개발 환경 preview는 상세
+  route의 단일 호출 책임으로 유지한다.
+
+## 결과
+
+- 실행되는 공개 기준값은 `policy.ts` 한 곳에서 바꾼다.
+- guide는 정책의 의미와 운영 절차를 설명하고, threshold 숫자의 별도 원본이 되지
+  않는다.
+- 수동 큐레이션 데이터와 발행 규칙이 이중 관리되지 않는다.
+
+## 검토한 대안
+
+- featured slug를 policy에 등록: frontmatter의 `featured`와 두 원본이 된다.
+- 점수 기준을 frontmatter schema로 이동: 유효한 입력값과 공개 판단을 섞는다.
+- route별 preview 조건까지 이동: 현재 한 파일의 두 호출만 공유하므로 불필요한
+  wrapper가 된다.
+
+## Related History
+
+- `c43af1e`: visibility 정책을 `publication-policy.ts`로 분리
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -65,6 +65,7 @@ ADR은 AI 협업 가이드와 별개의 문서다. 사람이 결정했든 AI가
 | [0045](0045-use-team-context-in-resume-company-column.md)                            | Accepted   | Resume 회사 열에는 팀 맥락만 표시한다                        |
 | [0046](0046-use-main-as-the-primary-branch.md)                                       | Accepted   | 저장소의 주 브랜치를 main으로 통일한다                       |
 | [0047](0047-isolate-publication-policy.md)                                           | Accepted   | 공개 정책을 blog 도메인 모듈로 분리한다                      |
+| [0048](0048-centralize-blog-publication-rules.md)                                    | Accepted   | 블로그 발행 규칙을 단일 policy 모듈로 확장한다               |
 
 ## 작성 조건
 
diff --git a/docs/blog-quality-guide.md b/docs/blog-quality-guide.md
@@ -103,11 +103,12 @@ Life 글은 아래 기준으로 본다.
 - `visibility` 기본값은 `private`다. 공개는 리뷰를 마친 뒤 명시적으로 승격한다.
 - `contentType`은 `essay`, `retrospective`, `review` 중 하나로 둔다.
 - 시리즈는 기본적으로 공개 자산이 아니라 학습 자산으로 보고, 공개 필요성이 생기기 전까지 `private`로 둔다.
-- 엔지니어링 글은 `philosophy`, `design`, `implementation` 평균이 `3.0` 이하이면 `private`로 둔다.
+- 엔지니어링 글은 `philosophy`, `design`, `implementation` 평균이
+  `blog/services/policy.ts`의 공개 하한을 넘어야 한다.
 - `featured`는 아래 조건을 모두 만족할 때만 허용한다.
   - 엔지니어링 글
   - 시리즈 아님
-  - `brandFit >= 4.0`
+  - `blog/services/policy.ts`의 `brandFit` 하한 충족
 - `featured`는 점수만으로 자동 결정하지 않는다. 현재 단계에서는 수동 큐레이션 목록으로 관리한다.
 - 현재 홈은 `featured` 글을 별도 노출하지 않고 전체 공개 글을 단일 피드로 보여준다.
 
