crearte-monorepo/docs/specs/2026-10-03-p15a-approve-phases-design.md

P15-A 设计：拆分 Approve 169 行七阶段（crearte-server）

• 日期：2026-10-03
• 仓：crearte-server（Go module 根在 src/）
• 分支：chore/p15a-approve-phases（AGENTS.md:18 只允许 {feat|fix|docs|chore}/）
• base：fe810dd（P14 merge，master）
• 维度：代码优雅（USER.md 六维度循环）
• 前置：P14 已交付（ContentService 拆分 + 七条架构守卫）。本批不得改动 architecture_test.go，除非某条断言因新 helper 变红（见 §5-T1 的 mutation (g)）。

---

§0 基线（已实测，2026-10-03 12:50）

四门（dockerized golang:1.24-alpine，AGENTS.md 硬红线；host Go 1.18 不可用）：gofmt -l . 空 · go vet ./... exit 0 · go build ./... exit 0 · go test ./... -count=1 11 包 ok（internal/api ~11.0s 含真库集成、internal/service ~3.7s）。

目标函数：internal/service/moderation.go:47-215 = 169 行（wc -l 口径，P14 spec §5 已钉该口径）。

service/ 包内非测试文件的函数长度分布（78 个函数，实测普查）：

阈值	超过的函数数	清单
>100 行	1	*ModerationService.Approve(169)
>80 行	2	+ *AccountService.deleteAccountLocked(83)
>70 行	4	+ *SubmissionService.UpdateSubmission(76)、ValidateWorkFields(75)
>60 行	7	+ *ImportService.ImportDir(70)、*CleanupService.Run(70)、*SubmissionService.checkSubmissionRules(66)

→ Approve 是包内唯一 >100 行的函数，且比次大者（83）大一倍。这就是本批的选型依据：不是"文件太长"，是单个函数承担了七件事。

行数口径：一律 wc -l。不要用 len(text.split('\n'))——文件以换行结尾时后者多算一个空段（P14 F5：控制者与任务级审查者为此报出 83/299 与 82/298 两套数字）。

---

§1 取证（决定设计，全部实测）

1.1 七阶段边界（moderation.go 真实行号；P14 挂账里 base 树的 606–772 已作废）

阶段	行	内容	返回的错误	是否碰 tx
① 加载 + 状态校验 + 解析	48–62	Submissions().GetByID → ErrNotFound 映射 ErrContentNotFound；sub.Status != Pending → ErrSubmissionConflict；ParseSubmissionEnvelope(sub.Payload)；p := env.Work	ErrContentNotFound / ErrSubmissionConflict / envelope 解析错	否
② owner 查取	64–70	仅 Kind == NewWork 时 s.users.GetByID(sub.SubmitterID)	service: resolve submitter: %w	否
③ 上传解析	72–85	BundleUploadID/CoverUploadID 各 Uploads().GetByID，并校验 up.ConsumedBy == sub.ID	ErrUploadUnavailable	否
④ 乐观预检 switch	87–100	NewWork：Works().GetByID 已存在 → ErrWorkIDTaken；NewVersion：Versions().Get 已存在 → ErrVersionExists；其它 kind 无 case	ErrWorkIDTaken / ErrVersionExists / service: approve precheck: %w	否（用 s.store）
⑤ 对象 Copy	102–123	finalBundleKey = "bundles/"+sub.WorkID+"/"+p.Version+".bin"；finalCoverKey = "covers/"+sub.WorkID+"/"+coverUpload.SHA256+path.Ext(...)；各 s.objects.Copy	ErrUploadUnavailable（storage.ErrObjectNotFound）/ `service: copy bundle	cover: %w`
⑥ WithTx 事务	125–206	GetByIDForUpdate 锁行 → 重校 Status == Pending → 悲观重检 switch（三分支）→ 建 Work / Version / Touch / UpdateMetadata → MarkReviewed	见 §1.2	是（tx repository.ContentRepository）
⑦ pending 清理 + slog	207–214	事务错误映射（repository.ErrConflict → ErrSubmissionConflict）；pendingKeys(bundleUpload, coverUpload) 逐个 s.objects.Delete（只 slog.Error 不返回，best-effort）；slog.Info("approve", …)；return nil	ErrSubmissionConflict / 裸 err	否

WithTx 签名（internal/repository/content.go:38）：WithTx(ctx context.Context, fn func(ContentRepository) error) error。

1.2 🔴 阶段④与阶段⑥的 switch 不同形，禁止合并（本批最重要的约束）

两者都 switch sub.Kind、都查 Works().GetByID / Versions().Get、都可能返回 ErrWorkIDTaken/ErrVersionExists，故看上去可以抽成一个"重复性检查" helper 共用。实测比对后确认不可合并，四处实质差异：

