From 600e9a2dc2464d0013f40375d71ab3937ce4e401 Mon Sep 17 00:00:00 2001 From: hermes Date: Mon, 26 Oct 2026 15:31:46 +0800 Subject: [PATCH] =?UTF-8?q?feat(qa):=20=E5=91=A8=E6=8A=A5=E9=82=AE?= =?UTF-8?q?=E4=BB=B6=E6=94=AF=E6=8C=81=E7=AB=8B=E5=8D=B3=E5=8F=91=E9=80=81?= =?UTF-8?q?=E6=B5=8B=E8=AF=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 管理员可在周报页先发一封测试邮件验证邮箱配置;测试不写入发送记录、不改变确认状态,也不会把该周标记为已发送。 --- api/openapi.yaml | 1 + internal/httpapi/qa_weekly_mail.go | 38 ++++++++++++++++++++++++++++++ internal/httpapi/server.go | 1 + internal/qawemail/store.go | 32 +++++++++++++++++++++++++ web/src/QAWeeklyMail.tsx | 27 ++++++++++++++++++--- web/src/qaWeeklyMail.ts | 10 ++++++++ 6 files changed, 106 insertions(+), 3 deletions(-) diff --git a/api/openapi.yaml b/api/openapi.yaml index b2039c7..5faf4e1 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -51,6 +51,7 @@ "/api/v1/qa-ops/master/weekly-mail/settings": {"get":{"operationId":"getQAWeeklyMailSettings","tags":["QA operations"],"summary":"读取周报自动发送设置:SMTP地址/端口/账号/发件人/收件人/发送星期与小时/是否启用;永不返回授权码,仅返回是否已保存","responses":{"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"},"200":{"$ref":"#/components/responses/Envelope"},"401":{"description":"需要登录"},"503":{"description":"邮件设置存储不可用"}}},"post":{"operationId":"saveQAWeeklyMailSettings","tags":["QA operations"],"summary":"管理员保存周报自动发送设置;授权码加密存储、留空表示保持不变、清除需显式标记;启用时必须已有服务器、发件人与至少一个合法收件人;基线版本不符返回409","parameters":[{"name":"X-Governance-Action","in":"header","required":true,"schema":{"const":"qa-weekly-mail"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["base_revision"],"properties":{"base_revision":{"type":"integer","minimum":0},"host":{"type":"string","maxLength":200},"port":{"type":"integer","minimum":1,"maximum":65535},"username":{"type":"string","maxLength":200},"password":{"type":"string","maxLength":400},"clear_password":{"type":"boolean"},"from":{"type":"string","maxLength":320},"recipients":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":320}},"weekday":{"type":"integer","minimum":1,"maximum":7},"hour":{"type":"integer","minimum":0,"maximum":23},"enabled":{"type":"boolean"}}}}}},"responses":{"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"},"200":{"$ref":"#/components/responses/Envelope"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"需要登录"},"403":{"description":"仅管理员可修改发送设置"},"409":{"description":"发送设置已被其他管理员修改"},"503":{"description":"邮件设置存储不可用,未标记为已发送"}}}}, "/api/v1/qa-ops/master/weekly-mail/confirmations/{week}": {"get":{"operationId":"getQAWeeklyMailConfirmation","tags":["QA operations"],"summary":"读取该周是否已确认自动发送;current=false表示确认后正文已被修改,需要重新确认","parameters":[{"name":"week","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{4}-W[0-9]{2}$"}}],"responses":{"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"},"200":{"$ref":"#/components/responses/Envelope"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"需要登录"},"403":{"description":"仅管理员可修改发送设置"},"409":{"description":"发送设置已被其他管理员修改"},"503":{"description":"邮件设置存储不可用,未标记为已发送"}}},"post":{"operationId":"confirmQAWeeklyMail","tags":["QA operations"],"summary":"确认本周周报可自动发送,绑定当前草稿版本与正文哈希;后续改动使确认失效,不发送改动后的正文","parameters":[{"name":"week","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{4}-W[0-9]{2}$"}},{"name":"X-Governance-Action","in":"header","required":true,"schema":{"const":"qa-weekly-mail"}}],"responses":{"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"},"200":{"$ref":"#/components/responses/Envelope"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"需要登录"},"403":{"description":"仅管理员可修改发送设置"},"409":{"description":"发送设置已被其他管理员修改"},"503":{"description":"邮件设置存储不可用,未标记为已发送"}}},"delete":{"operationId":"unconfirmQAWeeklyMail","tags":["QA operations"],"summary":"取消该周的自动发送确认","parameters":[{"name":"week","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{4}-W[0-9]{2}$"}},{"name":"X-Governance-Action","in":"header","required":true,"schema":{"const":"qa-weekly-mail"}}],"responses":{"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"},"200":{"$ref":"#/components/responses/Envelope"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"需要登录"},"403":{"description":"仅管理员可修改发送设置"},"409":{"description":"发送设置已被其他管理员修改"},"503":{"description":"邮件设置存储不可用,未标记为已发送"}}}}, "/api/v1/qa-ops/master/weekly-mail/sends": {"get":{"operationId":"listQAWeeklyMailSends","tags":["QA operations"],"summary":"读取周报邮件发送记录:周次、草稿版本、发送中/已发送/失败及错误摘要,不返回正文或收件人","parameters":[{"name":"week","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{4}-W[0-9]{2}$"}}],"responses":{"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"},"200":{"$ref":"#/components/responses/Envelope"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"需要登录"},"403":{"description":"仅管理员可修改发送设置"},"409":{"description":"发送设置已被其他管理员修改"},"503":{"description":"邮件设置存储不可用,未标记为已发送"}}}}, + "/api/v1/qa-ops/master/weekly-mail/test": {"post":{"operationId":"sendQAWeeklyMailTest","tags":["QA operations"],"summary":"管理员用当前已保存的邮件设置立即发送一封测试邮件,正文取该周已保存草稿;不写入发送记录、不改变确认状态、不把该周标记为已发送","parameters":[{"name":"X-Governance-Action","in":"header","required":true,"schema":{"const":"qa-weekly-mail"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["week"],"properties":{"week":{"type":"string","pattern":"^[0-9]{4}-W[0-9]{2}$"}}}}}},"responses":{"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalError"},"200":{"$ref":"#/components/responses/Envelope"},"401":{"description":"需要登录"},"403":{"description":"仅管理员可测试发送"},"502":{"description":"SMTP 拒绝或不可达,返回脱敏原因"},"503":{"description":"邮件设置存储不可用"}}}}, "/api/v1/qa-ops/departments/statistics": { "post": { "operationId": "qaDepartmentStatistics", diff --git a/internal/httpapi/qa_weekly_mail.go b/internal/httpapi/qa_weekly_mail.go index 934e38d..544f9e9 100644 --- a/internal/httpapi/qa_weekly_mail.go +++ b/internal/httpapi/qa_weekly_mail.go @@ -16,6 +16,7 @@ type weeklyMailStore interface { 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) SendDue(context.Context, time.Time) (qawemail.DueResult, error) } @@ -134,3 +135,40 @@ func qaWeeklyMailSends(w http.ResponseWriter, r *http.Request, c Config) { } 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}}) +} diff --git a/internal/httpapi/server.go b/internal/httpapi/server.go index c9e5700..7512ec7 100644 --- a/internal/httpapi/server.go +++ b/internal/httpapi/server.go @@ -210,6 +210,7 @@ func NewHandler(config Config) (http.Handler, error) { mux.HandleFunc("POST /api/v1/qa-ops/master/weekly-mail/confirmations/{week}", func(w http.ResponseWriter, r *http.Request) { qaWeeklyMailConfirm(w, r, config) }) mux.HandleFunc("DELETE /api/v1/qa-ops/master/weekly-mail/confirmations/{week}", func(w http.ResponseWriter, r *http.Request) { qaWeeklyMailConfirm(w, r, config) }) mux.HandleFunc("GET /api/v1/qa-ops/master/weekly-mail/sends", func(w http.ResponseWriter, r *http.Request) { qaWeeklyMailSends(w, r, config) }) + mux.HandleFunc("POST /api/v1/qa-ops/master/weekly-mail/test", func(w http.ResponseWriter, r *http.Request) { qaWeeklyMailTest(w, r, config) }) mux.HandleFunc("GET /api/v1/qa-ops/master/field-options", func(w http.ResponseWriter, r *http.Request) { qaMasterFieldOptions(w, r, config) }) mux.HandleFunc("POST /api/v1/qa-ops/master/records/{id}/fields", func(w http.ResponseWriter, r *http.Request) { qaMasterFieldPatch(w, r, config) }) mux.HandleFunc("GET /api/v1/qa-ops/master/records", func(w http.ResponseWriter, r *http.Request) { withQAMaster(w, r, config, listQAOpsRecords) }) diff --git a/internal/qawemail/store.go b/internal/qawemail/store.go index b250a7a..8f6a3dd 100644 --- a/internal/qawemail/store.go +++ b/internal/qawemail/store.go @@ -473,6 +473,38 @@ func (s *Store) SendDue(ctx context.Context, now time.Time) (DueResult, error) { return DueResult{State: "nothing_confirmed", Reason: "没有已确认且已结束的周报"}, 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) + return s.mailer.Send(ctx, SMTPConfig{Host: settings.Host, Port: settings.Port, Username: settings.Username, Password: password}, + Message{To: settings.Recipients, From: settings.From, Subject: fmt.Sprintf("知识库周报 %s(测试发送)", week), HTML: html, Text: text}) +} + func (s *Store) send(ctx context.Context, settings Settings, week string, revision int64, markdown string, now time.Time) (DueResult, error) { password, err := s.password(ctx, settings.Revision) if err != nil { diff --git a/web/src/QAWeeklyMail.tsx b/web/src/QAWeeklyMail.tsx index ad4856d..06e1789 100644 --- a/web/src/QAWeeklyMail.tsx +++ b/web/src/QAWeeklyMail.tsx @@ -6,6 +6,7 @@ import { fetchWeeklyMailSends, fetchWeeklyMailSettings, saveWeeklyMailSettings, + sendWeeklyMailTest, weeklyMailWeekdayLabels, } from './qaWeeklyMail' import type { WeeklyMailConfirmation, WeeklyMailSend, WeeklyMailSettings } from './qaWeeklyMail' @@ -23,6 +24,7 @@ export function QAWeeklyMail({ week, busy }: { week: string; busy: boolean }) { const [notice, setNotice] = useState('') const [working, setWorking] = useState(false) const [editing, setEditing] = useState(false) + const [testing, setTesting] = useState(false) const reload = useCallback(async () => { setError('') @@ -61,6 +63,20 @@ export function QAWeeklyMail({ week, busy }: { week: string; busy: boolean }) { } } + const testSend = async () => { + if (testing) return + setTesting(true) + setError('') + setNotice('') + try { + const id = await sendWeeklyMailTest(week) + setNotice(`测试邮件已发出(${id});成功后不影响正式发送记录`) + } catch (reason) { + setError(reason instanceof Error ? reason.message : '测试发送失败') + } finally { + setTesting(false) + } + } const stale = confirmation !== null && !confirmation.current return (
@@ -84,9 +100,14 @@ export function QAWeeklyMail({ week, busy }: { week: string; busy: boolean }) { )} {admin ? ( - + <> + + + ) : null} diff --git a/web/src/qaWeeklyMail.ts b/web/src/qaWeeklyMail.ts index 94653a7..314cf17 100644 --- a/web/src/qaWeeklyMail.ts +++ b/web/src/qaWeeklyMail.ts @@ -152,3 +152,13 @@ export async function fetchWeeklyMailSends(week: string): Promise { + const payload = (await getPayload(endpoint('test'), undefined, { + method: 'POST', + headers, + body: JSON.stringify({ week }), + })) as { message_id: string } + if (typeof payload.message_id !== 'string' || !payload.message_id) bad() + return payload.message_id +}