# AIWK Wallet MVP ai_read.me

위치 목표:
- 실제 서버 배치: /var/www/html/aiwk/wallet/
- 공통 DB 연결: /var/www/html/aiwk/yy_db_conn.php
- wallet 내부 PHP 파일은 기본적으로 `require_once __DIR__ . '/../yy_db_conn.php';` 로 시작한다.
- 사용자가 메시지에서 `yy_db_connn.php`라고 적었지만, 첨부된 실제 파일명은 `yy_db_conn.php`이다. 오타로 판단하고 `yy_db_conn.php` 기준으로 작성했다.

핵심 방향:
- 외부 블록체인/코인 발행이 아니라, AIWK 사이트 내부에서만 쓰는 Credit/Point 장부 시스템으로 시작한다.
- 외부 표현: AIWK Credit, AIWK Point, 작업권, 이용권 권장.
- 비추천 표현: Coin, 투자, 시세, 환전, 수익률, 상장.
- MVP 목적: 사이트 내 구매/충전, 결제, 회원 간 이전, P2P 작업 에스크로, 쿠폰 확장 가능성을 위한 DB와 함수 뼈대.

설치 순서:
1. `/var/www/html/aiwk/wallet/` 폴더를 만든다.
2. 이 ZIP 안의 wallet 폴더 내용을 업로드한다.
3. `/var/www/html/aiwk/yy_db_conn.php`가 존재해야 한다.
4. 브라우저에서 `/aiwk/wallet/wallet_install.php?debug=1` 실행한다.
5. 설치 후 `aiwk_wallet_*` 테이블이 생성되는지 확인한다.
6. 운영 전에는 `wallet_install.php`를 삭제하거나 접근 제한한다.

중요 보안 메모:
- 모든 금액은 float 사용 금지. BIGINT 정수 unit으로 처리한다.
- 예: 1 Credit = 100 unit으로 정하면 10.25 Credit = 1025 unit.
- 이 MVP 기본값은 1 Credit = 1 unit처럼 단순 사용 가능하다.
- 잔액 직접 수정 금지. 모든 변화는 ledger에 남긴다.
- 관리자 보정도 UPDATE만 하지 말고 ADMIN_ADJUST ledger를 남긴다.
- 삭제가 아니라 반대 거래로 정정한다.

파일 설명:
- wallet_install.sql
  테이블 생성 SQL. 직접 phpMyAdmin/MySQL CLI에서 실행 가능.

- wallet_install.php
  설치 실행기. yy_db_conn.php를 include하고 SQL 파일을 읽어 순차 실행한다.

- wallet_config.php
  공통 설정. DB include, 테이블명 prefix, currency, bucket, helper 설정.

- i18n.php
  한국어/영어 문구 분리 시작 파일. `wallet_t('key')`로 사용한다.

- wallet_lib.php
  핵심 함수 모음. 외부 코드에서는 이 파일만 include해서 사용하면 된다.
  주요 함수:
  - wallet_db()
  - wallet_uuid_v4()
  - wallet_ensure_account($user_id)
  - wallet_get_balances($user_id)
  - wallet_get_available_balance($user_id)
  - wallet_credit_charge($user_id, $amount, $memo, $ref_type, $ref_id)
  - wallet_transfer($from_user_id, $to_user_id, $amount, $memo, $ref_type, $ref_id)
  - wallet_payment($from_user_id, $to_user_id, $amount, $fee_user_id, $fee_amount, $memo, $ref_type, $ref_id)
  - wallet_admin_adjust($user_id, $amount, $memo)
  - wallet_ledger_list($user_id, $limit)
  - wallet_lock($user_id, $amount, $memo, $ref_type, $ref_id)
  - wallet_unlock($user_id, $amount, $memo, $ref_type, $ref_id)
  - wallet_pay_from_locked($from_user_id, $to_user_id, $amount, $fee_user_id, $fee_amount, $memo, $ref_type, $ref_id)

- wallet_api.php
  간단 API 예시.
  GET  wallet_api.php?action=balance&user_id=1
  GET  wallet_api.php?action=ledger&user_id=1
  POST wallet_api.php?action=transfer  from_user_id, to_user_id, amount, memo
  실제 운영에서는 로그인 세션의 user_id를 사용해야 하며, 요청값 user_id를 그대로 믿으면 안 된다.

- wallet_demo.php
  개발 확인용 화면. 운영 전 삭제 또는 접근 제한.

- wallet_job_lib.php
  P2P 작업 에스크로 예시 함수.
  주요 흐름:
  1. wallet_job_create(): 요청자 작업 생성
  2. wallet_job_accept(): 작업자 수락 + 요청자 금액 locked로 이동
  3. wallet_job_submit(): 작업 제출
  4. wallet_job_complete(): locked 금액에서 작업자 지급 + 수수료 지급
  5. wallet_job_cancel(): locked 금액 해제

