应用构建（Low-Code App Builder）

1. 页面概览

1.1 是什么

「应用构建」是 LightFoundry 的低代码应用构建器（对应设计文档 TAD-09，对标 Palantir Foundry Workshop，源码 action/web/src/views/AppsPage.vue，约 1047 行）。它让业务人员不写代码、通过点选组件 + 声明式 JSON 绑定来搭建面向对象的数据应用：左侧点选组件类型，中间编辑「组件配置（DataBinding JSON）」，右侧实时预览（<component :is> 动态渲染 table / object_detail / metric_card / button / text 等组件，组件数据经 POST /apps/:id/pages/:pageId/components/:compId/data 加载）。

页面顶部注释块给出了关键架构说明：

• 视图三级：① 应用列表（list，应用 CRUD + 发布）；② 应用详情（app，页面列表 + 创建/删除）；③ 页面编辑器（editor，左侧组件库 + 中部组件配置 + 右侧预览）。
• 组件数据加载「复用后端语义查询」：组件绑定的 DataBinding 会被翻译为语义查询（object_list / object_detail / aggregation / static），由后端连接真实数据源取数。
• 依赖 Foundry 后端 /api/v1/apps 系列接口（JWT 鉴权）。

数据模型三层：Application（应用）→ AppPage（页面）→ AppComponent（组件实例）。应用定义为 JSON 配置（DataBinding / ActionBinding / StyleConfig 存 PostgreSQL jsonb 或 SQLite TEXT），前端按 JSON 配置运行时渲染。也就是说，「做应用」的本质是配置一份份 JSON：应用是容器，页面是布局，组件是数据视图。

1.2 核心价值

1.3 一句话总结

2. 访问入口

2.1 路由与菜单

• 路由：/foundry/apps
• 路由名称：FoundryApps
• 菜单位置：Foundry 左侧边栏「应用构建」（FoundryLayout.vue 菜单项，位于「MLOps 模型」之后）
• 源码文件：action/web/src/views/AppsPage.vue（约 1047 行）
• 路由注册：action/web/src/router/index.js，meta: { title: '应用构建', requiresAuth: true }

2.2 认证与权限

• 需要登录：是（路由 meta.requiresAuth = true，父路由 /foundry 受保护）
• 登录方式：AIP 统一登录；localStorage.aip_token 由 client.js 请求拦截器自动写入 Authorization: Bearer <token>
• 应用有 owner_id（创建时由 currentUserID(c) 写入），但页面本身不按 owner 过滤，所有登录用户可见全部应用；创建/删除等写操作需登录用户身份。
• 组件数据加载走语义查询，受后端 RLS/CLS 约束：handleLoadComponentData 会把 user_id 注入运行时参数，供 RLS/CLS 只读路径使用。
• 401 排错：被重定向到 /login 说明 token 缺失/过期，重新登录即可。

2.3 端口与 API 前缀

• 后端端口：18081（Foundry）
• 前端 API 客户端：action/web/src/api/client.js，baseURL = '/api/v1'，超时 30 秒
• 本页所有请求路径形如 /api/v1/apps，完整 URL 为 http://localhost:18081/api/v1/apps（开发态经 Vite 代理）

3. 界面布局

页面是三级视图切换的单页应用，view 状态为 list / app / editor，标题随视图变化（viewTitle computed）：

