weaver-e10-builder 1.6.10 → 1.6.12

package/skill-docs/references/report/report-create-modes-guide.md

@@ -18,15 +18,41 @@
 服务端分支（**互斥，模板优先**）：
 
 ```text
-modelId > 0 → 模版创建（copySheet）
+modelId > 0           → 模版创建（copySheet）
 else quicklyParam 非空 → 快速构建-列表式
-else → 从空白创建（空 workbook + sheet）
+else                  → 从空白创建（空 workbook + sheet）
 ```
 
 **禁止混淆**：Skill 自带的 `assets/template-*-report.json` 是 **Agent 布局脚手架**，**不是**平台「模版创建」的 `getReportModels` 模板池。
 
 ---
 
+## 〇.1 ★★ 建壳顺序（强制 · 注意点 BUILD-50）
+
+`baseInfo` 只写 baseInfo 行；**`edc_report_dev` 记录由「设计器页首次加载」惰性创建**。故建壳后、
+**addDataset 之前**，必须 GET 一次设计器页：
+
+```text
+create blank → POST baseInfo → ★ GET /sp/edc/report/design/<id> → addDataset → (remap) → save
+```
+
+| 步骤 | 说明 |
+|------|------|
+| `POST baseInfo` | 得到 `reportId` |
+| **`GET /sp/edc/report/design/<reportId>?appId=<appId>`** | **初始化 dev 记录**（返回值是 HTML，可忽略）。构建层 / CLI 已内置 |
+| `addDataset` | 见 `add-dataset-registration-guide.md` |
+| `save` | 见 `report-internal-error-guide.md`（ENV-11 载荷矩阵 + R7/R8/R9 防御层） |
+
+**后果**（缺这一步 / 顺序颠倒）：
+- 缺 GET → dev 记录没建起来 → 后续 `saveReportDevInfo` **落不进去**；
+- **「先 save 后 addDataset」的壳会永久废掉** —— dev 与 baseInfo 状态不一致，无法修复，只能删表重建。
+
+已内置：`e10-cli report build`（`e10-cli report build spec`）在 `baseInfo` 之后自动调 `initReportDev`；
+`e10-cli report create blank` 同样自动执行；`e10-cli report card build` 新建分支同样。可用 `EB_SKIP_INIT_DEV=1` 跳过（仅定位）。
+失败时**降级为告警不阻断**（环境差异兜底）。
+
+---
+
 ## 一、共享入口
 
 `POST /api/bs/edc/report/baseInfo`（`multipart/form-data`，`id=0` 新建）
@@ -70,6 +96,9 @@ e10-cli report create models
 e10-cli report create template --app-id <appId> --name "新报表" --model-id <模板ID>
 ```
 
+> 建表前会自动**精确查重**：同名已存在 → `exit 3` 且**不创建**（返回已有 reportId / 设计器地址）。
+> 确需同名再建（用户明确要求）才加 `--allow-duplicate`。见 §五。
+
 Python：
 
 ```python
@@ -89,39 +118,39 @@ rid, obj = client.create_from_model(name, model_id)
 
 ```json
 {
- "dataSetList": [
- {
- "id": "<临时UUID，与 showField[].dataSetId 一致>",
- "sourceType": "1",
- "sourceId": "<表单/数据源 ID>",
- "sourceName": "表单名",
- "sourceGroup": ""
- }
- ],
- "showField": [
- {
- "dataSetId": "<同上临时UUID>",
- "tableId": "...",
- "name": "fieldKey",
- "text": "显示名"
- }
- ],
- "fieldConfig": {
- "<dataSetId>.<tableId>.<name>": {
- "colName": "列标题",
- "colWidth": "170",
- "vAlign": "1",
- "hAlign": "1",
- "group": "0",
- "hideCol": "0",
- "lockCell": "0",
- "textWrap": "0"
- }
- },
- "theme": "-1",
- "sheetIndex": 0,
- "startRow": 0,
- "startCol": 0
+  "dataSetList": [
+    {
+      "id": "<临时UUID，与 showField[].dataSetId 一致>",
+      "sourceType": "1",
+      "sourceId": "<表单/数据源 ID>",
+      "sourceName": "表单名",
+      "sourceGroup": ""
+    }
+  ],
+  "showField": [
+    {
+      "dataSetId": "<同上临时UUID>",
+      "tableId": "...",
+      "name": "fieldKey",
+      "text": "显示名"
+    }
+  ],
+  "fieldConfig": {
+    "<dataSetId>.<tableId>.<name>": {
+      "colName": "列标题",
+      "colWidth": "170",
+      "vAlign": "1",
+      "hAlign": "1",
+      "group": "0",
+      "hideCol": "0",
+      "lockCell": "0",
+      "textWrap": "0"
+    }
+  },
+  "theme": "-1",
+  "sheetIndex": 0,
+  "startRow": 0,
+  "startCol": 0
 }
 ```
 