AIWK 다른 코드에서 wallet 이용하는 기본 예:

```php
require_once __DIR__ . '/wallet/wallet_lib.php';

// 1번 사용자에게 1000 Credit 충전
$tx_id = wallet_credit_charge(1, 1000, '관리자 테스트 충전', 'manual', 0);

// 1번이 2번에게 100 Credit 전송
$tx_id = wallet_transfer(1, 2, 100, '테스트 송금', 'test', 0);

// 1번 잔액 조회
$bal = wallet_get_balances(1);
print_r($bal);
```

P2P 작업 예:

```php
require_once __DIR__ . '/wallet/wallet_job_lib.php';

// 요청자 1번이 500 Credit 작업 생성
$job_id = wallet_job_create(1, '파일 정리 작업', '샘플 설명', 500, 50);

// 작업자 2번이 수락하면 요청자 1번의 550 Credit이 locked로 이동
wallet_job_accept($job_id, 2);

// 작업자 제출
wallet_job_submit($job_id, '완료 파일 전달');

// 요청자 승인: 작업자 2번에게 500, 플랫폼 수수료 계정에게 50 지급
wallet_job_complete($job_id, 999999);
```

향후 확장 계획:
1. 로그인 세션 연동
2. PG 결제 웹훅 연동
3. 보너스 크레딧/구매 크레딧 사용 우선순위 정책 구체화
4. 쿠폰 발급/사용 함수 추가
5. 관리자 페이지
6. WSS Hub 실시간 잔액 알림
7. 작업별 과금: mypc.py, EXT4, Node-RED, 파일전송, AI 리포트 생성
8. 법률 검토 후 선불전자지급수단/환불정책/약관 정리

주의:
- 회원 간 전송 기능은 내부 경제에는 좋지만, 현금성/환전성/외부 사용성이 붙으면 규제 위험이 커진다.
- MVP 단계에서는 환전 금지, 외부 전송 금지, 시세 금지, 투자 표현 금지를 기본 정책으로 둔다.


============================================================
2026-06-24 추가 메모: AIWK 공통 UI 레이어 / BS5.3 + Tailwind prefix
============================================================

이번 단계에서 wallet 자체 기능과 UI 공통 레이어를 분리하였다.

추가된 공통 파일:

/var/www/html/aiwk/aiwk_ui_config.php
/var/www/html/aiwk/aiwk_header.php
/var/www/html/aiwk/aiwk_footer.php
/var/www/html/aiwk/assets/aiwk/aiwk_common.css
/var/www/html/aiwk/assets/aiwk/aiwk_theme.js
/var/www/html/aiwk/sample/wallet_use_sample.php

핵심 방향:

1. Bootstrap 5.3을 기본 UI 뼈대로 사용한다.
   - container, row, col, card, table, form-control, btn, modal 등은 Bootstrap 기준.

2. Tailwind는 보조 커스터마이징용으로만 사용한다.
   - prefix는 반드시 tw- 로 고정한다.
   - 예: tw-rounded-2xl, tw-shadow-lg, tw-px-3
   - Bootstrap의 p-4, m-3, rounded, shadow 등과 충돌하지 않게 하기 위함.

3. 다크/화이트 모드는 Bootstrap 5.3의 data-bs-theme 기준으로 통일한다.
   - <html data-bs-theme="light">
   - <html data-bs-theme="dark">
   - aiwk_theme.js가 localStorage(aiwk_theme)에 저장하고 복원한다.

4. 템플릿과 테마 모드는 분리한다.
   - template: bs53, future_tailwind 등 화면 구조/컴포넌트 단위
   - theme: light, dark 등 색상 모드

5. 운영 빌드 권장사항:
   - 현재 Tailwind는 MVP 편의를 위해 CDN을 사용한다.
   - 운영에서는 tailwind.config.js prefix: 'tw-' 로 빌드한 aiwk.tw.css 파일을 사용하는 방향이 더 안전하다.

공통 header 사용법:

$AIWK_PAGE = array(
    'title' => '페이지 제목',
    'active_menu' => 'wallet',
    'fluid' => false,
    'use_tailwind' => true
);
require_once dirname(__FILE__) . '/../aiwk_header.php';

// 본문 HTML

require_once dirname(__FILE__) . '/../aiwk_footer.php';

다른 폴더에서 wallet 기능 사용 예:

require_once dirname(__FILE__) . '/../wallet/wallet_lib.php';
$balances = wallet_get_balances(1);
$ledger = wallet_ledger_list(1, 10);

샘플 페이지:

/aiwk/sample/wallet_use_sample.php?user_id=1

중요:
wallet_demo.php는 이제 공통 header/footer를 사용하는 BS5.3 화면으로 바뀌었다.
그러나 여전히 실제 장부를 변경하는 개발용 화면이다.
운영 전에는 삭제하거나 관리자만 접근 가능하게 제한해야 한다.
