Plan Combined Task Detail Documentation Design

Goal

Complete the bilingual OpenAPI V3 documentation for planFusionTaskExternal and planFusionTaskMain, so callers can understand their nested fields and copy a representative payload without consulting the backend implementation.

Source of truth

The contract is based on the actual schedule-plan response supplied for this request and the Fusion DTOs in sch-tasks-server-v5:

• FusionTaskExternalDTO, FusionTaskMapDTO, and FusionTaskMapResourceDTO define the external task metadata, map list, and resource list.
• FusionTaskMainDTO, FusionTaskAdvanceConfigDTO, FusionSiteInfoDTO, FusionSubTaskDTO, and FusionWorkModeDTO define the main task payload.
• The response example keeps the public field name robotSn; downstream productId is not reintroduced into the platform documentation.

The two JSON objects are opaque JsonNode values at the plan API boundary, so the documentation describes the stable fields emitted by the current Fusion task implementation. Fields that are absent for a task type remain optional; tasks[].workMode may be null for position-style or otherwise unconfigured subtasks.

Scope

Update the following existing sources in both zh_CN and en_US:

1. Standard schedule-plan create and update request definitions and examples: Create Schedule Plan and Update Schedule Plan.
2. Schedule-plan query response definitions and examples: Get Schedule Plan, List Schedule Plans, and List Schedule Pre Tasks By Day.

The simple schedule-plan APIs, calendar API, backend repositories, generated Swagger files, navigation, and API rendering components are out of scope.

Data contract

planFusionTaskExternal

The schema is an object with these fields:

Field	Type	Meaning
fusionTaskId	string	Combined Task UUID.
fusionTaskType	integer	Combined Task kind: 1 persistent temporary task, 2 schedule task, 3 temporary task.
taskAPIVersion	string	Combined Task API version when returned by the task service.
siteId	string	Site UUID; empty for a non-site task.
siteName	string	Site name; empty for a non-site task.
mapList	object[]	Maps and their selected resources.
mapList[].mapId	string	Map UUID.
mapList[].mapName	string	Map name.
mapList[].floorIndex	integer	Floor index in the map data.
mapList[].floorName	string	Floor name.
mapList[].mapResourceList	object[]	Resources used by the task on the map.
mapList[].mapResourceList[].mapResourceId	string	Region or path UUID.
mapList[].mapResourceList[].mapResourceType	string	Resource type: region or path.
mapList[].mapResourceList[].mapResourceName	string	Region or path name.
mapList[].mapResourceList[].mapResourceAreaId	string	Legacy region/area identifier; empty for paths.

planFusionTaskMain

The schema is an object with task metadata, execution settings, and task selection:

Field	Type	Meaning
fusionTaskId	string	Combined Task UUID.
fusionTaskType	integer	Combined Task kind.
taskAPIVersion	string	Combined Task API version when returned by the task service.
fusionName	string	Combined Task name.
relatedTaskId	string	Source temporary-task ID when a schedule task is copied from one.
user	string	User who created the task.
createdAt	integer	Creation timestamp in seconds.
updatedUser	string	User who last updated the task.
updatedAt	integer	Update timestamp in seconds.
loopCount	integer	Number of task loops; defaults to 1.
persistence	boolean	Whether the task is persisted.
taskAdvanceConfig	object	Optional advanced execution settings.
taskAdvanceConfig.activeCleanSwitch	boolean	Whether active cleaning is enabled.
taskAdvanceConfig.activeCleanMode	integer	Active-cleaning mode: 0 regular, 1 dirt-first, 2 path-first.
taskAdvanceConfig.autoPlanning	boolean	Whether the robot plans the route automatically.
taskAdvanceConfig.coverageMode	string	Coverage mode, such as standard, efficiency, coverage, or extreme_efficiency.
taskAdvanceConfig.taskRunningMode	string	Run mode: normal or trial.
taskAdvanceConfig.walkingPattern	string	Walking pattern: 0 adaptive, 1 bow-shaped, 2 back-and-forth.
taskAdvanceConfig.subTaskMode	boolean	Whether subtask mode is enabled.
taskAdvanceConfig.tempTaskPriority	boolean	Whether temporary tasks take priority over this schedule.
siteInfo.siteId	string	Site UUID; empty for a non-site task.
tasks	object[]	Ordered subtask list.
tasks[].id	string	Subtask UUID.
tasks[].mapResourceId	string	Selected map-resource UUID.
tasks[].mapId	string	Map UUID.
tasks[].type	string	Subtask type, such as region or path.
tasks[].workMode	object/null	Optional subtask work-mode configuration.
tasks[].workMode.id	string	Work-mode UUID.
tasks[].workMode.name	string	Work-mode name.
tasks[].workMode.strength	string	Work strength, such as high, middle, low, or custom.
tasks[].workMode.subType	string	Work-mode subtype.
tasks[].workMode.type	integer	Work-mode type code.
workMode	object	Task-level work-mode configuration with the same five fields as tasks[].workMode.

Documentation shape

The nested schemas will use the repository's existing YApi format:

• objects use properties;
• arrays use items with nested properties;
• every documented leaf has type, example, description, and required;
• Chinese and English files have identical keys and types, with localized titles and descriptions.

The Markdown examples will use the supplied plan response as the canonical shape. The list example will place one plan object in data; the detail example will place the same object directly in data; the day-list example will place it under data.preTasks. Create and update request examples will show the two objects with representative IDs, map resources, advanced settings, subtasks, and work-mode values.

Validation

Before implementation, a Node.js assertion will fail because the target nested objects are currently empty or only contain fusionTaskId. After implementation the same assertion will verify:

• all localized JSON sources parse;
• every target endpoint exposes the complete nested key paths;
• the three response shapes place the detailed plan at the correct location;
• request examples contain both detailed objects;
• Chinese and English schemas have matching structural keys and types.

Run git diff --check and yarn build in open-platform as the final documentation regression gates. No backend unit-test source is added because the change is limited to documentation data and Markdown examples.

Non-goals

• Do not change the Combined Task runtime contract.
• Do not add unsupported legacy fields such as planTasks, switchStatus, or isFusionTask to the public V3 query examples.
• Do not change the API template or introduce $ref-based shared schemas.