🌱 万物云 Carbon Beat 碳数据上链存证服务
简介
本项目是一个基于 Conflux 树图区块链 的碳数据上链与存证服务。 允许企业或机构将碳排放相关的业务数据以安全、加密的方式上链存证，实现数据的透明、可追溯与不可篡改。
🌐 系统架构
本项目由两部分组成：
1. 链上智能合约
一个可升级的 Solidity 智能合约，部署在 Conflux 树图区块链主网。合约支持以下特性：
✅ 数据上链
以key-value格式（value为字符串）上传碳排放相关数据。
支持单条与批量上传。🔄 数据更新机制
区块链数据不可篡改，但可通过“更新”方式形成版本链（双向指针）：- 新版本会引用旧版本，旧版本会被标记为“锁定”；
- 历史数据仍可追溯。
🧩 数据状态管理
- 支持标记数据为“删除”或“恢复”；
- 支持“锁定”数据，禁止进一步修改。
2. API 服务
API 服务用于与链上合约交互，并提供访问控制与接口封装。
功能概要：
🔐 访问权限控制
- 通过 JWT（JSON Web Token）对上传、更新、删除等接口进行权限校验；
🔗 数据操作接口
- 支持上链、批量上链、读取、更新与删除；
📝 数据格式说明
上链的数据采用统一的 JSON 结构，主要由两个部分组成：
dataTime：数据时间，使用 Unix 时间戳（秒） 表示；data：一个包含若干关键字段的对象，以 key-value 形式提供，每个字段的值均为字符串。
示例
{
"dataTime": 1617235200,
"data": {
"prov": "GD",
"city": "广州",
"unit": "广州XXX服务中心",
"proj": "广州xxx花园",
"cat": "3",
"code": "S3-B-02-0001",
"src": "燃料和能源活动",
"act_data": "1194.09551399661",
"co2e": "0.43615726534125"
}
}
字段说明
| 字段名 | 含义 | 说明 |
|---|---|---|
dataTime |
数据时间 | Unix 时间戳（单位：秒），表示该条数据对应的时间点。 |
prov |
省份简写 | 采用中国大陆省份代码（见下表）。 |
city |
城市名称 | 数据所属城市名称。 |
unit |
业务单元 | 所属业务或机构名称。 |
proj |
项目名称 | 具体项目或设施名称。 |
cat |
范围类别 | 对应 GHG 协议下的排放范围类别（如 Scope 1、2、3 等）。 |
code |
碳编码 | 碳排放项的唯一标识符。 |
src |
碳排放来源 | 具体的排放源类型（例如“燃料和能源活动”）。 |
act_data |
活动数据 | 原始活动量数据（如燃料消耗量、电力用量等）。 |
co2e |
碳排放当量 | 以 CO₂e 表示的碳排放总量。 |
中国省份简写表
| 省份 | 简写 | 省份 | 简写 |
|---|---|---|---|
| 北京 | BJ | 天津 | TJ |
| 河北 | HE | 山西 | SX |
| 内蒙古 | NM | 辽宁 | LN |
| 吉林 | JL | 黑龙江 | HL |
| 上海 | SH | 江苏 | JS |
| 浙江 | ZJ | 安徽 | AH |
| 福建 | FJ | 江西 | JX |
| 山东 | SD | 河南 | HA |
| 湖北 | HB | 湖南 | HN |
| 广东 | GD | 广西 | GX |
| 海南 | HI | 重庆 | CQ |
| 四川 | SC | 贵州 | GZ |
| 云南 | YN | 西藏 | XZ |
| 陕西 | SN | 甘肃 | GS |
| 青海 | QH | 宁夏 | NX |
| 新疆 | XJ |
说明
- 除
dataTime外，其余字段均作为data的 key-value 形式传入； - 合约端接收时会将这些字段统一编码为紧凑的字符串存储；
- 若需更新数据，请保持相同的结构和字段命名；
- 建议数值型数据（如
act_data,co2e）以字符串形式上传，以确保跨语言兼容性。
📄 接口文档
可交互的接口文档已集成至项目中，运行服务后访问 /api 路径即可打开。
🔑 授权接口
POST /auth/login
功能：用户登录，获取访问令牌（JWT）
Body 示例：
{
"apiKey": "your-api-key"
}
返回示例：
{
"token": "eyJhbGciOiJIUzI1NiIs..."
}
📥 数据接口
POST /entry
功能：上传单条数据
Body 示例：
{
"dataTime": 1617235200,
"data": {
"prov": "GD",
"city": "广州",
"unit": "广州XXX服务中心",
"proj": "广州xxx花园",
"cat": "3",
"code": "S3-B-02-0001",
"src": "燃料和能源活动",
"act_data": "1194.09551399661",
"co2e": "0.43615726534125"
}
}
返回示例：
{
"txHash": "0xabc123...",
"index": 1
}
PUT /entry/:index
功能：更新指定索引的数据
Body 示例：
{
"dataTime": 1617235200,
"data": {
"prov": "GD",
"city": "广州",
"unit": "广州XXX服务中心",
"proj": "广州xxx花园",
"cat": "3",
"code": "S3-B-02-0001",
"src": "燃料和能源活动",
"act_data": "1200",
"co2e": "0.5"
}
}
返回示例：
{
"txHash": "0xdef456...",
"updateFrom": 1,
"updateTo": 2
}
GET /entry/:index
功能：读取指定索引的数据
返回示例：
{
"index": 2,
"dataTime": 1617235200,
"data": {
"prov": "GD",
"city": "广州",
"unit": "广州XXX服务中心",
"proj": "广州xxx花园",
"cat": "3",
"code": "S3-B-02-0001",
"src": "燃料和能源活动",
"act_data": "1200",
"co2e": "0.5"
},
"version": 0,
"uploadTime": 1730371201,
"uploader": "0x1234...",
"updateFrom": 1,
"updateTo": 3,
"locked": false
}
POST /entry/batch
功能：批量上传多条数据
Body 示例：
[
{
"dataTime": 1617235200,
"data": {
"prov": "GD",
"city": "广州",
"unit": "广州XXX服务中心",
"proj": "广州xxx花园",
"cat": "3",
"code": "S3-B-02-0001",
"src": "燃料和能源活动",
"act_data": "1194.09551399661",
"co2e": "0.43615726534125"
}
},
{
"dataTime": 1614556800,
"data": {
"prov": "GD",
"city": "深圳",
"unit": "深圳XXX住宅服务中心",
"proj": "深圳xxx花园",
"cat": "1",
"code": "S1-A-02-0001",
"src": "汽油",
"act_data": "88.3206448398404",
"co2e": "0.19282714544342"
}
}
]
返回结果将包含每一条数据的索引。