Action 测试（Action Tester）

1. 页面概览

1.1 是什么

「Action 测试」页面（页面标题「Action 写路径测试」）是 LightFoundry 提供的 Action 唯一写路径测试台。在 Foundry 本体体系中，业务数据的写入只能通过对象类型上声明的 Action（动作）完成——Action 携带 param_schema（参数模式）、validation_rules（提交前校验规则）、write_back_config（回写声明，含 SQL 模板与乐观锁配置）等定义，经过后端 writepath 安全流水线（Schema 校验 → 校验规则 → RBAC → 记录级 → 属性级 → 审计 → 幂等 + 事务）后才能落库。

本页面的源码位于 action/web/src/views/ActionTesterPage.vue，共约 395 行。它做的事情是把某个对象类型上的 Action 以可交互表单的形式暴露出来：选择对象与动作后，前端按 param_schema 动态生成参数表单（含必填标记、类型标注、枚举下拉），填好参数与幂等键后点击「执行（VALIDATE_AND_EXECUTE）」即可真实触发写路径；同时提供「重放上次执行」按钮演示幂等重放（replayed）语义。

页面顶部注释块概括了核心设计：选择对象与动作 → 按 param_schema 生成参数表单 → 执行（VALIDATE_AND_EXECUTE，idempotency_key 自动生成/手动输入）；幂等演示：记录上次执行的 idempotency_key，「重放上次执行」复现 replayed。因此本页既是开发调试工具，也是幂等与写路径机制的演示窗口——这正是本手册第 5、6 章重点展开的内容。

1.2 核心价值

1.3 一句话总结

2. 访问入口

2.1 路由与菜单

访问方式：登录后从 Foundry 左侧菜单点击「Action 测试」，或直接访问 /foundry/actions。

2.2 认证与权限

• 路由 meta.requiresAuth: true；API 认证使用 aip_token（localStorage），由 client.js 请求拦截器自动附加 Authorization: Bearer <aip_token>。
• 权限点是动作级 RBAC：后端 stepRBAC 会校验当前用户对 action:<name> 权限点是否被授权（AuthorizeUser(ctx, userID, username, "action:"+action.Name)），越权执行返回 FORBIDDEN（HTTP 403，状态 forbidden）。
• 由于本页是真实写路径，执行动作会真实修改数据源业务数据，请使用演示/测试环境，切勿在共享生产数据源上随意执行。
• 401 时客户端拦截器清 token 并跳 /login。

2.3 端口与 API 前缀

• Foundry 后端端口：18081；Vite 代理 /api 前缀到该后端。
• API 基础前缀：/api/v1（client.js 的 baseURL）。
• 本页请求落在 /api/v1/ontology/...。

3. 界面布局

本页为四张纵向卡片流：

┌─────────────────────────────────────────────────────┐
│  Action 写路径测试                                   │
│  ┌─────────────────────────────────────────────────┐ │
│  │ [alert 提示条（出现时展示，右上角"关闭"）]          │ │
│  └─────────────────────────────────────────────────┘ │
│  ┌─ 选择对象与动作 ─────────────────────────────────┐ │
│  │  对象类型 [下拉]  动作 [下拉]                     │ │
│  │  action_name — description [edit_type 标签]      │ │
│  └─────────────────────────────────────────────────┘ │
│  ┌─ 参数（按 param_schema 生成）────────────────────┐ │
│  │  提示：ValidationRules 提交前校验...（B7-6）      │ │
│  │  字段名*（type）  [输入框/枚举下拉]               │ │
│  │  idempotency_key（运行模式必填）[输入框][生成]     │ │
│  │  [执行（VALIDATE_AND_EXECUTE）] [重放上次执行]    │ │
│  │  上次执行幂等键：<key>                            │ │
│  └─────────────────────────────────────────────────┘ │
│  ┌─ 执行结果（result 存在时展示）───────────────────┐ │
│  │  status / mode / rows_affected / affected_records │ │
│  │  validation_result.result / edits.changed_records │ │
│  │  operation_id / replayed_from_run_id              │ │
│  │  validation（JSON）  result（JSON）               │ │
│  └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

