fanwei-e10-api-doc/references/output-document-standard.md

# Output Document Standard

Use this reference to validate final Markdown API documentation.

## Audience

Write for external integration developers. They need stable API behavior, authentication, request payloads, response payloads, examples, and field mapping. They do not need internal E10 management steps or implementation details.

## Required sections

The final document should contain:

1. Interface title.
2. Interface description.
3. Prerequisites.
4. OAuth2 access_token acquisition flow.
5. Identity mapping rules.
6. Request information.
7. Request parameters.
8. Request examples.
9. Response parameters.
10. Response examples.
11. Error codes.
12. Workflow field description when documenting workflow creation.
13. File upload prerequisite section only when attachments are involved.

## Authentication rules

Always document the two-step OAuth2 flow:

1. `POST /papi/openapi/oauth2/authorize` to obtain `code`.
2. `POST /papi/openapi/oauth2/access_token` to exchange `code` for `access_token`.

State that `access_token` is passed in the request body of business APIs, not in an HTTP Authorization header.

## Identity mapping rules

External systems usually do not hold E10 internal user or department IDs. Include a dedicated identity mapping section.

Top-level user identifier options:

| Parameter | Meaning |
|---|---|
| `JOB_NUM` | Employee job number. Preferred for personnel integrations when job numbers are stable. |
| `EMAIL` | Employee email. |
| `MOBILE` | Employee mobile number. |
| `idNos` | Identity document number. |
| `loginID` | E10 login ID. |
| `account` | Account value supported by the target E10 configuration. |

Department identifier options:

| Parameter | Meaning |
|---|---|
| `DEPT_CODE` | Department code. Preferred when external systems maintain department codes. |
| `DEPT_NAME` | Department name. Use only when names are unique and stable. |

For form fields:

- Employee fields should explain `dataOptions[].type: "resource"` and compatible `userType` values.
- Department fields should explain `dataOptions[].type: "department"` and compatible `deptType` values.
- File fields should explain upload-before-submit behavior.

## URL and placeholder rules

Use:

```text
https://<E10_BASE>
<ACCESS_TOKEN>
<APP_KEY>
<APP_SECRET>
<CORP_ID>
<CODE>
```

Do not use real hostnames, IP addresses, accounts, passwords, cookies, tokens, app secrets, database table names, or internal IDs in external documentation.

## Request examples

Provide at least two examples for workflow instance creation:

- Minimal request: only required fields and the smallest valid payload.
- Full request: representative optional fields, identity mapping, and detail rows if available.

Examples must use external identifiers such as `EMP001` and `DEPT_TECH`, not E10 internal IDs.

## Field table rules

Use this table header:

```markdown
| 字段名 | 类型 | 必填 | 说明 |
|---|---|---|---|
```

Requiredness should be:

- `是` when confirmed.
- `否` when confirmed optional.
- `需确认` when not available from docs, form rules, or user metadata.

Group fields by business meaning. Do not copy E10 internal group names such as “未分组” or technical database groupings unless the user explicitly wants internal documentation.

## Forbidden final-document content

The final external-facing document must not contain:

- E10 version numbers.
- Internal API paths under `/api/...`.
- Internal OpenAPI document page IDs.
- Database table names or column names.
- Browser-harness commands.
- XHR interception details.
- Screenshot paths.
- Login page operation instructions.
- Generated-at metadata.
- Informal labels such as “坑”, “注意”, “陷阱”, “提示”.

Convert operational caveats into formal constraints, parameter notes, or prerequisites.