feat(qa): 周报邮件支持立即发送测试
build / build (push) Successful in 1m17s

管理员可在周报页先发一封测试邮件验证邮箱配置;测试不写入发送记录、不改变确认状态,也不会把该周标记为已发送。
This commit is contained in:
hermes
2026-10-26 15:31:46 +08:00
parent eed83039ab
commit 600e9a2dc2
6 changed files with 106 additions and 3 deletions
+1
View File
@@ -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",
+38
View File
@@ -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}})
}
+1
View File
@@ -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) })
+32
View File
@@ -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 {
+24 -3
View File
@@ -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 (
<section className="qa-weekly-mail" aria-label="周报自动发送">
@@ -84,9 +100,14 @@ export function QAWeeklyMail({ week, busy }: { week: string; busy: boolean }) {
</button>
)}
{admin ? (
<button type="button" disabled={working} onClick={() => setEditing(!editing)}>
{editing ? '收起发送设置' : '发送设置'}
</button>
<>
<button type="button" disabled={working || testing} onClick={() => void testSend()}>
{testing ? '正在发送测试…' : '发送测试邮件'}
</button>
<button type="button" disabled={working} onClick={() => setEditing(!editing)}>
{editing ? '收起发送设置' : '发送设置'}
</button>
</>
) : null}
</div>
</header>
+10
View File
@@ -152,3 +152,13 @@ export async function fetchWeeklyMailSends(week: string): Promise<WeeklyMailSend
}
export const weeklyMailWeekdayLabels = ['周一', '周二', '周三', '周四', '周五', '周六', '周日']
export async function sendWeeklyMailTest(week: string): Promise<string> {
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
}