어바웃피싱 단축링크 시스템 구축 가이드

타입 : A
이름 : go
값   : 12.34.56.78        ← 0-2 표의 서버 공인 IP
TTL  : 3600

server {
    listen 80;
    server_name go.aboutfishing.kr;

    # 앱 연결 확인 파일은 파일 그대로 내려준다 (3장에서 만든다)
    location /.well-known/ {
        root /var/www/go;
        default_type application/json;
        add_header Access-Control-Allow-Origin *;
        # 아래 두 줄 중요 — 이 경로는 절대 리다이렉트되면 안 된다
        try_files $uri =404;
    }

    # 나머지는 NestJS 로 넘긴다
    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

CREATE TABLE short_links (
  id              BIGINT AUTO_INCREMENT PRIMARY KEY,
  slug            VARCHAR(32) COLLATE utf8mb4_bin NOT NULL,
  vessel_id       BIGINT,          -- 선박 ID. 선사 전용 링크가 아니면 NULL
  title           VARCHAR(120),    -- 어드민 목록에서 사람이 알아볼 이름
  target_url      VARCHAR(1000) NOT NULL,
  og_title        VARCHAR(255),
  og_description  VARCHAR(500),
  og_image_url    VARCHAR(1000),
  utm_source      VARCHAR(100),
  utm_medium      VARCHAR(100),
  utm_campaign    VARCHAR(100),
  click_count     INT NOT NULL DEFAULT 0,
  is_active       TINYINT(1) NOT NULL DEFAULT 1,
  expires_at      DATETIME,        -- 만료일. NULL이면 무기한
  memo            VARCHAR(500),    -- 운영 메모(어디에 배포했는지)
  created_by      BIGINT,
  updated_by      BIGINT,
  created_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uk_slug (slug),
  KEY idx_vessel (vessel_id),
  KEY idx_active_created (is_active, created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE click_logs (
  id           BIGINT AUTO_INCREMENT PRIMARY KEY,
  link_id      BIGINT NOT NULL,
  slug         VARCHAR(32) NOT NULL,
  vessel_id    BIGINT,
  device_type  ENUM('ios','android','pc','unknown') NOT NULL DEFAULT 'unknown',
  channel      ENUM('app','kakao','instagram','naver','browser','unknown') NOT NULL DEFAULT 'unknown',
  referer      VARCHAR(500),
  user_agent   VARCHAR(500),
  ip_hash      CHAR(64),         -- 원본 IP가 아니라 해시값 (10장 참고)
  clicked_at   DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  KEY idx_link_time (link_id, clicked_at),
  KEY idx_clicked_at (clicked_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

@Entity('short_links')
export class ShortLink {
  @PrimaryGeneratedColumn('increment', { type: 'bigint' }) id: number;
  @Column({ length: 32, unique: true })            slug: string;
  @Column({ name: 'vessel_id', nullable: true })     vesselId: number;
  @Column({ length: 120, nullable: true })          title: string;
  @Column({ name: 'target_url', length: 1000 })      targetUrl: string;
  @Column({ name: 'og_title', nullable: true })       ogTitle: string;
  @Column({ name: 'og_description', nullable: true }) ogDescription: string;
  @Column({ name: 'og_image_url', nullable: true })   ogImageUrl: string;
  @Column({ name: 'utm_source', nullable: true })     utmSource: string;
  @Column({ name: 'utm_medium', nullable: true })     utmMedium: string;
  @Column({ name: 'utm_campaign', nullable: true })   utmCampaign: string;
  @Column({ name: 'click_count', default: 0 })      clickCount: number;
  @Column({ name: 'is_active', default: true })       isActive: boolean;
  @Column({ name: 'expires_at', nullable: true })     expiresAt: Date;
  @Column({ nullable: true })                       memo: string;
  @Column({ name: 'created_by', nullable: true })     createdBy: number;
  @Column({ name: 'updated_by', nullable: true })     updatedBy: number;
  @CreateDateColumn({ name: 'created_at' })          createdAt: Date;
  @UpdateDateColumn({ name: 'updated_at' })          updatedAt: Date;
}

{
  "applinks": {
    "details": [
      {
        "appIDs": [ "ABCD123456.kr.co.aboutfishing" ],
        "components": [
          { "/": "/.well-known/*", "exclude": true },
          { "/": "/admin/*",       "exclude": true },
          { "/": "/*" }
        ]
      }
    ]
  }
}

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "kr.co.aboutfishing",
    "sha256_cert_fingerprints": [
      "AA:BB:CC:...:99",   // 앱 서명 키 (Play Console)
      "11:22:33:...:FF"    // 업로드 키 (내부 테스트 빌드용)
    ]
  }
}]

@Module({
  imports: [TypeOrmModule.forFeature([ShortLink, ClickLog])],
  controllers: [
    AdminShortlinkController,   // ← 반드시 먼저
    ShortlinkController,        // ← ':slug' 는 항상 마지막
  ],
  providers: [ShortlinkService],
})
export class ShortlinkModule {}

const ALPHABET = '23456789abcdefghjkmnpqrstuvwxyz';
export const RESERVED = new Set([
  'admin','api','health','static','assets','www','app','qr',
  'well-known','favicon.ico','robots.txt','sitemap.xml',
]);

export function randomSlug(len = 6): string {
  while (true) {
    let s = '';
    while (s.length < len) {
      // 256 을 31 로 나눈 나머지 때문에 앞 글자가 더 자주 나오는 것을 막는다
      for (const b of crypto.randomBytes(len)) {
        if (b >= 248) continue;               // 31 × 8 = 248
        s += ALPHABET[b % ALPHABET.length];
        if (s.length === len) break;
      }
    }
    if (!RESERVED.has(s)) return s;     // 우연히 예약어가 나오면 다시 뽑는다
  }
}

export function validateSlug(slug: string): string | null {
  if (!/^[a-z0-9-]{3,24}$/.test(slug)) return '영문 소문자·숫자·하이픈 3~24자만 쓸 수 있습니다.';
  if (RESERVED.has(slug))                return '사용할 수 없는 주소입니다.';
  return null;
}

// 목적지까지 그대로 넘겨야 하는 값 — 광고 클릭 식별자와 추가 UTM
const PASS_THROUGH = [
  'gclid','wbraid','gbraid','dclid','fbclid','ttclid','msclkid',
  'n_media','n_query','n_ad_group','n_ad','n_keyword','n_rank',
  'utm_content','utm_term','utm_id',
];

buildTargetUrl(link: ShortLink, query?: Record<string, any>): string {
  const u = new URL(link.targetUrl);
  if (link.utmSource)   u.searchParams.set('utm_source',   link.utmSource);
  if (link.utmMedium)   u.searchParams.set('utm_medium',   link.utmMedium);
  if (link.utmCampaign) u.searchParams.set('utm_campaign', link.utmCampaign);
  u.searchParams.set('af_slug', link.slug);            // 어느 링크로 들어왔는지 표시
  u.searchParams.set('utm_id',  link.slug);            // GA4 가 기본 수집하는 항목이라 설정 없이도 링크별 분해가 된다

  // 목록에 있는 값만 넘긴다. 아무 값이나 넘기면 주소가 주입 통로가 된다
  if (query) for (const k of PASS_THROUGH) {
    const v = query[k];
    if (typeof v === 'string' && v.length && v.length <= 200) u.searchParams.set(k, v);
  }
  return u.toString();
}

const ALLOWED_HOSTS = [
  'aboutfishing.kr', 'www.aboutfishing.kr', 'm.aboutfishing.kr',
  'dev-platform.aboutfishing.kr',
];

export function assertSafeTargetUrl(raw: string) {
  let u: URL;
  try { u = new URL(raw); }
  catch { throw new BadRequestException('주소 형식이 올바르지 않습니다.'); }

  if (u.protocol !== 'https:')
    throw new BadRequestException('https 주소만 등록할 수 있습니다.');

  const ok = ALLOWED_HOSTS.some(h => u.hostname === h || u.hostname.endsWith('.' + h));
  if (!ok)
    throw new BadRequestException('어바웃피싱 도메인 주소만 등록할 수 있습니다.');
}

@Controller()
export class ShortlinkController {
  constructor(private readonly svc: ShortlinkService) {}

  @Get(':slug')
  async redirect(@Param('slug') slug: string, @Req() req: Request, @Res() res: Response) {
    // 0. 예약어·정적 파일은 즉시 404
    if (RESERVED.has(slug)) return res.status(404).send();

    const link = await this.svc.findBySlug(slug);
    const ua  = String(req.headers['user-agent'] || '');
    const env = detectEnv(ua);                      // 5장

    // 1. 없거나 꺼졌거나 만료된 링크 → 안내 페이지 (빈 404가 아니다)
    if (!link || !link.isActive || (link.expiresAt && link.expiresAt < new Date())) {
      res.status(404).type('html');
      return res.send(this.svc.renderNotFound());
    }

    // 2. 캐시 금지 — 안 하면 링크를 수정해도 옛 목적지로 간다
    res.setHeader('Cache-Control', 'no-store, max-age=0');
    res.setHeader('X-Robots-Tag', 'noindex');

    // 3. 사람이 누른 것만 기록 (봇 제외)
    if (!env.isBot) this.svc.logClick(link, req, env).catch(() => {});

    // 4. 분기할 필요가 없는 경우는 곧장 목적지로 보낸다
    //    · 앱 안 웹뷰  → 다시 앱을 열려 하면 무한 반복이 된다
    //    · PC 브라우저 → 앱이 없으므로 중간 페이지를 거칠 이유가 없다.
    //      302 로 보내면 원래 유입 경로(referer)도 그대로 전달되어 GA4 귀속이 살아난다
    if (env.isOurApp || env.device === 'pc') {
      return res.redirect(302, this.svc.buildTargetUrl(link, req.query));
    }

    // 5. 그 외에는 OG 태그 + 분기 스크립트가 담긴 HTML
    res.type('html');
    return res.send(this.svc.renderRedirectHtml(link, env));
  }
}

const esc = (s = '') => String(s)
  .replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;')
  .replace(/"/g,'&quot;').replace(/'/g,'&#39;');

// 자바스크립트 문자열 안에 넣을 때는 JSON.stringify 를 쓴다
const js = (s = '') => JSON.stringify(String(s));

renderRedirectHtml(link: ShortLink, env: Env): string {
  const ogTitle = esc(link.ogTitle       || '어바웃피싱 낚시배 예약');
  const ogDesc  = esc(link.ogDescription || '가까운 항구에서 출발하는 낚시배를 바로 예약하세요.');
  const ogImage = esc(link.ogImageUrl    || 'https://www.aboutfishing.kr/og-default.jpg');
  const ogUrl   = esc(`https://go.aboutfishing.kr/${link.slug}`);
  const web     = this.buildTargetUrl(link);
  const appPath = link.vesselId ? `vessel/${link.vesselId}` : 'home';
  // 앱으로 넘길 때도 UTM 을 잃지 않도록 목적지 전체를 딸려 보낸다 (7장)
  const appQuery = '?to=' + encodeURIComponent(web);
  ...
}

(function(){
  var WEB   = "…목적지 주소…";
  var SCHEME= "aboutfishing://vessel/123?to=…";
  var INTENT= "intent://vessel/123?to=…#Intent;scheme=aboutfishing;"
            + "package=kr.co.aboutfishing;S.browser_fallback_url=…;end";
  var IOS_STORE = "https://apps.apple.com/kr/app/id0000000000";

  var ua = navigator.userAgent;
  var isIOS = /iPhone|iPad|iPod/.test(ua);
  var isAOS = /Android/.test(ua);

  if (isAOS) {
    // 안드로이드는 intent 한 방이면 끝. 앱 있으면 앱, 없으면 fallback 주소로 간다
    location.replace(INTENT);
    return;
  }

  if (isIOS) {
    // 앱이 설치돼 있으면 Universal Link 가 이 스크립트 실행 전에 앱을 연다.
    // 여기까지 왔다는 것은 앱이 없거나 Universal Link 가 막힌 환경이라는 뜻.
    var t = setTimeout(function(){ location.replace(WEB); }, 1200);
    function cancel(){ if (document.hidden) clearTimeout(t); }
    document.addEventListener('visibilitychange', cancel);
    window.addEventListener('pagehide', function(){ clearTimeout(t); });
    location.href = SCHEME;
    return;
  }

  location.replace(WEB);   // PC
})();

const BOTS = [
  'kakaotalk-scrap', 'facebookexternalhit', 'twitterbot', 'slackbot',
  'telegrambot', 'discordbot', 'whatsapp', 'line-poker',
  'googlebot', 'yeti', 'daumoa', 'bingbot', 'embedly', 'skypeuripreview',
];

export type Env = {
  isBot: boolean; isOurApp: boolean;
  device: 'ios'|'android'|'pc'|'unknown';
  channel: 'app'|'kakao'|'instagram'|'naver'|'browser'|'unknown';
  needsExternal: boolean;   // 외부 브라우저로 빼야 하는 환경인가
};

export function detectEnv(uaRaw: string): Env {
  const ua = (uaRaw || '').toLowerCase();       // ← 반드시 소문자로 비교

  const isBot    = BOTS.some(b => ua.includes(b));
  const isOurApp = ua.includes('aboutfishingapp');  // 6장에서 앱이 붙여 보낸다

  const device =
      /iphone|ipad|ipod/.test(ua) ? 'ios'
    : /android/.test(ua)          ? 'android'
    : /windows|macintosh|linux/.test(ua) ? 'pc' : 'unknown';

  const channel =
      isOurApp                    ? 'app'
    : ua.includes('kakaotalk')   ? 'kakao'
    : ua.includes('instagram')  ? 'instagram'
    : ua.includes('naver')      ? 'naver'
    : device === 'unknown'      ? 'unknown' : 'browser';

  // 카카오·인스타·네이버 인앱은 앱 링크가 막혀 있다
  const needsExternal = ['kakao','instagram','naver'].includes(channel);

  return { isBot, isOurApp, device, channel, needsExternal };
}

var CH = "kakao";            // 서버가 채워 넣는다
var SELF = location.href;

if (CH === "kakao") {
  if (isIOS) {
    // Safari 로 이 주소를 다시 연다 → 그 다음은 4-7 의 일반 흐름
    // _r=1 : 두 번째 요청이라는 표시. 서버가 이 값을 보고 클릭을 다시 세지 않는다
    var again = SELF + (SELF.indexOf("?") < 0 ? "?" : "&") + "_r=1&_ch=kakao";
    location.href = "kakaotalk://web/openExternal?url=" + encodeURIComponent(again);
    return;
  }
  if (isAOS) { location.replace(INTENT); return; }
}

if (CH === "instagram" && isIOS) {
  // 탈출 불가 — 웹으로 보내고 안내 배너를 띄운다
  document.getElementById('openHint').style.display = 'block';
  setTimeout(function(){ location.replace(WEB); }, 2500);
  return;
}

<body>
  <div class="wrap">
    <img src="https://www.aboutfishing.kr/logo.svg" alt="어바웃피싱" width="120">
    <p>잠시만 기다려 주세요</p>
    <a id="manual" href="…목적지…">눌러도 이동하지 않으면 여기를 누르세요</a>
    <div id="openHint" style="display:none">
      오른쪽 위 ··· 을 눌러 <b>Safari 로 열기</b> 를 선택하면 앱으로 이동합니다.
    </div>
  </div>
</body>

- (BOOL)application:(UIApplication *)application
  continueUserActivity:(NSUserActivity *)userActivity
  restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> *))restorationHandler {
  return [RCTLinkingManager application:application
                   continueUserActivity:userActivity
                     restorationHandler:restorationHandler];
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
  return [RCTLinkingManager application:application openURL:url options:options];
}

<!-- ① https 링크 (App Links) -->
<intent-filter android:autoVerify="true">
  <action   android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https" android:host="go.aboutfishing.kr" />
</intent-filter>

<!-- ② 커스텀 스킴 (인앱 브라우저 탈출용) -->
<intent-filter>
  <action   android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="aboutfishing" />
</intent-filter>

import React, { useRef, useEffect, useCallback } from 'react';
import { Linking } from 'react-native';
import WebView from 'react-native-webview';

const WEB_BASE = 'https://www.aboutfishing.kr';

export default function App() {
  const webRef = useRef<WebView>(null);

  const go = useCallback((url: string) => {
    webRef.current?.injectJavaScript(`location.replace(${JSON.stringify(url)}); true;`);
  }, []);

  const handle = useCallback((raw?: string | null) => {
    if (!raw) return;

    // ① 커스텀 스킴: aboutfishing://vessel/123?to=https%3A%2F%2F...
    if (raw.startsWith('aboutfishing://')) {
      const u  = new URL(raw.replace('aboutfishing://', 'https://x/'));
      const to = u.searchParams.get('to');
      if (to) return go(to);                // UTM 이 붙은 최종 주소 그대로
      const id = u.pathname.replace('/vessel/', '');
      return go(id ? `${WEB_BASE}/vessels/${id}` : WEB_BASE);
    }

    // ② Universal Link / App Links: https://go.aboutfishing.kr/ab12cd
    if (raw.startsWith('https://go.aboutfishing.kr/')) {
      // 그대로 웹뷰에 로드한다. 서버가 앱 요청임을 알아보고(6-4) 302 로 목적지까지 보내준다.
      return go(raw);
    }
  }, [go]);

  useEffect(() => {
    Linking.getInitialURL().then(handle);                        // 앱이 꺼져 있던 경우
    const sub = Linking.addEventListener('url', e => handle(e.url)); // 앱이 켜져 있던 경우
    return () => sub.remove();
  }, [handle]);

  return (
    <WebView
      ref={webRef}
      source={{ uri: WEB_BASE }}
      style={{ flex: 1 }}
      /* ↓ 6-4 — 서버가 앱 안 요청임을 구분하는 근거 */
      applicationNameForUserAgent="AboutFishingApp/1.0"
      originWhitelist={['https://*', 'aboutfishing://*']}
      setSupportMultipleWindows={false}
    />
  );
}

async logClick(link: ShortLink, req: Request, env: Env) {
  const ua = String(req.headers['user-agent'] || '').slice(0, 500);
  const ip = (req.headers['x-forwarded-for'] as string || req.ip || '').split(',')[0].trim();

  await this.clickLogRepo.insert({
    linkId:    link.id,
    slug:      link.slug,
    vesselId:  link.vesselId,
    deviceType: env.device,
    channel:    env.channel,
    referer:   String(req.headers.referer || '').slice(0, 500) || null,
    userAgent: ua,
    ipHash:    hashIp(ip),          // 10장
  });

  await this.shortLinkRepo.increment({ id: link.id }, 'clickCount', 1);
}

this.bigquery.dataset('aboutfishing').table('shortlink_clicks').insert([{
  link_id: link.id, slug: link.slug, vessel_id: link.vesselId,
  device_type: env.device, channel: env.channel,
  referer: req.headers.referer || null,
  clicked_at: new Date().toISOString(),
}]).catch(() => {});   // 적재 실패가 리다이렉트를 막으면 안 된다

import * as QRCode from 'qrcode';

@Get(':id/qr')
async qr(
  @Param('id', ParseIntPipe) id: number,
  @Query('format') format = 'png',
  @Query('disposition') disposition = 'attachment',   // inline 이면 미리보기용
  @Query('size', new DefaultValuePipe(800), ParseIntPipe) size: number,
  @Res() res: Response,
) {
  const link = await this.svc.findById(id);
  if (!link) throw new NotFoundException();

  const url = `https://go.aboutfishing.kr/${link.slug}`;
  const opt = {
    errorCorrectionLevel: 'H' as const,   // 30% 가려져도 읽힌다 — 인쇄물·로고 삽입 대비
    margin: 2,
    color: { dark: '#1A1A1A', light: '#FFFFFF' },
  };

  if (format === 'svg') {
    const svg = await QRCode.toString(url, { ...opt, type: 'svg' });
    res.setHeader('Content-Type', 'image/svg+xml');
    res.setHeader('Content-Disposition', `attachment; filename="${link.slug}.svg"`);
    return res.send(svg);
  }

  const buf = await QRCode.toBuffer(url, { ...opt, type: 'png', width: Math.min(size, 2000) });
  res.setHeader('Content-Type', 'image/png');
  if (disposition === 'inline') res.setHeader('Content-Disposition', 'inline');
  else res.setHeader('Content-Disposition', `attachment; filename="${link.slug}.png"`);
  return res.send(buf);
}

export class CreateShortlinkDto {
  @IsOptional() @IsInt()                      vesselId?: number;
  @IsString() @Length(1, 120)                 title: string;
  @IsOptional() @Matches(/^[a-z0-9-]{3,24}$/) slug?: string;
  @IsUrl({ protocols: ['https'], require_protocol: true }) targetUrl: string;

  @IsOptional() @Length(0, 40)  ogTitle?: string;        // 카카오 미리보기 제목 권장 상한
  @IsOptional() @Length(0, 80)  ogDescription?: string;
  @IsOptional() @IsUrl()          ogImageUrl?: string;

  @IsOptional() @IsIn(['naver','kakao','instagram','youtube','offline','partner']) utmSource?: string;
  @IsOptional() @IsIn(['blog','post','profile','qr','card','banner','dm'])       utmMedium?: string;
  @IsOptional() @Length(0, 100) utmCampaign?: string;

  @IsOptional() @IsDateString()   expiresAt?: string;
  @IsOptional() @Length(0, 500) memo?: string;
}

@Get('export.csv')
async exportCsv(@Query() q: ListQueryDto, @Res() res: Response) {
  const rows = await this.svc.findAllForExport(q);
  const head = ['링크명','선박','단축주소','목적지','유입경로','클릭수','상태','만료일','등록자','등록일'];
  const cell = (v: any) => `"${String(v ?? '').replace(/"/g, '""')}"`;
  const body = rows.map(r => [
    r.title, r.vesselName, `https://go.aboutfishing.kr/${r.slug}`, r.targetUrl,
    [r.utmSource, r.utmMedium].filter(Boolean).join('/'),
    r.clickCount, r.isActive ? '사용' : '중지',
    r.expiresAt ?? '', r.createdByName, r.createdAt,
  ].map(cell).join(','));

  const csv = '' + [head.map(cell).join(','), ...body].join('\r\n');
  res.setHeader('Content-Type', 'text/csv; charset=utf-8');
  res.setHeader('Content-Disposition', 'attachment; filename="shortlinks.csv"');
  return res.send(csv);
}

const SALT = process.env.CLICK_IP_SALT;   // 환경변수. 코드에 적지 않는다

export function hashIp(ip: string): string | null {
  if (!ip) return null;
  // 날짜를 섞어 매일 다른 값이 되게 한다 → 장기 추적 불가, 당일 중복 제거는 가능
  const day = new Date().toISOString().slice(0, 10);
  return crypto.createHash('sha256').update(SALT + day + ip).digest('hex');
}

CREATE TABLE short_link_histories (
  id         BIGINT AUTO_INCREMENT PRIMARY KEY,
  link_id    BIGINT NOT NULL,
  action     ENUM('create','update','activate','deactivate') NOT NULL,
  changes    JSON,           -- {"targetUrl":{"before":"…","after":"…"}}
  admin_id   BIGINT,
  admin_name VARCHAR(60),
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  KEY idx_link (link_id, created_at)
);

{
  "items": [ { ... }, { ... } ],
  "total": 128,          // 필터 적용 후 건수 (Total 표시에 그대로 쓴다)
  "page": 1,             // 1부터 시작
  "size": 20
}

{
  "id": 128,
  "slug": "ab12cd",
  "shortUrl": "https://go.aboutfishing.kr/ab12cd",   // 서버가 조립해서 내려준다
  "title": "스테이지테스트호 예약 — 네이버 블로그",
  "vesselId": 1023,
  "vesselName": "스테이지테스트호",                      // 조인해서 같이 내려준다
  "targetUrl": "https://www.aboutfishing.kr/vessels/1023",
  "ogTitle": "...", "ogDescription": "...", "ogImageUrl": "...",
  "utmSource": "naver", "utmMedium": "blog", "utmCampaign": "v1023_202609",
  "clickCount": 1284,
  "status": "active",          // active | inactive | expired ← 서버가 판정해서 내려준다
  "expiresAt": "2026-12-31T23:59:59+09:00",
  "memo": "...",
  "createdBy": 7, "createdByName": "신다훈",
  "updatedBy": 9, "updatedByName": "김채린",
  "createdAt": "2026-09-18T14:02:11+09:00",
  "updatedAt": "2026-09-20T16:41:03+09:00"
}

{
  "code": "SLUG_DUPLICATED",
  "message": "이미 사용 중인 주소입니다.",
  "field": "slug"          // 특정 입력칸 문제일 때만. 없으면 화면 상단에 띄운다
}

// 요청
{
  "vesselIds": [1023, 884, 771],        // 최대 100
  "titleTemplate": "{선박명} — 네이버 블로그",
  "targetMode": "vesselDetail",          // vesselDetail | fixed
  "targetUrl": null,                     // fixed 일 때만
  "utmSource": "naver", "utmMedium": "blog",
  "expiresAt": null, "memo": "9월 선사 블로그 배포분",
  "requestKey": "b3f1e0c2-..."           // 같은 키로 두 번 오면 두 번째는 무시한다
}

// 응답 200 — 부분 성공을 허용한다
{
  "requested": 3, "succeeded": 2, "failed": 1,
  "results": [
    { "vesselId": 1023, "vesselName": "스테이지테스트호", "status": "ok",
      "id": 129, "slug": "ab12cd", "shortUrl": "https://go.aboutfishing.kr/ab12cd" },
    { "vesselId": 884,  "vesselName": "광어호", "status": "ok", "id": 130, "slug": "p7m3kq", "shortUrl": "..." },
    { "vesselId": 771,  "vesselName": "참돔호", "status": "failed",
      "code": "TARGET_URL_NOT_FOUND", "message": "선박 상세 주소를 만들 수 없습니다." }
  ]
}

{
  "range": { "from": "2026-08-23", "to": "2026-09-21", "days": 30 },
  "summary": {
    "totalClicks": 1284,
    "uniqueClicks": 938,          // 일별 유니크의 합 (해시가 매일 바뀌므로 기간 전체 유니크는 낼 수 없다)
    "appBranchRate": 0.612,       // 추정값
    "dailyAverage": 42.8
  },
  "daily":   [ { "date": "2026-08-23", "clicks": 22 }, ... ],   // 0인 날도 0으로 채워 내려준다
  "channel": [ { "key": "kakao", "label": "카카오톡", "clicks": 612 }, ... ],
  "device":  [ { "key": "android", "label": "안드로이드", "clicks": 548, "rate": 0.427 }, ... ],
  "recent":  [ { "clickedAt": "2026-09-21T14:22:07+09:00", "channel": "kakao", "device": "ios" }, ... ]
}