feat(ECR-048): ReportTemplate 写面闭环并 Closed

growth.write POST/PUT · migration 000057 · 无新 C 端 · Loop STOP Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-13 22:51:42 +08:00
parent aa197b719b
commit e0f605558b
28 changed files with 915 additions and 11 deletions
@@ -55,7 +55,8 @@
 | [ops-rhythm-config-write.md](ops-rhythm-config-write.md) | RhythmConfig **写面** | §7 | admin 写 · `GET /rhythm/configs` | ExploreConfig · **ECR-044** |
 | [ops-image-card-deck.md](ops-image-card-deck.md) | ExploreConfig ImageCardDeck（只读） | §7 | `/admin/explore/image-card-decks*` | Ops · **ECR-037** |
 | [ops-image-card-deck-write.md](ops-image-card-deck-write.md) | ImageCardDeck **写面** | §7 | admin 写 · `GET /cards/decks` | ExploreConfig · **ECR-045** |
-| [ops-report-template.md](ops-report-template.md) | GrowthInsights ReportTemplate | §7 | `/admin/growth/report-templates*` | Ops · **ECR-038** |
+| [ops-report-template.md](ops-report-template.md) | GrowthInsights ReportTemplate（只读） | §7 | `/admin/growth/report-templates*` | Ops · **ECR-038** |
+| [ops-report-template-write.md](ops-report-template-write.md) | ReportTemplate **写面** | §7 | admin POST/PUT · growth.write | GrowthInsights · **ECR-048** |
 | [ops-funnel-definition.md](ops-funnel-definition.md) | GrowthInsights FunnelDefinition（只读） | §7 | `/admin/analytics/funnel-definitions*` | Ops · **ECR-039** |
 | [ops-funnel-definition-write.md](ops-funnel-definition-write.md) | FunnelDefinition **写面** | §7 | admin POST/PUT · growth.write | GrowthInsights · **ECR-047** |
 | [ops-scale-definition.md](ops-scale-definition.md) | ExploreConfig ScaleDefinition（只读） | §7 | `/admin/explore/scales*` | Ops · **ECR-040** |
@@ -0,0 +1,73 @@
+# Feature Spec: GrowthInsights · ReportTemplate 写面（Ops · ECR-048）
+
+> Status: `Active`（**Implemented · ECR-048 Closed**）  
+> Map: `§7` · Capability: `GrowthInsights` · BC: `Explore_Reports`  
+> Auth: `docs/WAVE0/ECR-048_WRITE_AUTHORIZATION.md`（**仅 ECR-048**）  
+> Predecessor: ECR-038 Closed（只读）· ECR-047 Closed（Funnel 写）  
+> 关联：[ops-report-template.md](ops-report-template.md)
+
+---
+
+## 1. 目标
+
+运营可 **创建 / 更新 / 上下架** `ReportTemplate`（报告模板目录）；写鉴权 + 审计；**无**新 C 端路由。
+
+**Closed 后立即 STOP**，不自动 ECR-049。
+
+## 2. In / Out
+
+| In | Out |
+|----|-----|
+| Admin POST/PUT `/admin/growth/report-templates*` | Funnel 再写 |
+| 复用 `admin.growth.write` | SystemPrompt · Knowledge · Chunk |
+| 复用表 `report_templates` | soft-delete · 真支付 · UGC |
+| 审计 | 题干 · Crisis/Handoff |
+| | 自动 ECR-049 · 新 C 端路由 |
+
+## 3. Domain
+
+| 字段 | 规则 |
+|------|------|
+| `code` | 唯一；`^[a-z][a-z0-9_]{1,62}$`；`system=true` **不可改 code** |
+| `title` | 必填 · ≤128 |
+| `scene` | 必填；`^[a-z][a-z0-9_]{0,30}$` · ≤32 |
+| `active` | `false` = 下架 |
+| `system` | 种子行；禁止物理删除 |
+
+## 4. API
+
+| Method | Path | 权限 |
+|--------|------|------|
+| GET | `/admin/growth/report-templates` · `/{id}` | `admin.growth.read` |
+| POST | `/admin/growth/report-templates` | `admin.growth.write` |
+| PUT | `/admin/growth/report-templates/{id}` | `admin.growth.write` |
+
+无 DELETE · 无新 C 端路径。
+
+## 5. Permission / Migration
+
+- Migration `000057_ops_report_template_write`：幂等确认 `super_admin` → `admin.growth.write`  
+- 编码时占号（Max=`000056` → `000057`）
+
+## 6. UI
+
+admin-h5 报告模板页：列表 + 新建/编辑/上下架。
+
+## 7. AC
+
+| ID | Then |
+|----|------|
+| AC-F-01 | POST → list/get 可见 |
+| AC-F-02 | PUT active=false → list 仍可见且 active=false |
+| AC-F-03 | 重复 code → 409 |
+| AC-S-01/02 | 401；仅 growth.read → POST 403 |
+| AC-A-01 | 写产生审计 |
+| AC-O-01 | 无 soft-delete · 无 Funnel/Prompt 写路径 |
+
+## 8. Closed 后
+
+**立即 STOP**。ECR-049 须新 Candidate Review + Human 拍板。
+
+## 9. Trace
+
+ECR-048 · BD-2026-048 · CONTRACT_DIFF · ECR-048_WRITE_AUTHORIZATION  
@@ -1,6 +1,7 @@
 # Feature Spec: GrowthInsights · ReportTemplate（Ops · ECR-038）

 > Status: `Active`（Loop continuous · **ECR-038 Closed**）  
+> **写面：** [ops-report-template-write.md](ops-report-template-write.md)（**ECR-048 Closed**）  
 > Parent: WAVE0-FROZEN · Predecessor: ECR-037 Closed  
 > Capability: `GrowthInsights` · BC: `Explore_Reports`  
 > 授权：`docs/WAVE0/LOOP_AUTHORIZATION.md`
