jesxion/smart-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
71fc0edd7a54b340d98093372de8a00d514e17d8
smart-project/docs/superpowers/specs/2026-04-24-site-management-mvp-design.md
jesxion 584939c12f docs: add site management MVP design spec 
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-04-24 10:01:48 +08:00

7.3 KiB
Raw Blame History

郑州智慧工地：现场管理 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、离线能力明确延后

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

Reference in New Issue View Git Blame Copy Permalink