差异	阶段④（87–100）	阶段⑥（136–186）
kind 覆盖	只有 NewWork / NewVersion 两个 case	三个 case：NewWork / NewVersion / MetadataChange
NewVersion 的额外校验	只查 Versions().Get 是否已存在	还查 work.Runtime != model.RuntimeVirtual || bundleUpload == nil → ErrSubmissionConflict；且 Versions().Create 后还调 tx.Works().Touch
NewWork 的动作	只查冲突，不建实体	PayloadToWork(p) + 设 OwnerID/CoverKey + tx.Works().Create（ErrConflict → ErrWorkIDTaken）+ 条件建 Version
错误文案	非 ErrNotFound 的错误包成 service: approve precheck: %w	裸返 err，无包装

语义差异（不可合并的根本原因）：④是乐观快失败——无锁、在任何对象 Copy 之前，失败时副作用为零；⑥是悲观重检——持 SELECT … FOR UPDATE 行锁、在对象已 Copy 之后，失败时须靠阶段⑦清理 pending 对象。合并成一个 helper 会让"检查"与"写入"的边界模糊，且改变错误文案（service: approve precheck: … 会消失或蔓延到事务内），属行为变更。

→ 裁定：④与⑥各自独立拆 helper，不共享代码。 表面重复是有意的双层校验（TOCTOU 防护：预检减少无谓 Copy，重检保证正确性），不是可消除的冗余。spec 里写明这条，防实现者"顺手 DRY"。

1.3 helper 形态：未导出方法与包级函数都不触架构守卫（实测，推翻 P15 账本 §8.1 的说法）

账本原写"新 helper 应是包级 func，因为方法会改动 expectedLineFields/断言 2 的方法集并触发守卫红"。这句是错的，已用两轮 mutation 实测推翻：

探针	追加到 moderation.go 的声明	go build	七断言
A	func (s *ModerationService) approvePrecheckLocked(ctx context.Context) error { return nil }（未导出方法）	exit 0	7 PASS / 0 FAIL
B	func approvePrecheck(store repository.ContentStore, sub model.Submission) error { return nil }（包级函数）	exit 0	7 PASS / 0 FAIL

机制：断言 2 TestLineExportedMethods 用 m.IsExported() 过滤，断言 4 遍历的 reflect.Type.NumMethod() 本身只暴露导出方法 → 未导出方法根本不在两条断言的视野内。断言 6 只看字段，不看方法。

→ 形态选择依据是"是否需要接收者字段"，不是守卫约束：

• 需要 s.store / s.objects / s.users 的 → 未导出方法（体例：account.go:78 的 func (s *AccountService) deleteAccountLocked(ctx, user) (DeletionReport, error)，注释「共享内核，调用方已确认账号存在且未注销」，两处调用）
• 只需 tx + 已备好的数据 → 包级函数（体例：moderation.go:283 versionFromUpload(workID, version, objectKey, up)、:290 pendingKeys(uploads ...*model.Upload)）

⚠️ 不得给 ModerationService 加字段（断言 6 会红：expectedLineFields["ModerationService"] = {objects, store, users}）；不得在 ContentService 上加任何方法（断言 5 源码扫描会红）。

1.4 ContentStore 内嵌 ContentRepository（决定事务 helper 的签名）

// internal/repository/content.go:28-39
type ContentRepository interface {
	Works() WorkRepository
	Versions() WorkVersionRepository
	Submissions() SubmissionRepository
	Uploads() UploadRepository
	Reactions() ReactionRepository
}
type ContentStore interface {
	ContentRepository
	WithTx(ctx context.Context, fn func(ContentRepository) error) error
}

→ ContentStore 是 ContentRepository 的超集。故收 repository.ContentRepository 的 helper 既能接 s.store（阶段④）也能接 tx（阶段⑥）。但本批刻意不用这个能力去合并④⑥（见 §1.2）；它只用于让事务体 helper 的签名收 tx。

1.5 ParseSubmissionEnvelope 的返回类型（决定 plan 结构体字段类型）

// internal/service/content.go:54-60
type SubmissionEnvelope struct {
	Work           WorkPayload `json:"work"`
	BundleUploadID string      `json:"bundle_upload_id,omitempty"`
	CoverUploadID  string      `json:"cover_upload_id,omitempty"`
}
func ParseSubmissionEnvelope(raw []byte) (SubmissionEnvelope, error)   // 值返回，非指针

Approve 内 p := env.Work（WorkPayload 值）。plan 结构体应持有 p WorkPayload 值而非 env 指针——与现有代码逐字一致，避免引入 nil 判定分支（那会是行为变更）。

1.6 既有测试覆盖：充分，不需要先补 characterization 测试

