peterruiter/claude-build-framework

Dataverse / Dynamics 365 통합 구축

가이드는 docs/integrations-dynamics.md에 있습니다. 먼저 읽으십시오. 이 스킬은 작업 순서입니다. 하나의 웨이브(waves-and-agents.md)로 계획하십시오. 엔진, 커넥터, 스탠드인 및 관리 UI는 계약(테이블, 커넥터 인터페이스, 설정 이름)이 작성되면 병렬 에이전트로 작업할 수 있습니다.

1. 소유자에게 묻기 (한 메시지, 번호 매기기, 각각 권장 사항 포함)

1. 어떤 흐름, 어떤 방향: 어떤 제품 레코드가 어떤 Dataverse 행이 되는지(연락처, 리드, 타임라인의 노트, Customer Insights - Journeys 이벤트 테이블, 커스텀 트리거), 그리고 읽어올 항목이 있는지(정적 마케팅 목록, 옵트아웃). 기본값: 단방향, 제품에서 Dynamics로, 요청 시 정적 목록 읽기.
2. 로그인 모델: 제품 자체의 멀티 테넌트 앱을 관리자 동의 및 사용자 정의 최소 권한 역할을 가진 애플리케이션 사용자와 함께 권장합니다. 고객별 앱 등록(인증서 선호)은 대체 방식으로 유지합니다. 서비스가 관리 ID를 페더레이션 자격 증명(시크릿 없음)으로 사용할 수 있는지 또는 인증서가 필요한지 물어보십시오.
3. 멀티 테넌트 앱을 호스팅할 Entra 테넌트, 등록하는 사람, 게시자 확인을 완료하는 사람. (소유자가 수행하며, 사용자는 단계를 준비합니다.)
4. 일치 규칙: 연락처는 이메일로 일치(세 열 모두, 활성 상태 우선); "대체"로 매핑되지 않는 한 비어 있지 않은 CRM 필드를 덮어쓰지 않음; 고유한 정확한 이름에서만 계정 연결; 계정을 생성하지 않음. 확인 또는 조정.
5. 동의: 고객은 동기화가 시작되기 전에 개인정보 보호 고지를 확인해야 합니다. 동의 질문에 게이트를 설정하거나 설정하지 않음; 동의가 제공되는 제품이 아니면 마케팅 동의를 기록하지 않으며, 소유자가 연락처 포인트 동의 레코드를 작성하기로 결정한 경우에만 기록합니다.
6. 여정: 원하는 커스텀 트리거(등록됨, 취소됨, 체크인, 리드 캡처 등 어떤 신호인지), 또는 동기화된 레코드에 대한 기본 제공 비즈니스 트리거로 충분한지.
7. 테스트용 실제 환경: 어떤 환경(전용 샌드박스/평가판 선호), 범위(레코드 상한, 하나의 테스트 트리거), 그리고 별도의 승인 없이는 스키마, 솔루션, 보안 역할 또는 앱 등록 변경이 허용되지 않는다는 확인.

결정 사항을 STATE.md에 기록하고 웨이브를 ROADMAP.md에 기록하십시오.

2. 계약 및 데이터 모델

• 테이블: 연결(작업공간/테넌트 및 환경별: URL, 테넌트 ID, 로그인 종류, 볼트 시크릿 이름, 힌트 및 만료, 상태, 일시 중지 기한, 프로브 결과 JSON, 설정/매핑 JSON, 개인정보 확인자/확인 시각), 동기화 항목(레코드당 한 행: 종류, 소스 ID, CRM 테이블 및 ID, 버전, 클레임 버전, 시도 횟수, 다음 시도, 마지막 오류, 마지막 신호), 이벤트/범위별 링크(포함됨, 연결된 CRM 이벤트, 캠페인, 동의 질문, 선택된 스폰서 또는 소스), 백필 커서, 동기화 로그(30일).
• 커넥터 인터페이스(CRM 중립): Probe, Write(rows) -> results (Synced | Retry | Throttled(RetryAfter) | Refused), Lookup(이벤트, 캠페인, 목록), RecordLink, 기본 매핑, 자체 열. CRM이 제공한 답변에 대해 예외를 던지지 않음.
• 설정: 로그인 기본 URL(노트북의 스탠드인), 플랫폼 클라이언트 ID, 볼트 시크릿 이름. 설정 계약(contracts.md)에 추가하십시오.

3. 다음 순서로 구축

1. 네트워크 없는 도메인 규칙: 환경 URL 검증(Dataverse 호스트, 주권 클라우드 포함, https, 경로 없음), Web API 루트(/api/data/v9.2/), 토큰 범위(https://<ENV>/.default), OData 리터럴 이스케이프, 오류 파싱(코드, 메시지), $batch 기록기 및 읽기(변경 집합 읽기 포함), 결정론적 ID(작업공간, 호스트, 종류, 소스 ID의 UUID v5), 레코드 딥 링크(main.aspx?appid=...&pagetype=entityrecord&etn=...&id=...). 단위 테스트.
2. 토큰: 클라이언트 자격 증명(시크릿, x5t#S256을 사용한 인증서 어설션, 플랫폼 앱, 개발 전용 개발자 az 토큰), 만료 5분 전까지 해시로 캐시, 401 발생 시 제거하고 한 번 재시도, Entra의 첫 번째 오류 줄을 UI로 전달.
3. 프로브: WhoAmI, RetrieveVersion(), 엔터티 집합, 쓰기 가능성 및 최대 길이를 포함한 속성, 다대일 탐색 속성 이름, 준비된 커스텀 트리거 및 해당 매개변수; 해당 테이블이 존재하는 경우에만 모드 제공.
4. 쓰기: 중복 감지가 설정된 연락처 일치 후 upsert, 고유한 경우 계정 링크, 결정론적 ID로 PATCH를 사용한 노트 및 소유 레코드, 리드 생성 전용(If-None-Match: *), If-Match: *를 사용한 업데이트(동일한 필드를 편집하는 경우 ETag 사용), statecode 및 statuscode, 모든 속성이 채워진 바인딩되지 않은 작업으로서의 커스텀 트리거.
5. 엔진: 훅 및 스윕, 복제본 간 클레임(한 사람의 행은 직렬, 종속성 우선), 재시도 스케줄(데드 레터 포함), 429 발생 시 Retry-After 동안 연결 일시 중지, 연결당 동시성 상한, $batch로 백필(독립 요청, Prefer: odata.continue-on-error, 소규모 배치), 연결 해제.
6. 관리 UI (모든 설정 언어): 연결 마법사(환경, 플랫폼 앱의 관리자 동의 링크를 통한 로그인, 발견된 모드를 보여주는 테스트, 동기화 대상, 실제 열에 대해 검증된 매핑, 이벤트/범위, 개인정보 확인), 연결 페이지(상태, 로그, 실패 재시도, 자격 증명 교체, 인증서 만료), 레코드별 "Dynamics에서 열기" 및 "다시 동기화" 링크, 정확한 역할 권한 및 Power Platform 관리 센터 단계를 나열하는 "연결 방법" 도움말 서랍.
7. 알림: 갱신 후 CRM이 로그인을 거부하면 작업공간 관리자에게 한 번 이메일 전송.

4. 테스트

• 스탠드인 우선: templates/project/tests/standins/dataverse.mjs와 해당 테스트를 tests/standins/로 복사하고, 테이블로 확장(testing.md의 패턴): 토큰 엔드포인트, 메타데이터, upsert 및 조건부 헤더가 포함된 CRUD, 바인딩되지 않은 작업, $batch, Dataverse 스타일 유효성 검사, 스로틀, 실패, 토큰 만료 및 상태 제어. 단위 테스트용 가짜 HTTP 핸들러 쌍.
• 가이드 목록의 단위 및 데이터베이스 테스트. 데스크톱 및 휴대폰 너비, 밝은 모드 및 어두운 모드, 두 가지 언어로 마법사 및 연결 페이지의 브라우저 확인.
• 실제 환경이 실행될 때까지 **"스탠드인에 대해서만 확인됨"**으로 보고.
• 실제 샌드박스는 해당 환경 및 범위에 대해 소유자의 명시적 승인이 있는 경우에만: az account get-access-token --resource https://<ENV>.crm4.dynamics.com --subscription <SUBSCRIPTION_ID>를 통한 토큰(기본 계정 또는 pac 프로필을 전환하지 않음), 실행 ID 및 하드 상한으로 표시된 레코드, 생성된 모든 ID 기록, 가이드의 확인 순서, 기록된 ID로 정리, 이후 0개 카운트, 생성 및 제거된 항목에 대한 간단한 보고서.

5. 소유자 체크리스트 (제공하고 직접 수행하지 마십시오)

• 멀티 테넌트 앱 등록(또는 등록하지 않기로 결정), 자격 증명 추가(페더레이션 관리 ID 또는 인증서) 및 동의된 이름으로 볼트에 시크릿 저장; 클라이언트 ID 설정.
• 게시자 확인.
• 최소 권한 역할을 고객용 관리 솔루션으로 패키징(선택 사항이지만 권장).
• 각 고객에 대해: 관리자 동의 링크, 역할이 있는 애플리케이션 사용자, 환경 URL 및 테넌트 ID를 제품에 입력, 테스트.

6. 기록

STATE.md: 구축된 내용, 모드, 실행 위치, 입증되지 않은 테이블(실제 환경, 탐색 속성 이름, 선택적 모듈의 필수 열, 중복 감지의 실제 응답, 변경 집합이 있는 $batch, 실제 커스텀 트리거, 스로틀링, 관리자 동의 및 고객 테넌트의 인증서). 입증될 때마다 가이드의 (확인) 표시를 업데이트하십시오. 모든 언어로 릴리스별 새로운 기능 항목.

규칙

• 소유자의 명시적 승인 없이 실제 환경 호출, 스키마/솔루션/역할/앱 등록/동의 변경 또는 생성하지 않은 레코드 삭제를 수행하지 마십시오.
• 코드, 로그, 채팅, 커밋 또는 보고서에 시크릿을 포함하지 마십시오. 볼트만 사용하십시오. 호스트, 상태, 오류 코드를 기록하십시오.
• 공유되는 모든 항목의 자리 표시자: <ENV>.crm4.dynamics.com, <TENANT_ID>, <CLIENT_ID>.
• 어디에도 AI 저작자 표시를 하지 마십시오.