---
title: 判断是否需要脚本
navTitle: 判断是否需要脚本
---
# 判断是否需要脚本

脚本用于补充 SuccApp 现有配置和低代码能力无法覆盖的个性化逻辑。开始写脚本前，先把用户需求还原成业务目标、触发时机、影响范围和验收方式，再判断是否需要代码，以及代码应该运行在什么位置。

## 先还原真实目标{#goal}

不要只根据“定制一下”“加个逻辑”“改个页面”这类说法直接写脚本。AI agent 应先把问题问清楚，并用自己的话复述判断依据。

优先确认：

1. 用户真正要达成什么结果，例如“提交前校验库存”“登录页展示客户品牌”“给外部系统提供订单查询接口”。
2. 逻辑在什么时候发生，例如页面打开、按钮点击、保存前、流程执行中、外部请求进入时、用户登录或会话失效时。
3. 逻辑需要访问什么信息，例如当前页面数据、组件状态、当前用户、数据库、文件、远程接口或服务端权限上下文。
4. 影响范围有多大，例如一个页面、一个应用、一个项目、所有项目，还是系统登录和权限流程。
5. 用户如何验收，例如页面操作、接口返回、流程结果、日志、权限账号对比或异常提示。

这些问题答不清时，先不要修改代码。可以先阅读现有页面、数据模型、程序流、权限配置和同项目脚本，再向用户补问缺口。

## 优先判断能否不用脚本{#avoid-script}

能用 SuccApp 产品能力完成的需求，优先不用脚本。产品配置通常更容易升级、交接、排查和由业务人员维护。

常见判断：

| 需求方向 | 先检查什么 | 什么时候再考虑脚本 |
| --- | --- | --- |
| 页面布局、字段显示、按钮、筛选和简单联动 | 页面设计器、组件属性、表达式和内置事件。 | 内置配置无法表达交互，或需要跨组件、跨页面组织复杂状态。 |
| 数据来源、字段加工、汇总计算和演示数据 | 数据模型、数据集、数据加工、调度和查询配置。 | 取数逻辑依赖复杂规则、外部接口、服务端上下文或运行时条件。 |
| 用户可见范围、操作入口和数据范围 | 用户、用户组、资源权限和数据权限配置。 | 权限规则需要结合请求参数、业务状态或外部系统动态判断。 |
| 报表参数、打印、导出、模板和主题 | 报表设计能力、参数栏、打印导出和主题配置。 | 输出过程或样式规则必须按项目逻辑动态生成。 |
| 审批、流转和任务编排 | 流程、程序流、调度和已有节点。 | 流程中需要插入产品节点无法表达的计算、校验或外部调用。 |

决定写脚本前，应和用户说明取舍：脚本可以满足特殊逻辑，但也会带来开发、测试、性能、安全、升级兼容和后续维护成本。

## 按逻辑发生的位置选型{#runtime}

判断脚本类型时，先问“这段逻辑必须在哪里运行”，而不是先问“文件该叫什么”。

| 逻辑发生的位置 | 适合的方式 | 继续阅读 |
| --- | --- | --- |
| 只影响浏览器中的交互、提示、组件联动、页面状态或前端表达式 | 前端脚本 | [前端脚本开发](./frontend/README.md) |
| 只影响页面、门户、仪表板、报表或系统页的视觉样式 | 自定义样式 | [前端自定义样式开发](./styles/README.md) |
| 需要完整控制 HTML、FTL、前端脚本和样式 | 自定义页面 | [HTML 和 FTL 自定义页面](./frontend/html-ftl-pages.md) |
| 需要访问数据库、文件系统、服务端上下文、权限上下文或服务端 API | 后端脚本 | [后端脚本开发](./backend/README.md) |
| 外部系统要通过 HTTP 调用 SuccApp 项目逻辑 | WEB API 脚本 | [WEB API 脚本](./backend/web-api-script.md) |
| 程序流或数据加工执行过程中需要补一段计算、校验或外部调用 | 脚本节点 | [后端程序流脚本节点](./backend/action-flow-script-node.md)、[前端程序流脚本节点](./frontend/action-flow-script-node.md)或 [ETL 脚本节点](./backend/etl-script-node.md) |
| 系统、项目或应用事件发生前后需要补充处理 | 钩子脚本 | [钩子脚本开发](./hooks/README.md) |
| 登录页、登录对话框、403、404、维护页或 SSO 提示页需要定制 | 系统页定制 | [系统页定制](./system-pages/README.md) |
| 同一类计算需要在多个表达式中复用 | 表达式函数脚本 | [表达式函数脚本](https://docs.succapp.com/v5/dev/script/expression-functions) |

如果需求是开发新的数据库适配、文件格式、组件、流程节点或平台级能力，不应只写项目脚本，应进入[扩展平台能力](../ai-building/extension/README.md)或对应扩展开发文档。

## 再选择最小影响范围{#scope}

确定脚本类型后，再决定文件放在哪里。原则是放在能满足需求的最小范围内。

1. 只影响一个页面，优先写页面同目录的同名脚本，例如 `order.spg.ts`、`order.spg.less` 或 `order.spg.action.ts`。
2. 一个应用内多页复用，再写应用级 `custom.ts`、`custom.less` 或 `hooks.action.ts`。
3. 一个项目内复用，再写项目级 `public/custom.ts`、`public/custom.less` 或 `settings/hooks.action.ts`。
4. 多个项目或系统级页面都要使用，才写到 `/sysdata`。

具体目录和加载范围见[脚本文件组织](./file-organization.md)。范围越大，越要确认兼容性、权限、安全和回退方案。

## AI 修改前要读什么{#reading-before-edit}

AI agent 准备修改脚本前，应先读取：

1. 当前项目中同类页面、同名脚本、`custom.ts`、`custom.less`、`hooks.action.ts` 和同类 `.action.ts`。
2. [脚本文件组织](./file-organization.md)，确认脚本层级和影响范围。
3. 对应专题文档，例如前端脚本、后端脚本、系统页、钩子、样式或脚本节点。
4. 对应 API 索引和类型声明：前端读[前端脚本 API 索引](./frontend/api-index.md)，后端读[后端脚本 API 索引](./backend/api-index.md)。
5. 当前项目调用方和验收路径，例如页面操作、接口请求、流程节点、调度任务、日志和权限账号。

如果仍无法判断运行位置或调用方，先输出不确定点，向用户确认；不要先写一段“看起来能跑”的脚本。

## AI 输出要求{#output}

开始修改前，AI 应先说明：

1. 用户真实目标，以及为什么产品已有能力不能满足。
2. 选择的脚本类型、运行位置和文件层级。
3. 候选文件、调用方、输入参数、返回结构和错误处理要求。
4. 不允许改变的接口、字段、权限规则、返回结构和页面范围。
5. 验证方式和回退方式。

## 修改后检查{#validation}

脚本修改完成后，至少检查：

1. 成功路径和失败路径是否都验证。
2. 前端脚本是否无浏览器控制台错误。
3. 后端脚本是否有必要日志，且没有输出敏感信息。
4. 权限、数据范围、调用方和返回结构是否保持兼容。
5. Git diff 是否只包含本次需求范围内的变化。