Approve 有 5 个直接调用点（internal/service/content_test.go:91,205,268,284,359）与 13 个相关测试函数：

测试	覆盖的阶段/分支
content_test.go:18 TestApproveConcurrentOnlyOneWins	⑥ 的行锁 + 重校状态（并发只有一个赢）
content_test.go:126 TestApproveSameWorkIDConcurrent	④/⑥ 的 ErrWorkIDTaken（断言文本：loser error = %v, want ErrWorkIDTaken or ErrSubmissionConflict）
content_test.go:237 TestApproveMetadataChangeFeaturesSemantics	⑥ 的 MetadataChange 分支 + Features 三态语义（用 meta-absent 与 ,"features":{} 两个 payload 精确区分 nil=保留 / 空 map=清空）
content_test.go:293 TestApproveOptionalFieldsRoundTrip	①② 的 envelope 解析与字段往返
content_hosted_test.go:76 TestMetadataChangeRuntimeImmutable	⑥ 的 Runtime 不可变约束
namespace_test.go:132 TestNewVersionMetadataChangeOwnership	⑥ 的 OwnerID 归属
api/admin_test.go:83,131,149,197,231（5 个）	HTTP 层：发布、Forbidden+DoubleApprove、同 slug 异命名空间、NewVersion、MetadataChange
api/integration_test.go:27 TestFullPublishChainOnPostgres、api/hosted_postgres_test.go:28 TestHostedPublishChainOnPostgres	⑤⑥ 的完整发布链（真库）

→ 既有测试就是本批的行为守卫（与 P14 D-G 同构）。验收硬指标：既有 *_test.go 修改数 = 0。若实现者发现必须改测试，停下来报告而不是改（P14 §4 末条）。

1.7 调用面：Approve 只有一个非测试调用点

internal/handler/admin.go:62：h.svc.Approve(c.Request.Context(), CurrentUser(c).ID, c.Param("id"), body.Note)（经 moderationPort 窄接口）→ 新 helper 无须导出，且 Approve 的签名与错误语义必须逐字不变（moderationPort 由 P14 断言 2 钉住 6 个方法名，签名变更会打破 serve.go 的接口满足性 → 编译红）。

---

§2 设计决策

#	决策点	裁定	依据
D-A	拆分粒度	按七阶段拆 5 个 helper（①②③ 合为一个"输入装载"、④ 一个、⑤ 一个、⑥ 一个（内部再拆 3 个 kind 分支）、⑦ 一个），不逐行拆	§1.1 的阶段边界是语义边界（副作用发生点），不是任意切点。①②③ 都只读、都产出 plan 的字段、失败时零副作用 → 合为一个 helper 不损失可读性；④⑤⑥⑦ 各自有独立副作用（预检/Copy/事务/清理）→ 必须分开
D-B	plan 结构体	新增包级私有 struct approvePlan，字段：sub model.Submission、p WorkPayload、owner model.User、bundleUpload *model.Upload、coverUpload *model.Upload、finalBundleKey string、finalCoverKey string	七阶段之间传递的就是这七样东西（实测自函数体）。用 struct 而非 7 个返回值：Go 的多返回值超过 4 个即难读，且 ⑤ 要往 plan 里写 finalBundleKey/finalCoverKey 供 ⑥⑦ 用
D-C	helper 形态	①②③④⑤⑦ → 未导出方法（需 s.store/s.users/s.objects）；⑥ 事务体 → 包级函数 applyApprovalInTx(ctx, tx repository.ContentRepository, plan approvePlan, adminID, note string) error；⑥ 内三个 kind 分支 → 包级函数	§1.3 实测两种形态都不触守卫；选择依据是"是否需要接收者字段"。事务体不碰 s.*（只用 tx）→ 包级函数更纯，且签名自证"事务内不得访问 store 外的东西"。体例分别同 deleteAccountLocked 与 versionFromUpload
D-D	④与⑥不合并	各自独立 helper，不共享代码	§1.2：四处实质差异 + 乐观/悲观语义不同 + 错误文案不同。表面重复是有意的 TOCTOU 双层校验
D-E	事务边界与 Copy 顺序	一行不动：⑤ 的两次 s.objects.Copy 必须在 ⑥ WithTx 之外（故 ⑦ 需要清理）；⑥ 的全部写入必须在 WithTx 之内；MarkReviewed 必须是事务内最后一个调用	改变顺序即行为变更：Copy 进事务会让长耗时 I/O 持锁；MarkReviewed 提前会让"实体建成但状态未改"的中间态可被并发观察到
D-F	Features 三态语义	if p.Features == nil { work.Features = existing.Features } 连注释一起搬进 MetadataChange helper，不得"简化"	该注释原文：「旧提交（features 采集上线前创建）的 payload 无 features 键：保留现值，避免审批通过时静默清空已发布作品的运行权限；显式 {} 才是清空」。三态（nil=保留 / 空 map=清空 / 有值=覆盖）由 content_test.go:237 精确钉住，简化即红
D-G	零行为变更	纯结构重构：方法体逐字迁移，只改接收者/参数传递与缩进。Approve 的签名、返回的每个错误值与错误文案、slog 的两条日志（键名与顺序）全部逐字不变	P14 同款契约。验收：既有测试零修改 + 四门绿 + 字节级方法体比对
D-H	结构指标钉什么	钉「最大单函数行数」，不钉文件行数	helper 仍在 moderation.go（298 行）内，拆完文件可能不降反升。用文件行数当指标会逼实现者把 helper 塞进新文件，那是无意义的文件增殖
D-I	派发形态	一个实现者子代理做完 T1→T3（同动 crearte-server 单一工作树与 git index）	AGENTS.md / sdd-parallel-dispatch §1「一仓一写者」；P12/P13/P14 同款。P15-B 在 crearte 仓，与本批可并行（两仓各自单写者）

