@restoai/resto-datacli 0.1.11 → 0.2.0

package/.agents/skills/resto-datacli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: resto-datacli
-description: Use deterministic local/remote resto-datacli commands to discover reports, inspect fields, validate query plans, execute report queries, and transform saved snapshots.
+description: Use deterministic local/remote resto-datacli commands to discover reports, inspect fields, validate query plans, execute report queries, drill into order details, and transform saved snapshots.
 ---
 
 # resto-datacli Skill
@@ -16,6 +16,17 @@ Use `resto-datacli` as evidence-backed tools for restaurant reporting data. Agen
 - Ask clarification when metric meaning is ambiguous, for example when "sales" could mean net sales, gross sales, paid amount, quantity, or order count.
 - Treat missing fields as capability gaps. Explain the gap, cite what was searched or inspected, and offer alternatives such as nearby fields, another report, narrower scope, or asking the data owner.
 
+## Startup Freshness Check
+
+At the start of a Resto data task or a new Agent session, check tool and knowledge freshness before discovery:
+
+1. Run `resto --version`.
+2. Run `npm view @restoai/resto-datacli version --cache /private/tmp/resto-datacli-npm-cache`.
+3. If npm has a newer version, run `npm install -g @restoai/resto-datacli@latest --cache /private/tmp/resto-datacli-npm-cache`, then run `resto install-skill`, and tell the user to restart the current Agent or open a new session so the updated skill is loaded.
+4. run `resto knowledge status` to inspect local knowledge.
+5. run `resto knowledge check` with the task's env and schema version when auth is available.
+6. run `resto knowledge sync` when local knowledge is missing, stale, or older than the remote manifest. For China production, use `--env bj --schema-version 1` unless the user or deployment context says otherwise.
+
 ## Prerequisites
 
 - run `resto knowledge status` to see the current local package.
@@ -27,13 +38,31 @@ Use `resto-datacli` as evidence-backed tools for restaurant reporting data. Agen
 ## Discovery Workflow
 
 1. Search candidate reports with `resto report search`.
-2. Inspect promising reports with `resto report inspect` to confirm report metadata and available fields.
+2. Inspect promising reports with `resto report inspect` to confirm report metadata, composition, row-pivot rules, and merged-head evidence.
 3. Search fields with `resto field search` when a metric, dimension, filter, currency, or time grain is unclear.
 4. Review reusable references with `resto playbook list` and `resto playbook inspect`. Playbooks are reference material, not automatic intent resolution.
 5. Build an explicit JSON query plan containing `reportId`, `selectFields`, `filters`, optional `orderBy`, paging, proportions, and additional dimension strategies.
 6. Validate before executing with `resto query validate`.
 7. Execute only validated plans with `resto query execute`.
 
+## Composite And Row-Pivot Reports
+
+- When `report inspect` returns `composition`, keep `reportId` / `queryReportId` as the executable report and use `basicReportId` plus merged fields as field evidence. Do not replace the executable report id with the basic report id.
+- Treat `metricsByDim` as an explicit dimension-to-metric allowlist. Use `metricFieldNames` for available metrics and prefer `defaultMetricFieldNames` only when they match the user's requested measure.
+- Do not generate row-pivot plans for entries where `disableMetricsByDim=true`.
+- Use `mergedHeads` to understand static versus dynamic sub-heads, subtotal behavior, and the dimension that generates dynamic columns. Do not invent possible dynamic values from metadata alone.
+- Hidden fields are omitted from normal field discovery. Use `resto field list --include-hidden` or `resto field search --include-hidden` only when technical validation, required filters, or drilldown needs them. A hidden field may be valid in a query plan even though it should not appear in a customer-facing field list.
+
+## Order Detail Drilldown
+
+- Treat the账单明细表 page (`reportId=888002`, `basicReportId=3`) and an individual order detail as different operations.
+- Use a normal validated query plan on `reportId=888002` to list or locate orders by date, shop, POS order id, and other fields.
+- Once an exact POS order id is known, retrieve the rendered multi-entity detail with `resto order detail --report-id 888002 --pos-order-id <id> --business-date-start <YYYY-MM-DD> --business-date-end <YYYY-MM-DD>`.
+- POS order drilldown requires both business-date options. The inclusive range must be at most 31 days; use the date range that was used to locate the order. The logged-in profile supplies the trusted corporation context.
+- Use `--order-id` only for a known internal order id, and never pass both order identifiers.
+- Do not emulate order detail by selecting many fields from report 3 or by directly calling BO/report-api. The dedicated command preserves server-side auth, report permission, shop scope, flow control, Sentinel, audit, and alerting.
+- The detail response is dynamic JSON produced by report-api order-type templates. Cite the executable main `reportId`, returned `shopId`, order identifier, and the dedicated detail command as evidence.
+
 ## Fast Report Catalog Workflow
 
 Use these shortcuts before slower exploratory analysis when the user asks for report counts, report names, or report identity:
