Merge pull request #98 from wellwind/codex/review-clean-architecture-plan

feat(shared): add cross-slice ports and stubs

Author: wellwind

docs/clean-architecture-plan.md

@@ -111,7 +111,7 @@ src/
 ### Phase 1 – Shared Core & Contracts
 - ✅ 建立 `shared/core` 骨架並搬遷 `PostMeta`／分類／標籤型別，新增 `@shared/core` 與 `@shared/testing` path alias 供程式與測試共用。
 - ✅ 在 `shared/testing` 提供 `postMetaBuilder`，開始以共用 builder 取代既有測試內的臨時工廠函式。
-- ⏳ 定義跨切片 ports（`AnalyticsPort`、`PlatformPort`、`SeoMetaPort`）並提供暫行實作；後續將補齊 Markdown／日期契約與其適配層。
+- ✅ 定義跨切片 ports（`AnalyticsPort`、`PlatformPort`、`SeoMetaPort`）並提供暫行實作；後續將補齊 Markdown／日期契約與其適配層。
 
 ### Phase 2 – Scaffold Feature Slices
 - Create directory skeletons for `blog`, `post-detail`, `search`, `taxonomy`, `layout` mirroring the proposed structure.

docs/phase-1-plan.md

@@ -11,7 +11,7 @@
 - [x] 搬遷 `PostMeta`、分類/標籤型別至共享模型，並更新現有呼叫端引用。
 - [x] 規劃 Markdown 與日期相關契約的遷移策略，並準備空殼模組待後續填補。
 - [x] 建立 `shared/testing` 的 builders/mocks 架構，並將既有測試改用共用 `postMetaBuilder`。
-- [ ] 定義並匯出跨切片 ports 的介面與暫行實作。
+- [x] 定義並匯出跨切片 ports 的介面與暫行實作。
 - [x] 更新 `tsconfig` path alias 與相關建置腳本，確保新路徑可用。
 - [x] 調整 `docs/clean-architecture-plan.md` 與其他文件，反映 Phase 1 的實作現況與剩餘工作。
 
@@ -31,3 +31,4 @@
 
 ## 進度紀錄
 - 2025-09-19：完成 `PostMeta` 模型搬遷與 `shared/core` 骨架建立，新增 `@shared/core`、`@shared/testing` path alias，並以 `postMetaBuilder` 取代部份測試中的臨時建構函式。已執行 `npm run lint` 與 `npm run test` 確認既有流程穩定，尚待定義跨切片 ports 與補齊 Markdown/日期契約實作，文件同步更新進行中。
+- 2025-09-20：補齊 `AnalyticsPort`、`PlatformPort`、`SeoMetaPort` 介面與暫行實作，並提供對應的測試替身，準備後續切片改造時的依賴注入介面。

src/shared/core/ports/analytics.port.ts

@@ -0,0 +1,38 @@
+export interface AnalyticsView {
+  name: string;
+}
+
+export interface AnalyticsPage {
+  id: string;
+  url: string;
+  title?: string;
+}
+
+export type AnalyticsEventAttributes = Record<string, unknown>;
+
+export interface AnalyticsSpan {
+  setAttribute(name: string, value: unknown): void;
+  end(): void;
+}
+
+export interface AnalyticsTracer {
+  startSpan(name: string, attributes?: AnalyticsEventAttributes): AnalyticsSpan;
+}
+
+export interface AnalyticsPort {
+  readonly isAvailable: boolean;
+  pushEvent(eventName: string, attributes?: AnalyticsEventAttributes): void;
+  setView(view: AnalyticsView): void;
+  getView(): AnalyticsView | null;
+  setPage(page: AnalyticsPage): void;
+  getTracer(instrumentation: string): AnalyticsTracer | null;
+}
+
+export const createNoopAnalyticsPort = (): AnalyticsPort => ({
+  isAvailable: false,
+  pushEvent: () => undefined,
+  setView: () => undefined,
+  getView: () => null,
+  setPage: () => undefined,
+  getTracer: () => null,
+});

src/shared/core/ports/index.ts

@@ -1,2 +1,3 @@
-// 跨切片 Ports 將在後續階段定義。
-export {};
+export * from './analytics.port';
+export * from './platform.port';
+export * from './seo-meta.port';

src/shared/core/ports/platform.port.ts