§2.1 被否方案

方案	否决理由
A：把④⑥的 switch 抽成共享 helper（DRY）	§1.2 实测四处差异 + 乐观/悲观语义不同。合并会改变错误文案（service: approve precheck: %w 消失或蔓延）与 NewVersion 分支的校验集 → 行为变更，违反 D-G
B：用 repository.ContentRepository 参数统一④⑥（机械上可行）	§1.4 证明 ContentStore 内嵌 ContentRepository，故技术上能让一个 helper 同时接 s.store 与 tx。但"能"不等于"该"：它把①的乐观预检与⑥的持锁重检伪装成同一件事，读者无法从签名看出锁语义差别 → 比 A 更隐蔽的行为语义损失
C：把七阶段拆到七个新文件	文件增殖。moderation.go 298 行本身不超标（P14 目标 <300），拆文件不解决"单函数太长"这个真问题，且 D-H 已判定不用文件行数当指标
D：先补 characterization 测试再重构	§1.6 实测既有 13 个测试函数已覆盖全部七阶段与三态语义（含并发、真库发布链）。补测试是额外成本而非额外保障，且会违反"既有 *_test.go 修改数 = 0"这个更硬的验收判据
E：本批一并拆 deleteAccountLocked(83) / UpdateSubmission(76)	D-F「一批一个关注点」（P14 同款）。三个函数分属 account/submission/moderation 三条线，混在一批会让"行为不变"的验收判断面翻三倍。已挂账
F：把 Approve 改成状态机/策略模式	过度设计。七个阶段是线性的（无分支跳转、无回退），switch sub.Kind 已经是策略分派。引入状态机会把 169 行变成更多的行 + 一个新抽象层，且改变错误的产生位置（行为变更）

---

§3 实现要求

3.1 目标形态（骨架，签名为示意，实现者须按 §1.1 的真实类型逐字对齐）

func (s *ModerationService) Approve(ctx context.Context, adminID, submissionID, note string) error {
	plan, err := s.loadApprovePlan(ctx, submissionID)          // ①②③
	if err != nil {
		return err
	}
	if err := s.precheckApprove(ctx, plan); err != nil {        // ④（乐观、无锁、Copy 之前）
		return err
	}
	if err := s.copyApprovalObjects(ctx, plan); err != nil {    // ⑤（写 plan.finalBundleKey/finalCoverKey）
		return err
	}
	err = s.store.WithTx(ctx, func(tx repository.ContentRepository) error {
		return applyApprovalInTx(ctx, tx, plan, adminID, note)  // ⑥
	})
	if err != nil {
		if errors.Is(err, repository.ErrConflict) {
			return ErrSubmissionConflict
		}
		return err
	}
	s.cleanupApprovalUploads(ctx, plan)                         // ⑦（best-effort，只 slog.Error）
	slog.Info("approve", "submission", submissionID, "work", plan.sub.WorkID, "kind", plan.sub.Kind, "admin", adminID)
	return nil
}

⚠️ 注意 copyApprovalObjects 必须能写回 plan：plan 是值类型，故该方法签名须为 (ctx context.Context, plan *approvePlan) error（收指针），或返回新的 plan。选前者——与 ⑤ 原地修改 finalBundleKey/finalCoverKey 的现有语义一致，且避免"返回新 plan 但调用方忘了接"的静默丢值。

3.2 逐阶段要求

①②③ loadApprovePlan（未导出方法）：

