bim-issue-platform

BIM 问题管理平台 · 项目介绍

本目录（docs_2/）是面向开源读者重写的文档集。原 docs/ 保留了项目从需求到实现的全过程记录（决策日志、评审意见、联调过程），供追溯历史决策时查阅；日常使用与二次开发请以本目录为准。

这是什么

BIM 问题管理平台是一个面向建模阶段 BIM 工程师的问题（碰撞、图面错误、净高不足等）跟踪管理平台：

• 单团队私有化部署：装在公司内网或一台云主机上即可使用，支持 Linux / Windows；
• 多项目、多角色：一个平台承载多个项目，项目负责人 / 专业负责人 / 工程师 / 甲方 / 协同方各按权限协作；
• 为 AI 而生：提供完整的 REST API 与个人 API Token，AI 客户端可以批量建问题、规范化描述、写答复 —— 这是它与传统问题台账工具最大的差别。

解决什么问题

痛点	本平台的应对
每人记录风格不统一，难以汇总	问题按「六要素」模板记录（楼层 → 图纸 → 位置 → 结论 → 详情 → 建议），分类挂四维度标准类目（类型 / 专业 / 专项 / 子项）
一次面对几百条问题，抓不住重点	重要程度四档（紧急 / 普通 / 轻微 / 建议）+ 服务端筛选 / 排序 / 分页，紧急判定有明确规则
记录载体五花八门（Excel / Word / 各家平台），导出格式混乱	三档导出：Excel 全量清单（同步）、带图 HTML 报告（后台任务打包 ZIP）、Word 小批量报告（前端组装）
想让 AI 帮着记录 / 批量处理，但平台没有 API	全部业务能力开放为 REST API；AI 通过「代理执行」模式借用户的令牌操作，权限受发令人与 AI 动作清单双重约束，全部留痕

功能总览

• 问题管理：创建（支持 Ctrl+V 粘贴截图、拖拽、附件）、筛选、批量操作（改状态 / 改分类 / 改重要程度 / 删除，单次 ≤500 条，支持 dry-run 预演）、状态流转（关闭 / 重开）、答复讨论（答复可带图）。
• 文件管理：截图统一转 WebP 存储 + 缩略图；过程附件（Word / PDF / DWG / 压缩包等）原样存储、只提供下载；项目封面、用户头像。
• 项目说明：项目概况、经济技术指标（一行一指标，可分组排序）、各专业设计说明（Markdown，渲染展示）。全部字段开放 AI 读写，AI 写入显著标注。
• 项目设置：41 项标准分类（建项目时自动初始化，可增改）、成员管理（加人 / 改角色 / 移出 / 复入）、项目参数、AI 允许动作清单。
• 平台管理（平台管理员专属）：建项目（同时指派负责人、生成 YYYY-NNN 编号）、账号管理（建号 / 停用 / 重置密码 / 平台角色）。
• 操作记录：全站写操作留痕 —— 谁（实际操作者）、受谁的指令（发令人）、何时、把哪个字段从什么改成什么，AI 通道的操作一眼可辨。
• 个人中心：资料 / 头像 / 改密 / 个人 API Token（一人一枚，库存哈希，重置即吊销）。

技术栈

层	选型
框架	Nuxt 4（全栈：app/ 前端 SPA + Nitro server/ 后端）
界面	Nuxt UI v4（Tailwind CSS v4）
数据库	SQLite（默认，零配置，走 Node 22 内置 node:sqlite） / MySQL 8（多人共享开发库或既有基础设施）
ORM	Drizzle ORM 0.45（跨方言，双 config）
鉴权	nuxt-auth-utils（sealed 加密 Cookie 会话）+ 个人 Bearer Token（脚本 / AI）
运行时	Node.js ≥ 22 + pnpm 11

一条贯穿全项目的依赖纪律：禁止一切需要本地编译的原生模块。使用者是 BIM 工程师而非运维，装不上等于平台不存在 —— 因此 SQLite 走 node:sqlite（而非 better-sqlite3）、密码哈希用内置 crypto.scrypt（而非 bcrypt/argon2）、图像处理用纯 JS 的 jimp / @jsquash/webp（而非 sharp）。全部依赖均为纯 JS。

部署形态

• Web 应用（B/S），私有化部署优先：局域网内网地址访问，或部署到有公网 IP 的服务器；
• 默认 SQLite 零配置开箱即用；需要接入既有 MySQL 时改一行配置切换；
• 典型规模：单团队 4~5 人至十几人，单项目千级问题、全平台十万级均经验证可行。

当前状态

第一版（MVP）已完成：7 个业务页面 + 14 张表 + 58 个 REST 端点全部实现并联调通过。

路线图（明确不在当前版本内）

项	状态
BIM 模型展示页（web-ifc + Three.js，仅旋转浏览）	暂缓；model_files 表已建，文件可上传存储
问题情况汇总页 / 报表统计端点	后置；模板已有现成范式
MCP Server	规划为 REST 之上的薄壳（只做协议翻译与转发，不重复实现权限与业务规则）
项目归档 / 负责人移交 / 平台用户冻结后语义细化	契约层已有提案（见 docs/6_2接口契约.md 第 3.1c 节），待定案
PostgreSQL 支持	ORM 层已按跨方言约束编写，未做兼容性验证

文档导航

文档	内容
02-getting-started.md	安装、初始化、演示数据、登录
03-configuration.md	环境变量、数据库切换、部署（反向代理 / HTTPS / 备份）
04-user-guide.md	页面导览、角色与权限、日常工作流、AI 接入指南
05-architecture.md	技术选型理由、目录结构、前后端架构
06-database.md	14 张表设计、通用约定、迁移与对拍
07-api.md	API 参考：鉴权、AI 代理执行、端点清单、错误码
08-development.md	开发环境、常用命令、代码门禁、贡献规范
09-design-decisions.md	关键设计决策及其理由（为什么这样设计）