# 📌 핀노트 (Pinnote)

어떤 웹사이트에든 **스크립트 한 줄**을 붙이면 됩니다. 사람들이 화면 요소에 핀을 꽂아 의견을 남기고, 여러 사이트의 의견이 한곳에 모입니다.
개발자(사람 또는 AI)는 **어느 사이트·화면·요소**에 대한 의견인지 정확히 보고 고칩니다. 고친 뒤에는 건마다 **완료 응답**을 남기고, 의견을 남긴 사람이 확인하거나 다시 엽니다.

- 관리 화면: https://pinnote.itemview.co.kr/admin/
- 데모: https://pinnote.itemview.co.kr/demo/?pinnote=1 (이름만 바뀐 버전 `?v=2`, 요소가 사라진 버전 `?v=3`)
- 문서: https://pinnote.itemview.co.kr/docs/ (붙이기 · API · 설계). **다른 사이트에 붙일 때는 [docs/INSTALL.md](docs/INSTALL.md) 한 장만 보면 된다.**

## 설치 한 줄

```html
<script src="https://pinnote.itemview.co.kr/w.js" data-site="pk_사이트키" defer></script>
```

선택 속성

| 속성 | 뜻 |
|---|---|
| `data-version="1.4.2"` | 앱 버전(의견에 함께 저장) |
| `data-env="staging"` | 환경 |
| `data-mode="toggle"` | `toggle`(기본, 📌 버튼으로 켜기) · `always`(항상 켜짐) · `off` |
| `data-capture="off"` | 요소 주변 캡처 끄기 |
| `data-errors="off"` | 최근 JS 오류 수집 끄기 |
| `data-lang="ko"` | 언어(지금은 한국어만) |
| `data-position="left"` | 📌 버튼을 왼쪽에 둔다(기본 `right`) |
| `data-offset-bottom="72"` | 📌 버튼을 바닥에서 이만큼(px) 올린다. 하단 고정 버튼·탭바가 있는 사이트용 |
| `data-offset-x="16"` | 📌 버튼과 화면 옆 가장자리 사이(px) |
| `data-name="홍길동"` | 의견 창 이름 칸의 기본값(저장된 이름이 있으면 그것이 우선). 표시용 이름만 넣는다 |

- 사이트 CSS의 `:root`에 `--pinnote-offset-bottom: 72px`를 두어도 된다(속성·`setPosition`이 우선).

- 주소에 `?pinnote=1`을 붙이면 의견 모드가 켜집니다(`?pinnote=0`은 끄기).
- **사이트에 Content-Security-Policy가 있으면** 다음 항목에 `https://pinnote.itemview.co.kr`을 더해야 합니다.
  - `script-src`, `connect-src`: 필수
  - `img-src`: 다시 연결 썸네일용
- 사이트 요소에 `data-ui="order.submit"` 같은 안정 이름을 붙이면 요소를 가장 정확히 다시 찾습니다.
- 가릴 영역에는 `data-pinnote-mask` 또는 `.pn-mask`를, 핀을 달지 않을 영역에는 `data-pinnote-ignore`를 붙입니다.

### 사이트 코드에서 쓰기

```js
Pinnote.setContext({ screen: 'checkout', journey_id: 'J123' }); // 의견에 함께 저장
Pinnote.setName('홍길동');                   // 이름 칸 기본값 (''이면 지우기, 창이 열려 있으면 바로 반영)
Pinnote.setPosition({ bottom: 72, side: 'right' }); // 하단 바 높이가 바뀔 때마다 알려 주기
Pinnote.open({ page: true });                // 화면 전체 의견 창
Pinnote.open({ selector: '#pay-button' });   // 특정 요소 의견 창
Pinnote.open();                              // 요소 고르기 모드
Pinnote.on('submitted', (d) => console.log('의견', d.id));
document.addEventListener('pinnote:submitted', (e) => console.log(e.detail));
```

설치 한 줄(`defer`)이 실행된 뒤의 호출은 위젯 본체가 아직 안 왔어도 로더가 쌓아 두었다가 넘깁니다. 그래서 사이트 코드는 `DOMContentLoaded` 안에서 부르면 안전합니다.

## 기능

- **Shadow DOM 위젯**
  - 호스트 페이지의 레이아웃·CSS에 영향을 주지 않습니다. 켜기 전후에 요소 좌표가 같은지 확인했습니다.
  - 인라인 style을 막는 엄격한 CSP에서도 동작합니다.
- **핀**
  - `[data-ui]` 요소를 먼저, 나머지는 휴리스틱으로 고릅니다. 겹치지 않게 놓고, 모바일에서는 28px로 그립니다.
  - 기존 의견 개수와 상태를 배지로 보여 줍니다.
  - 요소 직접 고르기와 화면 전체 의견도 됩니다.
- **의견 창**
  - 입력: 종류(아이디어·불편·오류·문구·디자인, 기본은 아이디어), 내용, 이름(`data-name`·`Pinnote.setName()`으로 미리 채울 수 있음)
  - 이 요소의 기존 의견(상태·공감·댓글·완료 응답)
- **여러 겹의 구분자**
  - 사이트: 도메인, URL, 화면 키(경로 규칙 `/t/:token`), 제목, 버전·환경
  - 요소 찾는 방법 9가지: data-ui, id, 짧은 선택자, DOM 경로, 태그·역할·접근성 이름, 텍스트, 기준 제목, 좌표 비율, 속성
  - 요소 원래 모습: HTML·스타일·크기, 요소 주변 캡처
  - 환경·사용자 문맥
