docs/update readme (#8)

更新 README
1. 簡述專案架構、重點資料夾或檔案的功用
2. 能夠在本地端啟動的教學

Co-authored-by: Simon Hung <yihsuan.simon@email.com>
Reviewed-on: #8
Reviewed-by: 王性驊 <igs170911@gmail.com>
Co-authored-by: simon.yhh <simon.yhh@30cm.net>
Co-committed-by: simon.yhh <simon.yhh@30cm.net>

README.md

@@ -0,0 +1,90 @@
+# 專案說明
+
+通知服務
+
+# 專案架構
+
+```
+$tree -L 3 --gitignore
+
+.
+├── Makefile
+├── build
+│   └── Dockerfile
+├── chart
+│   └── readme.md
+├── etc
+│   └── service.example.yaml   # 設定檔範例
+├── generate                   # 這個資料夾會用來自動生成一些程式
+│   ├── database                 ## 資料庫生成檔案或紀錄遷移版本
+│   │   ├── mongodb
+│   │   ├── mysql
+│   │   ├── readme.md
+│   │   └── seeder
+│   └── protobuf                 ## gRPC 的定義，用來生成 gRPC 檔案
+│       └── notification.proto
+├── go.mod
+├── internal
+│   ├── config                 # 設定的結構
+│   │   └── config.go
+│   ├── domain                 # 此服務下的一些常數定義
+│   │   ├── errors.go            ## 錯誤定義
+│   │   └── usecase              ## usecase 內的常數定義
+│   │       ├── mail.go
+│   │       └── sms.go
+│   ├── logic                  # 主要的程式邏輯都在這，每個功能用一個資料夾開發
+│   │   └── senderservice
+│   ├── server
+│   │   └── senderservice      # gRPC 自動產生的檔案
+│   ├── svc                    # 此服務下會共用的功能，例如 API context, db 連線等
+│   │   └── service_context.go   ## API context
+│   └── usecase
+│       ├── mitake.go
+│       └── smtp.go
+└── notification.go            # 服務主入口
+```
+
+# 啟動說明
+
+此文件會介紹以下兩種啟動方式：
+
+1. Docker 啟動 (Production 時使用)
+2. 本地端 go compiler 啟動 (開發、測試時使用)
+
+## Docker 啟動 (Production)
+
+```bash
+make build-docker
+make run-docker
+```
+
+## 本地端啟動（測試用）
+
+```bash
+go mod tidy
+# 進入 etc/notification.yml 設定各依賴的 config
+go run notification.go
+```
+
+### 本地啟動需要依賴套件或工具
+
+以下已 macOS 為例，若已安裝或有其他可用服務則可跳過
+
+- go-zero goctl (https://go-zero.dev/docs/tasks/installation/goctl)
+  ```bash
+  $ go install github.com/zeromicro/go-zero/tools/goctl@latest
+  ```
+- protobuf (https://protobuf.dev/)
+  ```bash
+  brew install protobuf
+  ```
+- etcd (https://etcd.io/)
+  ```bash
+  brew install etcd
+  brew services start etcd
+  ```
+- SMTP 服務（以 mailhog 為例） (https://github.com/mailhog/MailHog)
+  ```bash
+  brew install mailhog
+  brew services start mailhog
+  ```

build/Dockerfile

@@ -32,7 +32,7 @@ RUN --mount=type=ssh go mod download
 
 RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
     -ldflags "$FLAG" \
-    -o service
+    -o notification
 
 ##########
 ## FINAL #
@@ -44,4 +44,4 @@ WORKDIR /app
 COPY --from=builder /app/service /app/service
 COPY --from=builder /app/etc/service.yaml /app/etc/service.yaml
 EXPOSE 8080
-CMD ["/app/service"]
+CMD ["/app/notification"]

etc/service.example.yaml

@@ -5,12 +5,12 @@ Etcd:
     - 127.0.0.1:2379
   Key: notification.rpc
 SMTP:
-  Host: smtp.mailgun.org
+  Host: smtp.mail.host
   Port: 25
-  User: postmaster@abc123@30.com
+  User: smtp@user.net
-  Password: gg88g88
+  Password: smtp_password
 
 SMSSender:
-  User: daniel@30cm.net
+  User: sms@user.net
-  Password : test123
+  Password : sms_password
 

go.mod

@@ -3,7 +3,7 @@ module app-cloudep-notification-service
 go 1.22.3
 
 require (
-	code.30cm.net/digimon/library-go/errors v1.0.0
+	code.30cm.net/digimon/library-go/errs v1.2.3
 	code.30cm.net/digimon/library-go/validator v1.0.0
 	code.30cm.net/digimon/library-go/worker_pool v0.0.0-20240820153352-f9c90a90f5e2
 	github.com/minchao/go-mitake v1.0.0

internal/domain/errors.go

@@ -0,0 +1,58 @@
+package domain
+
+import (
+	"fmt"
+	"strings"
+
+	"code.30cm.net/digimon/library-go/errs"
+	"code.30cm.net/digimon/library-go/errs/code"
+	"github.com/zeromicro/go-zero/core/logx"
+)
+
+type ErrorCode uint32
+
+func (e ErrorCode) ToUint32() uint32 {
+	return uint32(e)
+}
+
+const (
+	_                           = iota
+	SendMailErrorCode ErrorCode = iota
+	SendSMSErrorCode
+)
+
+// SendMailError ...
+func SendMailError(s ...string) *errs.LibError {
+	return errs.NewError(code.CloudEPNotification, code.ThirdParty,
+		SendMailErrorCode.ToUint32(),
+		fmt.Sprintf("%s", strings.Join(s, " ")))
+}
+
+// SendMailErrorL logs error message and returns Err
+func SendMailErrorL(l logx.Logger, filed []logx.LogField, s ...string) *errs.LibError {
+	e := SendMailError(s...)
+	if filed != nil || len(filed) >= 0 {
+		l.WithCallerSkip(1).WithFields(filed...).Error(e.Error())
+	}
+	l.WithCallerSkip(1).Error(e.Error())
+
+	return e
+}
+
+// SendSMSError ...
+func SendSMSError(s ...string) *errs.LibError {
+	return errs.NewError(code.CloudEPNotification, code.ThirdParty,
+		SendSMSErrorCode.ToUint32(),
+		fmt.Sprintf("%s", strings.Join(s, " ")))
+}
+
+// SendSMSErrorL logs error message and returns Err
+func SendSMSErrorL(l logx.Logger, filed []logx.LogField, s ...string) *errs.LibError {
+	e := SendSMSError(s...)
+	if filed != nil || len(filed) >= 0 {
+		l.WithCallerSkip(1).WithFields(filed...).Error(e.Error())
+	}
+	l.WithCallerSkip(1).Error(e.Error())
+
+	return e
+}

internal/logic/senderservice/send_mail_by_template_id_logic.go

@@ -4,9 +4,7 @@ import (
 	"app-cloudep-notification-service/gen_result/pb/notification"
 	"app-cloudep-notification-service/internal/svc"
 	"context"
-	"fmt"
 
-	ers "code.30cm.net/digimon/library-go/errors"
 	"github.com/zeromicro/go-zero/core/logx"
 )
 
@@ -26,7 +24,6 @@ func NewSendMailByTemplateIdLogic(ctx context.Context, svcCtx *svc.ServiceContex
 
 // SendMailByTemplateId 寄送模板信件
 func (l *SendMailByTemplateIdLogic) SendMailByTemplateId(in *notification.SendByTemplateIDReq) (*notification.OKResp, error) {
-	fmt.Println(ers.ResourceNotFound("testing"))
 
 	return &notification.OKResp{}, nil
 }

internal/logic/senderservice/send_mail_logic.go

@@ -1,10 +1,11 @@
 package senderservicelogic
 
 import (
+	"app-cloudep-notification-service/internal/domain"
 	"app-cloudep-notification-service/internal/domain/usecase"
 	"context"
 
-	ers "code.30cm.net/digimon/library-go/errors"
+	ers "code.30cm.net/digimon/library-go/errs"
 
 	"app-cloudep-notification-service/gen_result/pb/notification"
 	"app-cloudep-notification-service/internal/svc"
@@ -45,7 +46,7 @@ func (l *SendMailLogic) SendMail(in *notification.SendMailReq) (*notification.OK
 		Body:    in.GetBody(),
 		From:    in.GetFrom(),
 	}); err != nil {
-		return nil, ers.InvalidFormat(err.Error())
+		return nil, ers.InvalidFormat("invalid format")
 	}
 
 	// TODO 以後可以做換線
@@ -56,12 +57,15 @@ func (l *SendMailLogic) SendMail(in *notification.SendMailReq) (*notification.OK
 		Body:    in.GetBody(),
 	})
 	if err != nil {
-		logx.WithCallerSkip(1).WithFields(
+		return nil, domain.SendMailErrorL(
-			logx.Field("func", "MailSender.SendMail"),
+			logx.WithContext(l.ctx),
-			logx.Field("in", in),
+			[]logx.LogField{
-			logx.Field("err", err),
+				logx.Field("func", "MailSender.SendMail"),
-		).Error(err.Error())
+				logx.Field("in", in),
-		return nil, ers.ArkInternal("MailSender.SendMail failed to send mail")
+				logx.Field("err", err),
+			},
+			"MailSender.SendMail failed to send mail",
+		)
 	}
 
 	return &notification.OKResp{}, nil

internal/logic/senderservice/send_sms_by_template_id_logic.go

@@ -23,7 +23,7 @@ func NewSendSmsByTemplateIdLogic(ctx context.Context, svcCtx *svc.ServiceContext
 	}
 }
 
-// SendSMSByTemplateID 寄送模板簡訊
+// SendSmsByTemplateId 寄送模板簡訊
 func (l *SendSmsByTemplateIdLogic) SendSmsByTemplateId(in *notification.SendByTemplateIDReq) (*notification.OKResp, error) {
 	// todo: add your logic here and delete this line
 

internal/logic/senderservice/send_sms_logic.go

@@ -1,10 +1,11 @@
 package senderservicelogic
 
 import (
+	"app-cloudep-notification-service/internal/domain"
 	"app-cloudep-notification-service/internal/domain/usecase"
 	"context"
 
-	ers "code.30cm.net/digimon/library-go/errors"
+	"code.30cm.net/digimon/library-go/errs"
 
 	"app-cloudep-notification-service/gen_result/pb/notification"
 	"app-cloudep-notification-service/internal/svc"
@@ -42,7 +43,7 @@ func (l *SendSmsLogic) SendSms(in *notification.SendSMSReq) (*notification.OKRes
 		Body:             in.GetBody(),
 		RecipientAddress: in.GetTo(),
 	}); err != nil {
-		return nil, ers.InvalidFormat(err.Error())
+		return nil, errs.InvalidFormat(err.Error())
 	}
 
 	// TODO 以後可以做換線
@@ -52,12 +53,15 @@ func (l *SendSmsLogic) SendSms(in *notification.SendSMSReq) (*notification.OKRes
 		Body:             in.GetBody(),
 	})
 	if err != nil {
-		logx.WithCallerSkip(1).WithFields(
+		return nil, domain.SendSMSErrorL(
-			logx.Field("func", "SMSSender.SendSMS"),
+			logx.WithContext(l.ctx),
-			logx.Field("in", in),
+			[]logx.LogField{
-			logx.Field("err", err),
+				logx.Field("func", "SMSSender.SendSMS"),
-		).Error(err.Error())
+				logx.Field("in", in),
-		return nil, ers.ArkInternal("SMSSender.SendSMS failed to send sms")
+				logx.Field("err", err),
+			},
+			"SMSSender.SendSMS failed to send sms",
+		)
 	}
 
 	return &notification.OKResp{}, nil

internal/svc/service_context.go

@@ -5,6 +5,9 @@ import (
 	domainUC "app-cloudep-notification-service/internal/domain/usecase"
 	"app-cloudep-notification-service/internal/usecase"
 
+	"code.30cm.net/digimon/library-go/errs"
+	"code.30cm.net/digimon/library-go/errs/code"
+
 	v "code.30cm.net/digimon/library-go/validator"
 )
 
@@ -17,6 +20,7 @@ type ServiceContext struct {
 }
 
 func NewServiceContext(c config.Config) *ServiceContext {
+	errs.Scope = code.CloudEPNotification
 	return &ServiceContext{
 		Config:     c,
 		MailSender: usecase.MustMailgunUseCase(usecase.MailUseCaseParam{Conf: c}),