@restoai/resto-datacli 0.1.12 → 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
@@ -38,13 +38,31 @@ At the start of a Resto data task or a new Agent session, check tool and knowled
 ## 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:
@@ -71,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));