# bim-issue-platform

**Repository Path**: ameba-h/bim-issue-platform

## Basic Information

- **Project Name**: bim-issue-platform
- **Description**: bim问题记录平台
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://bim.lansn.net/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-15
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BIM 问题管理平台

BIM 问题管理平台 —— 中小团队私有化部署，让 AI 替你记录、跟进、闭环问题。

**在线演示**：<http://120.25.73.105:5555> · **文档站点**：<https://bim.lansn.net/>

## 它能做什么

| | |
|---|---|
| 📝 **记录标准化** | 一条问题按六个要素记清：楼层、图纸、位置、结论、详情、建议，谁记都是同一个格式。再按重要程度 / 类型 / 子项 / 专业 / 专项五个维度归类，汇总与追溯都不用手工对齐。 |
| 📦 **绿色免安装包** | Windows x64 便携版，解压后双击启动脚本即可运行，包内自带 Node 运行时，目标机器无需安装任何依赖；默认附带示例项目，并可注册为 Windows 开机自启任务。 |
| 🤖 **AI 代理执行** | AI 用各人的令牌接入，权限即本人在该项目的权限。AI 改过的内容一律带标记，写清是谁让它做的；删除只生成待删清单，需本人确认。 |
| 📤 **三档导出** | 各有用途：带图 HTML 报告（ZIP 打包）用于成果归档，可直接打印成 PDF；Excel 用于外发统计与清单汇总；Word 用于过程讨论。 |
| 📊 **问题统计报表** | 首页看清项目问题全貌，紧急几条，未关几条，按专业 / 类型 / 专项 / 子项自动分好，四种图一眼分辨。项目问题什么样，进来就知道。 |
| 🗄️ **SQLite / MySQL 双库** | 默认自带 SQLite，一个文件就是数据库，不用另装数据库服务即可运行；团队多人共用，或要接公司现成的 MySQL 时，改一行配置即可切换。 |

## 快速开始

> 完整那几步（含 `.env` 每一行、从零建库、IFC 解析环境怎么装）在 **`docs/02_快速开始.md`**。这里只给最短一条路。
>
> **前置**：**Node.js ≥ 22** + **pnpm 11**。全程零原生依赖，不需要编译工具链。

```bash
git clone https://gitee.com/ameba-h/bim-issue-platform && cd bim-issue-platform
pnpm install                      # 由用户在自己的终端跑，见 docs/02 第 6 节
cp .env.example .env              # .env 已入库忽略，不会提交
pnpm dev                          # http://localhost:5555
```

**仓里已带一份灌好演示数据的 SQLite 库**（`data/bim_issue_demo.db`）与它的附件、封面、模型和解析产物 —— 克隆下来第一次登录就能看到真东西，**不必建库、不必灌种子**。`.env` 模板已按这份库配好（`DATABASE_CLIENT=sqlite` + `DATABASE_FILE=./data/bim_issue_demo.db`），只需把 `NUXT_SESSION_PASSWORD` 换成自己生成的一串（生成命令在 `docs/02_快速开始.md` 第 2 节）。

**登录：演示账号与口令都在 `docs/02_快速开始.md` 第 1 节那张表**（那批口令是为演示特意设的简单串，随仓公开）。看数据用 `demo_qiaof` —— `admin` 登进去只有两个后建的空项目。**部署到真实环境后第一件事是改掉 `admin` 的口令**。

如果不想用那份演示库、要自己建一份干净的：`pnpm db:init` 建空库（默认落 `data/bim_issue.db`），四条代价（含 `-- --force` 会先把库文件删掉再重建）写在 **`docs/02_快速开始.md`** 第 3 节；装依赖的坑与包完整性怎么判在第 6 节。

## 技术栈与命令

**Nuxt 4**（全栈 + SPA，`ssr: false`）+ **Nuxt UI v4** · **Drizzle ORM** 走 Node 内置 `node:sqlite` · 数据库默认 **SQLite**，多人共用或接现成库时切 **MySQL** · 鉴权 `nuxt-auth-utils`（sealed 加密 Cookie 会话）+ 一枚 API 令牌（**定性是 MCP 通道专用**）· AI 接入是平台进程内一条 `/mcp`（无状态 Streamable HTTP）· 运行时 **Node.js 22** + **pnpm 11**。