@@ -718,9 +718,55 @@ export const adminApi = {
      updated_at: string
    }>('PUT', `/explore/image-card-decks/${id}`, body),
  reportTemplates: () =>
-    request<{ items: Array<Record<string, unknown>> }>('GET', '/growth/report-templates'),
+    request<{
+      items: Array<{
+        id: string
+        code: string
+        title: string
+        scene: string
+        active: boolean
+        system: boolean
+        updated_at: string
+      }>
+    }>('GET', '/growth/report-templates'),
  reportTemplate: (id: string) =>
-    request<Record<string, unknown>>('GET', `/growth/report-templates/${id}`),
+    request<{
+      id: string
+      code: string
+      title: string
+      scene: string
+      active: boolean
+      system: boolean
+      updated_at: string
+    }>('GET', `/growth/report-templates/${id}`),
+  createReportTemplate: (body: {
+    code: string
+    title: string
+    scene: string
+    active: boolean
+  }) =>
+    request<{
+      id: string
+      code: string
+      title: string
+      scene: string
+      active: boolean
+      system: boolean
+      updated_at: string
+    }>('POST', '/growth/report-templates', body),
+  updateReportTemplate: (
+    id: string,
+    body: { code: string; title: string; scene: string; active: boolean },
+  ) =>
+    request<{
+      id: string
+      code: string
+      title: string
+      scene: string
+      active: boolean
+      system: boolean
+      updated_at: string
+    }>('PUT', `/growth/report-templates/${id}`, body),
  funnelDefinitions: () =>
    request<{
      items: Array<{
@@ -40,6 +40,7 @@ async function onLogout() {
        <RouterLink to="/image-card-decks">意象牌组</RouterLink>
        <RouterLink to="/scale-definitions">量表元数据</RouterLink>
        <RouterLink to="/funnel-definitions">漏斗定义</RouterLink>
+        <RouterLink to="/report-templates">报告模板</RouterLink>
        <RouterLink to="/catalogs">目录仓</RouterLink>
        <RouterLink to="/orders">订单</RouterLink>
        <RouterLink v-if="auth.can('admin.membership.plans.read')" to="/pricing">定价</RouterLink>
@@ -0,0 +1,171 @@
+<script setup lang="ts">
+import { onMounted, reactive, ref } from 'vue'
+import { adminApi } from '@/api/client'
+import { useAuthStore } from '@/stores/auth'
+
+type Row = Awaited<ReturnType<typeof adminApi.reportTemplates>>['items'][number]
+
+const auth = useAuthStore()
+const canWrite = () => auth.can('admin.growth.write')
+
+const loading = ref(false)
+const error = ref('')
+const items = ref<Row[]>([])
+const selected = ref<Row | null>(null)
+const saving = ref(false)
+const formErr = ref('')
+const form = reactive({
+  code: '',
+  title: '',
+  scene: 'portrait',
+  active: true,
+})
+
+async function load() {
+  loading.value = true
+  error.value = ''
+  try {
+    const res = await adminApi.reportTemplates()
+    items.value = res.items || []
+  } catch (e) {
+    error.value = e instanceof Error ? e.message : '加载失败'
+  } finally {
+    loading.value = false
+  }
+}
+
+function resetForm() {
+  form.code = ''
+  form.title = ''
+  form.scene = 'portrait'
+  form.active = true
+  selected.value = null
+  formErr.value = ''
+}
+
+async function openRow(id: string) {
+  formErr.value = ''
+  try {
+    const row = await adminApi.reportTemplate(id)
+    selected.value = row
+    form.code = row.code
+    form.title = row.title
+    form.scene = row.scene
+    form.active = row.active
+  } catch {
+    selected.value = null
+  }
+}
+
+function payload() {
+  return {
+    code: form.code.trim(),
+    title: form.title.trim(),
+    scene: form.scene.trim(),
+    active: form.active,
+  }
+}
+
+async function createRow() {
+  if (!canWrite()) return
+  saving.value = true
+  formErr.value = ''
+  try {
+    const row = await adminApi.createReportTemplate(payload())
+    await load()
+    await openRow(row.id)
+  } catch (e) {
+    formErr.value = e instanceof Error ? e.message : '创建失败'
+  } finally {
+    saving.value = false
+  }
+}
+
+async function saveRow() {
+  if (!selected.value || !canWrite()) return
+  saving.value = true
+  formErr.value = ''
+  try {
+    const row = await adminApi.updateReportTemplate(selected.value.id, payload())
+    selected.value = row
+    await load()
+  } catch (e) {
+    formErr.value = e instanceof Error ? e.message : '保存失败'
+  } finally {
+    saving.value = false
+  }
+}
+
+async function toggleActive() {
+  if (!selected.value || !canWrite()) return
+  form.active = !form.active
+  await saveRow()
+}
+
+onMounted(() => {
+  void load()
+})
+</script>
+
+<template>
+  <section>
+    <h1>报告模板</h1>
+    <p class="muted">ReportTemplate 写面 · 下架仅 active=false · ECR-048</p>
+    <p v-if="!canWrite()" class="err">需要 admin.growth.write 才可写</p>
+    <p v-if="loading" class="muted">加载中…</p>
+    <p v-else-if="error" class="err">{{ error }}</p>
+    <div v-else class="layout">
+      <div class="card">
+        <h2>列表</h2>
+        <button v-if="canWrite()" class="btn" type="button" @click="resetForm">新建</button>
+        <p v-if="!items.length" class="muted">暂无</p>
+        <table v-else>
+          <thead>
+            <tr><th>代码</th><th>标题</th><th>场景</th><th>状态</th><th></th></tr>
+          </thead>
+          <tbody>
+            <tr v-for="b in items" :key="b.id">
+              <td><code>{{ b.code }}</code></td>
+              <td>{{ b.title }}</td>
+              <td>{{ b.scene }}</td>
+              <td>{{ b.active ? '启用' : '停用' }}</td>
+              <td><button class="btn" type="button" @click="openRow(b.id)">编辑</button></td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+      <div class="card">
+        <h2>{{ selected ? '编辑' : '新建' }}</h2>
+        <label>代码 <input v-model="form.code" :disabled="!!selected?.system || !canWrite()" /></label>
+        <label>标题 <input v-model="form.title" :disabled="!canWrite()" /></label>
+        <label>场景 <input v-model="form.scene" :disabled="!canWrite()" /></label>
+        <label class="check"><input v-model="form.active" type="checkbox" :disabled="!canWrite()" /> 启用</label>
+        <p v-if="formErr" class="err">{{ formErr }}</p>
+        <div v-if="canWrite()" class="actions">
+          <button v-if="!selected" class="btn primary" type="button" :disabled="saving" @click="createRow">
+            创建
+          </button>
+          <template v-else>
+            <button class="btn primary" type="button" :disabled="saving" @click="saveRow">保存</button>
+            <button class="btn" type="button" :disabled="saving" @click="toggleActive">
+              {{ form.active ? '下架' : '上架' }}
+            </button>
+          </template>
+        </div>
+      </div>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+h1 { margin: 0 0 0.35rem; font-size: 1.35rem; }
+h2 { margin: 0 0 0.6rem; font-size: 1.05rem; }
+.layout { display: grid; grid-template-columns: 1.2fr 1fr; gap: 1rem; margin-top: 1rem; }
+code { font-size: 0.8rem; }
+.card label { display: block; margin: 0.4rem 0; font-size: 0.9rem; }
+.card input { width: 100%; margin-top: 0.2rem; }
+.check { display: flex; align-items: center; gap: 0.4rem; }
+.actions { display: flex; gap: 0.5rem; margin-top: 0.75rem; }
+.btn.primary { font-weight: 600; }
+@media (max-width: 900px) { .layout { grid-template-columns: 1fr; } }
+</style>
@@ -54,6 +54,12 @@ const router = createRouter({
          component: () => import('@/pages/FunnelDefinitionPage.vue'),
          meta: { permission: 'admin.growth.read' },
        },
+        {
+          path: 'report-templates',
+          name: 'report-templates',
+          component: () => import('@/pages/ReportTemplatePage.vue'),
+          meta: { permission: 'admin.growth.read' },
+        },
        { path: 'catalogs', name: 'catalogs', component: () => import('@/pages/CatalogHubPage.vue') },
        { path: 'push', name: 'push', component: () => import('@/pages/PushJobsPage.vue') },
        { path: 'admins', name: 'admins', component: () => import('@/pages/AdminsPage.vue'), meta: { superOnly: true } },
@@ -16,6 +16,8 @@ func (h *AdminHandler) registerReportTemplates(authed *gin.RouterGroup) {
 	g := authed.Group("/growth")
 	g.GET("/report-templates", middleware.RequireAdminPermission(h.Svc, admin.PermGrowthRead), h.ListReportTemplates)
 	g.GET("/report-templates/:id", middleware.RequireAdminPermission(h.Svc, admin.PermGrowthRead), h.GetReportTemplate)
+	g.POST("/report-templates", middleware.RequireAdminPermission(h.Svc, admin.PermGrowthWrite), h.CreateReportTemplate)
+	g.PUT("/report-templates/:id", middleware.RequireAdminPermission(h.Svc, admin.PermGrowthWrite), h.UpdateReportTemplate)
 }

 func (h *AdminHandler) ListReportTemplates(c *gin.Context) {
@@ -44,3 +46,66 @@ func (h *AdminHandler) GetReportTemplate(c *gin.Context) {
 	}
 	response.OK(c, row)
 }
+
+func (h *AdminHandler) CreateReportTemplate(c *gin.Context) {
+	adminID, ok := middleware.AdminIDFromContext(c)
+	if !ok {
+		response.Fail(c, http.StatusUnauthorized, 40101, "admin auth required")
+		return
+	}
+	var body admin.ReportTemplateWriteBody
+	if err := c.ShouldBindJSON(&body); err != nil {
+		response.Fail(c, http.StatusBadRequest, 40054, "invalid body")
+		return
+	}
+	row, err := h.Svc.CreateReportTemplate(c.Request.Context(), adminID, body)
+	if errors.Is(err, admin.ErrInvalidReportTemplate) {
+		response.Fail(c, http.StatusBadRequest, 40055, "invalid report template")
+		return
+	}
+	if errors.Is(err, admin.ErrReportTemplateConflict) {
+		response.Fail(c, http.StatusConflict, 40912, "report template code conflict")
+		return
+	}
+	if err != nil {
+		response.Fail(c, http.StatusInternalServerError, 50052, "create report template failed")
+		return
+	}
+	response.OK(c, row)
+}
+
+func (h *AdminHandler) UpdateReportTemplate(c *gin.Context) {
+	adminID, ok := middleware.AdminIDFromContext(c)
+	if !ok {
+		response.Fail(c, http.StatusUnauthorized, 40101, "admin auth required")
+		return
+	}
+	id, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		response.Fail(c, http.StatusBadRequest, 40002, "invalid id")
+		return
+	}
+	var body admin.ReportTemplateWriteBody
+	if err := c.ShouldBindJSON(&body); err != nil {
+		response.Fail(c, http.StatusBadRequest, 40054, "invalid body")
+		return
+	}
+	row, err := h.Svc.UpdateReportTemplate(c.Request.Context(), adminID, id, body)
+	if errors.Is(err, admin.ErrReportTemplateNotFound) {
+		response.Fail(c, http.StatusNotFound, 40420, "report-template not found")
+		return
+	}
+	if errors.Is(err, admin.ErrInvalidReportTemplate) {
+		response.Fail(c, http.StatusBadRequest, 40055, "invalid report template")
+		return
+	}
+	if errors.Is(err, admin.ErrReportTemplateConflict) {
+		response.Fail(c, http.StatusConflict, 40912, "report template code conflict")
+		return
+	}
+	if err != nil {
+		response.Fail(c, http.StatusInternalServerError, 50053, "update report template failed")
+		return
+	}
+	response.OK(c, row)
+}
@@ -0,0 +1,110 @@
+package integration_test
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"golang.org/x/crypto/bcrypt"
+)
+
+func TestGrowthReportTemplateWrite(t *testing.T) {
+	r, pool := setupAPIPool(t)
+	ctx := context.Background()
+	tok := adminLogin(t, r, "admin", "change-me")
+
+	code := fmt.Sprintf("rt_w_%d", time.Now().UnixNano()%1_000_000)
+	body := map[string]any{"code": code, "title": "测试报告模板", "scene": "portrait", "active": true}
+	env, httpCode := doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/growth/report-templates", body, tok)
+	if httpCode != 200 || env.Code != 0 {
+		t.Fatalf("create http=%d code=%d msg=%s", httpCode, env.Code, env.Message)
+	}
+	var created struct {
+		ID     string `json:"id"`
+		Code   string `json:"code"`
+		Scene  string `json:"scene"`
+		Active bool   `json:"active"`
+	}
+	_ = json.Unmarshal(env.Data, &created)
+	if created.ID == "" || created.Code != code || created.Scene != "portrait" || !created.Active {
+		t.Fatalf("bad create %#v", created)
+	}
+	t.Cleanup(func() {
+		_, _ = pool.Exec(ctx, `DELETE FROM report_templates WHERE id=$1`, created.ID)
+	})
+
+	_, httpCode = doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/growth/report-templates", body, tok)
+	if httpCode != http.StatusConflict {
+		t.Fatalf("dup expected 409 got %d", httpCode)
+	}
+
+	env, httpCode = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/growth/report-templates", nil, tok)
+	if httpCode != 200 {
+		t.Fatalf("list %d", httpCode)
+	}
+	var list struct {
+		Items []struct {
+			Code   string `json:"code"`
+			Active bool   `json:"active"`
+		} `json:"items"`
+	}
+	_ = json.Unmarshal(env.Data, &list)
+	found := false
+	for _, it := range list.Items {
+		if it.Code == code && it.Active {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatalf("missing active in list %#v", list.Items)
+	}
+
+	body["active"] = false
+	body["title"] = "测试报告模板下架"
+	env, httpCode = doAdminJSON(t, r, http.MethodPut, "/api/v1/admin/growth/report-templates/"+created.ID, body, tok)
+	if httpCode != 200 {
+		t.Fatalf("update %d", httpCode)
+	}
+	var updated struct {
+		Active bool   `json:"active"`
+		Title  string `json:"title"`
+	}
+	_ = json.Unmarshal(env.Data, &updated)
+	if updated.Active || updated.Title != "测试报告模板下架" {
+		t.Fatalf("bad update %#v", updated)
+	}
+
+	var n int
+	_ = pool.QueryRow(ctx, `
+		SELECT COUNT(*) FROM admin_audit_logs
+		WHERE action IN ('growth.report_template.create','growth.report_template.update') AND target_id=$1`,
+		created.ID).Scan(&n)
+	if n < 2 {
+		t.Fatalf("audit %d", n)
+	}
+
+	limitedRoleID := uuid.New()
+	_, _ = pool.Exec(ctx, `INSERT INTO admin_roles(id, name, system) VALUES ($1,$2,false)`,
+		limitedRoleID, "rt_ro_"+limitedRoleID.String()[:8])
+	_, _ = pool.Exec(ctx, `INSERT INTO admin_role_permissions(role_id, code) VALUES ($1,'admin.growth.read')`, limitedRoleID)
+	hash, _ := bcrypt.GenerateFromPassword([]byte("ro-pass"), bcrypt.DefaultCost)
+	roUser := fmt.Sprintf("rtro_%d", time.Now().UnixNano())
+	_, _ = pool.Exec(ctx, `INSERT INTO admin_accounts(username, password_hash, role_id) VALUES ($1,$2,$3)`,
+		roUser, string(hash), limitedRoleID)
+	t.Cleanup(func() {
+		_, _ = pool.Exec(ctx, `DELETE FROM admin_accounts WHERE username=$1`, roUser)
+		_, _ = pool.Exec(ctx, `DELETE FROM admin_roles WHERE id=$1`, limitedRoleID)
+	})
+	roTok := adminLogin(t, r, roUser, "ro-pass")
+	_, httpCode = doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/growth/report-templates", map[string]any{
+		"code": "x_ro", "title": "no", "scene": "portrait", "active": true,
+	}, roTok)
+	if httpCode != http.StatusForbidden {
+		t.Fatalf("expected 403 got %d", httpCode)
+	}
+}
@@ -0,0 +1,117 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+)
+
+// ReportTemplateWriteInput is create/update payload.
+type ReportTemplateWriteInput struct {
+	Code   string
+	Title  string
+	Scene  string
+	Active bool
+}
+
+// CreateReportTemplateWithAudit inserts and audits.
+func (r *AdminRepo) CreateReportTemplateWithAudit(
+	ctx context.Context, adminID uuid.UUID, in ReportTemplateWriteInput, meta json.RawMessage,
+) (*ReportTemplateRow, error) {
+	tx, err := r.Pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+	var row ReportTemplateRow
+	err = tx.QueryRow(ctx, `
+		INSERT INTO report_templates(code, title, scene, active, system)
+		VALUES ($1,$2,$3,$4,false)
+		RETURNING id, code, title, scene, active, system, updated_at`,
+		in.Code, in.Title, in.Scene, in.Active,
+	).Scan(&row.ID, &row.Code, &row.Title, &row.Scene, &row.Active, &row.System, &row.UpdatedAt)
+	if err != nil {
+		return nil, mapReportTemplateWriteErr(err)
+	}
+	if meta == nil {
+		meta = json.RawMessage(`{}`)
+	}
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO admin_audit_logs(admin_id, action, target_type, target_id, meta)
+		VALUES ($1,'growth.report_template.create','report_template',$2,$3)`,
+		adminID, row.ID.String(), meta,
+	); err != nil {
+		return nil, err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+	return &row, nil
+}
+
+// UpdateReportTemplateWithAudit updates and audits.
+func (r *AdminRepo) UpdateReportTemplateWithAudit(
+	ctx context.Context, adminID, id uuid.UUID, in ReportTemplateWriteInput, meta json.RawMessage,
+) (*ReportTemplateRow, error) {
+	tx, err := r.Pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+	var system bool
+	var oldCode string
+	err = tx.QueryRow(ctx, `SELECT system, code FROM report_templates WHERE id=$1`, id).Scan(&system, &oldCode)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, pgx.ErrNoRows
+	}
+	if err != nil {
+		return nil, err
+	}
+	code := in.Code
+	if system {
+		code = oldCode
+	}
+	var row ReportTemplateRow
+	err = tx.QueryRow(ctx, `
+		UPDATE report_templates
+		SET code=$2, title=$3, scene=$4, active=$5, updated_at=now()
+		WHERE id=$1
+		RETURNING id, code, title, scene, active, system, updated_at`,
+		id, code, in.Title, in.Scene, in.Active,
+	).Scan(&row.ID, &row.Code, &row.Title, &row.Scene, &row.Active, &row.System, &row.UpdatedAt)
+	if err != nil {
+		return nil, mapReportTemplateWriteErr(err)
+	}
+	if meta == nil {
+		meta = json.RawMessage(`{}`)
+	}
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO admin_audit_logs(admin_id, action, target_type, target_id, meta)
+		VALUES ($1,'growth.report_template.update','report_template',$2,$3)`,
+		adminID, id.String(), meta,
+	); err != nil {
+		return nil, err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+	return &row, nil
+}
+
+func mapReportTemplateWriteErr(err error) error {
+	var pgErr *pgconn.PgError
+	if errors.As(err, &pgErr) && pgErr.Code == "23505" {
+		return errString("report template code conflict")
+	}
+	return err
+}
+
+// ReportTemplateCodeConflict reports unique violation.
+func ReportTemplateCodeConflict(err error) bool {
+	return err != nil && strings.Contains(err.Error(), "report template code conflict")
+}
@@ -0,0 +1,77 @@
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"regexp"
+	"strings"
+	"unicode/utf8"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+
+	"github.com/yuxingu/digital-psychology/apps/api/internal/repository"
+)
+
+var (
+	ErrInvalidReportTemplate  = errors.New("invalid report template")
+	ErrReportTemplateConflict = errors.New("report template code conflict")
+	reportTemplateCodeRe      = regexp.MustCompile(`^[a-z][a-z0-9_]{1,62}$`)
+	reportTemplateSceneRe     = regexp.MustCompile(`^[a-z][a-z0-9_]{0,30}$`)
+)
+
+// ReportTemplateWriteBody is JSON for create/update.
+type ReportTemplateWriteBody struct {
+	Code   string `json:"code"`
+	Title  string `json:"title"`
+	Scene  string `json:"scene"`
+	Active bool   `json:"active"`
+}
+
+// CreateReportTemplate validates, inserts, audits.
+func (s *Service) CreateReportTemplate(ctx context.Context, adminID uuid.UUID, body ReportTemplateWriteBody) (*repository.ReportTemplateRow, error) {
+	in, err := normalizeReportTemplateWrite(body)
+	if err != nil {
+		return nil, err
+	}
+	meta, _ := json.Marshal(map[string]any{"code": in.Code, "scene": in.Scene, "active": in.Active})
+	row, err := s.Repo.CreateReportTemplateWithAudit(ctx, adminID, in, meta)
+	if repository.ReportTemplateCodeConflict(err) {
+		return nil, ErrReportTemplateConflict
+	}
+	return row, err
+}
+
+// UpdateReportTemplate validates, updates, audits.
+func (s *Service) UpdateReportTemplate(ctx context.Context, adminID, id uuid.UUID, body ReportTemplateWriteBody) (*repository.ReportTemplateRow, error) {
+	in, err := normalizeReportTemplateWrite(body)
+	if err != nil {
+		return nil, err
+	}
+	meta, _ := json.Marshal(map[string]any{"code": in.Code, "scene": in.Scene, "active": in.Active})
+	row, err := s.Repo.UpdateReportTemplateWithAudit(ctx, adminID, id, in, meta)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrReportTemplateNotFound
+	}
+	if repository.ReportTemplateCodeConflict(err) {
+		return nil, ErrReportTemplateConflict
+	}
+	return row, err
+}
+
+func normalizeReportTemplateWrite(body ReportTemplateWriteBody) (repository.ReportTemplateWriteInput, error) {
+	code := strings.TrimSpace(body.Code)
+	title := strings.TrimSpace(body.Title)
+	scene := strings.TrimSpace(body.Scene)
+	if !reportTemplateCodeRe.MatchString(code) {
+		return repository.ReportTemplateWriteInput{}, ErrInvalidReportTemplate
+	}
+	if !reportTemplateSceneRe.MatchString(scene) {
+		return repository.ReportTemplateWriteInput{}, ErrInvalidReportTemplate
+	}
+	if title == "" || utf8.RuneCountInString(title) > 128 {
+		return repository.ReportTemplateWriteInput{}, ErrInvalidReportTemplate
+	}
+	return repository.ReportTemplateWriteInput{Code: code, Title: title, Scene: scene, Active: body.Active}, nil
+}
@@ -0,0 +1,2 @@
+-- ECR-048 rollback marker (permission shared with ECR-047 — do not revoke growth.write)
+SELECT 1;
@@ -0,0 +1,7 @@
+-- ECR-048 GrowthInsights ReportTemplate write (reuse admin.growth.write)
+
+INSERT INTO admin_role_permissions(role_id, code)
+SELECT r.id, 'admin.growth.write'
+FROM admin_roles r
+WHERE r.name = 'super_admin'
+ON CONFLICT DO NOTHING;
@@ -0,0 +1,23 @@
+# Backend Design: ECR-048 ReportTemplate Write
+
+| Field | Value |
+|-------|-------|
+| ID | BD-2026-048 |
+| Status | **Closed** |
+| Coding | **Closed** |
+| Migration | `000057_ops_report_template_write` |
+
+## Boundary
+
+```text
+POST/PUT /api/v1/admin/growth/report-templates*
+Permission: admin.growth.write (reuse)
+Fields: code, title, scene, active
+system=true: code immutable
+Audit: growth.report_template.create|update
+No C-end route · no DELETE
+```
+
+## Out
+
+Funnel re-write · Prompt · soft-delete · auto ECR-049  
@@ -2,6 +2,8 @@

 ## 2026-08-13

