it235/multica-best-practices/multica-artifact-backend

Artifact · Backend（薄编排）

Purpose

只规定 API 契约写什么、发布前怎么自检；Confluence 发布、Apifox 同步由 platform skill 封装。

本 skill 不含脚本；实现编码见 multica-backend-impl（TDD）。

Platform 协作

凭据与 CLI 细节只查 platform skill；矩阵见 `docs/platform-collaboration.md`。

@BackendDev 标准流程

1. multica-backend-impl        — 读上游 + TDD 实现
2. 写 docs/backend/<ISSUE-KEY>/api-contract.md
3. 自检（见下表）
4. multica-platform-confluence — publish_design.py --append-jira
5. multica-platform-apifox — sync_openapi.js（OpenAPI 增/改/删 + Issue tag；**每次新建 AI 分支**，见 platform-apifox `openapi-branch-workflow.md`）
6. 回传 Confluence + Apifox 同步摘要（含 AI 分支名）给 Leader

父页面（Issue Hub）

与 multica-artifact-architect 相同：JIRA 描述中 Confluence 需求页 为父页面；API 契约发布为其子页面。

API 契约规范（发布前自检）

本地草稿：docs/backend/<ISSUE-KEY>/api-contract.md 基线：multica-platform-confluence/scripts/templates/backend-api-template.md

Breaking change → 版本 +1，修订记录说明，通知 Leader 与 @FrontendDev。

落地（platform skill）

pip install -r multica-platform-confluence/scripts/requirements.txt
python multica-platform-confluence/scripts/publish_design.py \
  <ISSUE-KEY> docs/backend/<ISSUE-KEY>/api-contract.md \
  --append-jira --json

JIRA 追加块标题建议：h3. API 契约 (API Contract)（append-artifact-link --section "API 契约 (API Contract)"）。

Apifox 同步（platform skill）

契约发布后，将 openapi.json（与契约同目录或团队约定路径）同步到 Apifox：

set APIFOX_ACCESS_TOKEN=<token>
set APIFOX_PROJECT_ID=<projectId>
 
node multica-platform-apifox/scripts/sync_openapi.js \
  --file docs/backend/<ISSUE-KEY>/openapi.json \
  --issue <ISSUE-KEY> \
  --branch ai/<ISSUE-KEY>-openapi-<YYYYMMDD> \
  --json

每次同步必须 `--branch` 新建 AI 分支（禁止省略、禁止直写 main）。步骤见 multica-platform-apifox/references/openapi-branch-workflow.md。

接口增/改/删与 Issue tag 由 platform skill 处理；Apifox 项目链接写入契约头部修订记录。

用法（角色侧）

产出 API 契约，按 multica-artifact-backend 规范写 api-contract.md，
自检后 platform 发布到 Confluence 并回传链接。

为什么有效

契约挂在需求 Confluence 树下，与 PRD/架构设计同树；薄编排 + TDD 在 impl skill，职责清晰。