manage-api-admin

name	manage-api-admin
description	新增或修改 Cat 项目的管理端 API（`/api/admin/<context>/<action>`）。用于 `api_admin` 计划层、admin 列表/详情/写操作的后端实现。

Manage Admin API

管理端 API 路径前缀 /api/admin/，DSL tag 使用 Admin<Context>，生成的 Request 模块为 CatWeb.AdminCatalogRequest 这类命名。

本 skill 只负责管理端 API。面向用户/前端的 /api/<context>/<action> 接口使用 manage-api。

Task Progress:
- [ ] Step 1: DSL 定义（admin api + schema）
- [ ] Step 2: 注册模块与 Admin Tag（如果是新 context）
- [ ] Step 3: 生成产物（mix cat.gen.spec）
- [ ] Step 4: 添加 admin 路由（:admin_api pipeline）
- [ ] Step 5: 实现 admin 控制器 + JSON 渲染
- [ ] Step 6: 更新 docs/prds/{domain}/features/{feature}.md 的 `## api_admin`

---

Step 1: DSL 定义

在 lib/cat_api_spec/<context>.ex 中定义 admin API 和 schema。admin API 可以和前端 API 放在同一个 DSL 模块里，通过 /api/admin/... 路径和 Admin<Context> tag 区分。

DSL 语法可直接复用前台 API 的参考：manage-api/dsl-reference.md。

管理端列表响应 schema 同样优先使用分页宏：

• 标准 {items, pagination} 结构优先使用 paginated_schema
• 标准 {items, cursor_pagination} 结构优先使用 cursor_paginated_schema
• 如果还需要 filters 等附加字段，继续在宏后追加 do ... end

defmodule CatApiSpec.Catalog do
  use CatApiSpec.Schema
  use CatApiSpec.Api

  api "/api/admin/catalog/list_classes" do
    method(:get)
    operation(tags: ["AdminCatalog"], summary: "管理端列出类型", description: "管理端列出类型")
    parameter(:page, :integer, :query, description: "页码")
    parameter(:page_size, :integer, :query, description: "每页条目数")
    response(200, "AdminListClassesResp")
  end

  paginated_schema "AdminListClassesResp", "AdminClassItem",
    items: [description: "类型列表"] do
    field :filters, :object, description: "筛选条件", nullable: true
  end
end

约定：

• 路径：/api/admin/<context>/<action>
• Tag：AdminCatalog、AdminPosts 等 Admin<Context> 格式
• Request 模块：CatWeb.Admin<Context>Request
• 资源 id：API/JSON 中使用 string 类型

---

Step 2: 注册模块与 Admin Tag

如果是新的 context 模块，需在 lib/cat_api_spec.ex 中注册：

1. 添加 alias：alias CatApiSpec.NewContext
2. 加入 @all_modules 列表
3. 添加 Admin Tag

lib/cat_api_spec.ex 当前有 build_spec(:all)、build_spec(:api)、build_spec(:admin) 三套独立的 tags 列表。新增 Admin Tag 时必须同步：

API 类型	build_spec(:all)	build_spec(:api)	build_spec(:admin)
Admin API Tag（如 AdminNewContext）	要加	不加	要加
前端 API Tag（如 NewContext）	转 manage-api	转 manage-api	转 manage-api

示例：

alias CatApiSpec.{Accounts, Catalog, Misc, Subjects, Rankings, NewContext}

@all_modules [Accounts, Catalog, Misc, Subjects, Rankings, NewContext]

def build_spec(:all) do
  %OpenApi{
    tags: [
      # ...existing tags...
      %Tag{name: "AdminNewContext", description: "管理端描述"}
    ]
  }
end

def build_spec(:admin) do
  %OpenApi{
    tags: [
      # ...existing tags...
      %Tag{name: "AdminNewContext", description: "管理端描述"}
    ]
  }
end

已有模块中添加 API 不需要添加 alias 或修改 @all_modules，但新增 Tag 仍要按上表同步。

---

Step 3: 生成产物

mix cat.gen.spec

生成三类文件：

• lib/cat_web/generated/admin_<tag>_request.ex — Request 验证模块
• lib/cat_web/schemas/<name>.gen.ex — Schema Struct
• openapi/openapi.yaml — OpenAPI 文档