┌─────────────────────────────────────────────────────────────────────┐
│  [低代码应用构建器 / 应用页面 · xxx / 页面编辑器 · xxx]  [返回][发布应用]│
├─────────────────────────────────────────────────────────────────────┤
│ View1 list（应用列表）:                                               │
│  ┌ 卡片: 创建应用（api_name* | 显示名称* | 分类下拉 | [创建]）──────┐  │
│  │        描述输入                                               │  │
│  ┌ 卡片: 应用列表（app-grid 卡片墙）──────────────────────────────┐  │
│  │  卡片: 显示名 + 状态徽标 / api_name·分类 / 描述                 │  │
│  │        操作: [打开] [发布(未发布时)] [页面] [删除]              │  │
├─────────────────────────────────────────────────────────────────────┤
│ View2 app（应用详情）:                                               │
│  ┌ 卡片: 应用信息（显示名/name/分类/状态）────────────────────────┐  │
│  ┌ 卡片: 添加页面（页面名称* | 路径 | 布局下拉 | [添加]）─────────┐  │
│  ┌ 卡片: 页面列表（page-row: 名称 + 路径 + 布局标签）─────────────┐  │
│  │        操作: [编辑] [预览] [删除]                              │  │
├─────────────────────────────────────────────────────────────────────┤
│ View3 editor（页面编辑器，三栏布局）:                                 │
│  ┌ 左栏(220px): 组件库(palette) ─────────────────────────────────┐  │
│  │  8 个组件类型按钮 + 已添加组件列表（点击选中）                  │  │
│  ├ 中栏(360px): 组件配置 ────────────────────────────────────────┤  │
│  │  组件类型下拉 | 标题* | 绑定对象类型下拉 | DataBinding JSON     │  │
│  │  ActionBinding JSON | [保存配置/创建组件] [删除组件]            │  │
│  ├ 右栏(自适应): 预览 ───────────────────────────────────────────┤  │
│  │  [刷新数据] + <component :is> 动态渲染各组件                  │  │
└─────────────────────────────────────────────────────────────────────┘

4. 交互元素详解

4.1 页面级元素

4.2 View1 应用列表

4.2.1 创建应用表单

四列栅格 + 下方描述输入：

4.2.2 应用列表卡片墙

每张卡片（app-card）包含：显示名 + 状态徽标（statusLabel：draft=草稿/published=已发布/archived=已归档）、api_name: xxx · 分类：xxx、描述（无则「无描述」）。

空列表显示「暂无应用，先创建一个吧。」

4.3 View2 应用详情

4.3.1 添加页面表单

4.3.2 页面列表

每行（page-row）：页面名 + 路径（灰色 page-path）+ 布局标签（status-tag status-draft）。

空列表显示「暂无页面，添加一个页面开始搭建应用。」

4.4 View3 页面编辑器

4.4.1 组件库（左栏）

点击任意组件按钮：busy 期间禁用；POST 创建组件（title 自动取组件类型中文标签，data_binding: {}），成功后提示「组件已添加，请在中间面板配置数据绑定」，刷新组件列表并自动选中新建组件。「已添加组件」列表：显示 title || 类型标签 与组件类型英文，点击选中（selectComp）。

4.4.2 组件配置（中栏）

选中组件后表单填充（selectComp 回填），可编辑：

DataBinding JSON 示例（模板 placeholder 逐字）：

{"mode":"object_list","properties":["order_id","amount","status"],"filters":[{"field":"order_id","op":"eq","value":"{{selectedRowId}}"}],"page_size":50}

mode 支持 object_list / object_detail / aggregation / static / action_trigger（后端 BindingMode* 常量）。{{...}} 是运行时参数引用，会在加载组件数据时用运行时参数替换（类型保留，未解析参数置 null）。

位置/尺寸的部分更新语义（重要边界）：UpdateComponent 用 defaultInt(in.PositionX, comp.PositionX) 等做部分更新（apps/service.go:649-652），即更新时传 0 会被当作「未提供」而保留原值——已存在组件的 position_x/position_y/width/height 无法经 PUT 置 0；CreateComponent 中 position_x/y 原样写入（创建时可 0），width/height 为 0 时回落为 6/4（apps/service.go:591-594）。前端编辑态四个输入 min=1，保存时仅下发 ≥1 的字段（<1 的字段省略，后端保留原值），并在结果提示中列出被保留的字段。

4.4.3 预览（右栏，按 page.layout_type 渲染）

预览区按 layout_type 真实排版（previewLayout），组件按 position_y → position_x → id 排序（previewComps）：

预览区每个组件一个 preview-item，点击可选中（联动中栏表单）。渲染器按类型分派（rendererFor）：

