alipay-enterprise-scenario-integration

# 支付宝企业码场景接入标准方案 Skill ## 定位 本 Skill 是企业码单场景接入的方案编排器：每次只接入一个费用场景，负责场景决策、分域编排、跨域聚合和最终校验。底层接口字段和领域规则由同级子 Skill 提供： - `alipay-enterprise-ec`：企业入驻、员工签约、企业和员工管理 - `alipay-enterprise-expense-control`：制度、额度及外部费控 SPI - `alipay-enterprise-bill`：账单、订单和对账 - `alipay-enterprise-invoice`：企业抬头、开票规则、发票消息和查询，仅地铁场景明确选择时启用 ## 任务形态 - 方案设计：输出场景决策、模式、模块、接口清单、规则配置和验证要点，不生成代码。 - 代码生成：场景和方案范围明确后生成或修改代码，并执行 SDK 预检、分域生成和工程校验。 ## 必读索引 - [场景接入指南](references/scenario-integration-guide.md)：方案设计和场景准备参考，不是完整代码生成流程 - [场景决策规则](references/scenario-decision-rules.md)：费用类型、子类、因公场景、规则因子和因公优先 opt-in 状态 - [多 Agent 代码生成编排规则](references/multi-agent-codegen.md)：代码生成前必须读取，决定分域生成、子 Skill 加载和汇合验收 - [项目判断与已有项目衔接契约](references/integration-contract.md)：代码生成前读取，用于自动判断新工程/已有项目和已有项目增量接入 - [主方案聚合质量门禁](references/quality-gates/aggregate.md)：代码生成前必须读取，决定 SDK 预检、完成交付和主聚合校验 ## 依赖闸门 如果运行环境支持访问 GitHub，可在开始前执行 `tools/check_version.js` 检查本地 Skill 是否落后。发现新版本时只提示用户更新，不得自动下载或覆盖本地 Skill；网络不可用或检查失败时不阻断接入流程。 读取任何 reference、执行场景识别或区分方案设计与代码生成之前，必须先执行： ```bash 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 预检来源和完成状态要求见 [主方案聚合质量门禁](references/quality-gates/aggregate.md)。 ```bash node alipay-enterprise-scenario-integration/scripts/validate_codegen.js <生成项目目录> ```