Retool 与 Appsmith 内部工具

内部工具的特征：
  用户少（数十到数百人）
  需求碎（每个部门一套）
  变化快（业务调整就改）
  逻辑杂（要连各种内部系统）

传统做法的问题：
  全栈开发：排期长、复用低
  纯拖拽平台：表达力不足、连不了内部系统

内部工具平台的答案：
  以查询为中心 + 组件绑定 + 允许写代码
  = 工程师的「快速拼装工具」

Retool 应用结构：
  Queries（查询）：SQL/REST/GraphQL，返回数据
  Components（组件）：Table/Form/Chart/Button
  State（状态）：组件的属性可被引用
  Events（事件）：组件事件触发查询或脚本

引用语法：{{ queryName.data }}

-- Retool 中的 SQL 查询，可用 {{ }} 注入组件状态
SELECT id, name, status, created_at
FROM orders
WHERE tenant_id = {{ current_user.tenantId }}
  AND status = {{ statusFilter.value }}
ORDER BY created_at DESC
LIMIT 100;

Appsmith 架构：
  前端：React 应用（画布 + 组件）
  后端：Java/Spring 服务（查询代理、鉴权）
  存储：PostgreSQL（元数据）+ MongoDB（历史）
  部署：Docker / K8s 自托管为主

核心抽象与 Retool 类似：
  Datasource → Query → Widget → Action

# Appsmith 自托管（docker-compose 精简示意）
services:
  appsmith:
    image: appsmith/appsmith-ce:latest
    ports: ["80:80", "443:443"]
    volumes:
      - ./stacks:/appsmith-stacks
    environment:
      APPSMITH_ENCRYPTION_PASSWORD: "change-me"
      APPSMITH_ENCRYPTION_SALT: "change-me-too"

查询的生命周期：
  1. 定义（连接数据源 + 写查询）
  2. 绑定（组件引用查询结果）
  3. 触发（页面加载 / 事件触发）
  4. 刷新（依赖变化时重跑）

关键概念：查询的依赖与刷新
  组件 A 的值变化 → 触发查询 Q 重跑 → 组件 B 更新

// Appsmith 的 JS Object：把逻辑集中管理
export default {
  async loadOrders() {
    const res = await Query_orders.run();
    await storeValue("orders", res);
    return res;
  },
  totalAmount() {
    return (appsmith.store.orders || [])
      .reduce((sum, o) => sum + o.amount, 0);
  },
};

反模式：链式刷新
  筛选器变化 → 查询 A 重跑 → 表格更新 → 选中行变化
  → 查询 B 重跑 → 详情更新 → ...

正解：
  - 明确「谁是数据源、谁是派生」
  - 把派生计算放在前端（JS Object 的纯函数）
  - 查询只负责取数，不做派生
  - 必要时手动触发（按钮），而非全自动

{
  "widgetName": "ordersTable",
  "type": "TABLE_WIDGET",
  "tableData": "{{ Query_orders.data }}",
  "columns": [
    { "label": "订单号", "key": "id" },
    { "label": "金额", "key": "amount", "type": "currency" }
  ],
  "onRowSelected": "{{ JS_utils.loadDetail() }}"
}

状态可见性：
  组件状态（ordersTable.selectedRow）
    → 全局可见，可被其他组件引用
  查询状态（Query_orders.isLoading / data / error）
    → 全局可见
  应用级 store（appsmith.store.xxx）
    → 跨页面持久

心法：状态是全局的，但作用域要克制
  滥用 store 会让数据流难以追踪

部署形态：
  云托管：免运维，数据经供应商基础设施
  自托管：数据在内网，需自行运维
  混合：元数据在云、查询在内网代理

自托管关注点：
  1. 数据库：元数据存储（PostgreSQL）
  2. 密钥管理：连接凭据加密（KMS / 环境变量）
  3. 网络：与内网数据库的连通（VPC / 专线）
  4. 升级：版本升级与回滚
  5. 高可用：多副本 + 负载均衡

# 自托管的备份要点
pg_dump appsmith > backup_$(date +%F).sql
tar czf stacks_$(date +%F).tar.gz ./stacks

扩展方式：
  1. 内联脚本：组件事件里写 JS（受限）
  2. 逻辑对象：集中管理 JS（Appsmith 的 JS Object）
  3. 自定义组件：打包 React 组件挂载（需开发）
  4. 自定义连接器：接入私有数据源

边界：
  内联脚本适合「一两行」的胶水逻辑
  复杂逻辑应抽到逻辑对象或自定义组件

安全要点：
  1. 数据库凭据：加密存储、最小权限账号（只读优先）
  2. 查询注入：参数化查询，禁止字符串拼接
  3. 行级权限：按用户过滤数据
  4. 审计：谁执行了哪个查询
  5. 敏感操作：写操作需二次确认
  6. 网络隔离：查询代理与数据库同网段

常见错误：
  用超级管理员账号连数据库
  → 一个查询失误就是全库灾难

写操作防护：
  1. 二次确认：修改/删除前弹窗确认，展示影响行数
  2. 软删除优先：能标记废弃就不物理删
  3. 变更留痕：记录操作前后的值（审计表）
  4. 限制范围：写查询必须带明确的 WHERE，禁止无界 UPDATE
  5. 灰度：高风险写操作先在测试库验证

-- 反模式：无界更新
UPDATE orders SET status = 'closed';

-- 正解：带明确条件的参数化更新
UPDATE orders SET status = 'closed', updated_at = now()
WHERE id = {{ table.selectedRow.id }};

选 Retool：
  - 数据不敏感或可接受托管
  - 需要大量 SaaS 连接器
  - 追求开箱即用的体验
  - 预算充足

选 Appsmith：
  - 数据必须留在内网
  - 有 K8s/容器运维能力
  - 连接以数据库/内部 API 为主
  - 希望控制成本

迁移考量：
  - 查询定义与组件绑定格式不通用，迁移需重做
  - 提前评估「锁定成本」，保留导出的可能性