+- **ECR-048 Closed：** ReportTemplate 薄写（复用 `admin.growth.write` POST/PUT · migration `000057` · 无新 C 端）· **Loop STOP** · 禁自动 ECR-049 · 无 Funnel/Prompt  
+- **ECR-048 Candidate Review Approved：** 首刀 = **ReportTemplate** 薄写（复用 `admin.growth.write`；编码占 `000057`）· Spec/Loop/Coding **未开** · Auth 草案 PENDING · **不得继承 047 Auth**  
 - **ECR-047 Freeze/Review → FROZEN WAIT：** push 齐平 `580f5ea` · 单刀授权硬边界 · **禁自动 ECR-048** · 下一刀须 Candidate Review  
 - **ECR-047 Authorized Closed：** Human `authorize ECR-047 Closed` · 接受本地 `1db5fcc`/`69cb996`/`000056` 为正式 Closed · **不含 push** · Loop STOP · 禁自动 ECR-048  
 - **ECR-047 Closed：** FunnelDefinition 薄写（`admin.growth.write` POST/PUT · migration `000056` · 无新 C 端）· **Loop STOP** · 禁自动 ECR-048 · 无 ReportTemplate  
@@ -0,0 +1,3 @@
+# CODE_REVIEW — ECR-048
+
+**Verdict:** Approve · ReportTemplate 薄写 only · 无 Funnel/Prompt/soft-delete · Closed 后 STOP · ECR-008 Live Promote 仍 BLOCKED
@@ -0,0 +1,18 @@
+ecr: ECR-048
+capability: GrowthInsights
+change:
+  type: additive
+breaking_change: false
+migration_required: true
+apis:
+  - method: POST
+    path: /api/v1/admin/growth/report-templates
+    change: added
+  - method: PUT
+    path: /api/v1/admin/growth/report-templates/{id}
+    change: added
+perms:
+  - code: admin.growth.write
+    change: reused
+migration: 000057_ops_report_template_write
+notes: no C-end route; Funnel out of scope
@@ -0,0 +1,20 @@
+# ECR-048
+
+**Title:** GrowthInsights · ReportTemplate 薄写面  
+**Status:** **Closed**（2026-08-13）  
+**Auth:** `ECR-048_WRITE_AUTHORIZATION.md` · Closed 后 STOP  
+
+## Change
+
+1. Spec `ops-report-template-write`  
+2. POST/PUT `/admin/growth/report-templates*` + `admin.growth.write` + 审计  
+3. 无新 C 端路由  
+4. Migration `000057` · OpenAPI · admin-h5  
+
+## Forbidden
+
+Funnel 再写 · Prompt 族 · soft-delete · 支付/UGC · 自动 ECR-049
+
+## Acceptance
+
+TEST_REPORT/ECR-048 · CODE_REVIEW Approve · Done · Closed.
@@ -0,0 +1,3 @@
+# HANDOFF — Architect → Engineer · ECR-048
+
+Auth Approved · Spec Ready · BD Approved · ReportTemplate ONLY · migration 000057 · Closed → STOP.
@@ -0,0 +1,4 @@
+# HANDOFF — Engineer → Reviewer · ECR-048
+
+TestGrowthReportTemplateWrite PASS · governance max 000057 · Ready Closed.  
+无 Funnel/Prompt · STOP · 禁自动 ECR-049.
@@ -0,0 +1,3 @@
+# PRODUCT_SPEC — ECR-048
+
+对齐 `ops-report-template-write.md` · **Closed**.
@@ -53,21 +53,21 @@
 - **本仓：** `ess_intake: strict` · Retro FAIL · 单 ECR Context  
 - **Ops foundation：** `docs/WAVE0/` · `.ai/domain/boundary-rules.md` · `glossary.yaml` · Loop: `docs/WAVE0/LOOP_AUTHORIZATION.md`  
 - ECR: main 线 ECR-006–016 Closed；Ops 扩展 ECR-013A/B · 017–040；分叉已固定为 `ECR-012-star` / `014-plan` / `015-code` / `016-insight`（见 TRACEABILITY）  
