alipay-enterprise-scenario-integration

name	alipay-enterprise-scenario-integration
description	支付宝企业码单场景接入标准方案 Skill。当用户希望接入企业码餐饮、地铁、公交、用车、酒店、商城、生活服务、票务、加油、医疗或其他文档已定义费用场景，或提出“企业码场景接入”“企业码标准方案”“按费用场景接入”等需求时必须使用。负责识别或确认单一业务场景，编排员企、费控、账单三个基础子 Skill，地铁场景还必须让服务商选择是否加入发票集成子 Skill，并按需启用其他引用文档定义的可选扩展，输出方案或生成接入代码。

支付宝企业码场景接入标准方案 Skill

定位

本 Skill 是企业码单场景接入的方案编排器：每次只接入一个费用场景，负责场景决策、分域编排、跨域聚合和最终校验。底层接口字段和领域规则由同级子 Skill 提供：

• alipay-enterprise-ec：企业入驻、员工签约、企业和员工管理
• alipay-enterprise-expense-control：制度、额度及外部费控 SPI
• alipay-enterprise-bill：账单、订单和对账
• alipay-enterprise-invoice：企业抬头、开票规则、发票消息和查询，仅地铁场景明确选择时启用

任务形态

• 方案设计：输出场景决策、模式、模块、接口清单、规则配置和验证要点，不生成代码。
• 代码生成：场景和方案范围明确后生成或修改代码，并执行 SDK 预检、分域生成和工程校验。

必读索引

• 场景接入指南：方案设计和场景准备参考，不是完整代码生成流程
• 场景决策规则：费用类型、子类、因公场景、规则因子和因公优先 opt-in 状态
• 多 Agent 代码生成编排规则：代码生成前必须读取，决定分域生成、子 Skill 加载和汇合验收
• 项目判断与已有项目衔接契约：代码生成前读取，用于自动判断新工程/已有项目和已有项目增量接入
• 主方案聚合质量门禁：代码生成前必须读取，决定 SDK 预检、完成交付和主聚合校验

依赖闸门

如果运行环境支持访问 GitHub，可在开始前执行 tools/check_version.js 检查本地 Skill 是否落后。发现新版本时只提示用户更新，不得自动下载或覆盖本地 Skill；网络不可用或检查失败时不阻断接入流程。

读取任何 reference、执行场景识别或区分方案设计与代码生成之前，必须先执行：

node alipay-enterprise-scenario-integration/tools/install_subskills.js