4. 交互元素详解

4.1 对象类型下拉框

4.2 动作下拉框

4.3 参数表单（按 param_schema 生成）

4.4 idempotency_key 输入与「生成」按钮

4.5 执行（VALIDATE_AND_EXECUTE）按钮

4.6 重放上次执行按钮

4.7 上次执行幂等键提示与执行结果卡片

5. 后端关联

5.1 API 客户端

5.2 端点表

execute 请求体字段：action_name（或路径参数 :name）、object_type_id、params（map）、idempotency_key、mode（VALIDATE/RUN/ASYNC/VALIDATE_AND_EXECUTE）。

5.3 响应结构

执行成功响应：

{
  "code": 0,
  "data": {
    "mode": "VALIDATE_AND_EXECUTE",
    "status": "success",
    "validation": {},
    "validation_result": { "result": "VALID", "criteria_results": [] },
    "edits": { "changed_records": 1 },
    "affected_records": 1,
    "rows_affected": 1,
    "latest_state": { ... },
    "result": { ... },
    "operation_id": "run_42",
    "replayed_from_run_id": ""
  }
}

幂等重放响应（status=replayed，HTTP 200）：

{
  "code": 0,
  "data": {
    "mode": "VALIDATE_AND_EXECUTE",
    "status": "replayed",
    "validation_result": { "result": "VALID" },
    "replayed_from_run_id": "42",
    "operation_id": "run_42",
    "result": { ... 首次执行结果 ... },
    "edits": { "changed_records": 1 }
  }
}

5.4 关联模块表

5.5 关键机制（写路径五步流水线 + 幂等 + 乐观锁）

0 模式分派

Execute 按 mode 分派——VALIDATE 走 validate()（仅步骤 1-4 + 冲突预检，不落盘不幂等）；RUN/ASYNC 走 run()（全流程）；VALIDATE_AND_EXECUTE 先 validate() 通过（Status==success）再 run()。

流水线步骤（run 全流程）

幂等（补偿式登记）

action_runs 表（foundry 库）与数据源回写（外部库）无法跨库事务，采用"先登记 pending → 外部执行 → 标记结果"补偿式。idempotency_key 有唯一索引；Begin 先查已存在 → 返回 ACTION_IDEMPOTENT_REPLAY（HTTP 409）并附首次结果，writeActionResponse 检测到 status==replayed 时把 HTTP 状态降为 200。并发竞态下 CreateActionRun 用 OnConflict{DoNothing:true} 吞冲突并重查幂等键兜底（run.ID=0 场景 BUG-2 已修复）。

乐观锁（G2）

write_back_config.optimistic_lock 支持两种形态——true（默认列 updated_at、参数 expected_updated_at）或 {column, expected_param}。SQL 模板中写入 AND updated_at=:expected_updated_at，预检（optimisticConflictCheck）与执行时行数 0 命中即判定冲突，返回 conflict（409，ACTION_CONFLICT）。演示数据用毫秒精度 strftime('%Y-%m-%d %H:%M:%f','now') 写回，避免同秒乐观锁盲区。

Status 常量与错误码

Status：success / validation_failed / forbidden / conflict / record_denied / replayed / rejected。错误码：VALIDATION_FAILED / FORBIDDEN / RECORD_ACCESS_DENIED / PROPERTY_EDIT_DENIED / ACTION_CONFLICT / ACTION_IDEMPOTENT_REPLAY / WRITE_CONFIG_ERROR。

审计口径

stepAudit 调用 LogEventRef(userID, "ACTION_EXECUTE", "ontology_action", action.Name, "ACTION_EXECUTE", details, string(result))；details 含 action_name、params（经 maskParams 脱敏）、idempotency_key、mode，有 prior_rows 时含 prior_state；validate/run 各失败分支也分别记录对应 status 的审计。

6. 核心流程详解

6.1 主流程：执行一个动作

