alipay-enterprise-scenario-integration

Alipay Enterprise Code Scenario Integration Standard Solution Skill

Positioning

This Skill is the solution orchestrator for enterprise code single-scenario integration: it integrates only one expense scenario at a time, and is responsible for scenario decision-making, domain-based orchestration, cross-domain aggregation, and final verification. Underlying interface fields and domain rules are provided by peer sub-skills:

• alipay-enterprise-ec: enterprise onboarding, employee signing, and enterprise and employee management
• alipay-enterprise-expense-control: policies, quotas, and external expense control SPI
• alipay-enterprise-bill: bills, orders, and reconciliation
• alipay-enterprise-invoice: enterprise title, invoicing rules, invoice messages, and queries, enabled only when explicitly selected in the metro scenario

Task Forms

• Solution design: output scenario decisions, modes, modules, interface lists, rule configurations, and verification points, without generating code.
• Code generation: after the scenario and solution scope are clear, generate or modify code, and execute SDK pre-checks, domain-based generation, and engineering verification.

Required Reading Index

• Scenario Integration Guide: reference for solution design and scenario preparation, not a complete code generation process
• Scenario Decision Rules: expense types, subcategories, business scenarios, rule factors, and business-priority opt-in status
• Multi-Agent Code Generation Orchestration Rules: must be read before code generation, determining domain-based generation, sub-skill loading, and convergence acceptance
• Project Determination and Existing Project Integration Contract: read before code generation, used to automatically determine new projects/existing projects and incremental integration into existing projects
• Main Solution Aggregation Quality Gate: must be read before code generation, determining SDK pre-checks, completion delivery, and main aggregation verification

Dependency Gate

If the runtime environment supports GitHub access, you may execute before starting tools/check_version.js to check whether the local Skill is behind. When a new version is found, only prompt the user to update; do not automatically download or overwrite the local Skill; when the network is unavailable or the check fails, do not block the integration process.

Before reading any reference, performing scenario identification, or distinguishing between solution design and code generation, you must first execute:

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

