Schedule Calendar Response Documentation Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Complete the bilingual response schema and full response example for the monthly schedule calendar endpoint.

Architecture: The localized JSON files remain the source data for the API field table, including nested items.properties for dayList. The localized Markdown files continue to provide the human-readable request and response examples, using the same response data in both locales.

Tech Stack: JSON, Markdown/MDX, Node.js assertions, Docusaurus, Yarn.

Global Constraints

• All code and configuration changes must follow the existing style and be kept as small as possible.
• Keep Chinese and English API definitions structurally identical; localize only titles, descriptions, and section labels.
• Swagger-visible response fields must include their type, example, and localized description.
• Do not add fields not present in CalendarOfMonthDTO or DayStatusOfMonthDTO.
• New code uses four-space indentation and lines no longer than 240 characters; preserve existing source formatting for the JSON/Markdown documents.
• No runtime code, log statements, or comments require changes because this is a documentation-source-only change.
• No new unit-test source is required; use repeatable Node.js structural assertions and the repository yarn build gate.
• Commit the implementation with an update: xxx message on the current feature/a6-query-calendar branch.

---

Task 1: Define and demonstrate the schedule calendar response

Files:

• Modify: openApiJson/zh_CN/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.json
• Modify: openApiJson/en_US/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.json
• Modify: md/zh_CN/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.md
• Modify: md/en_US/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.md
• Test: No new test file; use the inline Node.js assertions below.

Interfaces:

• Consumes: Existing YApi-style res_body schema, existing June 2026 request examples, and the backend CalendarOfMonthDTO contract.

• Produces: Bilingual nested response definitions and identical 30-day response examples for the API reference page.

• Step 1: Write the failing schema and example assertions

Run this from open-platform before modifying the four source files:

node - <<'NODE'
const assert = require('node:assert/strict');
const fs = require('node:fs');

const jsonFiles = [
    'openApiJson/zh_CN/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.json',
    'openApiJson/en_US/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.json',
];

for (const file of jsonFiles) {
    const api = JSON.parse(fs.readFileSync(file, 'utf8'));
    const data = api.res_body.data;
    assert.ok(data.properties, `${file}: data.properties is required`);
    assert.equal(data.properties.dayList.items.properties.dayOfMonth.type, 'integer');
    assert.equal(data.properties.dayList.items.properties.existPreTasks.type, 'integer');
    assert.equal(data.properties.month.type, 'integer');
    assert.equal(data.properties.year.type, 'integer');
}

const markdownFiles = [
    'md/zh_CN/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.md',
    'md/en_US/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.md',
];

for (const file of markdownFiles) {
    const content = fs.readFileSync(file, 'utf8');
    const match = content.match(/<CodeBlock language="jsx" title="(?:输出|Response)">{`\n([\s\S]*?)\n`}<\/CodeBlock>/);
    assert.ok(match, `${file}: response block is required`);
    const response = JSON.parse(match[1]);
    assert.equal(response.data.dayList.length, 30);
}
NODE

Expected: FAIL because the current JSON has no nested data.properties and the current Markdown example has no data.dayList.

• Step 2: Run the assertions and verify the failure is relevant

Run the command from Step 1 and confirm the first failure identifies the missing nested response definition, rather than a JSON parse or regular-expression error.

• Step 3: Add the localized nested response schemas

In both JSON files, replace the current res_body.data object with the same structure. Keep the existing two-space formatting of these source files and use the localized text shown below.

Chinese data definition:

"data": {
  "type": "object",
  "description": "月历数据。",
  "required": "否",
  "properties": {
    "dayList": {
      "type": "array",
      "description": "该月每天的排班任务状态列表，按日期升序返回。",
      "required": "否",
      "items": {
        "type": "object",
        "description": "每日排班状态。",
        "required": "否",
        "properties": {
          "dayOfMonth": {
            "type": "integer",
            "example": 1,
            "description": "月份中的日期，取值范围为 1 至当月最大天数。",
            "required": "否"
          },
          "existPreTasks": {
            "type": "integer",
            "example": 0,
            "description": "是否存在计划任务，0 表示不存在，1 表示存在。",
            "required": "否"
          }
        }
      }
    },
    "month": {
      "type": "integer",
      "example": 6,
      "description": "返回月份。",
      "required": "否"
    },
    "year": {
      "type": "integer",
      "example": 2026,
      "description": "返回年份。",
      "required": "否"
    }
  }
}

