258 lines
7.3 KiB
Markdown
258 lines
7.3 KiB
Markdown
# 郑州智慧工地：现场管理 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、离线能力明确延后
|
||
|
||
这样可以把当前“文档完整、实现缺位”的状态，推进成“有共享底座、已有一条真实业务闭环”的可持续开发状态。
|