# 郑州智慧工地：现场管理 MVP 下一阶段设计

## 1. 问题定义

当前仓库已经具备较完整的产品、架构、接口与数据库设计文档，也有一套可直接打开的 H5 原型，但真实后端、数据库、鉴权、OSS 文件链路尚未落地。  
因此，下一阶段工作的目标不是继续扩展 mock 原型，而是把项目推进到一个**可验证、可演示、可继续扩展**的真实 MVP 基座。

本轮工作的核心判断是：

- **优先做端到端 MVP 骨架**
- **业务优先级先做隐患随手拍，再做施工日志**
- **首轮不同时展开设备接入、预警聚合、AI 分析真实链路**

## 2. 当前项目状态

### 2.1 已有资产

- `SPEC.md`：总体产品规格
- `docs/architecture.md`：目标系统架构
- `docs/api.md`：后台 API 设计
- `docs/database.md`：MySQL 表设计
- `docs/h5.md`：H5 页面与交互设计
- `docs/offline.md`：离线能力设想
- `h5/`：基于原生 HTML/CSS/JS 的 H5 原型

### 2.2 真实现状

- 仓库中**尚无** Node.js / Express / TypeScript 后端代码
- 仓库中**尚无** MySQL 初始化脚本、迁移体系或部署脚本
- H5 页面当前依赖 `js/mock.js`、`js/api.js`、`js/app.js` 的浏览器全局函数与 mock 数据
- 最近的代码演进主要集中在 H5 原型与设计文档，说明项目当前处于“设计明确、实现待启动”的阶段

## 3. 目标与非目标

### 3.1 本轮目标

在不摊大范围的前提下，建立一条可真实运行的现场管理链路：

1. 建立后端最小骨架
2. 落地登录与项目隔离能力
3. 落地隐患随手拍真实闭环
4. 为后续施工日志接入复用同一套基础设施

### 3.2 本轮非目标

本轮明确不进入实现范围：

- 厂家设备推送接入
- 实时监测/历史曲线
- 预警中心真实聚合
- AI 分析真实入库链路
- 完整离线能力
- 复杂角色权限模型

这些能力在文档中已定义，但不应与首轮 MVP 骨架一起并行落地。

## 4. 方案选择

在“下一步工作”上，考虑过三类策略：

### 方案 A：基础设施先行（选定）

先建立后端骨架、数据库、鉴权、`project_id` 隔离、文件上传抽象，再接入隐患模块，最后复用到施工日志。

**优点：**

- 后续扩展成本低
- 共享能力边界清晰
- 施工日志可以直接复用隐患阶段沉淀的能力

**代价：**

- 初期可见业务结果稍慢
- 需要严格约束范围，避免“先打底”演变成“大铺底”

### 方案 B：隐患闭环先行

先只围绕隐患模块做最小闭环，共性能力在实现过程中再抽取。

**优点：**

- 最快看到业务功能跑通

**问题：**

- 后续接施工日志时可能出现重复设计与返工

### 方案 C：数据模型先行

优先固化 schema、状态机、OSS 文件索引，再逐步补接口和前端对接。

**优点：**

- 数据边界更稳

**问题：**

- 可演示业务进展最慢

综合考虑当前仓库形态与优先级，本设计采用 **方案 A：基础设施先行，但范围只做到支撑隐患模块真实上线的最小闭环**。

## 5. 推荐推进结构

### 阶段 A：MVP 基础骨架

目标是建立“可以承载真实业务”的后端基础层：

- 后端项目目录结构
- 配置管理与环境变量
- 数据库连接与初始化机制
- 统一错误处理与基础健康检查
- JWT 登录
- `project_id` 项目隔离中间件
- OSS/文件上传抽象接口

这一阶段不追求“大而全”，只要求足以支撑隐患模块真实落地。

### 阶段 B：隐患随手拍真实闭环

在阶段 A 的基础上落地第一条真实业务链：

