개념과 용어
이 문서의 결과: HandStack을 구성하는 네 가지 요소(ack, 모듈, 계약, 화면)의 역할을 구분한다.
한 줄 정의
HandStack은 HTML/JavaScript/SQL만으로 업무 앱을 만들고, 계약(Contract) 파일로 화면과 기능을 연결하는 오픈소스 솔루션입니다. 컴파일 과정 없이 텍스트 편집기만으로 개발합니다.
네 가지 요소
| 요소 | 역할 | 실제 형태 |
|---|---|---|
| ack | HandStack 서버 실행 프로그램. Windows/Linux/macOS에서 동일하게 동작 | app/ack 실행 파일, 기본 포트 8421 |
| 모듈 | ack 위에서 동작하는 기능 단위 (화면 호스팅, 거래 라우팅, SQL 실행, 함수 실행 등) | wwwroot, transact, dbclient, function, repository 등 |
| 계약(Contract) | 무엇을 주고받고 어떻게 실행할지 미리 정의한 파일 | .json(transact), .xml(dbclient), 소스 파일(function) |
| 화면 | 사용자가 보는 HTML/JS. 계약을 호출해 데이터를 주고받음 | wwwroot/{Application}/{Project}/*.html, *.js |
왜 "계약"이라고 부르는가
화면과 서버 기능이 직접 연결되면 한쪽이 바뀔 때 다른 쪽도 같이 고쳐야 합니다. HandStack은 그 사이에 미리 합의한 파일을 두어 화면 개발자와 서버 개발자가 각자 파일만 보고 협업할 수 있게 합니다.
[화면 HTML/JS] ---- 계약(.json, .xml) ---- [서버 모듈]
"무엇이 필요한지" "무엇을 주고받을지 약속" "어떻게 처리할지"
이 약속이 어긋나면(필드 이름이 다르거나 타입이 다르면) 통신은 성공해도 화면 에 데이터가 표시되지 않는 문제가 생깁니다. 이후 08. transact 거래 계약에서 이 문제를 자세히 다룹니다.
계약 파일 한눈에 보기
| 확장자/형태 | 담당 모듈 | 하는 일 |
|---|---|---|
.html, .js | wwwroot | 화면 레이아웃과 화면 업무 로직 |
.json (transact) | transact | 거래 요청 검증, 인증, 라우팅 |
.xml (dbclient) | dbclient | SQL 실행과 파라미터 매핑 |
| 함수 소스(.cs, .js 등) | function | 서버 함수(C#/Node.js) 실행 |
storage.json 등 | repository | 파일 업로드/다운로드 관리 |
전체 디렉토리 구조는 소스 디렉토리 구조에서 실제 예제로 확인할 수 있습니다.
핵심 용어
| 용어 | 뜻 | 헷갈리는 짝 |
|---|---|---|
| 거래(Transaction) | 화면 요청 한 건과 그 처리 전체 | 데이터베이스 트랜잭션과 이름은 같지만 다른 개념 |
| ApplicationID / ProjectID | 프로그램 약어 / 업무 약어 | 예: HDS / BOD |
| TransactionID | 화면 단위 거래 ID | 보통 화면 ID와 동일하게 맞춤 (예: BOD010) |
| FunctionID(ServiceID) | 거래 안의 기능 하나 | 목록 조회, 저장, 삭제 등 세부 동작 구분 |
자주 하는 오해
"HandStack이 프레임워크니까 특정 언어를 새로 배워야 하나요?" 아닙니다. 화면은 표준 HTML/JavaScript, 서버 로직은 SQL이나 익숙한 언어(C#, Node.js)로 작성합니다. HandStack이 새로 요구하는 것은 계약 파일의 구조뿐입니다.
"계약 파일만 있으면 코드를 안 짜도 되나요?" 아닙니다. 계약은 "무엇을 주고받을지"의 약속이고, 실제 SQL·함수·화면 로직은 개발자가 작성합니다.
이것만 기억하세요
- 화면·거래·SQL·함수는 각자 파일로 나뉘고, 계약이 이들을 연결한다.
- 계약이 정한 이름과 타입이 어긋나면 실행은 되어도 결과가 어긋난다.
- 모든 개발은 텍스트 편집기 +
ack실행만으로 가능하다.