# 太湖流域水文综合业务平台开发规范

**北京金水信息技术发展有限公司**

**2025年11月**

---

## 目录

1. [概述](#1-概述)
2. [技术标准](#2-技术标准)
   - [2.1 前端技术栈标准](#21-前端技术栈标准)
   - [2.2 数据服务与接口标准](#22-数据服务与接口标准)
3. [前端接入要求](#3-前端接入要求)
   - [3.1 视觉风格统一](#31-视觉风格统一)
   - [3.2 交互与组件统一](#32-交互与组件统一)
4. [UI设计规范](#4-ui设计规范)
   - [4.1 颜色规范](#41-颜色规范)
   - [4.2 字体规范](#42-字体规范)
   - [4.3 表单规范](#43-表单规范)
   - [4.4 按钮规范](#44-按钮规范)
   - [4.5 图表规范](#45-图表规范)
5. [信息共享平台接口集成技术方案](#5-信息共享平台接口集成技术方案)
   - [5.1 方案概述](#51-方案概述)
   - [5.2 系统架构设计](#52-系统架构设计)
   - [5.3 技术规范详情](#53-技术规范详情)
   - [5.4 安全保障措施](#54-安全保障措施)

---

## 1. 概述

现有业务系统由多家单位开发，在技术架构、数据格式、页面风格、菜单布局等方面存在差异，缺乏统一的接入要求和规范。本次项目将建立统一的技术架构、框架及界面风格，实现太湖水文业务系统统一集成管理，为各层级水文单位和部门提供统一而又个性化的业务支持。

前端界面采取**强关联、松耦合**方式进行集成整合，整合后的平台由两部分组成：

| 组成部分 | 说明 |
|---------|------|
| 太湖流域水文综合驾驶舱 | 驾驶舱数据由各子系统提供对应的数据接口，系统集成单位进行数据集成整合 |
| 太湖流域水文综合业务平台 | 业务平台由集成单位提供用户、权限、系统菜单管理，各业务子系统提供具体的功能页进行路由嵌套，实现多系统集成管理 |

**平台布局规范：**

- **顶部导航栏**：科技蓝色系，显示用户信息、用户权限菜单等
- **左侧菜单栏**：按业务优先级排序的树形菜单
- **中心内容区**：各单位专属业务功能展示区域

---

## 2. 技术标准

### 2.1 前端技术栈标准

| 技术项 | 标准要求 |
|-------|---------|
| 核心框架 | Vue 3.0 版本 |
| UI组件库 | Element Plus，需引入官方样式文件，禁止修改核心样式（可通过自定义主题文件调整色彩，主题变量需提交备案） |
| 路由管理 | Vue Router，路由路径使用 `/模块/功能` 格式（如 `/dataCenter/realtimeData`），禁止使用动态路由参数隐藏功能 |
| 网络请求 | Axios，统一封装请求拦截器（添加Token、请求头）和响应拦截器（统一错误处理） |
| 兼容性要求 | 支持龙芯浏览器、360安全浏览器、华为浏览器 |

### 2.2 数据服务与接口标准

**接口架构：**
- 采用 RESTful API 设计规范
- 接口地址统一前缀为 `/api/v1/`
- 按业务模块划分接口路径（如 `/api/v1/waterData/realtime`）

**请求方式：** GET、POST

**数据格式：**
- 统一使用 JSON 格式，编码为 UTF-8
- 禁止使用 XML 或其他格式

**请求头规范：**
- 必须包含 `Authorization`（Token信息）
- 必须包含 `Content-Type`（application/json）

**响应格式标准：**

成功响应：
```json
{
  "status": 200,
  "message": "操作成功",
  "result": [
    {"key1": "value1", "key2": "value2"}
  ]
}
```

失败响应：
```json
{
  "status": 404,
  "message": "具体错误原因",
  "data": null
}
```

**状态码规范：**

| 状态码 | 含义 |
|-------|------|
| 200 | 成功 |
| 400 | 参数错误 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 系统错误 |

**数据类型规范：**
- 日期时间格式：`yyyy-MM-dd HH:mm:ss`（如 `2025-11-17 10:30:00`）
- 数值类型：水位保留2位小数，流量保留3位小数
- 布尔类型：使用 `true/false`（禁止使用 `1/0`）

**接口注入：**
- 接口统一注入信息共享平台（参考第5章），集中管理所有API接口，实现统一调用、监控

---

## 3. 前端接入要求

### 3.1 视觉风格统一

#### 3.1.1 色彩体系标准

**主色调：**
- 科技蓝（RGB: 1, 125, 228，十六进制: #017DE4）
- 用于导航栏、标题栏、核心按钮等关键元素
- 体现水文行业的专业性与科技感

**禁用规则：**
- 禁止使用高饱和对比色（如红配绿），避免视觉疲劳
- 各系统色彩使用需严格对照色卡，偏差值≤5%

#### 3.1.2 菜单层级与命名规范

**排序规则：** 按"业务优先级+用户习惯"排序

**命名规则：**
- 菜单名称使用动宾结构或名词短语
- 避免模糊表述（如"数据查看"改为"数据查询"）
- 字数控制在4字以内（特殊情况不超过6字）

### 3.2 交互与组件统一

#### 3.2.1 通用组件规范

所有前端组件需基于 Element Plus 开发，禁止自定义与标准组件功能重复的组件。

**按钮规范：**
- 统一使用五种类型：主要按钮（主色调）、成功按钮（生态绿）、警告按钮（警示黄）、危险按钮（警示红）、文本按钮（无背景）
- 按钮尺寸统一为 Default
- 图标与文字间距 4px

**表单规范：**
- 输入框长度按内容长度限制（如站点编号固定8位则限制输入长度）
- 必填项前加红色 `*`
- 校验提示统一放在输入框下方，警示红文字

**表格规范：**
- 默认显示序号列
- 每页条数默认15条（支持30/50条切换）
- 表头使用中灰加粗
- 奇数行白色背景、偶数行浅灰背景
- 支持排序（点击表头）功能

**弹窗规范：**
- 按钮组放在右下角
- "确定"按钮在前（主色调），"取消"按钮在后（文本按钮）
- 弹窗宽度默认1200px（可自适应）

**图表规范：**
- 统一使用 ECharts
- 折线图（趋势分析）、柱状图（对比分析）、饼图（占比分析）
- 配色需符合系统色彩规范
- 图表需包含标题、图例、单位
- 鼠标悬浮显示详细数据

#### 3.2.2 交互体验规范

**操作反馈：**
- 点击按钮后立即显示加载状态（按钮文字变为"加载中..." + 旋转图标）
- 加载失败显示"加载失败"提示

**数据操作：**
- 批量删除、导出等操作需二次确认（弹窗提示"确定要执行XX操作吗？"）

**异常处理：**
- 页面404时显示"页面不存在，返回首页"按钮
- 500错误时显示"系统异常，请联系管理员"及联系方式
- 无数据时显示"暂无相关数据"提示图及刷新按钮

---

## 4. UI设计规范

### 4.1 颜色规范

**主色调：** 蓝色 `#1c97e7`

选择蓝色作为主色调的原因：
- 天空、大海和地球都是蓝色的，使人容易联想到平静、广阔和智慧
- 从心理上会给人以冷静的感觉
- 有利于逻辑思维的运转，视觉上更为简洁
- 适合与严肃的科技行业

### 4.2 字体规范

**行高计算公式：** 行高值 = 字号 × 1.5

| 字号 | 行高 |
|-----|------|
| 14px | 21px |
| 16px | 24px |

### 4.3 表单规范

#### 4.3.1 正常文本框
- 宽度可根据实际的放置位置做自适应

#### 4.3.2 被禁用的文本框
- 背景色：`#f2f2f2`
- 边框颜色：`#e1e5e6`
- 文字颜色：`#c2c2c2`

#### 4.3.3 下拉文本框
- 搜索场景：最小宽度120px，最大宽度可自适应
- 表单场景：最小宽度120px，最大宽度574px

#### 4.3.4 文本框多选
- 文字字体大小：13px
- 文字颜色：`#646464`

#### 4.3.5 填写日期文本框
- 文字大小：13px
- 文字颜色：`#646464`

#### 4.3.6 文本提示
- 正常状态颜色：`#a6a6a6`
- 鼠标滑过颜色：`#1c97e7`
- 提示框大小：自适应

#### 4.3.7 可下拉、可输入文本框
- 文字大小：13px
- 文字颜色：`#646464`
- 选中输入框时边框颜色由灰色变为 `#1c97e7`

#### 4.3.8 表单预设布局规范
- 分类标题字体大小：15px
- 分类标题颜色：`#646464`
- 分类与分类之间保持固定间距

#### 4.3.9 搜索框预设
- 对齐方式：左对齐
- 默认宽度：最小120px，最大200px

#### 4.3.10 标签规范
- 默认标签样式：标题 + 可下拉可输入文本框
- 输入框内提示信息："请输入建和请输入值"

#### 4.3.11 步骤条
- 遵循 Element Plus 标准步骤条样式

#### 4.3.12 气泡提示和弹出框
- 弹出框默认宽度：663px，默认高度：210px，最大高度：788px（超过可滚动）
- 气泡提示提供4种位置：顶部、右侧、底部、左侧

#### 4.3.13 进度条
- Table进度条长度：最小80px，最大不限

#### 4.3.14 消息提示
- 提示信息长度：520px，高度最高不超过173px（5行字区域）
- 圆角弧度：R=5px
- 内容字体大小：13px，颜色：`#646464`

**消息类型配色：**

| 类型 | 主色 |
|-----|------|
| 任务执行成功 | `#1c97e7` |
| 任务执行失败 | `#f74c47` |
| 任务正在执行 | `#79c662` |
| 即将到期/即将失败 | `#ffb83d` |

#### 4.3.15 列表规范
- 竖向分割线依据内容文字自适应
- 鼠标划过背景颜色：`#f5f5f5`
- 表单列表高度：限制最低高度44px
- 文字相对表格高度居中显示

#### 4.3.16 页面子区域规范
- 子区域标题：16px，颜色 `#1c97e7`，距离左边缘15px
- 标题栏背景模块高度：50px
- 子区域之间距离：15px

### 4.4 按钮规范

**基础样式：**
- 全部采用 3px 圆角矩形
- 有线框和填色两种展现形式

**列表页创建类按钮：**
- 尺寸：34px × 128px
- 圆角：R=3px
- 字号：13px

**查询栏按钮：**

| 按钮 | 背景色 | 字体颜色 | 边框 | 尺寸 |
|-----|-------|---------|------|------|
| 查询 | `#1c97e7` | `#fff` | 无 | 34×80px |
| 重置 | `#fff` | `#1c97e7` | `#1c97e7` | 34×80px |
| 高级 | `#f0f0f0` | `#1f1f1f` | 无 | 34×80px |

**保存按钮：**
- 背景色：`#1c97e7`
- 字体颜色：`#fff`
- 尺寸：34×80px
- 圆角：R=3px
- 字号：13px

**删除按钮：**
- 背景色：`#eb462b`
- 字体颜色：`#fff`
- 尺寸：34×80px
- 圆角：R=3px
- 字号：13px

**取消/关闭按钮：**
- 背景色：`#fff`
- 描边：`#e1e5e6`
- 字体颜色：`#646464`
- 尺寸：34×80px
- 圆角：R=3px
- 字号：13px

### 4.5 图表规范

**字体规范：**

| 元素 | 字体大小 | 颜色 |
|-----|---------|------|
| 饼状图图例 | 13px | `#1f1f1f` |
| 饼状图配置文字 | 13px | `#646464` |
| 其他统计图图例 | 13px | `#1f1f1f` |
| Y轴/X轴文字 | 12px | `#646464` |
| Y轴外轴单位 | 12px | `#c2c2c2` |

**柱状图配色：**

| 数量 | 配色方案 |
|-----|---------|
| 1个柱状图 | `#1c97e7` |
| 2个柱状图 | `#1c97e7` + `#26b8f3` |
| 3个柱状图 | 2个`#1c97e7` + 1个`#26b8f3` |
| 4个柱状图 | 2个`#1c97e7` + 2个`#26b8f3` |

**饼状图配色：**

| 数量 | 配色方案 |
|-----|---------|
| 单色 | `#1c97e7` |
| 双色 | `#1c97e7` + `#ffcc4d` |
| 三色及以上 | 遵循色卡优先级：`#1c97e7` + `#ffcc4d` + `#93d347` + `#ff8562` + `#16aeed` + `#1c6de7` + ... |

**状态颜色语义：**

| 颜色 | 含义 | 使用场景 |
|-----|------|---------|
| 红色 | 警告、危险 | 未通过、异常、错误 |
| 绿色 | 理想、希望、生长 | 审批通过、运行中 |
| 蓝色 | 沉稳、理智、准确 | 审核通过、使用中 |
| 灰色 | 记忆、流失、诚恳、沉稳 | 已取消、未使用 |

---

## 5. 信息共享平台接口集成技术方案

### 5.1 方案概述

本方案旨在构建统一信息共享平台，通过标准化接口集成各业务系统，实现跨系统数据安全共享。核心目标包括：

- 建立统一接口接入规范
- 实现多层级安全验证机制
- 全链路调用信息追溯
- 支撑各业务系统高效协同

### 5.2 系统架构设计

#### 5.2.1 整体架构分层

| 层级 | 职责 |
|-----|------|
| 接入层 | 接收各业务系统请求，提供负载均衡、请求转发能力，支持 HTTP/HTTPS 协议，兼容 RESTful、WebService 接口风格 |
| 验证层 | 集中处理 Token 验证、用户身份验证、业务系统合法性校验，是安全防护核心层 |
| 接口适配层 | 对各业务系统接口进行标准化封装，屏蔽底层差异，提供统一调用入口 |
| 日志记录层 | 实时采集接口调用全量信息，包括请求参数、响应数据、调用时长等，支持持久化存储与快速查询 |
| 数据交互层 | 负责平台与各业务系统的数据传输，支持 JSON、XML 等通用数据格式，确保数据一致性 |

#### 5.2.2 核心组件

| 组件 | 说明 |
|-----|------|
| 接口网关 | 统一接入入口，集成负载均衡、路由转发、限流熔断功能（采用 Spring Cloud Gateway） |
| 身份认证中心 | 管理 Token 发放、用户信息校验、业务系统注册授权 |
| 接口注册中心 | 存储各业务系统接口元数据（地址、参数、返回格式、权限要求等） |
| 日志存储与分析组件 | 采用 ELK 栈（Elasticsearch + Logstash + Kibana）或 ClickHouse，支持海量日志存储与可视化分析 |

### 5.3 技术规范详情

#### 5.3.1 接口 Token 验证机制

**Token 生成与发放：**

1. **业务系统注册**：业务系统需先在平台完成注册，提交系统名称、负责人、接口用途等信息，经审核通过后，由身份认证中心发放系统唯一标识（AppID）和密钥（AppSecret）

2. **Token 申请**：业务系统通过 AppID + AppSecret 发起 POST 请求（`/api/token/get`），携带参数：
   - `timestamp`：时间戳，精确到秒
   - `nonce`：随机字符串，32位
   - `signature`：签名，算法：`SHA256(AppID + AppSecret + timestamp + nonce)`

3. **Token 返回**：平台验证通过后，返回：
   - `Access Token`：有效期为2小时，字符串，64位
   - `Refresh Token`：有效期为7天，用于刷新 Access Token

**Token 验证规则：**

- 所有业务接口请求必须在 HTTP 头中携带 `Authorization` 字段，格式：`Bearer {Access Token}`
- 平台验证流程：
  1. 校验 Token 是否存在、格式是否合法
  2. 校验 Token 是否过期（结合 Redis 缓存）
  3. 校验 Token 对应的业务系统是否已授权
  4. 若 Token 过期，支持通过 Refresh Token 申请新 Token（`/api/token/refresh`）

**异常处理：**
- Token 无效/过期：返回 401 Unauthorized
- 签名错误：返回 403 Forbidden

#### 5.3.2 请求方用户验证

**用户身份标识：**

- 请求方用户需在平台完成统一身份注册，获取唯一用户 ID（UserID）
- 支持关联业务系统本地用户账号（通过用户映射表实现）
- 接口请求时，需在请求参数中携带 `UserID` 和 `UserToken`（用户登录凭证，有效期12小时）

**验证流程：**

1. 平台接收请求后，通过 UserID 查询用户状态（是否启用、是否有权限调用该接口）
2. 校验 UserToken 有效性（结合业务系统用户会话缓存）
3. 支持细粒度权限控制：按用户角色分配接口调用权限（如只读权限、读写权限），权限信息存储在 RBAC 权限模型中

**异常处理：**
- 用户未授权：返回 403 Forbidden
- UserToken 过期：返回 401 Unauthorized

#### 5.3.3 业务系统接口规范

**接口设计标准：**

- **接口风格**：统一采用 RESTful 风格
- **HTTP 方法对应**：GET（查询）、POST（新增）、PUT（修改）、DELETE（删除）
- **接口地址格式**：`/api/{业务域}/{系统标识}/{接口版本}/{接口名称}`
  - 示例：`/api/order/systemA/v1/queryOrder`
- **数据格式**：请求体与响应体统一使用 JSON 格式，编码为 UTF-8

**状态码规范：**

| HTTP状态码 | 含义 | 业务状态码 |
|-----------|------|-----------|
| 200 OK | 请求成功 | `{"code":200,"message":"success","data":{...}}` |
| 400 Bad Request | 请求参数错误 | - |
| 500 Internal Server Error | 服务器内部错误 | - |
| - | 业务异常 | 600~699（如601：数据不存在、602：参数校验失败） |

**请求参数规范：**

- 必选参数：除 UserID、UserToken 外，需包含业务核心参数
- 参数命名：采用下划线命名法（如 `order_no`）
- 参数校验：业务系统接口需支持参数合法性校验（格式、长度、取值范围），校验失败返回 602 错误及具体原因
- 分页参数：查询类接口统一采用 `page`（页码，默认1）、`page_size`（每页条数，默认20，最大100）参数

**响应数据规范：**

- 统一响应结构：包含 `code`（状态码）、`message`（提示信息）、`data`（业务数据）、`timestamp`（响应时间戳）四个字段
- 错误信息：需明确描述错误原因，便于问题排查（如 `message:"订单号不存在，order_no=123456"`）
- 大数据量响应：支持流式输出或分块传输，避免内存溢出

#### 5.3.4 接口调用信息记录规范

**记录内容：**

| 类别 | 记录项 |
|-----|-------|
| 基础信息 | 调用时间（精确到毫秒）、调用接口地址、请求方 IP、业务系统 AppID、用户 UserID |
| 请求信息 | HTTP 方法、请求头（脱敏处理 Authorization、Cookie）、请求参数（脱敏敏感字段如手机号、身份证号） |
| 响应信息 | 响应状态码、响应体（脱敏敏感数据）、调用时长（毫秒级） |
| 异常信息 | 异常类型、异常堆栈信息（仅存储关键片段）、错误码 |

**记录存储与查询：**

- **存储方式**：实时日志写入 Elasticsearch，按日期分索引存储（保留90天），核心数据同步至 MySQL 用于统计分析
- **查询能力**：支持按接口地址、AppID、UserID、时间范围、状态码等多条件组合查询，响应时间≤1秒
- **监控告警**：基于调用时长（阈值可配置，如超过500ms）、失败率（超过5%）设置告警，支持短信、邮件通知

### 5.4 安全保障措施

#### 5.4.1 数据传输安全

- 所有接口采用 HTTPS 加密传输
- 禁用弱加密算法（如 TLS 1.0/1.1）
#### 5.4.2 敏感数据脱敏
- 请求/响应中的手机号、身份证号、银行卡号等敏感信息，存储时采用掩码处理
- 示例：手机号 `138****1234`
#### 5.4.3 限流防护
- 按 AppID 设置接口调用频率限制（如每秒100次）
- 防止恶意请求攻击
#### 5.4.4 日志安全
- 日志数据仅授权人员可查询
- 操作日志留存180天
- 防止日志泄露
---
**文档版本：** V1.0  
**编制单位：** 北京金水信息技术发展有限公司  
**编制日期：** 2025年11月