smart-project/docs/superpowers/specs/2026-04-25-platform-admin-design.md

郑州智慧工地：平台级后台管理端设计

1. 问题定义

当前仓库已经有两块基础资产：

• h5-app/：面向项目现场用户的 H5 客户端
• server/：Node.js / Express + TypeScript 服务端雏形，已具备登录、隐患、文件等项目侧能力

但项目仍然缺少一块关键拼图：平台级后台管理端。
现阶段虽然已经有 projects、users、project_id 隔离等设计基础，但还没有一套面向平台管理员的产品与工程方案，用来完成项目开通、项目账号分配和平台治理。

本轮设计的目标不是扩展 H5 业务本身，而是补齐平台管理闭环，让平台管理员可以：

1. 登录平台后台
2. 创建项目
3. 为项目创建并分配项目管理员、管理人员账号
4. 让这些项目账号仅在 H5 使用，进入项目侧业务

2. 当前项目状态

2.1 已有基础

• SPEC.md、docs/architecture.md、docs/api.md、docs/database.md 已经明确总体产品、架构、接口和数据方向
• h5-app/ 现已不是纯静态原型，而是 React + Vite + Ant Design Mobile 的移动端工程
• server/ 已有基础后端骨架，当前主要覆盖：
  • POST /v1/auth/login
  • GET/POST 隐患相关接口
  • 文件相关接口
• 现有后端认证模型已把 project_id 放入 JWT，并通过中间件提供项目隔离能力

2.2 当前缺口

• 仓库中尚无 admin-web/ 管理后台前端工程
• 服务端尚无平台级认证域和平台级资源路由
• 现有用户模型主要围绕项目侧使用，没有显式区分“平台账号”和“项目账号”
• 产品文档主要面向 H5 与项目业务，平台后台尚未形成独立设计说明

3. 设计目标与非目标

3.1 本轮目标

本轮平台后台设计聚焦于最小闭环：

1. 平台管理员登录后台
2. 平台管理员创建项目
3. 平台管理员查看项目详情
4. 平台管理员在项目下创建项目管理员、管理人员账号
5. 新建项目账号只能登录 H5，不能登录平台后台

3.2 明确非目标

本轮不纳入范围：

• 设备分配、设备解绑、设备运维台账
• 平台运营大屏、复杂统计看板
• 审批流、消息中心、通知中心
• 细粒度 RBAC 权限系统
• 项目侧业务后台化（隐患、日志、预警在后台处理）
• 让项目管理员进入平台后台处理业务

平台后台一期的定位是开户与分配中台，不是完整运营平台。

4. 方案比较

方案 A：独立 admin-web + 扩展现有 server（选定）

新增独立管理后台前端应用，保留现有 h5-app/ 不动；后端在现有 server/ 上新增平台级认证、项目管理、项目账号管理能力。

优点：

• H5 和后台边界清晰，避免桌面端和移动端交互混杂
• 最大化复用现有服务端和数据库基础
• 一期范围清楚，后续扩展更自然

代价：

• 仓库会新增一个前端应用
• 部署入口需要新增后台前端站点

方案 B：把后台塞进 h5-app

在现有前端工程内同时承载 H5 和后台管理页面。

优点：

• 少一个前端工程
• 可直接复用部分现有配置

问题：

• 移动端与桌面后台混在一起，产品边界会越来越模糊
• 路由、布局、样式与权限模型都容易互相污染

方案 C：只补平台 API，不做后台 Web

先把平台接口和数据设计补齐，管理后台 UI 仅停留在方案层。

优点：

• 实施量最低

问题：

• 无法形成“创建项目并分配账号”的真实业务闭环
• 平台管理的价值无法直观验证

综合当前仓库形态和本轮目标，本设计采用 方案 A。

5. 产品边界与用户模型

5.1 使用者边界

本轮只做平台级后台。

• 平台管理员：登录后台，负责项目创建、项目账号分配
• 项目管理员 / 管理人员 / 现场用户：只登录 H5，在各自项目内完成业务工作

换言之：

• 平台后台不是给项目侧人员使用的
• 项目侧业务仍然在 H5 完成
• 平台账号与项目账号必须在访问边界上严格隔离

5.2 一期产品模块

平台后台一期仅包含以下模块：

1. 平台登录
2. 后台首页
3. 项目管理
4. 项目详情
5. 项目账号创建与查看

5.3 核心业务闭环

1. 平台管理员登录后台
2. 创建项目
3. 进入项目详情
4. 创建项目管理员 / 管理人员账号
5. 将账号交付项目侧人员
6. 项目侧人员使用 H5 登录开展工作

6. 推荐产品结构

6.1 后台首页

首页采用轻量工作台，不做复杂看板。核心目的是让平台管理员快速进入“项目管理”主流程。

建议包含：

• 项目总数
• 启用中项目数
• 最近创建项目
• 快捷入口：新建项目

6.2 项目管理

项目管理是平台后台一期的核心页面，承担项目生命周期入口职责。

页面能力：

• 项目列表
• 按名称搜索
• 查看项目状态、创建时间、账号数量
• 新建项目
• 进入项目详情

6.3 项目详情

项目详情页是“项目资料 + 项目账号”的聚合页。

建议信息块：

• 项目基础信息
• 项目状态
• 项目账号列表
• 新建项目账号入口

6.4 项目账号管理

账号创建不单独做复杂子系统，一期直接放在项目详情页内完成即可。

创建账号时填写：

