bim-issue-platform

使用手册

页面导览

登录后侧边栏（不同角色可见项不同）：

页面 路由 用途
首页 / 当前项目指标卡（总数 / 未关闭 / 已关闭 / 紧急未关闭）+ 最近问题
我的项目 /me 我参与的项目（卡片含项目编号与项目 ID，点击可复制；一键直达该项目问题列表）+ 我的问题（「我提的 / 交给我的」两档）
问题列表 /issues 核心工作页：筛选 / 排序 / 分页 / 批量操作 / 导出 / 详情抽屉
项目说明 /project 概况 / 经济技术指标 / 各专业设计说明（Markdown 展示，AI 写入带徽标）
项目设置 /project-settings 项目参数 / 成员管理 / 分类体系（仅项目负责人与专业负责人可见）
操作记录 /audit-logs 当前项目最近 20 条写操作留痕（AI 代执行的会显示发令人）
平台管理 /admin 建项目 / 管账号（仅平台管理员可见）
个人设置 /settings 资料 / 头像 / 改密 / API Token（侧栏无此项，从左下角头像菜单进入）

顶栏：项目切换器（支持按项目名 / 编号搜索）· 全局搜索（Ctrl+K）· 用户菜单。未加入任何项目的账号只能进「个人设置」（与「平台管理」），其余入口自动隐藏。

角色与权限

两层角色体系

角色代码 中文名 一句话权限
project_owner 项目负责人 项目内最高：全部问题可增删改、可管理成员 / 分类 / 项目说明 / 参数、可任命专业负责人
civil_lead 土建专业负责人 与机电专业负责人权限完全相等（拆分仅为称谓标识）；项目内所有问题都能动（不限本专业）+ 全部配置权；不可任命 / 撤销专业负责人
mep_lead 机电专业负责人 同上
engineer 工程师 只能编辑自己创建的问题；不可删除、不可变更执行人
client 甲方 可答复、可见项目内全部问题；不可创建 / 编辑 / 删除 / 关闭 / 导出
collaborator 协同方 同甲方

权限矩阵（问题域）

动作 项目负责人 专业负责人 工程师 甲方 / 协同方
查看列表 / 详情 ✅ ✅ ✅ ✅
创建问题 ✅ ✅ ✅ ⛔
编辑字段 ✅ 全部 ✅ 全部 ⚠️ 仅自己创建的 ⛔
答复 ✅ ✅ ✅ ✅（唯一写入口）
删除问题 ✅ ✅ ⛔ ⛔
关闭 / 重开 ⚠️ 仅执行人 ⚠️ 仅执行人 ⚠️ 仅执行人 ⛔（即便被指为执行人）
变更执行人 ✅ ✅ ⛔ ⛔
批量操作 ✅ ✅ ⚠️ 逐条按上述规则判定 ⛔
导出 ✅ ✅ ✅ ⛔（服务端直接 403）

要点：

日常工作流

提问题

  1. 问题列表页「新建问题」（或任意页面 Ctrl+V 粘贴截图自动关联当前编辑上下文）；
  2. 按六要素描述：楼层 → 图纸名称（版本日期）→ 位置描述 → 一句话结论 → 问题详情 → 建议；
  3. 挂分类（类型 / 专业 / 专项 / 子项四维度，可多选）、选重要程度（紧急 / 普通 / 轻微 / 建议）、填位置信息（图纸版本日期 + 轴网定位，图纸版本为空 = 「缺位置」，列表会有警示标记）；
  4. 截图粘贴即传（前端自动压缩，最多 6 个文件）；过程附件（Word / PDF / DWG / 压缩包等，单个 ≤10 MB）原样上传、只提供下载。

跟进与关闭

批量操作

多选后可批量改状态 / 改分类 / 改重要程度 / 删除（按角色显隐）。批量删除前先 dry-run 预演「将删除 N 条」；提交后逐条反馈结果（成功 N · 失败 M · 每条原因），部分成功是正常语义。单次上限 500 条。

导出

档 内容 适用
1 · Excel 纯文字全量清单（同步流式，秒级） 给 Excel 继续加工
2 · 带图 HTML 全量 + 截图原图，HTML + images 打包 ZIP（大体积自动切包） 给甲方用浏览器看；勿用 Word 打开（Word 的 HTML 引擎不认 WebP）
3 · Word 带图报告（前端组装，≤100 条；勾选了行则只导勾选 ∩ 当前筛选） 正式报送物

三档均跟随当前筛选条件；甲方 / 协同方无导出权。

键盘快捷键

以下快捷键在任意页面可用（2026-09-30 起随系统提供，此前未写入文档）：

按键 去向
G 然后 H 首页
G 然后 M 我的项目
G 然后 I 问题列表
G 然后 P 项目说明
G 然后 C IFC 配置（上传 IFC 模型）
G 然后 R IFC 画像（查看模型数据）
G 然后 S 设置（账号 / 头像 / API Token）
G 然后 A 平台管理（仅平台管理员；其他角色会被拦回并提示）
N 操作记录

三条使用说明：

  1. G + 字母 是两段式：先按一下 G（松开），再按字母；
  2. 在输入框 / 文本域里打字时不会误触（单键快捷键自动避开输入焦点）；
  3. 快捷键当前为固定配置，暂不支持自定义；要增减键位请向维护者提；
  4. 「IFC 配置」与「IFC 画像」两页的模型功能尚在建设中 —— 页面打得开、版式已定，但要等模型功能接进来才会有内容，现在打开会是空的。

AI 接入指南

这是本平台区别于传统台账工具的核心能力。

前置：生成个人 API Token

个人设置 → API Token → 生成。明文只显示一次，请立即保存。Token 是个人身份凭据（库存哈希、长期有效、重置即吊销），不携带任何权限 —— 每次请求按「该用户在该项目内的角色」实时判定。

调用方式

curl -X POST "http://<host>:<port>/api/v1/projects/<projectId>/issues" \
  -H "Authorization: Bearer <你的Token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <UUID>" \
  -d '{
    "description": "地下一层 → 水暖-02（2026.03.12）→ 消防控制室附近走道吊顶内 → 排烟风管与消防喷淋主管交叉冲突 → 详情…… → 建议：1、设计方复核确认……；2、解决方案建议……",
    "priority": 1,
    "drawingVersion": "2026.03.12",
    "gridLocation": "B-C 轴交 5-7 轴",
    "tagIds": ["<类目ID>", "..."]
  }'

AI 代理执行（推荐 AI 客户端使用）

AI 不持有自己的凭据、也不加入项目 —— 它借用某个真实用户的 Token，并声明自己是 AI：

Authorization: Bearer <发令人的Token>
X-Agent-Mode: on-behalf
X-Agent-Id: <AI账户的ULID>          # 部署时由管理员在库中创建（users.subject_type = 'ai'）

此时权限 = 发令人权限 ∩ 项目设置里的「AI 允许动作清单」（默认含建问题 / 改问题 / 写答复三项；改状态、删除等一律不在清单内）。三条保证：

  1. AI 永远做不到「发令人本来做不到的事」（交集，不是并集）；
  2. 每次代理操作在留痕里同时记录实际执行者（AI）与发令人（人），操作记录页显示「AI 助手 修改了问题 0008 · 发令：乔峰」；
  3. AI 通道上的删除请求不会真删，只返回「待删清单」，由人确认后用人的凭据执行。

常用场景

完整端点与字段见 07-api.md。

数据口径备忘