• 逐字搬 48–85 行。返回 (approvePlan, error)。
• 三处错误映射逐字保留：errors.Is(err, repository.ErrNotFound) → ErrContentNotFound；sub.Status != model.SubmissionStatusPending → ErrSubmissionConflict；fmt.Errorf("service: load submission: %w", err)；fmt.Errorf("service: resolve submitter: %w", err)；两处 ErrUploadUnavailable（含 up.ConsumedBy != sub.ID 判定）。
• ② 的 if sub.Kind == model.SubmissionKindNewWork 条件必须保留（其它 kind 不查 owner，plan.owner 为零值；⑥ 的 NewWork 分支才用 owner.ID）。
• ③ 的 bundleUpload = &up 取地址语义必须保留（up 是循环内局部变量，取其地址是本函数刻意的写法；改成存值会让 plan.bundleUpload != nil 判定失效）。

④ precheckApprove（未导出方法）：

• 逐字搬 87–100 行。保持用 s.store（不是 tx）。
• 错误文案 fmt.Errorf("service: approve precheck: %w", err) 逐字保留（两处）。
• 不得增加 MetadataChange case（④ 现在没有，加了会改变 MetadataChange 提交的失败时机）。

⑤ copyApprovalObjects（未导出方法，收 *approvePlan）：

• 逐字搬 102–123 行。key 拼接公式逐字保留（"bundles/"+sub.WorkID+"/"+p.Version+".bin"、"covers/"+sub.WorkID+"/"+coverUpload.SHA256+ext，ext := path.Ext(coverUpload.ObjectKey)）。
• if bundleUpload != nil / if coverUpload != nil 的条件 Copy 语义保留（无上传时 finalXxxKey 保持 ""，⑥ 的 MetadataChange 分支靠 if finalCoverKey != "" 判定是否覆盖）。
• storage.ErrObjectNotFound → ErrUploadUnavailable 的映射逐字保留；service: copy bundle|cover: %w 两条文案逐字保留。

⑥ applyApprovalInTx（包级函数）：

• 搬 126–205 行（WithTx 闭包体）。签名收 (ctx, tx repository.ContentRepository, plan approvePlan, adminID, note string) error。
• GetByIDForUpdate 锁行 + 重校 Status == Pending 必须在最前（125–134），且 errors.Is(err, repository.ErrNotFound) → ErrSubmissionConflict（注意与①不同：① 映射 ErrContentNotFound，⑥ 映射 ErrSubmissionConflict——这个差异是刻意的，事务内消失意味着并发删除，语义是冲突而非未找到）。
• 三个 kind 分支各自拆包级函数（createWorkInTx / createVersionInTx / applyMetadataChangeInTx），或保留为一个 switch——由实现者按可读性定，但 switch 的分支顺序与 MarkReviewed 在末尾的位置不得变。
• MetadataChange 分支的 Features 三态连注释一起搬（D-F）。
• 事务内错误裸返，不加 service: approve precheck 之类包装（§1.2）。

⑦ cleanupApprovalUploads（未导出方法）：

• 搬 212–213 行。for _, key := range pendingKeys(plan.bundleUpload, plan.coverUpload) + s.objects.Delete + if err != nil && !errors.Is(err, storage.ErrObjectNotFound) { slog.Error("approve: pending delete failed", "key", key, "error", err) } 逐字保留。
• 不得返回 error（best-effort 语义：清理失败不能让已成功的审批变失败）。
• ⚠️ slog.Info("approve", …) 与 return nil 留在 Approve 本体，不进 helper——helper 名是 cleanup，把成功日志塞进去会让职责不清。

3.3 不得触碰

• architecture_test.go（P14 的七条守卫）——除非 mutation (g) 证明某条因新 helper 变红，那时停下来报告，不要自行改守卫。
• moderationPort（handler/admin.go）与 serve.go。
• versionFromUpload / pendingKeys 的签名（可调用，不可改）。
• 任何 *_test.go。
• docs/、go.mod/go.sum（AGENTS.md 红线：实现者不得碰）。

---

§4 边界

项	在范围内	不在范围内
函数	Approve 及其拆出的 helper	Reject/Unpublish/Republish/UpdateWorkFeatures/ListQueue（同文件其它方法）、deleteAccountLocked(83)、UpdateSubmission(76)
文件	internal/service/moderation.go	其它 service 文件（除非编译需要，须报告）
行为	零变更（D-G）	任何错误文案/日志键名/错误产生时机的调整
测试	无（既有测试即守卫）	新增测试、修改既有测试
守卫	无	改 architecture_test.go

挂账（本批发现但刻意不做）：deleteAccountLocked(83 行，account 线)、UpdateSubmission(76)、ValidateWorkFields(75)、ImportDir(70)、CleanupService.Run(70)、checkSubmissionRules(66) —— 六个 >60 行函数，各自独立成批。

---

§5 测试计划