@@ -166,6 +195,15 @@ Python：`client.create_from_quickly_param(name, quickly_param_dict_or_str)`
 
 ## 五、禁令
 
+- **★ 禁止重复建报表（强制 · 2026-10-09）**：建表前**必须精确查重**
+  （`spec_lib.findReportsByName(appId, name)` = `listAppReports` + 名称归一化比对）；
+  同名已存在 → **不建新表**，把已有 `reportId` / 设计器地址交回，**`exit 3`**。
+  `build spec` 与 `create blank|template|quick` 均已内置该门禁（默认拒绝同名）；
+  仅当用户**明确要求**才加 `--allow-duplicate`。
+  **禁止**为绕过查重而「先删旧表再建同名」（旧表可能已被使用 → 数据丢失风险）。注意点 **BUILD-40**。
+- **★ 禁止空壳（强制）**：`blank` 只产出空报表 → 必须**同流程立刻填满**（`addDataset` → `saveReportDevInfo`），
+  失败/中止即 `lifecycle delete` 回收；正式搭表走 `e10-cli report build spec`（一条命令出表）。
+  自查：`e10-cli report cleanup shells --app-id <appId> --list`。
 - 禁止同时依赖 `reportModel>0` 与 `quicklyParam` 指望「都生效」——服务端 **模板优先**，快速构建被跳过。
 - 禁止把 `assets/template-list-report.json` 当成平台 `getReportModels` 模板去传 `reportModel`。
 - 禁止未登录乱扫前端 bundle 猜参数；以本指南 + 源码 bean 为准。

package/skill-docs/references/report/report-data-model.md

@@ -1,6 +1,6 @@
 # E-Builder 报表数据模型参考
 
-> **冷启动禁止通读**：见 `cold-start-scan-guide.md`。仅生成整包 ReportProps / 深分析时再读。
+> **冷启动禁止通读**：见 `api-report-build-fast-path.md`。仅生成整包 ReportProps / 深分析时再读。
 
 ## 一、核心枚举类型
 
@@ -100,16 +100,16 @@
 
 ```typescript
 interface ReportProps {
- config: {
- fields: CellProps[]; // 字段列表
- ds: SourceTableResult[]; // 数据源列表
- sheetProps?: { // 工作表属性
- rowHeights: Record<number, number>;
- colWidths: Record<number, number>;
- };
- };
- name: string; // 报表名称
- appId: string; // 应用ID
+    config: {
+        fields: CellProps[];           // 字段列表
+        ds: SourceTableResult[];       // 数据源列表
+        sheetProps?: {                 // 工作表属性
+            rowHeights: Record<number, number>;
+            colWidths: Record<number, number>;
+        };
+    };
+    name: string;                       // 报表名称
+    appId: string;                     // 应用ID
 }
 ```
 