@@ -0,0 +1,27 @@
+export type StateGetter<T> = () => T;
+
+export interface PlatformPort {
+  readonly isServer: boolean;
+  readonly isBrowser: boolean;
+  readonly isSmallScreen: StateGetter<boolean>;
+}
+
+export interface PlatformPortOptions {
+  isServer?: boolean;
+  isBrowser?: boolean;
+  isSmallScreen?: boolean;
+}
+
+export const createPlatformPort = (
+  options: PlatformPortOptions = {},
+): PlatformPort => {
+  const isServer = options.isServer ?? false;
+  const isBrowser = options.isBrowser ?? !isServer;
+  const isSmallScreenValue = options.isSmallScreen ?? false;
+
+  return {
+    isServer,
+    isBrowser,
+    isSmallScreen: () => isSmallScreenValue,
+  };
+};

src/shared/core/ports/seo-meta.port.ts

@@ -0,0 +1,17 @@
+export type SeoMetaType = 'website' | 'article';
+
+export interface SeoMetaPayload {
+  title: string;
+  description: string;
+  keywords: string[];
+  type: SeoMetaType;
+  ogImage?: string;
+}
+
+export interface SeoMetaPort {
+  resetMeta(meta: SeoMetaPayload): void;
+}
+
+export const createNoopSeoMetaPort = (): SeoMetaPort => ({
+  resetMeta: () => undefined,
+});

src/shared/testing/mocks/analytics-port.mock.ts

@@ -0,0 +1,49 @@
+import {
+  AnalyticsEventAttributes,
+  AnalyticsPage,
+  AnalyticsPort,
+  AnalyticsTracer,
+  AnalyticsView,
+} from '@shared/core';
+
+export interface LoggedAnalyticsEvent {
+  name: string;
+  attributes?: AnalyticsEventAttributes;
+}
+
+const noopTracer: AnalyticsTracer = {
+  startSpan: () => ({
+    setAttribute: () => undefined,
+    end: () => undefined,
+  }),
+};
+
+export class AnalyticsPortSpy implements AnalyticsPort {
+  readonly isAvailable = true;
+  readonly events: LoggedAnalyticsEvent[] = [];
+  readonly views: AnalyticsView[] = [];
+  readonly pages: AnalyticsPage[] = [];
+
+  private currentView: AnalyticsView | null = null;
+
+  pushEvent(name: string, attributes?: AnalyticsEventAttributes): void {
+    this.events.push({ name, attributes });
+  }
+
+  setView(view: AnalyticsView): void {
+    this.currentView = view;
+    this.views.push(view);
+  }
+
+  getView(): AnalyticsView | null {
+    return this.currentView;
+  }
+
+  setPage(page: AnalyticsPage): void {
+    this.pages.push(page);
+  }
+
+  getTracer(): AnalyticsTracer | null {
+    return noopTracer;
+  }
+}

src/shared/testing/mocks/index.ts

@@ -1,2 +1,3 @@
-// Ports 將於後續階段提供相對應的測試替身。
-export {};
+export * from './analytics-port.mock';
+export * from './platform-port.mock';
+export * from './seo-meta-port.mock';

src/shared/testing/mocks/platform-port.mock.ts

@@ -0,0 +1,27 @@
+import { PlatformPort, PlatformPortOptions, StateGetter } from '@shared/core';
+
+export class PlatformPortStub implements PlatformPort {
+  isServer: boolean;
+  isBrowser: boolean;
+  private isSmallScreenValue: boolean;
+
+  constructor(options: PlatformPortOptions = {}) {
+    this.isServer = options.isServer ?? false;
+    this.isBrowser = options.isBrowser ?? !this.isServer;
+    this.isSmallScreenValue = options.isSmallScreen ?? false;
+  }
+
+  readonly isSmallScreen: StateGetter<boolean> = () => this.isSmallScreenValue;
+
+  setIsServer(isServer: boolean) {
+    this.isServer = isServer;
+  }
+
+  setIsBrowser(isBrowser: boolean) {
+    this.isBrowser = isBrowser;
+  }
+
+  setIsSmallScreen(isSmallScreen: boolean) {
+    this.isSmallScreenValue = isSmallScreen;
+  }
+}

src/shared/testing/mocks/seo-meta-port.mock.ts

@@ -0,0 +1,13 @@
+import { SeoMetaPayload, SeoMetaPort } from '@shared/core';
+
+export class SeoMetaPortSpy implements SeoMetaPort {
+  readonly calls: SeoMetaPayload[] = [];
+
+  resetMeta(meta: SeoMetaPayload): void {
+    this.calls.push(meta);
+  }
+
+  get lastCall(): SeoMetaPayload | undefined {
+    return this.calls.at(-1);
+  }
+}