T1 —— 结构守卫（RED 先行）：扩展或新增函数长度断言

P14 的七条断言钉的是类型形态，没有一条钉函数长度。本批的验收核心是"Approve 从 169 行降到 <60"，若没有机械守卫，下一个贡献者可以把它加回去而无人拦截。

新增 internal/service/function_length_test.go（新文件，不改 architecture_test.go）：

1. TestNoOversizedFunction：解析 internal/service/ 下所有非测试 .go，统计每个 func 的行数（^func 起，括号深度归零止），断言没有任何函数 >100 行。
   • 阈值 100 的依据（实测，非拍脑袋）：§0 普查显示当前包内 >100 行的函数只有 Approve(169) 一个，次大是 83 → 阈值 100 在修前恰好红一条（Approve）、修后全绿，且给次大者（83）留 17 行余量不至于误伤。
   • ⚠️ 不得用 60 当阈值：那会让 deleteAccountLocked(83)、UpdateSubmission(76)、ValidateWorkFields(75)、ImportDir(70)、Run(70)、checkSubmissionRules(66) 六个本批范围外的既有函数立刻报红，把"重构 Approve"变成"重构整个包"（违反 D-F/E）。
2. TestApproveIsSmall：断言 Approve 本身 <60 行（本批的直接目标；169 → <60）。
3. TestApproveHelpersExist：断言 §3.1 骨架里的 helper 名存在（loadApprovePlan/precheckApprove/copyApprovalObjects/applyApprovalInTx/cleanupApprovalUploads）——防实现者只把代码挪进一个匿名闭包了事。
   • ⚠️ 这条断言的实现方式必须是源码文本匹配（os.ReadDir + 正则），不能用 reflect：未导出函数在 reflect 里不可见（§1.3 同一机制）。

RED 相位要求：T1 在 T2 之前提交时，go test ./internal/service/ -run 'TestNoOversizedFunction|TestApproveIsSmall|TestApproveHelpersExist' 必须红，且红的原因是断言失败而非编译错误（Approve 169 行 > 100、helper 名不存在）。这与 P14 T1 的 RED 形态不同（P14 是 undefined: CatalogService 编译红）——本批 T1 引用的都是既有类型，故必须是断言红。实现者须把 RED 输出逐字存证到 .superpowers/sdd-p15a/impl-evidence/t1-red.txt。

mutation 自查（实现者必做并附输出，每条测"预期红 + 其余绿 + 非编译红 + 恢复证明"）：

• (a) 把 Approve 的某阶段内联回去（helper 存在但 Approve 不调它，改为原地展开）→ TestApproveIsSmall 必须红
• (b) 给某个 helper 塞代码使 Approve 仍 <60 但某函数 >100（例如把⑥的三个 kind 分支全塞进 applyApprovalInTx 而不拆）→ TestNoOversizedFunction 必须红

  ⚠️ (b) 的可行性须先实测：若⑥整体（126–205 = 80 行）搬进 applyApprovalInTx 而不再拆，该函数是 80 行 < 100 → mutation (b) 在这个具体形态下不会红。这是阈值 100 的已知盲区，不是守卫失效：它钉的是"不再有 169 行的巨函数"，不是"每个 helper 都短"。实现者须在报告里写明这一点，不得声称 (b) 覆盖了所有塞代码形态。若要在 (b) 上取得真红，须构造 >100 行的 helper（例如把 ④⑥ 两个 switch 都塞进一个 helper）。

• (c) 删掉一个 helper（把其内容合并进 Approve）→ TestApproveHelpersExist 必须红
• (d) 把 helper 名改成别的（如 loadApproveInputs）→ TestApproveHelpersExist 必须红（这条是 (c) 的对照：证明断言钉的是名字集合而非"存在任意 5 个函数"）
• (e) 把 TestNoOversizedFunction 的扫描范围改成一个空目录 → 必须红（防"扫 0 文件也报 0 违规"的假信心，P13 审查者 M5 的同族教训；断言内须含"至少扫到 N 个 .go 文件"的前提检查）
• (f) 把阈值从 100 改成 1000 → 必须红（同 (e)，防阈值被放宽；断言须自证阈值字面量）
• (g) 给 ModerationService 加字段（如 clock func() time.Time）→ P14 的断言 6 TestLineFields 必须红（跨批回归检查：证明本批新增文件没有削弱 P14 守卫）
• (h) 在 ContentService 上加方法 → P14 的断言 5 必须红（同 (g)，且须同时测有名与匿名接收者两种形态——P14 FR-1 的教训：只测有名会漏掉 func (*ContentService) M()）

每次 mutation 后只回滚触及的文件（git checkout -- <file>，绝不用 git checkout -- .——P14 控制者第 24 次自伤：全量回滚会抹掉未提交的守卫编辑，导致后续各轮全在测没有修复的树），并核 git diff 空 + 守卫文件 func Test 计数不变。