- **Next ECR / Max Migration：** **Next=`ECR-048`（禁自动开）** · **Max=`000056`**  
+- **Next ECR / Max Migration：** **Next=`ECR-049`（禁自动开）** · **Max=`000057`**  
 - **Write-Wave CMS：** 041–042 Closed · STOP  
 - **ExploreConfig：** ECR-043…046 Closed · 同构写面 **耗尽 · STOP** · Prompt/Knowledge/Chunk STOP  
- **GrowthInsights：** ECR-047 FunnelDefinition **Closed · Authorized · Pushed**（`580f5ea`）· **FROZEN WAIT** · 禁自动 ECR-048 · ReportTemplate/Prompt STOP  
+- **GrowthInsights：** ECR-047 Funnel · ECR-048 ReportTemplate **Closed** · **Loop STOP** · 禁自动 ECR-049  
 - **Release：** ECR-008 Live Promote **BLOCKED**（独立门禁 · 勿与 Write-Wave 混谈）  
 - EXP: （无）  
- STATE: `docs/STATE/`（含 ECR-041…047）  
+- STATE: `docs/STATE/`（含 ECR-041…048）  
 - TRACEABILITY: `docs/TRACEABILITY.md` · 门禁 `scripts/repo-governance-check.py`  
 - ADR: `.ai/adr/0007-ess-ai-dual-track.md`  
 - Product status: `.ai/product/p1-status.md`（**P1 Complete**）· `.ai/product/p2-status.md`（**P2 Complete**）  
