Merge pull request #97 from wellwind/codex/determine-next-steps-after-reviewing-clean-architecture-plan

wellwind · web-flow · commit 15466c041d50 · 2025-09-19T09:35:27.000+08:00
feat: scaffold shared core contracts for phase 1
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,4 @@
+# 協作指引
+
+- 每次變更若累計 diff 大於 ±400 行，必須立即暫停後續開發，先提交 PR，並在文件中明確記錄尚未完成的事項。
+- 所有已提交至版本庫的變更，都必須建立對應的 PR；未建立 PR 不得視為任務完成。
diff --git a/docs/clean-architecture-plan.md b/docs/clean-architecture-plan.md
@@ -109,9 +109,9 @@ src/
 - [ ] Wire the Node-driven Jasmine runner into CI after confirming compatible Node and dependency versions in the target environment.
 
 ### Phase 1 – Shared Core & Contracts
-- Create `shared/core` with existing `PostMeta`, `Category`, `Tag`, date utilities, Markdown parsing contracts.
-- Introduce testing builders/mocks in `shared/testing` to support upcoming migrations.
-- Define cross-feature ports (`AnalyticsPort`, `PlatformPort`, `SeoMetaPort`) in `shared/core/ports` so features can consume them consistently.
+- ✅ 建立 `shared/core` 骨架並搬遷 `PostMeta`／分類／標籤型別，新增 `@shared/core` 與 `@shared/testing` path alias 供程式與測試共用。
+- ✅ 在 `shared/testing` 提供 `postMetaBuilder`，開始以共用 builder 取代既有測試內的臨時工廠函式。
+- ⏳ 定義跨切片 ports（`AnalyticsPort`、`PlatformPort`、`SeoMetaPort`）並提供暫行實作；後續將補齊 Markdown／日期契約與其適配層。
 
 ### Phase 2 – Scaffold Feature Slices
 - Create directory skeletons for `blog`, `post-detail`, `search`, `taxonomy`, `layout` mirroring the proposed structure.
diff --git a/docs/phase-1-plan.md b/docs/phase-1-plan.md
@@ -0,0 +1,33 @@
+# Phase 1：Shared Core 與契約落地計畫
+
+## 目標
+- 建立 `src/shared/core` 架構，收納跨切片共用的模型、日期工具與 Markdown 契約，並提供乾淨的公開 API。
+- 建立 `src/shared/testing`，集中共用的 builders 與 mocks，以利後續各切片測試重用。
+- 定義 `AnalyticsPort`、`PlatformPort`、`SeoMetaPort` 等跨功能介面，為後續功能切片鋪設穩定契約。
+
+## 工作分解與狀態
+- [x] 盤點並記錄現存跨切片模型與工具，整理移轉清單。
+- [x] 建立 `shared/core` 目錄骨架與 `index.ts` 桶狀匯出，準備 `models/`、`markdown/`、`dates/`、`ports/` 子目錄。
+- [x] 搬遷 `PostMeta`、分類/標籤型別至共享模型，並更新現有呼叫端引用。
+- [x] 規劃 Markdown 與日期相關契約的遷移策略，並準備空殼模組待後續填補。
+- [x] 建立 `shared/testing` 的 builders/mocks 架構，並將既有測試改用共用 `postMetaBuilder`。
+- [ ] 定義並匯出跨切片 ports 的介面與暫行實作。
+- [x] 更新 `tsconfig` path alias 與相關建置腳本，確保新路徑可用。
+- [x] 調整 `docs/clean-architecture-plan.md` 與其他文件，反映 Phase 1 的實作現況與剩餘工作。
+
+## 測試策略
+- 每完成一個主要子任務，至少執行 `npm run lint` 驗證程式碼靜態品質，必要時補跑 `npm run test` 確認回歸測試。
+- 建立新的共用 builders 或 ports 後，新增或調整單元測試，確保行為維持正確。
+
+## 風險與緩解
+- **變更多點**：拆分提交，必要時提早提交 PR，避免超出 ±400 行限制。
+- **匯入路徑錯誤**：調整完成後以 TypeScript 編譯與 lint 驗證，並透過 IDE/CI 觀察潛在錯誤。
+- **測試資源遷移造成回歸**：每次替換測試 helper 後立即執行相關單元測試。
+
+## 里程碑追蹤
+- 2024-??-??：建立共享架構（進行中）。
+- 2024-??-??：完成核心模型搬遷（未開始）。
+- 2024-??-??：完成 ports 定義與共用測試資源（未開始）。
+
+## 進度紀錄
+- 2025-09-19：完成 `PostMeta` 模型搬遷與 `shared/core` 骨架建立，新增 `@shared/core`、`@shared/testing` path alias，並以 `postMetaBuilder` 取代部份測試中的臨時建構函式。已執行 `npm run lint` 與 `npm run test` 確認既有流程穩定，尚待定義跨切片 ports 與補齊 Markdown/日期契約實作，文件同步更新進行中。
diff --git a/src/app/blog/blog-archives/blog-archives-posts-resolve.ts b/src/app/blog/blog-archives/blog-archives-posts-resolve.ts
@@ -1,6 +1,6 @@
 import { Injectable, inject } from '@angular/core';
