openapi.v1.yaml

openapi: 3.0.3
info:
  title: 分布式配置文档服务 管理面 API v1
  version: 1.0.0
  description: |
    管理面 REST 契约，与 docs/design-v2.md §5.3 一致。
    数据面为 gRPC，正式契约见 proto/config.v1.proto。
    所有管理写操作应携带 Idempotency-Key 请求头（幂等，见 design-v2 §4.2）。
  contact:
    name: Defing Config Service
servers:
  - url: http://localhost:8384
security:
  - AdminSession: []
paths:
  /api/v1/login:
    post:
      summary: 登录（单一管理员会话 I7；第二个登录返回 409）
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LoginRequest' }
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/LoginResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '409': { $ref: '#/components/responses/SessionInUse' }
  /api/v1/logout:
    post:
      summary: 登出（使当前会话失效）
      responses:
        '204': { description: 成功 }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/heartbeat:
    post:
      summary: 会话心跳续期（默认每 5min）
      responses:
        '200':
          description: 续期成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  expires_at: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /api/v1/me/password:
    post:
      summary: 自助修改自己的密码（全局管理员 / 项目管理员通用；校验当前密码，改后全部旧会话失效需重新登录）
      security:
        - AdminSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [current_password, new_password]
              properties:
                current_password: { type: string, description: 当前密码（验证本人；错误返回 401 ERR_BAD_CREDENTIALS） }
                new_password: { type: string, minLength: 6, description: 新密码（≥6 位） }
      responses:
        '200':
          description: 已修改（当前会话一并失效）
        '401': { $ref: '#/components/responses/Unauthorized' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /api/v1/projects:
    get:
      summary: 项目列表
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Project' }
    post:
      summary: 创建项目（name 全局唯一；可选 clone_from 克隆源项目已发布结构）
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string, maxLength: 128 }
                clone_from:
                  type: string
                  description: 可选：从该项目克隆已发布结构（新项目结构直接以 v1 落地；不传/空串 = 空结构普通创建）
      responses:
        '200':
          description: 已创建（默认创建 dev/test/prod 分支）
          content:
            application/json:
              schema:
                type: object
                required: [id, branches]
                properties:
                  id: { type: string }
                  branches:
                    type: array
                    items: { type: string }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /api/v1/projects/{p}:
    get:
      summary: 项目详情
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Project' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      summary: 删除项目（需确认 force=true 参数）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { name: force, in: query, schema: { type: boolean, default: false } }
      responses:
        '204': { description: 成功 }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/projects/{p}/branches:
    get:
      summary: 分支列表（含活动版本号）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/Branch' }
    post:
      summary: 新建分支（继承当前已发布结构与活动版本值）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string, pattern: '^[a-z0-9][a-z0-9-]{0,63}$' }
      responses:
        '201':
          description: 已创建
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Branch' }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/projects/{p}/branches/{b}:
    get:
      summary: 分支详情
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Branch' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      summary: 删除分支（活动版本为 1 且无草稿时可删）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
      responses:
        '204': { description: 成功 }
        '409': { $ref: '#/components/responses/Conflict' }
  /api/v1/projects/{p}/structure:
    get:
      summary: 查询已发布结构（当前生效版本）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                required: [version, groups]
                properties:
                  version: { type: integer, format: int64, description: 当前已发布结构版本 }
                  groups:
                    type: array
                    items: { $ref: '#/components/schemas/GroupDef' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/projects/{p}/structure-draft:
    get:
      summary: 读取结构草稿（含基础版本）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StructureDraft' }
    put:
      summary: 整体替换结构草稿（base_version 必须匹配当前基础版本，否则 409）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/StructureDraft' }
      responses:
        '200':
          description: 已保存
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StructureDraft' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /api/v1/projects/{p}/structure-draft/publish:
    post:
      summary: 发布结构（对全部分支同时生效，所有分支版本号推进）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PublishRequest' }
      responses:
        '200':
          description: 已发布
          content:
            application/json:
              schema:
                type: object
                required: [structure_version, affected_branches]
                properties:
                  structure_version: { type: integer, format: int64 }
                  affected_branches:
                    type: array
                    items:
                      type: object
                      properties:
                        branch: { type: string }
                        version: { type: integer, format: int64 }
        '422': { $ref: '#/components/responses/PublishBlocked' }
  /api/v1/projects/{p}/branches/{b}/draft:
    get:
      summary: 读取分支值草稿（待发布变更）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DraftBody' }
    put:
      summary: 更新值草稿（updates 覆盖写入；deletes 按 "group/key" 移除）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DraftBody' }
      responses:
        '200':
          description: 已保存
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DraftBody' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /api/v1/projects/{p}/branches/{b}/publish:
    post:
      summary: 发布分支版本（原子；幂等键防重复）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PublishRequest' }
      responses:
        '200':
          description: 已发布
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PublishResult' }
        '409': { $ref: '#/components/responses/NoDraft' }
        '422': { $ref: '#/components/responses/PublishBlocked' }
  /api/v1/projects/{p}/branches/{b}/versions:
    get:
      summary: 版本历史
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
        - { name: limit, in: query, schema: { type: integer, maximum: 200, default: 50 } }
        - { name: before, in: query, schema: { type: integer, format: int64 } }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions:
                    type: array
                    items: { $ref: '#/components/schemas/Version' }
  /api/v1/projects/{p}/branches/{b}/config:
    get:
      summary: 管理面查看配置（secret 默认掩码；reveal=true 需会话+审计）
      security:
        - AdminSession: []
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
        - { name: reveal, in: query, schema: { type: boolean, default: false } }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ConfigSnapshot' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/projects/{p}/branches/{b}/rollback:
    post:
      summary: 回滚到指定版本（以旧内容创建新版本）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RollbackRequest' }
      responses:
        '200':
          description: 已回滚
          content:
            application/json:
              schema:
                type: object
                required: [new_version]
                properties:
                  new_version: { type: integer, format: int64 }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/projects/{p}/branches/{b}/gray-publish:
    post:
      summary: 灰度发布（固化草稿 → 灰度快照 + 灰度规则；稳定版不动）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/GrayPublishRequest' }
      responses:
        '200':
          description: 已发布灰度
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GrayPublishResult' }
        '409': { $ref: '#/components/responses/NoDraft' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /api/v1/projects/{p}/branches/{b}/gray-promote:
    post:
      summary: 灰度转正（灰度内容 → 新稳定版；清灰度）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/GrayCommentRequest' }
      responses:
        '200':
          description: 已转正
          content:
            application/json:
              schema:
                type: object
                required: [active_version]
                properties:
                  active_version: { type: integer, format: int64 }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /api/v1/projects/{p}/branches/{b}/gray-abort:
    post:
      summary: 灰度下量/回滚（摘灰度指针，客户端回落稳定版）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/GrayCommentRequest' }
      responses:
        '200':
          description: 已下量
          content:
            application/json:
              schema:
                type: object
                required: [fallback_version]
                properties:
                  fallback_version: { type: integer, format: int64 }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /api/v1/projects/{p}/branches/{b}/gray-status:
    get:
      summary: 灰度状态（gray_active/gray_seq/gray_rule/active_version）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GrayStatus' }
        '404': { $ref: '#/components/responses/NotFound' }
  /api/v1/projects/{p}/diff:
    get:
      summary: 分支间值对比（同结构按 key）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { name: branch_a, in: query, required: true, schema: { type: string } }
        - { name: branch_b, in: query, required: true, schema: { type: string } }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DiffResult' }
  /api/v1/projects/{p}/promote:
    post:
      summary: 值提升（写入目标分支值草稿；默认不覆盖目标已改项）
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PromoteRequest' }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PromoteResult' }
  /api/v1/shared:
    get:
      summary: 共享项列表
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/SharedItem' }
    post:
      summary: 新建共享项（写共享草稿）
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SharedItem' }
      responses:
        '201': { $ref: '#/components/responses/Created' }
  /api/v1/shared-draft:
    get:
      summary: 共享草稿列表（secret 值掩码）
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/SharedItem' }
    put:
      summary: 更新共享草稿
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SharedItem' }
      responses:
        '200': { description: 已保存 }
  /api/v1/shared/publish:
    post:
      summary: 发布共享项（auto 模式自动级联受影响项目；返回受影响列表）
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PublishRequest' }
      responses:
        '200':
          description: 已发布
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SharedPublishResult' }
        '422': { $ref: '#/components/responses/PublishBlocked' }
  /api/v1/shared/{key}:
    delete:
      summary: 删除已发布共享项（连同草稿）；被项目结构引用 → 409 Conflict
      parameters:
        - { name: key, in: path, required: true, schema: { type: string } }
      responses:
        '204': { description: 已删除 }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /api/v1/shared-draft/{key}:
    delete:
      summary: 删除共享草稿（幂等）
      parameters:
        - { name: key, in: path, required: true, schema: { type: string } }
      responses:
        '204': { description: 已删除 }
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /api/v1/audit:
    get:
      summary: 审计查询
      parameters:
        - { name: action, in: query, schema: { type: string } }
        - { name: since, in: query, schema: { type: string, format: date-time } }
        - { name: limit, in: query, schema: { type: integer, default: 100, maximum: 1000 } }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/AuditEntry' }
  /api/v1/cluster/join:
    post:
      summary: 新节点加入（加为 learner；经 leader）
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/JoinRequest' }
      responses:
        '200':
          description: 已受理，返回成员表
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MemberList' }
  /api/v1/cluster/promote:
    post:
      summary: 将 learner 提升为 voter
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [node_id]
              properties:
                node_id: { type: string }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MemberList' }
  /api/v1/cluster/remove:
    post:
      summary: 移除节点（先降 learner 再移除）
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [node_id]
              properties:
                node_id: { type: string }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MemberList' }
  /api/v1/cluster/members:
    get:
      summary: 集群成员表（含节点地址/角色；SDK 端点池刷新用）
      security: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  node_id: { type: string, nullable: true }
                  current_leader: { type: string, nullable: true }
                  state: { type: string }
                  members:
                    type: array
                    items: { $ref: '#/components/schemas/Member' }
  /api/v1/admin/rotate-master-key:
    post:
      summary: 轮换主密钥（KeyRing 追加 + 环文件持久化；DEK 重包由后台任务执行）
      security:
        - AdminSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [new_key]
              properties:
                new_key: { type: string, description: base64 32B 新 KEK }
      responses:
        '200':
          description: 已轮换（返回 generation 与环条目数）
        '422': { $ref: '#/components/responses/ValidationFailed' }
  /api/v1/admin/force-logout:
    post:
      summary: 强制下线管理员会话（CLI `dsh admin force-logout` 兜底，I7）
      security:
        - AdminSession: []
      responses:
        '200': { description: 已下线 }
  /api/v1/admin/set-password:
    post:
      summary: 修改管理员密码（哈希落状态机，集群一致；旧会话失效）
      security:
        - AdminSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [password]
              properties:
                password: { type: string, minLength: 6 }
      responses:
        '200': { description: 已修改 }
  /api/v1/admin/snapshot:
    get:
      summary: 备份快照（状态机 KV dump；`dsh admin snapshot --out` 存盘）
      security:
        - AdminSession: []
      responses:
        '200':
          description: 状态机 dump（{version, kind, entries:[{key,value}]}）
  /api/v1/admin/retention-status:
    get:
      summary: 保留策略状态（--version-retention / --audit-retention 配置 + 计数）
      security:
        - AdminSession: []
      responses:
        '200':
          description: 保留策略与当前计数
  /healthz:
    get:
      summary: 存活检查
      security: []
      responses:
        '200':
          description: 存活
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, enum: [ok] }
  /readyz:
    get:
      summary: 就绪检查（已加入集群且可服务）
      security: []
      responses:
        '200':
          description: 就绪
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, enum: [ok] }
        '503':
          description: 未就绪
  /metrics:
    get:
      summary: Prometheus 指标文本
      security: []
      responses:
        '200':
          description: 指标文本（text/plain; version=0.0.4）
  /admin:
    get:
      summary: 内嵌 Admin UI
      security: []
      responses:
        '200':
          description: HTML 页面
  /v1/projects/{p}/branches/{b}/snapshot:
    get:
      summary: SDK 数据面快照（纯值输出；secret 恒脱敏为掩码 "***"，面向应用经 TLS 拉取）
      security: []
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ConfigSnapshot' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/projects/{p}/branches/{b}/watch:
    get:
      summary: SDK 数据面 SSE 订阅（发布事件流；keepalive 注释帧）
      security: []
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
        - { name: after_version, in: query, schema: { type: integer, format: int64 }, description: 断线续传起点（重放该版本之后的历史事件再转实时） }
      responses:
        '200':
          description: text/event-stream
  /v1/projects/{p}/branches/{b}/config:
    get:
      summary: 渲染输出配置文档（YAML/TOML/JSON/ENV；secret 默认掩码）
      security: []
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { $ref: '#/components/parameters/BranchPath' }
        - { name: format, in: query, schema: { type: string, enum: [yaml, toml, json, env], default: yaml }, description: "env = .env 文件（GROUP__KEY=VALUE，组/键大写，双下划线分隔）" }
        - { name: version, in: query, schema: { type: integer, format: int64 } }
        - { name: reveal, in: query, schema: { type: boolean, default: false }, description: 需权限+审计 }
      responses:
        '200':
          description: 渲染文档（Content-Type 按 format）
          content:
            application/octet-stream: {}
        '404': { $ref: '#/components/responses/NotFound' }
  # F10（P3-④ 补全）：项目管理员（PA）账号管理面（admin-only；global admin 管理）
  /api/v1/projects/{p}/admins:
    get:
      summary: 项目管理员账号列表（该项目的 PA；global admin 会话）
      security: [AdminSession: []]
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
      responses:
        '200':
          description: 账号列表
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/ProjectAdminAccount' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      summary: 创建项目管理员账号（用户名 [A-Za-z0-9_-]{2,64} 且 ≠ admin）
      security: [AdminSession: []]
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PAUpsertRequest' }
      responses:
        '201':
          description: 创建成功
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ProjectAdminAccount' }
        '409': { $ref: '#/components/responses/Conflict' }
        '422': { $ref: '#/components/responses/Validation' }
  /api/v1/projects/{p}/admins/{u}:
    put:
      summary: 修改项目管理员密码（旧会话即时失效）
      security: [AdminSession: []]
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { name: u, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PAUpsertRequest' }
      responses:
        '200':
          description: 修改成功
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      summary: 删除项目管理员账号（级联删除其会话）
      security: [AdminSession: []]
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { name: u, in: path, required: true, schema: { type: string } }
      responses:
        '204': { description: 删除成功 }
        '404': { $ref: '#/components/responses/NotFound' }
  # 项目访问令牌（project-token）：数据面 SDK 机器凭据（admin-only；仅全局管理员可管理）
  /api/v1/projects/{p}/tokens:
    get:
      summary: 项目访问令牌列表（不含明文与 hash；含 revoked 标记）
      security: [AdminSession: []]
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
      responses:
        '200':
          description: 令牌列表
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/ProjectToken' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
    post:
      summary: 创建项目访问令牌（明文仅创建响应返回一次；SHA-256 落盘）
      security: [AdminSession: []]
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TokenCreateRequest' }
      responses:
        '201':
          description: 创建成功（token 明文仅此一次）
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TokenCreatedResponse' }
        '409': { $ref: '#/components/responses/Conflict' }
        '404': { $ref: '#/components/responses/NotFound' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /api/v1/projects/{p}/tokens/{id}:
    delete:
      summary: 吊销项目访问令牌（幂等；已吊销重复删仍 204）
      security: [AdminSession: []]
      parameters:
        - { $ref: '#/components/parameters/ProjectPath' }
        - { name: id, in: path, required: true, schema: { type: string }, description: token id（hash 前 16 位） }
      responses:
        '204': { description: 吊销成功 }
        '404': { $ref: '#/components/responses/NotFound' }
        '403': { $ref: '#/components/responses/Forbidden' }

components:
  securitySchemes:
    AdminSession:
      type: http
      scheme: bearer
      description: 管理面会话令牌（/api/v1/login 获取；单会话强制）
  parameters:
    ProjectPath:
      name: p
      in: path
      required: true
      schema: { type: string }
      description: 项目名
    BranchPath:
      name: b
      in: path
      required: true
      schema: { type: string }
      description: 分支名（dev/test/prod 或自定义）
  responses:
    Unauthorized:
      description: 未认证或会话过期（ERR_SESSION_EXPIRED）
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorBody' }
    SessionInUse:
      description: 已有管理员在线（ERR_SESSION_IN_USE）
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorBody' }
    NotFound:
      description: 不存在（ERR_NOT_FOUND）
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorBody' }
    Conflict:
      description: 冲突（ERR_CONFLICT / 命名冲突 / base_version 不匹配）
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorBody' }
    ValidationFailed:
      description: 校验失败（ERR_VALIDATION，detail 携带明细）
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorBody' }
    PublishBlocked:
      description: 完整性校验阻断发布（ERR_PUBLISH_BLOCKED，detail 携带明细）
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorBody' }
    NoDraft:
      description: 无待发布草稿（ERR_NO_DRAFT）
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorBody' }
    Created:
      description: 已创建
      content:
        application/json:
          schema: { $ref: '#/components/schemas/SharedItem' }
  schemas:
    ErrorBody:
      type: object
      required: [code, message]
      properties:
        code: { type: string }
        message: { type: string }
        detail: { type: object, additionalProperties: true }
        request_id: { type: string }
    LoginRequest:
      type: object
      required: [password]
      properties:
        password: { type: string }
        device_id: { type: string }
    LoginResponse:
      type: object
      required: [token, expires_at]
      properties:
        token: { type: string }
        expires_at: { type: string, format: date-time }
        must_change_password: { type: boolean, default: false }
    Project:
      type: object
      required: [id, name]
      properties:
        id: { type: string }
        name: { type: string }
        created_at: { type: string, format: date-time }
    Branch:
      type: object
      required: [name, active_version]
      properties:
        name: { type: string }
        active_version: { type: integer, format: int64 }
        structure_version: { type: integer, format: int64 }
        created_at: { type: string, format: date-time }
        draft_rev: { type: integer, format: int64, description: 草稿修订号（乐观锁） }
        shared_refs:
          type: array
          description: 结构 shared 项 × 本分支绑定解析值（secret 已掩码）；未绑定项 shared_key 为空串、version/value 为 null
          items:
            type: object
            properties:
              group: { type: string }
              key: { type: string }
              shared_key: { type: string, description: 本分支绑定的共享项 key；空串 = 未绑定 }
              version: { type: [integer, "null"], format: int64 }
              value:
                anyOf:
                  - { $ref: '#/components/schemas/Value' }
                  - { type: "null" }
    ConfigSnapshot:
      type: object
      required: [project, branch, version]
      properties:
        project: { type: string }
        branch: { type: string }
        version: { type: integer, format: int64 }
        # G3/D27+R1：数据面按身份 resolve 的结果——灰度命中时 version=active（v/ 空间）、
        # resolved_version=gray_seq、gray=true；稳定路径 resolved_version=version。
        resolved_version: { type: integer, format: int64 }
        gray: { type: boolean, default: false }
        structure_version: { type: integer, format: int64 }
        groups:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/Value'
    ItemDef:
      type: object
      required: [key, type]
      properties:
        key: { type: string }
        type: { type: string, enum: [string, int, float, bool, json, array, secret] }
        required: { type: boolean, default: false }
        secret: { type: boolean, default: false }
        validate: { type: string, description: 校验规则（正则/范围，JSON 字符串） }
        description: { type: string, maxLength: 200, description: 助记描述（≤200 字节，不渲染） }
        shared: { type: boolean, default: false, description: 引用共享标记：true 时值由共享库物化，各分支在草稿页选择引用的共享项 }
    GroupDef:
      type: object
      required: [name, items]
      properties:
        name: { type: string }
        items:
          type: array
          items: { $ref: '#/components/schemas/ItemDef' }
    StructureDraft:
      type: object
      required: [base_version, groups]
      properties:
        base_version: { type: integer, format: int64, description: 发布时必须等于当前已发布结构版本 }
        groups:
          type: array
          items: { $ref: '#/components/schemas/GroupDef' }
        changed_items:
          type: array
          items: { type: string }
          description: 服务端回填的影响 item（group/key），用于预览
    Value:
      type: object
      required: [type]
      properties:
        type: { type: string, enum: [string, int, float, bool, json, array, secret] }
        str_value: { type: string }
        int_value: { type: integer, format: int64 }
        float_value: { type: number }
        bool_value: { type: boolean }
        json_value: { type: string }
        list_value:
          type: array
          items: { type: string }
        masked: { type: boolean, default: false }
    DraftUpdate:
      type: object
      required: [group, key, value]
      properties:
        group: { type: string }
        key: { type: string }
        value: { $ref: '#/components/schemas/Value' }
    DraftBody:
      type: object
      properties:
        updates:
          type: array
          items: { $ref: '#/components/schemas/DraftUpdate' }
        deletes:
          type: array
          items: { type: string }
          description: '待删除 item，格式 "group/key"'
        shared_bindings:
          type: array
          description: 分支级共享引用绑定 upsert/解除（shared_key 空串 = 解除绑定）
          items:
            type: object
            required: [group, key, shared_key]
            properties:
              group: { type: string }
              key: { type: string }
              shared_key: { type: string, description: 共享项 key；空串 = 解除绑定 }
    PublishRequest:
      type: object
      required: [comment]
      properties:
        comment: { type: string, maxLength: 500 }
        request_id: { type: string, description: 幂等键；缺省服务端生成并回显 }
    Change:
      type: object
      required: [group, key, kind]
      properties:
        group: { type: string }
        key: { type: string }
        kind: { type: string, enum: [upsert, delete] }
        new_value: { $ref: '#/components/schemas/Value' }
    PublishResult:
      type: object
      required: [version]
      properties:
        version: { type: integer, format: int64 }
        structure_version: { type: integer, format: int64 }
        changes:
          type: array
          items: { $ref: '#/components/schemas/Change' }
        request_id: { type: string }
    Version:
      type: object
      required: [no, structure_version, created_at, kind]
      properties:
        no: { type: integer, format: int64 }
        structure_version: { type: integer, format: int64 }
        created_at: { type: string, format: date-time }
        operator: { type: string }
        comment: { type: string }
        rollback_of: { type: integer, format: int64, nullable: true }
        kind: { type: string, enum: [full, diff] }
    RollbackRequest:
      type: object
      required: [to_version, comment]
      properties:
        to_version: { type: integer, format: int64 }
        comment: { type: string, maxLength: 500 }
        request_id: { type: string }
    GrayRule:
      type: object
      description: 灰度规则（G2：状态机数据；求值次序 labels→IP→percent，任一命中即命中；无身份永不进灰度）
      properties:
        match_labels:
          type: array
          description: 标签匹配（OR：任一 key=value 命中）
          items:
            type: object
            required: [key, value]
            properties:
              key: { type: string }
              value: { type: string }
        ip_cidrs:
          type: array
          description: IP 段（CIDR，如 10.0.0.0/8）
          items: { type: string }
        percentage:
          type: integer
          minimum: 0
          maximum: 100
          description: 百分比放量（fnv1a(instance_id) % 100 < pct）
    GrayPublishRequest:
      type: object
      required: [rule, comment]
      properties:
        rule: { $ref: '#/components/schemas/GrayRule' }
        comment: { type: string, maxLength: 500 }
        request_id: { type: string }
    GrayCommentRequest:
      type: object
      required: [comment]
      properties:
        comment: { type: string, maxLength: 500 }
        request_id: { type: string }
    GrayPublishResult:
      type: object
      properties:
        gray_seq: { type: integer, format: int64 }
        gray_rule: { $ref: '#/components/schemas/GrayRule' }
        active_version: { type: integer, format: int64 }
        event_gray: { type: boolean }
        request_id: { type: string }
    GrayStatus:
      type: object
      properties:
        active_version: { type: integer, format: int64 }
        structure_version: { type: integer, format: int64 }
        gray_active: { type: boolean }
        gray_seq: { type: integer, format: int64 }
        gray_rule: { $ref: '#/components/schemas/GrayRule' }
    DiffResult:
      type: object
      properties:
        diffs:
          type: array
          items:
            type: object
            properties:
              group: { type: string }
              key: { type: string }
              branch_a: { $ref: '#/components/schemas/Value' }
              branch_b: { $ref: '#/components/schemas/Value' }
        missing:
          type: array
          items: { type: string }
          description: 仅在一侧有值的 item（group/key）
    PromoteRequest:
      type: object
      required: [from, to]
      properties:
        from: { type: string, description: 源分支 }
        to: { type: string, description: 目标分支（写其值草稿） }
        items:
          type: array
          items: { type: string }
          description: 限定 item（group/key）；缺省=全部
        force: { type: boolean, default: false, description: 覆盖目标草稿已修改项 }
    PromoteResult:
      type: object
      properties:
        applied:
          type: array
          items: { type: string }
        skipped:
          type: array
          items: { type: string }
        missing_from:
          type: array
          items: { type: string }
    SharedItem:
      type: object
      required: [key, type]
      properties:
        key: { type: string, description: 共享项 key（全局唯一，无分组） }
        type: { type: string, enum: [string, int, float, bool, json, array, secret] }
        secret: { type: boolean, default: false }
        required: { type: boolean, default: false }
        value:
          $ref: '#/components/schemas/Value'
          description: 'secret 项传空字符串（{type: string, str_value: ""}）表示保留当前密文（编辑场景，仅改描述/required）；无既有值或当前非 secret 时 422'
        version: { type: integer, format: int64 }
        description: { type: string, description: 助记描述（≤200 字节，不渲染） }
        refs:
          type: array
          description: 绑定该共享项的项目分支位置（仅 GET /api/v1/shared 返回）
          items:
            type: object
            properties:
              project: { type: string }
              branch: { type: string }
              group: { type: string }
              item_key: { type: string }
    SharedPublishResult:
      type: object
      properties:
        version: { type: integer, format: int64 }
        affected:
          type: array
          items:
            type: object
            properties:
              project: { type: string }
              branch: { type: string }
              new_version: { type: integer, format: int64 }
    AuditEntry:
      type: object
      properties:
        seq: { type: integer, format: int64 }
        ts: { type: string, format: date-time }
        operator: { type: string }
        action: { type: string }
        project: { type: string }
        branch: { type: string }
        version: { type: integer, format: int64 }
        request_id: { type: string }
        detail: { type: object, additionalProperties: true }
    Member:
      type: object
      required: [node_id, grpc_addr, http_addr]
      properties:
        node_id: { type: string }
        grpc_addr: { type: string }
        http_addr: { type: string }
        raft_addr: { type: string }
        is_leader: { type: boolean }
        is_voter: { type: boolean }
        committed_index: { type: integer, format: int64 }
    ProjectAdminAccount:
      type: object
      required: [username, project, created_at]
      properties:
        username: { type: string, description: "全局唯一，[A-Za-z0-9_-]{2,64}，≠ admin" }
        project: { type: string }
        created_at: { type: integer, format: int64, description: 墙钟 ms }
        # 密码哈希不外泄：账号列表不含 salt/password_hash 明文（服务端自行省略）
    PAUpsertRequest:
      type: object
      required: [username, password]
      properties:
        username: { type: string, description: "[A-Za-z0-9_-]{2,64}，≠ admin" }
        password: { type: string, minLength: 6, description: 新密码（≥6 位） }
    ProjectToken:
      type: object
      required: [id, name, created_at, revoked]
      properties:
        id: { type: string, description: token id（= SHA-256 前 16 位 hex） }
        name: { type: string, description: "展示名，项目内唯一（[A-Za-z0-9._-]{1,64}）" }
        created_at: { type: integer, format: int64, description: 墙钟 ms }
        created_by: { type: string }
        revoked: { type: boolean }
        # 不含 hash/token 明文：列表永不返回凭据
    TokenCreateRequest:
      type: object
      required: [name]
      properties:
        name: { type: string, description: "展示名，项目内唯一（[A-Za-z0-9._-]{1,64}）" }
    TokenCreatedResponse:
      type: object
      required: [id, name, token, created_at]
      properties:
        id: { type: string }
        name: { type: string }
        token: { type: string, description: 明文令牌——仅此响应返回一次，服务端只存 SHA-256 }
        created_at: { type: integer, format: int64 }
    MemberList:
      type: object
      properties:
        members:
          type: array
          items: { $ref: '#/components/schemas/Member' }
    JoinRequest:
      type: object
      required: [node_id, grpc_addr, raft_addr]
      properties:
        node_id: { type: string }
        grpc_addr: { type: string }
        http_addr: { type: string }
        raft_addr: { type: string }