禅道项目需求管理（HTTP API 版）

通过禅道页面内置 HTTP 接口和 REST API 管理项目需求，支持创建/编辑/删除/查询，确保需求正确关联到项目。同时支持需求文档编写与禅道需求的双向同步。

核心工作流：需求文档 ↔ 禅道需求

需求文档(.md)  ──创建──>  禅道需求(story)
     ↑                        │
     └────回写禅道ID──────────┘
     ↑                        │
     └──更新文档──>──询问是否同步──>──编辑禅道需求

1. 需求文档编写

当用户要求编写或更新需求文档时：

1. 遵循工作区规则：仅当用户确认功能OK并主动说明时，才更新需求文档
2. 阅读需求文档：先读取 config.json 中 requirements_doc 指定的文档路径
3. 按文档格式编写：保持现有文档的章节结构和格式
4. 禅道ID标注：每个功能标题格式为 ### F001 - 功能名称（#禅道ID）
   - 已创建禅道需求的：标注ID，如 ### F001 - 多人分工（#155）
   - 未创建的：不标注，如 ### F005 - 登录认证

2. 文档更新后询问同步

需求文档更新完成后，主动询问用户是否需要同步到禅道：

> "需求文档已更新。是否需要同步到禅道？"

3. 同步逻辑

根据需求文档中的禅道ID标注，自动判断操作类型：

4. 禅道ID回写

创建需求成功后，自动更新需求文档中对应功能标题：
- 创建前：### F005 - 开始编写校验
- 创建后：### F005 - 开始编写校验（#172）

5. 描述转换规则

将需求文档的 Markdown 内容转为禅道 HTML 格式，按以下结构组织描述内容：

Markdown → HTML 映射：

转换时遵循写作规范：不写英文字段名、不写UI样式细节。

配置

在 config.json 中配置：

{
  "zentao_url": "http://your-zentao-server/zentao",
  "zentao_user": "your_username",
  "zentao_password": "your_password",
  "default_project": 0,
  "default_product": 0,
  "requirements_doc": "requirements.md"
}

功能列表

1. 创建需求

# 单条创建
python create_story_api.py create --title "需求标题" --desc "描述" --pri 3

# 批量创建
python create_story_api.py create --input stories.json

创建接口：POST /story-create-{product}-all-{module}-0-{project}-0-0-0--story.html

URL 中的 {project} 参数确保需求关联到项目。

2. 编辑需求

# 修改标题和优先级
python create_story_api.py edit --id 163 --title "新标题" --pri 1

# 修改描述
python create_story_api.py edit --id 163 --desc "新的需求描述"

# 从文件读取描述（推荐用于HTML长文本）
python create_story_api.py edit --id 163 --desc-file description.html

# 修改状态为激活
python create_story_api.py edit --id 163 --status active

编辑接口：POST /story-edit-{storyID}-default-story.html?zin=1

编辑前会自动查询当前需求数据，仅提交修改的字段，未修改字段保留原值。

3. 删除需求

python create_story_api.py delete --id 166

删除接口：DELETE /api.php/v1/stories/{storyID}（REST API）

请求头需携带 Token 认证。

4. 查询需求

python create_story_api.py get --id 163

查询接口：GET /api.php/v1/stories/{storyID}

5. 同步需求文档到禅道

# 扫描需求文档，同步所有功能到禅道（有ID的编辑，无ID的创建）
python create_story_api.py sync

# 只同步指定功能编号
python create_story_api.py sync --features F001 F002 F003

# 只做试运行（不实际操作禅道，仅显示计划）
python create_story_api.py sync --dry-run

同步逻辑：读取需求文档，解析每个功能标题中的禅道ID标注：
- 有 （#ID） → 编辑该禅道需求
- 无标注 → 创建禅道需求，创建成功后回写ID到文档

描述字段格式

写作规范

1. 不写英文字段名（如 readinessStatus、uploadedFiles），这些属于技术实现，由前端/后端把控
2. 不写UI样式细节（如色值 #e74c3c、字号 11px、像素宽度 48px），这些由UI设计师把控
3. 可以写字段中文名和属性（如类型、是否必填、默认值、说明），用表格展示
4. 用HTML格式让描述更直观，禅道富文本编辑器支持 HTML

HTML 格式模板

<h3>用户故事</h3>
<p>作为<b>编制人员</b>，我希望<b>功能描述</b>，以便<b>业务价值</b>。</p>

<h3>前置条件</h3>
<ul>
<li>条件1</li>
<li>条件2</li>
</ul>

<h3>功能要点</h3>
<ol>
<li>步骤1</li>
<li>步骤2</li>
<li>步骤3</li>
</ol>

