---
name: shb-paas
version: "1.5.0"
description: "当用户需要查看或修改 PaaS/PASS 表单/应用(自定义业务模块/菜单,如\"寄修\"等非工单/客户/产品的模块,也包括仍在用\"应用/应用数据\"这类说法的场景)、表单数据、单据、记录数、字段、流程时触发;也包括问某个业务名称(不属于工单/客户/产品)的\"数据/单据/记录有多少条\"。通过 shb-cli 列出全部表单、按名称定位表单,读取表单字段、表单数据量,表单搜索/创建,流程定义/日志/按钮/版本,以及字段保存、发起流程、继续流程、催办、撤回、会签、批量转交。"
metadata:
  requires:
    bins: ["shb-cli"]
  cliHelp: "shb-cli paas --help"
---

# paas (v1)

**CRITICAL — 开始前 MUST 先加载 [`../shb-shared/SKILL.md`](../shb-shared/SKILL.md),其中包含 profile 初始化、环境选择、OAuth2 登录、token 导入、租户切换、安全规则。所有 PaaS 命令都依赖 `shb-shared` 描述的认证状态。**

## Core Concepts

- **表单(PaaS 业务模块/页面)**:PaaS 里一个自定义的业务模块/页面,对应导航里的一个菜单入口(例如"寄修")——类似"工单"这样的模块,只是工单/客户/产品是内置模块、各有独立技能,而"寄修"这类是 PaaS 自定义模块、走本技能。**本技能只处理 PaaS 自定义表单/模块**;用户说的名字若不属于工单/客户/产品等内置模块,就当作 PaaS 表单来定位。**没有单独的"模板"概念——一切都是表单**;表单的 id 在命令参数里叫 `template-biz-id` / `form-template-id`(即 `paas app forms` 结果里的 `bizId`),只是参数名。`paas template fields --template-biz-id <bizId>` 取表单字段,`paas form search/get`(`content-biz-id`)取表单下的一条条数据记录。
- **bizId / appId**:`paas app forms` 结果里得到的两个**内部标识**——`bizId` 即表单 id(传参名 templateBizId),`appId` 供 `paas flow` / `paas template create` 等命令的必填参数使用;都不是面向用户的概念,**字段名和 id 值在回复中一律不暴露**,指代表单只用表单显示名。
- **Field(表单字段)**:表单的字段定义,既包含表单自身字段,也包含流程节点上的字段。
- **Flow(流程)**:表单对应的流程定义,版本通过 `flow-version` 管理。
- **数据记录**:表单下的一条内容记录,标识 `content-biz-id`。

## Resource Relationships

```
表单 (template-biz-id)   ← 一个 PaaS 业务模块/页面;template-biz-id 只是表单 id 的参数名
├── Field 表单字段 (自身字段 / 流程节点字段)
├── Flow 流程 (form-template-id)
│   ├── Version (flow-version)
│   ├── Log (content-biz-id)
│   └── Buttons
└── 数据记录 (content-biz-id)

# appId 为定位表单时得到的内部标识,供 paas flow / template create 等命令使用。
```

## Important Notes

### 面向用户的输出措辞（禁止回显接口字段名与内部机制）

**CRITICAL** — 以下内容**只供你内部使用，禁止出现在给用户的回复里**：

1. **接口/JSON 字段名**：`templateBizId`、`appId`、`bizId`、`contentBizId`、`totalElements`、`pageNum` 等，一律转成自然语言。例：「totalElements 为 42」→「共 42 条数据」。其中表单的 `bizId`(templateBizId) 与 `appId` 不仅字段名不出现，**id 的值也不给用户展示**，指代表单只用表单显示名。
2. **命令与一切技术细节**：任何 shb-cli 命令、子命令、flag、参数名，以及取数过程（按名定位、分页、`--all` 全量拉取、字段裁剪、截断重试）都是后台实现细节，**回复里绝不出现，也不要解释你用了什么命令/参数、怎么取的数**，换种说法也不行。直接给结果。
3. **自定义字段的显示**：表单字段的 key 是 `fieldName`（如 `field_xxx`），**绝不能直接拿这个 key 显示给用户**。用 `--format-data` 输出时 CLI 已按字段定义转成中文字段名和可读值；自行拼装时先 `paas template fields --template-biz-id <bizId>` 取 `displayName`，给用户看「中文字段名：值」，匹配不到的宁可不展示。

