@kesflow/kf 0.1.11 → 0.1.12

package/SKILL.md

@@ -16,13 +16,13 @@ description: Thao tác nội bộ KesFlow qua CLI `kf` thay cho bấm màn ops,
 ## Cách dùng
 - Danh sách thao tác (lấy trực tiếp từ server, luôn đúng): `kf --help`. Tham số một thao tác: `kf <op> --help`, `kf schema <op>`.
 - Gọi: `kf <op> --<tham-so> <giá trị>` hoặc `kf <op> --json '{...}'`. Kết quả: một dòng JSON (`--pretty` để đọc).
-- Không chắc thì chạy thử trước: thêm `--dry-run` (chỉ kiểm, không ghi gì).
+- Không chắc thì chạy thử trước: thêm `--dry-run`: chỉ kiểm khuôn tham số, không kiểm quyền hay điều kiện nghiệp vụ, không ghi gì. Thao tác `[high]` chạy thử không cần `--yes`.
 - Tải tệp từ máy lên buổi học: `kf lms upload <tệp> --buoi-id <id> [--loai slide_pdf|slide_html|record|video_xem_truoc] [--ten ...]`.
 - Tải tệp tài nguyên lên sản phẩm: `kf tn upload <tệp> --ma <SP>` (tối đa 256 MiB, gửi tới `https://ops.kesflow.vn`; dùng `KF_NB_URL` cho host nội bộ thử/cục bộ).
 - Tìm `buoi-id`: `kf status` (lớp tôi phụ trách) → `kf lop-chi-tiet --ma <MÃ LỚP>`.
 
 ## Thao tác rủi ro cao (`[high]`, cần `--yes`)
-- Ví dụ `lms-dang-buoi --gui-thu true` gửi thư cho **cả lớp thật**. `lms-dang-buoi` luôn cần `--yes`, kể cả khi không gửi thư.
+- Ví dụ `lms-dang-buoi --gui-thu true` gửi thư cho **cả lớp thật**. `lms-dang-buoi` luôn cần `--yes` (trừ `--dry-run`), kể cả khi không gửi thư.
 - Chỉ thêm `--yes` **sau khi người dùng đồng ý rõ trong chat** với đúng nội dung: buổi nào, lớp nào, có gửi thư không. Không tự suy ra ý định gửi thư.
 - `--yes` không thay người duyệt; người dùng nên để Claude Code hỏi quyền trước lệnh `kf … --yes`.
 - `sp-gia`/`sp-trang-thai` đổi giá và mở bán thật: chỉ dùng `--yes` sau khi người dùng nêu đúng mã sản phẩm và con số trong chat.
@@ -75,7 +75,7 @@ description: Thao tác nội bộ KesFlow qua CLI `kf` thay cho bấm màn ops,
 
 ## Xoá dữ liệu (chỉ CEO — cực kỳ nguy hiểm, không hoàn tác)
 - Luôn `kf xoa-xem --loai <san_pham|voucher|ghi_danh> --khoa <mã/id>` trước. Trình cho người dùng **nguyên văn**: từng loại dữ liệu và số dòng sẽ mất, các tín hiệu "dữ liệu thật", số dòng Base Tiền phải xoá tay, và câu "không hoàn tác được". Bị chặn (`chan`) thì dừng, báo lý do.
-- Dữ liệu rác: một lệnh `kf xoa … --yes` sau khi người dùng đồng ý. Dữ liệu thật: lệnh đầu trả `NB_XOA_CAN_XAC_NHAN_2` kèm mã — **dừng, hỏi người dùng lần hai**, chỉ khi họ đồng ý mới gọi lại với mã đó. Không bao giờ gửi hai xác nhận trong một lượt.
+- Dữ liệu rác: một lệnh `kf xoa … --yes` sau khi người dùng đồng ý. Dữ liệu thật: lệnh đầu trả `NB_XOA_CAN_XAC_NHAN_2` kèm mã ở trường `ly_do` — **dừng, hỏi người dùng lần hai**, chỉ khi họ đồng ý mới gọi lại với `--xac-nhan-2 <mã đó>`. Không bao giờ gửi hai xác nhận trong một lượt.
 - `NB_XOA_DA_DOI`: dữ liệu đã đổi từ lúc xem — xem lại từ đầu. `NB_XOA_CHAN`: bị chặn (vd sổ chi trả affiliate, SP quản lý ở Base Tiền) — dừng, báo lý do. Giao dịch ngân hàng của đơn bị xoá không mất, quay về "Chờ xử lý".
 
 ## Hoàn tiền và hoá đơn (CEO, kế toán; admin đọc trong phạm vi)

