dapp/vote:add doc

plugin/dapp/vote/proto/vote.proto

@@ -6,112 +6,104 @@ package types;
 message VoteAction {
     int32 ty = 1;
     oneof value {
-        CreateGroup createGroup = 2;
-        UpdateMember updateMember = 3;
-        CreateVote createVote = 4;
-        CommitVote commitVote = 5;
-
+        CreateGroup  createGroup  = 2; //创建投票组
+        UpdateMember updateMember = 3; //更新组成员
+        CreateVote   createVote   = 4; //创建一个投票
+        CommitVote   commitVote   = 5; //组员提交投票
     }
 }
 
 message GroupMember {
-    string addr = 1;
-    uint32 voteWeight = 2;
+    string addr       = 1; //用户地址
+    uint32 voteWeight = 2; //投票权重， 不填时默认为1
 }
 
 //创建投票组
 message CreateGroup {
-    string name = 1;
-    repeated string admins = 2;
-    repeated GroupMember members = 3;
+    string   name                = 1; //投票组名称
+    repeated string admins       = 2; //管理员地址列表
+    repeated GroupMember members = 3; //组员
 }
 
 //更新投票组
-message UpdateMember{
-    string groupID = 1;
-    repeated GroupMember addMembers = 2;
-    repeated string removeMemberAddrs = 3;
+message UpdateMember {
+    string   groupID                  = 1; //投票组ID
+    repeated GroupMember addMembers   = 2; //需要增加的组成员
+    repeated string removeMemberAddrs = 3; //删除组成员的地址列表
 }
 
-//
+// 投票组信息
 message GroupInfo {
 
-    string ID = 1;
-    string name = 2;
-    uint32 memberNum = 3;
-    string creator = 4;
-    repeated string admins = 5;
-    repeated GroupMember members = 6;
-
+    string   ID                  = 1; //投票组ID
+    string   name                = 2; //投票组名称
+    uint32   memberNum           = 3; //组员数量
+    string   creator             = 4; //创建者
+    repeated string admins       = 5; //管理员列表
+    repeated GroupMember members = 6; //成员列表
 }
 
+//投票选项
 message VoteOption {
-    string option = 1;
-    uint32 score = 2;
+    string option = 1; //投票选项
+    uint32 score  = 2; //投票得分
 }
 
-//
-message CreateVote{
-    string name = 1;
-    repeated string voteGroups = 2;
-    repeated string voteOptions = 3;
-    int64 beginTimestamp = 4;
-    int64 endTimestamp = 5;
+// 创建投票交易，请求结构
+message CreateVote {
+    string   name                  = 1; //投票名称
+    repeated string voteGroups     = 2; //投票关联组列表
+    repeated string voteOptions    = 3; //投票选项列表
+    int64           beginTimestamp = 4; //投票开始时间戳
+    int64           endTimestamp   = 5; //投票结束时间戳
 }
 
-//
-message CommitVote{
-    string voteID = 1;
-    string groupID = 2;
-    uint32 optionIndex = 3;
+// 创建提交投票交易，请求结构
+message CommitVote {
+    string voteID      = 1; //投票ID
+    string groupID     = 2; //所属投票组ID
+    uint32 optionIndex = 3; //投票选项数组下标，下标对应投票内容
 }
 
-//
-message VoteInfo{
-
-    string ID = 1;
-    string name = 2;
-    string creator = 3;
-    repeated string voteGroups = 4;
-    repeated VoteOption voteOptions = 5;
-    int64 beginTimestamp = 6;
-    int64 endTimestamp = 7;
-    repeated string votedMembers = 8;
-
+//投票信息
+message VoteInfo {
+
+    string   ID                        = 1; //投票ID
+    string   name                      = 2; //投票名称
+    string   creator                   = 3; //投票创建者
+    repeated string voteGroups         = 4; //投票关联的投票组
+    repeated VoteOption voteOptions    = 5; //投票的选项
+    int64               beginTimestamp = 6; //投票开始时间戳
+    int64               endTimestamp   = 7; //投票结束时间戳
+    repeated string votedMembers       = 8; //已投票的成员
 }
 
 message VoteInfos {
-    repeated VoteInfo voteList = 1;
+    repeated VoteInfo voteList = 1; //投票信息列表
 }
 
+message GroupVoteInfo {
 
-message GroupVoteInfo{
-
-    GroupInfo groupInfo = 1;
-    repeated string voteIDs = 2;
+    GroupInfo groupInfo     = 1; // 投票组信息
+    repeated string voteIDs = 2; //投票组关联的投票ID信息
 }
 
-message GroupVoteInfos{
-    repeated GroupVoteInfo groupList = 1;
+message GroupVoteInfos {
+    repeated GroupVoteInfo groupList = 1; //投票组信息列表
 }
 
 message MemberInfo {
-    string addr = 1;
-    repeated string groupIDs = 2;
+    string   addr            = 1; //地址
+    repeated string groupIDs = 2; //所属投票组的ID列表
 }
 
-message MemberInfos{
-    repeated MemberInfo memberList = 1;
+message MemberInfos {
+    repeated MemberInfo memberList = 1; //投票组成员信息列表
 }
 
-message ReqListItem{
-    string startItemID = 1;
-    int32 count = 2;
-    int32 direction = 3;
+//列表请求结构
+message ReqListItem {
+    string startItemID = 1; //列表开始的ID，如请求组列表即groupID，不包含在结果中
+    int32  count       = 2; //请求列表项数量
+    int32  direction   = 3; // 0表示根据ID降序，1表示升序
 }
-
-
-
-
-
-

plugin/dapp/vote/readme.md

+
+## 投票合约
+基于区块链，公开透明的投票系统
+
+
+### 交易功能
+以下功能需要创建交易，并在链上执行
+
+#### 创建投票组
+
+- 设定投票组名称，管理员和组成员
+- 默认创建者为管理员
+- 可设定组成员的投票权重，默认都为1
+- 投票组ID在交易执行后自动生成
+
+##### 交易请求
+```proto
+
+//创建投票组
+message CreateGroup {
+    string   name                = 1; //投票组名称
+    repeated string admins       = 2; //管理员地址列表
+    repeated GroupMember members = 3; //组员
+}
+
+message GroupMember {
+    string addr       = 1; //用户地址
+    uint32 voteWeight = 2; //投票权重， 不填时默认为1
+}
+
+``` 
+
+##### 交易回执
+```proto
+ 
+// 投票组信息
+message GroupInfo {
+
+    string   ID                  = 1; //投票组ID
+    string   name                = 2; //投票组名称
+    uint32   memberNum           = 3; //组员数量
+    string   creator             = 4; //创建者
+    repeated string admins       = 5; //管理员列表
+    repeated GroupMember members = 6; //成员列表
+}
+
+```
+
+#### 更新投票组成员
+指定投票组ID，并由管理员添加或删除组成员
+
+##### 交易请求
+```proto
+message UpdateMember {
+    string   groupID                  = 1; //投票组ID
+    repeated GroupMember addMembers   = 2; //需要增加的组成员
+    repeated string removeMemberAddrs = 3; //删除组成员的地址列表
+}
+```
+##### 交易回执
+```proto
+ 
+// 投票组信息
+message GroupInfo {
+
+    string   ID                  = 1; //投票组ID
+    string   name                = 2; //投票组名称
+    uint32   memberNum           = 3; //组员数量
+    string   creator             = 4; //创建者
+    repeated string admins       = 5; //管理员列表
+    repeated GroupMember members = 6; //成员列表
+}
+
+```
+
+
+#### 创建投票
+- 设定投票名称，投票选项，关联投票组ID
+- 关联投票组，即只有这些投票组的成员进行投票
+- 投票ID在交易执行后生成
+
+##### 交易请求
+```proto
+
+// 创建投票交易，请求结构
+message CreateVote {
+    string   name                  = 1; //投票名称
+    repeated string voteGroups     = 2; //投票关联组列表
+    repeated string voteOptions    = 3; //投票选项列表
+    int64           beginTimestamp = 4; //投票开始时间戳
+    int64           endTimestamp   = 5; //投票结束时间戳
+}
+
+``` 
+
+##### 交易回执
+```proto
+
+//投票信息
+message VoteInfo {
+
+    string   ID                        = 1; //投票ID
+    string   name                      = 2; //投票名称
+    string   creator                   = 3; //投票创建者
+    repeated string voteGroups         = 4; //投票关联的投票组
+    repeated VoteOption voteOptions    = 5; //投票的选项
+    int64               beginTimestamp = 6; //投票开始时间戳
+    int64               endTimestamp   = 7; //投票结束时间戳
+    repeated string votedMembers       = 8; //已投票的成员
+}
+```
+
+#### 提交投票
+- 群成员发起投票交易
+- 指定所在投票群ID，投票ID，投票选项
+- 投票选项使用数组下标标识，而不是选项内容
+
+##### 交易请求
+```proto
+
+// 创建提交投票交易，请求结构
+message CommitVote {
+    string voteID      = 1; //投票ID
+    string groupID     = 2; //所属投票组ID
+    uint32 optionIndex = 3; //投票选项数组下标，下标对应投票内容
+}
+
+```
+
+##### 交易回执
+```proto
+
+//投票信息
+message VoteInfo {
+
+    string   ID                        = 1; //投票ID
+    string   name                      = 2; //投票名称
+    string   creator                   = 3; //投票创建者
+    repeated string voteGroups         = 4; //投票关联的投票组
+    repeated VoteOption voteOptions    = 5; //投票的选项
+    int64               beginTimestamp = 6; //投票开始时间戳
+    int64               endTimestamp   = 7; //投票结束时间戳
+    repeated string votedMembers       = 8; //已投票的成员
+}
+```
+
+
+### 查询功能
+以下功能为本地查询，无需创建交易
+
+#### 获取组信息
+根据投票组ID查询组信息
+
+##### 请求结构
+```proto
+message ReqString {
+    string Data = 1;
+}
+```
+
+##### 响应结构
+
+```proto
+message GroupVoteInfo {
+
+    GroupInfo groupInfo     = 1; // 投票组信息
+    repeated string voteIDs = 2; //投票组关联的投票ID信息
+}
+```
+
+#### 获取投票信息
+根据投票ID查询投票信息
+
+##### 请求结构
+```proto
+message ReqString {
+    string Data = 1;
+}
+```
+
+##### 响应结构
+```proto
+message VoteInfo {
+
+    string   ID                        = 1; //投票ID
+    string   name                      = 2; //投票名称
+    string   creator                   = 3; //投票创建者
+    repeated string voteGroups         = 4; //投票关联的投票组
+    repeated VoteOption voteOptions    = 5; //投票的选项
+    int64               beginTimestamp = 6; //投票开始时间戳
+    int64               endTimestamp   = 7; //投票结束时间戳
+    repeated string votedMembers       = 8; //已投票的成员
+}
+```
+
+#### 获取成员信息
+根据成员地址，查询成员信息
+
+##### 请求结构
+```proto
+message ReqString {
+    string Data = 1;
+}
+```
+
+##### 响应结构
+```proto
+ 
+message MemberInfo {
+    string   addr            = 1; //地址
+    repeated string groupIDs = 2; //所属投票组的ID列表
+}
+```
+
+#### 获取投票组列表
+
+##### 请求结构
+```proto
+//列表请求结构
+message ReqListItem {
+    string startItemID = 1; //列表开始的ID，如请求组列表即groupID，不包含在结果中
+    int32  count       = 2; //请求列表项数量
+    int32  direction   = 3; // 0表示根据ID降序，1表示升序
+}
+```
+
+##### 响应结构
+```proto
+message GroupVoteInfos {
+    repeated GroupVoteInfo groupList = 1; //投票组信息列表
+}
+```
+
+#### 获取投票列表
+
+##### 请求结构
+```proto
+//列表请求结构
+message ReqListItem {
+    string startItemID = 1; //列表开始的ID，如请求组列表即groupID，不包含在结果中
+    int32  count       = 2; //请求列表项数量
+    int32  direction   = 3; // 0表示根据ID降序，1表示升序
+}
+```
+
+##### 响应结构
+```proto
+message VoteInfos {
+    repeated VoteInfo voteList = 1; //投票信息列表
+}
+```
+
+#### 获取投票组成员列表
+
+##### 请求结构
+
+```proto
+//列表请求结构
+message ReqListItem {
+    string startItemID = 1; //列表开始的ID，如请求组列表即groupID，不包含在结果中
+    int32  count       = 2; //请求列表项数量
+    int32  direction   = 3; // 0表示根据ID降序，1表示升序
+}
+```
+
+##### 响应结构
+```proto
+message MemberInfos {
+    repeated MemberInfo memberList = 1; //投票组成员信息列表
+}
+```
+
+####其他 
+ 
+[投票合约proto源文件](proto/vote.proto)

plugin/dapp/vote/types/vote.pb.go

@@ -299,7 +299,7 @@ func (m *UpdateMember) GetRemoveMemberAddrs() []string {
 	return nil
 }
 
-//
+// 投票组信息
 type GroupInfo struct {
 	ID                   string         `protobuf:"bytes,1,opt,name=ID,proto3" json:"ID,omitempty"`
 	Name                 string         `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
@@ -379,6 +379,7 @@ func (m *GroupInfo) GetMembers() []*GroupMember {
 	return nil
 }
 
+//投票选项
 type VoteOption struct {
 	Option               string   `protobuf:"bytes,1,opt,name=option,proto3" json:"option,omitempty"`
 	Score                uint32   `protobuf:"varint,2,opt,name=score,proto3" json:"score,omitempty"`
@@ -426,7 +427,7 @@ func (m *VoteOption) GetScore() uint32 {
 	return 0
 }
 
-//
+// 创建投票交易，请求结构
 type CreateVote struct {
 	Name                 string   `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
 	VoteGroups           []string `protobuf:"bytes,2,rep,name=voteGroups,proto3" json:"voteGroups,omitempty"`
@@ -498,7 +499,7 @@ func (m *CreateVote) GetEndTimestamp() int64 {
 	return 0
 }
 
-//
+// 创建提交投票交易，请求结构
 type CommitVote struct {
 	VoteID               string   `protobuf:"bytes,1,opt,name=voteID,proto3" json:"voteID,omitempty"`
 	GroupID              string   `protobuf:"bytes,2,opt,name=groupID,proto3" json:"groupID,omitempty"`
@@ -554,7 +555,7 @@ func (m *CommitVote) GetOptionIndex() uint32 {
 	return 0
 }
 
-//
+//投票信息
 type VoteInfo struct {
 	ID                   string        `protobuf:"bytes,1,opt,name=ID,proto3" json:"ID,omitempty"`
 	Name                 string        `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
@@ -861,6 +862,7 @@ func (m *MemberInfos) GetMemberList() []*MemberInfo {
 	return nil
 }
 
+//列表请求结构
 type ReqListItem struct {
 	StartItemID          string   `protobuf:"bytes,1,opt,name=startItemID,proto3" json:"startItemID,omitempty"`
 	Count                int32    `protobuf:"varint,2,opt,name=count,proto3" json:"count,omitempty"`