方案设计和代码生成都依赖该安装步骤。脚本只会把缺失的 subskills/*.zip 安装到当前用户 Skills 根目录下的平级 Skill，例如 <skillsRoot>/alipay-enterprise-ec/，并验证三个基础子 Skill。它优先使用显式 --skills-root 或 ALIPAY_SKILLS_ROOT，否则根据当前 Skill 的用户安装位置识别根目录；无法唯一识别时失败关闭，禁止退回源码仓库的 solution-skills/。失败时必须停止并请求用户授权或修复环境；不得在子 Skill 不完整时猜测场景。

可选子 Skill 不属于默认依赖。地铁场景必须先询问服务商是否接入发票；明确启用后通过 tools/install_subskills.js --with alipay-enterprise-invoice 安装。其他扩展仅在用户已主动提出且引用文档确认适用时，才通过 --with <extension-id> 安装；未启用时不安装、不读取、不生成、不校验。不得手工 unzip subskills/*.zip -d <skillsRoot>，所有子 Skill 都必须安装为 <skillsRoot>/<skillName>/。

场景闸门

1. 每次只允许一个场景。用户一次提出多个场景时，必须让用户选择本次先接入哪一个。
2. 用户明确费用类型、费用子类和因公场景时直接沿用，并按文档校验合法性；未明确因公场景时按场景决策规则使用默认值。
3. 上下文可唯一推断时，展示推断结果后继续，不重复询问。
4. 存在多个合法的场景、模式或模块选择时必须询问用户。先按文档判断规则因子配置来源：场景固定值自动预置，企业策略值只要求服务商实现配置能力；两类都不应让服务商在接入时随意选择。
5. 文档找不到的费用类型、费用子类、规则因子或场景固定值不得自行补成 DEFAULT；因公场景仅按默认策略取值：地铁场景和票务类场景默认“差旅”（TRAVEL），其他场景默认“通用”（DEFAULT）。用户明确选择其它合法因公场景时沿用其选择。企业输入必须限制在文档枚举、范围、格式、结构和组合约束内。
6. 因公优先不是默认待确认项；用户没有明确提出“因公优先/企业码优先/因公支付优先”时，不得询问是否启用，不得把“启用/不启用”放入确认选项，直接写入关闭状态。
7. 代码生成前必须生成 <项目>/.alipay-skill/scenario.json，且不得保留 NEEDS_USER_CONFIRM。
8. 地铁场景的发票集成是必须形成是/否决策的选接模块；不得默认开启或默认关闭，也不得在未确认时进入代码生成。其他可选扩展仍保持默认静默；用户没有明确提出时，不得询问、写入决策字段或读取扩展 Skill。
9. 场景固定值必须有当前场景文档的精确依据并阻止企业覆盖，例如票务场景的 12306 商户 PID；企业策略值必须按企业隔离接收、校验并持久化。两类配置都要在制度创建/修改时正确映射为 rule_value。订单、商户、金额等运行期数据属于制度匹配或外部费控 SPI 输入，不是规则因子配置来源。

默认范围

默认采用企业码标准方案的三域基础模块：

能力域	必选模块	按需模块
员企	企业入驻、员工签约、员工管理、企业管理	部门、核算主体、企业地址、企业消息任务
费控	制度管理	手工发放、额度管理
账单	账单管理	订单同步、对账单下载
发票（地铁选接）	选择接入后必须包含企业抬头、开票规则、发票消息、单笔发票查询	员工抬头、企业抬头批量查询、发票批量查询

• 员企默认邀请企业注册、邀请员工签约。
• 费控不默认内部或外部；无法从上下文推断时必须询问。
• 账单默认推模式。
• 消息通道按上游方案、用户指定、存量入口、新项目默认的优先级统一决策；新建 Java 项目推荐 WebSocket，非 Java 默认 HTTP(S)。发票、账单和员企共用同一投递通道和主路由。
• 用户只选择基础模块时，不得读取或实现未选择的扩展模块。
• 可选扩展的接入方式、预检和本域 validator 由对应引用文档定义；未启用时不得执行扩展预检或扩展校验。

执行阶段

1. 依赖准备：安装并验证三个子 Skill。
2. 场景决策：读取指南、决策规则和必要枚举文档，确认单一场景。
3. 项目判断：按项目判断与衔接契约规则先自动判断新工程或已有项目；只有目录不可访问、证据冲突或上下文无法推断时才询问。新工程直接规划；已有项目先盘点、输出增量计划和衔接契约，等待用户确认。
4. 代码生成准备：读取多 Agent 编排规则和主方案聚合质量门禁，完成 SDK 或 HTTP(S) 预检，并建立接口证据表。
5. 分域生成：优先启动员企、费控、账单子 Agent，显式加载对应子 Skill；未完成启动或降级确认、未输出本域接口证据前，不得生成接口调用代码。
6. 选接域：地铁已确认 invoiceIntegration.enabled=true 时加载发票 Skill 并生成完整基础链路；其他扩展仅当已确认启用时加载。未启用的选接域跳过生成和校验。
7. 聚合收口：所有子 Agent 返回最终回执后，主 Agent 统一处理公共配置、消息入口，生成加载真实启动类且验证业务消息路由非空的完整上下文测试，再运行主聚合校验。

证据闸门

代码生成必须证据驱动，不能按业务语义猜字段、类名或方法名。每个子域开始生成接口调用代码前，必须输出本域接口证据表，至少包含：接口方法名、已读取的接口 Markdown、示例代码位置或片段、SDK/接入方式确认结果、Request/Model/Response 或 HTTP 字段来源、关键字段路径。任一接口缺少证据时只能继续查文档或暂停说明，不能先生成再靠编译、反射或 validator 补救。

启用可选扩展时，还必须按扩展引用文档输出扩展接口证据表，覆盖该扩展的接入方式、关键字段来源、状态流转和本域 validator 结果；不得套用不适用的 SDK、协议模型或字段结构。

生成后校验

代码生成完成后必须执行官方主校验；退出码语义、SDK 预检来源和完成状态要求见 主方案聚合质量门禁。

node alipay-enterprise-scenario-integration/scripts/validate_codegen.js <生成项目目录>