package/dist/api.d.ts

@@ -2,7 +2,8 @@ export declare class CliError extends Error {
     readonly exitCode: number;
     readonly code: string;
     readonly http: number | null;
-    constructor(message: string, exitCode: number, code: string, http?: number | null);
+    readonly detail: Record<string, unknown>;
+    constructor(message: string, exitCode: number, code: string, http?: number | null, detail?: Record<string, unknown>);
 }
 export declare function httpExit(status: number): number;
 export declare function request(baseUrl: string, token: string, path: string, body?: Record<string, unknown>): Promise<unknown>;

package/dist/api.js

@@ -2,11 +2,13 @@ export class CliError extends Error {
     exitCode;
     code;
     http;
-    constructor(message, exitCode, code, http = null) {
+    detail;
+    constructor(message, exitCode, code, http = null, detail = {}) {
         super(message);
         this.exitCode = exitCode;
         this.code = code;
         this.http = http;
+        this.detail = detail;
     }
 }
 export function httpExit(status) {
@@ -44,7 +46,15 @@ export async function request(baseUrl, token, path, body) {
         const obj = data && typeof data === 'object' ? data : {};
         const candidate = typeof obj.ma === 'string' ? obj.ma : typeof obj.loai === 'string' ? obj.loai : '';
         const code = /^[A-Za-z][A-Za-z0-9_]{0,79}$/.test(candidate) ? candidate : `HTTP_${response.status}`;
-        throw new CliError(code, httpExit(response.status), code, response.status);
+        // Server error envelope (thanLoiAgent) carries what the agent must act on next, e.g. the second-confirmation
+        // code of NB_XOA_CAN_XAC_NHAN_2 in ly_do. Pass through only these keys, as strings or string lists.
+        const detail = {};
+        for (const key of ['ly_do', 'chi_tiet', 'khoa', 'ket_qua_khop']) {
+            const value = obj[key];
+            if (typeof value === 'string' || (Array.isArray(value) && value.every((x) => typeof x === 'string')))
+                detail[key] = value;
+        }
+        throw new CliError(code, httpExit(response.status), code, response.status, detail);
     }
     return data;
 }

package/dist/cli.js

@@ -253,6 +253,6 @@ stdout.on('error', (error) => { if (error.code === 'EPIPE')
     process.exit(0); throw error; });
 run(process.argv.slice(2)).catch((error) => {
     const e = error instanceof CliError ? error : new CliError('Lỗi hệ thống', 5, 'INTERNAL');
-    stderr.write(`${redact(JSON.stringify({ error: e.message, code: e.code, http: e.http }))}\n`);
+    stderr.write(`${redact(JSON.stringify({ error: e.message, code: e.code, http: e.http, ...e.detail }))}\n`);
     process.exitCode = e.exitCode;
 });

package/dist/ops.js

@@ -83,9 +83,11 @@ export function parseBody(op, args) {
             throw new CliError(`Thiếu giá trị: --${flag}`, 2, 'USAGE');
         body[key] = scalar(props[key], raw);
     }
-    if (op.risk === 'high' && !yes)
+    // --dry-run needs no --yes: the server parses the body and returns before running the op, in a rolled-back
+    // transaction (apps/web/lib/agent/http.ts). xac_nhan is still set so the dry run checks the same body.
+    if (op.risk === 'high' && !yes && !dryRun)
         throw new CliError('Thao tác rủi ro cao cần --yes', 2, 'USAGE');
-    if (yes && op.risk === 'high')
+    if ((yes || dryRun) && op.risk === 'high')
         body.xac_nhan = true;
     if (dryRun)
         body.dry_run = true;
@@ -97,5 +99,5 @@ export function operationHelp(op) {
         const type = schema.type || schema.anyOf?.map((s) => s.type).filter(Boolean).join('|') || 'JSON';
         return `  --${name.replaceAll('_', '-')} <${type}>${required}`;
     }).join('\n');
-    return `${op.id} [${op.risk}] — ${op.tom_tat}\nRoles: ${op.roles.join(', ')}\n${props}\n  --json '<object>'  --dry-run  --pretty${op.risk === 'high' ? '  --yes (required)' : ''}`;
+    return `${op.id} [${op.risk}] — ${op.tom_tat}\nRoles: ${op.roles.join(', ')}\n${props}\n  --json '<object>'  --dry-run  --pretty${op.risk === 'high' ? '  --yes (required, trừ khi --dry-run)' : ''}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kesflow/kf",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "KesFlow agent CLI",
   "type": "module",
   "bin": {