- Active Spec: `account-auth` · `explore-test` · `home` · `star-profile` · `life-rhythm` · `input-compliance` · `ops-system` · `profile` · `ops-banner-write` · `ops-star-config-write` · `ops-rhythm-config-write` · `ops-image-card-deck-write` · `ops-scale-definition-write` · `ops-funnel-definition-write`  
+- Active Spec: `account-auth` · `explore-test` · `home` · `star-profile` · `life-rhythm` · `input-compliance` · `ops-system` · `profile` · `ops-banner-write` · `ops-star-config-write` · `ops-rhythm-config-write` · `ops-image-card-deck-write` · `ops-scale-definition-write` · `ops-funnel-definition-write` · `ops-report-template-write`  

 ## WIP（尚未单独 ECR）

- **FROZEN WAIT**（ECR-047 Freeze/Review 收口）· 下一刀须 `ECR-048 Candidate Review` + Human 单独授权 · **禁止** Spec→Code 直开  
+- （无 · ECR-048 Closed · Loop STOP）  
 - BD-2026-044 状态补丁：工作区可暂留 · **不**自动提交  

 ## Pointers
@@ -0,0 +1,7 @@
+# STATE — ECR-048
+
+| Status | **Closed** |
+| Spec | ops-report-template-write |
+| Migration | 000057_ops_report_template_write |
+| Closed | 2026-08-13 |
+| Next | STOP · ECR-049 禁自动开 |
@@ -0,0 +1,11 @@
+# TEST_REPORT — ECR-048 ReportTemplate Write
+
+**Commit:** (pending Close)
+
+```bash
+go test ./internal/integration/ -count=1 -run TestGrowthReportTemplateWrite
+python3 scripts/repo-governance-check.py
+```
+
+PASS · create · 409 · PUT 下架 · audit · 403  
+REPO GOVERNANCE: PASS · max 000057 · Next ECR-049（禁自动开）
@@ -4,8 +4,8 @@

 | Anchor | Value | Rule |
 |--------|-------|------|
