{
  "module": "kanban",
  "version": "1.1",
  "purpose": "看板任务系统。两个接口层：(1) kanban_api.py (:9580) 提供跨机器 Agent 完整读写 REST API；(2) dashboard.py (:5803) 'Kanban' tab 只读展示看板任务列表，支持按状态和负责人筛选，实时刷新。",
  "ui_location": "主菜单 → Kanban tab (dashboard :5803)",

  "human_help": {
    "title": "Kanban 看板",
    "description": [
      "本页面展示系统中的看板任务卡片，每个任务包含标题、状态标签、负责人和创建日期。",
      "顶部筛选器可按状态和负责人过滤任务列表。",
      "任务卡片可点击展开/收起详细描述。"
    ],
    "usage": [
      "1. 使用顶部筛选器（All Status / All）缩小任务范围",
      "2. 点击任务卡片展开详情（支持 multi-line 描述）",
      "3. 状态颜色标识：绿色=Ready、黄色=In Progress、红色=Blocked、灰色=Done",
      "4. 页面每 15s 自动刷新任务列表"
    ],
    "troubleshooting": [
      "如果任务列表为空：检查 Hermes kanban.db 是否存在（~/.hermes/kanban.db）",
      "如果筛选器无反应：页面自动刷新后会重置筛选状态 — 请确保在刷新间隔内操作"
    ],
    "related": "G 规范定义开发流程和任务管理规范；Agent 处理卡片流程见 docs/KANBAN-HANDLER-PROTOCOL.md"
  },

  "ai_spec": {
    "service_ports": [
      {"port": 9580, "service": "kanban_api.py", "host": "0.0.0.0", "purpose": "跨机器 Agent 完整读写 API（直接操作 ~/.hermes/kanban.db）"},
      {"port": 5803, "service": "dashboard.py", "host": "246", "purpose": "Dashboard Kanban tab 只读展示"}
    ],
    "apis": [
      {"method": "GET", "path": "/api/kanban", "port": 5803, "returns": "{ok, tasks[{id,title,body,status,assignee,created_at}]}", "description": "Dashboard 只读：返回全部任务列表"},
      {"method": "POST", "path": "/kanban/create", "port": 9580, "returns": "{ok, task_id, raw}", "description": "创建卡片 (title 必填, assignee/body 可选)"},
      {"method": "POST", "path": "/kanban/create_xmpp", "port": 9580, "returns": "{ok, task_id, notified}", "description": "创建卡片并 XMPP 通知核心群 (coregroup@conference.yoin.fun)"},
      {"method": "POST", "path": "/kanban/list", "port": 9580, "returns": "{tasks[]}", "description": "列表 (可选 status/assignee 筛选)"},
      {"method": "POST", "path": "/kanban/show", "port": 9580, "returns": "{id,title,body,status,assignee,created_by,created_at}", "description": "单卡详情"},
      {"method": "POST", "path": "/kanban/update", "port": 9580, "returns": "{ok}", "description": "更新 status/assignee (id 必填)"},
      {"method": "POST", "path": "/kanban/comment", "port": 9580, "returns": "{ok}", "description": "评论卡片 (id/body 必填, author 可选) + XMPP 通知"},
      {"method": "POST", "path": "/kanban/comments", "port": 9580, "returns": "{comments[]}", "description": "读某卡片评论 (id 必填)"}
    ],
    "dependencies": [
      "看板数据存于 ~/.hermes/kanban.db (SQLite, 表: tasks / task_comments)",
      "dashboard.py 直接读同一 kanban.db 做只读展示",
      "kanban_api.py 的 create/comment 通过 hermes CLI 或 XMPP 桥 (127.0.0.1:5804) 通知核心群"
    ],
    "constraints": [
      "页面每 15s 轮询刷新 (setInterval(fK,15000))",
      "筛选器状态通过 DOM 直接读取 (document.getElementById)",
      "任务卡片展开使用 onclick 切换 expanded class — max-height 从 60px ↔ none 切换",
      "Agent 处理卡片：拉详情用 POST /kanban/show（不是 GET /api/kanban/t_xxx，该端点不存在）",
      "kanban_api.py 全部端点均为 POST（含 list/show/comments 这类读操作）"
    ],
    "tests": [
      {"id": "KB01", "name": "/api/kanban 返回任务列表", "endpoint": "GET /api/kanban (:5803)"},
      {"id": "KB02", "name": "筛选器过滤正确", "endpoint": "n/a (frontend)"},
      {"id": "KB03", "name": "kanban_api 创建任务", "endpoint": "POST /kanban/create (:9580)"},
      {"id": "KB04", "name": "kanban_api 更新状态", "endpoint": "POST /kanban/update (:9580)"},
      {"id": "KB05", "name": "kanban_api 评论", "endpoint": "POST /kanban/comment (:9580)"}
    ],
    "related_files": [
      "scripts/kanban_api.py — :9580 完整读写 API",
      "gateway/scripts/templates/dashboard.html — fK() 渲染函数",
      "gateway/scripts/dashboard.py — /api/kanban 只读端点",
      "gateway/scripts/specs/kanban.json — 本 spec 文件",
      "docs/KANBAN-HANDLER-PROTOCOL.md — Agent 处理卡片协议",
      "skills/kanban-handler/SKILL.md — handler session 工作流"
    ]
  }
}
