Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

15.3 KB
Raw Blame
package domain

import (
	"strconv"
	"strings"
	"time"
)

type Issue struct {
	ID             string `json:"id"`
	ProjectID      string `json:"projectId"`
	Number         int    `json:"number"`
	Title          string `json:"title"`
	Description    string `json:"description"`
	Status         string `json:"status"`                // backlog, todo, in_progress, in_review, done, closed, blocked, cancelled
	CloseSource    string `json:"closeSource,omitempty"` // manual, external; empty on older manually closed issues
	Priority       string `json:"priority"`
	AssigneeType   string `json:"assigneeType,omitempty"` // member, agent
	AssigneeID     string `json:"assigneeId,omitempty"`
	AssigneeUserID int64  `json:"assigneeUserId,omitempty"`
	WorkflowID     string `json:"workflowId,omitempty"`
	// PlaybookID is which named project combo this requirement uses.
	PlaybookID string `json:"playbookId,omitempty"`
	// SOPBindings is an optional per-issue override of the chosen playbook.
	// Nil means inherit that playbook's steps. AssigneeUserID on the issue
	// stays the overall owner / TAPD 跟进人.
	SOPBindings []IssueSOPBinding `json:"sopBindings,omitempty"`
	// SOPMode "none" delivers the requirement without an SOP (clarified and
	// changed in conversations): no SOP is bound by default and scheduled SOPs
	// never claim it. Empty on writes keeps the stored mode; "sop" clears it.
	SOPMode      string `json:"sopMode,omitempty"`
	RepositoryID string `json:"repositoryId,omitempty"`
	// RepositoryIDs lists every repository the issue touches. RepositoryID
	// stays the legacy single-repository field (kept in sync with the first
	// entry for display and external sync).
	RepositoryIDs []string `json:"repositoryIds,omitempty"`
	// BaseBranch is the legacy API key for an existing work branch to continue.
	// Empty creates a new work branch from the repository configured main branch.
	BaseBranch string `json:"baseBranch,omitempty"`
	// RepositoryBranches selects existing work branches by repository ID. When
	// provided, it replaces BaseBranch; an unlisted repository creates a new branch.
	RepositoryBranches map[string]string `json:"repositoryBranches,omitempty"`
	LatestTaskID       string            `json:"latestTaskId,omitempty"`
	AutomationState    string            `json:"automationState,omitempty"` // ignored means scheduled SOPs must not claim it
	DeliveryState      string            `json:"deliveryState,omitempty"`   // merged, reopened
	DeliveryMRURL      string            `json:"deliveryMrUrl,omitempty"`
	DeliveryMRState    string            `json:"deliveryMrState,omitempty"` // merged (default branch), integrated (baseline), opened, closed, reopened, unknown
	// DeliveryMRs lists one MR per delivered repository. DeliveryMRURL is its
	// first entry and DeliveryMRState the aggregate (see SetDeliveryMRs).
	DeliveryMRs       []DeliveryMR            `json:"deliveryMrs,omitempty"`
	DeliveryUpdatedAt time.Time               `json:"deliveryUpdatedAt,omitempty"`
	Kind              string                  `json:"kind,omitempty"` // requirement, issue
	Clarification     ClarificationAssessment `json:"clarification"`
	Source            string                  `json:"source,omitempty"` // local, gongfeng, tapd
	// TapdID is an optional metrics-only link for a platform-created requirement.
	// It does not create a tracker binding or authorize TAPD write-back.
	TapdID      string       `json:"tapdId,omitempty"`
	ExternalRef *ExternalRef `json:"externalRef,omitempty"`
	// ConversationSessionID is the conversation that identified and created
	// this requirement while changing code directly, without an SOP.
	ConversationSessionID string    `json:"conversationSessionId,omitempty"`
	CreatedAt             time.Time `json:"createdAt"`
	UpdatedAt             time.Time `json:"updatedAt"`
	// CompletedAt records an observed transition to done/closed, independent of
	// later edits and MR polling. Older completed issues may have no timestamp.
	CompletedAt time.Time `json:"completedAt,omitempty"`
	// Operations is the requirement's own audit trail: create, edit, close, reopen, dispatch.
	Operations []IssueOperation `json:"operations,omitempty"`
}