• 用户名
• 初始密码
• 真实姓名
• 手机号（可选）
• 角色：项目管理员 / 管理人员

这些账号创建后：

• 绑定当前项目
• 只能登录 H5
• 默认不能访问平台后台

7. 数据模型与权限设计

7.1 用户表策略

用户确认采用单表复用策略：

• 继续使用 users 表
• 增加 user_type 区分平台账号与项目账号

推荐字段语义如下：

• user_type = platform：平台后台账号
• user_type = project：项目账号

约束规则：

• platform 账号的 project_id 为空
• project 账号的 project_id 必填

7.2 角色模型

user_type 和 role 分离：

• user_type 决定账号属于哪个访问域
• role 决定该域内的业务身份

一期建议如下：

• user_type=platform 时，role=platform_admin
• user_type=project 时，role ∈ {project_admin, manager, 安全负责人, 安全员}
  其中一期后台创建账号时重点覆盖 project_admin 与 manager

7.3 认证边界

后端需要形成两套访问边界：

• 平台后台域
  • 入口：/v1/platform/*
  • 只允许 user_type=platform
• 项目业务域
  • 入口：现有 /v1/* 业务接口
  • 只允许 user_type=project

JWT 中建议显式包含：

• id
• username
• user_type
• role
• project_id

7.4 项目隔离

现有 project_id 隔离原则保持不变，但只对项目业务域生效：

• H5 业务请求仍通过 project_id 过滤数据
• 平台管理员不直接进入项目业务接口
• 平台接口通过显式 project_id 操作项目资源，而不是复用项目业务中间件

8. API 设计建议

8.1 平台认证接口

• POST /v1/platform/auth/login

职责：

• 校验平台账号
• 生成平台后台 JWT
• 返回平台用户信息

8.2 项目管理接口

• GET /v1/platform/projects
• POST /v1/platform/projects
• GET /v1/platform/projects/:id
• PATCH /v1/platform/projects/:id（如纳入启停/编辑）

8.3 项目账号接口

• GET /v1/platform/projects/:id/users
• POST /v1/platform/projects/:id/users
• PATCH /v1/platform/users/:id/status（如纳入启停）

8.4 现有项目侧接口调整

现有 POST /v1/auth/login 需继续保留给项目账号使用，但要补充限制：

• 只允许 user_type=project
• 平台账号不能从该入口登录 H5 业务域

9. 工程拆分建议

9.1 仓库结构

建议形成三块应用：

• h5-app/：项目现场用户 H5
• admin-web/：平台级后台前端
• server/：统一后端服务

9.2 admin-web 技术方向

用户已确认前端默认按桌面管理台范式规划。

建议技术栈：

• React
• Vite
• TypeScript
• Ant Design（桌面版）
• React Router

9.3 server 后端拆分方向

建议在现有结构中新增平台侧模块：

• routes/platform-auth.ts
• routes/platform-projects.ts
• services/platform-auth-service.ts
• services/project-service.ts
• repositories/project-repository.ts
• middleware/require-platform-auth.ts

同时对现有模块做增量改造：

• auth：补 user_type 区分
• user-repository：支持平台账号与项目账号查询 / 创建
• JWT 类型定义：补 user_type

10. 推荐实施顺序

阶段 1：数据层与认证层

1. 调整 users 表结构，增加 user_type
2. 更新后端用户类型定义
3. 区分平台登录与项目登录
4. 新增平台鉴权中间件

阶段 2：平台项目 API

1. 项目列表
2. 新建项目
3. 项目详情

阶段 3：平台项目账号 API

1. 项目账号列表
2. 创建项目管理员 / 管理人员账号
3. 初始密码加密存储

阶段 4：admin-web 骨架

1. 登录页
2. 基础布局
3. 路由守卫
4. API 请求封装

阶段 5：admin-web 业务页

1. 项目列表页
2. 新建项目页 / 弹窗
3. 项目详情页
4. 新建项目账号弹窗 / 页面

阶段 6：联调与验收

1. 平台管理员创建项目
2. 平台管理员创建项目账号
3. 新建项目账号成功登录 H5
4. 新账号不可登录平台后台

11. 验收标准

一期完成后，应满足以下标准：

1. 平台管理员能够登录后台
2. 平台管理员能够创建项目
3. 平台管理员能够查看项目详情
4. 平台管理员能够为项目创建“项目管理员 / 管理人员”账号
5. 新建项目账号可登录 H5
6. 新建项目账号不可登录平台后台
7. 现有项目业务接口继续保持 project_id 隔离，不被平台能力破坏

12. 风险与约束

12.1 主要风险

• 若继续把平台账号和项目账号混作同一种用户语义，后续权限边界会越来越模糊
• 若把后台功能扩到设备管理、运营看板、审计日志，一期范围会快速失控
• 若强行把后台塞进 h5-app，后期前端维护成本会明显变高

12.2 控制策略

• 一期只做“平台开户闭环”
• 平台账号与项目账号通过 user_type 强隔离
• admin-web 独立建站，避免污染 H5 客户端
• 后端新增平台域接口，不挤压现有项目业务域

13. 结论

本轮平台后台最合适的推进方式是：

• 产品上：只做平台级后台，不做项目业务后台
• 工程上：新增独立 admin-web，扩展现有 server
• 数据上：复用 users 表，引入 user_type
• 实施上：先补平台认证和项目/账号 API，再补后台前端

这条路线能以最小复杂度补齐平台管理闭环，同时不破坏当前 H5 与项目隔离的既有主线。