-| **Next ECR** | `ECR-048` | **冻结：** 须重新 Candidate Review + Human 单独拍板；**禁止自动开刀** |
-| **Max Migration** | `000056` | 禁止凭记忆 |
+| **Next ECR** | `ECR-049` | **冻结：** 须重新 Candidate Review + Human 单独拍板；**禁止自动开刀** |
+| **Max Migration** | `000057` | 禁止凭记忆 |

 - ECR identity **全局唯一**（含已 Closed）；禁止同号双义。分叉只用 `ECR-NNN-suffix` / `ECR-NNNA`。  
 - Migration **6 位版本号唯一**。撞号修复见 `docs/MIGRATION_RENUMBER.md`。  
@@ -72,6 +72,7 @@
 | ECR-044 | ExploreConfig · RhythmConfig 薄写面 | **Closed** | Spec ops-rhythm-config-write · BD-2026-044 · migration **000053** · Closed 后 STOP · 禁自动 ECR-045 |
 | ECR-045 | ExploreConfig · ImageCardDeck 薄写面 | **Closed** | Spec ops-image-card-deck-write · BD-2026-045 · migration **000054** · Closed 后 STOP · 禁自动 ECR-046 · 无牌面编辑 |
 | ECR-046 | ExploreConfig · ScaleDefinition 元数据薄写 | **Closed** | Spec ops-scale-definition-write · BD-2026-046 · migration **000055** · status 仍 ECR-008 · Closed 后 STOP · 禁自动 ECR-047 |