正例：「远程寄修最近 7 天共 42 条数据，其中……」。此规则适用于所有 paas 子命令。

### 复用已知 ID（禁止重复定位/搜索）

**CRITICAL** — 只要本轮对话已经定位过某表单的 `bizId`(templateBizId) / `appId`，或某条记录的 `content-biz-id`，后续再用到时**必须从已有结果中直接复用**，禁止为「重新拿 id」再跑 `paas app forms` / `paas form search`。只有本轮从未出现过该表单/记录时才允许发起新的定位或搜索。

### 命令分层

- **`shb-cli paas <resource> <method>`** —— 业务操作的唯一入口(查询、写操作都走这里)。
- 一律使用 `shb-cli paas ...`;**不要使用 `shb-cli service ...`(含 `service paas` / `service example`)** 调用任何能力。

### 输出格式

所有命令支持全局 `--output` / `-o` 标志：

```bash
shb-cli paas form search --template-biz-id <bizId> -o json          # 默认，投影后的 JSON（含 page.totalElements）
shb-cli paas form search --template-biz-id <bizId> -o raw           # 紧凑单行 JSON
shb-cli paas form search --template-biz-id <bizId> -o table         # 投影后的表格
```

### PaaS 表单数据只读链路

用户询问某个 PaaS 表单里的数据或记录数量时,先**按表单/菜单名称定位**,再取数,优先按这个顺序执行:

```bash
shb-cli paas app forms --name <form-name>
shb-cli paas form search --template-biz-id <templateBizId> --page-size 10
```

要继续看某条记录的单条详情时,加载 [`references/shb-paas-detail.md`](references/shb-paas-detail.md) 走 `form get` 详情链路。

- `templateBizId` 来自 `paas app forms` 结果里的 `bizId`(bizId 即表单 id)。
- **只问数量/求分布 → 只取计数,不拉明细**:`--page-size 1` 读 `page.totalElements`(输出极小,零截断风险);分布则逐个取值各查一次汇总,详见 [`references/shb-paas-search.md`](references/shb-paas-search.md)「统计 / 聚合计数」。
- `form search` 始终投影成少量列(投影是默认,无需格式化 flag),用 `--fields` 选列;没有裸出整表的开关。
- **过滤失效即停手**:加筛选后总数不变 = 条件没生效,立即停止,不要换格式反复重试;详见 search 文档。
- search 结果里每条记录的 `bizId` / `内容ID` 即单条详情的 `content-biz-id`(与表单 id 不同层级,详情操作见 detail 文档)。
- 复杂高级筛选(含按创建时间范围)用 `paas form search --data '<json>'`,写法见 search 文档。

### 写操作安全

- 写操作（`form create/save/start-content/finish-content/delete`、`template create/delete/add-fields`、`flow start/deploy/approve/...`）执行前确认用户明确要求，详见下方权限/安全表。
- 高风险写操作先用 `--dry-run` 预演，确认无误后再 `--confirm-write`。
- **使用优先级：快捷 flags ＞ `--data` ＞ `--file`**——常规字段用快捷 flags；复杂/完整 JSON 用 `--data` 内联；`--file` 仅本地已有现成 JSON 文件时用。

## API Resources

**CRITICAL — 执行任何 PaaS 子命令前，必须先加载对应 reference 文档，再执行命令：**

