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

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

2025年11月

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）

响应格式标准：

成功响应：

{
  "status": 200,
  "message": "操作成功",
  "result": [
    {"key1": "value1", "key2": "value2"}
  ]
}

失败响应：

{
  "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 生成与发放：

业务系统注册：业务系统需先在平台完成注册，提交系统名称、负责人、接口用途等信息，经审核通过后，由身份认证中心发放系统唯一标识（AppID）和密钥（AppSecret）
Token 申请：业务系统通过 AppID + AppSecret 发起 POST 请求（/api/token/get），携带参数：
- timestamp：时间戳，精确到秒
- nonce：随机字符串，32位
- signature：签名，算法：SHA256(AppID + AppSecret + timestamp + nonce)
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小时）

验证流程：

平台接收请求后，通过 UserID 查询用户状态（是否启用、是否有权限调用该接口）
校验 UserToken 有效性（结合业务系统用户会话缓存）
支持细粒度权限控制：按用户角色分配接口调用权限（如只读权限、读写权限），权限信息存储在 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月

结构规范.md 18 KB Постоянная ссылка История Исходник

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

目录

1. 概述

2. 技术标准

2.1 前端技术栈标准

2.2 数据服务与接口标准

3. 前端接入要求

3.1 视觉风格统一

3.1.1 色彩体系标准

3.1.2 菜单层级与命名规范

3.2 交互与组件统一

3.2.1 通用组件规范

3.2.2 交互体验规范

4. UI设计规范

4.1 颜色规范

4.2 字体规范

4.3 表单规范

4.3.1 正常文本框

4.3.2 被禁用的文本框

4.3.3 下拉文本框

4.3.4 文本框多选

4.3.5 填写日期文本框

4.3.6 文本提示

4.3.7 可下拉、可输入文本框

4.3.8 表单预设布局规范

4.3.9 搜索框预设

4.3.10 标签规范

4.3.11 步骤条

4.3.12 气泡提示和弹出框

4.3.13 进度条

4.3.14 消息提示

4.3.15 列表规范

4.3.16 页面子区域规范

4.4 按钮规范

4.5 图表规范

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

5.1 方案概述

5.2 系统架构设计

5.2.1 整体架构分层

5.2.2 核心组件

5.3 技术规范详情

5.3.1 接口 Token 验证机制

5.3.2 请求方用户验证

5.3.3 业务系统接口规范

5.3.4 接口调用信息记录规范

5.4 安全保障措施

5.4.1 数据传输安全

5.4.2 敏感数据脱敏

5.4.3 限流防护

5.4.4 日志安全

防止日志泄露

结构规范.md 18 KB

Постоянная ссылка История Исходник