Both solution design and code generation depend on this installation step. The script will only install the missing subskills/*.zip to peer-level Skills under the current user's Skills root directory, for example <skillsRoot>/alipay-enterprise-ec/, and verify the three foundational sub-skills. It preferentially uses the explicit --skills-root or ALIPAY_SKILLS_ROOT, otherwise it identifies the root directory based on the user installation location of the current Skill; if it cannot be uniquely identified, it fails closed, and falling back to the source repository's solution-skills/is prohibited. On failure, it must stop and request user authorization or environment repair; do not guess the scenario when sub-skills are incomplete.

Optional sub-skills are not default dependencies. For the metro scenario, you must first ask the service provider whether to integrate invoicing; after explicit enablement, install via tools/install_subskills.js --with alipay-enterprise-invoice . Other extensions are installed via --with <extension-id> only when the user has proactively raised them and the referenced documentation confirms they are applicable; when not enabled, do not install, read, generate, or verify. Manual unzip subskills/*.zip -d <skillsRoot>is prohibited; all sub-skills must be installed as <skillsRoot>/<skillName>/。

Scenario Gate

1. Only one scenario is allowed at a time. When the user proposes multiple scenarios at once, the user must choose which one to integrate first this time.
2. When the user explicitly specifies the expense type, expense subtype, and business-related scenario, use them directly and validate their validity according to the documentation; when the business-related scenario is not specified, use the default value according to the scenario decision rules.
3. When the context allows a unique inference, present the inferred result and continue without asking again.
4. When multiple valid scenarios, modes, or module choices exist, the user must be asked. First determine the source of rule factor configuration according to the documentation decision rules: scenario fixed values are automatically preset, and enterprise policy values only require the service provider to implement configuration capability; neither type should be arbitrarily chosen by the service provider at integration time.
5. Expense types, expense subtypes, rule factors, or scenario fixed values that cannot be found in the documentation must not be supplemented on one's own into DEFAULT; business-related scenarios take values only according to the default policy: metro scenarios and ticketing-type scenarios default to "Travel" (TRAVEL), and other scenarios default to "General" (DEFAULT). When the user explicitly selects another valid business-related scenario, use that selection. Enterprise input must be limited to the documentation's enumerations, ranges, formats, structures, and combination constraints.
6. Business-priority is not a default item pending confirmation; when the user has not explicitly proposed "business-priority/enterprise code priority/business payment priority", do not ask whether to enable it, do not put "enable/disable" into the confirmation options, and directly write the disabled state.
7. Before code generation, <项目>/.alipay-skill/scenario.jsonmust be generated, and NEEDS_USER_CONFIRM。
8. must not be retained. The invoice integration for the metro scenario is an optional module that must form a yes/no decision; it must not be enabled or disabled by default, and code generation must not proceed before confirmation. Other optional extensions remain silent by default; when the user has not explicitly proposed them, do not ask, do not write decision fields, and do not read extension Skills.
9. Scenario fixed values must have precise basis in the current scenario documentation and prevent enterprise override, such as the 12306 merchant PID for the ticketing scenario; enterprise policy values must be received, validated, and persisted in isolation by enterprise. Both types of configuration must be correctly mapped at policy creation/modification to rule_value. Runtime data such as orders, merchants, and amounts are inputs for policy matching or external expense control SPI, not sources of rule factor configuration.

Default Scope

By default, the three-domain basic modules of the enterprise code standard solution are used:

Capability Domain	Required Modules	On-Demand Modules
Employee-Enterprise	Enterprise onboarding, employee signing, employee management, enterprise management	Department, accounting entity, enterprise address, enterprise message task
Expense Control	Policy management	Manual issuance, quota management
Billing	Bill management	Order synchronization, statement download
Invoice (optional for metro)	After opting in, it must include enterprise title, invoicing rules, invoice messages, and single invoice query	Employee title, enterprise title batch query, invoice batch query

• Employee-Enterprise defaults to inviting enterprise registration and inviting employee signing.
• Expense Control does not default to internal or external; when it cannot be inferred from the context, it must be asked.
• Billing defaults to push mode.
• Message channels are uniformly decided according to the priority of the upstream plan, user specification, existing entry points, and new project defaults; WebSocket is recommended for new Java projects, and HTTP(S) is the default for non-Java. Invoices, bills, and employee-enterprise share the same delivery channel and main route.
• When the user selects only the basic modules, extension modules that are not selected must not be read or implemented.
• The integration method, pre-check, and domain-specific validator for optional extensions are defined by the corresponding referenced documents; when not enabled, extension pre-checks or extension validations must not be executed.

Execution Phase

1. Dependency preparation: install and verify the three sub-Skills.
2. Scenario decision: read the guide, decision rules, and necessary enumeration documents to confirm a single scenario.
3. Project determination: first automatically determine whether it is a new project or an existing project according to the project determination and connection contract rules; ask only when the directory is inaccessible, evidence conflicts, or the context cannot be inferred. For a new project, plan directly; for an existing project, first take inventory, output an incremental plan and connection contract, and wait for user confirmation.
4. Code generation preparation: read the multi-Agent orchestration rules and the main plan aggregation quality gate, complete the SDK or HTTP(S) pre-check, and establish an interface evidence table.
5. Domain-specific generation: prioritize starting the employee-enterprise, expense control, and billing sub-Agents, and explicitly load the corresponding sub-Skills; before startup or degradation confirmation is completed and the domain interface evidence is output, interface call code must not be generated.
6. Selected integration domains: when subway has been confirmed invoiceIntegration.enabled=true , load the invoice Skill and generate the complete basic链路; other extensions are loaded only when their enablement has been confirmed. Selected integration domains that are not enabled skip generation and validation.
7. Aggregation and closure: after all sub-Agents return final receipts, the main Agent uniformly handles common configuration and message entry points, generates a complete context test that loads the real startup class and verifies that the business message route is non-empty, and then runs the main aggregation validation.

Evidence Gate

Code generation must be evidence-driven and must not guess fields, class names, or method names based on business semantics. Before each subdomain starts generating interface call code, it must output the interface evidence table for that domain, including at least: interface method name, the interface Markdown that has been read, example code location or snippet, SDK/integration method confirmation result, Request/Model/Response or HTTP field source, and key field path. If any interface lacks evidence, it may only continue checking documents or pause for explanation, and must not generate first and then remedy it through compilation, reflection, or validator.

When enabling optional extensions, an extension interface evidence table must also be output according to the extension reference document, covering the extension's integration method, key field sources, state transitions, and domain-specific validator results; inapplicable SDKs, protocol models, or field structures must not be applied.

Post-Generation Validation

After code generation is completed, the official main validation must be executed; for exit code semantics, SDK pre-check sources, and completion status requirements, see Main Plan Aggregation Quality Gate。

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