-| ECR-047 | GrowthInsights · FunnelDefinition 薄写面 | **Closed · Authorized · Pushed · FROZEN WAIT** | Spec ops-funnel-definition-write · BD-2026-047 · migration **000056** · Human authorize · Freeze `ECR-047_FREEZE_REVIEW.md` · origin=`580f5ea` · **禁自动 ECR-048** |
+| ECR-047 | GrowthInsights · FunnelDefinition 薄写面 | **Closed · Authorized · Pushed · FROZEN WAIT** | Spec ops-funnel-definition-write · BD-2026-047 · migration **000056** · Human authorize · Freeze `ECR-047_FREEZE_REVIEW.md` · origin=`aa197b7` · **禁自动 ECR-048** |
+| ECR-048 | GrowthInsights · ReportTemplate 薄写面 | **Closed** | Spec ops-report-template-write · BD-2026-048 · migration **000057** · Closed 后 STOP · 禁自动 ECR-049 |

 > **Migration：** 合并后 `000015`–`000023` 曾撞号，已重编号至 `000050`。以 `apps/api/migrations/` 与 `docs/MIGRATION_RENUMBER.md` 为准（文档中旧号引用可能滞后）。
@@ -0,0 +1,70 @@
+# ECR-048 Candidate Review — GrowthInsights · ReportTemplate
+
+> **RESOLVED 2026-08-13（Human: Candidate Review → Auth/Spec/开码 → Closed）：**  
+> 首刀 = **ReportTemplate 薄写** · **Closed** · Loop **STOP** · 禁自动 ECR-049  
+
+**Date:** 2026-08-13  
+**Mode:** Candidate Review **Approved** · Spec **Closed** · Coding **Closed**  
+**Anchors:** Next=`ECR-049`（禁自动开）· Max Migration=`000057`
+
+## 锁定现状
+
+| 项 | 状态 |
+|----|------|
+| ECR-047 | FunnelDefinition **Closed · Authorized · Pushed** · Loop **STOP** |
+| ECR-038 | ReportTemplate **只读** Closed |
+| `admin.growth.write` | **已存在**（047 授予） |
+| Continuous Loop | **STOP**（047 Auth 耗尽 · **不得继承**） |
+| 硬 STOP | 支付 / UGC / soft-delete / Crisis·Handoff / Prompt / Knowledge / Chunk |
+| ECR-008 Live Promote | **BLOCKED** |
+
+## 八问（Candidate Review 强制）
+
+| # | 问 | 答 |
+|---|----|----|
+| 1 | 做什么能力？ | **ReportTemplate 薄写**（`code` / `title` / `scene` / `active`） |
+| 2 | 为什么现在做？ | GrowthInsights 只读目录写面剩 ReportTemplate；与 047 Funnel **同构**，可验证 `growth.write` 复用 |
+| 3 | 是否属当前 Write-Wave？ | **GrowthInsights 写面续刀**（非 CMS / 非 ExploreConfig / 非 AICore） |
+| 4 | 风险等级？ | **低–中**：目录/开关；无新 C 端路由；不改模型行为 |
+| 5 | 是否需要新权限？ | **否** · 复用 `admin.growth.write`（047 已授） |
+| 6 | 是否需要 migration？ | **是** · 占 **000057**（幂等确认 growth.write；与 053–055 同模式） |
+| 7 | 是否触碰硬 STOP？ | **否**（排除 Prompt/Knowledge/Chunk/支付/UGC/soft-delete/Crisis） |
+| 8 | 是否值得继续？ | **是** · 对称收口 GrowthInsights 两表写面；Closed 后仍须 STOP |
+
+## 概念候选
+
+| 优先 | 概念 | 备注 |
+|------|------|------|
+| **★ 决议首刀** | **ReportTemplate** | 表 `report_templates`；复用 growth.write |
+| ✕ 排除 | Funnel 再写 | 047 Closed · 勿回流 |
+| ✕ 排除 | SystemPrompt / Knowledge / Chunk | **硬 STOP** |
+| ✕ 排除 | CMS / Explore / 题干 / Live Promote | 禁 |
+
+## 决议
+
+**ECR-048 = GrowthInsights · ReportTemplate 薄写面**
+
+拟议（Spec 细化）：
+
+- 复用表 `report_templates`  
+- 复用 `admin.growth.write`  
+- Admin `POST/PUT /admin/growth/report-templates*`  
+- 字段仅 `code` · `title` · `scene` · `active`  
+- `system=true`：禁止改 `code` / 物理删  
+- 审计 `growth.report_template.create|update`  
+- **无**新 C 端路由  
+- Migration：编码时占 **000057**  
+- Continuous Loop：**仅**单独 Auth 且 **仅限 ECR-048**；Closed → STOP · **禁自动 ECR-049**  
+
+## 硬 STOP
+
+Prompt / Knowledge / Chunk · 支付 · UGC · soft-delete · Crisis/Handoff · 题干 · Funnel 再写 · ECR-008 Live Promote 解禁 · 继承 047 Auth · 自动下一刀  
+
+## 下一步（仍不写码）
+
+1. ~~ECR-048 Candidate Review approve~~ **Done · ReportTemplate**  
+2. Human：批准 **ECR-048 专用** Write Authorization（例：`批准 ECR-048 专用 Write Auth → Spec → 开码`）  
+3. Spec `ops-report-template-write` · ECR · BD  
+4. 开码口令后才改 `apps/`  
+
+**本回合交付 = Candidate Review RESOLVED；无 Spec · 无 Auth Loop · 无 `apps/`。**
@@ -0,0 +1,27 @@
+# GrowthInsights Write Authorization — ECR-048 only
+
+| Field | Value |
+|-------|-------|
+| Date | 2026-08-13 |
+| Authorizer | Human |
+| Status | **Approved · ECR-048 Closed · Loop STOP** |
+| Scope | **ReportTemplate 薄写面 ONLY** |
+| Continuous Loop | **Finished · STOP** |
+| After Closed | **STOP** · 禁止自动 ECR-049 |
+
+## Human 拍板（2026-08-13）
+
+1. Candidate Review = ReportTemplate  
+2. Write Auth → Spec → 开码  
+3. 复用 `admin.growth.write` · 字段 code/title/scene/active · 无新 C 端路由  
+4. Continuous Loop **仅限 ECR-048** · **不得继承 047 Auth**
+
+## Hard STOP
+
+Funnel 再写 · Prompt / Knowledge / Chunk · 支付 · UGC · soft-delete · Crisis/Handoff · Closed 后自动下一刀 · ECR-008 Live Promote 解禁
+
+## Refs
+
+Candidate Review: `ECR-048-CANDIDATE_REVIEW.md`  
+Spec: `.ai/product/feature-spec/ops-report-template-write.md`  
+ECR: `docs/ECR/ECR-048-report-template-write.md`
@@ -1408,6 +1408,21 @@ paths:
          description: Unauthorized
        '403':
          description: Forbidden
+    post:
+      tags: [admin]
+      summary: Create ReportTemplate
+      description: Requires admin.growth.write · ECR-048 · code/title/scene/active only
+      responses:
+        '200':
+          description: OK
+        '400':
+          description: Invalid
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden
+        '409':
+          description: Code conflict

  /api/v1/admin/growth/report-templates/{id}:
    get:
@@ -1423,6 +1438,26 @@ paths:
          description: OK
        '404':
          description: Not found
+    put:
+      tags: [admin]
+      summary: Update ReportTemplate
+      description: Requires admin.growth.write · deactivate via active=false · ECR-048
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        '200':
+          description: OK
+        '400':
+          description: Invalid
+        '403':
+          description: Forbidden
+        '404':
+          description: Not found
+        '409':
+          description: Code conflict

  /api/v1/admin/analytics/funnel-definitions:
    get: