fanwei-e10-api-doc/references/troubleshooting.md

Troubleshooting

Use this reference when live extraction or documentation quality checks fail.

Browser and session

• Browser-harness daemon may persist across commands. Always set BU_CDP_URL in the same command as browser-harness.
• Clear stale daemons before a new task.
• Use an isolated Chrome profile and port. Never attach to the user's daily browser.
• If headless screenshots are blank, wait and capture again.
• CloakBrowser-style Playwright wrappers may not expose the CDP endpoint expected by browser-harness.

Login

• E10 input fields often require native setter plus input, change, and blur events.
• Locate inputs through data-id, not placeholder or name attributes.
• Captcha is expected to be four digits. If fewer digits are recognized, refresh the captcha and retry.
• After login, verify the URL is no longer the login page before extracting docs.

OpenAPI pages

• E10 docs are React SPA pages. Wait after navigation before extracting document.body.innerText.
• curl may return only the shell HTML and is not reliable for page content.
• Documentation category entries are often <a> tags; extract hrefs and navigate directly.
• Distinguish “新增流程” from “创建流程实例”. Use the workflow-instance API for external workflow submission.

Workflow and forms

• Prefer internal read-only APIs over UI clicking.
• workflowId is not formId.
• Workflow names and form names may differ. Use core keywords.
• pageNo and pageSize are the expected pagination keys, not page and size.
• formFieldSearchEntity is required for field queries.
• If formTableId returns no main-table fields, retry without formTableId.
• Use getForm to detect detail tables before trying UI switching.

UI fallback

• JS click() may fail on workflow cards. Coordinate click may be required.
• Multiple menu items have similar names. Confirm the current page and tab before extracting fields.
• 字段设置 and 字段管理 are not the same.
• Pagination can be unreliable; prefer requesting enough records through the internal field API.

Output quality

• If requiredness cannot be confirmed, write 需确认.
• If field type mapping is unclear, describe the known field type and mark payload mapping as needing confirmation.
• If a workflow has no detail table, omit the detail-table section entirely.
• If generated documentation contains internal API paths or database names, revise before delivery.