- 隐患上报
- 隐患列表
- 隐患详情
- 隐患认领
- 隐患处理完成
- 隐患图片上传与对象索引记录
- H5 隐患页面从 mock 改接真实接口

### 阶段 C：施工日志接入

复用登录、项目隔离、文件上传、数据库约定，补施工日志：

- 日志新建
- 日志列表
- 日志详情
- 附件图片上传

### 阶段 D：后续扩展

在现场管理链路稳定后，再继续推进：

- 设备接入
- 预警中心
- AI 分析
- 离线/PWA

## 6. 首轮工程边界

### 6.1 后端范围

首轮建议落地以下后端模块：

- `config`：环境变量读取与校验
- `db`：数据库连接、初始化、基础查询封装
- `auth`：登录、token 签发、token 解析
- `project_middleware`：将 `project_id` 作为硬约束注入业务查询
- `files`：上传凭证、对象索引、上传元数据
- `hazards`：上报、列表、详情、认领、处理

### 6.2 前端范围

首轮只改与隐患闭环直接相关的页面：

- `login.html`
- `report.html`
- `reports.html`
- `report-detail.html` 或统一后的隐患详情页

H5 继续维持当前的静态页面结构与 shared globals 方案，不在这一轮强行做前端架构重构。

### 6.3 暂缓改造范围

以下页面允许继续保持 mock：

- `devices.html`
- `device.html`
- `alerts.html`
- `alert.html`
- `ai-analyses.html`
- `ai-analysis.html`

## 7. 建议的实施顺序

### Step 1：先搭共享底座

- 建后端目录与启动入口
- 建数据库连接与初始化机制
- 落地 `users / projects / oss_files / hazards` 最小表集
- 打通 JWT 登录与 `project_id` 注入
- 建统一错误响应与健康检查

### Step 2：打通隐患最小闭环

实现以下接口：

- `POST /v1/hazards`
- `GET /v1/hazards`
- `GET /v1/hazards/:id`
- `POST /v1/hazards/:id/assign`
- `POST /v1/hazards/:id/resolve`

并将 H5 隐患相关页面从 mock API 切换到真实接口。

### Step 3：补文件上传链路

- 获取上传凭证
- 文件直传 OSS
- 记录 `oss_files`
- 业务记录中仅保存 object key 或对象引用

### Step 4：接施工日志

在共享底座复用基础上补：

- `POST /v1/logs`
- `GET /v1/logs`
- `GET /v1/logs/:id`

## 8. 首个验收节点

第一阶段不以“全部模块上线”为验收标准，而以**隐患随手拍真实闭环可演示、可验收**为标准。

验收节点定义如下：

- 用户能登录
- 用户可在所属项目下真实上报隐患
- 用户可查看本项目隐患列表与详情
- 用户可认领隐患
- 用户可将隐患标记为处理完成
- 隐患图片可真实上传并回显
- 不同 `project_id` 的数据不能串看

## 9. 风险与约束

### 9.1 主要风险

- 文档中的完整目标系统远大于当前仓库落地状态，容易在首轮就被拉成“大而全”工程
- 如果先把设备接入、AI、离线能力一并纳入，会显著增加交付风险
- H5 原型页当前存在页面命名与详情页组织不完全统一的情况，真实接入时需要做一次有限的页面归拢

### 9.2 约束原则

- 共享能力必须服务于首条业务链，而不是脱离业务独立扩张
- `project_id` 必须是硬约束，不允许作为可选过滤条件
- 施工日志必须建立在隐患阶段沉淀的能力之上，而不是并行另起一套

## 10. 结论

本项目下一步工作的最合理安排是：

1. 先做 **基础设施先行的 MVP 骨架**
2. 第一条真实业务链选择 **隐患随手拍**
3. 在隐患闭环跑通后，再接 **施工日志**
4. 将设备、预警、AI、离线能力明确延后

这样可以把当前“文档完整、实现缺位”的状态，推进成“有共享底座、已有一条真实业务闭环”的可持续开发状态。