243 lines
9.5 KiB
Markdown
243 lines
9.5 KiB
Markdown
# 云效实写 API（YunxiaoPMapp 已验证）
|
||
|
||
`verified_at`: 2026-07-25 · **项目须门禁 PJ 点选**（见 [project-selection.md](project-selection.md)）；历史验证样本项目为 `01_ONEOS` / 原「统一运营管理平台」（`last_selected.spaceIdentifier` 见 `assets/runtime-ids.json`，禁止未点选即使用）。
|
||
|
||
本文件只记**已跑通**的写法；禁止再盲试 `updateStatus` / 错误 `updateFieldValue` POST。
|
||
|
||
## 认证
|
||
|
||
- Cookie：Chrome 域 `.aliyun.com` / `devops.aliyun.com`（`browser_cookie3` 或 Playwright storage）
|
||
- Header：`x-xsrf-token` = cookie `XSRF-TOKEN`（URL 解码后）
|
||
- `Origin` / `Referer`：`https://devops.aliyun.com`
|
||
|
||
## 建单
|
||
|
||
`POST|PUT /projex/api/workitem/workitem?_input_charset=utf-8`
|
||
|
||
创建响应 `result.identifier` / `serialNumber` 即编号真相；**禁止按标题查重**。
|
||
|
||
## 改负责人（已通）
|
||
|
||
```http
|
||
PATCH /projex/api/workitem/workitem/{id}?_input_charset=utf-8
|
||
{"propertyKey":"assignedTo","propertyValue":"<userId>","operateType":"COVER"}
|
||
```
|
||
|
||
交棒：【交付】`propertyValue` = 何斐 ID。
|
||
|
||
## 打标签（已通）
|
||
|
||
```http
|
||
PATCH /projex/api/workitem/workitem/{id}?_input_charset=utf-8
|
||
{"workitemIdentifier":"{id}","propertyKey":"tag","propertyValue":"<tagId>[,<tagId>]","operateType":"COVER"}
|
||
```
|
||
|
||
## 改状态（已通 · 唯一推荐）
|
||
|
||
```http
|
||
POST /projex/api/workitem/workitem/{id}/status/transit?_input_charset=utf-8
|
||
{"fromStatus":"<当前status.identifier>","toStatus":"<目标status.identifier>"}
|
||
```
|
||
|
||
成功：`code=200` 且 `result=true`。失败时 `errorMsg` 含「不能流转」。
|
||
|
||
### 需求状态 ID（本项目）
|
||
|
||
| 显示名 | identifier |
|
||
|---|---|
|
||
| 待处理 | `100005` |
|
||
| 已确认 | `32` |
|
||
| 分析中 | `154395` |
|
||
| 设计中 | `156603` |
|
||
| 设计完成 | `307012` |
|
||
| 待开发 | `1582fc929d429111b925309493` |
|
||
|
||
### 任务状态 ID
|
||
|
||
| 显示名 | identifier |
|
||
|---|---|
|
||
| 待处理 | `100005` |
|
||
| 已完成 | `100014` |
|
||
|
||
### 极速交棒跳转（工作流允许）
|
||
|
||
从「待处理」菜单可见直达「设计完成」；推荐最少跳：
|
||
|
||
```text
|
||
待处理 → 设计完成 → 待开发
|
||
```
|
||
|
||
标准路径若需看板留痕，可走完整链：已确认→分析中→设计中→设计完成→待开发（仍用本 API，勿开 UI）。
|
||
|
||
### 禁止（已证伪）
|
||
|
||
| 写法 | 结果 |
|
||
|---|---|
|
||
| `PATCH …/updateStatus` + `statusIdentifier` | `400 不能为空` |
|
||
| `PATCH …/{id}` + `propertyKey=status` | `property not found` |
|
||
| Playwright 点左侧/列表上的状态色块（`x<1100`） | 假成功、状态不落库 |
|
||
|
||
仅当 `status/transit` 不可用时，才用 UI：右侧详情状态钮（`getBoundingClientRect().x > 1100`）+ `.next-menu-item`。
|
||
|
||
## 计划开始/完成 · 提交部门/人 · 预计工时（2026-07-27 修订）
|
||
|
||
**通用字段写入（已通）：**
|
||
|
||
```http
|
||
POST /projex/api/workitem/workitem/field/value/{workitemId}?_input_charset=utf-8
|
||
Content-Type: application/x-www-form-urlencoded
|
||
|
||
fieldValueList=[{"fieldIdentifier":"79","value":"2026-07-27 12:00:00"},{"fieldIdentifier":"3132597a9718d1c282b7ba5a0c","value":"业务管理部"},{"fieldIdentifier":"9e01269e96f91fbb97d36bf5b3","value":"何苗苗"}]
|
||
```
|
||
|
||
| 字段 | fieldIdentifier | value |
|
||
|---|---|---|
|
||
| 计划开始 | `79` | `YYYY-MM-DD HH:mm:ss`（推荐正午）或 epoch ms 字符串 |
|
||
| 计划完成 | `80` | 同上 |
|
||
| 提交部门 | `3132597a9718d1c282b7ba5a0c` | 纯文本 |
|
||
| 提交人 | `9e01269e96f91fbb97d36bf5b3` | 纯文本 |
|
||
|
||
**预计工时 `101586`：禁止直接改字段**（报「不可直接修改」）。须登记：
|
||
|
||
```http
|
||
POST /projex/api/workitem/workitem/time/estimate?_input_charset=utf-8
|
||
{"workitemIdentifier":"<id>","spentTime":8,"type":"develop","description":"阶段日历工时","recordUserIdentifier":"<userId>","forCreate":false,"containsRestDay":false}
|
||
```
|
||
|
||
删除多余预估：`DELETE /projex/api/workitem/workitem/time/estimate/{workitemId}/{estimateId}`
|
||
列表：`GET …/time/estimate/list?workitemIdentifier=`
|
||
|
||
旧写法 `PATCH …/updateWorkitemFieldValue` 对上述自定义字段常 `400 不能为空`，勿再优先使用。
|
||
|
||
## 父子 / 子项 / 关联项（已通 · 2026-07-23 修订 · 子项优先）
|
||
|
||
### 关联项（【交付】强制 · ASSOCIATED）
|
||
|
||
任务详情「关联项」只认 `ASSOCIATED`。**仅【交付】**建单时 `createWorkitemRelationInfo` 必须指向**需求**：
|
||
|
||
```json
|
||
{
|
||
"createWorkitemRelationInfo": {
|
||
"relatedWorkitemIdentifier": "<需求id>",
|
||
"relatedToRelationIdentifier": "ASSOCIATED"
|
||
}
|
||
}
|
||
```
|
||
|
||
校验：
|
||
|
||
```http
|
||
GET /projex/api/workitem/v2/workitem/{交付id}/relation/workitem/list/by-relation-category?category=ASSOCIATED&isForward=true
|
||
```
|
||
|
||
`result` 含该需求即通过。
|
||
|
||
### 禁止（关联项）
|
||
|
||
| 写法 | 结果 |
|
||
|---|---|
|
||
| `relatedToRelationIdentifier=PARENT` 把交付挂需求 | 详情可能有 parent，**关联项仍为空** |
|
||
| 分析/设计只用 `ASSOCIATED→需求` + `parentIdentifier` | 关联项可能有，**交付子项仍为空**（ONEOS-246/247） |
|
||
| 建后再 `POST …/relation/record` 补关系 | Cookie 路径下常报「不能关联相同的工作项」 |
|
||
| `createWorkitemRelationList` | 不落 ASSOCIATED |
|
||
|
||
### 子项（【分析】/【设计】强制 · TASK_SUB）
|
||
|
||
「子项」页读 `PARENT_SUB` / `TASK_SUB`，分析/设计**必须**：
|
||
|
||
```json
|
||
{
|
||
"parent": "<交付id>",
|
||
"parentIdentifier": "<交付id>",
|
||
"createWorkitemRelationInfo": {
|
||
"relatedWorkitemIdentifier": "<交付id>",
|
||
"relatedToRelationIdentifier": "TASK_SUB"
|
||
}
|
||
}
|
||
```
|
||
|
||
同一 create 只能带一条 `createWorkitemRelationInfo`。
|
||
`ASSOCIATED→需求` 与 `TASK_SUB→交付` **不能同时写**。
|
||
|
||
**产品优先级：交付「子项」tab > 阶段任务「关联项」。**
|
||
交付本身仍必须 `ASSOCIATED→需求`。标准路径下分析/设计的「关联项」允许为空。
|
||
|
||
**无单快轨例外（设计双挂）：** create 用 `TASK_SUB→交付` 后，须再补 **ASSOCIATED→原始需求**，使设计详情「关联项」可见需求。
|
||
|
||
```http
|
||
POST /projex/api/workitem/workitem/{设计id}/relation/record?_input_charset=utf-8
|
||
{"relationIdentifier":"ASSOCIATED","toWorkitemIdentifier":"<需求id>"}
|
||
```
|
||
|
||
**已证伪（Cookie · 2026-07-27）：** 凡工作项**已创建**后再 `relation/record` 补挂（含 ASSOCIATED / TASK_SUB），常报「不能关联相同的工作项」；与是否已有父项无关。`createWorkitemRelationList` 亦不落 ASSOCIATED。
|
||
**可行路径：**
|
||
|
||
| 目标 | 做法 |
|
||
|---|---|
|
||
| 交付「子项」可见设计（优先） | create 带 `TASK_SUB→交付` |
|
||
| 设计「关联项」可见需求 | create 带 `ASSOCIATED→需求`（与上互斥，同 create 只能一条） |
|
||
| 双挂 | 需个人 `x-yunxiao-token` OpenAPI；Cookie 路径**不得**声称成功 |
|
||
|
||
产品默认：**子项优先**；关联项失败须在回报中标红并列出缺项。
|
||
|
||
校验子项：
|
||
|
||
```http
|
||
GET /projex/api/workitem/v2/workitem/{交付id}/relation/workitem/list/by-relation-category?category=PARENT_SUB&isForward=true
|
||
```
|
||
|
||
结果须含对应分析/设计 identifier。
|
||
|
||
校验设计关联项：
|
||
|
||
```http
|
||
GET /projex/api/workitem/v2/workitem/{设计id}/relation/workitem/list/by-relation-category?category=ASSOCIATED&isForward=true
|
||
```
|
||
|
||
`result` 须含原始需求 identifier。
|
||
|
||
### 无单快轨字段默认（2026-07-27）
|
||
|
||
| 对象 | 规则 |
|
||
|---|---|
|
||
| 【设计】描述 | 复制需求 document HTML |
|
||
| 【设计】`79`/`80` | 当日 `12:00:00` / `23:59:59`，create 后 `field/value`（勿 create 同时带 79+80） |
|
||
| 【交付】描述 | 手工同步需求正文，或原型→AutoPRD；禁止无故占位 |
|
||
| 【交付】`79` | 创建当日；不写 `80` |
|
||
| 【交付】/【设计】标签 | 与需求相同，`PATCH propertyKey=tag` |
|
||
| 需求预计工时 | `time/estimate` **spentTime=2**（先删多余预估） |
|
||
| 需求实际工时 | `POST …/workitem/time`，body 用 **`actualTime`**（非 spentTime）+ `gmtStart`/`gmtEnd` epoch ms 字符串；见 `runtime-ids.json` `fields.actual_hours` |
|
||
| 描述更新 | `PATCH …/workitem/{id}/document`，`{"content":"<html>","formatType":"RICHTEXT"}` |
|
||
|
||
## 迭代挂接（已通 · 2026-07-27 · 只挂交付）
|
||
|
||
创建迭代：`POST /projex/api/workspace/sprint`（必填 `staffIds`；可写 `capacityHours`）。
|
||
|
||
挂【交付】到迭代：
|
||
|
||
```http
|
||
PATCH /projex/api/workitem/workitem/{交付id}?_input_charset=utf-8
|
||
{"workitemIdentifier":"{交付id}","propertyKey":"sprint","propertyValue":"{sprintId}","operateType":"COVER"}
|
||
```
|
||
|
||
清空误挂（如需求）：`propertyValue:""` + `operateType:"COVER"`。
|
||
|
||
**校验**必须读 `/extra`（详情主接口常不含 sprint 字段，禁止据此判失败）：
|
||
|
||
```http
|
||
GET /projex/api/workitem/workitem/{id}/extra?_input_charset=utf-8
|
||
→ result.sprint[].identifier / name
|
||
```
|
||
|
||
产品规则：**只挂【交付】**；需求 / 分析 / 设计默认不挂（除非口令显式）。
|
||
|
||
### 极速建单注意
|
||
|
||
1. Cookie 只刷一次；全程纯 HTTP，默认**不开浏览器**。
|
||
2. 交付建完后，【分析】与【设计】**并行**创建（均 TASK_SUB→交付）；标准/快轨两树可并行。
|
||
3. 状态用 `transit` + **本地追踪 fromStatus**（禁止每次 GET）；负责人在交棒场景下**创建时即何斐**。
|
||
4. 建单 `fieldValueList` 可带计划开始 `79`；**不要**在 create 同时写 `79+80`（同日会 400）。
|
||
5. 标签必须 PATCH（create 带 tag 不落库）；可与建子任务重叠；快轨交付/设计须与需求同标签。
|
||
6. `requests.Session` keep-alive；**禁止**对共享 opener 加全局锁。
|
||
7. 脚本入口：`scripts/live_create_fast.py`（v5：快轨描述/计划/标签/工时 2+2/设计 ASSOCIATED 补挂）。
|