+import { PostMetaWithSlug } from '@shared/core';
 import { Observable } from 'rxjs';
-import { PostMetaWithSlug } from '../../site-common/post-meta.interface';
 import { SitePostService } from '../../site-common/site-post.service';
 
 @Injectable({
diff --git a/src/app/blog/blog-archives/blog-archives.component.ts b/src/app/blog/blog-archives/blog-archives.component.ts
@@ -4,11 +4,11 @@ import { MatCardModule } from '@angular/material/card';
 import { MatIconModule } from '@angular/material/icon';
 import { MatToolbarModule } from '@angular/material/toolbar';
 import { RouterLink } from '@angular/router';
+import { PostMetaWithSlug } from '@shared/core';
 import { getRouteData, getRouteParam } from 'src/app/site-common/route-utils';
 import { BlogPostSubtitleComponent } from '../../site-common/blog-post-subtitle.component';
 import { PaginationComponent } from '../../site-common/pagination.component';
 import { PostDateAsPathPipe } from '../../site-common/post-date-as-path.pipe';
-import { PostMetaWithSlug } from '../../site-common/post-meta.interface';
 import { getPagePosts } from '../get-page-posts';
 
 const PAGE_SIZE = 10;
diff --git a/src/app/blog/blog-categories/blog-categories-posts-resolve.ts b/src/app/blog/blog-categories/blog-categories-posts-resolve.ts
@@ -1,8 +1,8 @@
 import { Injectable, inject } from '@angular/core';
 import { ActivatedRouteSnapshot } from '@angular/router';
 import { descend, prop, sortWith } from 'ramda';
+import { PostMetaWithSlug } from '@shared/core';
 import { Observable, map } from 'rxjs';
-import { PostMetaWithSlug } from '../../site-common/post-meta.interface';
 import { SitePostService } from '../../site-common/site-post.service';
 import { findPosts } from '../find-posts';
 
diff --git a/src/app/blog/blog-categories/blog-categories-posts.component.ts b/src/app/blog/blog-categories/blog-categories-posts.component.ts
@@ -10,7 +10,7 @@ import { MatCardModule } from '@angular/material/card';
 import { MatIconModule } from '@angular/material/icon';
 import { MatToolbarModule } from '@angular/material/toolbar';
 import { RouterLink } from '@angular/router';
-import { PostMetaWithSlug } from 'src/app/site-common/post-meta.interface';
+import { PostMetaWithSlug } from '@shared/core';
 import { getRouteData, getRouteParam } from 'src/app/site-common/route-utils';
 import { BlogPostSubtitleComponent } from '../../site-common/blog-post-subtitle.component';
 import { PaginationComponent } from '../../site-common/pagination.component';
diff --git a/src/app/blog/blog-categories/blog-categories-resolve.ts b/src/app/blog/blog-categories/blog-categories-resolve.ts
@@ -1,6 +1,6 @@
 import { Injectable, inject } from '@angular/core';
+import { PostMetaWithSlug } from '@shared/core';
 import { Observable } from 'rxjs';
-import { PostMetaWithSlug } from '../../site-common/post-meta.interface';
 import { SitePostService } from '../../site-common/site-post.service';
 
 @Injectable({
diff --git a/src/app/blog/blog-categories/blog-categories.component.ts b/src/app/blog/blog-categories/blog-categories.component.ts
@@ -7,8 +7,8 @@ import {
 } from '@angular/core';
 import { MatCardModule } from '@angular/material/card';
 import { RouterLink } from '@angular/router';
+import { PostMetaWithSlug } from '@shared/core';
 import { getRouteData } from 'src/app/site-common/route-utils';
-import { PostMetaWithSlug } from '../../site-common/post-meta.interface';
 import { SiteMetaService } from '../../site-common/site-meta.service';
 import { SlugifyPipe } from '../../site-common/slugify.pipe';
 
diff --git a/src/app/blog/blog-posts/blog-post/blog-post.component.ts b/src/app/blog/blog-posts/blog-post/blog-post.component.ts
@@ -14,6 +14,7 @@ import { MatIconModule } from '@angular/material/icon';
 import { MatTooltipModule } from '@angular/material/tooltip';
 import { DomSanitizer } from '@angular/platform-browser';
 import { RouterLink } from '@angular/router';
+import { PostMetaWithSlug } from '@shared/core';
 import { MarkdownMeta } from 'site-utils';
 import { getRouteData } from 'src/app/site-common/route-utils';
 import { findMainContentContainer, scrollTo } from '../../../../utils';
@@ -22,7 +23,6 @@ import { CommentComponent } from '../../../site-common/comment.component';
 import { LikerCoinComponent } from '../../../site-common/liker-coin.component';
 import { PlatformService } from '../../../site-common/platform.service';
 import { PostDateAsPathPipe } from '../../../site-common/post-date-as-path.pipe';
-import { PostMetaWithSlug } from '../../../site-common/post-meta.interface';
 import { SiteMetaService } from '../../../site-common/site-meta.service';
 import { SitePostService } from '../../../site-common/site-post.service';
 import { SlugifyPipe } from '../../../site-common/slugify.pipe';
diff --git a/src/app/blog/blog-tags/blog-tag-posts.component.ts b/src/app/blog/blog-tags/blog-tag-posts.component.ts
@@ -10,11 +10,11 @@ import { MatCardModule } from '@angular/material/card';
 import { MatIconModule } from '@angular/material/icon';
 import { MatToolbarModule } from '@angular/material/toolbar';
 import { RouterLink } from '@angular/router';
+import { PostMetaWithSlug } from '@shared/core';
 import { getRouteData, getRouteParam } from 'src/app/site-common/route-utils';
 import { BlogPostSubtitleComponent } from '../../site-common/blog-post-subtitle.component';
 import { PaginationComponent } from '../../site-common/pagination.component';
 import { PostDateAsPathPipe } from '../../site-common/post-date-as-path.pipe';
-import { PostMetaWithSlug } from '../../site-common/post-meta.interface';
 import { SiteMetaService } from '../../site-common/site-meta.service';
 import { UnslugifyPipe } from '../../site-common/unslugify.pipe';
 import { getPagePosts } from '../get-page-posts';
diff --git a/src/app/blog/blog-tags/blog-tags-posts-resolve.ts b/src/app/blog/blog-tags/blog-tags-posts-resolve.ts
@@ -1,8 +1,8 @@
 import { Injectable, inject } from '@angular/core';
 import { ActivatedRouteSnapshot } from '@angular/router';
 import { descend, prop, sortWith } from 'ramda';
+import { PostMetaWithSlug } from '@shared/core';
 import { Observable, map } from 'rxjs';
-import { PostMetaWithSlug } from '../../site-common/post-meta.interface';
 import { SitePostService } from '../../site-common/site-post.service';
 import { findPosts } from '../find-posts';
 
diff --git a/src/app/blog/blog-tags/blog-tags-resolve.ts b/src/app/blog/blog-tags/blog-tags-resolve.ts
@@ -1,6 +1,6 @@
 import { Injectable, inject } from '@angular/core';
+import { PostMetaWithSlug } from '@shared/core';
 import { Observable } from 'rxjs';
-import { PostMetaWithSlug } from '../../site-common/post-meta.interface';
 import { SitePostService } from '../../site-common/site-post.service';
 
 @Injectable({
diff --git a/src/app/blog/blog-tags/blog-tags.component.ts b/src/app/blog/blog-tags/blog-tags.component.ts
@@ -8,8 +8,8 @@ import {
 } from '@angular/core';
 import { MatCardModule } from '@angular/material/card';
 import { RouterLink } from '@angular/router';
+import { PostMetaWithSlug } from '@shared/core';
 import { getRouteData } from 'src/app/site-common/route-utils';
-import { PostMetaWithSlug } from '../../site-common/post-meta.interface';
 import { SiteMetaService } from '../../site-common/site-meta.service';
 import { SlugifyPipe } from '../../site-common/slugify.pipe';
 import { BlogPostTagSizePipe } from './blog-post-tag-size.pipe';
diff --git a/src/app/blog/find-posts.spec.ts b/src/app/blog/find-posts.spec.ts
@@ -1,19 +1,11 @@
+import { PostMetaWithSlug } from '@shared/core';
+import { postMetaBuilder } from '@shared/testing';
 import { findPosts } from './find-posts';
-import { PostMetaWithSlug } from '../site-common/post-meta.interface';
-
-const buildPost = (slug: string): PostMetaWithSlug => ({
-  slug,
-  title: slug,
-  date: '2024-01-01 00:00:00',
-  categories: [],
-  tags: [],
-  summary: '',
-});
 
 describe('findPosts', () => {
   const postsByCategory: Record<string, PostMetaWithSlug[]> = {
-    'Frontend Favorites': [buildPost('angular')],
-    'Backend Basics': [buildPost('node')],
+    'Frontend Favorites': [postMetaBuilder({ slug: 'angular', title: 'angular' })],
+    'Backend Basics': [postMetaBuilder({ slug: 'node', title: 'node' })],
   };
 
   it('returns matched posts when slugified key exists', () => {
diff --git a/src/app/blog/find-posts.ts b/src/app/blog/find-posts.ts
@@ -1,5 +1,5 @@
+import { PostMetaWithSlug } from '@shared/core';
 import { slugify } from '../../../utils/slugify';
-import { PostMetaWithSlug } from '../site-common/post-meta.interface';
 
 export const findPosts = (slug: string, data: { [key: string]: PostMetaWithSlug[] }) => {
   const found = Object
diff --git a/src/app/blog/get-page-posts.spec.ts b/src/app/blog/get-page-posts.spec.ts
@@ -1,18 +1,10 @@
+import { PostMetaWithSlug } from '@shared/core';
+import { postMetaBuilder } from '@shared/testing';
 import { getPagePosts } from './get-page-posts';
-import { PostMetaWithSlug } from '../site-common/post-meta.interface';
-
-const buildPost = (slug: string): PostMetaWithSlug => ({
-  slug,
-  title: slug,
-  date: '2024-01-01 00:00:00',
-  categories: [],
-  tags: [],
-  summary: '',
-});
 
 describe('getPagePosts', () => {
   const posts: PostMetaWithSlug[] = Array.from({ length: 5 }, (_, index) =>
-    buildPost(`post-${index + 1}`),
+    postMetaBuilder({ slug: `post-${index + 1}`, title: `post-${index + 1}` }),
   );
 
   it('returns posts for the requested page', () => {
diff --git a/src/app/blog/get-page-posts.ts b/src/app/blog/get-page-posts.ts
@@ -1,4 +1,4 @@
-import { PostMetaWithSlug } from '../site-common/post-meta.interface';
+import { PostMetaWithSlug } from '@shared/core';
 
 export const getPagePosts = (pageNum: number, pageSize: number, item: PostMetaWithSlug[]) =>
   item.slice((pageNum - 1) * pageSize, (pageNum - 1) * pageSize + pageSize);
diff --git a/src/app/site-common/blog-post-subtitle.component.ts b/src/app/site-common/blog-post-subtitle.component.ts
@@ -1,8 +1,8 @@
 import { Component, input } from '@angular/core';
 import { MatIconModule } from '@angular/material/icon';
 import { RouterLink } from '@angular/router';
+import { PostMeta } from '@shared/core';
 import { MarkdownMeta } from 'site-utils';
-import { PostMeta } from './post-meta.interface';
 import { SlugifyPipe } from './slugify.pipe';
 
 @Component({
diff --git a/src/app/site-common/post-date-as-path.pipe.ts b/src/app/site-common/post-date-as-path.pipe.ts
@@ -1,5 +1,5 @@
 import { Pipe, PipeTransform } from '@angular/core';
-import { PostMetaWithSlug } from './post-meta.interface';
+import { PostMetaWithSlug } from '@shared/core';
 
 @Pipe({
     name: 'postDateAsPath',
diff --git a/src/app/site-common/search-posts.spec.ts b/src/app/site-common/search-posts.spec.ts
@@ -1,35 +1,26 @@
+import { PostMetaWithSlug } from '@shared/core';
+import { postMetaBuilder } from '@shared/testing';
 import { searchPosts, searchPostsByDateRange } from './search-posts';
-import { PostMetaWithSlug } from './post-meta.interface';
-
-const buildPost = (overrides: Partial<PostMetaWithSlug>): PostMetaWithSlug => ({
-  title: 'Default Title',
-  date: '2024-01-01 00:00:00',
-  categories: [],
-  tags: [],
-  summary: 'Default summary',
-  slug: 'default-slug',
-  ...overrides,
-});
 
 describe('searchPosts', () => {
   const posts: PostMetaWithSlug[] = [
-    buildPost({
+    postMetaBuilder({
       title: 'Angular Signals Deep Dive',
       slug: 'angular-signals',
       categories: ['Frontend'],
       tags: ['Angular', 'RxJS'],
       summary: 'A guide to Angular signals and RxJS interop',
       date: '2024-03-10 12:00:00',
     }),
-    buildPost({
+    postMetaBuilder({
       title: 'RxJS In Practice',
       slug: 'rxjs-in-practice',
       categories: ['Frontend'],
       tags: ['RxJS'],
       summary: 'Practical patterns with RxJS operators',
       date: '2024-02-01 08:30:00',
     }),
-    buildPost({
+    postMetaBuilder({
       title: 'Node Deployment Handbook',
       slug: 'node-deployment',
       categories: ['Backend'],
@@ -106,17 +97,17 @@ describe('searchPosts', () => {
 
 describe('searchPostsByDateRange', () => {
   const posts: PostMetaWithSlug[] = [
-    buildPost({
+    postMetaBuilder({
       title: 'Early Post',
       slug: 'early',
       date: '2024-01-01 00:00:00',
     }),
-    buildPost({
+    postMetaBuilder({
       title: 'Mid Post',
       slug: 'mid',
       date: '2024-02-15 00:00:00',
     }),
-    buildPost({
+    postMetaBuilder({
       title: 'Late Post',
       slug: 'late',
       date: '2024-04-01 00:00:00',
diff --git a/src/app/site-common/search-posts.ts b/src/app/site-common/search-posts.ts
@@ -1,5 +1,5 @@
+import { PostMetaWithSlug } from '@shared/core';
 import { slugify } from '../../../utils/slugify';
-import { PostMetaWithSlug } from './post-meta.interface';
 
 const searchFieldMapping = {
   tag: '標籤',
diff --git a/src/app/site-common/site-post.service.ts b/src/app/site-common/site-post.service.ts
@@ -5,7 +5,7 @@ import { ascend, descend, prop, sortWith } from 'ramda';
 import { combineLatest, iif, map, of, shareReplay, startWith, tap } from 'rxjs';
 import { environment } from '../../environments/environment';
 import { PlatformService } from './platform.service';
-import { PostMeta, PostMetaWithSlug } from './post-meta.interface';
+import { PostMeta, PostMetaWithSlug } from '@shared/core';
 
 type PostMetaCollection = { [keg: string]: PostMeta } | null;
 const _cacheBlogPostsKey = makeStateKey<PostMetaCollection>('blog-posts.json');
diff --git a/src/shared/core/dates/index.ts b/src/shared/core/dates/index.ts
@@ -0,0 +1,2 @@
+// 日期相關工具將在後續階段補齊。
+export {};
diff --git a/src/shared/core/index.ts b/src/shared/core/index.ts
@@ -0,0 +1,4 @@
+export * from './models';
+export * from './markdown';
+export * from './dates';
+export * from './ports';
diff --git a/src/shared/core/markdown/index.ts b/src/shared/core/markdown/index.ts
@@ -0,0 +1,2 @@
+// Markdown 契約將在後續階段補齊。
+export {};
diff --git a/src/shared/core/models/index.ts b/src/shared/core/models/index.ts
@@ -0,0 +1 @@
+export * from './post-meta';
diff --git a/src/shared/core/models/post-meta.ts b/src/shared/core/models/post-meta.ts
@@ -1,8 +1,11 @@
+export type Category = string;
+export type Tag = string;
+
 export interface PostMeta {
   title: string;
   date: string;
-  categories: string[];
-  tags: string[];
+  categories: Category[];
+  tags: Tag[];
   summary: string;
 }
 
diff --git a/src/shared/core/ports/index.ts b/src/shared/core/ports/index.ts
@@ -0,0 +1,2 @@
+// 跨切片 Ports 將在後續階段定義。
+export {};
diff --git a/src/shared/testing/builders/index.ts b/src/shared/testing/builders/index.ts
@@ -0,0 +1 @@
+export * from './post-meta.builder';
diff --git a/src/shared/testing/builders/post-meta.builder.ts b/src/shared/testing/builders/post-meta.builder.ts
@@ -0,0 +1,21 @@
+import { PostMetaWithSlug } from '@shared/core';
+
+export type PostMetaBuilderOptions = Partial<PostMetaWithSlug> & {
+  index?: number;
+};
+
+export const postMetaBuilder = (
+  options: PostMetaBuilderOptions = {},
+): PostMetaWithSlug => {
+  const { index, ...overrides } = options;
+  const suffix = typeof index === 'number' ? `-${index}` : '';
+
+  return {
+    title: overrides.title ?? `範例文章${suffix}`,
+    date: overrides.date ?? '2024-01-01',
+    categories: overrides.categories ?? ['angular'],
+    tags: overrides.tags ?? ['angular'],
+    summary: overrides.summary ?? '預設摘要',
+    slug: overrides.slug ?? `sample-post${suffix}`,
+  };
+};
diff --git a/src/shared/testing/index.ts b/src/shared/testing/index.ts
@@ -0,0 +1,2 @@
+export * from './builders';
+export * from './mocks';
diff --git a/src/shared/testing/mocks/index.ts b/src/shared/testing/mocks/index.ts
@@ -0,0 +1,2 @@
+// Ports 將於後續階段提供相對應的測試替身。
+export {};
diff --git a/tsconfig.json b/tsconfig.json
@@ -23,6 +23,18 @@
     "paths": {
       "site-utils": [
         "utils"
+      ],
+      "@shared/core": [
+        "src/shared/core/index.ts"
+      ],
+      "@shared/core/*": [
+        "src/shared/core/*"
+      ],
+      "@shared/testing": [
+        "src/shared/testing/index.ts"
+      ],
+      "@shared/testing/*": [
+        "src/shared/testing/*"
       ]
     },
     "useDefineForClassFields": false
