@cnbmtech/dsh-zentao-session 0.0.0-stage → 0.2.0

package/src/client.js

@@ -0,0 +1,816 @@
+/**
+ * ZenTao (禅道) session-based client.
+ *
+ * Uses the officially documented "session" integration path (zentao.net/book/extension-dev/1341.html)
+ * which works on legacy ZenTao versions that do NOT expose REST API v1:
+ *   1. POST /user-login.html        -> zentaosid session cookie
+ *   2. GET  /my-bug.json, /my-task.json, /bug-view-{id}.json  (t=json envelope)
+ *   3. POST /bug-confirmBug-{id}.html       (confirm a bug; uid taken from page JS)
+ *   4. POST /action-comment-bug-{id}.html   (add a remark)
+ */
+
+const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/120 Safari/537.36'
+const LOGIN_PATH = '/user-login.html'
+
+function trimSlash(value) {
+  return String(value || '').replace(/\/+$/, '')
+}
+
+export class ZentaoSessionError extends Error {}
+
+export function createZentaoSessionClient(options = {}) {
+  const baseUrl = trimSlash(options.baseUrl)
+  const timeoutMs = Number(options.timeoutMs) > 0 ? Number(options.timeoutMs) : 30000
+  const readAccount = typeof options.resolveAccount === 'function' ? options.resolveAccount : async () => options.account
+  const readPassword = typeof options.resolvePassword === 'function' ? options.resolvePassword : async () => options.password
+
+  if (!baseUrl) throw new ZentaoSessionError('baseUrl 不能为空')
+
+  const jar = new Map()
+  let loggedIn = false
+
+  function cookieHeader() {
+    return [...jar.entries()].map(([k, v]) => `${k}=${v}`).join('; ')
+  }
+
+  function absorbCookies(res) {
+    let list = []
+    try {
+      list = typeof res.headers.getSetCookie === 'function' ? res.headers.getSetCookie() : []
+    } catch {
+      list = []
+    }
+    for (const raw of list) {
+      const first = String(raw).split(';')[0]
+      const idx = first.indexOf('=')
+      if (idx > 0) jar.set(first.slice(0, idx).trim(), first.slice(idx + 1).trim())
+    }
+  }
+
+  async function raw(path, { method = 'GET', form, signal } = {}) {
+    const url = /^https?:/i.test(path) ? path : baseUrl + path
+    const headers = { 'User-Agent': UA, Accept: '*/*' }
+    const cookies = cookieHeader()
+    if (cookies) headers.Cookie = cookies
+    let body
+    if (form !== undefined) {
+      // 数组必须展开成重复键（mailto[]=a&mailto[]=b）：直接 new URLSearchParams(form)
+      // 会把数组逗号拼成单值（mailto[]=a%2Cb），禅道只会收到一个错误账号。
+      const params = new URLSearchParams()
+      for (const [key, value] of Object.entries(form)) {
+        if (value === undefined || value === null) continue
+        if (Array.isArray(value)) { for (const item of value) params.append(key, String(item)) }
+        else params.append(key, String(value))
+      }
+      body = params.toString()
+      headers['Content-Type'] = 'application/x-www-form-urlencoded'
+    }
+    // 超时/取消必须覆盖整个响应生命周期（只在响应头前生效的话，body 卡住就永久挂起）；
+    // 同时兼容「传进来的 signal 已经 abort」的情况——旧写法对已 abort 的信号不会触发回调。
+    if (signal && signal.aborted) throw new ZentaoSessionError('请求已取消')
+    const signals = [AbortSignal.timeout(timeoutMs)]
+    if (signal) signals.push(signal)
+    const combined = typeof AbortSignal.any === 'function' ? AbortSignal.any(signals) : signals[0]
+    const res = await fetch(url, { method, headers, body, redirect: 'manual', signal: combined })
+    absorbCookies(res)
+    return res
+  }
+
+  async function login(signal) {
+    const account = await readAccount()
+    const password = await readPassword()
+    if (!account || !password) {
+      throw new ZentaoSessionError('缺少禅道账号或密码（config.account/password、凭据 ZENTAO_ACCOUNT/ZENTAO_PASSWORD 或环境变量）')
+    }
+    // 不再先 jar.clear()：并发下会把别的请求刚建立的会话抹掉；新会话的 zentaosid 会覆盖旧的
+    const res = await raw(LOGIN_PATH, { method: 'POST', form: { account, password, keepLogin: '0' }, signal })
+    const body = await res.text()
+    if (!jar.has('zentaosid')) {
+      throw new ZentaoSessionError(`禅道登录失败：未取得会话 Cookie（HTTP ${res.status}）`)
+    }
+    if (/账号或密码错误|密码错误|登录失败/.test(body)) {
+      throw new ZentaoSessionError('禅道登录失败：账号或密码不正确')
+    }
+    loggedIn = true
+    return { account }
+  }
+
+  /** 单飞登录：并发调用只发一次登录 POST（否则每个调用都新建会话并互相覆盖 Cookie）。 */
+  let loginFlight = null
+  async function ensure(signal) {
+    if (loggedIn && jar.has('zentaosid')) return
+    if (!loginFlight) loginFlight = login(signal).finally(() => { loginFlight = null })
+    return loginFlight
+  }
+
+  function looksLikeLoginPage(body) {
+    return /user-login\.html/.test(body) && /name=['"]?account['"]?/.test(body)
+  }
+
+  async function html(path, { signal, retry = true } = {}) {
+    await ensure(signal)
+    let res = await raw(path, { signal })
+    if (res.status === 302 || res.status === 401) {
+      if (!retry) throw new ZentaoSessionError(`禅道会话已失效（HTTP ${res.status}）`)
+      loggedIn = false
+      await ensure(signal)
+      res = await raw(path, { signal })
+    }
+    const body = await res.text()
+    if (looksLikeLoginPage(body)) {
+      if (!retry) throw new ZentaoSessionError('禅道会话已失效（被重定向到登录页）')
+      loggedIn = false
+      await ensure(signal)
+      return html(path, { signal, retry: false })
+    }
+    return body
+  }
+
+  async function jsonPage(path, { signal } = {}) {
+    const body = await html(path, { signal })
+    let outer
+    try {
+      outer = JSON.parse(body)
+    } catch {
+      throw new ZentaoSessionError(`禅道返回非 JSON（${path}）：${body.slice(0, 160)}`)
+    }
+    if (!outer || typeof outer !== 'object') {
+      throw new ZentaoSessionError(`禅道返回结构异常（${path}）：期望对象，实际 ${typeof outer}`)
+    }
+    // 必须显式成功：缺 status 或 result=fail 时旧写法会静默返回空列表，
+    // 最终渲染成「你没有 BUG」这种**错误事实**喂给模型。
+    const ok = outer.status === 'success' || outer.result === 'success'
+    if (!ok) {
+      const reason = outer.message || outer.reason || JSON.stringify(outer).slice(0, 200)
+      throw new ZentaoSessionError(`禅道接口失败（${path}）：${reason}`)
+    }
+    if (outer.data === undefined) {
+      throw new ZentaoSessionError(`禅道返回缺少 data 字段（${path}）：${JSON.stringify(outer).slice(0, 200)}`)
+    }
+    if (typeof outer.data !== 'string') return outer.data
+    try {
+      return JSON.parse(outer.data)
+    } catch {
+      throw new ZentaoSessionError(`禅道 data 字段不是合法 JSON（${path}）：${String(outer.data).slice(0, 160)}`)
+    }
+  }
+
+  async function postForm(path, form, { signal } = {}) {
+    await ensure(signal)
+    const res = await raw(path, { method: 'POST', form, signal })
+    const body = await res.text()
+    const location = res.headers.get('location') || ''
+    // 302 本身是禅道表单提交后的正常跳转，**不能**当成会话失效；
+    // 只有落到登录页才算失效（而且非幂等写操作绝不自动重试）。
+    const loginPage = looksLikeLoginPage(body) || /user-login/i.test(location)
+    if (loginPage || res.status === 401) loggedIn = false
+    const failed = /alert\(\s*(['"])([\s\S]*?)\1\s*\)/i.exec(body)
+    return {
+      status: res.status,
+      location,
+      body,
+      alert: failed ? failed[2] : '',
+      loginPage,
+      // posted 只代表「禅道没有报错」，不代表服务端确实改了数据；要证实必须回读
+      posted: !loginPage && !failed && res.status < 400,
+    }
+  }
+
+  /** 取页面 JS 变量：兼容 var/let/const 与单双引号（禅道各版本写法不同）。 */
+  function pageVar(source, name) {
+    const m = new RegExp(`(?:var|let|const)\\s+${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`).exec(String(source))
+    return m ? m[2] : ''
+  }
+
+  /** 取令牌（uid）：取不到直接失败——带着空令牌写入只会静默不生效。 */
+  function requireUid(source) {
+    const uid = pageVar(source, 'kuid') || pageVar(source, 'uid')
+    if (!uid) throw new ZentaoSessionError('未取到禅道表单令牌（kuid），已中止写入以免产生无效操作')
+    return uid
+  }
+
+  /** 取下拉框当前选中值：属性引号单双皆可（禅道不同版本/模板渲染可能不一致）。 */
+  function selectedValue(source, name) {
+    const sel = new RegExp(`<select[^>]*name=['"]${name}['"][^>]*>([\\s\\S]*?)</select>`).exec(source)
+    if (!sel) return ''
+    const m = /<option[^>]*selected['"]?[^>]*value=['"]([^'"]*)['"]/.exec(sel[1])
+      || /<option[^>]*value=['"]([^'"]*)['"][^>]*selected/.exec(sel[1])
+    return m ? m[1] : ''
+  }
+
+  /** 取隐藏域值：同样兼容单双引号。 */
+  function hiddenValue(source, name) {
+    const m = new RegExp(`<input[^>]*name=['"]${name}['"][^>]*value=['"]([^'"]*)['"]`).exec(source)
+    return m ? m[1] : ''
+  }
+
+  /** 表单里是否存在该控件：用于「解析不到就拒绝写入」的硬判断。 */
+  function hasControl(source, name) {
+    return new RegExp(`<(?:select|input|textarea)[^>]*name=['"]${name}['"]`).test(source)
+  }
+
+  /**
+   * 取「我的地盘」某一类条目的某一浏览范围。
+   * 路径必须写成 /my-{kind}-{scope}.json：?type= 查询参数禅道**不认**（实测返回默认范围）。
+   */
+  async function myList(kind, type, signal) {
+    const scope = resolveBrowse(kind, type)
+    const data = await jsonPage(`/my-${kind}-${scope}.json`, { signal })
+    const key = kind === 'bug' ? 'bugs' : kind === 'task' ? 'tasks' : 'stories'
+    return { data, rows: listRows(data, key), scope }
+  }
+
+  return {
+    baseUrl,
+
+    async ping({ signal } = {}) {
+      await login(signal)
+      const [bugPage, taskPage] = await Promise.all([
+        jsonPage('/my-bug-assignedTo.json', { signal }),
+        jsonPage('/my-task-assignedTo.json', { signal }),
+      ])
+      // 需求接口在老版本禅道上可能不存在：取不到时给 null（"不可用"），不要伪造成 0 条
+      let myStoryCount = null
+      try {
+        myStoryCount = listRows(await jsonPage('/my-story-assignedTo.json', { signal }), 'stories').length
+      } catch { myStoryCount = null }
+      return {
+        connected: true,
+        baseUrl,
+        myBugCount: listRows(bugPage, 'bugs').length,
+        myTaskCount: listRows(taskPage, 'tasks').length,
+        myStoryCount,
+      }
+    },
+
+    /** 需求（story）列表，与 BUG/任务同一套范围语义。 */
+    async myStories({ type, limit, signal } = {}) {
+      const { data, rows } = await myList('story', type, signal)
+      const mapped = rows.map((s) => ({
+        id: String(s.id),
+        title: s.title,
+        status: s.status,
+        stage: s.stage,
+        pri: s.pri,
+        estimate: s.estimate,
+        version: s.version,
+        openedBy: s.openedBy,
+        openedDate: s.openedDate,
+        assignedTo: s.assignedTo,
+        assignedDate: s.assignedDate,
+        reviewedBy: s.reviewedBy,
+        reviewedDate: s.reviewedDate,
+        closedBy: s.closedBy,
+        closedDate: s.closedDate,
+        product: s.product,
+        productTitle: s.productTitle,
+        planTitle: s.planTitle,
+        lastEditedDate: s.lastEditedDate,
+      }))
+      return {
+        total: mapped.length,
+        recTotal: pageTotal(data, mapped.length),
+        type: resolveBrowse('story', type),
+        stories: sliceLimit(mapped, limit),
+      }
+    },
+
+    /** 需求完整详情：全字段 + 模块路径 + 相关人真名 + 操作历史。 */
+    async storyFull({ id, signal } = {}) {
+      const data = await jsonPage(`/story-view-${encodeURIComponent(id)}.json`, { signal })
+      const story = data?.story || {}
+      const users = data?.users || {}
+      return {
+        id: String(story.id ?? id),
+        baseUrl,
+        productName: story.productName || data?.productName || '',
+        modulePath: moduleNames(data?.modulePath),
+        story: normalizeFields(story),
+        users: referencedUsers(users, story, data?.actions),
+        actions: normalizeActions(data?.actions, users),
+      }
+    },
+
+    async myBugs({ type, limit, signal } = {}) {
+      const { data, rows } = await myList('bug', type, signal)
+      const all = rows
+      const mapped = all.map((b) => ({
+        id: String(b.id),
+        title: b.title,
+        status: b.status,
+        confirmed: b.confirmed,
+        pri: b.pri,
+        type: b.type,
+        assignedTo: b.assignedTo,
+        openedBy: b.openedBy,
+        openedDate: b.openedDate,
+        product: b.product,
+        project: b.project,
+      }))
+      return {
+        total: mapped.length,
+        recTotal: pageTotal(data, mapped.length),
+        type: resolveBrowse('bug', type),
+        bugs: sliceLimit(mapped, limit),
+      }
+    },
+
+    async myTasks({ type, limit, signal } = {}) {
+      const { data, rows } = await myList('task', type, signal)
+      const mapped = rows.map((t) => ({
+        id: String(t.id),
+        name: t.name,
+        status: t.status,
+        pri: t.pri,
+        estimate: t.estimate,
+        consumed: t.consumed,
+        left: t.left,
+        deadline: t.deadline,
+        project: t.project,
+        execution: t.execution,
+      }))
+      return {
+        total: mapped.length,
+        recTotal: pageTotal(data, mapped.length),
+        type: resolveBrowse('task', type),
+        tasks: sliceLimit(mapped, limit),
+      }
+    },
+
+    async bugView({ id, signal } = {}) {
+      const data = await jsonPage(`/bug-view-${encodeURIComponent(id)}.json`, { signal })
+      const bug = data?.bug || {}
+      return {
+        id: String(bug.id ?? id),
+        title: bug.title,
+        status: bug.status,
+        confirmed: bug.confirmed,
+        type: bug.type,
+        pri: bug.pri,
+        severity: bug.severity,
+        assignedTo: bug.assignedTo,
+        openedBy: bug.openedBy,
+        openedDate: bug.openedDate,
+        resolvedBy: bug.resolvedBy,
+        resolvedDate: bug.resolvedDate,
+        resolution: bug.resolution,
+        steps: bug.steps,
+        product: bug.product,
+        project: bug.project,
+        execution: bug.execution,
+      }
+    },
+
+    async bugConfirm({ id, comment, signal } = {}) {
+      const path = `/bug-confirmBug-${encodeURIComponent(id)}.html`
+      const source = await html(path, { signal })
+      const form = {
+        assignedTo: selectedValue(source, 'assignedTo'),
+        type: selectedValue(source, 'type'),
+        pri: selectedValue(source, 'pri'),
+        status: hiddenValue(source, 'status') || 'active',
+      }
+      const uid = requireUid(source)
+      // 解析不到「指派给」就中止：把空值发出去等于把指派人清空（静默的数据污染）
+      if (hasControl(source, 'assignedTo') && !form.assignedTo) {
+        throw new ZentaoSessionError('确认表单解析失败（未取到指派给），已中止写入以免清空字段')
+      }
+      form.uid = uid
+      if (comment) form.comment = comment
+      const result = await postForm(path, form, { signal })
+      // posted 只说明禅道没报错；再回读一次证实 confirmed 真的变了
+      let verified = null
+      if (result.posted) {
+        try {
+          const after = await jsonPage(`/bug-view-${encodeURIComponent(id)}.json`, { signal })
+          verified = String(after?.bug?.confirmed) === '1'
+        } catch { verified = null }
+      }
+      return {
+        id: String(id),
+        posted: result.posted,
+        verified,
+        httpStatus: result.status,
+        location: result.location,
+        alert: result.alert,
+        sentFields: Object.keys(form),
+        note: '禅道「确认」只置 confirmed=1；status 仍为 active（激活/待解决）属正常。verified=true 表示已回读证实。',
+      }
+    },
+
+    async bugComment({ id, comment, signal } = {}) {
+      if (!comment || !String(comment).trim()) throw new ZentaoSessionError('comment 不能为空')
+      const viewPath = `/bug-view-${encodeURIComponent(id)}.html`
+      const source = await html(viewPath, { signal })
+      const form = { comment }
+      form.uid = requireUid(source)
+      const result = await postForm(`/action-comment-bug-${encodeURIComponent(id)}.html`, form, { signal })
+      // 回读操作历史证实备注真的进去了（避免把「禅道没报错」当成「已写入」）
+      let verified = null
+      if (result.posted) {
+        try {
+          const data = await jsonPage(`/bug-view-${encodeURIComponent(id)}.json`, { signal })
+          const actions = Array.isArray(data?.actions) ? data.actions : []
+          const head = String(comment).trim().slice(0, 40)
+          verified = actions.some((item) => String(item?.comment || '').trim().includes(head))
+        } catch { verified = null }
+      }
+      return {
+        id: String(id),
+        posted: result.posted,
+        verified,
+        httpStatus: result.status,
+        location: result.location,
+        alert: result.alert,
+        note: 'verified=true 表示已回读操作历史确认写入；本版本禅道不支持删除备注。',
+      }
+    },
+
+    /** 缺陷完整详情：全字段 + 模块路径 + 相关人真名 + 操作历史（含备注）。 */
+    async bugFull({ id, signal } = {}) {
+      const data = await jsonPage(`/bug-view-${encodeURIComponent(id)}.json`, { signal })
+      const bug = data?.bug || {}
+      const users = data?.users || {}
+      return {
+        id: String(bug.id ?? id),
+        baseUrl,
+        productName: data?.productName || '',
+        projectName: bug.projectName || '',
+        modulePath: moduleNames(data?.modulePath),
+        bug: normalizeFields(bug),
+        users: referencedUsers(users, bug, data?.actions),
+        actions: normalizeActions(data?.actions, users),
+      }
+    },
+
+    /** 任务完整详情：全字段 + 相关人真名 + 操作历史。 */
+    async taskFull({ id, signal } = {}) {
+      const data = await jsonPage(`/task-view-${encodeURIComponent(id)}.json`, { signal })
+      const task = data?.task || {}
+      const users = data?.users || {}
+      return {
+        id: String(task.id ?? id),
+        baseUrl,
+        projectName: task.projectName || data?.project?.name || '',
+        modulePath: moduleNames(data?.modulePath),
+        task: normalizeFields(task),
+        users: referencedUsers(users, task, data?.actions),
+        actions: normalizeActions(data?.actions, users),
+      }
+    },
+
+    /** 取禅道文件（缺陷截图/附件）。仅允许 /file-read-* 与 /file-download-* 白名单路径。 */
+    async fetchFile({ path, signal } = {}) {
+      const target = String(path || '')
+      // 规范化后再校验：否则 /file-read-1/../../index.php 之类的点段会被上游解析到别处
+      let resolved
+      try {
+        resolved = new URL(target, baseUrl)
+      } catch {
+        throw new ZentaoSessionError(`文件路径无法解析：${target.slice(0, 80)}`)
+      }
+      const base = new URL(baseUrl)
+      if (resolved.origin !== base.origin) throw new ZentaoSessionError(`文件路径越界（跨源）：${target.slice(0, 80)}`)
+      if (!FILE_PATH_PATTERN.test(resolved.pathname)) {
+        throw new ZentaoSessionError(`不允许的文件路径：${target.slice(0, 80)}`)
+      }
+      await ensure(signal)
+      const res = await raw(resolved.pathname, { signal })
+      if (res.status !== 200) throw new ZentaoSessionError(`取文件失败：HTTP ${res.status}`)
+      const contentType = String(res.headers.get('content-type') || '').split(';')[0].trim().toLowerCase()
+      // 先看 content-length，避免把超大文件整块读进内存
+      const declared = Number(res.headers.get('content-length') || 0)
+      if (Number.isFinite(declared) && declared > MAX_FILE_BYTES) {
+        throw new ZentaoSessionError(`文件过大（声明 ${declared} 字节，上限 ${MAX_FILE_BYTES}）`)
+      }
+      const buffer = Buffer.from(await res.arrayBuffer())
+      if (buffer.length > MAX_FILE_BYTES) throw new ZentaoSessionError(`文件过大（${buffer.length} 字节）`)
+      return { contentType, buffer }
+    },
+
+    /** 用给定账号密码试登录（不改动当前会话），用于首次安装的登录校验。 */
+    /** 当前会话 id：用于在浏览器里以 ?zentaosid= 免登录打开禅道页面。 */
+    async currentSessionId({ signal } = {}) {
+      await ensure(signal)
+      return jar.get('zentaosid') || ''
+    },
+
+    async login({ baseUrl: targetBase, account, password, signal } = {}) {
+      const probe = createZentaoSessionClient({
+        baseUrl: trimSlash(targetBase),
+        account: String(account || ''),
+        password: String(password || ''),
+        timeoutMs,
+      })
+      const info = await probe.ping({ signal })
+      return { baseUrl: trimSlash(targetBase), account: String(account || ''), ...info }
+    },
+
+    /** 当前 BUG 在禅道里可执行的操作（解析详情页里的 /bug-{op}-{id}.html 链接）。 */
+    async bugOps({ id, signal } = {}) {
+      const source = await html(`/bug-view-${encodeURIComponent(id)}.html`, { signal })
+      const found = new Set()
+      const pattern = new RegExp(`/bug-([a-zA-Z][a-zA-Z0-9]*)-${String(id).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.html`, 'g')
+      for (const match of source.matchAll(pattern)) found.add(match[1])
+      for (const skip of ['view', 'create', 'browse', 'export', 'report']) found.delete(skip)
+      // 保险：破坏性操作不暴露给面板。实测本实例只会出现 confirmBug/assignTo/resolve/edit，
+      // 但 ops 是从详情页链接抓来的，别的实例/权限若列出删除类操作，这里先挡住。
+      for (const op of [...found]) {
+        if (/^(delete|remove|erase|trash|batch)/i.test(op)) found.delete(op)
+      }
+      return { id: String(id), ops: [...found] }
+    },
+
+    /** 取某个操作的表单定义（字段、选项、默认值），与禅道弹窗同源。 */
+    async bugForm({ id, op, signal } = {}) {
+      const path = `/bug-${String(op).replace(/[^a-zA-Z0-9]/g, '')}-${encodeURIComponent(id)}.html`
+      const source = await html(path, { signal })
+      const parsed = parseZentaoForm(source)
+      return { id: String(id), op, path, uid: pageVar(source, 'kuid'), ...parsed }
+    },
+
+    /** 按禅道表单提交操作（确认/解决/关闭/激活/指派/编辑）。 */
+    async bugAction({ id, op, values, signal } = {}) {
+      const safeOp = String(op || '').replace(/[^a-zA-Z0-9]/g, '')
+      if (!safeOp) throw new ZentaoSessionError('缺少操作名')
+      // 不再用清洗后的名字静默改写端点：名字里有非法字符就直接拒绝
+      if (safeOp !== String(op || '')) throw new ZentaoSessionError(`操作名含非法字符，已拒绝：${String(op).slice(0, 40)}`)
+      const path = `/bug-${safeOp}-${encodeURIComponent(id)}.html`
+      const source = await html(path, { signal })
+      const form = {}
+      for (const [key, value] of Object.entries(values || {})) {
+        if (key === 'uid') continue
+        if (Array.isArray(value)) form[key] = value.map((item) => String(item))
+        else if (value !== undefined && value !== null) form[key] = String(value)
+      }
+      form.uid = requireUid(source)
+      const result = await postForm(path, form, { signal })
+      return {
+        id: String(id),
+        op: safeOp,
+        posted: result.posted,
+        httpStatus: result.status,
+        location: result.location,
+        alert: result.alert,
+        sentFields: Object.keys(form),
+      }
+    },
+  }
+}
+
+/**
+ * 「我的地盘」列表的浏览范围白名单。
+ * 值必须与禅道自己 tab 链接里的写法逐字一致：写错时禅道**不报错**，
+ * 而是静默退化成未过滤的全量列表（实测把 reviewedBy 写成 reviewBy，
+ * recTotal 从 137 变成 27428），所以未知值一律抛错、绝不发出去。
+ */
+const BROWSE_TYPES = {
+  bug: ['assignedTo', 'openedBy', 'resolvedBy', 'closedBy'],
+  task: ['assignedTo', 'openedBy', 'finishedBy', 'closedBy', 'canceledBy'],
+  story: ['assignedTo', 'openedBy', 'reviewedBy', 'closedBy'],
+}
+
+/** 校验并返回浏览范围；缺省 assignedTo（= 指派给我，与禅道 tab 默认一致）。 */
+function resolveBrowse(kind, type) {
+  const allowed = BROWSE_TYPES[kind]
+  if (!allowed) throw new ZentaoSessionError(`未知条目类型：${kind}`)
+  const wanted = type === undefined || type === null || type === '' ? 'assignedTo' : String(type)
+  if (!allowed.includes(wanted)) {
+    throw new ZentaoSessionError(`未知范围 ${wanted}（${kind} 支持：${allowed.join('/')}）`)
+  }
+  return wanted
+}
+
+/** 列表容器归一化：BUG/任务返回数组，需求返回 id→对象的 map（实测差异），两种都要吃。 */
+function listRows(data, key) {
+  const raw = data ? data[key] : undefined
+  if (Array.isArray(raw)) return raw
+  if (raw && typeof raw === 'object') return Object.values(raw)
+  return []
+}
+
+/** 服务端声明的总条数（本页只有前 N 条时，界面要能说清"共多少条"）。 */
+function pageTotal(data, fallback) {
+  const value = Number(data && data.pager && data.pager.recTotal)
+  return Number.isFinite(value) && value > 0 ? value : fallback
+}
+
+/** limit<=0/未给 时返回全部（工具默认条数由调用方决定）。 */
+function sliceLimit(rows, limit) {
+  return typeof limit === 'number' && limit > 0 ? rows.slice(0, limit) : rows
+}
+
+/** 只允许禅道自身的文件存取路径：带 $ 锚点，避免 /file-read-1/../../x 这类穿越。 */
+const FILE_PATH_PATTERN = /^\/file-(read|download)-\d+(?:\.[a-z0-9]+)?$/i
+const MAX_FILE_BYTES = 8 * 1024 * 1024
+
+/** 把模块链拼成 "投资企业侧应用 / 危险作业管理"。 */
+function moduleNames(modulePath) {
+  if (!Array.isArray(modulePath)) return ''
+  return modulePath.map((item) => item && item.name).filter(Boolean).join(' / ')
+}
+
+/** 去掉空值字段，保证返回的是 lossless JSON。 */
+function normalizeFields(source) {
+  const out = {}
+  for (const [key, value] of Object.entries(source || {})) {
+    if (value === null || value === undefined || value === '') continue
+    if (Array.isArray(value)) {
+      out[key] = value.length === 0 ? [] : value
+      continue
+    }
+    out[key] = typeof value === 'object' ? JSON.parse(JSON.stringify(value)) : value
+  }
+  return out
+}
+
+/** 汇总本次详情涉及到的账号真名（禅道 users 表有 700+ 条，只带相关的）。 */
+function referencedUsers(users, record, actions) {
+  const accounts = new Set()
+  for (const key of ['openedBy', 'assignedTo', 'resolvedBy', 'closedBy', 'finishedBy', 'canceledBy', 'lastEditedBy', 'startedBy']) {
+    if (record && typeof record[key] === 'string' && record[key]) accounts.add(record[key])
+  }
+  if (record && typeof record.assignedToRealName === 'string' && record.assignedToRealName) accounts.add(record.assignedTo)
+  for (const action of Object.values(actions || {})) {
+    if (action && typeof action.actor === 'string' && action.actor) accounts.add(action.actor)
+  }
+  const out = {}
+  for (const account of accounts) {
+    const realname = users && users[account]
+    out[account] = typeof realname === 'string' && realname ? realname : account
+  }
+  return out
+}
+
+/** 操作历史：按时间倒序，附上操作人真名。 */
+function normalizeActions(actions, users) {
+  return Object.values(actions || {})
+    .filter((action) => action && typeof action === 'object')
+    .map((action) => ({
+      id: String(action.id || ''),
+      action: String(action.action || ''),
+      actor: String(action.actor || ''),
+      actorName: (users && users[action.actor]) || String(action.actor || ''),
+      date: String(action.date || ''),
+      comment: stripTags(String(action.comment || '')),
+      history: Array.isArray(action.history) ? action.history.length : 0,
+    }))
+    .sort((left, right) => String(right.date).localeCompare(String(left.date)))
+}
+
+/** 把 HTML 片段压成纯文本（操作历史里的备注可能是富文本）。 */
+function stripTags(html) {
+  return String(html)
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/p>/gi, '\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+/** 禅道必填字段（服务端以 JS 校验收尾，HTML 上没有标记，按标签兜底）。 */
+const REQUIRED_FIELDS = new Set(['解决方案'])
+/** 条件显示的行：行 id → 依赖字段与取值（与禅道 JS 的显隐逻辑一致）。
+ *  实测该实例：解决版本默认可见，选「重复bug」时隐藏；重复ID 仅在「重复bug」时出现。 */
+const SHOW_WHEN = {
+  duplicateBugBox: { field: 'resolution', in: ['duplicate'] },
+  newBuildProjectBox: { field: 'resolution', notIn: ['duplicate'] },
+}
+
+/**
+ * 解析禅道表单页，得到字段定义（名称/标签/类型/默认值/下拉选项/是否宽行/是否条件显示）。
+ * 用于在面板里渲染与禅道弹窗一致的确认、解决、关闭等操作界面。
+ */
+function parseZentaoForm(source) {
+  const main = /<div id='mainContent'[\s\S]*?<form([^>]*)>([\s\S]*?)<\/form>/i.exec(String(source))
+  if (!main) return { title: '', fields: [] }
+  const titleMatch = /<h2>([\s\S]*?)<\/h2>/i.exec(String(source))
+  const title = titleMatch ? stripTags(titleMatch[1]).replace(/\s+/g, ' ').slice(0, 120) : ''
+  const body = main[2]
+  const fields = []
+
+  // 隐藏域：除 uid（每次请求现取）外全部保留，禅道表单依赖它们
+  for (const tag of body.matchAll(/<input[^>]*type=['"]hidden['"][^>]*>/gi)) {
+    const name = /name=['"]([^'"]+)['"]/.exec(tag[0])
+    if (!name || name[1] === 'uid') continue
+    fields.push({
+      name: name[1],
+      label: name[1],
+      type: 'hidden',
+      value: (/value=['"]([^'"]*)['"]/.exec(tag[0]) || [])[1] || '',
+    })
+  }
+
+  let rowIndex = 0
+  for (const row of body.matchAll(/<tr[^>]*>([\s\S]*?)<\/tr>/gi)) {
+    if (/form-actions/i.test(row[0])) continue
+    const th = /<th[^>]*>([\s\S]*?)<\/th>/i.exec(row[1])
+    if (!th) continue
+    const label = stripTags(th[1]).replace(/\s+/g, ' ').trim()
+    const cell = row[1].slice(row[1].indexOf('</th>'))
+    // 行属性：条件显示（禅道把 id/class 放在 tr 或 td 上）与整行隐藏
+    const rowAttrs = row[0].slice(0, row[0].indexOf('>') + 1)
+    const rowId = (/id=['"]([^'"]+)['"]/.exec(row[0]) || [])[1] || ''
+    const rowHidden = /\bclass=['"][^'"]*\bhide\b/i.test(rowAttrs)
+    // 整行只有隐藏域时（如「Bug状态」行）：不渲染，值已由隐藏域循环带走
+    const onlyHiddenInput = /<input[^>]*type=['"]hidden['"][^>]*>/i.test(cell)
+      && !/<select|<textarea|<input(?![^>]*type=['"]hidden['"])/i.test(cell)
+    if (onlyHiddenInput) continue
+    if (/file-input-list|type=['"]file['"]/i.test(cell)) continue // 附件：插件不支持上传，整行不渲染
+
+    const wide = /<td[^>]*colspan=['"]?([2-9])/i.test(cell)
+    const required = /\bclass=['"][^'"]*\brequired\b/i.test(cell) || REQUIRED_FIELDS.has(label)
+    const meta = {
+      ...(wide ? { wide: true } : {}),
+      ...(rowHidden ? { hidden: true } : {}),
+      ...(SHOW_WHEN[rowId] ? { showWhen: SHOW_WHEN[rowId] } : {}),
+    }
+
+    // 收集该行内所有控件（禅道一行可能有多个：所属项目 + 解决版本 + 创建 + 新版本名称）
+    rowIndex++
+    const rowKey = `r${rowIndex}`
+    const controls = []
+    const escapeRe = (value) => String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    /** 控件是否位于「勾选创建后才出现」的容器里（td/div id 以 newBuild 开头：所属项目、新版本名称）。 */
+    const isCreateOnly = (name) => new RegExp(`<(?:div|td)[^>]*id='newBuild[^']*'[^>]*>(?:(?!</(?:div|td)>)[\\s\\S])*?name='${escapeRe(name)}'`).test(cell)
+    /** 控件前的 input-group 前缀文字（如「所属项目」）。 */
+    const addonOf = (name) => {
+      const hit = new RegExp(`<span class='input-group-addon'>([^<]*)</span>[\\s\\S]{0,240}?name='${escapeRe(name)}'`).exec(cell)
+      return hit ? hit[1].trim() : ''
+    }
+
+    for (const select of cell.matchAll(/<select[^>]*name=['"]([^'"]+)['"]([^>]*)>([\s\S]*?)<\/select>/gi)) {
+      const options = [...select[3].matchAll(/<option[^>]*value=['"]([^'"]*)['"]([^>]*)>([\s\S]*?)<\/option>/gi)]
+        .map((option) => ({
+          value: option[1],
+          label: stripTags(option[3]).replace(/\s+/g, ' ').trim(),
+          selected: /selected/i.test(option[2]),
+        }))
+      controls.push({
+        name: select[1],
+        type: 'select',
+        multiple: /multiple/i.test(select[2]),
+        options,
+        value: (options.find((option) => option.selected) || {}).value || '',
+      })
+    }
+    for (const textarea of cell.matchAll(/<textarea[^>]*name=['"]([^'"]+)['"]([^>]*)>([\s\S]*?)<\/textarea>/gi)) {
+      controls.push({
+        name: textarea[1],
+        type: 'textarea',
+        rows: Number((/rows=['"]?(\d+)/i.exec(textarea[2]) || [])[1] || 6),
+        value: textarea[3].replace(/\s+$/, ''),
+      })
+    }
+    for (const input of cell.matchAll(/<input[^>]*>/gi)) {
+      const tag = input[0]
+      if (/type=['"]hidden['"]/i.test(tag) || /type=['"]file['"]/i.test(tag)) continue
+      const name = /name=['"]([^'"]+)['"]/.exec(tag)
+      if (!name) continue
+      const isCheckbox = /type=['"]checkbox['"]/i.test(tag)
+      const around = cell.slice(Math.max(0, cell.indexOf(tag) + tag.length), cell.indexOf(tag) + tag.length + 80)
+      controls.push({
+        name: name[1],
+        type: isCheckbox ? 'checkbox' : (/type=['"]date['"]/.test(tag) ? 'date' : 'text'),
+        value: (/value=['"]([^'"]*)['"]/.exec(tag) || [])[1] || '',
+        checked: isCheckbox ? /\bchecked\b/i.test(tag) : undefined,
+        placeholder: (/placeholder=['"]([^'"]*)['"]/.exec(tag) || [])[1] || '',
+        // 勾选框文案：禅道写成 <input ...><label for='x'>创建</label>
+        inlineText: isCheckbox ? (stripTags(around).replace(/\s+/g, ' ').trim().split(/[<]/)[0] || '') : '',
+      })
+    }
+    if (controls.length === 0) continue
+
+    // 主控件：优先取「非勾选创建才出现」的第一个控件（避免把「所属项目」当成主字段）
+    const plainControls = controls
+      .map((control, index) => ({ control, index }))
+      .filter((item) => item.control.type !== 'checkbox')
+    const mainEntry = plainControls.find((item) => !isCreateOnly(item.control.name)) || plainControls[0]
+    const mainIndex = mainEntry ? mainEntry.index : 0
+    controls.forEach((control, index) => {
+      const isMain = index === mainIndex
+      const createOnly = control.type !== 'checkbox' && isCreateOnly(control.name)
+        && controls.some((item) => item.name === 'createBuild')
+      fields.push({
+        ...control,
+        label: isMain ? label : '',
+        rowKey,
+        primary: isMain,
+        addon: isMain ? '' : addonOf(control.name),
+        required: isMain ? required : false,
+        ...meta,
+        ...(createOnly ? { showWhenChecked: 'createBuild' } : {}),
+        ...(control.type === 'checkbox' ? {
+          inline: true,
+          label: control.inlineText || control.name,
+          defaultChecked: control.checked === true,
+        } : {}),
+      })
+    })
+  }
+  return { title, fields }
+}