@@ -60,6 +89,7 @@ Always cite the evidence used in the final answer:
 - selected fields and filter fields
 - filters and time range
 - currency, or state that no currency field/value was present
+- for row-pivot queries, cite the dimension and metric relationship from `metricsByDim`
 - `resultId` from `resto query execute`
 - for snapshot transforms, cite the source query `resultId`
 - for `resto analysis topn`, cite the transform command and parameters: transform name, dimension, metric, limit

package/README.md

@@ -36,33 +36,69 @@ Customer-facing installation steps are documented in [`docs/installation.md`](do
 
 ## Auth
 
-Interactive login prompts for the BO URL, corporation id, auth method, and secret values. Passwords and tokens are hidden while you paste them:
+Interactive login prompts for the CLI auth gateway URL, corporation id, auth method, and secret values. Phone dynamic codes and passwords are hidden while you paste them:
 
 ```bash
 resto auth login --interactive
 ```
 
-Token login still requires an explicit corporation id:
+Phone login uses the CLI auth gateway to send a dynamic verification code, then exchanges the phone number and code for a CLI-platform token:
 
 ```bash
 resto auth login \
-  --base-url https://bo.restosuite.cn \
-  --token <token> \
-  --corporation-id 302
+  --base-url https://cli.test.restosuite.ai \
+  --plat cli \
+  --corporation-id 302 \
+  --phone-number <phone-number> \
+  --dynamic-code <verification-code>
 ```
 
-Password login follows the BO login step flow, encrypts the password with BO's RSA-OAEP/SHA-256 public key, and stores the returned token in the same local auth profile:
+Password login follows the auth gateway login step flow, encrypts the password with the gateway-compatible RSA-OAEP/SHA-256 public key, and stores the returned token in the same local auth profile:
 
 ```bash
 resto auth login \
-  --base-url https://bo.restosuite.cn \
+  --base-url https://cli.test.restosuite.ai \
+  --plat cli \
   --username <account> \
   --password <password>
 ```
 
-`--base-url` is the BO gateway host used for login, knowledge manifest sync, and report query execution. `language-code` and `timezone` default to `zh_CN` and `Asia/Shanghai`. If the BO password flow requires an explicit tenant or flow step, pass `--corporation-id`, `--login-flow-code`, and optionally `--login-step-name`.
+`--base-url` is the CLI auth gateway host used for login and token acquisition, and `--plat` defaults to `cli`. Knowledge manifest sync/check, report query execution, and shop filter lookup go through `report-cli-service`; configure `--report-cli-url` or `RESTO_REPORT_CLI_URL` when using a non-default service endpoint. `language-code` and `timezone` default to `zh_CN` and `Asia/Shanghai`. For phone login, `--phone-area-code` defaults to `+86` and `--phone-region` defaults to `CN` when omitted. If the gateway password flow requires an explicit tenant or flow step, pass `--corporation-id`, `--login-flow-code`, and optionally `--login-step-name`.
 For normal email/password login, `--login-flow-code` is not required; it is kept only as a troubleshooting escape hatch.
 
+## Query Backend
+
+`resto query execute` sends query requests to `report-cli-service`:
+
+```bash
+resto query execute --plan ./plan.json
+```
+
+For local report CLI chain testing, start `report-api` and `report-cli-service` locally, then point the CLI at the local service:
+
+```bash
+resto query execute \
+  --plan ./plan.json \
+  --report-cli-url http://127.0.0.1:18081
+```
+
+The same service URL can be selected with an environment variable:
+
+```bash
+RESTO_REPORT_CLI_URL=http://127.0.0.1:18081 \
+resto query execute --plan ./plan.json
+```
+
+`resto shop search` also sends shop filter requests to `report-cli-service`:
+
+```bash
+resto shop search zn线上店铺 \
+  --report-id 888001 \
+  --organization-type 1 \
+  --org-type-list 1,2 \
+  --report-cli-url http://127.0.0.1:18081
+```
+
 ## Fixture Mode
 
 Fixture mode uses bundled local knowledge and does not require remote services or auth:

package/dist/cli.js

@@ -7,6 +7,7 @@ import { createAuthCommand } from "./commands/auth.js";
 import { createFieldCommand } from "./commands/field.js";
 import { createInstallSkillCommand } from "./commands/install-skill.js";
 import { createKnowledgeCommand } from "./commands/knowledge.js";
+import { createOrderCommand } from "./commands/order.js";
 import { configureJsonParseErrors, JsonCommandError } from "./commands/json-command.js";
 import { createPlaybookCommand } from "./commands/playbook.js";
 import { createQueryCommand } from "./commands/query.js";
@@ -49,6 +50,7 @@ The CLI does not infer user intent. Agents choose reports, fields, filters, and
     program.addCommand(createQueryCommand(options));
     program.addCommand(createSnapshotCommand(options));
     program.addCommand(createAnalysisCommand(options));
+    program.addCommand(createOrderCommand(options));
     program.addCommand(createShopCommand(options));
     program.addCommand(createInstallSkillCommand(options));
     program.addCommand(createUninstallCommand(options));