SQLite 一律走 Node 内置的 `node:sqlite`；口令哈希用 Node 内置 scrypt，图像处理用纯 JS。

命令逐条在 **`docs/02_快速开始.md`** 与 **`docs/13_测试与门禁.md`**，日常只用这三条：`pnpm dev` 起服务、`pnpm check:all` 判一轮改动是否算完（类型检查 + 代码规范 + 单测 + 文档字符自检 + 表定义对拍）、改了 `server/database/schema*.ts` 之后必跑 `pnpm db:check`。

## 文档

现行文档在 **`docs/`**，共 **20 份**（接口那套六册：主册 + 附录 1~5）。标头体例两套：**十四份册子**（`01`–`07`、`09`–`15`）开头三行写「这份是什么 / 谁该读 / 不是什么」；**接口那六册**另立体例（主册那一行是「定位」，边界由主册那句「不解释为什么」承担）。

| 文档 | 内容 |
|---|---|
| `01_工作方式.md` | 目录所有权、提交与推送边界、门禁、红线、探针纪律、表达与文案约定 |
| `02_快速开始.md` | 装依赖 → 配 `.env` → 建库 → 灌演示 → 起服务 → 登录，命令逐条可抄 |
| `03_需求分析.md` | 痛点清单、需求边界、哪些能力本期不做、第一版的实际范围 |
| `04_业务规则.md` | **权限矩阵 · 问题分类的原则 · 重要程度的区分 · 状态机 · 事务与文件一致性 · 报表口径** |
| `05_决策记录.md` | 只写现行结论：每条 = 定了什么 + 为什么 + 代价 |
| `06_架构.md` | 技术栈与选型理由、SPA、目录形状、取数与判权 |
| `07_数据模型.md` | 14 张表现状、隔离判据、软删与三处例外、四份表定义对拍（实体关系图 `docs/07_数据库ER图.drawio`） |
| `08_接口.md` | **端点清单与响应字段、错误码的唯一事实来源**（主册：速查卡 + 必读三章 + 分册地图） |
| `08_接口_附录1.md` | 错误码全表（45 枚）—— 拿到一枚 `code` 想知道什么意思、该配哪个状态码 |
| `08_接口_附录2.md` | 权限判定表完整版：问题类 · 非问题类 · AI 三层过滤 + 易错点 |
| `08_接口_附录3.md` | 通用约定细节：响应体 · 分页排序筛选 · 幂等与 dry-run · 批量部分成功 · 留痕 · 时间与枚举 |
| `08_接口_附录4.md` | 端点清单（批次 1 / 2 / 3），逐字段标冻结级别 |
| `08_接口_附录5.md` | 不在契约内的 · 待拍板的 · 变更流程 |
| `09_页面.md` | 路由与交互口径、各角色看得见什么、判权显隐 |
| `10_使用手册.md` | 给使用者读的那一份 |
| `11_IFC模型链路.md` | 上传、解析、探测四态、三道尺寸闸与合计上限、重传即重跑 |
| `12_AI接入.md` | AI 客户端怎么接进来、工具清单（数字以该册与上面那条命令为准）、令牌与通道、fail-closed |
| `13_测试与门禁.md` | 两层自动化检查、怎么跑、三个产物目录 |
| `14_部署与交付.md` | 生产包、绿色包、解析环境装法（含离线）、开机自启 |
| `15_现状与待办.md` | **唯一一份现状与欠账清单** —— 想知道「还欠什么」就读这里 |

**接口字段 / 错误码 / 路径一律以 `docs/08_接口.md` 那六册为唯一事实来源**；「现在做到哪、还欠什么」一律以 `docs/15_现状与待办.md` 为准。

## 许可与致谢

- **License**：MIT
- **前端基座**：派生自 [nuxt-ui-templates/dashboard]（MIT）。