Files
knowledge-governance/internal/qawemail/store.go
T
姚章浩 5e850e96f5
build / build (push) Successful in 2m18s
fix(qa-weekly-mail): 修复发送记录读回并区分未知投递
1) 发送记录读回(确定性回归):Sends() 的 SELECT 只有 6 列,Scan 却收 7 个字段(多出
message_id)。只要历史里存在任意一条发送记录,整个列表就返回 ErrUnavailable —— 发送
成功后页面刷新、以及“完成读真实发送记录”都会失败。改为查询带 message_id,并检查
rows.Err(),不把截断的列表当成完整历史。

2) 未知投递不再当成可重试失败:DATA 已提交但没收到最终 250(连接中断/超时)时,邮件可能
已被服务器接受;旧实现记 failed 并允许下一分钟重发,会重复投递。现在由 SMTPMailer 在
writer.Close() 失败处抛出窄类型 unknownDeliveryError,deliver 保留 sending 并记录原因,
自动/手动路径都不再重发(手动返回 ERRDeliveryUnknown,HTTP 409 说明原因)。连接建立前
失败、STARTTLS/AUTH/MAIL/RCPT/DATA 命令被拒、正文写入失败仍是确定失败,可如实 failed 并
重试一次。

3) SMTP 交互加有限期限:整体 90 秒(随请求 ctx 收紧),并用 context.AfterFunc 在取消时打断
阻塞读写,避免服务器接受 DATA 后不响应时挂死 worker 与发送行。

验证:真实隔离 PG 先 RED 后 GREEN(非空 sent+failed 历史读回成功并带真实 message_id;
HTTP GET /weekly-mail/sends 非空历史 200);本机 TLS SMTP 桩 + 真实 SMTPMailer 覆盖成功、
RCPT 550、DATA 后丢最终 250、DATA 阶段卡死(ctx 800ms 内返回)四类;真实 deliver 在未知
结果时留 sending 且不重发,在明确拒绝时 failed 并可重试一次成功。make verify 17 项全绿。
2026-11-09 01:06:09 +08:00

1049 lines
40 KiB
Go

