weaver-work-cli 0.1.24 → 0.1.25

package/skills/weaver-e10-builder/references/report/report-permission-guide.md

@@ -0,0 +1,365 @@
+# 报表使用权限 · 完整 API 指南
+
+> **UI 入口**：应用报表列表 → 报表卡片「…」→ **报表权限**
+> **弹窗结构**：顶层 **使用范围** / **禁用范围**；各含子 Tab **通用** / **矩阵相关**
+> **源码依据**：`EdcDataPermissionController.java`、`EdcReportMatrixRight.java`、`DataRightType.java`、`EdcReportDevAnalysisController.java`（weaver-edcreportd / weaver-common-edc）
+> **组件契约**：与平台 **shareBrowser** 一致（同动作流 SendMessage「提醒对象」枚举，见 e10-cli `formula_service.py`）
+> **设计区保护**：权限仅走 `savePermissions` / `matrix/save`，**禁止**为改权限调用 `saveReportDevInfo`（见 `safe-partial-save-guide.md`）
+
+---
+
+## 一、UI 结构与 API 映射
+
+```mermaid
+flowchart TB
+ subgraph dialog["报表权限弹窗"]
+ U["使用范围 Tab"]
+ D["禁用范围 Tab"]
+ end
+ subgraph sub["各 Tab 下"]
+ G["通用 — shareBrowser 对象列表"]
+ M["矩阵相关 — 引用矩阵表 / e-Builder 表单"]
+ end
+ U --> G
+ U --> M
+ D --> G
+ D --> M
+ G --> API1["table/list/new + savePermissions.viewRight / disableRight"]
+ M --> API2["matrix/list + savePermissions.viewMatrixRight / matrix/save"]
+```
+
+| UI 区域 | 读接口 | 写接口 | 说明 |
+|---------|--------|--------|------|
+| 使用范围 · 通用 | `table/list/new` + `permissionType: 1` | `savePermissions` → `viewRight` | 人员/部门/…/所有人 |
+| 使用范围 · 矩阵 | `matrix/list` + `type: "1"` | `savePermissions` → `viewMatrixRight` | 保存前服务端会把 `id` 改为 `tmp_*` |
+| 禁用范围 · 通用 | `table/list/new` + `permissionType: -1` | `savePermissions` → `disableRight` | 命中则**否决**查看权 |
+| 禁用范围 · 矩阵 | `matrix/list` + `type: "-1"` | `matrix/save`（`rightsType: "-1"`） | **注意**：`savePermissions` 只处理 `viewMatrixRight`，禁用矩阵需单独 `matrix/save` |
+
+**运行时判定**（`EdcReportDevAnalysisController`）：
+
+```
+可查看 = (后台查看 ∨ 前台查看 ∨ 使用矩阵 ∨ 使用权限组)
+ ∧ ¬(禁用通用 ∨ 禁用矩阵 ∨ 禁用权限组)
+```
+
+---
+
+## 二、DataRightType 与 permissionType
+
+| permissionType | 含义 | UI Tab | permissionId |
+|----------------|------|--------|--------------|
+| `1` | 后台查看（使用范围） | 使用范围 · 通用/矩阵 | `report_view` |
+| `-1` | 后台禁用（禁用范围） | 禁用范围 · 通用 | `report_view` |
+| `2` | 前台查看 | （部分环境/前台入口） | `report_view` |
+| `-2` | 前台禁用 | | `report_view` |
+| `11`–`17` | 按钮级（导出 Excel/PDF/打印/快照等） | 非本弹窗主体 | `report_view` |
+
+矩阵 `rightsType` 与上表 **code 字符串**一致：`"1"`=使用，`"-1"`=禁用。
+
+---
+
+## 三、通用 Tab · 九种对象类型（shareBrowser）
+
+设计器下拉与 API 字段 **`objType`** 对照（**人员**在 API 中为 `resource`，不是 `user`）：
+
+| UI 名称 | objType | obj_id 字段 | _entityType | targetType | targetId | 备注 |
+|---------|---------|-------------|-------------|------------|----------|------|
+| 人员 | `resource` | `obj_id` | `resource` | `1` | 人员 ID | 可加 `user_type`（1 当前人员…） |
+| 部门 | `department` | `obj_id_department` | `dept` | `2` | 部门 ID | Live `本地工作目录` |
+| 分部 | `subcompany` | `obj_id_subcompany` | `subcompany` | `4` | 分部 ID | 可加 `department_attribute` |
+| 角色 | `role` | `obj_id_role` | `role` | **`10`** | 角色 ID | 可加 `role_level`（0 总部/1 分部/2 部门） |
+| 群组 | `channel` | `obj_id_channel` | `channel` | **`14`** | 群组 ID | UI 称「群组」，浏览器为 `hrm/.../channel`；非 `group`/`targetType:5` |
+| 群组 | ~~`group`~~ | ~~`obj_id_group`~~ | — | ~~5~~ | — | **勿用**：`5` 会被存成分部 |
+| 岗位 | `position` | `obj_id_position` | `position` | `6` | 岗位 ID | 可加 `position_level` 等 |
+| 所有人 | `all` | （无） | `all` | `11` | `0` | Live copy 脚本 |
+| 外部联系人 | `external` | `obj_id_external` | `external` | `7` | 外部人 ID | 须 browser 查真实 ID |
+| 所有外部人 | `allExternal` | （无） | `allExternal` | `12` | `0` | 无对象选择框 |
+
+> **targetType 判断依据**（`edc_report_ph_report_view` 的 `org_config.typeEnum`，weaver-edcreportd SQL）：
+> 人员 `1|17` · 部门 `2|3|4|…` · 分部 `5|6|7|…` · **角色 `10`** · **群组(channel) `14|1411`** · 岗位 `12|13|…` · 外部 `110` · 所有人 `11`
+> 写入前务必 `table/list/new` 回读；**禁止**把角色写成 `targetType:3`、群组写成 `targetType:5`（会分别落库为部门/分部）。
+> **安全级别**：通用项均可带 `seclevel: {"min": -999, "max": 999}`（UI「安全级别」列）。
+
+### 3.1 读列表
+
+```http
+POST /api/bs/edc/report/permission/table/list/new
+Content-Type: application/json
+
+{
+ "permissionId": "report_view",
+ "id": "<reportId>",
+ "current": 1,
+ "pageSize": 50,
+ "permissionType": 1,
+ "params": { "appId": "<appId>" }
+}
+```
+
+- **使用范围**：`permissionType: 1`
+- **禁用范围**：`permissionType: -1`
+- 返回列含 `objType`、`obj_id`/`obj_id_span`、**安全级别** `level`
+
+### 3.2 写 — savePermissions（全量替换）
+
+`savePermissions` 对每张报表 **先删后增**（view + disable 通用项；使用矩阵 rightsType=1 软删后重建）：
+
+```json
+{
+ "<reportId>": {
+ "viewRight": [ /* permissionType: 1 的 shareBrowser 行 */ ],
+ "disableRight": [ /* permissionType: -1 的 shareBrowser 行 */ ],
+ "viewMatrixRight": [ /* 使用范围 · 矩阵行，见 §四 */ ]
+ }
+}
+```
+
+**shareBrowser 行公共字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `sourceId` | 报表 ID（字符串） |
+| `permissionId` | 固定 `"report_view"` |
+| `permissionType` | 使用 `1`，禁用 `-1` |
+| `sourceType` | `1` |
+| `targetType` / `targetId` | 见上表 |
+| `objType` / `objTypeSpan` | 类型枚举与 UI 文案 |
+| `_entityType` | 前端实体类型 |
+| `obj_id_*` | 对象展示数组（含 id/name/content） |
+| `obj_id_span` / `objIdList` / `content` / `name` | 列表展示 |
+| `seclevel` | 安全级别范围 |
+| `shareKey` | 新建可用 `tmp_<type>_<id>_<随机>` |
+
+### 3.3 示例
+
+**所有人（使用范围）** — 见 `e10-cli report lifecycle` → `everyoneViewRight()`：
+
+```json
+{
+ "sourceId": "<reportId>",
+ "permissionId": "report_view",
+ "permissionType": 1,
+ "targetType": 11,
+ "targetId": 0,
+ "sourceType": 1,
+ "objType": "all",
+ "objTypeSpan": "所有人",
+ "_entityType": "all",
+ "obj_id_all": [{ "content": "所有人", "icon": "Icon-all02", "id": "0" }],
+ "obj_id_span": "所有人",
+ "objIdList": ["所有人"],
+ "seclevel": { "min": -999, "max": 999 },
+ "shareKey": "tmp_all_0_abc123"
+}
+```
+
+**部门（使用范围）** — 见 `本地工作目录`：
+
+```json
+{
+ "sourceId": "<reportId>",
+ "permissionId": "report_view",
+ "permissionType": 1,
+ "targetType": 2,
+ "targetId": "<deptId>",
+ "sourceType": 1,
+ "objType": "department",
+ "objTypeSpan": "部门",
+ "_entityType": "dept",
+ "obj_id_department": [{ "id": "<deptId>", "name": "总经办", "content": "总经办", "title": "总经办" }],
+ "obj_id_span": "总经办",
+ "objIdList": ["总经办"],
+ "seclevel": { "min": -999, "max": 999 },
+ "shareKey": "tmp_dept_<deptId>_abc123"
+}
+```
+
+**禁用某部门** — 与上相同结构，仅改 `permissionType: -1`，放入 `disableRight` 数组。
+
+**人员（使用范围）** — `objType: "resource"`，`targetType: 1`，`obj_id` 为人员对象数组。
+
+### 3.4 对象 ID 查询（browser）
+
+| UI 对象 | 推荐 browser | 说明 |
+|---------|--------------|------|
+| 人员 | `POST /api/edc/report/common/browser/complete/resource` | 报表权限弹窗内 browser |
+| 部门 | `POST /api/workflow/pathdef/common/browser/complete/department` | body 含 `searchValue` |
+| 角色 | `POST /api/hrm/common/browser/complete/role` | body 含 `searchValue` |
+| **群组** | **`POST /api/hrm/common/browser/data/channel`** | **勿用** `/.../group`（返回 browser not found）；UI 称群组，API 类型为 `channel` |
+| 分部/岗位 | 设计器 shareBrowser 实际请求为准 | 报表弹窗 browser 常仅注册 resource/role/department/subcompany |
+
+**Live 示例**（eteams · 进销存应用）：
+
+| 对象 | 搜索名 | ID |
+|------|--------|-----|
+| 角色 eb分权管理员 | `complete/role` | `845885352284553217` |
+| 群组 测试-zc0813 | `data/channel` + keywords `zc0813` | `1303036100793573378` |
+
+---
+
+## 四、矩阵相关 Tab
+
+UI：**引用矩阵表**（矩阵表 / e-Builder 表单）→ **条件** → **取值字段** → 添加 → 使用列表。
+
+实体 `EdcReportMatrixRight`（表 `edc_report_matrix_right`）：
+
+| 字段 | 说明 |
+|------|------|
+| `selectedType` | 组织/矩阵类型，传入 `OrgType.valueOf(...)`（如矩阵表、e-Builder 表单，**实际请求为准**） |
+| `dataId` | JSON 字符串，矩阵/表单引用，如 `[{"id":"<matrixOrFormId>","name":"..."}]` |
+| `matrixConditionData` | 矩阵值**条件**（平台矩阵条件 DSL，JSON 字符串） |
+| `matrixValueRelation` | 矩阵值**关系/取值字段**映射（JSON 字符串） |
+| `targetId` | 报表 ID |
+| `rightsType` | `"1"` 使用范围矩阵；`"-1"` 禁用范围矩阵 |
+| `rightsName` | 展示名称（可选） |
+
+校验走 `EBMatrixPermissionDubboService.checkMatrixPermission`。
+
+### 4.1 读矩阵列表
+
+```http
+POST /api/bs/edc/report/permission/matrix/list
+
+{ "target": "<reportId>", "type": "1" }
+```
+
+- 使用范围：`type: "1"`
+- 禁用范围：`type: "-1"`
+
+### 4.2 写 — 使用范围矩阵（推荐并入 savePermissions）
+
+```json
+{
+ "<reportId>": {
+ "viewRight": [],
+ "disableRight": [],
+ "viewMatrixRight": [
+ {
+ "id": "tmp_matrix_001",
+ "targetId": "<reportId>",
+ "selectedType": "<OrgType枚举名>",
+ "dataId": "[{\"id\":\"<matrixId>\",\"name\":\"矩阵表名\"}]",
+ "matrixConditionData": "<条件JSON字符串>",
+ "matrixValueRelation": "<取值字段JSON字符串>",
+ "rightsType": "1",
+ "rightsName": "矩阵权限说明"
+ }
+ ]
+ }
+}
+```
+
+服务端保存前会将 `id` 前缀改为 `tmp_` 再插入。
+
+### 4.3 写 — 禁用范围矩阵（单独 matrix/save）
+
+`savePermissions` **不**处理禁用矩阵；需：
+
+```http
+POST /api/bs/edc/report/permission/matrix/save
+Content-Type: application/json
+
+[
+ {
+ "id": "tmp_disable_matrix_001",
+ "targetId": "<reportId>",
+ "selectedType": "<OrgType>",
+ "dataId": "[{...}]",
+ "matrixConditionData": "...",
+ "matrixValueRelation": "...",
+ "rightsType": "-1"
+ }
+]
+```
+
+> **矩阵字段 JSON 结构**因「矩阵表 vs e-Builder 表单」及租户配置而异，**必须以设计器 Network 实际请求为准**；Skill 禁止臆造 `matrixConditionData` / `matrixValueRelation` 内部键名。
+
+---
+
+## 五、权限组（shareGroup，补充）
+
+`table/list/new` 在传入 `params.appId` 时，会 **append** 应用级权限组行（`objType: "shareGroup"`）。
+源码 `EdcReportGroupRightServiceImpl.getGroupRights` 注明：**禁用范围权限组回显暂未支持**（permissionType ≠ 1 时返回空）。
+
+---
+
+## 六、脚本与客户端
+
+| 能力 | Node | Python |
+|------|------|--------|
+| 复制 + 所有人 + 加菜单 | `report_lifecycle.js` | `copy_sheet` / `save_permissions` / `add_report_to_menu` |
+| **任意使用范围** | **`set_report_view_scope.js`** | `build_share_entry` + `save_permissions` |
+| 存为新版本 | `save_as_version.js`（`--list-only` 只读） | `save_as_version()` |
+| 构建 share 行 | — | `ReportApiClient.build_share_entry()`（`group`→`channel`） |
+| 列表/矩阵读 | — | `list_permission_table` / `list_matrix_rights` |
+| **矩阵增删 CLI** | **`report_list_ops.js` / `e10-cli report scope matrix`** | `delete_use_matrix_by_replace` / `soft_delete_matrix_row` / `save_matrix_rights` |
+
+**Node — 矩阵列表 / 添加 / 删除**：
+
+```bash
+e10-cli report scope matrix list --app-id <appId> --report-id <id> --type 1
+e10-cli report scope matrix save --app-id <appId> --report-id <id> --file matrix-row.json --type 1
+e10-cli report scope matrix delete --app-id <appId> --report-id <id> --matrix-id <mid> --type 1
+```
+
+> 使用矩阵删除走 `savePermissions` 全量替换剩余行；禁用矩阵删除走 `matrix/save` + `deleteType:1`。条件 DSL 须实际请求，见 §4.2/4.3。
+> 列表页分组/移动/转移见 **`report-list-page-ops-guide.md`**。
+
+**Node — 角色 + 群组使用范围**：
+
+```bash
+node e10-cli report scope set \
+ --host https://<your-e10-host> \
+ --app-id <your-app-id> \
+ --report-id 1310967397636390912 \
+ --scope "role:eb分权管理员,channel:测试-zc0813"
+```
+
+**Python 示例**：
+
+```python
+from report_api_client import ReportApiClient
+
+client = ReportApiClient(...)
+rid = "1310967397636390912"
+client.save_permissions(rid, {
+ "viewRight": [client.build_share_entry("all", report_id=rid)],
+ "disableRight": [client.build_share_entry("department", "123", "总经办", report_id=rid, permission_type=-1)],
+ "viewMatrixRight": [],
+})
+client.list_permission_table(rid, "report_view", permission_type=-1) # 回读禁用范围
+```
+
+---
+
+## 七、验证清单
+
+1. **使用范围通用**：`table/list/new` + `permissionType:1` 行数与 objType 正确
+2. **禁用范围通用**：`permissionType:-1` 能回读
+3. **使用矩阵**：`matrix/list` + `type:"1"`
+4. **禁用矩阵**：`matrix/list` + `type:"-1"`（若 UI 已配置）
+5. **运行时**：目标用户在「使用」内且不在「禁用」内时可打开分析页 `/api/bs/edc/report/analysis/...`
+6. **雪花 ID**：reportId / targetId 全程字符串化，见 `snowflake-id-precision-guide.md`
+
+---
+
+## 八、常见错误
+
+| 现象 | 原因 | 处理 |
+|------|------|------|
+| 只写了 `objType: "user"` | 设计器不认 | 改为 `objType: "resource"` |
+| 禁用矩阵保存后丢失 | 只调了 savePermissions | 禁用矩阵用 `matrix/save` + `rightsType:"-1"` |
+| 角色写成 `targetType:3` | 落库成**部门** | 角色 = **`10`** |
+| 群组写成 `targetType:5` 或 `objType:group` | 落库成**分部** | 群组 = **`channel` + targetType `14`** |
+| 搜群组用 `/browser/.../group` | browser not found | 改用 **`/hrm/.../data/channel`** |
+| 部门 targetType 写成 3 | 与角色混淆 | 部门 = **`2`** |
+| 权限 ID 末位漂移 | JS JSON.parse | 用 `json_snowflake.js` / `json_snowflake.py` |
+| savePermissions 后旧行还在 | 误解为增量 | 接口为**全量替换**，需提交完整 viewRight/disableRight |
+
+---
+
+## 关联文档
+
+- `report-lifecycle-api-guide.md` — 复制/菜单/删除与权限入口总览
+- `snowflake-id-precision-guide.md` — ID 精度
+- `api-auth-headers.md` — 鉴权三项

