magic-agent 2.4.3 → 2.6.3

package/internal/requirements/shots_test.go

@@ -0,0 +1,387 @@
+package requirements
+
+// shots_test.go - 「页面完成情况」截图的落盘、文档追加与往返保持。
+//
+// 重点盯三件事：
+//   · 追加截图**不动**用户手改过的内容（只加两行，不整篇重渲染）；
+//   · 归纳重写文档时**保住**截图段（否则用户攒的完成情况会被抹掉）；
+//   · 落盘路径是**正斜杠**（Windows 的反斜杠在 markdown 里是转义符）。
+
+import (
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// fakePNG 造一个最小 PNG（只需要文件头合法，core 不解码像素）。
+func fakePNG() []byte {
+	return append(append([]byte{}, pngMagic...), 0x00, 0x01, 0x02, 0x03)
+}
+
+// 造一篇已存在的功能点文档，返回工作区 id 与文档路径。
+func seedFeature(t *testing.T, module, name string) (string, string) {
+	t.Helper()
+	root := t.TempDir()
+	t.Setenv(EnvDir, filepath.Join(root, "requirements"))
+	id := "ws-abc1234567"
+	dir := filepath.Join(featuresDir(id), module)
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	file := filepath.Join(dir, SlugifyFeature(name)+".md")
+	doc := RenderDoc(name, Doc{
+		Desc:        "一个功能点",
+		Points:      []string{"要点一"},
+		Conclusions: []string{"结论一"},
+		Final:       "**目标**：一个功能点",
+	})
+	if err := os.WriteFile(file, []byte(doc), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return id, file
+}
+
+func TestAttachShotAppendsToDoc(t *testing.T) {
+	id, file := seedFeature(t, "任务列表", "需求页")
+	res, err := AttachShot(id, "任务列表", "需求页", "改成双列布局", fakePNG())
+	if err != nil {
+		t.Fatalf("追加截图失败: %v", err)
+	}
+	if !res.OK || res.Shots != 1 {
+		t.Fatalf("结果不对: %+v", res)
+	}
+	if !strings.Contains(res.Path, "/") || strings.Contains(res.Path, `\`) {
+		t.Errorf("截图路径应是正斜杠: %q", res.Path)
+	}
+	if _, err := os.Stat(filepath.FromSlash(res.Path)); err != nil {
+		t.Errorf("截图文件不在盘上: %v", err)
+	}
+	raw, err := os.ReadFile(file)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(raw)
+	if !strings.Contains(text, "## 页面完成情况") {
+		t.Fatalf("文档里没有新增段落:\n%s", text)
+	}
+	if !strings.Contains(text, "改成双列布局") {
+		t.Errorf("文档里没有标注说明:\n%s", text)
+	}
+	// 原有内容必须还在。
+	if !strings.Contains(text, "## 需求点") || !strings.Contains(text, "要点一") {
+		t.Errorf("原有内容被弄丢了:\n%s", text)
+	}
+	// 段的位置：在来源对话之前。
+	if strings.Index(text, "## 页面完成情况") > strings.Index(text, "## 来源对话") {
+		t.Errorf("新段应在来源对话之前:\n%s", text)
+	}
+}
+
+func TestAttachShotKeepsUserEdits(t *testing.T) {
+	// 用户在两次归纳之间手改了文档（加了一个自定义段 + 改了措辞）。
+	// 追加截图**不能**把那些内容抹掉 —— 这就是「文本级插入」的意义。
+	id, file := seedFeature(t, "任务列表", "需求页")
+	raw, _ := os.ReadFile(file)
+	edited := string(raw) + "\n## 我自己加的备注\n这段是用户手写的\n"
+	if err := os.WriteFile(file, []byte(edited), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := AttachShot(id, "任务列表", "需求页", "标注", fakePNG()); err != nil {
+		t.Fatalf("追加截图失败: %v", err)
+	}
+	after, _ := os.ReadFile(file)
+	if !strings.Contains(string(after), "## 我自己加的备注") {
+		t.Errorf("用户手写的内容被抹掉了:\n%s", after)
+	}
+	if !strings.Contains(string(after), "这段是用户手写的") {
+		t.Errorf("用户手写的内容被抹掉了:\n%s", after)
+	}
+}
+
+func TestAttachShotTwiceKeepsBoth(t *testing.T) {
+	id, file := seedFeature(t, "任务列表", "需求页")
+	if _, err := AttachShot(id, "任务列表", "需求页", "第一张", fakePNG()); err != nil {
+		t.Fatal(err)
+	}
+	res, err := AttachShot(id, "任务列表", "需求页", "第二张", fakePNG())
+	if err != nil {
+		t.Fatalf("第二次追加失败: %v", err)
+	}
+	if res.Shots != 2 {
+		t.Errorf("应有 2 张截图，实际 %d", res.Shots)
+	}
+	raw, _ := os.ReadFile(file)
+	text := string(raw)
+	if !strings.Contains(text, "第一张") || !strings.Contains(text, "第二张") {
+		t.Errorf("两张截图都该在文档里:\n%s", text)
+	}
+	// 占位符不该留着。
+	if strings.Contains(text, "（暂无）\n## 来源对话") {
+		t.Errorf("有图后不该还留着占位符:\n%s", text)
+	}
+}
+
+func TestAttachShotErrors(t *testing.T) {
+	id, _ := seedFeature(t, "任务列表", "需求页")
+	// 找不到功能点。
+	if _, err := AttachShot(id, "任务列表", "不存在的功能", "x", fakePNG()); err == nil {
+		t.Error("找不到功能点应当报错")
+	}
+	// 模块对不上。
+	if _, err := AttachShot(id, "别的模块", "需求页", "x", fakePNG()); err == nil {
+		t.Error("模块对不上应当报错")
+	}
+	// 不是 PNG。
+	if _, err := AttachShot(id, "任务列表", "需求页", "x", []byte("not a png")); err == nil {
+		t.Error("非 PNG 应当报错")
+	}
+	// 空内容。
+	if _, err := AttachShot(id, "任务列表", "需求页", "x", nil); err == nil {
+		t.Error("空内容应当报错")
+	}
+	// 超限。
+	if _, err := AttachShot(id, "任务列表", "需求页", "x", make([]byte, MaxShotBytes+1)); err == nil {
+		t.Error("超限应当报错")
+	}
+	// 功能点名空。
+	if _, err := AttachShot(id, "任务列表", "  ", "x", fakePNG()); err == nil {
+		t.Error("功能点名空应当报错")
+	}
+}
+
+func TestDocRoundTripKeepsShots(t *testing.T) {
+	// 归纳重写文档时（ParseDoc → RenderDoc）要保住截图与页面地址。
+	d := Doc{
+		Desc:        "描述",
+		Points:      []string{"要点"},
+		Conclusions: []string{"结论"},
+		PageURL:     "https://example.com/page",
+		Shots: []Shot{
+			{Path: "C:/Users/x/a b (v2)/1.png", Caption: "改完了", At: 1793000000000},
+		},
+	}
+	out := RenderDoc("需求页", d)
+	back := ParseDoc(out)
+	if back.PageURL != d.PageURL {
+		t.Errorf("页面地址丢了: %q", back.PageURL)
+	}
+	if len(back.Shots) != 1 {
+		t.Fatalf("截图丢了: %+v", back.Shots)
+	}
+	if back.Shots[0].Path != d.Shots[0].Path {
+		t.Errorf("截图路径不对: %q", back.Shots[0].Path)
+	}
+	if back.Shots[0].Caption != "改完了" {
+		t.Errorf("标注说明不对: %q", back.Shots[0].Caption)
+	}
+	if back.Shots[0].At != d.Shots[0].At {
+		t.Errorf("截图时间不对: %d", back.Shots[0].At)
+	}
+}
+
+func TestRenderDocWritesShotsSection(t *testing.T) {
+	out := RenderDoc("需求页", Doc{Points: []string{"要点"}})
+	if !strings.Contains(out, "## 页面完成情况") {
+		t.Errorf("空文档也该有这一段（占位）:\n%s", out)
+	}
+	if !strings.Contains(out, "（暂无）") {
+		t.Errorf("空段该写占位:\n%s", out)
+	}
+}
+
+func TestValidPageURL(t *testing.T) {
+	good := []string{"https://example.com", "http://a.b/c?d=1", "HTTPS://X.COM"}
+	bad := []string{"", "无", "待定", "见上文", "C:/Users/x", "ftp://x", "javascript:alert(1)"}
+	for _, u := range good {
+		if !validPageURL(u) {
+			t.Errorf("应认: %q", u)
+		}
+	}
+	for _, u := range bad {
+		if validPageURL(u) {
+			t.Errorf("不该认: %q", u)
+		}
+	}
+}
+
+func TestConsolidateKeepsShots(t *testing.T) {
+	// 假模型：返回一个已有功能点的增量（只有 desc）。
+	// 断言：重写文档后截图段仍在、页面地址仍在。
+	root := t.TempDir()
+	t.Setenv(EnvDir, filepath.Join(root, "requirements"))
+	id := "ws-abc1234567"
+	dir := filepath.Join(featuresDir(id), "任务列表")
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	file := filepath.Join(dir, "需求页.md")
+	doc := RenderDoc("需求页", Doc{
+		Desc:        "旧描述",
+		Points:      []string{"要点"},
+		PageURL:     "https://example.com/p",
+		Shots:       []Shot{{Path: "C:/x/1.png", Caption: "已改", At: 1793000000000}},
+		Conclusions: []string{},
+	})
+	if err := os.WriteFile(file, []byte(doc), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	merger := newDocMerger(id)
+	w := writeFeatureItem(id, featureOut{
+		Module: "任务列表",
+		Name:   "需求页",
+		Desc:   "新描述",
+	}, &writeCtx{merger: merger, kind: "归纳"})
+	if !w.ok {
+		t.Fatal("写入失败")
+	}
+	raw, _ := os.ReadFile(file)
+	back := ParseDoc(string(raw))
+	if len(back.Shots) != 1 {
+		t.Fatalf("归纳把截图抹掉了:\n%s", raw)
+	}
+	if back.Shots[0].Caption != "已改" {
+		t.Errorf("标注说明丢了: %+v", back.Shots)
+	}
+	if back.PageURL != "https://example.com/p" {
+		t.Errorf("页面地址丢了: %q", back.PageURL)
+	}
+	if back.Desc != "新描述" {
+		t.Errorf("描述没更新: %q", back.Desc)
+	}
+}
+
+func TestConsolidateKeepsPageURLWhenModelEmpty(t *testing.T) {
+	// 本轮模型没给 page_url（空串）→ 保留旧的，不能被空值抹掉。
+	root := t.TempDir()
+	t.Setenv(EnvDir, filepath.Join(root, "requirements"))
+	id := "ws-abc1234567"
+	dir := filepath.Join(featuresDir(id), "任务列表")
+	_ = os.MkdirAll(dir, 0o700)
+	file := filepath.Join(dir, "需求页.md")
+	doc := RenderDoc("需求页", Doc{Desc: "旧", PageURL: "https://example.com/keep"})
+	_ = os.WriteFile(file, []byte(doc), 0o600)
+	merger := newDocMerger(id)
+	w := writeFeatureItem(id, featureOut{Module: "任务列表", Name: "需求页", Desc: "新"}, &writeCtx{merger: merger, kind: "归纳"})
+	if !w.ok {
+		t.Fatal("写入失败")
+	}
+	raw, _ := os.ReadFile(file)
+	if back := ParseDoc(string(raw)); back.PageURL != "https://example.com/keep" {
+		t.Errorf("空 page_url 不该抹掉旧地址: %q", back.PageURL)
+	}
+}
+
+func TestConsolidateRejectsBadPageURL(t *testing.T) {
+	// 模型给了个非法地址（不是 http/https）→ 保留旧的，不写进去。
+	root := t.TempDir()
+	t.Setenv(EnvDir, filepath.Join(root, "requirements"))
+	id := "ws-abc1234567"
+	dir := filepath.Join(featuresDir(id), "任务列表")
+	_ = os.MkdirAll(dir, 0o700)
+	file := filepath.Join(dir, "需求页.md")
+	doc := RenderDoc("需求页", Doc{Desc: "旧", PageURL: "https://example.com/keep"})
+	_ = os.WriteFile(file, []byte(doc), 0o600)
+	merger := newDocMerger(id)
+	w := writeFeatureItem(id, featureOut{Module: "任务列表", Name: "需求页", Desc: "新", PageURL: "javascript:alert(1)"},
+		&writeCtx{merger: merger, kind: "归纳"})
+	if !w.ok {
+		t.Fatal("写入失败")
+	}
+	raw, _ := os.ReadFile(file)
+	if back := ParseDoc(string(raw)); back.PageURL != "https://example.com/keep" {
+		t.Errorf("非法地址不该写进去: %q", back.PageURL)
+	}
+}
+
+func TestAttachShotDedupesSamePath(t *testing.T) {
+	// 同一张图被写进文档两遍 → 段里只该有一行（留最后那条）。
+	// 触发方式：把同一行手工塞进文档，再追加一张**同名**的图。
+	id, file := seedFeature(t, "任务列表", "需求页")
+	if _, err := AttachShot(id, "任务列表", "需求页", "第一张", fakePNG()); err != nil {
+		t.Fatalf("追加截图失败: %v", err)
+	}
+	raw, _ := os.ReadFile(file)
+	// 把已有那行原样复制一遍（模拟重放/手工编辑造成的重复）。
+	lines := strings.Split(string(raw), "\n")
+	dup := ""
+	for _, l := range lines {
+		if strings.Contains(l, "第一张") {
+			dup = l
+			break
+		}
+	}
+	if dup == "" {
+		t.Fatalf("文档里没找到截图行:\n%s", raw)
+	}
+	edited := strings.Replace(string(raw), dup, dup+"\n"+dup, 1)
+	if err := os.WriteFile(file, []byte(edited), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	// 再追加一张新图 —— insertShot 应顺手把重复行去掉。
+	res, err := AttachShot(id, "任务列表", "需求页", "第二张", fakePNG())
+	if err != nil {
+		t.Fatalf("追加截图失败: %v", err)
+	}
+	if res.Shots != 2 {
+		t.Errorf("去重后应有 2 张（两张不同路径），实际 %d", res.Shots)
+	}
+	after, _ := os.ReadFile(file)
+	if n := strings.Count(string(after), "第一张"); n != 1 {
+		t.Errorf("重复的截图行没去掉，出现 %d 次:\n%s", n, after)
+	}
+}
+
+func TestTrimShotsDedupesAndTrims(t *testing.T) {
+	shots := []Shot{
+		{Path: "C:/x/1.png", Caption: "a"},
+		{Path: "C:/x/2.png", Caption: "b"},
+		{Path: "C:/x/1.png", Caption: "a2"},
+	}
+	out := TrimShots(shots)
+	if len(out) != 2 {
+		t.Fatalf("去重后应有 2 条，实际 %d: %+v", len(out), out)
+	}
+	// 留最后一条的**内容**，但位置不动（首次出现的位置）。
+	if out[0].Path != "C:/x/1.png" || out[0].Caption != "a2" {
+		t.Errorf("该留最后一条的内容（位置不动），实际 %+v", out[0])
+	}
+	if out[1].Path != "C:/x/2.png" {
+		t.Errorf("第二条不对: %+v", out[1])
+	}
+	// 超上限时丢最旧的。
+	many := make([]Shot, 0, MaxShots+5)
+	for i := 0; i < MaxShots+5; i++ {
+		many = append(many, Shot{Path: "C:/x/" + strconv.Itoa(i) + ".png"})
+	}
+	got := TrimShots(many)
+	if len(got) != MaxShots {
+		t.Fatalf("该裁到 %d 条，实际 %d", MaxShots, len(got))
+	}
+	if got[0].Path != "C:/x/5.png" {
+		t.Errorf("该丢最旧的 5 条，实际第一条 %q", got[0].Path)
+	}
+}
+
+func TestRenderDocShotLinesAreCounted(t *testing.T) {
+	// RenderDoc 写的是列表项 `- ![…](…)`；这行必须能被 countShots 数出来，
+	// 也必须能被 ParseDoc 解析回来 —— 否则归纳重渲染后截图就「消失」了。
+	out := RenderDoc("需求页", Doc{
+		PageURL: "https://example.com/p",
+		Shots:   []Shot{{Path: "C:/x/1.png", Caption: "改完了", At: 1793000000000}},
+	})
+	if !strings.Contains(out, "- ![改完了](C:/x/1.png)") {
+		t.Errorf("RenderDoc 的截图形状不对:\n%s", out)
+	}
+	if n := countShots(strings.Split(out, "\n")); n != 1 {
+		t.Errorf("countShots 数不出 RenderDoc 写的截图（得 %d）:\n%s", n, out)
+	}
+	back := ParseDoc(out)
+	if len(back.Shots) != 1 {
+		t.Fatalf("ParseDoc 解析不回来: %+v", back.Shots)
+	}
+	if back.Shots[0].Caption != "改完了" || back.Shots[0].Path != "C:/x/1.png" {
+		t.Errorf("解析结果不对: %+v", back.Shots[0])
+	}
+}