T2 —— 执行拆分（T1 由红转绿）

按 §3 执行。完成后 go test ./... 必须 11 包全绿且既有测试文件零修改。

T3 —— 字节级方法体保真证明（加做项，P14 同款）

写脚本对 base 树（fe810dd）的 Approve 函数体与新树的 Approve + 5 个 helper 做语句级比对：base 的每一行（归一化缩进与接收者前缀后）必须在新树中出现，且顺序保持（阶段①→⑦ 的相对顺序不得变）。产出三张清单：verbatim（逐字一致）、changed（刻意变更，须逐条给理由）、missing（必须为 0）。

⚠️ 脚本的已知坑（P14 两位审查者都栽过）：

• 提取声明块时不能"剥行注释后数括号"——字符串字面量里的 //（如 strings.HasPrefix(k, "https://")）会被当注释起点吃掉右括号。须用状态机分词器跟踪 " / ` / ' / // / /* */，把字面量与注释内容替换为等长空格后再数括号（P14 任务级审查者 F6 的修法）。
• 单行 var X = errors.New(...) 须有提前终止分支，否则会把后续声明并入同一块（P14 F6 的残留局限）。
• 若工具给出意外值（如某方法报 CHANGED），先怀疑自己的模式，不要据此指控实现者（P14 F6：第一版工具误报 CoverURL 为 CHANGED，若照它写报告会产生一条完全虚假的 critical finding）。

四门验收

cd crearte-server && docker run --rm -v "$PWD/src:/src" -w /src \
  -v crearte_gomod:/go/pkg/mod -e GOCACHE=/gocache -v crearte_gocache:/gocache \
  -e GOPROXY=https://goproxy.cn,direct -e GOSUMDB=sum.golang.google.cn \
  golang:1.24-alpine sh -c 'gofmt -l . ; go vet ./... ; go build ./... ; go test ./... -count=1'

⚠️ -count=1 强制实跑（禁缓存）。⚠️ 落盘证据用 setsid nohup 脱离 + 宿主侧重定向（容器只挂 /src 写不了 .superpowers/；exec session 一断容器就被杀——P14 实现者与任务级审查者都踩过）。⚠️ grep -c 输出 0 时 exit 1，放 && 链里会静默中断后续步骤（含 git commit）。⚠️ pkill -f <pattern> 会匹配到自己的命令行（P14 控制者把自己 SIGKILL）→ 用 [p]attern。

结构指标（交付时须报实测数字，wc -l 口径）

指标	基线	目标
Approve 行数	169	< 60
service/ 包内 >100 行的函数数	1	0
service/ 包内最大单函数行数	169	< 100（实测次大者 83，故目标应落在 83–100 之间）
moderation.go 行数	298	不作指标（D-H：helper 同文件，可能不降反升；报了即可，不设目标）
既有 *_test.go 修改文件数	—	0
architecture_test.go 修改行数	—	0
Approve 的签名	(ctx context.Context, adminID, submissionID, note string) error	逐字不变
字节级比对 missing	—	0

---

§6 记账

• crearte-server/docs/CHANGELOG.md 新增 ## [0.19.0] - 2026-10-03（插 ## [0.18.0] 前）。格式：同条目英文行紧跟中文行、无空行；不同条目空一行；小节标题双语（### Changed / 变更、### Tests / 测试、### Context / 背景）。
• wrapper docs/CHANGELOG.md 新增 ## [0.3.8] - 2026-10-03（插 ## [0.3.7] 前），小节 ### Done / 完成。
• docs/ROADMAP.md：第三波表新增 P15-A 行（P14 行之后）+ 文档索引表新增一行。哈希引 merge commit（P12/P13/P14 惯例），记账 commit 另列。
• 挂账新增：六个 >60 行函数（deleteAccountLocked 83 / UpdateSubmission 76 / ValidateWorkFields 75 / ImportDir 70 / CleanupService.Run 70 / checkSubmissionRules 66）· TestNoOversizedFunction 阈值 100 的已知盲区（80 行的 helper 不会被拦，见 §5 mutation (b) 的警告）。
• go.mod / 任何 version 文件不 bump。
• 纪律：显式 git add <file>，禁 git add -A。wrapper 的 IDENTITY.md/SOUL.md/USER.md 三个未跟踪文件非本批产物，绝不 stage。

---

§7 风险与缓解