package/skills/weaver-e10-builder/references/report/report-requirement-analysis-template.md

@@ -0,0 +1,202 @@
+# 报表需求分析交付规范（仅用户要「分析」时必做）
+
+> **冷启动禁止通读（纯搭表）**：见 `cold-start-scan-guide.md`。
+> **适用范围**：凡用户**明确要求**「需求分析」「报表需求分析」「根据效果图/截图分析」「报表搭建指导 / 图示」时，按本规范输出完整分析 + **报表搭建图示**。
+> **不适用**：用户只要「搭建 / 创建报表 / 生成报表」—— **跳过本模板**，直接走 `api-report-build-fast-path.md` + `report-delivery-contract.md` **模式 A**（交设计器地址即结束）。
+> **HTML 手册**：非强制；仅用户点名要 HTML/指导文档时才 `build_guide_html.py`。
+>
+> **与能力一/二关系**：本规范是能力二（搭建配置指导）在「分析」意图下的输出格式；**禁止**在纯搭表任务中先强制跑本规范再落库。
+
+---
+
+## 一、交付清单（缺一不可）
+
+每次报表需求分析必须包含以下 **8 个章节**（顺序固定）：
+
+| # | 章节 | 必含要素 |
+|---|------|----------|
+| 1 | 报表定位 | 名称、业务目的、报表类型（LIST/GROUP/COUNT…）、行基格说明 |
+| 2 | 查询条件 | 条件名、字段类型、默认值、关系运算符、绑定数据集 |
+| 3 | 数据集与数据集过滤 | 物理表/逻辑源、datasetFilter（queryInfoSave）规则 |
+| 4 | 页面与网格布局图示 | ASCII 或 Mermaid：R1 分组行、R2 列名、R3 配置基格 |
+| 5 | 父格与扩展方向图示 | 行基格、左父格链、公式格「不扩展」 |
+| 6 | **列级配置总表** | 见 §二（每列 8 项） |
+| 7 | 公式列说明 | 公式、除零规则、显示格式（百分比等） |
+| 8 | 待业务确认项 | 口径歧义、缺字段、同比/累计定义 |
+
+**禁止**：只写业务口径文字、不给搭建图示；只给列名列表、不写父格/筛选/汇总。
+
+---
+
+## 二、列级配置总表（核心）
+
+对 **每一个数据列/公式列**（含行基格 A 列），必须填下表一行：
+
+| 列 | 列名 | 字段/公式 | **字段类型** | **数据集** | **父格** | **扩展方向** | **显示方式** | **汇总方式** | **父格筛选** | **自定义筛选** |
+|:--:|---|---|:---:|:---:|---|:---:|:---:|:---:|---|---|
+| A | 大区/专项 | 大区/专项 | Text/Select | 合同表 | **无（行基格）** | 纵向 | 列表/分组 | — | — | — |
+| B | 当月新客户合同数 | 合同号 | Text | 合同表 | A3 | 纵向 | 汇总 | COUNT DISTINCT | — | 业绩年月=当月 AND 合同种类=新签 |
+| E | 当月伙伴签占比 | `IF(B3=0,"--",D3/B3)` | Formula | — | A3 | **不扩展** | 百分比 | — | — | — |
+
+**字段类型** 枚举（写清物理类型 + 平台 componentKey 如有）：
+
+`Text` · `Number` · `Money` · `Date`/`yearmonth` · `Select` · `Employee` · `Department` · `EBuilder` · `Formula` · `Const`
+
+**父格**：单数据集且无指定计算时填 **默认**（见 `datasource-selection-and-parent-filter-guide.md` §〇）；勿臆造自定义坐标链。
+
+
+**显示方式**：`列表` · `分组` · `排列` · `汇总` · `隐藏`
+
+**汇总方式**：`—` · `sum` · `count` · `distinctcount` · `avg` · `max` · `min`
+
+**父格筛选**（leftFilterField / 左父格筛选）：跨数据集时**仅连续同源区域的入口列**必填，同区域其余列填 `-`（见 `datasource-selection-and-parent-filter-guide.md` §二）。格式示例：
+
+`合同.销售经理 = EBU团队.责任人`（fieldKey 见 cross-dataset-filter-guide.md）
+
+**数据集选用**：先核主表是否已有用户/部门等展示字段；有则**不要**为显示再挂人员表/部门表（`datasource-selection-and-parent-filter-guide.md` §一）。
+**自定义筛选**（customFilterField / 单元格级）：列口径差异写在此，示例：
+
+`业绩年月=当月` · `合同种类=新签合同` · `签约渠道=伙伴签` · `客户名称 非空`
+
+---
+
+## 三、数据集过滤（datasetFilter）专表
+
+与「列级自定义筛选」区分：**datasetFilter** 作用于整个数据集实例（设计器左侧数据集 → 筛选条件 / queryInfoSave）。
+
+| 数据集 | 逻辑关系 | 字段 | 运算符(func) | 值 | 说明 |
+|---|---|---|:---:|---|---|
+| 直销合同业绩表 | AND | 核算机构 | NotContain/uncontains | 亘岩 | 剔除专项机构 |
+| 直销合同业绩表 | AND | 核算机构 | NotContain | 契约锁 | … |
+| EBU团队 | AND | 负责人 | eq | `{userid}` | 行级权限（若需要） |
+
+> API 写入见 `dataset-query-filter-guide.md`；**禁止**与 saveQueryItem（高级搜索）混用。
+
+---
+
+## 四、查询条件专表
+
+| 显示名 | 绑定字段 | **字段类型** | 关系 | 默认值 | **显示方式**（必填） | 备注 |
+|---|---|:---:|:---:|---|:---:|---|
+| 年份 | 业绩年月.年 | Number/Select | Equals | `{thisyear}` | **高级搜索**（默认） | 驱动 R1 动态标题 |
+| 月份 | 业绩年月.月 | Select | Equals | `{thismonth}` | **高级搜索**（默认） | 01–12 |
+
+> **显示方式**：设计器必填；默认「高级搜索」（`showWhere: advancedSearch`）；用户指定「筛选」时写筛选（`filter`）。**不可留空**。见 `query-condition-api-guide.md` §2.1。
+> 日期区间 21 项、asNameIndex 等见同文档。
+
+---
+
+## 五、搭建布局图示（必须输出 ≥4 张）
+
+### 5.1 页面整体布局
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│ {报表名称} │
+├─────────────────────────────────────────────────────────────┤
+│ [查询条件区] [搜索] [重置] [导出] [打印] [更多] │
+├─────────────────────────────────────────────────────────────┤
+│ 报表 Sheet 工作区 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5.2 网格与表头合并（R1/R2/R3）
+
+```text
+ A B C …
+R1 ┌─────────┬──────────────── 分组标题1 ────────────────┬──────── 分组标题2 ────────┐
+R2 │ 列名A │ 列名B │ 列名C │ …
+R3 │ ★行基格 │ 指标B │ 指标C │ … ← 数据区起点，行基格纵向扩展
+ │ 维度值1 │ … │ … │
+ │ 维度值2 │ … │ … │
+```
+
+- 标注 **★ 行基格** 坐标（如 A3）
+- 标注 R1 合并范围与背景色（若效果图有分区色）
+- R1 动态标题规则：`{查询年}-{查询月}` + 固定后缀
+
+### 5.3 父格与扩展方向（Mermaid 或 ASCII）
+
+```mermaid
+flowchart TB
+ A3["A3 行基格<br/>纵向扩展"]
+ B3["B3 指标列<br/>左父格→A3<br/>纵向+汇总"]
+ E3["E3 公式列<br/>左父格→A3<br/>不扩展"]
+ A3 --> B3
+ A3 --> E3
+```
+
+### 5.4 数据集挂载关系
+
+```mermaid
+flowchart LR
+ Q[查询条件] --> DS1[(数据集1)]
+ Q --> DS2[(数据集2)]
+ DS1 --> C1[列 B~J]
+ DS2 --> C2[列 K~S]
+ DS2 -.leftFilterField.-> DS1
+```
+
+### 5.5 列级筛选叠加示意（可选，多口径报表建议画）
+
+```text
+ [datasetFilter 全局] + [列 customFilter 时间/新客/伙伴] + [父格筛选 跨表关联]
+```
+
+### 5.6 Sheet1 式单元格配置示例（R3 任选一列展示 6 项）
+
+```text
+┌──────────────────────────────────────────┐
+│ D3 当前月份新客户伙伴签合同数量 │
+├──────────────────────────────────────────┤
+│ 字段： 合同业绩表.合同号 │
+│ 父格： A3（大区/专项） │
+│ 显示方式： 汇总 │
+│ 扩展方向： 纵向扩展 │
+│ 父格筛选： -（同数据集无） │
+│ 自定义筛选：业绩年月=当月 AND 新客 AND 伙伴签 │
+└──────────────────────────────────────────┘
+```
+
+---
+
+## 六、三类筛选分工（必须在分析中写清）
+
+| 类型 | 配置位置 | API | 典型用途 |
+|---|---|---|---|
+| **查询条件** | 报表顶部高级搜索 | saveQueryItem | 年月、大区、负责人 |
+| **数据集过滤** | 左侧数据集筛选 | queryInfoSave | 核算机构剔除、行级权限 |
+| **自定义筛选** | 单元格属性 | customFilterField | 新客/伙伴签/当月/年累计/去年同期 |
+| **父格筛选** | 跨数据集单元格 | leftFilterField | 销售经理=责任人 |
+
+**禁止重复**：已在 datasetFilter 的全局规则（如核算机构 NotContain ×7）**不要**再写入每个单元格 customFilter。
+
+---
+
+## 七、公式列规范（分析阶段即写明）
+
+| 列 | 公式 | 除零 | 父格 | 扩展 |
+|---|---|---|---|---|
+| E | `IF(B3=0,"--",D3/B3)` | 显示 `--` | A3 | 不扩展 |
+
+API 写入约束见 `formula-cell-api-guide.md`（cellText 无前导 `=`）。
+
+---
+
+## 八、完整示例索引
+
+- **EBU 37 列分组表**：`本地工作目录` + `outputs/新版需求-EBU经营数据统计_字段映射.json`
+- **新客户伙伴签约 19 列**：对话示例「2026-06 新客户伙伴签约统计报表」需求分析（A~S 列、双分组表头）
+
+---
+
+## 九、自检清单（交付前必过）
+
+- [ ] 是否包含 **§一 全部 8 章节**？
+- [ ] **列级配置总表**是否每列都有：字段类型、父格、扩展方向、汇总、父格筛选、自定义筛选？
+- [ ] 是否单独给出 **数据集过滤表** 和 **查询条件表**？
+- [ ] 是否至少有 **网格布局图 + 父格扩展图**？
+- [ ] 行基格坐标是否明确（如 A3 / F3）？
+- [ ] 公式列是否标注「不扩展」与除零规则？
+- [ ] 三类筛选是否分工清晰、无重复？
+- [ ] 是否列出 **待业务确认项**？