动作触发（ActionBinding）已接线（2026-09-14）：后端服务层 ExecuteActionTrigger（apps/service.go，含 findActionTriggerComponent/auditTrigger）与 HTTP 路由 POST /api/v1/apps/pages/:pageId/actions/:actionName/execute（handleExecuteActionTrigger）均已就绪，openapi 已收录。预览中 button 组件读取 data_binding.action_trigger.action_name，点击后按输入的「动作参数(JSON)」与自动生成的幂等键真实触发（writepath 五步流水线），组件内显示 status/rows_affected/operation_id 结果；未配置 action_name 时提示补充绑定。前端不再做「缺口拦截」。

5. 后端关联

5.1 API 客户端

• baseURL: '/api/v1'（Vite 开发代理到 Foundry 18081）
• timeout: 30000（30 秒）
• 请求拦截器：自动附带 Authorization: Bearer ${localStorage.aip_token}
• 响应拦截器：401 时清除 token 并跳转 /login
• 本页无独立 axios 实例。

5.2 端点表

5.3 响应结构

组件数据加载响应示例（table 组件）：

{
  "data": {
    "component_id": 3,
    "component_type": "table",
    "title": "订单列表",
    "columns": ["order_id", "amount", "status"],
    "rows": [
      [1001, 2000, "已发货"],
      [1002, 1500, "待审核"]
    ]
  }
}

加载失败时前端把 err.response?.data?.error 存入 dataMap[comp.id].error，预览区渲染「加载失败：<error>」。无绑定的组件（文本/按钮）返回空 columns/rows，预览走各自渲染分支。

5.4 关联模块表

5.5 关键机制

• 视图状态机：list → app（选应用）→ editor（选页面）；「返回」逐级回退并刷新数据。
• 组件数据加载：LoadComponentData 读组件 DataBinding → 参数引用替换（resolveBindingParams）→ 按 mode 分派：object_list（execObjectList）/ object_detail（execObjectDetail）/ aggregation（execAggregation）/ static（空数据）/ action_trigger（解析动作元数据）。user_id 由服务端注入参数（RLS/CLS 只读路径用）。
• 页面联动加载：LoadPageData 遍历页面组件，先执行参数引用组件、结果注册为后续组件运行时参数（联动）；单个组件失败不阻断整页。
• 发布语义：发布仅把应用状态 draft → published，不生成可独立访问的运行时 URL（低代码应用当前在前端编辑器内预览使用）。
• 渲染器：前端用 Vue render 函数按 componentType 动态渲染（runtime-only 构建），预览数据来自 dataMap[comp.id]。

6. 核心流程详解

6.1 主流程一：创建应用

1. 进入页面默认在「应用列表」视图。
2. 填「api_name」与「显示名称」（必填），选「分类」，可填「描述」。
3. 点「创建」→ createApp() 校验 → POST /api/v1/apps → 成功提示「应用创建成功」，清空表单并刷新列表。
4. 新应用出现在卡片墙，状态为草稿（draft）。

6.2 主流程二：添加页面

1. 在卡片墙点「打开」或「页面」→ 进入「应用详情」视图。
2. 填「页面名称」（必填）、「路径」（默认 /）、「布局」（grid/tabs/sidebar）。
3. 点「添加」→ POST /api/v1/apps/:id/pages → 页面列表出现新页面，布局标签显示。

6.3 主流程三：编辑器内组装应用

1. 在页面列表点「编辑」或「预览」→ 进入「页面编辑器」三栏视图，自动并行加载组件列表与对象类型列表。
2. 左栏点组件类型按钮 → 自动创建组件并选中，中栏填充表单。
3. 中栏选「绑定对象类型（数据源）」、写「DataBinding JSON」（如 object_list 模式）、可选「ActionBinding JSON」。
4. 点「保存配置」（新建时显示「创建组件」）→ PUT/POST 组件接口 → 刷新组件列表与预览数据。
5. 右栏点「刷新数据」手动重新加载全部组件数据；点击预览区的组件可快速选中。
6. 保存后组件出现在「已添加组件」列表，预览区实时渲染真实数据。

6.4 主流程四：发布应用

• 在应用列表卡片点「发布」，或进入编辑器后点页面头「发布应用」→ POST /api/v1/apps/:id/publish → 提示「应用已发布」，状态徽标变已发布。
• 已发布应用的「发布」按钮从卡片上消失；编辑器头部按钮变「已发布」并禁用。

