Files
knowledge-governance/internal/httpapi/qa_weekly_mail.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

308 lines
11 KiB
Go

package httpapi
import (
"context"
"encoding/base64"
"errors"
"knowledge-governance/internal/dobotaiops"
"knowledge-governance/internal/qawemail"
"net/http"
"strconv"
"time"
)
type weeklyMailStore interface {
ReadSettings(context.Context) (qawemail.Settings, error)
SaveSettings(context.Context, string, qawemail.SettingsInput) (qawemail.Settings, error)
Confirm(context.Context, string, string) (qawemail.Confirmation, error)
Unconfirm(context.Context, string) error
ReadConfirmation(context.Context, string) (*qawemail.Confirmation, error)
Sends(context.Context, string) ([]qawemail.Send, error)
TestSend(context.Context, string) (string, error)
SaveDashboardImage(context.Context, string, []byte) error
SendDue(context.Context, time.Time) (qawemail.DueResult, error)
PreviewSend(context.Context, string, int64, string, time.Time) (qawemail.SendPreview, error)
SendManual(context.Context, string, int64, string, string, time.Time) (qawemail.ManualResult, error)
}
// weeklyMailSendError names the rule that refused a manual resend. Anything SMTP-related is
// reported by the handler itself, so an unmet precondition never looks like a mail failure.
func weeklyMailSendError(w http.ResponseWriter, err error) {
switch {
case errors.Is(err, qawemail.ErrNotCurrent):
writeJSON(w, http.StatusConflict, map[string]string{"error": "该周周报未确认,或确认后正文/版本已变化;请先确认当前版本再补发"})
case errors.Is(err, qawemail.ErrFutureWeek):
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "不能补发未来周"})
case errors.Is(err, qawemail.ErrSlotPending):
writeJSON(w, http.StatusConflict, map[string]string{"error": "本周尚未到达设定的发送时点,暂不能补发"})
case errors.Is(err, qawemail.ErrNotConfigured):
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "未配置邮件服务器、发件人或收件人,无法补发"})
case errors.Is(err, qawemail.ErrSendInFlight):
writeJSON(w, http.StatusConflict, map[string]string{"error": "该周该版本有一次发送结果未知(记录停在发送中),为避免重复投递未重发;请先核对已发出的邮件"})
case errors.Is(err, qawemail.ErrDeliveryUnknown):
writeJSON(w, http.StatusConflict, map[string]string{"error": "SMTP 已提交但未收到最终确认,投递结果未知;为避免重复已停止重发,请先核对已发出的邮件"})
case errors.Is(err, qawemail.ErrNoPassword):
writeJSON(w, http.StatusConflict, map[string]string{"error": "SMTP 授权码缺失或无法解密,无法补发"})
case errors.Is(err, qawemail.ErrInvalid):
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "补发参数无效:需要精确的周、已确认版本与正文 hash"})
default:
weeklyMailError(w, err)
}
}
// qaWeeklyMailSendPreview lets the confirmation dialog show the exact week, revision and
// distribution this send would use — the same settings the send path reads.
func qaWeeklyMailSendPreview(w http.ResponseWriter, r *http.Request, c Config) {
if !authorizeQAOps(w, r) {
return
}
store, ok := c.QAWeeklyMail.(weeklyMailStore)
if !ok {
weeklyMailError(w, qawemail.ErrUnavailable)
return
}
query := r.URL.Query()
revision, err := strconv.ParseInt(query.Get("revision"), 10, 64)
if err != nil {
weeklyMailSendError(w, qawemail.ErrInvalid)
return
}
preview, err := store.PreviewSend(r.Context(), r.PathValue("week"), revision, query.Get("body_sha256"), time.Now())
if err != nil {
weeklyMailSendError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": preview})
}
// qaWeeklyMailSend is the formal resend: admin only, bound to the live confirmation, and the same
// render/claim path as the automatic slot. It is not a test send and never targets the review box.
func qaWeeklyMailSend(w http.ResponseWriter, r *http.Request, c Config) {
if !authorizeQAOps(w, r) || !authorizeQAIntent(w, r, "qa-weekly-mail") {
return
}
identity, ok := sessionFrom(r.Context())
if !ok || identity.Role != "admin" {
writeJSON(w, http.StatusForbidden, map[string]string{"error": "仅管理员可正式补发周报"})
return
}
store, found := c.QAWeeklyMail.(weeklyMailStore)
if !found {
weeklyMailError(w, qawemail.ErrUnavailable)
return
}
var request struct {
Revision int64 `json:"revision"`
BodySHA256 string `json:"body_sha256"`
}
if decodeQualityJSON(w, r, &request) != nil {
weeklyMailError(w, qawemail.ErrInvalid)
return
}
result, err := store.SendManual(r.Context(), r.PathValue("week"), request.Revision, request.BodySHA256, identity.Username, time.Now())
if err != nil {
weeklyMailSendError(w, err)
return
}
if result.Status == "failed" {
reason := result.Reason
if len(reason) > 300 {
reason = reason[:300]
}
writeJSON(w, http.StatusBadGateway, map[string]string{"error": "正式补发未送达:" + reason})
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": result})
}
func weeklyMailError(w http.ResponseWriter, err error) {
switch {
case errors.Is(err, qawemail.ErrConflict):
writeJSON(w, http.StatusConflict, map[string]string{"error": "发送设置已被其他人修改,请重新读取后再保存"})
case errors.Is(err, qawemail.ErrInvalid):
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "发送设置无效:请检查服务器、发件地址、收件人与时间"})
case errors.Is(err, qawemail.ErrUnavailable):
writeJSON(w, http.StatusServiceUnavailable, map[string]string{"error": "周报邮件暂不可用,请稍后重试;未标记为已发送"})
default:
qaOpsError(w, dobotaiops.ErrUnavailable)
}
}
func qaWeeklyMailSettings(w http.ResponseWriter, r *http.Request, c Config) {
if !authorizeQAOps(w, r) {
return
}
store, ok := c.QAWeeklyMail.(weeklyMailStore)
if !ok {
weeklyMailError(w, qawemail.ErrUnavailable)
return
}
switch r.Method {
case http.MethodGet:
settings, err := store.ReadSettings(r.Context())
if err != nil {
weeklyMailError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": settings})
case http.MethodPost:
if !authorizeQAIntent(w, r, "qa-weekly-mail") {
return
}
if identity, ok := sessionFrom(r.Context()); !ok || identity.Role != "admin" {
writeJSON(w, http.StatusForbidden, map[string]string{"error": "仅管理员可修改邮件发送设置"})
return
}
var input qawemail.SettingsInput
if decodeQualityJSON(w, r, &input) != nil {
weeklyMailError(w, qawemail.ErrInvalid)
return
}
identity, _ := sessionFrom(r.Context())
actor := identity.Username
settings, err := store.SaveSettings(r.Context(), actor, input)
if err != nil {
weeklyMailError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": settings})
default:
w.Header().Set("Allow", "GET, POST")
writeJSON(w, http.StatusMethodNotAllowed, map[string]string{"error": "不支持的方法"})
}
}
func qaWeeklyMailConfirm(w http.ResponseWriter, r *http.Request, c Config) {
if !authorizeQAOps(w, r) {
return
}
if r.Method != http.MethodGet && !authorizeQAIntent(w, r, "qa-weekly-mail") {
return
}
store, ok := c.QAWeeklyMail.(weeklyMailStore)
if !ok {
weeklyMailError(w, qawemail.ErrUnavailable)
return
}
week := r.PathValue("week")
switch r.Method {
case http.MethodGet:
confirmation, err := store.ReadConfirmation(r.Context(), week)
if err != nil {
weeklyMailError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": map[string]any{"confirmation": confirmation}})
case http.MethodPost:
identity, _ := sessionFrom(r.Context())
actor := identity.Username
confirmation, err := store.Confirm(r.Context(), week, actor)
if err != nil {
weeklyMailError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": map[string]any{"confirmation": confirmation}})
case http.MethodDelete:
if err := store.Unconfirm(r.Context(), week); err != nil {
weeklyMailError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": map[string]any{"confirmation": nil}})
default:
w.Header().Set("Allow", "GET, POST, DELETE")
writeJSON(w, http.StatusMethodNotAllowed, map[string]string{"error": "不支持的方法"})
}
}
func qaWeeklyMailSends(w http.ResponseWriter, r *http.Request, c Config) {
if !authorizeQAOps(w, r) {
return
}
store, ok := c.QAWeeklyMail.(weeklyMailStore)
if !ok {
weeklyMailError(w, qawemail.ErrUnavailable)
return
}
sends, err := store.Sends(r.Context(), r.URL.Query().Get("week"))
if err != nil {
weeklyMailError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": map[string]any{"sends": sends}})
}
func qaWeeklyMailTest(w http.ResponseWriter, r *http.Request, c Config) {
if !authorizeQAOps(w, r) || !authorizeQAIntent(w, r, "qa-weekly-mail") {
return
}
identity, ok := sessionFrom(r.Context())
if !ok || identity.Role != "admin" {
writeJSON(w, http.StatusForbidden, map[string]string{"error": "仅管理员可发送测试邮件"})
return
}
store, found := c.QAWeeklyMail.(weeklyMailStore)
if !found {
weeklyMailError(w, qawemail.ErrUnavailable)
return
}
var request struct {
Week string `json:"week"`
}
if decodeQualityJSON(w, r, &request) != nil {
weeklyMailError(w, qawemail.ErrInvalid)
return
}
messageID, err := store.TestSend(r.Context(), request.Week)
if err != nil {
if errors.Is(err, qawemail.ErrInvalid) {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "请先保存该周周报正文,并确认已配置服务器、发件人、收件人与授权码"})
return
}
reason := err.Error()
if len(reason) > 300 {
reason = reason[:300]
}
writeJSON(w, http.StatusBadGateway, map[string]string{"error": "测试发送失败:" + reason})
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": map[string]any{"sent": true, "week": request.Week, "message_id": messageID}})
}
func qaWeeklyMailImage(w http.ResponseWriter, r *http.Request, c Config) {
if !authorizeQAOps(w, r) || !authorizeQAIntent(w, r, "qa-weekly-mail") {
return
}
identity, ok := sessionFrom(r.Context())
if !ok || identity.Role != "admin" {
writeJSON(w, http.StatusForbidden, map[string]string{"error": "仅管理员可上传周报附图"})
return
}
store, found := c.QAWeeklyMail.(weeklyMailStore)
if !found {
weeklyMailError(w, qawemail.ErrUnavailable)
return
}
var request struct {
PNGBase64 string `json:"png_base64"`
}
// The chart is megabytes of base64, far above the tiny quality-edit limit.
if decodeGovernanceJSON(w, r, &request, 12<<20) != nil {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "看板图片数据无效或过大(上限 8MB)"})
return
}
png, err := base64.StdEncoding.DecodeString(request.PNGBase64)
if err != nil || len(png) < 8 || len(png) > 8<<20 {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "图片无效或超过 8MB"})
return
}
if err := store.SaveDashboardImage(r.Context(), r.PathValue("week"), png); err != nil {
if errors.Is(err, qawemail.ErrInvalid) {
writeJSON(w, http.StatusBadRequest, map[string]string{"error": "请先确认本周周报,再附上统计看板图片"})
return
}
weeklyMailError(w, err)
return
}
writeJSON(w, http.StatusOK, map[string]any{"data": map[string]any{"saved": true, "bytes": len(png)}})
}