规范化后的skill

2026-06-01 14:37:23 +08:00
parent 3d8df9b51f
commit 8dc6e5ab06
14 changed files with 1107 additions and 1139 deletions
@@ -0,0 +1,120 @@
+# 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.