6.5 数据流 / 任务终态语义

用户点击组件类型 ──▶ POST components ──▶ 组件落库(component_type/title/data_binding)
      │
      ▼
选中组件 → 中栏表单回填 → 编辑 DataBinding JSON
      │
      ▼
保存配置(PUT/POST) ──▶ fetchComponents ──▶ loadAllData
                                            │
            ┌───────────────────────────────┤
            ▼                               ▼
  POST components/:compId/data      (逐组件并行)
            │
            ▼
  resolveBindingParams({{selectedRowId}} 等)
            ▼
  mode 分派: object_list / object_detail / aggregation / static / action_trigger
            ▼
  dataMap[comp.id] ──▶ 右栏 <component :is> 渲染

状态机：应用 draft（草稿）→ published（已发布）→ archived（已归档，后端支持、前端无 UI）。组件无独立状态字段，以是否存在为准。组件数据加载是同步 HTTP，无任务轮询。

7. 权限与安全

• 认证：全部接口走 /api/v1 protected 组，JWT 必需；client.js 自动带 Bearer token。
• 数据级安全：应用创建时写入 owner_id，但列表对所有登录用户可见（页面无过滤）；组件数据加载时服务端注入 user_id，语义查询路径受 RLS/CLS 约束。
• 写操作防护：删除应用/页面/组件均有 confirm 二次确认；创建/保存/删除在 busy 期间按钮禁用防重复提交。
• 输入校验：前端校验 api_name/显示名称/页面名称/组件标题必填，DataBinding/ActionBinding 必须 JSON 可解析；后端校验 name 唯一、枚举（分类/组件类型/布局）合法。
• 数据加载安全：DataBinding 的 filters/条件由后端语义层翻译执行，参数替换保留数字类型，避免注入。

8. 常见问题与排错

8.1 预览区「加载失败：...」

• 现象：右栏预览组件显示红框「加载失败：<error>」。
• 原因：组件绑定了对象类型但 DataBinding 的字段/过滤条件与对象不匹配，或对象类型不可用，或 GET /ontology/objects 失败导致没有绑定选项。
• 排查：① 确认「绑定对象类型（数据源）」已选（「不绑定」则表格组件无数据源）；② 检查 DataBinding 的 properties/filters 字段名是否真实存在于对象；③ 看「对象类型不可用不阻断编辑器」的提示是否出现（后端 ontology 服务是否正常）。

8.2 DataBinding JSON 格式错误

• 现象：点「保存配置」提示 DataBinding JSON 格式错误：...。
• 原因：textarea 内容不是合法 JSON（缺引号/多逗号）。
• 排查：① 用 JSON.parse 思路自查：键与字符串值必须双引号；② 从模板 placeholder 复制改字段名而非手敲；③ 暂时把内容清空保存（空串会被解析为 {}，即无绑定模式）。

8.3 组件列表刷新后预览数据消失

• 现象：保存组件配置后「已添加组件」列表出现，但预览区数据为空/「暂无数据」。
• 原因：fetchComponents 后调用 loadAllData，若组件 DataBinding 是 static 模式或未绑定对象，返回空数据属正常；若绑定了对象但查询无结果，是数据问题。
• 排查：① 点「刷新数据」看是否恢复；② 确认 DataBinding mode 是否为 object_list/object_detail/aggregation；③ 确认对象中确实有符合 filter 的数据。

8.4 创建应用提示必填却无反应

• 现象：只填了 api_name 没填显示名称，点「创建」提示 api_name 与显示名称必填。
• 原因：createApp() 前端校验要求两个字段都非空。
• 排查：两个输入框都填上；注意 api_name 只允许小写字母/数字/下划线（placeholder 提示）。

8.5 应用发布后找不到运行入口

• 现象：应用状态已变「已发布」，但页面只有编辑器预览，没有独立访问 URL。
• 原因：MVP 的「发布」仅固化了应用状态（draft → published），不生成可独立访问的运行时页面。
• 排查：这是当前边界而非 bug；通过「打开」进入编辑器即可预览真实数据。

9. 已知缺陷与边界