1. 页面挂载执行 fetchObjects()，GET /ontology/objects 填充对象下拉。
2. 选择对象 → handleSelectObject()：
   • 重置 selectedActionName/selectedAction/result/paramValues；
   • GET /ontology/objects/:id，把返回 data.data.actions 填入动作下拉；失败 alert「加载动作失败：...」。
3. 选择动作 → handleSelectAction()：
   • selectedAction = actions.find(a => a.name === selectedActionName)；
   • 重置结果与参数，按 schemaFields 初始化空值。
4. 填写参数；必要时点「生成」产生幂等键或手动输入。
5. 点击「执行（VALIDATE_AND_EXECUTE）」→ handleExecute()：
   • 前置校验（选动作/幂等键）→ doExecute(name, 'VALIDATE_AND_EXECUTE')；
   • doExecute 组装 params（number/integer 空值转 null）、body {action_name, object_type_id, params, idempotency_key, mode}，POST /ontology/actions/:name/execute；
   • 成功或业务失败（err.response.data.data）均把 res.data.data 返回；
   • result = resp，lastKey = idempotencyKey，alert「执行完成：{status}」。
6. 「执行结果」卡片展示各字段；非空 validation/result 以 JSON 区块展开。

6.2 分支流程：重放（幂等演示）

1. 首次执行成功后 lastKey 已记录，页面出现「上次执行幂等键：<key>」。
2. 点击「重放上次执行」→ handleReplay()：idempotencyKey = lastKey，同一动作、同一 key 再次 VALIDATE_AND_EXECUTE。
3. 后端 Begin 发现幂等键已处理 → 返回 status: replayed（HTTP 200）+ 首次结果；前端 alert「重放完成：replayed」，结果卡片中 replayed_from_run_id 显示首次 run id。
4. 演示意义：同一业务操作重复提交不会产生第二次数据变更，rows_affected 回放首次值而非重新执行。

6.3 状态机/终态语义

6.4 执行时序（VALIDATE_AND_EXECUTE 单请求）

前端 POST /ontology/actions/:name/execute
  → Executor.Execute(mode=VALIDATE_AND_EXECUTE)
    → validate(): 1 Schema → 1b Rules → 2 RBAC → 3 记录级 → 3b 属性级 → 4 审计 → 5 乐观锁预检
    → 通过则 run(): 1-4 同上 → 5 Begin(idempotency_key 查重/登记) → buildWriteSQL
      → ConnectorFor(dataSourceID) 取连接器 → 编辑态落盘/血缘/事件（可选）→ 回写执行
      → Finish 标记 success/failed → 响应

7. 权限与安全

• 认证：aip_token Bearer；/ontology/... 全在 protected 组。
• 逐动作 RBAC：权限点 action:<name>；未授权返回 FORBIDDEN。跨产品 JWT 场景下 user_id 在本库查不到角色时经 username 兜底反查同名用户（ExecuteRequest.Username）。
• 数据级安全：记录级（RLS 可见性，写侧不 SQL 改写，改 SELECT 主键 + 可见性判定）与属性级（EditProperty/EditPolicyProperty 三分）双重防护。
• 写操作防护：幂等键唯一索引防止重复业务操作；乐观锁防止并发覆盖；前端 busy 锁 + 结果展示便于核对。
• 强制审计：每次执行（含各失败分支与重放）都落 ACTION_EXECUTE 审计事件，参数经 maskParams 脱敏，不落敏感参数明文。
• 可追溯：operation_id（run_<id>）可关联 action_runs 表记录与审计日志；ASYNC 模式下还可通过 GET /ontology/actions/runs/:id 轮询终态。

8. 常见问题与排错

9. 已知缺陷与边界

注：执行/重放提示语义混淆已于 2026-09-06 修复（按实际返回 status 判定成功/失败：success/replayed 标绿，其余失败以 alert-error 标红展示）。

注：type=boolean 参数此前落入 text 输入框，提交的字符串（"true"/"1" 等）被后端严格类型校验判为不符，导致测试页无法执行；已于 2026-09-07 修复（#IKDX27）——前端对 boolean 渲染 true/false 下拉（提交 JSON 布尔），后端 normalizeBoolParams 补充字符串形态布尔归一兜底直接 API 调用。