func (i Issue) Completed() bool {
	switch strings.ToLower(strings.TrimSpace(i.Status)) {
	case "done", "closed", "completed":
		return true
	}
	return false
}

// RequirementTAPDID returns the authoritative TAPD key for analytics.
// Synced TAPD issues use their tracker identity; platform issues may opt in
// with a metrics-only manual link and remain valid without one.
func (i Issue) RequirementTAPDID() string {
	if i.ExternalRef != nil && (strings.EqualFold(i.Source, "tapd") || strings.EqualFold(i.ExternalRef.Source, "tapd")) {
		if id := strings.TrimSpace(i.ExternalRef.ExternalID); id != "" {
			return id
		}
	}
	if i.ExternalRef != nil || strings.EqualFold(i.Source, "gongfeng") {
		return ""
	}
	return strings.TrimSpace(i.TapdID)
}

// IssueOperation is one user-visible action on a requirement.
type IssueOperation struct {
	At          time.Time `json:"at"`
	Actor       string    `json:"actor,omitempty"`
	ActorUserID int64     `json:"actorUserId,omitempty"`
	Action      string    `json:"action"`
	Detail      string    `json:"detail,omitempty"`
}

// AppendOperation records an action and keeps the newest 200 entries.
func (i *Issue) AppendOperation(op IssueOperation) {
	if i == nil {
		return
	}
	op.Action = strings.TrimSpace(op.Action)
	if op.Action == "" {
		return
	}
	if op.At.IsZero() {
		op.At = time.Now().UTC()
	}
	i.Operations = append(i.Operations, op)
	const maxOps = 200
	if len(i.Operations) > maxOps {
		i.Operations = append([]IssueOperation(nil), i.Operations[len(i.Operations)-maxOps:]...)
	}
}

// EffectiveRepositoryIDs returns the deduplicated, non-empty list of
// repositories bound to the issue. RepositoryIDs is authoritative;
// RepositoryID (the legacy single-repository field) is appended as fallback.
func (i Issue) EffectiveRepositoryIDs() []string {
	seen := map[string]bool{}
	out := make([]string, 0, len(i.RepositoryIDs)+1)
	for _, id := range append(append([]string(nil), i.RepositoryIDs...), i.RepositoryID) {
		id = strings.TrimSpace(id)
		if id == "" || seen[id] {
			continue
		}
		seen[id] = true
		out = append(out, id)
	}
	return out
}

// WorkBranchForRepository resolves the per-repository selection, falling back
// to the legacy branch only for a single repository (including project defaults).
func (i Issue) WorkBranchForRepository(repositoryID string) string {
	if i.RepositoryBranches != nil {
		return strings.TrimSpace(i.RepositoryBranches[repositoryID])
	}
	ids := i.EffectiveRepositoryIDs()
	if len(ids) == 0 || (len(ids) == 1 && ids[0] == repositoryID) {
		return strings.TrimSpace(i.BaseBranch)
	}
	return ""
}

type ClarificationAssessment struct {
	Summary              string                  `json:"summary,omitempty"`
	Status               string                  `json:"status,omitempty"` // analyzing, in_progress, ready, needs_user
	History              []ClarificationMessage  `json:"history,omitempty"`
	Questions            []ClarificationQuestion `json:"questions,omitempty"`
	SessionID            string                  `json:"sessionId,omitempty"`
	SessionUserID        int64                   `json:"sessionUserId,omitempty"`
	WriteBackStatus      string                  `json:"writeBackStatus,omitempty"` // pending, succeeded, failed, skipped
	WriteBackError       string                  `json:"writeBackError,omitempty"`
	WriteBackFingerprint string                  `json:"writeBackFingerprint,omitempty"`
	WriteBackAt          time.Time               `json:"writeBackAt,omitempty"`
	// StartedAt is the first observed start of clarification, including
	// pre-issue composer analysis when its server timestamp is carried over.
	StartedAt time.Time `json:"startedAt,omitempty"`
	// Gated is legacy: older TAPD imports were marked by it instead of
	// ExternalRef.Imported. It is only read (tracker retention), never set.
	Gated bool `json:"gated,omitempty"`
}