- **요소가 바뀌거나 사라질 때**
  - 방문마다 다시 찾아 ATTACHED / RELOCATED(선택자 자동 갱신 + 이력) / MISSING(방문 N번·N일)으로 나눕니다.
  - **사라진 요소** 목록에서 원래 모습을 보고 [수정으로 해결됨] / [다시 연결](페이지에서 새 요소 클릭) / [보관]으로 정리합니다.
- **상태 흐름**
  - `NEW → TRIAGED → IN_PROGRESS → RESOLVED(완료 응답 필수) → VERIFIED / REOPENED`
  - 그 밖에 `WONT_FIX`(사유), `DUPLICATE`(원본), `NEEDS_INFO`가 있습니다. `VERIFIED`·`REOPENED`는 관리 화면·REST·CLI에서만 바꿉니다.
  - 모든 변경은 히스토리에 남습니다: 누가·언제·이전→이후·메모.
- **보고자에게 처리 시각·처리 알림을 보이지 않음**: 위젯에는 "N분 전"·"처리됐어요" 알림·[확인했어요]가 없습니다(작업 시간 추적 방지). 확인 완료·다시 열기는 관리 화면·REST·CLI에서 합니다.
- **전송 실패 보관 후 재전송**, **포커스 모드**(`?pinnote_focus=번호`: 스크롤 + 깜빡임)
- **개발자·AI**
  - REST API v1(토큰)
  - 마크다운/JSON 내보내기(사이트 → 화면 → 요소 → 의견)
  - CLI `bin/pinnote.php`
- **관리 화면**: 받은 의견함(필터·일괄 처리), 사이트별 보기, 의견 상세(스냅샷·문맥·댓글·히스토리·상태 버튼), 사라진 요소, 사이트 설정, API 토큰, 통계
- **보안**
  - 위젯 API: 공개 키 + Origin 허용 목록, CORS, IP 해시 기준 시간당 제한, 크기 제한
  - 관리 화면: CSRF, 서명 쿠키
  - 출력 이스케이프, 민감 값 가림
  - 설정·저장소는 웹 루트 밖

## 관리 화면

- **[위젯 닫기] / [위젯 열기]**: 첫 화면 위젯 줄과 사이트 목록에서 한 번 누르면 된다. 닫으면 그 사이트에서 핀노트가 흔적 없이 사라지고(버튼·오류·재시도 없음), 의견과 기록은 그대로 남는다.

1. `/admin/`에서 관리자 비밀번호와 이름(목록에서 고르거나 새로 입력)으로 들어갑니다.
2. **사이트 설정 → 새 사이트**: 도메인을 넣으면 사이트 키와 설치 한 줄이 나옵니다. 여기서 경로 규칙, 사라짐 기준, 캡처 켜기·끄기를 정합니다.
3. **받은 의견**에서 정리하고, 의견 상세에서 **이 요소를 실제 페이지에서 보기**로 확인합니다.
4. 해결할 때는 **완료 응답**(무엇을 어떻게 고쳤는지)을 적습니다.
5. **API 토큰**을 만들어 에이전트나 CI에 넘깁니다. 사용법은 [docs/API.md](docs/API.md)에 있습니다.

## API 한눈에

```bash
curl -H "Authorization: Bearer $PN_TOKEN" "https://pinnote.itemview.co.kr/api/v1/items?site=1&status=open"
curl -H "Authorization: Bearer $PN_TOKEN" "https://pinnote.itemview.co.kr/api/v1/export?site=1&status=open"   # 마크다운
curl -X POST -H "Authorization: Bearer $PN_TOKEN" -H 'Content-Type: application/json' \
  -d '{"status":"RESOLVED","note":"무엇을 어떻게 고쳤는지","version":"1.4.2"}' https://pinnote.itemview.co.kr/api/v1/items/12/status
php bin/pinnote.php resolve 12 "무엇을 어떻게 고쳤는지" --version=1.4.2
```

## 서버 설치·운영

```bash
# PHP 8.2 + MariaDB + Apache(AllowOverride All), 웹 루트 = public/
cp config.local.php.example config.local.php   # db, base_url, admin_password, app_secret (웹 루트 밖, git 제외)
php bin/migrate.php      # db/migrations/NNN_*.sql 순서대로 적용 (여러 번 실행해도 안전)
php bin/seed.php         # 기본 워크스페이스·뉴팅 데모·핀노트 데모 사이트와 사이트 키 출력 (중복 없음)
```

- `config.local.php`는 apache가 읽을 수 있어야 합니다(`chgrp apache`, 640).
- `storage/`(logs, shots)는 apache가 쓸 수 있어야 합니다.

## 폴더

```
public/            웹 루트
  w.php            /w.js 로더(캐시 안 함) → widget/pinnote.js?v=버전(길게 캐시)
  widget/          위젯 본체
  vendor/          html2canvas 1.4.1 (MIT, 라이선스 파일 포함)
  api/w/           위젯 API
  api/v1/          REST API v1
  admin/           관리 화면
  demo/            데모 사이트(샘플 페이지 2개)
  docs/            문서 보기
  shot.php         캡처 보기(서명 URL)
lib/               공통 코드(웹 루트 밖)
db/migrations/     스키마
bin/               migrate, seed, pinnote(CLI)
docs/              INSTALL.md, API.md, DESIGN.md
storage/           logs, shots (git 제외)
```