package qawemail
import (
"context"
"crypto/aes"
"crypto/cipher"
"crypto/rand"
"crypto/sha256"
"crypto/tls"
"encoding/base64"
"encoding/hex"
"errors"
"fmt"
"net"
"net/mail"
"net/smtp"
"os"
"strings"
"time"
"github.com/jackc/pgx/v5"
"github.com/jackc/pgx/v5/pgxpool"
"github.com/yuin/goldmark"
"github.com/yuin/goldmark/extension"
)
var (
ErrUnavailable = errors.New("weekly mail store unavailable")
ErrInvalid = errors.New("weekly mail invalid input")
ErrConflict = errors.New("weekly mail settings changed")
ErrNoPassword = errors.New("weekly mail password missing")
// Manual resend has its own refusals: an operator must be told which rule failed instead of
// seeing a generic SMTP error for something SMTP never saw.
ErrNotCurrent = errors.New("weekly mail confirmation is not current")
ErrFutureWeek = errors.New("weekly mail week is in the future")
ErrSlotPending = errors.New("weekly mail slot has not arrived for the running week")
ErrNotConfigured = errors.New("weekly mail transport is not configured")
ErrSendInFlight = errors.New("weekly mail send outcome is unknown")
// ErrDeliveryUnknown is the honest answer when the SMTP exchange ended without a final
// verdict: the server may already have queued the message, so retrying could duplicate it.
ErrDeliveryUnknown = errors.New("weekly mail delivery outcome is unknown")
)
// unknownDeliveryError marks a failure where the server may already have accepted the message.
// Only the caller that knows the SMTP phase can raise it, so a plain I/O error never silently
// becomes "unknown" (and never silently becomes a retryable failure either).
type unknownDeliveryError struct{ err error }
func (e *unknownDeliveryError) Error() string { return e.err.Error() }
func (e *unknownDeliveryError) Unwrap() error { return e.err }
// IsUnknownDelivery reports whether the send may have reached the recipients.
func IsUnknownDelivery(err error) bool {
var unknown *unknownDeliveryError
return errors.As(err, &unknown)
}
// Settings never carries the SMTP password; HasPassword only says whether one is stored.
type Settings struct {
Host string `json:"host"`
Port int `json:"port"`
Username string `json:"username"`
From string `json:"from"`
Recipients []string `json:"recipients"`
Cc []string `json:"cc_recipients"`
Review string `json:"review_address"`
Weekday int `json:"weekday"`
Hour int `json:"hour"`
Enabled bool `json:"enabled"`
HasPassword bool `json:"has_password"`
Revision int64 `json:"revision"`
UpdatedBy string `json:"updated_by"`
UpdatedAt time.Time `json:"updated_at"`
}
type SettingsInput struct {
BaseRevision int64 `json:"base_revision"`
Host string `json:"host"`
Port int `json:"port"`
Username string `json:"username"`
Password string `json:"password"`
ClearPassword bool `json:"clear_password"`
From string `json:"from"`
Recipients []string `json:"recipients"`
Cc []string `json:"cc_recipients"`
Review string `json:"review_address"`
Weekday int `json:"weekday"`
Hour int `json:"hour"`
Enabled bool `json:"enabled"`
}
type Confirmation struct {
Week string `json:"week"`
HasImage bool `json:"has_image"`
DraftRevision int64 `json:"draft_revision"`
BodySHA256 string `json:"body_sha256"`
ConfirmedBy string `json:"confirmed_by"`
ConfirmedAt time.Time `json:"confirmed_at"`
Current bool `json:"current"`
}
type Send struct {
Week string `json:"week"`
Revision int64 `json:"draft_revision"`
Status string `json:"status"`
Attempts int `json:"attempts"`
LastError string `json:"last_error"`
MessageID string `json:"message_id"`
UpdatedAt time.Time `json:"updated_at"`
}
// InlineImage is embedded with a Content-ID so clients show it inside the body
// instead of as a detached attachment.
type InlineImage struct {
Name string
ContentType string
CID string
Bytes []byte
}
type Message struct {
To []string
Cc []string
From string
Subject string
HTML string
Text string
Images []InlineImage
}
// Mailer is the only outbound dependency; tests substitute it to prove the exact wire payload.
type Mailer interface {
Send(ctx context.Context, cfg SMTPConfig, msg Message) (string, error)
}
type SMTPConfig struct {
Host string
Port int
Username string
Password string
}
type Store struct {
pool *pgxpool.Pool
tenant string
keyFile string
mailer Mailer
now func() time.Time
}
func NewStore(pool *pgxpool.Pool, tenant, keyFile string, mailer Mailer) *Store {
if mailer == nil {
mailer = SMTPMailer{}
}
return &Store{pool: pool, tenant: tenant, keyFile: keyFile, mailer: mailer, now: time.Now}
}
func (s *Store) valid() bool {
return s != nil && s.pool != nil && strings.TrimSpace(s.tenant) != ""
}
func (s *Store) masterKey() ([]byte, error) {
info, err := os.Lstat(s.keyFile)
if err != nil || !info.Mode().IsRegular() || info.Mode().Perm() != 0o600 {
return nil, ErrUnavailable
}
raw, err := os.ReadFile(s.keyFile)
if err != nil || len(raw) != 32 {
return nil, ErrUnavailable
}
return raw, nil
}
func (s *Store) seal(secret string, revision int64) ([]byte, error) {
key, err := s.masterKey()
if err != nil {
return nil, err
}
block, err := aes.NewCipher(key)
if err != nil {
return nil, ErrUnavailable
}
aead, err := cipher.NewGCM(block)
if err != nil {
return nil, ErrUnavailable
}
nonce := make([]byte, aead.NonceSize())
if _, err = rand.Read(nonce); err != nil {
return nil, ErrUnavailable
}
// The AAD must not follow the settings revision: rotating recipients would otherwise
// make a previously saved password undecryptable.
return aead.Seal(nonce, nonce, []byte(secret), []byte("weekly-mail:"+s.tenant)), nil
}
func (s *Store) unseal(sealed []byte, revision int64) (string, error) {
if len(sealed) == 0 {
return "", ErrNoPassword
}
key, err := s.masterKey()
if err != nil {
return "", err
}
block, err := aes.NewCipher(key)
if err != nil {
return "", ErrUnavailable
}
aead, err := cipher.NewGCM(block)
if err != nil || len(sealed) < aead.NonceSize() {
return "", ErrUnavailable
}
nonce, body := sealed[:aead.NonceSize()], sealed[aead.NonceSize():]
raw, err := aead.Open(nil, nonce, body, []byte("weekly-mail:"+s.tenant))
if err == nil {
return string(raw), nil
}
// Legacy rows were sealed with the revision in the AAD; recover them without forcing
// the operator to paste the authorization code again.
for candidate := int64(1); candidate <= 8; candidate++ {
if plain, openErr := aead.Open(nil, nonce, body, []byte(fmt.Sprintf("weekly-mail:%s:%d", s.tenant, candidate))); openErr == nil {
return string(plain), nil
}
}
return "", ErrUnavailable
}
func validAddress(value string) bool {
parsed, err := mail.ParseAddress(strings.TrimSpace(value))
return err == nil && parsed.Address == strings.TrimSpace(value) && strings.Contains(parsed.Address, "@")
}
func normalize(input SettingsInput) (SettingsInput, error) {
input.Host = strings.TrimSpace(input.Host)
input.Username = strings.TrimSpace(input.Username)
input.From = strings.TrimSpace(input.From)
input.Review = strings.TrimSpace(input.Review)
seen := map[string]bool{}
recipients := make([]string, 0, len(input.Recipients))
for _, raw := range input.Recipients {
address := strings.TrimSpace(raw)
if address == "" || !validAddress(address) || seen[strings.ToLower(address)] {
return input, ErrInvalid
}
seen[strings.ToLower(address)] = true
recipients = append(recipients, address)
}
input.Recipients = recipients
cc := make([]string, 0, len(input.Cc))
for _, raw := range input.Cc {
address := strings.TrimSpace(raw)
if address == "" {
continue
}
// A copy that is also a primary recipient would receive the mail twice.
if !validAddress(address) || seen[strings.ToLower(address)] {
return input, ErrInvalid
}
seen[strings.ToLower(address)] = true
cc = append(cc, address)
}
input.Cc = cc
if input.Host != "" && !strings.Contains(input.Host, " ") && !strings.Contains(input.Host, "/") {
if _, err := net.LookupHost(input.Host); err != nil {
// A host that does not resolve yet stays a validation error, not a silent no-op.
return input, ErrInvalid
}
}
if input.Port == 0 {
input.Port = 465
}
if input.Weekday == 0 {
input.Weekday = 1
}
if input.Port < 1 || input.Port > 65535 || input.Weekday < 1 || input.Weekday > 7 || input.Hour < 0 || input.Hour > 23 {
return input, ErrInvalid
}
if input.Review != "" && !validAddress(input.Review) {
return input, ErrInvalid
}
if input.Enabled {
if input.Host == "" || input.From == "" || !validAddress(input.From) || len(input.Recipients) == 0 {
return input, ErrInvalid
}
}
return input, nil
}
func (s *Store) ReadSettings(ctx context.Context) (Settings, error) {
out := Settings{Port: 465, Weekday: 1, Hour: 9, Recipients: []string{}, Cc: []string{}}
if !s.valid() {
return out, ErrUnavailable
}
var sealed []byte
err := s.pool.QueryRow(ctx, `SELECT smtp_host,smtp_port,smtp_username,smtp_password_sealed,from_address,recipients,cc_recipients,review_address,send_weekday,send_hour,enabled,revision,updated_by,updated_at FROM qa_weekly_email_settings WHERE tenant_key=$1`, s.tenant).
Scan(&out.Host, &out.Port, &out.Username, &sealed, &out.From, &out.Recipients, &out.Cc, &out.Review, &out.Weekday, &out.Hour, &out.Enabled, &out.Revision, &out.UpdatedBy, &out.UpdatedAt)
if errors.Is(err, pgx.ErrNoRows) {
return out, nil
}
if err != nil {
return Settings{}, ErrUnavailable
}
if out.Recipients == nil {
out.Recipients = []string{}
}
if out.Cc == nil {
out.Cc = []string{}
}
out.HasPassword = len(sealed) > 0
return out, nil
}
func (s *Store) SaveSettings(ctx context.Context, actor string, input SettingsInput) (Settings, error) {
if !s.valid() || strings.TrimSpace(actor) == "" {
return Settings{}, ErrUnavailable
}
normalized, err := normalize(input)
if err != nil {
return Settings{}, err
}
ctx, cancel := context.WithTimeout(ctx, 8*time.Second)
defer cancel()
tx, err := s.pool.Begin(ctx)
if err != nil {
return Settings{}, ErrUnavailable
}
defer tx.Rollback(context.Background())
if _, err = tx.Exec(ctx, `SELECT pg_advisory_xact_lock(hashtextextended($1,257))`, "weekly-mail:"+s.tenant); err != nil {
return Settings{}, ErrUnavailable
}
var current int64
var sealed []byte
var passwordRevision int64
err = tx.QueryRow(ctx, `SELECT revision,smtp_password_sealed,password_revision FROM qa_weekly_email_settings WHERE tenant_key=$1 FOR UPDATE`, s.tenant).Scan(&current, &sealed, &passwordRevision)
if err != nil && !errors.Is(err, pgx.ErrNoRows) {
return Settings{}, ErrUnavailable
}
if current != input.BaseRevision {
return Settings{}, ErrConflict
}
next := current + 1
switch {
case normalized.ClearPassword:
sealed, passwordRevision = nil, 0
case strings.TrimSpace(normalized.Password) != "":
if sealed, err = s.seal(normalized.Password, next); err != nil {
return Settings{}, err
}
passwordRevision = next
}
if _, err = tx.Exec(ctx, `INSERT INTO qa_weekly_email_settings(tenant_key,smtp_host,smtp_port,smtp_username,smtp_password_sealed,from_address,recipients,cc_recipients,review_address,send_weekday,send_hour,enabled,revision,updated_by,updated_at,password_revision)
VALUES($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,now(),$15)
ON CONFLICT (tenant_key) DO UPDATE SET smtp_host=excluded.smtp_host,smtp_port=excluded.smtp_port,smtp_username=excluded.smtp_username,smtp_password_sealed=excluded.smtp_password_sealed,from_address=excluded.from_address,recipients=excluded.recipients,cc_recipients=excluded.cc_recipients,review_address=excluded.review_address,send_weekday=excluded.send_weekday,send_hour=excluded.send_hour,enabled=excluded.enabled,revision=excluded.revision,updated_by=excluded.updated_by,updated_at=now(),password_revision=excluded.password_revision`,
s.tenant, normalized.Host, normalized.Port, normalized.Username, sealed, normalized.From, normalized.Recipients, normalized.Cc, normalized.Review, normalized.Weekday, normalized.Hour, normalized.Enabled, next, actor, passwordRevision); err != nil {
return Settings{}, ErrUnavailable
}
if err = tx.Commit(ctx); err != nil {
return Settings{}, ErrUnavailable
}
return s.ReadSettings(ctx)
}
func bodyHash(markdown string) string {
sum := sha256.Sum256([]byte(markdown))
return hex.EncodeToString(sum[:])
}
// Confirm binds the confirmation to the exact revision and body the operator just reviewed,
// so a later edit invalidates it instead of silently mailing changed text.
func (s *Store) Confirm(ctx context.Context, week, actor string) (Confirmation, error) {
if !s.valid() || strings.TrimSpace(actor) == "" || strings.TrimSpace(week) == "" {
return Confirmation{}, ErrUnavailable
}
ctx, cancel := context.WithTimeout(ctx, 8*time.Second)
defer cancel()
var revision int64
var markdown string
if err := s.pool.QueryRow(ctx, `SELECT revision,markdown FROM qa_ops_weekly_drafts WHERE tenant_key=$1 AND week=$2`, s.tenant, week).Scan(&revision, &markdown); err != nil {
if errors.Is(err, pgx.ErrNoRows) {
return Confirmation{}, ErrInvalid
}
return Confirmation{}, ErrUnavailable
}
if revision <= 0 || strings.TrimSpace(markdown) == "" {
return Confirmation{}, ErrInvalid
}
var out Confirmation
err := s.pool.QueryRow(ctx, `INSERT INTO qa_weekly_confirmations(tenant_key,week,draft_revision,body_sha256,confirmed_by,confirmed_at)
VALUES($1,$2,$3,$4,$5,now())
ON CONFLICT (tenant_key,week) DO UPDATE SET draft_revision=excluded.draft_revision,body_sha256=excluded.body_sha256,confirmed_by=excluded.confirmed_by,confirmed_at=now()
RETURNING week,draft_revision,body_sha256,confirmed_by,confirmed_at`, s.tenant, week, revision, bodyHash(markdown), actor).
Scan(&out.Week, &out.DraftRevision, &out.BodySHA256, &out.ConfirmedBy, &out.ConfirmedAt)
if err != nil {
return Confirmation{}, ErrUnavailable
}
out.Current = true
return out, nil
}
func (s *Store) Unconfirm(ctx context.Context, week string) error {
if !s.valid() {
return ErrUnavailable
}
if _, err := s.pool.Exec(ctx, `DELETE FROM qa_weekly_confirmations WHERE tenant_key=$1 AND week=$2`, s.tenant, week); err != nil {
return ErrUnavailable
}
return nil
}
func (s *Store) ReadConfirmation(ctx context.Context, week string) (*Confirmation, error) {
if !s.valid() {
return nil, ErrUnavailable
}
var out Confirmation
var currentRevision int64
var currentMarkdown string
err := s.pool.QueryRow(ctx, `SELECT c.week,c.draft_revision,c.body_sha256,c.confirmed_by,c.confirmed_at,d.revision,d.markdown,c.dashboard_png IS NOT NULL
FROM qa_weekly_confirmations c LEFT JOIN qa_ops_weekly_drafts d ON d.tenant_key=c.tenant_key AND d.week=c.week
WHERE c.tenant_key=$1 AND c.week=$2`, s.tenant, week).
Scan(&out.Week, &out.DraftRevision, &out.BodySHA256, &out.ConfirmedBy, &out.ConfirmedAt, &currentRevision, &currentMarkdown, &out.HasImage)
if errors.Is(err, pgx.ErrNoRows) {
return nil, nil
}
if err != nil {
return nil, ErrUnavailable
}
out.Current = currentRevision == out.DraftRevision && currentMarkdown != "" && bodyHash(currentMarkdown) == out.BodySHA256
return &out, nil
}
func (s *Store) Sends(ctx context.Context, week string) ([]Send, error) {
if !s.valid() {
return nil, ErrUnavailable
}
rows, err := s.pool.Query(ctx, `SELECT week,draft_revision,status,attempts,last_error,message_id,updated_at FROM qa_weekly_email_sends WHERE tenant_key=$1 AND ($2='' OR week=$2) ORDER BY updated_at DESC LIMIT 50`, s.tenant, week)
if err != nil {
return nil, ErrUnavailable
}
defer rows.Close()
out := []Send{}
for rows.Next() {
var item Send
if err := rows.Scan(&item.Week, &item.Revision, &item.Status, &item.Attempts, &item.LastError, &item.MessageID, &item.UpdatedAt); err != nil {
return nil, ErrUnavailable
}
out = append(out, item)
}
// A read that stopped early is not a successful list: callers would silently show partial history.
if err := rows.Err(); err != nil {
return nil, ErrUnavailable
}
return out, nil
}
type DueResult struct {
State string `json:"state"`
Week string `json:"week,omitempty"`
MessageID string `json:"message_id,omitempty"`
SentAt time.Time `json:"sent_at,omitempty"`
Reason string `json:"reason,omitempty"`
}
// weekStart resolves the Beijing Monday of an ISO week label; reports are due after that week closes.
func weekStart(week string) (time.Time, error) {
var year, number int
if _, err := fmt.Sscanf(week, "%4d-W%2d", &year, &number); err != nil || year < 2000 || year > 2200 || number < 1 || number > 53 {
return time.Time{}, ErrInvalid
}
location := time.FixedZone("CST", 8*3600)
jan4 := time.Date(year, 1, 4, 0, 0, 0, 0, location)
offset := (int(jan4.Weekday()) + 6) % 7
start := jan4.AddDate(0, 0, -offset+7*(number-1))
if _, got := start.ISOWeek(); got != number {
return time.Time{}, ErrInvalid
}
return start, nil
}
var cstZone = time.FixedZone("CST", 8*3600)
// slotMatches is the single definition of "the configured weekly slot is now".
func slotMatches(settings Settings, now time.Time) bool {
local := now.In(cstZone)
weekday := int(local.Weekday())
if weekday == 0 {
weekday = 7
}
return weekday == settings.Weekday && local.Hour() == settings.Hour
}
// slotWeek names the report week the configured slot stands for.
//
// A slot on the week's last day (周日) reports the week that ends that same day; on every other
// weekday the week has already ended, which is what "周一 09:00 发上一个完整周" has always meant.
// Deriving the week from the slot — instead of asking reportClosed whether the week has ended —
// is what the 周日23点 configuration needs: that slot sits inside its own week, so waiting for the
// next Monday 00:00 would always miss the window it was configured for.
func slotWeek(settings Settings, now time.Time) (string, bool) {
if !slotMatches(settings, now) {
return "", false
}
day := now.In(cstZone)
if settings.Weekday != 7 {
day = day.AddDate(0, 0, -7)
}
year, number := day.ISOWeek()
return fmt.Sprintf("%04d-W%02d", year, number), true
}
// reportClosed reports whether the ISO week is over and its report may go out.
func reportClosed(week string, now time.Time) bool {
start, err := weekStart(week)
if err != nil {
return false
}
return !now.Before(start.AddDate(0, 0, 7))
}
// SendDue mails only the confirmed, still-current week the configured slot stands for.
// Every skip path returns a reason instead of pretending a message went out.
func (s *Store) SendDue(ctx context.Context, now time.Time) (DueResult, error) {
if !s.valid() {
return DueResult{}, ErrUnavailable
}
settings, err := s.ReadSettings(ctx)
if err != nil {
return DueResult{}, err
}
if !settings.Enabled {
return DueResult{State: "disabled", Reason: "未启用自动发送"}, nil
}
week, ok := slotWeek(settings, now)
if !ok {
return DueResult{State: "not_due", Reason: "未到设定发送时段"}, nil
}
// Only the week this slot stands for may go out automatically. Replaying every older
// confirmed week would turn one missed run into an unbounded backfill.
var revision, draftRevision int64
var hash, markdown string
err = s.pool.QueryRow(ctx, `SELECT c.draft_revision,c.body_sha256,d.revision,d.markdown
FROM qa_weekly_confirmations c JOIN qa_ops_weekly_drafts d ON d.tenant_key=c.tenant_key AND d.week=c.week
WHERE c.tenant_key=$1 AND c.week=$2`, s.tenant, week).Scan(&revision, &hash, &draftRevision, &markdown)
if errors.Is(err, pgx.ErrNoRows) {
return DueResult{State: "nothing_confirmed", Week: week, Reason: "该周没有已确认的周报"}, nil
}
if err != nil {
return DueResult{}, ErrUnavailable
}
if draftRevision != revision || bodyHash(markdown) != hash || strings.TrimSpace(markdown) == "" {
return DueResult{State: "nothing_confirmed", Week: week, Reason: "已确认的正文或版本已变化,需重新确认"}, nil
}
delivered, err := s.deliver(ctx, settings, week, revision, markdown, now, fmt.Sprintf("知识库周报 %s", week))
if err != nil {
return DueResult{}, err
}
return DueResult{State: delivered.state, Week: week, MessageID: delivered.messageID, SentAt: delivered.sentAt, Reason: delivered.reason}, nil
}
// SaveDashboardImage stores the dashboard PNG that belongs to the currently confirmed revision,
// so a later body edit (which invalidates the confirmation) never mails a stale chart.
func (s *Store) SaveDashboardImage(ctx context.Context, week string, png []byte) error {
if !s.valid() || strings.TrimSpace(week) == "" || len(png) < 8 || len(png) > 8<<20 {
return ErrInvalid
}
if string(png[:8]) != "\x89PNG\r\n\x1a\n" {
return ErrInvalid
}
sum := sha256.Sum256(png)
tag, err := s.pool.Exec(ctx, `UPDATE qa_weekly_confirmations SET dashboard_png=$2,dashboard_sha256=$3,dashboard_saved_at=now()
WHERE tenant_key=$1 AND week=$4`, s.tenant, png, hex.EncodeToString(sum[:]), week)
if err != nil {
return ErrUnavailable
}
if tag.RowsAffected() == 0 {
return ErrInvalid
}
return nil
}
func (s *Store) dashboardImage(ctx context.Context, week string) ([]byte, error) {
var png []byte
err := s.pool.QueryRow(ctx, `SELECT dashboard_png FROM qa_weekly_confirmations WHERE tenant_key=$1 AND week=$2`, s.tenant, week).Scan(&png)
if errors.Is(err, pgx.ErrNoRows) || len(png) == 0 {
return nil, nil
}
if err != nil {
return nil, ErrUnavailable
}
return png, nil
}
// TestSend mails a saved weekly body right now so an operator can verify the mailbox
// before any scheduled run. It never writes a send receipt and never marks a week as sent.
func (s *Store) TestSend(ctx context.Context, week string) (string, error) {
if !s.valid() || strings.TrimSpace(week) == "" {
return "", ErrInvalid
}
settings, err := s.ReadSettings(ctx)
if err != nil {
return "", err
}
if settings.Host == "" || settings.From == "" || len(settings.Recipients) == 0 {
return "", ErrInvalid
}
password, err := s.password(ctx, settings.Revision)
if err != nil {
return "", err
}
var markdown string
if err := s.pool.QueryRow(ctx, `SELECT markdown FROM qa_ops_weekly_drafts WHERE tenant_key=$1 AND week=$2`, s.tenant, week).Scan(&markdown); err != nil {
if errors.Is(err, pgx.ErrNoRows) {
return "", ErrInvalid
}
return "", ErrUnavailable
}
if strings.TrimSpace(markdown) == "" {
return "", ErrInvalid
}
html, text := renderReport(markdown)
images, err := s.inlineImages(ctx, week, &html)
if err != nil {
return "", err
}
// A review copy goes only to the operator's own review address so testing never
// reaches colleagues who are on the real distribution list.
target := settings.Recipients
if settings.Review != "" {
target = []string{settings.Review}
}
return s.mailer.Send(ctx, SMTPConfig{Host: settings.Host, Port: settings.Port, Username: settings.Username, Password: password},
Message{To: target, Cc: nil, From: settings.From, Subject: fmt.Sprintf("知识库周报 %s(测试发送)", week), HTML: html, Text: text, Images: images})
}
// delivery is what one attempt at a single (week, revision) proved: a state, never an assumption.
type delivery struct {
state string
messageID string
reason string
sentAt time.Time
}
// deliver is the only place a weekly report is rendered, claimed and handed to the mailer, so the
// automatic slot and the manual resend can never drift apart.
//
// The claim is also the concurrency control: only a brand-new row or a 'failed' row may be taken.
// A 'sent' row is idempotent, and a 'sending' row means the previous outcome is unknown — resending
// it could deliver the report twice, so it is reported instead of retried. (SMTP offers no exactly
// -once primitive; this is the strongest honest guarantee.)
func (s *Store) deliver(ctx context.Context, settings Settings, week string, revision int64, markdown string, now time.Time, subject string) (delivery, error) {
password, err := s.password(ctx, settings.Revision)
if err != nil {
return delivery{state: "blocked", reason: "SMTP 密码未配置或无法解密"}, nil
}
html, text := renderReport(markdown)
images, err := s.inlineImages(ctx, week, &html)
if err != nil {
return delivery{}, err
}
var sendID string
err = s.pool.QueryRow(ctx, `INSERT INTO qa_weekly_email_sends(tenant_key,week,draft_revision,body_sha256,status,attempts,created_at,updated_at)
VALUES($1,$2,$3,$4,'sending',1,now(),now())
ON CONFLICT (tenant_key,week,draft_revision) DO UPDATE SET status='sending',attempts=qa_weekly_email_sends.attempts+1,updated_at=now()
WHERE qa_weekly_email_sends.status='failed'
RETURNING id::text`, s.tenant, week, revision, bodyHash(markdown)).Scan(&sendID)
if errors.Is(err, pgx.ErrNoRows) {
return s.existingDelivery(ctx, week, revision)
}
if err != nil {
return delivery{}, ErrUnavailable
}
messageID, sendErr := s.mailer.Send(ctx, SMTPConfig{Host: settings.Host, Port: settings.Port, Username: settings.Username, Password: password},
Message{To: settings.Recipients, Cc: settings.Cc, From: settings.From, Subject: subject, HTML: html, Text: text, Images: images})
if sendErr != nil {
reason := sendErr.Error()
if len(reason) > 400 {
reason = reason[:400]
}
if IsUnknownDelivery(sendErr) {
// The message may already be queued at the server. Leaving the row in 'sending' makes
// every later attempt (automatic or manual) refuse instead of blindly re-delivering.
_, _ = s.pool.Exec(ctx, `UPDATE qa_weekly_email_sends SET last_error=$2,updated_at=now() WHERE id=$1`, sendID, reason)
return delivery{state: "unknown", reason: "SMTP 已提交但未收到最终确认,投递结果未知;为避免重复已停止自动重发,请核对已发出的邮件:" + reason}, nil
}
_, _ = s.pool.Exec(ctx, `UPDATE qa_weekly_email_sends SET status='failed',last_error=$2,updated_at=now() WHERE id=$1`, sendID, reason)
return delivery{state: "failed", reason: "发送失败:" + reason}, nil
}
if _, err = s.pool.Exec(ctx, `UPDATE qa_weekly_email_sends SET status='sent',message_id=$2,last_error='',updated_at=now() WHERE id=$1`, sendID, messageID); err != nil {
return delivery{}, ErrUnavailable
}
return delivery{state: "sent", messageID: messageID, sentAt: now}, nil
}
// existingDelivery explains why this attempt could not claim the row, instead of guessing.
func (s *Store) existingDelivery(ctx context.Context, week string, revision int64) (delivery, error) {
var status, messageID, lastError string
var updatedAt time.Time
err := s.pool.QueryRow(ctx, `SELECT status,message_id,last_error,updated_at FROM qa_weekly_email_sends
WHERE tenant_key=$1 AND week=$2 AND draft_revision=$3`, s.tenant, week, revision).Scan(&status, &messageID, &lastError, &updatedAt)
if err != nil {
return delivery{}, ErrUnavailable
}
switch status {
case "sent":
return delivery{state: "already_sent", messageID: messageID, reason: "该周该版本已发送,未重复投递", sentAt: updatedAt}, nil
case "sending":
return delivery{state: "in_flight", reason: "上次发送结果未知(记录停在 sending),为避免重复投递未重发;请先核对已发出的邮件"}, nil
default:
return delivery{state: "in_flight", reason: "发送记录状态与本次认领冲突(" + status + "),未重复投递"}, nil
}
}
type ManualResult struct {
Week string `json:"week"`
Revision int64 `json:"draft_revision"`
Status string `json:"status"`
MessageID string `json:"message_id,omitempty"`
Recipients int `json:"recipients"`
Cc int `json:"cc_recipients"`
Reason string `json:"reason,omitempty"`
SentAt time.Time `json:"sent_at,omitempty"`
}
// SendPreview is what the confirmation dialog must show before an operator commits: the exact
// week/revision and the real distribution counts the send would use.
type SendPreview struct {
Week string `json:"week"`
Revision int64 `json:"draft_revision"`
BodySHA256 string `json:"body_sha256"`
Recipients int `json:"recipients"`
Cc int `json:"cc_recipients"`
Status string `json:"status"`
MessageID string `json:"message_id,omitempty"`
SentAt time.Time `json:"sent_at,omitempty"`
}
// manualWindow decides whether a week may be sent by hand right now: a week that has ended is
// always fair game; the running week only once its own configured slot has arrived; a future week
// never.
func manualWindow(week string, settings Settings, now time.Time) error {
start, err := weekStart(week)
if err != nil {
return ErrInvalid
}
local := now.In(cstZone)
if start.After(local) {
return ErrFutureWeek
}
if !local.Before(start.AddDate(0, 0, 7)) {
return nil
}
slot := start.AddDate(0, 0, settings.Weekday-1).Add(time.Duration(settings.Hour) * time.Hour)
if local.Before(slot) {
return ErrSlotPending
}
return nil
}
// prepareManual binds a manual request to the confirmed revision and body that are live right now.
func (s *Store) prepareManual(ctx context.Context, week string, revision int64, hash string, now time.Time) (Settings, string, error) {
settings, err := s.ReadSettings(ctx)
if err != nil {
return settings, "", err
}
if settings.Host == "" || settings.From == "" || len(settings.Recipients) == 0 {
return settings, "", ErrNotConfigured
}
if err := manualWindow(week, settings, now); err != nil {
return settings, "", err
}
var confirmedRevision, draftRevision int64
var confirmedHash, markdown string
err = s.pool.QueryRow(ctx, `SELECT c.draft_revision,c.body_sha256,d.revision,d.markdown
FROM qa_weekly_confirmations c JOIN qa_ops_weekly_drafts d ON d.tenant_key=c.tenant_key AND d.week=c.week
WHERE c.tenant_key=$1 AND c.week=$2`, s.tenant, week).Scan(&confirmedRevision, &confirmedHash, &draftRevision, &markdown)
if errors.Is(err, pgx.ErrNoRows) {
return settings, "", ErrNotCurrent
}
if err != nil {
return settings, "", ErrUnavailable
}
if confirmedRevision != revision || confirmedHash != hash || draftRevision != revision ||
strings.TrimSpace(markdown) == "" || bodyHash(markdown) != hash {
return settings, "", ErrNotCurrent
}
return settings, markdown, nil
}
// PreviewSend validates a manual resend without sending or writing anything.
func (s *Store) PreviewSend(ctx context.Context, week string, revision int64, hash string, now time.Time) (SendPreview, error) {
if !s.valid() || revision <= 0 || len(strings.TrimSpace(hash)) != 64 {
return SendPreview{}, ErrInvalid
}
settings, _, err := s.prepareManual(ctx, week, revision, hash, now)
if err != nil {
return SendPreview{}, err
}
out := SendPreview{Week: week, Revision: revision, BodySHA256: hash, Recipients: len(settings.Recipients), Cc: len(settings.Cc), Status: "ready"}
var status, messageID string
var updatedAt time.Time
err = s.pool.QueryRow(ctx, `SELECT status,message_id,updated_at FROM qa_weekly_email_sends
WHERE tenant_key=$1 AND week=$2 AND draft_revision=$3`, s.tenant, week, revision).Scan(&status, &messageID, &updatedAt)
switch {
case errors.Is(err, pgx.ErrNoRows):
case err != nil:
return SendPreview{}, ErrUnavailable
case status == "sent":
out.Status, out.MessageID, out.SentAt = "already_sent", messageID, updatedAt
case status == "sending":
out.Status = "in_flight"
}
return out, nil
}
// SendManual is the explicit operator path for a missed or refused automatic run. It reuses the
// automatic render/claim/deliver path, so body, chart, To/Cc and idempotency are identical.
func (s *Store) SendManual(ctx context.Context, week string, revision int64, hash, actor string, now time.Time) (ManualResult, error) {
if !s.valid() || strings.TrimSpace(actor) == "" || revision <= 0 || len(strings.TrimSpace(hash)) != 64 {
return ManualResult{}, ErrInvalid
}
settings, markdown, err := s.prepareManual(ctx, week, revision, hash, now)
if err != nil {
return ManualResult{}, err
}
delivered, err := s.deliver(ctx, settings, week, revision, markdown, now, fmt.Sprintf("知识库周报 %s", week))
if err != nil {
return ManualResult{}, err
}
out := ManualResult{Week: week, Revision: revision, Status: delivered.state, MessageID: delivered.messageID,
Recipients: len(settings.Recipients), Cc: len(settings.Cc), Reason: delivered.reason, SentAt: delivered.sentAt}
switch delivered.state {
case "blocked":
return out, ErrNoPassword
case "in_flight":
return out, ErrSendInFlight
case "unknown":
return out, ErrDeliveryUnknown
}
return out, nil
}
const dashboardImageCID = "weekly-dashboard@knowledge-governance"
// inlineImages appends the confirmed dashboard chart to the end of the HTML body.
func (s *Store) inlineImages(ctx context.Context, week string, html *string) ([]InlineImage, error) {
png, err := s.dashboardImage(ctx, week)
if err != nil || len(png) == 0 {
return nil, err
}
footer := `<h2 style="font-size:17px;margin-top:24px;color:#17324d">统计看板</h2>` +
`<p><img src="cid:` + dashboardImageCID + `" alt="问题统计看板" style="max-width:100%;height:auto;border:1px solid #e5e7eb;border-radius:8px"></p>`
*html = strings.Replace(*html, "</body>", footer+"</body>", 1)
return []InlineImage{{Name: "dashboard.png", ContentType: "image/png", CID: dashboardImageCID, Bytes: png}}, nil
}
func (s *Store) password(ctx context.Context, revision int64) (string, error) {
var sealed []byte
var sealedAt int64
if err := s.pool.QueryRow(ctx, `SELECT smtp_password_sealed,password_revision FROM qa_weekly_email_settings WHERE tenant_key=$1`, s.tenant).Scan(&sealed, &sealedAt); err != nil {
return "", ErrUnavailable
}
if sealedAt <= 0 {
sealedAt = revision
}
return s.unseal(sealed, sealedAt)
}
func renderReport(markdown string) (string, string) {
converter := goldmark.New(goldmark.WithExtensions(extension.GFM))
var html strings.Builder
if err := converter.Convert([]byte(markdown), &html); err != nil {
html.Reset()
}
return `<!doctype html><html><head><meta charset="utf-8"><style>
body{font-family:-apple-system,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;color:#1f2937;line-height:1.7;margin:0;padding:24px;background:#fff}
h1{font-size:22px;border-bottom:2px solid #e5e7eb;padding-bottom:8px;margin-top:32px}
h2{font-size:17px;margin-top:24px;color:#17324d}
table{border-collapse:collapse}h1:first-child{margin-top:0}
</style></head><body>` + html.String() + `</body></html>`, markdown
}
// SMTPMailer speaks SMTP directly: implicit TLS on 465, STARTTLS elsewhere. Plaintext is refused.
// TLS is nil in production (system roots); an in-process test stub injects its own trust so the
// real mailer — not a mock — can be exercised end to end.
type SMTPMailer struct{ TLS *tls.Config }
// smtpExchangeTimeout bounds the whole SMTP conversation. Without it a server that accepts DATA
// and then stops responding would hang the worker (and hold the send row) indefinitely.
const smtpExchangeTimeout = 90 * time.Second
func (m SMTPMailer) tlsConfig(host string) *tls.Config {
cfg := &tls.Config{ServerName: host, MinVersion: tls.VersionTLS12}
if m.TLS != nil {
cfg = m.TLS.Clone()
if cfg.ServerName == "" {
cfg.ServerName = host
}
if cfg.MinVersion == 0 {
cfg.MinVersion = tls.VersionTLS12
}
}
return cfg
}
func (m SMTPMailer) Send(ctx context.Context, cfg SMTPConfig, msg Message) (string, error) {
if cfg.Host == "" || cfg.Port <= 0 || len(msg.To) == 0 || !validAddress(msg.From) {
return "", ErrInvalid
}
deadline := time.Now().Add(smtpExchangeTimeout)
if ctxDeadline, ok := ctx.Deadline(); ok && ctxDeadline.Before(deadline) {
deadline = ctxDeadline
}
address := net.JoinHostPort(cfg.Host, fmt.Sprint(cfg.Port))
dialer := &net.Dialer{Timeout: 15 * time.Second, Deadline: deadline}
var conn net.Conn
var err error
if cfg.Port == 465 {
conn, err = tls.DialWithDialer(dialer, "tcp", address, m.tlsConfig(cfg.Host))
} else {
conn, err = dialer.DialContext(ctx, "tcp", address)
}
if err != nil {
// The connection never opened: nothing was submitted, so this is a retryable failure.
return "", fmt.Errorf("smtp 连接失败: %w", err)
}
if err := conn.SetDeadline(deadline); err != nil {
conn.Close()
return "", fmt.Errorf("smtp 设置超时失败: %w", err)
}
// Cancellation must interrupt a blocked read/write, not just the dial.
stop := context.AfterFunc(ctx, func() { _ = conn.SetDeadline(time.Now()) })
defer stop()
client, err := smtp.NewClient(conn, cfg.Host)
if err != nil {
conn.Close()
return "", fmt.Errorf("smtp 握手失败: %w", err)
}
defer client.Close()
if cfg.Port != 465 {
if ok, _ := client.Extension("STARTTLS"); !ok {
return "", errors.New("smtp 服务器不支持 STARTTLS,已拒绝明文发送")
}
if err := client.StartTLS(m.tlsConfig(cfg.Host)); err != nil {
return "", fmt.Errorf("smtp STARTTLS 失败: %w", err)
}
}
if cfg.Username != "" {
if err := client.Auth(smtp.PlainAuth("", cfg.Username, cfg.Password, cfg.Host)); err != nil {
return "", fmt.Errorf("smtp 登录失败: %w", err)
}
}
if err := client.Mail(msg.From); err != nil {
return "", fmt.Errorf("smtp MAIL FROM 被拒: %w", err)
}
for _, to := range append(append([]string{}, msg.To...), msg.Cc...) {
if err := client.Rcpt(to); err != nil {
return "", fmt.Errorf("smtp RCPT 被拒: %w", err)
}
}
writer, err := client.Data()
if err != nil {
return "", fmt.Errorf("smtp DATA 被拒: %w", err)
}
messageID := fmt.Sprintf("<%s@%s>", hex.EncodeToString(randomBytes(12)), domainOf(msg.From))
boundary := hex.EncodeToString(randomBytes(10))
if _, err = writer.Write([]byte(buildMIME(msg, messageID, boundary))); err != nil {
// The body never finished uploading, so the server cannot have accepted it.
return "", fmt.Errorf("smtp 写入失败: %w", err)
}
if err = writer.Close(); err != nil {
// Close() sends the terminating "." and waits for the final 250. Losing that exchange
// (dropped connection, timeout) means the message may already be queued: it must stay
// unknown rather than be retried as a plain failure.
return "", &unknownDeliveryError{err: fmt.Errorf("smtp 提交后未收到最终确认: %w", err)}
}
_ = client.Quit()
return messageID, nil
}
func randomBytes(n int) []byte {
out := make([]byte, n)
_, _ = rand.Read(out)
return out
}
func domainOf(address string) string {
if at := strings.LastIndex(address, "@"); at >= 0 {
return address[at+1:]
}
return "localhost"
}
func buildMIME(msg Message, messageID, boundary string) string {
var body strings.Builder
body.WriteString("From: " + msg.From + "\r\n")
body.WriteString("To: " + strings.Join(msg.To, ", ") + "\r\n")
if len(msg.Cc) > 0 {
body.WriteString("Cc: " + strings.Join(msg.Cc, ", ") + "\r\n")
}
body.WriteString("Subject: " + mimeSubject(msg.Subject) + "\r\n")
body.WriteString("Date: " + time.Now().Format(time.RFC1123Z) + "\r\n")
body.WriteString("Message-ID: " + messageID + "\r\n")
body.WriteString("MIME-Version: 1.0\r\n")
alternative := func(w *strings.Builder) {
w.WriteString("--" + boundary + "\r\nContent-Type: text/plain; charset=UTF-8\r\nContent-Transfer-Encoding: base64\r\n\r\n")
w.WriteString(base64Lines(msg.Text))
w.WriteString("\r\n--" + boundary + "\r\nContent-Type: text/html; charset=UTF-8\r\nContent-Transfer-Encoding: base64\r\n\r\n")
w.WriteString(base64Lines(msg.HTML))
w.WriteString("\r\n--" + boundary + "--\r\n")
}
if len(msg.Images) == 0 {
body.WriteString("Content-Type: multipart/alternative; boundary=\"" + boundary + "\"\r\n\r\n")
alternative(&body)
return body.String()
}
// Images live in a multipart/related wrapper so "cid:" references render inline,
// after the text and HTML alternatives.
related := boundary + "-related"
body.WriteString("Content-Type: multipart/related; boundary=\"" + related + "\"; type=\"multipart/alternative\"\r\n\r\n")
body.WriteString("--" + related + "\r\nContent-Type: multipart/alternative; boundary=\"" + boundary + "\"\r\n\r\n")
alternative(&body)
for _, image := range msg.Images {
body.WriteString("--" + related + "\r\nContent-Type: " + image.ContentType + "; name=\"" + image.Name + "\"\r\n")
body.WriteString("Content-Transfer-Encoding: base64\r\nContent-ID: <" + image.CID + ">\r\n")
body.WriteString("Content-Disposition: inline; filename=\"" + image.Name + "\"\r\n\r\n")
body.WriteString(base64Lines(string(image.Bytes)))
body.WriteString("\r\n")
}
body.WriteString("--" + related + "--\r\n")
return body.String()
}
func base64Std(value string) string {
return base64.StdEncoding.EncodeToString([]byte(value))
}
func base64Lines(value string) string {
encoded := base64Std(value)
var out strings.Builder
for len(encoded) > 76 {
out.WriteString(encoded[:76] + "\r\n")
encoded = encoded[76:]
}
out.WriteString(encoded)
return out.String()
}
func mimeSubject(value string) string {
return "=?UTF-8?B?" + base64Std(value) + "?="
}