92 lines
6.2 KiB
Markdown
92 lines
6.2 KiB
Markdown
---
|
|
name: fanwei-e10-api-doc
|
|
description: generate external-facing markdown api documentation for 泛微 oa e10 openapi integrations. use when the user asks to write e10 interface documentation, especially for creating workflow instances, discovering workflow form fields, extracting e10 openapi docs, documenting oauth2 access_token flow, or producing developer-ready api docs from an e10 system.
|
|
---
|
|
|
|
# Fanwei E10 API Documentation
|
|
|
|
Use this skill to create developer-facing Markdown API documentation for 泛微 OA E10 OpenAPI integrations. Focus on external system developers: how to authenticate, which endpoint to call, what parameters to send, how workflow form fields map to request payloads, and how to handle responses.
|
|
|
|
## Hard boundary: read-only operation
|
|
|
|
Never modify the E10 system while using this skill.
|
|
|
|
Allowed actions:
|
|
- Navigate pages, view content, take screenshots, and extract rendered text.
|
|
- Use authenticated browser-session read calls to retrieve workflow, form, and field metadata.
|
|
- Inspect E10 OpenAPI documentation pages.
|
|
- Generate documentation outside the E10 system.
|
|
|
|
Forbidden actions:
|
|
- Create, update, delete, publish, enable, disable, submit, approve, or reject any workflow, form, system object, or business data.
|
|
- Call any endpoint or UI action that changes E10 configuration or data.
|
|
- Save credentials to memory, files, logs, examples, or final documentation.
|
|
|
|
If an endpoint or UI action might write data, stop and ask the user before continuing.
|
|
|
|
## Required inputs
|
|
|
|
Before accessing E10, collect or confirm:
|
|
- E10 base URL, expressed as `https://<E10_BASE>` in final documentation.
|
|
- Login account and password for the current task only.
|
|
- Target documentation type: general E10 OpenAPI documentation or workflow-instance API documentation.
|
|
- Target workflow name when documenting workflow instance creation.
|
|
- Desired output location and filename if the user cares; otherwise save as `E10_<workflow-or-api-name>_API.md`.
|
|
|
|
Do not reuse cached credentials. Do not expose real IPs, real credentials, real tokens, internal IDs, database names, or internal API paths in the final external-facing document unless the user explicitly requests an internal-only diagnostic note.
|
|
|
|
## Workflow decision tree
|
|
|
|
1. Determine whether the request is for a general E10 API or for creating a workflow instance.
|
|
2. If the task needs live E10 inspection, read `references/login-and-browser-harness.md` and log in through an isolated browser session.
|
|
3. For OpenAPI documentation pages, read `references/openapi-doc-navigation.md` and extract rendered documentation text.
|
|
4. For workflow-instance documentation, read `references/workflow-field-discovery.md` and use the internal read-only API chain described in `references/internal-apis.md` to discover workflow, form, and field metadata.
|
|
5. If the API involves attachments, read the file-upload section in `references/openapi-doc-navigation.md` and include an upload prerequisite section.
|
|
6. Generate the final Markdown using `assets/templates/e10-api-doc-template.md`.
|
|
7. Validate the output with `references/output-document-standard.md` and `evals/test-cases.md` before presenting or saving it.
|
|
8. If live access fails, provide the missing inputs or evidence needed instead of inventing field definitions, endpoint details, owners, dates, IDs, or examples.
|
|
|
|
## External documentation rules
|
|
|
|
The final output must be written for external integration developers, not E10 administrators.
|
|
|
|
Always include:
|
|
- OAuth2 `code` to `access_token` flow.
|
|
- A clear statement that `access_token` is passed as a request-body parameter, not as an HTTP Bearer header.
|
|
- Identity mapping guidance: `userType`, `deptType`, and field-level `dataOptions` for employee, department, subcompany, file, and related object fields.
|
|
- Request URL, method, content type, request parameters, request examples, response parameters, response examples, and error codes.
|
|
- At least two `curl` examples when documenting workflow creation: a minimal request and a full request.
|
|
- Workflow field tables grouped by business meaning, not by internal E10 UI group names.
|
|
|
|
Never include in the external-facing document:
|
|
- Real E10 hostnames or IP addresses; use `https://<E10_BASE>`.
|
|
- Credentials, session cookies, real tokens, app secrets, or screenshots.
|
|
- E10 version numbers, internal document page IDs, internal API paths, database table names, `columnName`, or management UI instructions.
|
|
- Internal troubleshooting notes, browser-harness commands, XHR interception details, or generation timestamps.
|
|
- Informal warning labels such as “坑”, “注意”, “陷阱”, or “提示”; convert them into formal parameter notes or constraints.
|
|
|
|
## Resource guide
|
|
|
|
Use these bundled resources as needed:
|
|
|
|
- `references/login-and-browser-harness.md`: isolated browser startup, login, captcha handling, session safety, cleanup.
|
|
- `references/openapi-doc-navigation.md`: how to navigate rendered E10 OpenAPI docs and distinguish similar API names.
|
|
- `references/workflow-field-discovery.md`: workflow lookup, form lookup, field extraction, main/detail table handling.
|
|
- `references/internal-apis.md`: read-only internal API chain for workflow/form/field metadata.
|
|
- `references/output-document-standard.md`: final documentation quality rules and field mapping conventions.
|
|
- `references/troubleshooting.md`: common failures and recovery steps.
|
|
- `assets/templates/e10-api-doc-template.md`: output skeleton for generated Markdown API documentation.
|
|
- `examples/`: sanitized examples showing prompt, extracted metadata, and expected output style.
|
|
- `evals/test-cases.md`: trigger and quality checks for maintaining this skill.
|
|
|
|
## Completion checklist
|
|
|
|
Before finishing, verify:
|
|
- The document is usable without access to E10 management pages.
|
|
- All URLs use `https://<E10_BASE>`.
|
|
- Authentication is complete and accurate.
|
|
- Request examples use external identifiers, such as job number and department code, rather than internal E10 IDs.
|
|
- No internal API path, database table name, session value, screenshot path, or version number appears in the final document.
|
|
- Field names, types, required flags, and examples are derived from actual documentation or explicit user-provided metadata.
|
|
- Missing or uncertain information is marked as “需确认” rather than fabricated.
|