type ClarificationMessage struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type ClarificationQuestion struct {
	ID          string   `json:"id"`
	Question    string   `json:"question"`
	Options     []string `json:"options,omitempty"`
	MultiSelect bool     `json:"multiSelect,omitempty"`
	FreeText    bool     `json:"freeText,omitempty"`
}

// ExternalRef links a local Issue to an external issue/story in Gongfeng or TAPD.
type ExternalRef struct {
	// SourceContentHash records the last imported body so provider adapters can
	// distinguish a remote edit from a locally clarified requirement.
	SourceContentHash string    `json:"sourceContentHash,omitempty"`
	Source            string    `json:"source"`        // gongfeng, tapd
	ExternalID        string    `json:"externalId"`    // gongfeng issue id or tapd story id
	ExternalIID       int       `json:"externalIid"`   // gongfeng issue iid (for URL)
	ExternalURL       string    `json:"externalUrl"`   // clickable URL
	ExternalState     string    `json:"externalState"` // opened/closed for gongfeng, etc.
	ExternalType      string    `json:"externalType"`  // issue, story
	SyncedAt          time.Time `json:"syncedAt"`
	// Imported is set for 导入 TAPD / 新建 TAPD. Iteration sync must not
	// delete these just because they are outside the current TAPD pool.
	Imported bool `json:"imported,omitempty"`
}

// GongfengClosed reports whether this item is a Gongfeng issue already closed on Gongfeng.
// Local status can lag after a failed sync, so dispatch must use ExternalState, not Status.
func (i Issue) GongfengClosed() bool {
	if !strings.EqualFold(strings.TrimSpace(i.Source), "gongfeng") {
		return false
	}
	if i.ExternalRef == nil {
		return false
	}
	return strings.EqualFold(strings.TrimSpace(i.ExternalRef.ExternalState), "closed")
}

// ManuallyClosed distinguishes an explicit local close from a tracker close.
// Before CloseSource existed, only manual closes used Issue.Status=closed.
func (i Issue) ManuallyClosed() bool {
	return strings.EqualFold(strings.TrimSpace(i.Status), "closed") &&
		!strings.EqualFold(strings.TrimSpace(i.CloseSource), "external")
}

// TrackerClosed reads the tracker's raw state so a lagging local status cannot
// make an externally closed work item executable.
func (i Issue) TrackerClosed() bool {
	if i.ExternalRef == nil || (i.Source != "gongfeng" && i.Source != "tapd" && i.Source != "github") {
		return false
	}
	state := strings.ToLower(strings.TrimSpace(i.ExternalRef.ExternalState))
	return state == "closed" || state == "已关闭"
}

// DeliveryLocked reports whether a merged MR or completed delivery has made this work item final.
// A user can explicitly reopen it to allow a follow-up run.
func (i Issue) DeliveryLocked() bool {
	return strings.EqualFold(strings.TrimSpace(i.DeliveryState), "merged")
}

// DeliveryLockedLabel is the user-facing stage label for a delivery-locked issue.
// MR wording requires a real MR link. Historical manual close stored
// deliveryMrState=closed without a link, and that is not an MR.
func (i Issue) DeliveryLockedLabel() string {
	if i.ManuallyClosed() {
		return "关闭"
	}
	state := strings.ToLower(strings.TrimSpace(i.DeliveryMRState))
	if strings.TrimSpace(i.DeliveryMRURL) == "" {
		if state == "closed" {
			return "已关闭"
		}
		return "交付闭环"
	}
	switch state {
	case "merged":
		return "MR 已合入"
	case "integrated":
		return "已合入基线"
	case "closed":
		return "MR 已关闭"
	default:
		return "交付闭环"
	}
}

const issueIdentityMarker = "需求身份(平台权威,禁止忽略)"

