games-development-ai/contracts/api-schemas/project.yaml

openapi: 3.0.3
# 契约 #1 API | 模块：project（黄金模板）| owner：WS1 lead 主笔，全员 review
# 端：/app-api（产品端 game-studio，用户 Token+DataPermission） /admin-api（管理端 game-admin，RBAC）；前缀由 yudao 框架按 controller.app/admin 包名自动添加
# 错误码段：project = 1-100-***-***
# 响应统一 Yudao CommonResult 信封：{ code, data, msg }；code=0 成功
info:
  title: 绘境AI project 模块 API
  version: 1.0.0
  description: 游戏项目 CRUD / 状态机 / 版本 / 草稿 / 发布编排 / 审核 / 专区。前端据此 vite-plugin-mock 自动生成 mock。

servers:
  - url: http://localhost:48080
    description: 本地（Swagger/Knife4j http://localhost:48080/doc.html）

paths:
  /app-api/project/my:
    get:
      tags: [app-project]
      summary: 我的项目列表（创作者只见自己数据）
      parameters:
        - { name: status, in: query, required: false, schema: { type: integer }, description: 按状态机筛选 }
        - { name: pageNo, in: query, required: false, schema: { type: integer, default: 1 } }
        - { name: pageSize, in: query, required: false, schema: { type: integer, default: 10 } }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommonResultProjectPage' }

  /app-api/project:
    post:
      tags: [app-project]
      summary: 创建项目（初始 status=0 草稿）
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProjectCreateReqVO' }
      responses:
        '200':
          description: 返回新建项目 ID
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommonResultLong' }

  /app-api/project/{id}:
    get:
      tags: [app-project]
      summary: 项目详情
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommonResultProject' }

  /app-api/project/{id}/draft:
    put:
      tags: [app-project]
      summary: 保存草稿（仅 status=0 可改；标题/简介/封面/标签/适龄）
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProjectDraftReqVO' }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommonResultBoolean' }

  /app-api/project/{id}/publish:
    post:
      tags: [app-project]
      summary: 提交发布（发布前检查清单 7 门禁 → 进审核 BPM；统一发布编排 compliance→runtime→feed 失败回滚 ←G6）
      description: 服务端校验状态机（仅 status=0 可提交），通过发布前检查后置 status=1 审核中。
      parameters:
        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ProjectPublishReqVO' }
      responses:
        '200':
          description: 成功（含发布前检查项结果）
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommonResultBoolean' }

  /admin-api/project/review/page:
    get:
      tags: [admin-project]
      summary: 审核队列（管理端 RBAC）
      parameters:
        - { name: status, in: query, required: false, schema: { type: integer }, description: 默认取 status=1 审核中 }
        - { name: pageNo, in: query, required: false, schema: { type: integer, default: 1 } }
        - { name: pageSize, in: query, required: false, schema: { type: integer, default: 10 } }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommonResultProjectPage' }

  /admin-api/project/review:
    post:
      tags: [admin-project]
      summary: 审核决策（通过/拒绝/下架；锁风门 Gate 二态聚合）
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ReviewReqVO' }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CommonResultBoolean' }

components:
  schemas:
    # ---- Yudao CommonResult 信封 ----
    CommonResultBoolean:
      type: object
      properties:
        code: { type: integer, description: '0=成功，非0=错误码 1-100-***-***' }
        data: { type: boolean }
        msg:  { type: string }
    CommonResultLong:
      type: object
      properties:
        code: { type: integer }
        data: { type: integer, format: int64, description: 新建项目 ID }
        msg:  { type: string }
    CommonResultProject:
      type: object
      properties:
        code: { type: integer }
        data: { $ref: '#/components/schemas/ProjectRespVO' }
        msg:  { type: string }
    CommonResultProjectPage:
      type: object
      properties:
        code: { type: integer }
        data:
          type: object
          properties:
            list:  { type: array, items: { $ref: '#/components/schemas/ProjectRespVO' } }
            total: { type: integer, format: int64 }
        msg:  { type: string }

    # ---- 请求/响应 VO ----
    ProjectCreateReqVO:
      type: object
      required: [title, templateId]
      properties:
        title:      { type: string, maxLength: 60, description: 标题 }
        templateId: { type: string, description: 玩法模板 ID }
    ProjectDraftReqVO:
      type: object
      properties:
        title:     { type: string, maxLength: 60 }
        summary:   { type: string, maxLength: 500 }
        coverUrl:  { type: string }
        tags:      { type: array, items: { type: string }, maxItems: 10 }
        ageRating: { type: string, enum: [all, '8+', '12+', '16+'] }
    ProjectPublishReqVO:
      type: object
      required: [versionId, launchZoneId]
      properties:
        versionId:    { type: integer, format: int64, description: 发布的版本 ID }
        launchZoneId: { type: integer, format: int64, description: 发布去向专区（launchZone ←G1） }
    ReviewReqVO:
      type: object
      required: [gameId, versionId, decision]
      properties:
        gameId:    { type: integer, format: int64 }
        versionId: { type: integer, format: int64 }
        decision:  { type: integer, enum: [1, 2, 3], description: '1通过 2拒绝 3下架' }
        reason:    { type: string, maxLength: 500, description: 拒绝/下架理由（回填创作者） }
    ProjectRespVO:
      type: object
      properties:
        id:              { type: integer, format: int64 }
        title:           { type: string }
        summary:         { type: string }
        coverUrl:        { type: string }
        tags:            { type: array, items: { type: string } }
        templateId:      { type: string }
        ageRating:       { type: string }
        status:          { type: integer, description: '0草稿 1审核中 2已通过 3已拒绝 4已发布 5已下架 6已封禁' }
        currentVersionId: { type: integer, format: int64 }
        launchZoneId:    { type: integer, format: int64 }
        featured:        { type: boolean }
        playCount:       { type: integer, format: int64 }
        likeCount:       { type: integer, format: int64 }
        createTime:      { type: string, format: date-time }