@@ -117,24 +117,24 @@ interface ReportProps {
 
 ```typescript
 interface CellProps {
- cellType: CellTypeEnum; // 字段类型
- displayType: DisplayTypeEnum; // 显示方式
- expandType: ExpandTypeEnum; // 扩展方向
- dataSet: string; // 数据集主键
- field: string; // 字段主键
- leftParent: CellParentValueType; // 左父格 [类型, x, y]
- topParent: CellParentValueType; // 上父格 [类型, x, y]
- groupType: GroupTypeEnum; // 分组类型
- countType: CountTypeEnum; // 统计类型
- orderType: OrderTypeEnum; // 排序方式
- cellText: string; // 内容/显示文本
- x: number; // 行号
- y: number; // 列号
- rowCount: number; // 所占行数
- colCount: number; // 所占列数
- style?: SpreadJSCellStyle; // 单元格样式
- leftFilterField?: FilterFieldItem[]; // 左父格过滤
- topFilterField?: FilterFieldItem[]; // 上父格过滤
+    cellType: CellTypeEnum;             // 字段类型
+    displayType: DisplayTypeEnum;       // 显示方式
+    expandType: ExpandTypeEnum;         // 扩展方向
+    dataSet: string;                    // 数据集主键
+    field: string;                     // 字段主键
+    leftParent: CellParentValueType;    // 左父格 [类型, x, y]
+    topParent: CellParentValueType;     // 上父格 [类型, x, y]
+    groupType: GroupTypeEnum;           // 分组类型
+    countType: CountTypeEnum;           // 统计类型
+    orderType: OrderTypeEnum;           // 排序方式
+    cellText: string;                   // 内容/显示文本
+    x: number;                          // 行号
+    y: number;                          // 列号
+    rowCount: number;                   // 所占行数
+    colCount: number;                   // 所占列数
+    style?: SpreadJSCellStyle;           // 单元格样式
+    leftFilterField?: FilterFieldItem[];  // 左父格过滤
+    topFilterField?: FilterFieldItem[];   // 上父格过滤
 }
 ```
 
@@ -142,19 +142,19 @@ interface CellProps {
 
 ```typescript
 interface SpreadJSCellStyle {
- backColor?: string; // 背景颜色
- foreColor?: string; // 字体颜色
- hAlign?: number; // 水平对齐 (0=左, 1=居中, 2=右)
- vAlign?: number; // 垂直对齐 (0=上, 1=居中, 2=下)
- font?: string; // 字体 (如 "12px Arial")
- formatter?: string; // 数字格式
- borderLeft?: { color: string; style: number };
- borderTop?: { color: string; style: number };
- borderRight?: { color: string; style: number };
- borderBottom?: { color: string; style: number };
- textIndent?: number; // 缩进
- wordWrap?: boolean; // 自动换行
- textDecoration?: number; // 文本装饰 (0=无, 1=下划线, 2=删除线)
+    backColor?: string;       // 背景颜色
+    foreColor?: string;       // 字体颜色
+    hAlign?: number;          // 水平对齐 (0=左, 1=居中, 2=右)
+    vAlign?: number;          // 垂直对齐 (0=上, 1=居中, 2=下)
+    font?: string;            // 字体 (如 "12px Arial")
+    formatter?: string;       // 数字格式
+    borderLeft?: { color: string; style: number };
+    borderTop?: { color: string; style: number };
+    borderRight?: { color: string; style: number };
+    borderBottom?: { color: string; style: number };
+    textIndent?: number;      // 缩进
+    wordWrap?: boolean;       // 自动换行
+    textDecoration?: number; // 文本装饰 (0=无, 1=下划线, 2=删除线)
 }
 ```
 
@@ -166,28 +166,28 @@ interface SpreadJSCellStyle {
 
 // 父格过滤（跨数据源关联）
 type ParentFilter = {
- parentField?: string; // 父格字段 fieldKey
- currentField?: string; // 当前字段 fieldKey
- type?: FilterOptionEnum; // 匹配关系（如 Equals）
- id?: string; // 必须等于 currentField（设计器回显）
+    parentField?: string;      // 父格字段 fieldKey
+    currentField?: string;     // 当前字段 fieldKey
+    type?: FilterOptionEnum;   // 匹配关系（如 Equals）
+    id?: string;               // 必须等于 currentField（设计器回显）
 }
 
 // 自定义过滤（单元格级）
 type CustomFilter = {
- currentField?: string; // fieldKey
- type?: FilterOptionEnum; // 平台枚举，禁止 eq/uncontains/empty/nempty
- value?: string;
- id?: string; // 必须等于 currentField
+    currentField?: string;     // fieldKey
+    type?: FilterOptionEnum;   // 平台枚举，禁止 eq/uncontains/empty/nempty
+    value?: string;
+    id?: string;               // 必须等于 currentField
 }
 
 // 从属关系（VLOOKUP 映射，与 leftFilterField 配套）
-type Subordination = [string, string]; // [父格fieldKey, 当前fieldKey]
+type Subordination = [string, string];  // [父格fieldKey, 当前fieldKey]
 ```
 
 // 数据行过滤
 type DataFilter = {
- currentField?: DataRowFilterType; // Before|Last|Odd|Even|Designates
- value?: string;
+    currentField?: DataRowFilterType;  // Before|Last|Odd|Even|Designates
+    value?: string;
 }
 ```
 
@@ -218,17 +218,17 @@ type DataFilter = {
 
 ```java
 class ReportAIDto {
- Long appId; // 所属应用ID
- Long reportId; // 报表ID（更新时使用）
- String reportName; // 报表名称
- String formId; // 数据源表单ID
- String formName; // 数据源表单名称
- List<FieldAIDto> groupFields; // 分组字段（维度字段）
- List<FieldAIDto> listFields; // 列表字段（不分组只展示）
- List<FieldAIDto> targetFields; // 指标/度量字段（要聚合计算的字段）
- String theme; // 报表主题/样式
- List<FieldAIDto> queryFields; // 查询筛选字段
- String version; // 版本标识（"v2"表示直接创建）
+    Long appId;               // 所属应用ID
+    Long reportId;            // 报表ID（更新时使用）
+    String reportName;        // 报表名称
+    String formId;            // 数据源表单ID
+    String formName;          // 数据源表单名称
+    List<FieldAIDto> groupFields;   // 分组字段（维度字段）
+    List<FieldAIDto> listFields;    // 列表字段（不分组只展示）
+    List<FieldAIDto> targetFields;   // 指标/度量字段（要聚合计算的字段）
+    String theme;             // 报表主题/样式
+    List<FieldAIDto> queryFields;    // 查询筛选字段
+    String version;           // 版本标识（"v2"表示直接创建）
 }
 ```
 
@@ -236,9 +236,9 @@ class ReportAIDto {
 
 ```java
 class FieldAIDto {
- String fieldName; // 字段显示名称（中文业务名）
- String groupType; // 分组时间粒度（仅分组字段使用）
- String countType; // 聚合计算类型（仅指标字段使用）
+    String fieldName;   // 字段显示名称（中文业务名）
+    String groupType;   // 分组时间粒度（仅分组字段使用）
+    String countType;   // 聚合计算类型（仅指标字段使用）
 }
 ```
 
@@ -290,25 +290,25 @@ class FieldAIDto {
 
 ```typescript
 interface StyleConfig {
- custom: boolean; // 是否自定义
- theme: number | null; // 主题编号 (1-10)
- alternateMode: 'row' | 'col'; // 交替方式
- titleBg: string; // 标题背景色
- alternateBg1: string; // 交替背景色1
- alternateBg2: string; // 交替背景色2
- titleStyle: {
- fontSize: number;
- color: string;
- bold: boolean;
- italic: boolean;
- };
- bodyStyle: {
- fontSize: number;
- color: string;
- bold: boolean;
- italic: boolean;
- };
- area: { row: number; col: number; rowCount: number; colCount: number } | null;
+    custom: boolean;              // 是否自定义
+    theme: number | null;         // 主题编号 (1-10)
+    alternateMode: 'row' | 'col'; // 交替方式
+    titleBg: string;              // 标题背景色
+    alternateBg1: string;         // 交替背景色1
+    alternateBg2: string;         // 交替背景色2
+    titleStyle: {
+        fontSize: number;
+        color: string;
+        bold: boolean;
+        italic: boolean;
+    };
+    bodyStyle: {
+        fontSize: number;
+        color: string;
+        bold: boolean;
+        italic: boolean;
+    };
+    area: { row: number; col: number; rowCount: number; colCount: number } | null;
 }
 ```
 
@@ -318,9 +318,9 @@ interface StyleConfig {
 
 ```typescript
 interface ConditionRuleType {
- highlightDatas?: HightlightRuleType[]; // 高亮规则
- lineDatas?: DataLineRuleType[]; // 数据条规则
- iconDatas?: DataIconRuleType[]; // 图标集规则
+    highlightDatas?: HightlightRuleType[];  // 高亮规则
+    lineDatas?: DataLineRuleType[];         // 数据条规则
+    iconDatas?: DataIconRuleType[];         // 图标集规则
 }
 ```
 
@@ -328,18 +328,18 @@ interface ConditionRuleType {
 
 ```typescript
 interface HightlightRuleType {
- index: number;
- conditionType?: 'currCell' | 'otherCell';
- relation?: HighlightRelationEnum; // equals/greater/less/interval/include/happenDate/sameValue 等
- value1?: any;
- value2?: any;
- fontFamily?: string;
- fontSize?: string;
- bold?: boolean;
- italic?: boolean;
- underline?: boolean;
- backColor?: string;
- foreColor?: string;
+    index: number;
+    conditionType?: 'currCell' | 'otherCell';
+    relation?: HighlightRelationEnum;  // equals/greater/less/interval/include/happenDate/sameValue 等
+    value1?: any;
+    value2?: any;
+    fontFamily?: string;
+    fontSize?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    backColor?: string;
+    foreColor?: string;
 }
 ```
 
@@ -347,14 +347,14 @@ interface HightlightRuleType {
 
 ```typescript
 interface DataLineRuleType {
- index: number;
- leftType: 'min' | 'custom';
- leftValue?: number;
- rightType: 'max' | 'custom';
- rightValue?: number;
- gradient?: 'gradient' | 'solid';
- color?: string;
- negativeFillColor?: string;
+    index: number;
+    leftType: 'min' | 'custom';
+    leftValue?: number;
+    rightType: 'max' | 'custom';
+    rightValue?: number;
+    gradient?: 'gradient' | 'solid';
+    color?: string;
+    negativeFillColor?: string;
 }
 ```
 
@@ -362,32 +362,32 @@ interface DataLineRuleType {
 
 ```typescript
 interface IReportConditionItemType {
- uuid: string;
- id: string;
- text: string; // 条件名称
- displayType: ReportConditionDisplayTypeEnum; // 显示类型
- selectOptions: any[];
- filterOptions: any[];
- defaultValue: [string, string];
- param: string;
- filterType: 'default' | 'sql';
- conditions: IReportConditionRel[]; // 条件关联
- showOrder: number;
- queryType?: 'filter' | 'advance';
+    uuid: string;
+    id: string;
+    text: string;                           // 条件名称
+    displayType: ReportConditionDisplayTypeEnum;  // 显示类型
+    selectOptions: any[];
+    filterOptions: any[];
+    defaultValue: [string, string];
+    param: string;
+    filterType: 'default' | 'sql';
+    conditions: IReportConditionRel[];      // 条件关联
+    showOrder: number;
+    queryType?: 'filter' | 'advance';
 }
 
 // 查询条件显示类型
 enum ReportConditionDisplayTypeEnum {
- text = 'text', // 文本
- number = 'number', // 数字
- select = 'select', // 下拉选择
- cascader = 'cascader', // 级联
- date = 'date', // 日期范围
- singleDate = 'singleDate', // 单日期
- eBuilder = 'eBuilder', // e-builder组件
- browser = 'browser', // 浏览框
- custom = 'custom', // 自定义
- time = 'time' // 时间
+    text = 'text',         // 文本
+    number = 'number',     // 数字
+    select = 'select',     // 下拉选择
+    cascader = 'cascader', // 级联
+    date = 'date',         // 日期范围
+    singleDate = 'singleDate', // 单日期
+    eBuilder = 'eBuilder', // e-builder组件
+    browser = 'browser',   // 浏览框
+    custom = 'custom',     // 自定义
+    time = 'time'          // 时间
 }
 ```
 

package/skill-docs/references/report/report-delivery-contract.md

@@ -1,6 +1,6 @@
 # 报表搭建完成交付规范（强制）
 
-> **冷启动**：开场只读 `cold-start-scan-guide.md`；交链后禁止续跑（含 verify/HTML）。
+> **冷启动**：开场只读 `api-report-build-fast-path.md`；交链后禁止续跑（含 verify/HTML）。
 > **适用范围**：凡通过本 Skill 完成「线上建表 / 布局落库」或「需求分析」的任务。
 > **优先级**：高于 Agent 默认收尾习惯。
 
@@ -38,6 +38,26 @@
 
 **禁止**为下列事项拖延或续跑：视觉比对、多轮 `getReportDevInfo`、SpreadJS 黑盒、HTML、verify、预聚合、需求分析、配置检测、「再确认一下」。
 
+### 地址格式（硬规则 · 2026-09-15 用户强调 · 2026-10-29 收口为三道防线）
+
+- **必须纯文本**给出完整设计器地址：`https://<host>/sp/edc/report/designer/<reportId>`
+- ★ **`designer/` vs `design/` 一词之差（DELIVERY-3）**：
+  - `/sp/edc/report/designer/<reportId>` = **设计器页面**（给人打开、交付唯一正确形态）；
+  - `/sp/edc/report/design/<id>` = **dev 记录初始化接口**（BUILD-50 建壳用的 GET，机器用，用户打不开）。
+- **唯一构造器**：`spec_lib.designerUrlOf(reportId)` —— 所有交付出口一律走它，**禁止手拼**（协议按部署自动取 http/https；兼容旧双参 `designerUrlOf(host, reportId)`）。曾因误写 `/design/` 被用户截图质问。
+- **交付前硬校验**：`spec_lib.assertDesignerUrl(url, reportId)` —— 非 `/designer/<reportId>` 形态或 reportId 不匹配 ⇒ **throw，宁失败不交假链**。
+- ⚠ **`/sp/edc/report/design/<id>`（含 `?appId=…&type=1&from=management` 变体）是 BUILD-50 初始化 dev 记录的接口端点**，不是设计器页面地址，**禁止交付**（注意点 DELIVERY-5；`doctor scripts` 的 `designurl` 项把守）。
+- **禁止**把 reportId / 地址放进 markdown 加粗、反引号或其它修饰中 —— 用户端曾原样渲染出 `**`，
+  被质疑「返回的报表id是个什么」。地址不可信 = 交付失败。
+- reportId 与地址同段给出，不再单独罗列裸 ID 作为「地址」。
+
+### 预聚合（建表阶段必做 · 不属交付后动作）
+
+- 用户硬规则（多次强调）：**表单中存在不支持预聚合的字段 → 必须关闭 dataPreAgg**。
+- 执行时点：`addDataset` 后、落库前（`e10-cli report preagg check|disable --apply`），属搭建流程的一部分。
+- 关闭验证：回读 `sheetProps.sheetConfig` 含 `"dataPreAgg":false`。
+- 交付后**不再**因预聚合续跑（见上文「搭完即停」）。
+
 ### 与门禁
 
 - **硬失败** → 不交假链；删空壳（`failure-cleanup-and-nonblocking-guide.md`）。
@@ -69,7 +89,7 @@
 仅用户明确要求时：
 
 ```bash
-python （未移植，需要时另议） --config <guide_config.json> --output <输出路径>.html
+python  --config <guide_config.json> --output <输出路径>.html
 ```
 
 建议：`outputs/<reportId>/《报表名称》·搭建配置指导.html`
@@ -96,6 +116,6 @@ python （未移植，需要时另议） --config <guide_config.json> --output <
 ## 五、相关文档
 
 - `api-report-build-fast-path.md`
-- `session-build-performance-guide.md`
+- `api-report-build-fast-path.md`
 - `report-requirement-analysis-template.md`（仅分析意图）
 - `failure-cleanup-and-nonblocking-guide.md`