// IdentityBlock is the authoritative tracker identity injected into SOP input
// and the compiled task prompt. Agents must not guess a TAPD/Gongfeng ID from
// branch names when this block is present.
func (i Issue) IdentityBlock() string {
	id := strings.TrimSpace(i.ID)
	if id == "" {
		return ""
	}
	source := strings.ToLower(strings.TrimSpace(i.Source))
	if source == "" {
		source = "local"
	}
	var b strings.Builder
	b.WriteString(issueIdentityMarker)
	b.WriteString(":\n")
	b.WriteString("- 平台工作项:")
	b.WriteString(id)
	b.WriteString("\n- 来源:")
	switch source {
	case "tapd":
		b.WriteString("TAPD")
	case "gongfeng":
		b.WriteString("工蜂")
	default:
		b.WriteString("本地")
	}
	b.WriteByte('\n')
	ref := i.ExternalRef
	if ref == nil {
		if tapdID := i.RequirementTAPDID(); tapdID != "" {
			b.WriteString("- 统计关联 TAPD ID:")
			b.WriteString(tapdID)
			b.WriteString("(仅用于指标归集,不代表 TAPD 同步关系)\n")
		} else {
			b.WriteString("- 外部 ID:无\n")
		}
		return b.String()
	}
	if kind := strings.TrimSpace(ref.ExternalType); kind != "" {
		b.WriteString("- 类型:")
		b.WriteString(kind)
		b.WriteByte('\n')
	}
	if extID := strings.TrimSpace(ref.ExternalID); extID != "" {
		b.WriteString("- 外部 ID:")
		b.WriteString(extID)
		b.WriteByte('\n')
	}
	if ref.ExternalIID != 0 {
		b.WriteString("- 外部编号:")
		b.WriteString(strconv.Itoa(ref.ExternalIID))
		b.WriteByte('\n')
	}
	if url := strings.TrimSpace(ref.ExternalURL); url != "" {
		b.WriteString("- 链接:")
		b.WriteString(url)
		b.WriteByte('\n')
	}
	return b.String()
}

func (i Issue) HasIdentityBlock(text string) bool {
	return strings.Contains(text, issueIdentityMarker)
}

const (
	IssueSOPNone = "none"
	IssueSOPUse  = "sop"
)

// WithoutSOP reports whether the requirement opted out of SOP delivery.
func (i Issue) WithoutSOP() bool {
	return strings.EqualFold(strings.TrimSpace(i.SOPMode), IssueSOPNone)
}

func (i Issue) ExecutionBlockedReason() string {
	if i.ManuallyClosed() {
		return "工作项已关闭,请先重新打开后再触发 SOP"
	}
	if i.TrackerClosed() || (i.Status == "closed" && i.CloseSource == "external") {
		return "外部工作项已关闭,请先在外部系统重新打开"
	}
	if i.DeliveryLocked() {
		switch i.DeliveryLockedLabel() {
		case "已关闭":
			return "工作项已关闭,请先重新打开后再触发 SOP"
		case "MR 已合入":
			return "关联 MR 已合入,请先重新打开工作项再触发 SOP"
		case "已合入基线":
			return "已合入基线,请先重新打开工作项再触发 SOP"
		case "MR 已关闭":
			return "关联 MR 已关闭,请先重新打开工作项再触发 SOP"
		default:
			return "工作项已交付闭环,请先重新打开后再触发 SOP"
		}
	}
	return ""
}

type IssueComment struct {
	ID         string    `json:"id"`
	IssueID    string    `json:"issueId"`
	AuthorType string    `json:"authorType"`
	AuthorID   string    `json:"authorId"`
	Body       string    `json:"body"`
	CreatedAt  time.Time `json:"createdAt"`
}

type RejectRequest struct {
	Expected *NodeDecisionExpectation `json:"expected,omitempty"`
	NodeID   string                   `json:"nodeId"`
	TargetID string                   `json:"targetId"`
	Reason   string                   `json:"reason"`
	Context  string                   `json:"context,omitempty"`
}

// HumanDecision is the shared payload for approve / retry so operators can
// attach extra facts (failed test names, links) that later nodes will see.
type HumanDecision struct {
	Expected *NodeDecisionExpectation `json:"expected,omitempty"`
	NodeID   string                   `json:"nodeId"`
	Reason   string                   `json:"reason,omitempty"`
	Context  string                   `json:"context,omitempty"`
}

// NodeDecisionExpectation binds a workbench action to the attempt being viewed.
type NodeDecisionExpectation struct {
	Status      string `json:"status"`
	Attempt     int    `json:"attempt"`
	ReworkCount int    `json:"reworkCount"`
}