---

Step 4: 添加 admin 路由

在 lib/cat_web/router.ex 的 admin scope 中添加路由。必须使用 :admin_api pipeline；它包含 require_superuser。

scope "/api/admin", CatWeb.API.Admin do
  pipe_through [:admin_api]

  get "/catalog/list_classes", CatalogController, :list_classes
  post "/catalog/create_class", CatalogController, :create_class
end

HTTP 方法规则：读操作用 get，写操作用 post。

不要把 admin 路由放进 scope "/api", CatWeb.API，也不要使用 :api / :public_api pipeline。

---

Step 5: 实现 admin 控制器 + JSON 渲染

Admin 控制器

路径：lib/cat_web/controllers/api/admin/<context>_controller.ex 模块：CatWeb.API.Admin.<Context>Controller

defmodule CatWeb.API.Admin.CatalogController do
  use CatWeb, :api_controller

  alias CatWeb.AdminCatalogRequest
  alias Cat.Catalog

  def list_classes(conn, _params) do
    with {:ok, conn} <-
           cast_and_validate(conn, AdminCatalogRequest.operation(:get, :list_classes)) do
      %{entries: entries, metadata: metadata} = Catalog.admin_list_classes(conn.params)

      render(conn, :list_classes, classes: entries, metadata: metadata)
    end
  end
end

cast_and_validate/2 后，conn.params 和 conn.body_params 会被替换为 atom 键；控制器读取参数时优先使用 params[:key] / conn.params[:key]，并把已校验的 conn.params 直接传给 Context。只有在 DSL 校验没有覆盖某些类型转换或需要兼容原始参数时，才额外写 normalize_params/1。

Admin JSON 模块

路径：lib/cat_web/controllers/api/admin/<context>_json.ex 模块：CatWeb.API.Admin.<Context>JSON

defmodule CatWeb.API.Admin.CatalogJSON do
  import CatWeb.API.ResponseHelper

  alias CatWeb.Schemas.Class

  def list_classes(%{classes: classes, metadata: metadata}) do
    items = Enum.map(classes, &build_class/1)
    paginated(items, metadata)
  end

  defp build_class(class) do
    %Class{
      id: class.id,
      idname: class.idname,
      label: class.label
    }
  end
end

Context 层

Context 层通常实现 admin_list_xxx、admin_get_xxx 等函数。列表接口使用 Cat.Paginator 做分页，分页与筛选模式详见 references/api-admin-patterns.md。

def admin_list_classes(params) do
  Class
  |> maybe_filter_by_idname(params[:idname])
  |> maybe_filter_by_label(params[:label])
  |> order_by(desc: :is_primary, asc: :label)
  |> Paginator.paginate(params)
end

---

Step 6: PRD 文档

在 docs/prds/{domain}/features/{feature}.md 的 ## api_admin 小节中记录管理端 API 设计。PRD 已按 domain + feature 分层，不再创建或更新 docs/prds/{domain}/api_admin.md 这种 aspect 文件。

选择 feature 的规则：

1. 先阅读 docs/prds/{domain}/overview.md 的 Feature 列表和 features/ 下已有文档。
2. 如果该管理端 API 服务某个已有业务能力，更新对应 feature 的 ## api_admin。
3. 如果 API 引入新的可复制业务能力包，先按 manage-prd 的规则创建 / 更新 feature，并同步 overview.md 的 Feature 列表。
4. 如果只是增加筛选、列表列、审核动作或状态切换，通常并入现有 feature，不单独创建 feature。
5. 如果 API 变更影响共享实体、字段或状态，必要时同步更新 domain data_model.md，并让 feature ## data_model 保持自包含。

---

文件对照表

文件	Admin API
DSL 定义	lib/cat_api_spec/<ctx>.ex，路径 /api/admin/...
Request 模块	generated/admin_<ctx>_request.ex
路由	scope "/api/admin" + pipe_through [:admin_api]
控制器	controllers/api/admin/<ctx>_controller.ex
JSON 渲染	controllers/api/admin/<ctx>_json.ex
PRD	docs/prds/{domain}/features/{feature}.md 的 ## api_admin