@soddong/agentic-domain-artifact-standard 0.11.0

package/docs/usage.md

@@ -0,0 +1,197 @@
+# Usage
+
+이 패키지는 산출물 유형별 `Artifact Standard` 정보, aggregate 기반 document import profile helper, legacy document import profile fixture, SQLite repository/service를 제공한다.
+
+`Artifact Standard`는 템플릿, 가이드, 예시, 문서 blueprint, document component, physical structure policy, block/table schema, validation rule을 묶은 산출물 작성 표준이다. `Package`는 npm 배포 단위를 의미할 때만 사용하고, 도메인 개념에는 `Artifact Standard Package` 대신 `Artifact Standard`를 사용한다.
+
+현재 API에는 호환성을 위해 `getArtifactStandardPackageInfo()`, `artifactStandardPackageCode` 명명이 남아 있다. 신규 호출은 `getArtifactStandardInfo()`, `artifactStandardCode` 계열을 우선 사용한다.
+
+## Profile 용어 구분
+
+`ArtifactStandardProfile`은 산출물 표준 자체의 복수 작성 모드 후보 모델이며, 1차 DB 모델에서는 제외되어 있다.
+
+반면 다음 profile은 현재 사용한다.
+
+| 용어 | 의미 |
+| --- | --- |
+| `DocumentImportProfile` | `@soddong/agentic-domain-document` importer에 전달하는 외부 contract |
+| validation provider profile | `@soddong/agentic-contract-validation`의 rule bundle/provider profile |
+
+따라서 `DocumentImportProfile` helper와 validation provider manifest는 `ArtifactStandardProfile` 도입이 아니라 외부 contract 연계 기능이다.
+
+```ts
+import {
+  createDocumentImportProfileFromArtifactStandardAggregate,
+  getArtifactStandardDocumentProfile,
+  getArtifactStandardInfo
+} from "@soddong/agentic-domain-artifact-standard";
+
+const info = getArtifactStandardInfo();
+console.log(info.name);
+
+const profile = getArtifactStandardDocumentProfile({
+  artifactStandardCode: "architecture_specification"
+});
+
+console.log(profile.documentTypeCode);
+```
+
+`getArtifactStandardDocumentProfile()`은 호환성을 위해 유지되는 legacy fixture provider다. 신규 산출물 표준은 DB aggregate에서 `DocumentImportProfile`을 도출하는 방식을 우선한다.
+
+## SQLite Service
+
+```ts
+import {
+  ArtifactStandardService,
+  openArtifactStandardDatabase
+} from "@soddong/agentic-domain-artifact-standard";
+
+const db = openArtifactStandardDatabase();
+const service = new ArtifactStandardService(db);
+
+const standard = service.createArtifactStandard({
+  artifactStandardCode: "business_process_definition",
+  artifactStandardVersion: "1.0.0",
+  artifactStandardName: "Business Process Definition"
+});
+```
+
+## Aggregate 조회
+
+`getArtifactStandardAggregateByCodeVersion()`은 standard, components, blueprints, template slots, document components, component relations, physical structure policies, table schemas, columns, validation rule sets, source mappings를 한 번에 반환한다.
+
+```ts
+const aggregate = service.getArtifactStandardAggregateByCodeVersion(
+  "business_process_definition",
+  "1.0.0"
+);
+
+console.log(aggregate?.documentComponents);
+console.log(aggregate?.physicalStructurePolicies);
+console.log(aggregate?.tableSchemas[0]?.columns);
+```
+
+Aggregate에서 document import profile을 생성할 수 있다.
+
+```ts
+if (aggregate !== undefined) {
+  const profile = createDocumentImportProfileFromArtifactStandardAggregate(aggregate);
+  console.log(profile.profileCode);
+  console.log(profile.defaultTocLevelLimit);
+}
+```
+
+이 helper는 `DocumentBlueprint`, `TemplateSlot`, `TableSchema`, `ValidationRuleSet`을 기반으로 `@soddong/agentic-domain-document`의 `DocumentImportProfile`을 생성한다.
+
+## Fixture 사용 예시
+
+Business Process Definition과 Information Object Definition fixture는 선행/후행 산출물 context 조립 검증에 사용할 수 있다.
+
+```ts
+import {
+  createDocumentImportProfileFromArtifactStandardAggregate,
+  seedBusinessProcessDefinitionArtifactStandard,
+  seedInformationObjectDefinitionArtifactStandard
+} from "@soddong/agentic-domain-artifact-standard";
+
+const sourceFixture = seedBusinessProcessDefinitionArtifactStandard(service);
+const targetFixture = seedInformationObjectDefinitionArtifactStandard(service);
+
+const sourceProfile = createDocumentImportProfileFromArtifactStandardAggregate(sourceFixture.aggregate, {
+  blueprintCode: "main_document"
+});
+
+const targetProfile = createDocumentImportProfileFromArtifactStandardAggregate(targetFixture.aggregate, {
+  blueprintCode: "main_document"
+});
+
+console.log(sourceProfile.profileCode); // business_process_definition.main_document
+console.log(targetProfile.profileCode); // information_object_definition.main_document
+```
+
+## Document Component 사용
+
+`DocumentComponent`는 실제 산출물 문서의 본문, 부록, 보조자료 같은 논리 구성 단위를 정의한다. `Component`가 개념, 서식, 가이드, 예시 같은 작성 참고 resource라면, `DocumentComponent`는 산출물 자체의 구성 단위다.
+
+```ts
+const main = service.addDocumentComponent({
+  artifactStandardId: standard.artifactStandardId,
+  documentComponentCode: "main_document",
+  documentComponentName: "Business Process Definition Main Document",
+  componentRoleCode: "MAIN",
+  componentTypeCode: "MAIN_DOCUMENT",
+  logicalLevel: 0
+});
+
+const appendix = service.addDocumentComponent({
+  artifactStandardId: standard.artifactStandardId,
+  parentDocumentComponentId: main.documentComponentId,
+  documentComponentCode: "appendix_l3_process",
+  documentComponentName: "L3 Process Appendix",
+  componentRoleCode: "APPENDIX",
+  componentTypeCode: "L3_PROCESS_APPENDIX",
+  logicalLevel: 1,
+  isRepeatable: true
+});
+
+service.addDocumentComponentRelation({
+  artifactStandardId: standard.artifactStandardId,
+  sourceDocumentComponentId: main.documentComponentId,
+  targetDocumentComponentId: appendix.documentComponentId,
+  relationTypeCode: "CONTAINS",
+  isRequired: true
+});
+```
+
+물리 파일/폴더 구조는 component 계층과 별도로 `PhysicalStructurePolicy`로 정의한다.
+
+```ts
+service.addPhysicalStructurePolicy({
+  artifactStandardId: standard.artifactStandardId,
+  policyCode: "grouped_by_parent",
+  policyName: "Group Appendix Documents By Parent Component",
+  strategyCode: "GROUPED_BY_PARENT",
+  relationSourceCode: "DB",
+  pathPattern: "business-process-definition/{parentComponentCode}/{documentComponentCode}.md",
+  isDefault: true
+});
+```
+
+## Methodology 연결 사용 예시
+
+`artifact-standard`는 Stage/Activity를 소유하지 않는다. Stage 안에서 어떤 산출물을 만들지, 선행 산출물이 후행 산출물에 어떻게 handoff되는지는 `@soddong/agentic-domain-methodology`가 정의한다.
+
+예를 들어 비즈니스 프로세스 정의서가 본문과 부록들로 나뉘면 다음처럼 연결한다.
+
+| Methodology 요소 | Artifact Standard 참조 |
+| --- | --- |
+| 본문 작성 Activity output | `business_process_definition@1.0.0` + `main_document` |
+| L3 프로세스 부록 작성 Activity output | `business_process_definition@1.0.0` + `appendix_l3_process` |
+| 시나리오 부록 작성 Activity output | `business_process_definition@1.0.0` + `appendix_scenario` |
+| L4 상세 부록 작성 Activity output | `business_process_definition@1.0.0` + `appendix_l4_detail` |
+| 종합/정제 Activity input | 위 4개 component 산출물 |
+| 후행 정보 객체 정의 Stage handoff | 검토/승인된 비즈니스 프로세스 정의서 산출물 묶음 |
+
+작성 과정의 세부 절차는 Step으로 해석할 수 있지만, 현재 MVP에서는 Step 실행 모델까지 강제하지 않는다.
+
+## Validation Provider Manifest
+
+`artifact_standard_validation_rule_sets`에 저장된 rule set은 `@soddong/agentic-contract-validation`의 `ValidationProviderManifest`로 export할 수 있다.
+
+```ts
+const manifest = service.exportValidationProviderManifest(standard.artifactStandardId);
+console.log(manifest.profiles[0].rules);
+```
+
+`validationTypeCode`, `executionModeCode`, `severityCode`는 service 저장 시 `@soddong/agentic-contract-validation` code guard로 검증된다.
+
+## Fixture Helper
+
+```ts
+import { seedBusinessProcessDefinitionArtifactStandard } from "@soddong/agentic-domain-artifact-standard";
+
+const fixture = seedBusinessProcessDefinitionArtifactStandard(service);
+console.log(fixture.aggregate.standard.artifactStandardCode);
+```
+
+fixture helper는 사용성 테스트와 integration test를 위한 축소 샘플이며, 참조 데이터 최종 이행으로 간주하지 않는다.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@soddong/agentic-domain-artifact-standard",
+  "version": "0.11.0",
+  "description": "Agentic Platform artifact standard domain package",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    ".tbls.yml",
+    "docs",
+    "src/database/migrations"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.11.1",
+    "@soddong/agentic-contract-validation": "^0.2.0",
+    "@soddong/agentic-domain-document": "^0.7.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13"
+  }
+}