<h3>字段说明</h3>
<table border="1" cellpadding="4" cellspacing="0" style="border-collapse:collapse;width:100%;">
<tr><th>字段</th><th>类型</th><th>必填</th><th>默认值</th><th>说明</th></tr>
<tr><td>字段中文名</td><td>类型</td><td>是/否</td><td>默认值</td><td>说明</td></tr>
</table>

<h3>注意事项</h3>
<ul>
<li>注意1</li>
<li>注意2</li>
</ul>

支持的 HTML 标签

格式选择逻辑

• 描述包含 HTML 块级标签（<h3>, <ul>, <ol>, <table> 等）→ 直接使用原始 HTML
• 描述为纯文本 → 按换行分段，每段自动包裹 <p><span>...</span></p>

认证原理

1. 通过 /api.php/v1/tokens 获取 token
2. 该 token 同时作为 zentaosid cookie（用于页面内置接口）
3. 也作为 Token 请求头（用于 REST API）

接口详情

创建接口

POST /story-create-{product}-{branch}-{module}-{parent}-{project}-{execution}-{plan}-{storyType}--story.html
Content-Type: multipart/form-data
Cookie: zentaosid={token}
X-Requested-With: XMLHttpRequest

表单字段：

关键：必须包含 files[] 空文件字段，否则请求失败。

编辑接口

POST /story-edit-{storyID}-default-story.html?zin=1
Content-Type: multipart/form-data
Cookie: zentaosid={token}
X-Requested-With: XMLHttpRequest

表单字段与创建类似，额外字段：

删除接口

DELETE /api.php/v1/stories/{storyID}
Token: {token}

响应：{"message": "success"}

查询接口

GET /api.php/v1/stories/{storyID}
Token: {token}

示例对话

用户： 在禅道创建一个需求"章节分工功能"

AI：
1. 登录获取 token
2. 创建需求：title="章节分工功能", pri=3, status=draft
3. 查询获取需求ID
4. 返回：已创建需求 #168（草稿），链接：http://xxx/zentao/projectstory-view-168-45.html

用户： 把需求 #168 的优先级改为 1

AI：
1. 登录获取 token
2. 查询需求 #168 当前数据
3. 编辑：pri=1
4. 返回：编辑需求 #168 成功

用户： 删除需求 #167

AI：
1. 登录获取 token
2. 删除需求 #167
3. 返回：删除需求 #167 成功

文件结构

zentao-story-api/
├── SKILL.md                # 本文件
├── config.json             # 配置文件（需填写真实信息）
└── scripts/
    └── create_story_api.py  # 管理脚本（创建/编辑/删除/查询）

注意事项

1. 认证方式：token 同时用于 cookie（内置接口）和请求头（REST API）
2. 请求格式：创建和编辑必须用 multipart/form-data（因为有 files[] 字段）
3. 空文件字段：files[] 必须存在但为空
4. 项目关联：创建时 URL 中的 {project} 参数确保需求关联到项目
5. 草稿状态：新建需求默认 status=draft
6. 描述格式：描述必须用 HTML 格式（<p><span>文本</span></p>）
7. 编辑合并：编辑时自动查询当前数据，未修改字段保留原值
8. Token有效期：约2小时，批量操作无需重复获取
9. 双向同步：需求文档中通过 （#ID） 标注禅道需求ID，创建新需求后自动回写ID到文档
10. 需求文档规则：仅当用户确认功能OK并主动说明时，才更新需求文档
11. 同步询问：更新需求文档后主动询问用户是否需要同步到禅道
12. 创建接口选择：创建需求使用内置页面接口而非官方 RESTful API，原因是项目类型为【项目型】而非【产品型】时，创建项目需求池无需填写关联产品字段，但 RESTful API 中关联产品为必填，因此创建功能采用内置页面接口
13. --desc-file 参数：当描述内容较长或包含HTML时，建议使用 --desc-file 从文件读取，避免命令行解析问题

AI 行为指南

当用户要求编写/更新需求文档时

1. 先读取需求文档，了解当前内容和已有禅道ID标注
2. 按文档现有格式和规范编写需求内容
3. 更新文档后，主动询问："需求文档已更新，是否需要同步到禅道？"
4. 如用户确认同步，执行 sync 流程

当用户要求创建禅道需求时

1. 检查需求文档中该功能是否已有禅道ID
2. 如有ID → 提醒用户该需求已存在于禅道，询问是否编辑
3. 如无ID → 创建需求，成功后自动回写ID到需求文档标题

当用户要求同步需求时

1. 读取需求文档，解析所有功能及禅道ID标注
2. 列出同步计划（哪些要创建、哪些要编辑）
3. 确认后逐条执行，创建成功的自动回写ID

依赖要求

• Python 3.7+
• requests 库（pip install requests）