주문 번호 ${esc(o.order_no)} · ${esc(ctx.group.name)} · 발행 ${esc(o.created_at.slice(0, 10))}${o.approved_at ? ` · 승인 ${esc(o.approved_at.slice(0, 10))}` : ''}
' 에 있다. 허용 키 id 는 'hal' 뿐이다.
+ * 호출 주체 운영자 식별(감사 기록용)은 HAL 이 X-Ops-Actor 헤더로 전달한다(이름만, 비밀 없음).
+ * 테스트에서는 deps.opsAuthBypass=true 로 서명 없이 부를 수 있다(운영 코드 경로에서는 절대 켜지 않는다).
+ */
+import { HttpError } from '../../lib/http.mjs';
+import { verifyCtx } from '../../lib/serviceauth.mjs';
+
+const ALLOWED_KEYS = new Set(['hal']);
+/** 검증 후 { keyId, actor } 를 돌려준다. 실패는 401. */
+export async function requireOps(ctx, deps) {
+ const actor = String(ctx.headers['x-ops-actor'] || 'operator').slice(0, 80);
+ if (deps.opsAuthBypass) return { keyId: 'test', actor };
+ const r = await verifyCtx(ctx, (id) => (ALLOWED_KEYS.has(id) ? deps.vault.get('service:' + id) : null));
+ if (!r.ok) throw new HttpError(401, 'service_auth_failed', `운영자 콘솔 호출 인증 실패(${r.reason})`);
+ return { keyId: r.keyId, actor };
+}
diff --git a/portal/commerce/orders.mjs b/portal/commerce/orders.mjs
new file mode 100644
index 0000000..3c047e7
--- /dev/null
+++ b/portal/commerce/orders.mjs
@@ -0,0 +1,237 @@
+/**
+ * portal/commerce/orders.mjs — 주문·수동 결제 확인·승인·권리 활성화·구독·갱신·축소·해지·환불/크레딧·초과 사용(§6.2~6.5, §27.1, §35).
+ *
+ * 흐름(0.1.1 기본 = 수동 결제 확인)
+ * 1) 고객이 상품(+옵션)·적용 대상·결제 방식(manual_transfer 만)·약관 동의를 보내면 주문(awaiting_payment)이 생긴다. 주문 번호·금액·통화·세금·입금 기한·입금 안내를 보인다.
+ * 2) 운영자가 실제 입금을 확인(markPaid)하고 승인(approve)하거나 거절(reject)한다. 승인 때만 권리(lib/quota entitlement)가 생긴다.
+ * 3) 같은 승인을 두 번 눌러도 권리가 중복 생기지 않는다: 승인 트랜잭션 안에서 status 를 검사하고 부여한 권리 id 를 orders.entitlement_ids_json 에 남긴다.
+ * 4) 기한이 지나면 expired. 거절·만료 사유와 재주문·문의 안내를 화면에 보인다.
+ * 멱등: 고객이 보낸 idempotency_key 가 같으면 기존 주문을 돌려준다(새로 고침·연타 §36).
+ * 구독(subscriptions): 기본 상품 주문이 승인되면 활성 구독이 되고 next_billing_at 이 정해진다. 갱신은 renewal_notice_days 전에 갱신 주문(kind='renewal')을 만들어 알리고,
+ * 입금 확인 전까지 'awaiting_renewal_payment' 로 보인다. 미납 제한 예정 시각(restrict_at)은 정책의 restriction_after_unpaid_days 로 계산해 고객·운영자에게 똑같이 보인다. 데이터는 지우지 않는다.
+ * 축소(§6.4): 새 상품 한도 안에 현재 사용량·배정이 들어오면 즉시 축소 주문(kind='downsize', 0원이면 바로 승인 대기)이, 아니면 downsize_holds 에 보류되고 줄여야 할 항목을 구체적으로 보인다.
+ * 해지: cancel_at(=다음 청구일)에 권리를 종료한다. 사용 중 권리를 경고 없이 즉시 회수하지 않는다.
+ */
+import { newId } from '../../lib/crypto.mjs';
+import { nowIso, toJson, parseJson } from '../../lib/db.mjs';
+import { HttpError } from '../../lib/http.mjs';
+import * as quota from '../../lib/quota.mjs';
+import { notify } from '../../lib/notify.mjs';
+import { audit } from '../../lib/audit.mjs';
+import { getProductVersion, getSetting, publicProduct, rowToProduct } from './catalog.mjs';
+
+export const ORDER_STATUS = { AWAITING_PAYMENT: 'awaiting_payment', AWAITING_APPROVAL: 'awaiting_approval', APPROVED: 'approved', REJECTED: 'rejected', EXPIRED: 'expired', CANCELLED: 'cancelled' };
+export const ORDER_LABEL = { awaiting_payment: '결제 대기', awaiting_approval: '승인 대기', approved: '승인 완료', rejected: '거절됨', expired: '기한 만료', cancelled: '취소됨' };
+export const SUB_LABEL = { active: '사용 중', awaiting_renewal_payment: '갱신 결제 대기', restricted: '미납 제한', cancel_scheduled: '해지 예약', cancelled: '해지됨', downsize_scheduled: '축소 예약' };
+const DAY = 86400000;
+
+export const rowToOrder = (r) => (r ? { ...r, items: parseJson(r.items_json, []), payment_instructions: parseJson(r.payment_instructions_json, null), entitlement_ids: parseJson(r.entitlement_ids_json, []), terms: parseJson(r.terms_json, null) } : null);
+export const rowToSub = (r) => (r ? { ...r, items: parseJson(r.items_json, []), entitlement_ids: parseJson(r.entitlement_ids_json, []) } : null);
+/** 주문 번호 AW-YYYYMMDD-NNNN (그날 순번) */
+function orderNo(store) { const d = new Date().toISOString().slice(0, 10).replace(/-/g, ''); const n = store.get("SELECT COUNT(*) AS n FROM orders WHERE order_no LIKE ?", `AW-${d}-%`).n + 1; return `AW-${d}-${String(n).padStart(4, '0')}`; }
+
+/**
+ * 주문 항목 계산. input.items = [{ optionId?, qty, targetType?, targetId? }] + 기본 상품 포함 여부(includeBase).
+ * 각 항목에 단가·세금·합계·부여 자원(grants)을 붙인다. 옵션 수량 상한(max_qty)·per(site 면 대상 필요)을 검사한다.
+ */
+export function priceItems(pv, { includeBase = true, items = [] } = {}) {
+ const out = []; const addTax = (amt) => Math.round(amt * pv.tax_rate);
+ if (includeBase) out.push({ type: 'product', id: pv.product_id, name: pv.name, qty: 1, unit_price: pv.price, amount: pv.price, tax: addTax(pv.price), target_type: 'group', target_id: null, grants: pv.limits });
+ for (const it of items) {
+ const o = pv.options.find((x) => x.id === it.optionId); if (!o) throw new HttpError(400, 'bad_option', `알 수 없는 옵션: ${it.optionId}`);
+ const qty = Math.max(1, Math.min(Number(it.qty) || 1, o.max_qty || 99));
+ if (o.per === 'site' && !it.targetId) throw new HttpError(400, 'target_required', `${o.name} 은(는) 적용할 사이트를 골라야 합니다`);
+ const amount = o.price * qty; const grants = Object.fromEntries(Object.entries(o.grants || {}).map(([k, v]) => [k, v * qty]));
+ out.push({ type: 'option', id: o.id, name: o.name, qty, unit_price: o.price, amount, tax: addTax(amount), target_type: o.per === 'site' ? 'site' : 'group', target_id: it.targetId || null, grants, policy: o.policy || null });
+ }
+ const amount = out.reduce((s, x) => s + x.amount, 0); const tax = out.reduce((s, x) => s + x.tax, 0);
+ return { items: out, amount, tax, total: amount + tax, currency: pv.currency };
+}
+/** 입금 안내(settings.payment_instructions, 운영자 관리). 비밀값 없음. */
+export function paymentInstructions(store) { return getSetting(store, 'payment_instructions', { method: 'manual_transfer', bank: '', account: '', holder: '', note: '', deadline_days: 7 }); }
+
+/**
+ * 주문 만들기. 이메일 미확인 사용자는 유료 상품을 살 수 없다(§3.1). idempotencyKey 가 같으면 기존 주문.
+ * @returns {{order, created}}
+ */
+export function createOrder(store, { groupId, userId, userVerified, productVersionId, includeBase = true, items = [], paymentMethod = 'manual_transfer', acceptTerms, idempotencyKey = null, kind = 'new', subscriptionId = null }) {
+ const pv = getProductVersion(store, productVersionId); if (!pv || !pv.published) throw new HttpError(404, 'product_not_found', '판매 중인 상품이 아닙니다');
+ if (paymentMethod !== 'manual_transfer') throw new HttpError(400, 'payment_method_unsupported', '버전 0.1.1 은 수동 결제 확인(계좌 이체)만 지원합니다');
+ if (!acceptTerms) throw new HttpError(400, 'terms_required', '약관과 제한 사항에 동의해야 주문할 수 있습니다');
+ const priced = priceItems(pv, { includeBase, items });
+ if (priced.total > 0 && !userVerified) throw new HttpError(403, 'email_unverified', '이메일 확인이 끝나야 유료 상품을 주문할 수 있습니다', { action: 'verify_email' });
+ if (!priced.items.length) throw new HttpError(400, 'empty_order', '주문 항목이 없습니다');
+ return store.tx(() => {
+ if (idempotencyKey) { const ex = store.get('SELECT * FROM orders WHERE idempotency_key=?', idempotencyKey); if (ex) return { order: rowToOrder(ex), created: false }; }
+ // 같은 그룹에 결제 대기 중인 같은 상품 주문이 있으면 그것을 돌려준다(새로 고침 뒤 다른 키로 다시 눌러도 중복 생성 안 함)
+ if (kind === 'new' && includeBase) { const dup = store.get('SELECT * FROM orders WHERE group_id=? AND product_version_id=? AND kind=? AND status IN (?,?)', groupId, pv.id, 'new', 'awaiting_payment', 'awaiting_approval'); if (dup) return { order: rowToOrder(dup), created: false }; }
+ const pi = paymentInstructions(store); const now = nowIso(); const dueDays = Number(pv.policy?.payment_deadline_days || pi.deadline_days || 7);
+ const id = newId('o_');
+ store.run('INSERT INTO orders(id, group_id, order_no, kind, product_version_id, items_json, target_type, target_id, amount, tax, total, currency, status, payment_method, payment_instructions_json, due_at, idempotency_key, created_by, created_at, updated_at, terms_json, subscription_id) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)',
+ id, groupId, orderNo(store), kind, pv.id, toJson(priced.items), 'group', groupId, priced.amount, priced.tax, priced.total, priced.currency, priced.total === 0 ? ORDER_STATUS.AWAITING_APPROVAL : ORDER_STATUS.AWAITING_PAYMENT, paymentMethod, toJson(pi), new Date(Date.now() + dueDays * DAY).toISOString(), idempotencyKey, userId, now, now, toJson({ acceptedAt: now, productVersion: pv.id, terms: 'v0.1.1' }), subscriptionId);
+ const order = rowToOrder(store.get('SELECT * FROM orders WHERE id=?', id));
+ audit(store, { actorType: 'user', actorId: userId, groupId, subjectType: 'order', subjectId: id, action: 'order.create', detail: { orderNo: order.order_no, total: order.total, kind } });
+ notify(store, { groupId, category: 'billing', severity: 'info', title: `주문 ${order.order_no} 접수 — ${order.status === 'awaiting_payment' ? '입금 확인 대기' : '승인 대기'}`, body: `금액 ${order.total.toLocaleString('ko-KR')} ${order.currency}(세금 포함) · 기한 ${order.due_at.slice(0, 10)}`, link: `/orders/${id}`, subjectType: 'order', subjectId: id, incidentKey: `order:${id}:status` });
+ return { order, created: true };
+ });
+}
+export function getOrder(store, id, groupId = null) { const r = store.get(`SELECT * FROM orders WHERE id=? ${groupId ? 'AND group_id=?' : ''}`, ...(groupId ? [id, groupId] : [id])); return rowToOrder(r); }
+export function listOrders(store, { groupId, status, limit = 100 } = {}) { const w = []; const p = []; if (groupId) { w.push('group_id=?'); p.push(groupId); } if (status) { w.push(Array.isArray(status) ? `status IN (${status.map(() => '?').join(',')})` : 'status=?'); p.push(...[].concat(status)); } return store.all(`SELECT * FROM orders ${w.length ? 'WHERE ' + w.join(' AND ') : ''} ORDER BY created_at DESC LIMIT ?`, ...p, limit).map(rowToOrder); }
+/** 고객 취소: 결제·승인 전에만 */
+export function cancelOrder(store, id, groupId, userId) { const o = getOrder(store, id, groupId); if (!o) throw new HttpError(404, 'not_found', '주문이 없습니다'); if (!['awaiting_payment', 'awaiting_approval'].includes(o.status)) throw new HttpError(409, 'order_not_cancellable', `${ORDER_LABEL[o.status]} 상태의 주문은 취소할 수 없습니다`); store.run('UPDATE orders SET status=?, cancelled_at=?, updated_at=? WHERE id=?', 'cancelled', nowIso(), nowIso(), id); audit(store, { actorType: 'user', actorId: userId, groupId, subjectType: 'order', subjectId: id, action: 'order.cancel' }); return getOrder(store, id); }
+/** 운영자: 입금 확인(승인 전 단계). 입금 참조(입금자명·일시)는 비밀 아님. */
+export function markPaid(store, id, { by, ref = '' }) { const o = getOrder(store, id); if (!o) throw new HttpError(404, 'not_found', '주문이 없습니다'); if (o.status !== 'awaiting_payment') throw new HttpError(409, 'order_not_awaiting_payment', `${ORDER_LABEL[o.status]} 상태에서는 입금 확인을 할 수 없습니다`); store.run('UPDATE orders SET status=?, paid_at=?, paid_ref=?, updated_at=? WHERE id=?', 'awaiting_approval', nowIso(), String(ref).slice(0, 120), nowIso(), id); audit(store, { actorType: 'operator', actorId: by, groupId: o.group_id, subjectType: 'order', subjectId: id, action: 'payment.confirm', detail: { ref } }); notify(store, { groupId: o.group_id, category: 'billing', severity: 'info', title: `주문 ${o.order_no} 입금 확인 — 승인 대기`, link: `/orders/${id}`, subjectType: 'order', subjectId: id, incidentKey: `order:${id}:status` }); return getOrder(store, id); }
+
+/**
+ * 운영자 승인 → 권리 활성화(§35). 멱등: 이미 approved 면 그대로 돌려준다(권리 재부여 없음).
+ * 기본 상품 주문이면 구독을 만들고(또는 갱신/축소 주문이면 구독을 갱신하고) 다음 청구일을 정한다.
+ */
+export function approveOrder(store, id, { by }) {
+ return store.tx(() => {
+ const o = getOrder(store, id); if (!o) throw new HttpError(404, 'not_found', '주문이 없습니다');
+ if (o.status === 'approved') return { order: o, granted: [], already: true };
+ if (!['awaiting_approval', 'awaiting_payment'].includes(o.status)) throw new HttpError(409, 'order_not_approvable', `${ORDER_LABEL[o.status]} 상태의 주문은 승인할 수 없습니다`);
+ if (o.status === 'awaiting_payment' && o.total > 0) throw new HttpError(409, 'payment_not_confirmed', '입금 확인을 먼저 기록하세요');
+ const pv = getProductVersion(store, o.product_version_id); const now = nowIso();
+ let sub = o.subscription_id ? rowToSub(store.get('SELECT * FROM subscriptions WHERE id=?', o.subscription_id)) : null;
+ const granted = [];
+ if (o.kind === 'renewal' && sub) {
+ // 갱신: 권리는 그대로, 다음 청구일만 한 주기 뒤로
+ store.run('UPDATE subscriptions SET status=?, next_billing_at=?, renewal_order_id=NULL, renewal_notified_at=NULL, payment_due_at=NULL, restrict_at=NULL, updated_at=? WHERE id=?', 'active', addCycle(sub.next_billing_at || now, sub.billing_cycle), now, sub.id);
+ } else if (o.kind === 'downsize' && sub) {
+ // 축소: 옛 권리를 끝내고 새 상품 한도로 다시 부여(승인 시점에 다시 검증 — 그 사이 사용량이 늘었으면 거절)
+ const check = evaluateDownsize(store, o.group_id, pv, o.items);
+ if (check.shortages.length) throw new HttpError(409, 'downsize_blocked', '승인 시점 재검증에서 새 한도를 넘는 사용량이 있습니다', { shortages: check.shortages });
+ for (const eid of sub.entitlement_ids) quota.endEntitlement(store, eid, now);
+ for (const it of o.items) for (const [res, amt] of Object.entries(it.grants || {})) if (amt > 0) granted.push(quota.grantEntitlement(store, { groupId: o.group_id, resource: res, amount: amt, sourceId: o.id, productVersionId: pv.id, note: it.name }));
+ store.run('UPDATE subscriptions SET product_version_id=?, items_json=?, amount=?, tax=?, total=?, entitlement_ids_json=?, status=?, updated_at=? WHERE id=?', pv.id, toJson(o.items), o.amount, o.tax, o.total, toJson(granted), 'active', now, sub.id);
+ store.run("UPDATE downsize_holds SET status='applied', order_id=?, updated_at=? WHERE group_id=? AND status='ordered' AND order_id=?", o.id, now, o.group_id, o.id);
+ } else {
+ for (const it of o.items) for (const [res, amt] of Object.entries(it.grants || {})) if (amt > 0) granted.push(quota.grantEntitlement(store, { groupId: o.group_id, resource: res, amount: amt, sourceId: o.id, productVersionId: pv.id, note: it.target_type === 'site' && it.target_id ? `${it.name} (사이트 ${it.target_id})` : it.name }));
+ if (o.items.some((i) => i.type === 'product')) {
+ const sid = newId('sub_');
+ store.run('INSERT INTO subscriptions(id, group_id, product_version_id, order_id, items_json, billing_cycle, amount, tax, total, currency, status, started_at, next_billing_at, entitlement_ids_json, created_at, updated_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)', sid, o.group_id, pv.id, o.id, toJson(o.items), pv.billing_cycle, o.amount, o.tax, o.total, o.currency, 'active', now, addCycle(now, pv.billing_cycle), toJson(granted), now, now);
+ store.run('UPDATE orders SET subscription_id=? WHERE id=?', sid, o.id); sub = rowToSub(store.get('SELECT * FROM subscriptions WHERE id=?', sid));
+ } else if (sub) {
+ // 기존 구독의 추가 옵션: 구독 권리 목록에 합치고 금액을 더한다(다음 청구에 반영)
+ store.run('UPDATE subscriptions SET items_json=?, amount=amount+?, tax=tax+?, total=total+?, entitlement_ids_json=?, updated_at=? WHERE id=?', toJson([...sub.items, ...o.items]), o.amount, o.tax, o.total, toJson([...sub.entitlement_ids, ...granted]), now, sub.id);
+ }
+ }
+ store.run('UPDATE orders SET status=?, approved_at=?, approved_by=?, entitlement_ids_json=?, updated_at=? WHERE id=?', 'approved', now, by, toJson(granted), now, id);
+ audit(store, { actorType: 'operator', actorId: by, groupId: o.group_id, subjectType: 'order', subjectId: id, action: 'order.approve', detail: { orderNo: o.order_no, granted: granted.length, kind: o.kind } });
+ notify(store, { groupId: o.group_id, category: 'billing', severity: 'info', mandatory: true, title: `주문 ${o.order_no} 승인 — 권리가 활성화되었습니다`, body: o.items.map((i) => `${i.name}×${i.qty}`).join(', '), link: `/orders/${id}`, subjectType: 'order', subjectId: id, incidentKey: `order:${id}:status` });
+ return { order: getOrder(store, id), granted, already: false };
+ });
+}
+export function rejectOrder(store, id, { by, reason }) { const o = getOrder(store, id); if (!o) throw new HttpError(404, 'not_found', '주문이 없습니다'); if (!['awaiting_payment', 'awaiting_approval'].includes(o.status)) throw new HttpError(409, 'order_not_rejectable', `${ORDER_LABEL[o.status]} 상태의 주문은 거절할 수 없습니다`); if (!reason) throw new HttpError(400, 'reason_required', '거절 사유를 적으세요'); store.run('UPDATE orders SET status=?, rejected_at=?, rejected_reason=?, updated_at=? WHERE id=?', 'rejected', nowIso(), String(reason).slice(0, 500), nowIso(), id); audit(store, { actorType: 'operator', actorId: by, groupId: o.group_id, subjectType: 'order', subjectId: id, action: 'order.reject', detail: { reason } }); notify(store, { groupId: o.group_id, category: 'billing', severity: 'warning', mandatory: true, title: `주문 ${o.order_no} 거절`, body: `사유: ${reason}. 다시 주문하거나 문의하세요`, link: `/orders/${id}`, subjectType: 'order', subjectId: id, incidentKey: `order:${id}:status` }); return getOrder(store, id); }
+/** 기한 만료 처리(주기 작업). 만료된 주문 목록 반환 */
+export function expireOrders(store, at = nowIso()) {
+ const rows = store.all("SELECT * FROM orders WHERE status='awaiting_payment' AND due_at IS NOT NULL AND due_at= billing - noticeDays * DAY && s.status === 'active' && !s.cancel_at) {
+ const id = newId('o_'); const pi = paymentInstructions(store); const due = new Date(billing + deadlineDays * DAY).toISOString(); const restrictAt = new Date(billing + restrictDays * DAY).toISOString();
+ store.run('INSERT INTO orders(id, group_id, order_no, kind, product_version_id, items_json, target_type, target_id, amount, tax, total, currency, status, payment_method, payment_instructions_json, due_at, created_by, created_at, updated_at, subscription_id) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)', id, s.group_id, orderNo(store), 'renewal', pv.id, s.items_json, 'group', s.group_id, s.amount, s.tax, s.total, s.currency, 'awaiting_payment', 'manual_transfer', toJson(pi), due, 'system', at, at, s.id);
+ store.run('UPDATE subscriptions SET renewal_order_id=?, renewal_notified_at=?, payment_due_at=?, restrict_at=?, status=?, updated_at=? WHERE id=?', id, at, due, restrictAt, 'awaiting_renewal_payment', at, s.id);
+ notify(store, { groupId: s.group_id, category: 'billing', severity: 'warning', mandatory: true, title: `갱신 결제 안내 — ${s.next_billing_at.slice(0, 10)} 청구 예정 ${s.total.toLocaleString('ko-KR')} ${s.currency}`, body: `입금 기한 ${due.slice(0, 10)} · 미납 시 ${restrictAt.slice(0, 10)} 부터 신규 배포·설정 변경이 제한됩니다(데이터는 삭제하지 않습니다)`, link: `/orders/${id}`, subjectType: 'subscription', subjectId: s.id, incidentKey: `sub:${s.id}:renewal` });
+ created.push(s.id);
+ } else if (s.status === 'awaiting_renewal_payment' && s.restrict_at && now >= Date.parse(s.restrict_at)) {
+ store.run('UPDATE subscriptions SET status=?, updated_at=? WHERE id=?', 'restricted', at, s.id); restricted.push(s.id);
+ notify(store, { groupId: s.group_id, category: 'billing', severity: 'critical', mandatory: true, title: '미납으로 신규 변경이 제한되었습니다', body: `${pv.policy?.restriction_effect || '신규 배포·설정 변경 제한'}. 입금이 확인되면 즉시 해제됩니다`, link: `/orders/${s.renewal_order_id}`, subjectType: 'subscription', subjectId: s.id, incidentKey: `sub:${s.id}:restricted` });
+ }
+ }
+ // 해지 예약 도래: 권리 종료
+ for (const s of store.all("SELECT * FROM subscriptions WHERE status='cancel_scheduled' AND cancel_at<=?", at).map(rowToSub)) { for (const eid of s.entitlement_ids) quota.endEntitlement(store, eid, at); store.run('UPDATE subscriptions SET status=?, cancelled_at=?, updated_at=? WHERE id=?', 'cancelled', at, at, s.id); notify(store, { groupId: s.group_id, category: 'billing', severity: 'warning', mandatory: true, title: '상품 해지가 적용되었습니다', body: '권리가 종료되었습니다. 데이터는 보존 기간 동안 조회·내보내기가 가능합니다', link: '/billing', subjectType: 'subscription', subjectId: s.id }); audit(store, { actorType: 'system', automatic: true, groupId: s.group_id, subjectType: 'subscription', subjectId: s.id, action: 'cancel.apply' }); }
+ return { created, restricted };
+}
+
+/**
+ * 축소 가능성 평가(§6.4). 새 상품 한도(+옵션 grants) 와 현재 배정·예약·실제 사용을 자원별로 비교한다.
+ * shortages: [{ resource, label, newLimit, inUse(배정+예약), used(계측), reduceBy, items:[{subjectType, subjectId, amount}] }]
+ */
+export function evaluateDownsize(store, groupId, pv, items = []) {
+ const newLimits = { ...pv.limits }; for (const it of items) if (it.type === 'option') for (const [r, a] of Object.entries(it.grants || {})) newLimits[r] = (newLimits[r] || 0) + a;
+ const shortages = []; const resources = [];
+ for (const r of Object.keys(quota.RESOURCES)) {
+ const f = quota.figures(store, groupId, r); const limit = newLimits[r] || 0; const inUse = f.allocated + f.reserved; const need = Math.max(inUse, f.used);
+ resources.push({ resource: r, label: f.label, unit: f.unit, current: f.purchased, newLimit: limit, allocated: f.allocated, reserved: f.reserved, used: f.used });
+ if (need > limit) shortages.push({ resource: r, label: f.label, unit: f.unit, newLimit: limit, inUse, used: f.used, reduceBy: need - limit, items: quota.listAllocations(store, groupId, r).map((a) => ({ subjectType: a.subject_type, subjectId: a.subject_id, amount: a.amount, used: a.used || 0 })) });
+ }
+ return { newLimits, resources, shortages };
+}
+/**
+ * 축소 요청: 범위 안이면 축소 주문(승인 대기; 차액은 0 — 차기 청구부터 새 금액)을 만들고, 아니면 보류(hold)를 만든다.
+ * @returns {{ fits:boolean, order?, hold?, shortages }}
+ */
+export function requestDownsize(store, { groupId, userId, userVerified, productVersionId, items = [], acceptTerms }) {
+ const sub = activeSubscription(store, groupId); if (!sub) throw new HttpError(409, 'no_subscription', '활성 상품이 없습니다');
+ const pv = getProductVersion(store, productVersionId); if (!pv || !pv.published) throw new HttpError(404, 'product_not_found', '판매 중인 상품이 아닙니다');
+ const priced = priceItems(pv, { includeBase: true, items }); const ev = evaluateDownsize(store, groupId, pv, priced.items);
+ const now = nowIso();
+ if (ev.shortages.length) {
+ const open = store.get("SELECT * FROM downsize_holds WHERE group_id=? AND status='holding'", groupId);
+ const id = open ? open.id : newId('dh_');
+ if (open) store.run('UPDATE downsize_holds SET target_product_version_id=?, items_json=?, shortages_json=?, last_checked_at=?, updated_at=? WHERE id=?', pv.id, toJson(priced.items), toJson(ev.shortages), now, now, id);
+ else store.run('INSERT INTO downsize_holds(id, group_id, subscription_id, target_product_version_id, items_json, status, shortages_json, last_checked_at, created_by, created_at, updated_at) VALUES(?,?,?,?,?,?,?,?,?,?,?)', id, groupId, sub.id, pv.id, toJson(priced.items), 'holding', toJson(ev.shortages), now, userId, now, now);
+ notify(store, { groupId, category: 'billing', severity: 'warning', title: '상품 축소 보류 — 정리가 필요한 항목이 있습니다', body: ev.shortages.map((s) => `${s.label} ${s.reduceBy} 줄이기`).join(', '), link: '/billing#downsize', subjectType: 'downsize_hold', subjectId: id, incidentKey: `downsize:${groupId}` });
+ return { fits: false, hold: rowToHold(store.get('SELECT * FROM downsize_holds WHERE id=?', id)), shortages: ev.shortages };
+ }
+ const { order } = createOrder(store, { groupId, userId, userVerified, productVersionId, items, acceptTerms, kind: 'downsize', subscriptionId: sub.id, idempotencyKey: `downsize:${groupId}:${pv.id}:${sub.id}` });
+ store.run("UPDATE downsize_holds SET status='ordered', order_id=?, updated_at=? WHERE group_id=? AND status='holding'", order.id, now, groupId);
+ return { fits: true, order, shortages: [] };
+}
+export const rowToHold = (r) => (r ? { ...r, items: parseJson(r.items_json, []), shortages: parseJson(r.shortages_json, []) } : null);
+export function openHold(store, groupId) { return rowToHold(store.get("SELECT * FROM downsize_holds WHERE group_id=? AND status='holding'", groupId)); }
+/** 보류 재검증: 정리가 끝났으면 축소 주문으로 전환 */
+export function revalidateHold(store, { groupId, userId, userVerified }) { const h = openHold(store, groupId); if (!h) throw new HttpError(404, 'no_hold', '보류 중인 축소 요청이 없습니다'); return requestDownsize(store, { groupId, userId, userVerified, productVersionId: h.target_product_version_id, items: h.items.filter((i) => i.type === 'option').map((i) => ({ optionId: i.id, qty: i.qty, targetId: i.target_id })), acceptTerms: true }); }
+export function cancelHold(store, groupId) { return store.run("UPDATE downsize_holds SET status='cancelled', updated_at=? WHERE group_id=? AND status='holding'", nowIso(), groupId).changes; }
+/** 해지 예약/철회(§6.4·§23). 다음 청구일에 권리 종료. */
+export function scheduleCancel(store, { groupId, userId }) { const s = activeSubscription(store, groupId); if (!s) throw new HttpError(409, 'no_subscription', '활성 상품이 없습니다'); if (s.status === 'cancel_scheduled') return s; const at = s.next_billing_at || nowIso(); store.run('UPDATE subscriptions SET status=?, cancel_at=?, cancel_requested_at=?, updated_at=? WHERE id=?', 'cancel_scheduled', at, nowIso(), nowIso(), s.id); audit(store, { actorType: 'user', actorId: userId, groupId, subjectType: 'subscription', subjectId: s.id, action: 'cancel.schedule', detail: { cancelAt: at } }); notify(store, { groupId, category: 'billing', severity: 'warning', mandatory: true, title: `상품 해지 예약 — ${at.slice(0, 10)} 적용`, body: '적용일까지 서비스와 권리는 유지됩니다. 적용 후 데이터는 보존 기간 동안 읽기·내보내기만 가능합니다', link: '/billing', subjectType: 'subscription', subjectId: s.id, incidentKey: `sub:${s.id}:cancel` }); return activeSubscription(store, groupId); }
+export function undoCancel(store, { groupId, userId }) { const s = activeSubscription(store, groupId); if (!s || s.status !== 'cancel_scheduled') throw new HttpError(409, 'not_scheduled', '해지 예약이 없습니다'); store.run('UPDATE subscriptions SET status=?, cancel_at=NULL, cancel_requested_at=NULL, updated_at=? WHERE id=?', 'active', nowIso(), s.id); audit(store, { actorType: 'user', actorId: userId, groupId, subjectType: 'subscription', subjectId: s.id, action: 'cancel.undo' }); return activeSubscription(store, groupId); }
+/** 운영자: 수동 결제 실패/재처리 등 메모 */
+export function noteOrder(store, id, { by, note }) { store.run('UPDATE orders SET note=?, updated_at=? WHERE id=?', String(note || '').slice(0, 1000), nowIso(), id); audit(store, { actorType: 'operator', actorId: by, subjectType: 'order', subjectId: id, action: 'order.note', detail: { note } }); return getOrder(store, id); }
+
+/** 초과 사용 허용(§6.5): 항목별 최대 금액 또는 최대 사용량·기간 필수. 철회하면 그 즉시 100% 제한이 다시 적용된다. */
+export function optInOverage(store, { groupId, userId, resource, capAmount = null, capUnits = null, periodStart, periodEnd }) {
+ if (!quota.RESOURCES[resource]) throw new HttpError(400, 'unknown_resource', '알 수 없는 자원'); if (!(capAmount > 0) && !(capUnits > 0)) throw new HttpError(400, 'cap_required', '최대 금액 또는 최대 사용량을 정해야 합니다'); if (!periodStart || !periodEnd || Date.parse(periodEnd) <= Date.parse(periodStart)) throw new HttpError(400, 'period_required', '적용 기간을 정해야 합니다');
+ const pv = appliedProduct(store, groupId); const unit = pv?.policy?.overage?.unit_prices?.[resource] || null; if (!unit) throw new HttpError(409, 'overage_not_offered', '이 자원은 초과 사용 상품이 없습니다');
+ store.run('UPDATE overage_optins SET revoked_at=?, revoked_by=? WHERE group_id=? AND resource=? AND revoked_at IS NULL', nowIso(), userId, groupId, resource);
+ const id = newId('ov_'); store.run('INSERT INTO overage_optins(id, group_id, resource, cap_amount, cap_units, unit_price_json, period_start, period_end, created_by, created_at) VALUES(?,?,?,?,?,?,?,?,?,?)', id, groupId, resource, capAmount, capUnits, toJson(unit), periodStart, periodEnd, userId, nowIso());
+ audit(store, { actorType: 'user', actorId: userId, groupId, subjectType: 'overage', subjectId: id, action: 'overage.optin', detail: { resource, capAmount, capUnits, periodStart, periodEnd } });
+ return store.get('SELECT * FROM overage_optins WHERE id=?', id);
+}
+export function revokeOverage(store, { groupId, userId, resource }) { const n = store.run('UPDATE overage_optins SET revoked_at=?, revoked_by=? WHERE group_id=? AND resource=? AND revoked_at IS NULL', nowIso(), userId, groupId, resource).changes; if (n) audit(store, { actorType: 'user', actorId: userId, groupId, subjectType: 'overage', subjectId: resource, action: 'overage.revoke' }); return n; }
+export function activeOverage(store, groupId, resource, at = nowIso()) { return store.get('SELECT * FROM overage_optins WHERE group_id=? AND resource=? AND revoked_at IS NULL AND period_start<=? AND period_end>? ORDER BY created_at DESC LIMIT 1', groupId, resource, at, at) || null; }
+export function listOverage(store, groupId) { return store.all('SELECT * FROM overage_optins WHERE group_id=? ORDER BY created_at DESC', groupId); }
+/** 도메인 등록 기능 제공 여부(settings.domain_registration, 운영자가 등록기관 연결 후 켠다) */
+export function domainRegistration(store) { const v = getSetting(store, 'domain_registration', { enabled: false }); return { enabled: !!v.enabled, registrar: v.registrar || null, note: v.note || '도메인 등록 기능이 연결되어 있지 않습니다. 외부 등록기관에서 등록한 뒤 도메인 화면에서 연결하세요' }; }
+/** 이번 달 예상 비용·결제 대기 금액(§6.3) */
+export function billingSummary(store, groupId) {
+ const subs = listSubscriptions(store, groupId); const act = subs.filter((s) => !['cancelled'].includes(s.status));
+ const awaiting = listOrders(store, { groupId, status: ['awaiting_payment', 'awaiting_approval'] });
+ const credits = listCredits(store, groupId); const creditBalance = credits.reduce((s, c) => s + (c.kind === 'refund' ? 0 : c.amount), 0);
+ return { subscriptions: act.map((s) => ({ ...s, label: SUB_LABEL[s.status] || s.status, product: publicProduct(getProductVersion(store, s.product_version_id)) })), nextBillingAt: act.map((s) => s.next_billing_at).filter(Boolean).sort()[0] || null, monthEstimate: act.reduce((s, x) => s + (x.billing_cycle === 'monthly' ? x.total : Math.round(x.total / 12)), 0), awaitingTotal: awaiting.reduce((s, o) => s + o.total, 0), awaitingOrders: awaiting, creditBalance, credits, currency: 'KRW' };
+}
+export { getProductVersion, rowToProduct };
diff --git a/portal/commerce/public/billing.js b/portal/commerce/public/billing.js
new file mode 100644
index 0000000..e5e6ae3
--- /dev/null
+++ b/portal/commerce/public/billing.js
@@ -0,0 +1,28 @@
+/* portal/commerce/public/billing.js — 결제 화면(§6.3~6.5): 활성 상품·다음 청구일·예상 금액·결제 대기·주문 목록·권리·환불/크레딧·축소 보류·해지·AI Wallet·초과 사용·도메인 등록 안내. */
+(() => {
+ const el = document.getElementById('billing'); const esc = aw.esc; const money = (n) => Number(n).toLocaleString('ko-KR') + '원'; const GB = 1024 ** 3;
+ const fmt = (n, unit) => (unit.startsWith('bytes') ? (n / GB).toFixed(1) + ' GB' : Number(n).toLocaleString('ko-KR'));
+ async function load() {
+ try { const d = await aw.api('GET', '/api/commerce/billing');
+ let h = `이번 달 예상
${money(d.monthEstimate)}
다음 청구일 ${d.nextBillingAt ? aw.fmt(d.nextBillingAt) : '없음'}
결제 대기
${money(d.awaitingTotal)}
${d.awaitingOrders.length}건
크레딧 잔액
${money(d.creditBalance)}
활성 상품과 옵션
${d.subscriptions.length ? d.subscriptions.map((s) => `
- 상품
- ${esc(s.product.name)} v${s.product.version} ${s.status === 'active' ? '●' : '!'} ${esc(s.label)}
- 항목
- ${s.items.map((i) => esc(i.name) + '×' + i.qty).join(', ')}
- 청구
- ${money(s.total)} / ${s.billing_cycle === 'monthly' ? '월' : '년'} · 다음 ${s.next_billing_at ? aw.fmt(s.next_billing_at) : '-'}
${s.payment_due_at ? `- 갱신 입금 기한
- ${aw.fmt(s.payment_due_at)} · 미납 제한 예정 ${aw.fmt(s.restrict_at)}
` : ''}${s.cancel_at ? `- 해지 적용일
- ${aw.fmt(s.cancel_at)}
` : ''}
${s.status === 'cancel_scheduled' ? '
' : '
'}
상품 변경·축소`).join('') : '
활성 상품이 없습니다.
상품 보기'}
상품 축소 보류
새 한도 안에 들어오지 않는 항목이 있어 축소가 보류되었습니다. 아래 항목을 정리한 뒤 "다시 검증" 을 누르세요.
${d.hold.shortages.map((s) => `- ${esc(s.label)}: ${fmt(s.reduceBy, s.unit)} 줄이기 (새 한도 ${fmt(s.newLimit, s.unit)}, 배정+예약 ${fmt(s.inUse, s.unit)}, 사용 ${fmt(s.used, s.unit)})
${s.items.map((i) => `- ${esc(i.subjectType)} ${esc(i.subjectId)}: 배정 ${fmt(i.amount, s.unit)}
`).join('')}
`).join('')}
마지막 검증 ${aw.fmt(d.hold.last_checked_at)}
활성화된 권리
| 자원 | 구매 | 배정 | 사용 |
|---|
${d.entitlements.filter((e) => e.purchased).map((e) => `| ${esc(e.label)} | ${fmt(e.purchased, e.unit)} | ${fmt(e.allocated, e.unit)} | ${fmt(e.used, e.unit)} |
`).join('') || '| 없음 |
'}
주문
${d.orders.length ? `
| 번호 | 종류 | 금액 | 상태 | 일시 |
|---|
${d.orders.map((o) => `| ${esc(o.order_no)} | ${esc({ new: '신규', renewal: '갱신', downsize: '축소' }[o.kind] || o.kind)} | ${money(o.total)} | ${esc(o.statusLabel)} | ${aw.fmt(o.created_at)} |
`).join('')}
` : '
주문이 없습니다.
'}
환불·크레딧
${d.credits.length ? `
| 종류 | 금액 | 사유 | 적용일 |
|---|
${d.credits.map((c) => `| ${esc({ refund: '환불', credit: '크레딧', adjust: '조정' }[c.kind])} | ${money(c.amount)} | ${esc(c.reason)} | ${aw.fmt(c.applies_at)} |
`).join('')}
` : '
없음
'}
AI Wallet
제작(AI) 기능 전용이며 호스팅 디스크·트래픽·메일 사용량과 분리되어 있습니다.
${d.wallet && d.wallet.balance !== undefined ? `
${esc(d.wallet.unit ? d.wallet.balanceText || d.wallet.balance : money(d.wallet.balance))}
${(d.wallet.ledger || []).slice(0, 10).map((l) => `
${aw.fmt(l.at)} ${esc(l.type)} ${esc(String(l.amount))} ${esc(l.memo || '')}${l.refunded ? ' (실패 환급)' : ''}
`).join('')}
충전·이력` : `
${esc(d.wallet?.message || '')}
`}
초과 사용 허용
자동 초과 사용과 자동 추가 과금은 기본으로 꺼져 있습니다. 허용하려면 항목별 최대 금액 또는 최대 사용량과 기간을 정해야 하며, 철회하면 즉시 100% 제한이 다시 적용됩니다.
${d.overage.filter((o) => !o.revoked_at).map((o) => `
${esc(o.resource)}: 상한 ${o.cap_amount ? money(o.cap_amount) : o.cap_units + ' 단위'} · ${o.period_start.slice(0, 10)}~${o.period_end.slice(0, 10)}
`).join('') || '
허용한 항목 없음
'}
도메인 등록
${d.domainRegistration.enabled ? '
등록기관을 통해 도메인을 검색·등록할 수 있습니다.
' : `
${esc(d.domainRegistration.note)}
`}
${kind === 'done' ? '✔' : kind === 'failed' ? '✘' : '◔'} ${esc(o.statusLabel)}마지막 갱신 ${aw.fmt(o.updated_at)}
${esc(o.nextStep)}
${o.remaining ? `
${esc(o.remaining)}
` : ''}
+
- 주문 번호
- ${esc(o.order_no)}
- 종류
- ${esc({ new: '신규', renewal: '갱신', downsize: '축소' }[o.kind] || o.kind)}
- 금액
- ${money(o.amount, o.currency)} + 세금 ${money(o.tax, o.currency)} = ${money(o.total, o.currency)}
- 결제 방식
- 계좌 이체(수동 결제 확인)
${o.due_at ? `- 입금 기한
- ${aw.fmt(o.due_at)}
` : ''}${o.paid_at ? `- 입금 확인
- ${aw.fmt(o.paid_at)}
` : ''}${o.approved_at ? `- 승인
- ${aw.fmt(o.approved_at)}
` : ''}- 취소 가능 단계
- ${esc(o.lastCancellableStep)}
+ ${o.status === 'awaiting_payment' ? `
입금 안내
${esc(pi.bank || '')} ${esc(pi.account || '')} (예금주 ${esc(pi.holder || '')})
${esc(pi.note || '')}
` : ''}
+
| 항목 | 수량 | 적용 대상 | 단가 | 세금 | 합계 |
|---|
${o.items.map((i) => `| ${esc(i.name)} | ${i.qty} | ${i.target_type === 'site' ? '사이트 ' + esc(i.target_id || '') : '사용자 그룹'} | ${money(i.unit_price, o.currency)} | ${money(i.tax, o.currency)} | ${money(i.amount + i.tax, o.currency)} |
`).join('')}
+ ${o.policyNotes ? `
입금 기한 ${o.policyNotes.paymentDeadlineDays}일 · 미납 ${o.policyNotes.restrictionAfterUnpaidDays}일 후 ${esc(o.policyNotes.restrictionEffect || '')}
` : ''}
+
2. 가격과 청구 주기
${q.items.map((i) => `| ${esc(i.name)} × ${i.qty} | ${money(i.amount)} + 세금 ${money(i.tax)} |
`).join('')}| 합계(세금 포함) | ${money(q.total)} ${q.currency} |
|---|
청구 주기: ${pv.billingCycle === 'monthly' ? '매월' : '매년'} · 갱신 전 청구 예정일과 금액을 알려 드립니다
3. 약관과 제한
${quote.terms.notes.map((n) => `- ${esc(n)}
`).join('')}
${pv.deferred.length ? `
! 미확정 정책 ${pv.deferred.map((d) => esc(d.key)).join(', ')} — 확정 전에는 약속으로 보지 마세요
` : ''}
4. 결제 방식
${esc(pi.bank)} ${esc(pi.account)} (예금주 ${esc(pi.holder)}) · 입금 기한 ${pi.deadline_days}일 · ${esc(pi.note || '')}
운영자가 입금을 확인하고 승인한 뒤에만 사이트 수·용량·메일함·백업 권리를 쓸 수 있습니다.
ⓘ 결제 방식: ${esc(d.paymentMethods.map((m) => m.label).join(', '))} — 자동 결제는 지원하지 않습니다.
` + `${d.products.map((p) => `
${esc(p.name)} v${p.version}
${esc(p.audience)}
${esc(p.description || '')}
${money(p.price)}/${p.billingCycle === 'monthly' ? '월' : '년'} + 세금 ${money(p.tax)} = ${money(p.total)}
+
- 사이트 수
- ${p.limits.sites}개
- 웹 디스크
- ${gb(p.limits.web_disk)}
- 월간 웹 아웃바운드
- ${gb(p.limits.web_out)}
- 메일 저장 공간
- ${gb(p.limits.mail_storage)}
- 월간 메일 통수
- ${p.limits.mail_msgs.toLocaleString('ko-KR')}통(송신+수신)
- 메일함
- ${p.limits.mailboxes}개
+
추가 옵션
${p.options.map((o) => `- ${esc(o.name)} — ${money(o.price)}${o.per === 'site' ? ' (사이트당)' : ''}
`).join('')}
+
제공 범위
${p.includes.map((x) => `- ${esc(x)}
`).join('')}
제외
${p.excludes.map((x) => `- ${esc(x)}
`).join('')}
+ ${p.deferred.length ? `
미확정 정책
${p.deferred.map((x) => `- ! 미확정 정책 ${esc(x.key)} — ${esc(x.note)}
`).join('')}
` : ''}
+
사용량 경고 ${p.warnLevels.join('·')}% · 승인 방식: 운영자 수동 승인 · 적용 ${esc(p.effectiveFrom.slice(0, 10))}
+
`).join('')}
도메인 등록
${d.domainRegistration.enabled ? `
등록기관(${esc(d.domainRegistration.registrar || '')})을 통해 도메인을 검색·등록할 수 있습니다.
` : `
${esc(d.domainRegistration.note)}
`}
${deps.statePanel('loading')}
`, scripts: ['/ui/usage/usage.js'] })); });
+ app.get('/usage/allocate/:subject', (ctx) => { requireGroup(ctx); return ctx.html(shell(ctx, { title: '보장량 배정 변경', crumbs: [{ label: '사용량', href: '/usage' }, { label: '배정 변경' }], body: `${deps.statePanel('loading')}
`, scripts: ['/ui/usage/allocate.js'] })); });
+
+ app.get('/api/usage', (ctx) => { requireGroup(ctx); return usageSummary(deps, ctx.group.id); });
+ app.get('/api/usage/limits', (ctx) => { requireGroup(ctx); return { limits: listLimits(store, ctx.group.id), semantics: LIMIT_SEMANTICS }; });
+ app.post('/api/usage/evaluate', (ctx) => { requireRole(ctx, ['owner', 'admin', 'billing', 'member']); return { ok: true, ...evaluate(deps, ctx.group.id) }; });
+ app.get('/api/usage/allocate/:subject', (ctx) => { requireGroup(ctx); return allocationView(deps, ctx.group.id, ctx.params.subject); });
+ app.post('/api/usage/allocate/:subject', async (ctx) => { requireRole(ctx, 'admin'); const b = await ctx.body(); try { return { ok: true, ...changeAllocation(deps, { groupId: ctx.group.id, userId: ctx.user.id, subjectStr: ctx.params.subject, resource: b.resource, amount: b.amount }) }; } catch (e) { if (e instanceof quota.QuotaError) throw new HttpError(409, e.code, e.message, e.detail); throw e; } });
+
+ // 운영자 콘솔용
+ app.get('/internal/ops/usage/overview', async (ctx) => { await requireOps(ctx, deps); const groups = store.all('SELECT DISTINCT group_id FROM quota_entitlements'); return { groups: groups.map((g) => { const gr = store.get('SELECT id, name, kind FROM groups WHERE id=?', g.group_id); return { group: gr || { id: g.group_id }, resources: quota.summary(store, g.group_id).map((f) => ({ resource: f.resource, label: f.label, unit: f.unit, purchased: f.purchased, allocated: f.allocated, reserved: f.reserved, used: f.used, percent: quota.percent(f.used, f.purchased) })), limits: listLimits(store, g.group_id).length }; }), staleMinutes: staleMinutes(store) }; });
+ app.get('/internal/ops/usage/group/:groupId', async (ctx) => { await requireOps(ctx, deps); return usageSummary(deps, ctx.params.groupId); });
+ app.get('/internal/ops/usage/limits', async (ctx) => { await requireOps(ctx, deps); return { limits: store.all('SELECT * FROM usage_limits WHERE level>0 ORDER BY level DESC, evaluated_at DESC').map((r) => ({ ...r, limited: !!r.limited, semantics: LIMIT_SEMANTICS[r.resource] || null })) }; });
+ app.post('/internal/ops/usage/evaluate', async (ctx) => { await requireOps(ctx, deps); return { ok: true, results: evaluateAll(deps) }; });
+ // 주기 작업 등록(스케줄러가 있으면)
+ if (deps.scheduler?.every) deps.scheduler.every('usage.evaluate', 5 * 60 * 1000, () => evaluateAll(deps));
+ deps.usage = { evaluate: (groupId) => evaluate(deps, groupId), evaluateAll: () => evaluateAll(deps), summary: (groupId) => usageSummary(deps, groupId) };
+}
diff --git a/portal/usage/limits.mjs b/portal/usage/limits.mjs
new file mode 100644
index 0000000..892bcb7
--- /dev/null
+++ b/portal/usage/limits.mjs
@@ -0,0 +1,32 @@
+/**
+ * portal/usage/limits.mjs — 100% 제한 조회(다른 영역이 쓰는 읽기 전용 API)와 자원별 제한 의미(§13.4).
+ *
+ * 자원별 100% 동작
+ * web_out 사이트 대신 제한 안내 화면(유지: 관리자 화면·조회·삭제·내보내기 / 제한: 공개 접속). 다음 KST 월 시작 또는 추가 용량 적용 후 복구.
+ * web_disk 유지: 기존 사이트 조회·삭제·내보내기 / 제한: 새 업로드·데이터베이스 증가·새 배포.
+ * mail_storage 유지: 기존 메일 조회·삭제 / 제한: 새 수신(발신 서버가 재시도하도록 임시 실패 4xx)·저장.
+ * mail_msgs 유지: 조회·삭제 / 제한: 새 발신 차단 + 새 수신 임시 실패. 다음 KST 월 시작 또는 추가 용량 적용 후 복구.
+ * mailboxes 유지: 기존 메일함 / 제한: 새 메일함 생성.
+ * sites·mail_services·source·backup 은 개수 권리라 100% = "추가 생성 불가"(lib/quota.reserve 가 거부).
+ * 초과 사용 허용(overage opt-in)이 유효하고 상한 안이면 limited=false 로 두되 overage=1 로 표시한다.
+ * 고객 데이터는 어떤 경우에도 자동 삭제하지 않는다.
+ */
+export const LIMIT_SEMANTICS = Object.freeze({
+ web_out: { kept: ['관리 화면 접근', '파일 조회·내보내기', '삭제'], blocked: ['공개 사이트 접속(제한 안내 화면 표시)'], recovery: '다음 KST 월 시작 또는 추가 용량(옵션 구매·배정 증가) 적용 후 자동 복구', monthly: true },
+ web_disk: { kept: ['기존 사이트 조회', '삭제·내보내기'], blocked: ['새 업로드', '데이터베이스 증가', '새 배포'], recovery: '파일·데이터 정리 또는 추가 용량 적용 후 복구', monthly: false },
+ mail_storage: { kept: ['기존 메일 조회', '삭제'], blocked: ['새 수신(임시 실패 응답 — 발신 서버가 재시도)', '새 저장'], recovery: '메일 정리 또는 추가 용량 적용 후 복구', monthly: false },
+ mail_msgs: { kept: ['기존 메일 조회', '삭제'], blocked: ['새 발신', '새 수신(임시 실패 응답)'], recovery: '다음 KST 월 시작 또는 추가 통수 적용 후 복구', monthly: true },
+ mailboxes: { kept: ['기존 메일함'], blocked: ['새 메일함 생성'], recovery: '메일함 정리 또는 추가 메일함 옵션 적용 후 복구', monthly: false },
+ sites: { kept: ['운영 중 사이트'], blocked: ['새 공개 배포(사이트 수 확보)'], recovery: '사이트 수 반환(§14) 또는 상품 구매', monthly: false },
+ mail_services: { kept: ['기존 메일 서비스'], blocked: ['새 독립 메일 서비스'], recovery: '옵션 구매', monthly: false },
+ source: { kept: ['기존 저장소 조회'], blocked: ['새 Source 옵션 적용'], recovery: '옵션 구매', monthly: false },
+ backup: { kept: ['기존 백업 보관'], blocked: ['새 백업 옵션 활성화'], recovery: '옵션 구매', monthly: false },
+});
+/** 대상(사이트·메일 서비스)의 자원이 100% 제한 중인지 */
+export function isLimited(store, resource, subjectType, subjectId) { const r = store.get('SELECT limited FROM usage_limits WHERE resource=? AND subject_type=? AND subject_id=?', resource, subjectType, subjectId); return !!(r && r.limited); }
+/** 제한 상세(화면용): { level, limited, used, limit, since, reason, semantics, overage } 또는 null */
+export function limitInfo(store, resource, subjectType, subjectId) { const r = store.get('SELECT * FROM usage_limits WHERE resource=? AND subject_type=? AND subject_id=?', resource, subjectType, subjectId); if (!r) return null; return { resource, level: r.level, limited: !!r.limited, used: r.used, limit: r.limit, since: r.since, reason: r.reason, overage: !!r.overage, evaluatedAt: r.evaluated_at, semantics: LIMIT_SEMANTICS[resource] || null }; }
+/** 그룹 전체의 제한·경고 목록 */
+export function listLimits(store, groupId) { return store.all('SELECT * FROM usage_limits WHERE group_id=? AND level>0 ORDER BY level DESC, resource', groupId).map((r) => ({ ...r, limited: !!r.limited, overage: !!r.overage, semantics: LIMIT_SEMANTICS[r.resource] || null })); }
+/** 대상에 걸린 모든 제한(배포 전 확인 등에서 한 번에) */
+export function limitsFor(store, subjectType, subjectId) { return store.all('SELECT * FROM usage_limits WHERE subject_type=? AND subject_id=? AND level>0', subjectType, subjectId).map((r) => ({ ...r, limited: !!r.limited, semantics: LIMIT_SEMANTICS[r.resource] || null })); }
diff --git a/portal/usage/model.mjs b/portal/usage/model.mjs
new file mode 100644
index 0000000..52ca926
--- /dev/null
+++ b/portal/usage/model.mjs
@@ -0,0 +1,11 @@
+/**
+ * portal/usage/model.mjs — 사용량 영역 표(§13.4).
+ * usage_limits 그룹·자원·대상별 현재 경고 구간(level)과 제한 여부(limited). 다른 영역(사이트·메일·배포)은 portal/usage/limits.mjs 로 읽는다.
+ */
+export const MIGRATIONS = [{ id: 'usage_0001', sql: `
+CREATE TABLE IF NOT EXISTS usage_limits (
+ group_id TEXT NOT NULL, resource TEXT NOT NULL, subject_type TEXT NOT NULL, subject_id TEXT NOT NULL, level INTEGER NOT NULL DEFAULT 0, limited INTEGER NOT NULL DEFAULT 0,
+ used INTEGER NOT NULL DEFAULT 0, "limit" INTEGER NOT NULL DEFAULT 0, since TEXT, reason TEXT, overage INTEGER NOT NULL DEFAULT 0, evaluated_at TEXT NOT NULL, period_start TEXT,
+ PRIMARY KEY(group_id, resource, subject_type, subject_id)
+);
+` }];
diff --git a/portal/usage/public/allocate.js b/portal/usage/public/allocate.js
new file mode 100644
index 0000000..1655317
--- /dev/null
+++ b/portal/usage/public/allocate.js
@@ -0,0 +1,19 @@
+/* portal/usage/public/allocate.js — 서비스별 보장량 배정 변경(§13.3). 구매 총량·사용 중·다른 서비스 배정·예약·미배정·변경 후 값을 함께 보인다. */
+(() => {
+ const el = document.getElementById('alloc'); const subject = el.dataset.subject; const esc = aw.esc;
+ const fmt = (n, unit) => (unit.startsWith('bytes') ? (n >= 1024 ** 3 ? (n / 1024 ** 3).toFixed(2) + ' GB' : n >= 1024 ** 2 ? (n / 1024 ** 2).toFixed(0) + ' MB' : n + ' B') : Number(n).toLocaleString('ko-KR'));
+ const GB = 1024 ** 3;
+ async function load() {
+ try {
+ const d = await aw.api('GET', `/api/usage/allocate/${encodeURIComponent(subject)}`);
+ el.innerHTML = `${esc(d.subject.label)} · ${esc(d.subject.name)}
월간 항목은 ${esc(d.nextResetText)} 에 초기화됩니다. 실제 사용량보다 작게 줄일 수 없고, 월간 항목은 이번 달 누적보다 작게 줄일 수 없습니다.
${esc(r.label)}${r.monthly ? ' (월간)' : ''}
+
- 구매 총량
- ${esc(r.texts.purchased)}
- 이 서비스 사용 중(배정)
- ${esc(r.texts.mine)} ○ ${esc(r.mineState)}
- 다른 서비스 배정
- ${esc(r.texts.others)}
- 진행 중 작업 예약
- ${esc(r.texts.reserved)}
- 미배정
- ${esc(r.texts.unallocated)}
- 실제 사용${r.monthly ? '(이번 달 누적)' : ''}
- ${esc(r.texts.used)}${r.measuredAt ? ` 계측 ${aw.fmt(r.measuredAt)}` : ''}${r.stale ? ' ! 정보 확인 지연 — 늘릴 수 없음' : ''}
${r.limit ? `- 제한
- ${r.limit.limited ? '100% 제한 적용 중' : r.limit.level + '% 경고'}
` : ''}
+
`;
+ const lvlOf = (p) => (p >= 100 ? 100 : p >= 95 ? 95 : p >= 90 ? 90 : p >= 80 ? 80 : p >= 70 ? 70 : 0);
+ async function load() {
+ try {
+ const d = await aw.api('GET', '/api/usage');
+ if (!d.product) { aw.state(el, 'empty', '활성 상품이 없습니다. 상품을 주문하면 사용량이 표시됩니다', { href: '/products', hrefLabel: '상품 보기' }); return; }
+ let h = `- 적용 상품정책
- ${esc(d.product.name)} v${d.product.version} (경고 구간 ${d.product.warnLevels.join('·')}%)
- 다음 KST 월 초기화
- ${esc(d.nextResetText)}
- 마지막 계측
- ${esc(d.lastMeasuredText)}${d.stale ? ' ! 정보 확인 지연' : ''}
경고·제한
${d.limits.map((l) => `- ${l.limited ? '✘ 제한' : '! ' + l.level + '%'} ${esc(l.resource)} · ${esc(l.subject_type)} ${esc(l.subject_id)}${l.limited && l.semantics ? ` — 제한: ${esc(l.semantics.blocked.join(', '))} / 유지: ${esc(l.semantics.kept.join(', '))} / 해제: ${esc(l.semantics.recovery)}` : ''}${l.overage ? ' (초과 사용 허용 중)' : ''}
`).join('')}
그룹 전체(구매 총량 기준)
| 자원 | 구매 총량 | 배정 | 예약(진행 중 작업) | 미배정 | 실제 사용 | 사용률 |
|---|
${d.resources.map((r) => `| ${esc(r.label)}${r.monthly ? ' (월간)' : ''} | ${fmt(r.purchased, r.unit)} | ${fmt(r.allocated, r.unit)} | ${fmt(r.reserved, r.unit)} | ${fmt(r.unallocated, r.unit)} | ${fmt(r.used, r.unit)} | ${bar(r.usedPercent, lvlOf(r.usedPercent))} ${r.usedPercent}% |
`).join('')}
서비스별 배정과 사용
${d.allocations.length ? `
| 서비스 | 자원 | 배정 | 상태 | 사용 | 계측 | |
|---|
${d.allocations.map((a) => `| ${esc(a.subjectLabel)} · ${esc(a.subjectName)} | ${esc(a.label)} | ${esc(a.amountText)} | ○ ${esc(a.stateLabel)} | ${esc(a.usedText)} ${a.percent != null ? bar(a.percent, lvlOf(a.percent)) + a.percent + '%' : ''} | ${a.measured_at ? aw.fmt(a.measured_at) : '계측 전'}${a.stale ? ' ! 지연' : ''} | 배정 변경 |
`).join('')}
` : '
아직 배정된 서비스가 없습니다. 사이트나 메일 서비스를 만들면 여기에 표시됩니다.
'}
진행 중 작업의 예약
| 자원 | 양 | 상태 | 사유 | 만료·반환 예정 |
|---|
${d.reservations.map((r) => `| ${esc(r.label)} | ${r.amount} | ${esc(r.stateLabel)} | ${esc(r.reason || '')} | ${r.return_due_at ? aw.fmt(r.return_due_at) : r.expires_at ? aw.fmt(r.expires_at) : ''} |
`).join('')}