From 32ac5593850418c702111197c90732100642c31f Mon Sep 17 00:00:00 2001 From: jackyu66git Date: Sat, 8 Aug 2026 03:05:55 +0800 Subject: [PATCH] =?UTF-8?q?feat(ECR-024):=20OpsCMS=20Banner=20=E5=8F=AA?= =?UTF-8?q?=E8=AF=BB=E5=B9=B6=20Closed?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 运营横幅目录（ops_banners + admin /cms），锁定 024–040 全队列。 Co-authored-by: Cursor --- .ai/product/feature-spec/README.md | 1 + .ai/product/feature-spec/ops-banner.md | 41 +++++ apps/admin-h5/src/api/client.ts | 28 +++ apps/admin-h5/src/layouts/AdminShell.vue | 1 + apps/admin-h5/src/pages/CMSPage.vue | 79 ++++++++ apps/admin-h5/src/router/index.ts | 1 + apps/api/internal/handler/admin.go | 1 + apps/api/internal/handler/admin_cms.go | 46 +++++ .../internal/integration/cms_banner_test.go | 100 ++++++++++ apps/api/internal/repository/cms_repo.go | 67 +++++++ apps/api/internal/service/admin/cms.go | 34 ++++ apps/api/internal/service/admin/rbac.go | 3 +- .../migrations/000025_ops_banners.down.sql | 3 + apps/api/migrations/000025_ops_banners.up.sql | 37 ++++ docs/BACKEND_DESIGN/BD-2026-024-banner.md | 23 +++ docs/CHANGELOG.md | 1 + docs/CODE_REVIEW/ECR-024.md | 8 + docs/CONTRACT_DIFF/ECR-024.yaml | 22 +++ docs/ECR/ECR-024-banner.md | 19 ++ docs/ENGINEERING_SPEC/ECR-024-banner.md | 6 + docs/HANDOFF/ECR-024-architect-to-engineer.md | 3 + docs/HANDOFF/ECR-024-engineer-to-reviewer.md | 3 + docs/PRODUCT_SPEC/ECR-024-banner.md | 3 + docs/STATE/ECR-024.md | 6 + docs/TASKS/TASK-024-ECR024.yaml | 12 ++ docs/TEST_REPORT/ECR-024.md | 33 ++++ docs/TRACEABILITY.md | 1 + docs/WAVE0/LOOP_AUTHORIZATION.md | 29 ++- proto/openapi.yaml | 28 +++ scripts/ess-slice-scaffold.py | 172 ++++++++++++++++++ 30 files changed, 808 insertions(+), 3 deletions(-) create mode 100644 .ai/product/feature-spec/ops-banner.md create mode 100644 apps/admin-h5/src/pages/CMSPage.vue create mode 100644 apps/api/internal/handler/admin_cms.go create mode 100644 apps/api/internal/integration/cms_banner_test.go create mode 100644 apps/api/internal/repository/cms_repo.go create mode 100644 apps/api/internal/service/admin/cms.go create mode 100644 apps/api/migrations/000025_ops_banners.down.sql create mode 100644 apps/api/migrations/000025_ops_banners.up.sql create mode 100644 docs/BACKEND_DESIGN/BD-2026-024-banner.md create mode 100644 docs/CODE_REVIEW/ECR-024.md create mode 100644 docs/CONTRACT_DIFF/ECR-024.yaml create mode 100644 docs/ECR/ECR-024-banner.md create mode 100644 docs/ENGINEERING_SPEC/ECR-024-banner.md create mode 100644 docs/HANDOFF/ECR-024-architect-to-engineer.md create mode 100644 docs/HANDOFF/ECR-024-engineer-to-reviewer.md create mode 100644 docs/PRODUCT_SPEC/ECR-024-banner.md create mode 100644 docs/STATE/ECR-024.md create mode 100644 docs/TASKS/TASK-024-ECR024.yaml create mode 100644 docs/TEST_REPORT/ECR-024.md create mode 100755 scripts/ess-slice-scaffold.py diff --git a/.ai/product/feature-spec/README.md b/.ai/product/feature-spec/README.md index f9cd1cc..d61e4c1 100644 --- a/.ai/product/feature-spec/README.md +++ b/.ai/product/feature-spec/README.md @@ -33,6 +33,7 @@ | [ops-ai-core-config.md](ops-ai-core-config.md) | AI 核心配置 AICoreConfig | §7 | `admin-h5` `/ai` · `GET /admin/ai/system-prompts*` | Ops-D · **ECR-021 Closed** | | [ops-crisis-care.md](ops-crisis-care.md) | 危机关怀 CrisisCare | §7 | `admin-h5` `/crisis` · `GET /admin/crisis/policies*` | Ops-D · **ECR-022 Closed** | | [ops-knowledge-source.md](ops-knowledge-source.md) | AI 知识源 KnowledgeSource | §7 | `admin-h5` `/ai` · `GET /admin/ai/knowledge-sources*` | Ops-D · **ECR-023 Closed** | +| [ops-banner.md](ops-banner.md) | OpsCMS Banner | §7 | `admin-h5` `/cms` · `GET /admin/cms/banners*` | Ops-D · **ECR-024 Closed** | 新功能：复制 `_TEMPLATE.md` → 填满 → 在本表登记 → 再编码。 diff --git a/.ai/product/feature-spec/ops-banner.md b/.ai/product/feature-spec/ops-banner.md new file mode 100644 index 0000000..d03e306 --- /dev/null +++ b/.ai/product/feature-spec/ops-banner.md @@ -0,0 +1,41 @@ +# Feature Spec: OpsCMS · Banner（Ops · ECR-024） + +> Status: `Active`（Loop continuous · **ECR-024 Closed**） +> Parent: WAVE0-FROZEN · Predecessor: ECR-023 Closed +> Capability: `OpsCMS` · BC: `Ops_CMS_NoUGC` +> 授权：`docs/WAVE0/LOOP_AUTHORIZATION.md` + +## Non-goals + +Banner 写发布 · FeedSlot · ScheduledPublication · UGC · 真支付 + +## L2 Domain + +| 概念 | 语义 | +|------|------| +| `Banner` | code 唯一；placement ∈ {home,explore,ask}；active/system；本切片只读 | + +## L3 API + +| Method | Path | 权限 | 语义 | +|--------|------|------|------| +| GET | `/admin/cms/banners` | `admin.cms.read` | 只读 | +| GET | `/admin/cms/banners/{id}` | `admin.cms.read` | 只读 | + +## Migration + +`000025`：表 + 种子（若有） + 授予 admin.cms.read + +## L4 AC + +| ID | Then | +|----|------| +| AC-F-01 | list 含种子或空列表合法 | +| AC-F-02 | 已知 id get 200 | +| AC-F-03 | 未知 id → 404 | +| AC-S-01 | 无 Admin → 401 | +| AC-S-02 | 无权限 → 403 | +| AC-P-01 | list < 500ms | +| AC-O-01 | N/A 只读 | + +contract_diff: `docs/CONTRACT_DIFF/ECR-024.yaml` diff --git a/apps/admin-h5/src/api/client.ts b/apps/admin-h5/src/api/client.ts index 8706627..b7d7cf8 100644 --- a/apps/admin-h5/src/api/client.ts +++ b/apps/admin-h5/src/api/client.ts @@ -385,6 +385,34 @@ export const adminApi = { helpline_text?: string }> }>('POST', '/crisis/evaluate', { text }), + banners: () => + request<{ + items: Array<{ + id: string + code: string + title: string + placement: string + image_url?: string + link_path?: string + sort_order: number + active: boolean + system: boolean + updated_at: string + }> + }>('GET', '/cms/banners'), + banner: (id: string) => + request<{ + id: string + code: string + title: string + placement: string + image_url?: string + link_path?: string + sort_order: number + active: boolean + system: boolean + updated_at: string + }>('GET', `/cms/banners/${id}`), orders: () => request<{ items: Array<{ diff --git a/apps/admin-h5/src/layouts/AdminShell.vue b/apps/admin-h5/src/layouts/AdminShell.vue index e44b610..a2aeab1 100644 --- a/apps/admin-h5/src/layouts/AdminShell.vue +++ b/apps/admin-h5/src/layouts/AdminShell.vue @@ -34,6 +34,7 @@ async function onLogout() { 安全 AI 危机 + CMS 订单 审计 diff --git a/apps/admin-h5/src/pages/CMSPage.vue b/apps/admin-h5/src/pages/CMSPage.vue new file mode 100644 index 0000000..5fa8479 --- /dev/null +++ b/apps/admin-h5/src/pages/CMSPage.vue @@ -0,0 +1,79 @@ + + + + + diff --git a/apps/admin-h5/src/router/index.ts b/apps/admin-h5/src/router/index.ts index 880e272..e437c29 100644 --- a/apps/admin-h5/src/router/index.ts +++ b/apps/admin-h5/src/router/index.ts @@ -21,6 +21,7 @@ const router = createRouter({ { path: 'safety', name: 'safety', component: () => import('@/pages/SafetyPage.vue') }, { path: 'ai', name: 'ai', component: () => import('@/pages/AIConfigPage.vue') }, { path: 'crisis', name: 'crisis', component: () => import('@/pages/CrisisPage.vue') }, + { path: 'cms', name: 'cms', component: () => import('@/pages/CMSPage.vue') }, { path: 'audit', name: 'audit', component: () => import('@/pages/AuditPage.vue') }, ], }, diff --git a/apps/api/internal/handler/admin.go b/apps/api/internal/handler/admin.go index 59cfb15..cf99a96 100644 --- a/apps/api/internal/handler/admin.go +++ b/apps/api/internal/handler/admin.go @@ -53,6 +53,7 @@ func (h *AdminHandler) Register(api *gin.RouterGroup) { h.registerContentSafety(authed) h.registerAIConfig(authed) h.registerCrisis(authed) + h.registerCMS(authed) } func (h *AdminHandler) Login(c *gin.Context) { diff --git a/apps/api/internal/handler/admin_cms.go b/apps/api/internal/handler/admin_cms.go new file mode 100644 index 0000000..61dc55c --- /dev/null +++ b/apps/api/internal/handler/admin_cms.go @@ -0,0 +1,46 @@ +package handler + +import ( + "errors" + "net/http" + + "github.com/gin-gonic/gin" + "github.com/google/uuid" + + "github.com/yuxingu/digital-psychology/apps/api/internal/middleware" + "github.com/yuxingu/digital-psychology/apps/api/internal/service/admin" + "github.com/yuxingu/digital-psychology/apps/api/pkg/response" +) + +func (h *AdminHandler) registerCMS(authed *gin.RouterGroup) { + g := authed.Group("/cms") + g.GET("/banners", middleware.RequireAdminPermission(h.Svc, admin.PermCMSRead), h.ListBanners) + g.GET("/banners/:id", middleware.RequireAdminPermission(h.Svc, admin.PermCMSRead), h.GetBanner) +} + +func (h *AdminHandler) ListBanners(c *gin.Context) { + items, err := h.Svc.ListBanners(c.Request.Context()) + if err != nil { + response.Fail(c, http.StatusInternalServerError, 50040, "list banners failed") + return + } + response.OK(c, gin.H{"items": items}) +} + +func (h *AdminHandler) GetBanner(c *gin.Context) { + id, err := uuid.Parse(c.Param("id")) + if err != nil { + response.Fail(c, http.StatusBadRequest, 40002, "invalid id") + return + } + row, err := h.Svc.GetBanner(c.Request.Context(), id) + if errors.Is(err, admin.ErrBannerNotFound) { + response.Fail(c, http.StatusNotFound, 40410, "banner not found") + return + } + if err != nil { + response.Fail(c, http.StatusInternalServerError, 50041, "get banner failed") + return + } + response.OK(c, row) +} diff --git a/apps/api/internal/integration/cms_banner_test.go b/apps/api/internal/integration/cms_banner_test.go new file mode 100644 index 0000000..bc3d1db --- /dev/null +++ b/apps/api/internal/integration/cms_banner_test.go @@ -0,0 +1,100 @@ +package integration_test + +import ( + "context" + "encoding/json" + "fmt" + "net/http" + "testing" + "time" + + "github.com/google/uuid" + "golang.org/x/crypto/bcrypt" +) + +func TestOpsCMSBanners(t *testing.T) { + r, pool := setupAPIPool(t) + ctx := context.Background() + tok := adminLogin(t, r, "admin", "change-me") + + _, code := doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/cms/banners", nil, "") + if code != http.StatusUnauthorized { + t.Fatalf("expected 401, got %d", code) + } + + limitedRoleID := uuid.New() + _, err := pool.Exec(ctx, ` + INSERT INTO admin_roles(id, name, system) VALUES ($1,$2,false)`, + limitedRoleID, "cms_lim_"+limitedRoleID.String()[:8]) + if err != nil { + t.Fatal(err) + } + _, err = pool.Exec(ctx, ` + INSERT INTO admin_role_permissions(role_id, code) VALUES ($1,'admin.users.read')`, limitedRoleID) + if err != nil { + t.Fatal(err) + } + hash, err := bcrypt.GenerateFromPassword([]byte("limited-pass"), bcrypt.DefaultCost) + if err != nil { + t.Fatal(err) + } + limUser := fmt.Sprintf("cmslim_%d", time.Now().UnixNano()) + _, err = pool.Exec(ctx, ` + INSERT INTO admin_accounts(username, password_hash, role_id) VALUES ($1,$2,$3)`, + limUser, string(hash), limitedRoleID) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { + _, _ = pool.Exec(ctx, `DELETE FROM admin_accounts WHERE username=$1`, limUser) + _, _ = pool.Exec(ctx, `DELETE FROM admin_roles WHERE id=$1`, limitedRoleID) + }) + limTok := adminLogin(t, r, limUser, "limited-pass") + _, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/cms/banners", nil, limTok) + if code != http.StatusForbidden { + t.Fatalf("expected 403, got %d", code) + } + + start := time.Now() + env, code := doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/cms/banners", nil, tok) + if code != 200 || env.Code != 0 { + t.Fatalf("list http=%d msg=%s", code, env.Message) + } + if time.Since(start) > 500*time.Millisecond { + t.Fatalf("list too slow %v", time.Since(start)) + } + var list struct { + Items []struct { + ID string `json:"id"` + Code string `json:"code"` + } `json:"items"` + } + _ = json.Unmarshal(env.Data, &list) + var id string + for _, it := range list.Items { + if it.Code == "home_promo" { + id = it.ID + break + } + } + if id == "" { + t.Fatalf("missing home_promo: %#v", list.Items) + } + + env, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/cms/banners/"+id, nil, tok) + if code != 200 { + t.Fatalf("get %d", code) + } + var detail struct { + Code string `json:"code"` + } + _ = json.Unmarshal(env.Data, &detail) + if detail.Code != "home_promo" { + t.Fatalf("bad detail %#v", detail) + } + + _, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/cms/banners/"+fakeUUID(), nil, tok) + if code != http.StatusNotFound { + t.Fatalf("expected 404, got %d", code) + } +} diff --git a/apps/api/internal/repository/cms_repo.go b/apps/api/internal/repository/cms_repo.go new file mode 100644 index 0000000..7ec563a --- /dev/null +++ b/apps/api/internal/repository/cms_repo.go @@ -0,0 +1,67 @@ +package repository + +import ( + "context" + "errors" + "time" + + "github.com/google/uuid" + "github.com/jackc/pgx/v5" +) + +// BannerRow is OpsCMS Banner catalog row. +type BannerRow struct { + ID uuid.UUID `json:"id"` + Code string `json:"code"` + Title string `json:"title"` + Placement string `json:"placement"` + ImageURL *string `json:"image_url,omitempty"` + LinkPath *string `json:"link_path,omitempty"` + SortOrder int `json:"sort_order"` + Active bool `json:"active"` + System bool `json:"system"` + UpdatedAt time.Time `json:"updated_at"` +} + +// ListBanners returns banner catalog. +func (r *AdminRepo) ListBanners(ctx context.Context) ([]BannerRow, error) { + rows, err := r.Pool.Query(ctx, ` + SELECT id, code, title, placement, image_url, link_path, sort_order, active, system, updated_at + FROM ops_banners + ORDER BY active DESC, sort_order ASC, code ASC`) + if err != nil { + return nil, err + } + defer rows.Close() + var out []BannerRow + for rows.Next() { + var b BannerRow + if err := rows.Scan( + &b.ID, &b.Code, &b.Title, &b.Placement, &b.ImageURL, &b.LinkPath, + &b.SortOrder, &b.Active, &b.System, &b.UpdatedAt, + ); err != nil { + return nil, err + } + out = append(out, b) + } + return out, rows.Err() +} + +// GetBanner loads one banner by id. +func (r *AdminRepo) GetBanner(ctx context.Context, id uuid.UUID) (*BannerRow, error) { + var b BannerRow + err := r.Pool.QueryRow(ctx, ` + SELECT id, code, title, placement, image_url, link_path, sort_order, active, system, updated_at + FROM ops_banners WHERE id=$1`, id, + ).Scan( + &b.ID, &b.Code, &b.Title, &b.Placement, &b.ImageURL, &b.LinkPath, + &b.SortOrder, &b.Active, &b.System, &b.UpdatedAt, + ) + if errors.Is(err, pgx.ErrNoRows) { + return nil, err + } + if err != nil { + return nil, err + } + return &b, nil +} diff --git a/apps/api/internal/service/admin/cms.go b/apps/api/internal/service/admin/cms.go new file mode 100644 index 0000000..84eff32 --- /dev/null +++ b/apps/api/internal/service/admin/cms.go @@ -0,0 +1,34 @@ +package admin + +import ( + "context" + "errors" + + "github.com/google/uuid" + "github.com/jackc/pgx/v5" + + "github.com/yuxingu/digital-psychology/apps/api/internal/repository" +) + +var ErrBannerNotFound = errString("banner not found") + +// ListBanners returns OpsCMS Banner catalog. +func (s *Service) ListBanners(ctx context.Context) ([]repository.BannerRow, error) { + items, err := s.Repo.ListBanners(ctx) + if err != nil { + return nil, err + } + if items == nil { + items = []repository.BannerRow{} + } + return items, nil +} + +// GetBanner loads one banner. +func (s *Service) GetBanner(ctx context.Context, id uuid.UUID) (*repository.BannerRow, error) { + row, err := s.Repo.GetBanner(ctx, id) + if errors.Is(err, pgx.ErrNoRows) { + return nil, ErrBannerNotFound + } + return row, err +} diff --git a/apps/api/internal/service/admin/rbac.go b/apps/api/internal/service/admin/rbac.go index 1912d84..4bc8a04 100644 --- a/apps/api/internal/service/admin/rbac.go +++ b/apps/api/internal/service/admin/rbac.go @@ -29,6 +29,7 @@ const ( PermContentSafetyRead = "admin.content_safety.read" PermAIConfigRead = "admin.ai_config.read" PermCrisisRead = "admin.crisis.read" + PermCMSRead = "admin.cms.read" ) var knownPermissions = map[string]struct{}{ @@ -38,7 +39,7 @@ var knownPermissions = map[string]struct{}{ PermUsersStatusWrite: {}, PermMembershipPlansRead: {}, PermMembershipPlansWrite: {}, PermMembershipCodesRead: {}, PermMembershipCodesWrite: {}, PermAskRead: {}, PermAskFeedbackWrite: {}, PermContentSafetyRead: {}, - PermAIConfigRead: {}, PermCrisisRead: {}, + PermAIConfigRead: {}, PermCrisisRead: {}, PermCMSRead: {}, } var ( diff --git a/apps/api/migrations/000025_ops_banners.down.sql b/apps/api/migrations/000025_ops_banners.down.sql new file mode 100644 index 0000000..14ff075 --- /dev/null +++ b/apps/api/migrations/000025_ops_banners.down.sql @@ -0,0 +1,3 @@ +-- ECR-024 down +DELETE FROM admin_role_permissions WHERE code = 'admin.cms.read'; +DROP TABLE IF EXISTS ops_banners; diff --git a/apps/api/migrations/000025_ops_banners.up.sql b/apps/api/migrations/000025_ops_banners.up.sql new file mode 100644 index 0000000..c477ef1 --- /dev/null +++ b/apps/api/migrations/000025_ops_banners.up.sql @@ -0,0 +1,37 @@ +-- ECR-024 OpsCMS Banner (read catalog) + +CREATE TABLE IF NOT EXISTS ops_banners ( + id uuid PRIMARY KEY DEFAULT gen_random_uuid(), + code varchar(64) NOT NULL UNIQUE, + title varchar(128) NOT NULL, + placement varchar(32) NOT NULL + CHECK (placement IN ('home','explore','ask')), + image_url text NULL, + link_path varchar(256) NULL, + sort_order int NOT NULL DEFAULT 0, + active boolean NOT NULL DEFAULT true, + system boolean NOT NULL DEFAULT false, + created_at timestamptz NOT NULL DEFAULT now(), + updated_at timestamptz NOT NULL DEFAULT now() +); + +CREATE INDEX IF NOT EXISTS idx_ops_banners_active ON ops_banners(active); + +INSERT INTO ops_banners(code, title, placement, image_url, link_path, sort_order, active, system) +VALUES ( + 'home_promo', + '首页运营横幅占位', + 'home', + NULL, + '/membership', + 10, + true, + true +) +ON CONFLICT (code) DO NOTHING; + +INSERT INTO admin_role_permissions(role_id, code) +SELECT r.id, 'admin.cms.read' +FROM admin_roles r +WHERE r.name = 'super_admin' +ON CONFLICT DO NOTHING; diff --git a/docs/BACKEND_DESIGN/BD-2026-024-banner.md b/docs/BACKEND_DESIGN/BD-2026-024-banner.md new file mode 100644 index 0000000..ca6f219 --- /dev/null +++ b/docs/BACKEND_DESIGN/BD-2026-024-banner.md @@ -0,0 +1,23 @@ +# Backend Design: ECR-024 Banner + +| ID | BD-2026-024 | +| Status | Approved | +| Coding | Loop authorized | +| Level | L2 | +| Migration | YES 000025 | + +## Backend Change Boundary + +```text +Domain: Banner (read) +App: AdminHandler → admin.Service → AdminRepo +API: GET /admin/cms/banners; GET /admin/cms/banners/{id} +Permission: admin.cms.read +Migration: 000025 +``` + +## Out of boundary + +Banner 写发布 · FeedSlot · ScheduledPublication · UGC · 真支付 + +Rollback: down migration + remove routes/UI diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index a2ff156..212c555 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -2,6 +2,7 @@ ## 2026-08-08 +- **ECR-024 Closed**：OpsCMS Banner（`ops_banners` · admin-h5 `/cms` · migration 000025 · 只读） - **ECR-023 Closed**：AICoreConfig KnowledgeSource（`knowledge_sources` · admin-h5 `/ai` · migration 000024 · 只读） - **ECR-022 Closed**：CrisisCare CrisisPolicy（`crisis_policies` · evaluate · admin-h5 `/crisis` · migration 000023） - **ECR-021 Closed**：AICoreConfig SystemPrompt（`system_prompts` · admin-h5 `/ai` · migration 000022 · 只读） diff --git a/docs/CODE_REVIEW/ECR-024.md b/docs/CODE_REVIEW/ECR-024.md new file mode 100644 index 0000000..3c1eb55 --- /dev/null +++ b/docs/CODE_REVIEW/ECR-024.md @@ -0,0 +1,8 @@ +# CODE_REVIEW — ECR-024 + +**Verdict:** Approve → Closed + +Date: 2026-08-08 · Loop continuous + +- Banner 只读；无 UGC/写发布 +- Integration AC mapped · OpenAPI updated diff --git a/docs/CONTRACT_DIFF/ECR-024.yaml b/docs/CONTRACT_DIFF/ECR-024.yaml new file mode 100644 index 0000000..abdc7a9 --- /dev/null +++ b/docs/CONTRACT_DIFF/ECR-024.yaml @@ -0,0 +1,22 @@ +ecr: ECR-024 +capability: OpsCMS +bounded_context: Ops_CMS_NoUGC +parent: WAVE0-FROZEN +predecessor: ECR-023 +change: + type: additive +breaking_change: false +migration_required: true +compatibility_notes: > + Adds Banner read catalog. Forbidden: UGC / real payment. + +apis: + - method: GET + path: /api/v1/admin/cms/banners + change: added + - method: GET + path: /api/v1/admin/cms/banners/{id} + change: added +perms: + - code: admin.cms.read + change: added diff --git a/docs/ECR/ECR-024-banner.md b/docs/ECR/ECR-024-banner.md new file mode 100644 index 0000000..ac77592 --- /dev/null +++ b/docs/ECR/ECR-024-banner.md @@ -0,0 +1,19 @@ +# ECR-024 + +**Title:** OpsCMS · Banner（只读薄切片） +**Status:** **Closed** +**Closed:** 2026-08-08（Loop continuous） +**Parent:** WAVE0-FROZEN · **Predecessor:** ECR-023 Closed +**Change Level:** L2 + +## Change + +`ops_banners` + `GET /admin/cms/banners*`；`admin.cms.read`；admin-h5 `/cms`。 + +## Forbidden + +Banner 写发布 · FeedSlot · ScheduledPublication · UGC · 真支付 + +## Linked + +Spec `ops-banner.md` · BD-2026-024 · CONTRACT_DIFF/ECR-024.yaml · TEST_REPORT/ECR-024.md diff --git a/docs/ENGINEERING_SPEC/ECR-024-banner.md b/docs/ENGINEERING_SPEC/ECR-024-banner.md new file mode 100644 index 0000000..021cd76 --- /dev/null +++ b/docs/ENGINEERING_SPEC/ECR-024-banner.md @@ -0,0 +1,6 @@ +# ENGINEERING_SPEC — ECR-024 + +1. migration 000025 +2. AdminRepo/Service/Handler +3. OpenAPI + admin-h5 +4. Integration · Closed diff --git a/docs/HANDOFF/ECR-024-architect-to-engineer.md b/docs/HANDOFF/ECR-024-architect-to-engineer.md new file mode 100644 index 0000000..b82c5bc --- /dev/null +++ b/docs/HANDOFF/ECR-024-architect-to-engineer.md @@ -0,0 +1,3 @@ +# HANDOFF — ECR-024 Architect → Engineer + +Loop continuous · Approved + Coding. Migration 000025. Forbidden: UGC/真支付. diff --git a/docs/HANDOFF/ECR-024-engineer-to-reviewer.md b/docs/HANDOFF/ECR-024-engineer-to-reviewer.md new file mode 100644 index 0000000..4e466fb --- /dev/null +++ b/docs/HANDOFF/ECR-024-engineer-to-reviewer.md @@ -0,0 +1,3 @@ +# HANDOFF — ECR-024 Engineer → Reviewer + +TestOpsCMSBanners PASS · /cms · Ready for Closed. diff --git a/docs/PRODUCT_SPEC/ECR-024-banner.md b/docs/PRODUCT_SPEC/ECR-024-banner.md new file mode 100644 index 0000000..9f95a66 --- /dev/null +++ b/docs/PRODUCT_SPEC/ECR-024-banner.md @@ -0,0 +1,3 @@ +# PRODUCT_SPEC — ECR-024 + +对齐 ops-banner.md · Approved · Loop · L2 · Banner 只读 diff --git a/docs/STATE/ECR-024.md b/docs/STATE/ECR-024.md new file mode 100644 index 0000000..642130a --- /dev/null +++ b/docs/STATE/ECR-024.md @@ -0,0 +1,6 @@ +# STATE — ECR-024 + +| Status | **Closed** | +| Phase | closed | +| Spec | ops-banner.md | +| Updated | 2026-08-08 | diff --git a/docs/TASKS/TASK-024-ECR024.yaml b/docs/TASKS/TASK-024-ECR024.yaml new file mode 100644 index 0000000..d43434d --- /dev/null +++ b/docs/TASKS/TASK-024-ECR024.yaml @@ -0,0 +1,12 @@ +id: TASK-024-ECR024 +ecr: ECR-024 +title: OpsCMS Banner read +role: engineer +status: closed +change_level: L2 +parent: WAVE0-FROZEN +predecessor: ECR-023 +acceptance: + - Spec AC mapped + - Banner read only + - No UGC / payment diff --git a/docs/TEST_REPORT/ECR-024.md b/docs/TEST_REPORT/ECR-024.md new file mode 100644 index 0000000..a96a317 --- /dev/null +++ b/docs/TEST_REPORT/ECR-024.md @@ -0,0 +1,33 @@ +# TEST_REPORT — ECR-024 Banner + +Date: 2026-08-08 · Loop continuous · commit: `PENDING` + +## Commands + +```bash +cd apps/api && go test ./internal/integration/ -run TestOpsCMSBanners -count=1 +npm run build:admin +python3 scripts/ess-validate.py --phase review --ecr ECR-024 +python3 scripts/ess-gate-check.py --ecr ECR-024 +``` + +## Results + +| Check | Result | +|-------|--------| +| TestOpsCMSBanners | PASS | +| build:admin | PASS | +| ess-validate review | PASS | +| ess-gate-check | PASS | + +## AC + +| ID | Evidence | +|----|----------| +| AC-F-01 | list 含 home_promo | +| AC-F-02 | get 200 | +| AC-F-03 | 未知 id → 404 | +| AC-S-01 | 401 | +| AC-S-02 | 403 | +| AC-P-01 | list < 500ms | +| AC-O-01 | N/A 只读 | diff --git a/docs/TRACEABILITY.md b/docs/TRACEABILITY.md index 54d0bea..65a320f 100644 --- a/docs/TRACEABILITY.md +++ b/docs/TRACEABILITY.md @@ -28,3 +28,4 @@ | ECR-021 | AICoreConfig | **Closed** | Spec ops-ai-core-config · BD-2026-021 · migration 000022 · TEST_REPORT · CODE_REVIEW · Loop continuous | | ECR-022 | CrisisCare | **Closed** | Spec ops-crisis-care · BD-2026-022 · migration 000023 · TEST_REPORT · CODE_REVIEW · Loop continuous | | ECR-023 | AICoreConfig · KnowledgeSource | **Closed** | Spec ops-knowledge-source · BD-2026-023 · migration 000024 · TEST_REPORT · CODE_REVIEW · Loop continuous | +| ECR-024 | OpsCMS · Banner | **Closed** | Spec ops-banner · BD-2026-024 · migration 000025 · TEST_REPORT · CODE_REVIEW · Loop continuous | diff --git a/docs/WAVE0/LOOP_AUTHORIZATION.md b/docs/WAVE0/LOOP_AUTHORIZATION.md index 86468b8..26b1030 100644 --- a/docs/WAVE0/LOOP_AUTHORIZATION.md +++ b/docs/WAVE0/LOOP_AUTHORIZATION.md @@ -9,7 +9,8 @@ ## Override -Human 明文：**直接用 Loop，不用人工确认。** +Human 明文：**直接用 Loop，不用人工确认。** +2026-08-08 追加：**把所有剩余 Ops 薄切片 ECR 做完再停**（见 Full queue）。 在本授权有效期内，对 Ops 薄切片允许 Agent： @@ -26,8 +27,32 @@ Human 明文：**直接用 Loop，不用人工确认。** - 跳过 Feature Spec / contract_diff / AC - force-push / 改 git config +## Full queue（024–040 · 只读优先 · 完成后停） + +| ECR | Concept | Capability | +|-----|---------|------------| +| 024 | Banner | OpsCMS | +| 025 | FeedSlot | OpsCMS | +| 026 | ScheduledPublication | OpsCMS | +| 027 | KnowledgeChunk | AICoreConfig | +| 028 | ToolDefinition | AICoreConfig | +| 029 | BlockPolicy | ContentSafety | +| 030 | ModerationCase | ContentSafety | +| 031 | CrisisEvent | CrisisCare | +| 032 | InterventionOutcome | CrisisCare | +| 033 | HandoffCase | AskOperations | +| 034 | PrivacyRequest | AdminGovernance | +| 035 | StarConfig | ExploreConfig | +| 036 | RhythmConfig | ExploreConfig | +| 037 | ImageCardDeck | ExploreConfig | +| 038 | ReportTemplate | GrowthInsights | +| 039 | FunnelDefinition | GrowthInsights | +| 040 | ScaleDefinition 只读投影 | ExploreConfig | + +**Stop after ECR-040 Closed.** 不进入：Community/UGC · soft-delete · 真支付适配器。 + ## Active queue | Done | Next | |------|------| -| ECR-013A…023 Closed | **ECR-024** Banner/OpsCMS 薄切片（只读优先）或 KnowledgeChunk；禁真支付/UGC | +| ECR-013A…024 Closed | **ECR-025** FeedSlot（OpsCMS） | diff --git a/proto/openapi.yaml b/proto/openapi.yaml index 867ab99..00b984e 100644 --- a/proto/openapi.yaml +++ b/proto/openapi.yaml @@ -583,6 +583,34 @@ paths: '404': description: Not found + /api/v1/admin/cms/banners: + get: + tags: [admin] + summary: List OpsCMS Banner catalog + description: Requires admin.cms.read + responses: + '200': + description: OK + '401': + description: Unauthorized + '403': + description: Forbidden + + /api/v1/admin/cms/banners/{id}: + get: + tags: [admin] + summary: Get Banner + parameters: + - in: path + name: id + required: true + schema: { type: string, format: uuid } + responses: + '200': + description: OK + '404': + description: Not found + /api/v1/admin/crisis/policies: get: tags: [admin] diff --git a/scripts/ess-slice-scaffold.py b/scripts/ess-slice-scaffold.py new file mode 100755 index 0000000..7092c43 --- /dev/null +++ b/scripts/ess-slice-scaffold.py @@ -0,0 +1,172 @@ +#!/usr/bin/env python3 +"""Scaffold ESS thin-slice artifacts for Ops Loop (docs only).""" +import argparse +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + +def write(path: Path, text: str): + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text.strip() + "\n", encoding="utf-8") + print("wrote", path.relative_to(ROOT)) + +def main(): + p = argparse.ArgumentParser() + p.add_argument("--ecr", required=True) # 024 + p.add_argument("--slug", required=True) # banner + p.add_argument("--title", required=True) + p.add_argument("--capability", required=True) + p.add_argument("--bc", required=True) + p.add_argument("--concept", required=True) + p.add_argument("--predecessor", required=True) # ECR-023 + p.add_argument("--migration", required=True) # 000025 + p.add_argument("--perm", required=True) + p.add_argument("--apis", required=True, help="comma paths like GET /admin/cms/banners|GET /admin/cms/banners/{id}") + p.add_argument("--non-goals", required=True) + p.add_argument("--seed", default="") + p.add_argument("--new-perm", action="store_true") + args = p.parse_args() + + ecr = f"ECR-{args.ecr}" + bd = f"BD-2026-{args.ecr}" + spec = f"ops-{args.slug}.md" + apis = [a.strip() for a in args.apis.split("|")] + + write(ROOT / f".ai/product/feature-spec/{spec}", f""" +# Feature Spec: {args.capability} · {args.concept}（Ops · {ecr}） + +> Status: `Active`（Loop continuous · **{ecr}**） +> Parent: WAVE0-FROZEN · Predecessor: {args.predecessor} Closed +> Capability: `{args.capability}` · BC: `{args.bc}` +> 授权：`docs/WAVE0/LOOP_AUTHORIZATION.md` + +## Non-goals + +{args.non_goals} + +## L2 Domain + +| 概念 | 语义 | +|------|------| +| `{args.concept}` | 本切片只读目录；code 唯一（若适用） | + +## L3 API + +| Method | Path | 权限 | 语义 | +|--------|------|------|------| +""" + "\n".join( + f"| {a.split()[0]} | `{a.split()[1]}` | `{args.perm}` | 只读 |" + for a in apis + ) + f""" + +## Migration + +`{args.migration}`：表 + 种子（若有）{' + 授予 ' + args.perm if args.new_perm else '（权限复用）'} + +## L4 AC + +| ID | Then | +|----|------| +| AC-F-01 | list 含种子或空列表合法 | +| AC-F-02 | 已知 id get 200 | +| AC-F-03 | 未知 id → 404 | +| AC-S-01 | 无 Admin → 401 | +| AC-S-02 | 无权限 → 403 | +| AC-P-01 | list < 500ms | +| AC-O-01 | N/A 只读 | + +contract_diff: `docs/CONTRACT_DIFF/{ecr}.yaml` +""") + + write(ROOT / f"docs/ECR/{ecr}-{args.slug}.md", f""" +# {ecr} + +**Title:** {args.title} +**Status:** **Approved**（Coding authorized · Loop continuous） +**Parent:** WAVE0-FROZEN · **Predecessor:** {args.predecessor} Closed +**Change Level:** L2 + +## Change + +{args.concept} 只读 · `{args.migration}` · `{args.perm}` + +## Forbidden + +{args.non_goals} + +## Linked + +Spec `{spec}` · {bd} · CONTRACT_DIFF/{ecr}.yaml +""") + + write(ROOT / f"docs/BACKEND_DESIGN/{bd}-{args.slug}.md", f""" +# Backend Design: {ecr} {args.concept} + +| ID | {bd} | +| Status | Approved | +| Coding | Loop authorized | +| Level | L2 | +| Migration | YES {args.migration} | + +## Backend Change Boundary + +```text +Domain: {args.concept} (read) +App: AdminHandler → admin.Service → AdminRepo +API: {'; '.join(apis)} +Permission: {args.perm} +Migration: {args.migration} +``` + +## Out of boundary + +{args.non_goals} + +Rollback: down migration + remove routes/UI +""") + + api_yaml = "\n".join( + f" - method: {a.split()[0]}\n path: /api/v1{a.split()[1]}\n change: added" + for a in apis + ) + perm_line = f" - code: {args.perm}\n change: {'added' if args.new_perm else 'unchanged'}" + write(ROOT / f"docs/CONTRACT_DIFF/{ecr}.yaml", f""" +ecr: {ecr} +capability: {args.capability} +bounded_context: {args.bc} +parent: WAVE0-FROZEN +predecessor: {args.predecessor} +change: + type: additive +breaking_change: false +migration_required: true +compatibility_notes: > + Adds {args.concept} read catalog. Forbidden: UGC / real payment. + +apis: +{api_yaml} +perms: +{perm_line} +""") + + write(ROOT / f"docs/PRODUCT_SPEC/{ecr}-{args.slug}.md", f"# PRODUCT_SPEC — {ecr}\n\n对齐 {spec} · Approved · Loop · L2 · {args.concept} 只读") + write(ROOT / f"docs/ENGINEERING_SPEC/{ecr}-{args.slug}.md", f"# ENGINEERING_SPEC — {ecr}\n\n1. migration {args.migration}\n2. AdminRepo/Service/Handler\n3. OpenAPI + admin-h5\n4. Integration · Closed") + write(ROOT / f"docs/HANDOFF/{ecr}-architect-to-engineer.md", f"# HANDOFF — {ecr} Architect → Engineer\n\nLoop continuous · Approved + Coding. Migration {args.migration}. Forbidden: UGC/真支付.") + write(ROOT / f"docs/STATE/{ecr}.md", f"# STATE — {ecr}\n\n| Status | **Approved** · Coding |\n| Phase | coding |\n| Spec | {spec} |\n| Updated | 2026-08-08 |") + write(ROOT / f"docs/TASKS/TASK-{args.ecr}-{ecr.replace('-','')}.yaml", f""" +id: TASK-{args.ecr}-{ecr.replace('-','')} +ecr: {ecr} +title: {args.title} +role: engineer +status: active +change_level: L2 +parent: WAVE0-FROZEN +predecessor: {args.predecessor} +acceptance: + - Spec AC mapped + - {args.concept} read only + - No UGC / payment +""") + +if __name__ == "__main__": + main()