English data definition:

"data": {
  "type": "object",
  "description": "Monthly schedule calendar data.",
  "required": "No",
  "properties": {
    "dayList": {
      "type": "array",
      "description": "Daily schedule task status list for the month, returned in ascending date order.",
      "required": "No",
      "items": {
        "type": "object",
        "description": "Schedule status for one day.",
        "required": "No",
        "properties": {
          "dayOfMonth": {
            "type": "integer",
            "example": 1,
            "description": "Day of the selected month, from 1 to the last day of the month.",
            "required": "No"
          },
          "existPreTasks": {
            "type": "integer",
            "example": 0,
            "description": "Whether schedule tasks exist: 0 means no tasks and 1 means tasks exist.",
            "required": "No"
          }
        }
      }
    },
    "month": {
      "type": "integer",
      "example": 6,
      "description": "Returned month.",
      "required": "No"
    },
    "year": {
      "type": "integer",
      "example": 2026,
      "description": "Returned year.",
      "required": "No"
    }
  }
}

• Step 4: Replace both empty Markdown response examples

Replace only the current data: {} response object in the Chinese and English Markdown files. Use this same JSON data in both files; keep the existing localized CodeBlock title and version note:

{
    "code": 0,
    "data": {
        "dayList": [
            {"dayOfMonth": 1, "existPreTasks": 0},
            {"dayOfMonth": 2, "existPreTasks": 0},
            {"dayOfMonth": 3, "existPreTasks": 0},
            {"dayOfMonth": 4, "existPreTasks": 0},
            {"dayOfMonth": 5, "existPreTasks": 1},
            {"dayOfMonth": 6, "existPreTasks": 0},
            {"dayOfMonth": 7, "existPreTasks": 0},
            {"dayOfMonth": 8, "existPreTasks": 0},
            {"dayOfMonth": 9, "existPreTasks": 0},
            {"dayOfMonth": 10, "existPreTasks": 1},
            {"dayOfMonth": 11, "existPreTasks": 0},
            {"dayOfMonth": 12, "existPreTasks": 0},
            {"dayOfMonth": 13, "existPreTasks": 0},
            {"dayOfMonth": 14, "existPreTasks": 0},
            {"dayOfMonth": 15, "existPreTasks": 1},
            {"dayOfMonth": 16, "existPreTasks": 0},
            {"dayOfMonth": 17, "existPreTasks": 0},
            {"dayOfMonth": 18, "existPreTasks": 0},
            {"dayOfMonth": 19, "existPreTasks": 0},
            {"dayOfMonth": 20, "existPreTasks": 1},
            {"dayOfMonth": 21, "existPreTasks": 0},
            {"dayOfMonth": 22, "existPreTasks": 0},
            {"dayOfMonth": 23, "existPreTasks": 0},
            {"dayOfMonth": 24, "existPreTasks": 0},
            {"dayOfMonth": 25, "existPreTasks": 1},
            {"dayOfMonth": 26, "existPreTasks": 0},
            {"dayOfMonth": 27, "existPreTasks": 0},
            {"dayOfMonth": 28, "existPreTasks": 0},
            {"dayOfMonth": 29, "existPreTasks": 0},
            {"dayOfMonth": 30, "existPreTasks": 1}
        ],
        "month": 6,
        "year": 2026
    },
    "msg": "success"
}

• Step 5: Run the structural assertions and inspect the diff

Run the Node.js command from Step 1. Expected: it completes with exit code 0. Then run:

git diff --check
git diff --stat
git diff -- \
    'openApiJson/zh_CN/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.json' \
    'openApiJson/en_US/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.json' \
    'md/zh_CN/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.md' \
    'md/en_US/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.md'

Confirm the diff contains only the requested nested response fields and the two response example blocks.

• Step 6: Build the documentation site

Run:

yarn build

Expected: Docusaurus completes successfully without malformed JSON, MDX, route, or API-reference errors.

• Step 7: Commit the implementation

git add 'openApiJson/zh_CN/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.json' \
    'openApiJson/en_US/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.json' \
    'md/zh_CN/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.md' \
    'md/en_US/OpenAPI V3 Service/Schedules/Get Schedule Calendar By Month.md'
git diff --cached --check
git commit -m "update: complete schedule calendar response docs"