| 操作 | 必须先加载 |
|------|-----------|
| 查询 PaaS 表单数据且已知表单 id（`paas form search`） | [`references/shb-paas-search.md`](references/shb-paas-search.md) |
| 查询 PaaS 表单但用户只给表单名称 / 描述 / 业务语义 | 先加载 [`references/shb-paas-form.md`](references/shb-paas-form.md) 用 `paas app forms --name` 定位表单，再加载 [`references/shb-paas-search.md`](references/shb-paas-search.md) |
| 查看 PaaS 详情（数据记录、流程按钮、日志） | [`references/shb-paas-detail.md`](references/shb-paas-detail.md) |
| 列出全部表单 / 按名定位表单 | [`references/shb-paas-form.md`](references/shb-paas-form.md) |
| 查询表单有哪些字段 / 字段类型(`formType`)/ 字段 key / 是否必填 / 当前节点可填字段判定 | [`references/shb-paas-fields.md`](references/shb-paas-fields.md) |
| 表单基本信息 / 全量表单选项列表(`template get` / `all-list`) | [`references/shb-paas-form.md`](references/shb-paas-form.md) |
| 查询 / 操作流程 | [`references/shb-paas-flow.md`](references/shb-paas-flow.md) |
| 编辑（更新/修改/保存)已有数据、改表单字段定义 | [`references/shb-paas-update.md`](references/shb-paas-update.md) |
| 删除任何东西（数据记录、表单、流程版本） | [`references/shb-paas-delete.md`](references/shb-paas-delete.md) |
| 创建表单（新业务模块）、字段、数据记录与流程发起链路 | [`references/shb-paas-create.md`](references/shb-paas-create.md) |

同一会话中每个 reference 只需加载一次。所有业务操作都走 `shb-cli paas <resource> <method> [flags]` 这一个入口。

## 权限与安全

下列写操作必须先和用户确认:

| 类型 | 命令 |
|------|------|
| 表单(结构) | `paas template create` / `delete` |
| 表单字段定义 | `paas template add-fields` / `save-fields` |
| 流程 | `paas flow start` / `deploy` / `redeploy` / `approve` / `pause` / `resume` / `urge` / `back-to-me` / `countersign` / `batch-transfer` |
| 表单 | `paas form create` / `save` / `start-content` / `finish-content` / `delete` |

PaaS 表单/流程最小真实链路:

```bash
shb-cli config
shb-cli paas template add-fields --data '<json>' --dry-run
shb-cli paas template add-fields --data '<json>' --confirm-write
shb-cli paas form create --data '<json>' --confirm-write
shb-cli paas form start-content --data '<json>' --confirm-write
shb-cli paas flow buttons --content-biz-id <content-biz-id>
shb-cli paas form finish-content --data '<json>' --confirm-write
shb-cli paas flow log --content-biz-id <content-biz-id>
```

真实写入前必须核对 `shb-cli config` 输出里的租户和用户是否是用户指定目标。

## 排错

- 大多数 4xx 来自 payload 字段缺失或格式错,先用 `--dry-run` 预演比对字段。
- 401 / `token is empty` / `valid: false` → 回到 `shb-shared` 技能重新认证。
- 流程相关错误如 `state invalid`,先用 `paas template check-state --template-biz-id <id>` 与 `paas flow version list` 排查表单/版本状态。

## References

- [`references/shb-paas-form.md`](references/shb-paas-form.md) —— 列出全部表单、按表单/菜单名定位
- [`references/shb-paas-search.md`](references/shb-paas-search.md) —— 表单数据查询(快捷 flag / --data / 高级条件 / --all)
- [`references/shb-paas-detail.md`](references/shb-paas-detail.md) —— 表单内容、流程按钮/日志详情
- [`references/shb-paas-fields.md`](references/shb-paas-fields.md) —— 表单字段定义:字段类型(formType)目录、字段元数据、value 传参格式、当前节点可填字段判定
- 字段定义写操作(加字段 `add-fields` / 全量替换 `save-fields`)见 fields.md;建表单 / 状态校验见 create.md;删除表单见 delete.md
- [`references/shb-paas-flow.md`](references/shb-paas-flow.md) —— 流程定义/日志/按钮/版本/部署/审批/启停
- [`references/shb-paas-update.md`](references/shb-paas-update.md) —— 编辑(更新):记录字段值/子表行/附件、表单字段定义
- [`references/shb-paas-delete.md`](references/shb-paas-delete.md) —— 删除:数据记录/表单/流程版本(destructive)
- [`references/shb-paas-create.md`](references/shb-paas-create.md) —— 字段、表单内容与流程发起的创建链路