判断是否需要脚本

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

先还原真实目标

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

优先确认：

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

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

优先判断能否不用脚本

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

常见判断：

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

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

按逻辑发生的位置选型

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

逻辑发生的位置	适合的方式	继续阅读
只影响浏览器中的交互、提示、组件联动、页面状态或前端表达式	前端脚本	前端脚本开发
只影响页面、门户、仪表板、报表或系统页的视觉样式	自定义样式	前端自定义样式开发
需要完整控制 HTML、FTL、前端脚本和样式	自定义页面	HTML 和 FTL 自定义页面
需要访问数据库、文件系统、服务端上下文、权限上下文或服务端 API	后端脚本	后端脚本开发
外部系统要通过 HTTP 调用 SuccApp 项目逻辑	WEB API 脚本	WEB API 脚本
程序流或数据加工执行过程中需要补一段计算、校验或外部调用	脚本节点	后端程序流脚本节点、前端程序流脚本节点或 ETL 脚本节点
系统、项目或应用事件发生前后需要补充处理	钩子脚本	钩子脚本开发
登录页、登录对话框、403、404、维护页或 SSO 提示页需要定制	系统页定制	系统页定制
同一类计算需要在多个表达式中复用	表达式函数脚本	表达式函数脚本

如果需求是开发新的数据库适配、文件格式、组件、流程节点或平台级能力，不应只写项目脚本，应进入扩展平台能力或对应扩展开发文档。

再选择最小影响范围

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

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。

具体目录和加载范围见脚本文件组织。范围越大，越要确认兼容性、权限、安全和回退方案。

AI 修改前要读什么

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

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

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

AI 输出要求

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

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

修改后检查

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

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