风险	缓解
实现者"顺手 DRY"合并④⑥的 switch	§1.2 已写明四处实质差异 + 语义差别（乐观/悲观）+ 错误文案差别；D-D 明令禁止；T3 字节级比对会暴露合并（base 的 service: approve precheck: %w 文案会消失或移位）；既有 TestApproveSameWorkIDConcurrent 断言的错误集合会变
plan 值传递导致 ⑤ 的 finalXxxKey 静默丢失	§3.1 已点名：copyApprovalObjects 必须收 *approvePlan。TestApproveOptionalFieldsRoundTrip 与 api 层发布链测试会抓到（key 为空 → 作品无 bundle）
② 的 owner 零值被误当成"未加载"	§3.2 已写明 if sub.Kind == NewWork 条件必须保留；namespace_test.go:132 TestNewVersionMetadataChangeOwnership 会抓到 OwnerID 错误
③ 的 bundleUpload = &up 取地址语义被改成存值	§3.2 已点名；改了会让 plan.bundleUpload != nil 恒真或恒假 → ⑤⑥⑦ 全链路错，api 层发布链测试必红
⑦ 的 slog.Info 被搬进 cleanup helper	§3.2 已明令留在 Approve 本体（职责清晰）。日志键名/顺序变更由 D-G 约束；若实现者搬了，代码审查阶段抓
新守卫 TestNoOversizedFunction 写成恒真/恒假	mutation (e)(f) 双向验证（改扫描范围→红、改阈值→红）+ P13/P14 教训：max(a,b) ≥ k 是恒真高发区、NumMethod()==0 是恒假形态。本批新增镜像形态须防：断言里若含"至少扫到 N 个文件"的前提检查，N 写太小会让前提恒成立而主体断言失去意义
未导出 helper 让 reflect 类断言失效	§1.3 已实测：未导出方法不在断言 2/4 视野内 → 这是特性不是缺陷（重构私有实现不该触守卫）。但 T1.3 的 TestApproveHelpersExist 因此必须用源码文本匹配而非 reflect
本批削弱 P14 守卫	mutation (g)(h) 跨批回归检查（加字段→断言 6 红；加组合根方法→断言 5 红，且须测有名与匿名两种接收者形态，P14 FR-1 教训）

---

§8 实现纪律（P11–P14 累计教训，逐条来自真实事故）

1. 不推断，只实测。 任何"应该是/大概/按惯例"都要跑一条命令确认。P14 控制者在勘查期与裁定期共犯 28 次断言/grep/锚点/区间/路径/正则错误。
2. 断言或 grep 返回意外值时，先怀疑自己的模式，别先宣布缺陷。 P14 任务级审查者的第一版比对脚本误报 CoverURL 为 CHANGED（字符串字面量里的 // 被当注释起点）；控制者五次因这条纪律避免了指控子代理的假缺陷。
3. 修守卫必须两方向都验：对合法值不误红 + mutation 下不误绿。P13 控制者只验前者，交付了数学恒真的断言（max(填充侧,边框侧) ≥ 3，互补两侧下界 = √cr(paper,ink) = 4.0621 > 3，50653 采样暴力验证）。
4. 全称声明需要全称范围的证据。 P14 控制者写"断言 5 是唯一能抓遮蔽的手段"被终审推翻（匿名接收者 func (*ContentService) M() 绕过）；写"两层覆盖完整"被推翻（孤儿私有方法）。写"唯一/全部/任何"之前先枚举形态（有名/匿名接收者、值/指针、导出/未导出）。
5. 恒假断言与恒真断言同样无价值，且恒假更容易因"看起来严格"而通过审查。 P14 控制者 spike 否决的 NumMethod()==0（嵌入 *T 使方法进值+指针两个方法集，合法树上已是 22）就是恒假形态。
6. 管道会吞掉真退出码。 go test ./... | tail -30; echo $? 取的是 tail 的退出码。P14 终审者踩过（full_exit=0 而实际套件 FAIL）。
7. || echo "(zero)" 这类兜底文本在 glob 失败时会伪装成"测量结果为零"。 P14 终审者 R0 轮整轮结论无证据支撑，自查后在真仓用绝对路径重跑；控制者的 bg-surface=0 同形态（cd 到仓根却写 app/...，真根是 src/app/...）。任何"零命中"结论都要先证明扫描范围非空。
8. 长时命令落盘证据用 setsid nohup 脱离 + 宿主侧重定向。 exec session 一断容器就被杀，P14 实现者的 t3-gates.txt 首跑只写 1/12 包。
9. restore() 只回滚 mutation 触及的文件，绝不用 git checkout -- .；每轮恢复后核验守卫编辑仍在（func Test 计数），否则 FATAL 终止——让脚本在被自毁时大声失败，而不是静默产出"未按预期"的假结论。
10. 测试被迫修改 = 设计失败的信号。 若必须改既有测试，停下来报告而不是改。本批的验收硬指标就是"既有 *_test.go 修改数 = 0"。