agentic-coding-workflow/internal/project/domain.go

// Package project 承载 Project / Requirement / Issue 三个 PM 聚合根的领域类型与
// Service 接口契约。本文件只做类型与签名声明，业务实现在 *_service.go。
//
// 三个聚合根共享同一个 Go 包是有意为之：它们在 schema 上紧耦合（Issue 引用
// Requirement，Requirement 属于 Project），且对外只暴露一组 chi route，拆包
// 反而要互相 import。
package project

import (
	"context"
	"time"

	"github.com/google/uuid"
)

// Phase 是 Requirement 的五阶段枚举。phase 不强制单向流动，可任意跳跃/回退。
// 字符串常量保持与 DB CHECK 约束一致。
type Phase string

// 五阶段枚举值，与 migrations/0002 的 CHECK 约束完全一致。
const (
	PhasePlanning     Phase = "planning"
	PhaseAuditing     Phase = "auditing"
	PhaseImplementing Phase = "implementing"
	PhaseReviewing    Phase = "reviewing"
	PhaseDone         Phase = "done"
)

// AllPhases 用于校验 phase 字符串合法性，顺序也对应前端看板/流转条的列序。
var AllPhases = []Phase{PhasePlanning, PhaseAuditing, PhaseImplementing, PhaseReviewing, PhaseDone}

// IsValid 报告 p 是否在枚举集合内。
func (p Phase) IsValid() bool {
	for _, x := range AllPhases {
		if p == x {
			return true
		}
	}
	return false
}

// Status 是 Requirement / Issue 通用的开/关状态。
type Status string

// 开/关状态枚举值，与 DB CHECK 约束一致。
const (
	StatusOpen   Status = "open"
	StatusClosed Status = "closed"
)

// Visibility 控制 Project 的可见域：private 仅 owner+admin 可读，
// internal 所有登录用户可读；写权限两者都仅限 owner+admin。
type Visibility string

// 可见性枚举值，与 DB CHECK 约束一致。
const (
	VisibilityPrivate  Visibility = "private"
	VisibilityInternal Visibility = "internal"
)

// IsValid 报告 v 是否在枚举集合内。
func (v Visibility) IsValid() bool {
	return v == VisibilityPrivate || v == VisibilityInternal
}

// Project 是顶层聚合根。ArchivedAt 为 nil 表示未归档。
type Project struct {
	ID          uuid.UUID
	Slug        string
	Name        string
	Description string
	Visibility  Visibility
	OwnerID     uuid.UUID
	ArchivedAt  *time.Time
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

// Requirement 表示一个项目内的需求。Number 在 (project_id) 内自增。
type Requirement struct {
	ID          uuid.UUID
	ProjectID   uuid.UUID
	Number      int
	Title       string
	Description string
	Phase       Phase
	Status      Status
	OwnerID     uuid.UUID
	ClosedAt    *time.Time
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

// Issue 可挂载到某个 Requirement，也可游离（RequirementID == nil）。
// AssigneeID 为 nil 表示未指派。CreatedBy 永远存在（DELETE RESTRICT）。
type Issue struct {
	ID            uuid.UUID
	ProjectID     uuid.UUID
	RequirementID *uuid.UUID
	Number        int
	Title         string
	Description   string
	Status        Status
	AssigneeID    *uuid.UUID
	CreatedBy     uuid.UUID
	ClosedAt      *time.Time
	CreatedAt     time.Time
	UpdatedAt     time.Time
}

// Caller 表示发起请求的用户上下文。Service 层据此判定鉴权。
type Caller struct {
	UserID  uuid.UUID
	IsAdmin bool
}

// ProjectService 暴露 Project 聚合根的应用服务方法。包内有三个并列服务
// （Project/Requirement/Issue），这里保留聚合名前缀以避免歧义。
//
//nolint:revive // 名字带聚合根前缀比 "Service" 更准确：包里有 3 个并列服务接口
type ProjectService interface {
	Create(ctx context.Context, c Caller, in CreateProjectInput) (*Project, error)
	Get(ctx context.Context, c Caller, slug string) (*Project, error)
	List(ctx context.Context, c Caller, includeArchived bool) ([]*Project, error)
	Update(ctx context.Context, c Caller, slug string, in UpdateProjectInput) (*Project, error)
	Archive(ctx context.Context, c Caller, slug string) error
	Unarchive(ctx context.Context, c Caller, slug string) error
}

// RequirementService 暴露 Requirement 聚合根的应用服务方法。
type RequirementService interface {
	Create(ctx context.Context, c Caller, projectSlug string, in CreateRequirementInput) (*Requirement, error)
	Get(ctx context.Context, c Caller, projectSlug string, number int) (*Requirement, error)
	List(ctx context.Context, c Caller, projectSlug string, filter RequirementFilter) ([]*Requirement, error)
	Update(ctx context.Context, c Caller, projectSlug string, number int, in UpdateRequirementInput) (*Requirement, error)
	ChangePhase(ctx context.Context, c Caller, projectSlug string, number int, to Phase) (*Requirement, error)
	Close(ctx context.Context, c Caller, projectSlug string, number int) error
	Reopen(ctx context.Context, c Caller, projectSlug string, number int) error
}

// IssueService 暴露 Issue 聚合根的应用服务方法。
type IssueService interface {
	Create(ctx context.Context, c Caller, projectSlug string, in CreateIssueInput) (*Issue, error)
	Get(ctx context.Context, c Caller, projectSlug string, number int) (*Issue, error)
	List(ctx context.Context, c Caller, projectSlug string, filter IssueFilter) ([]*Issue, error)
	Update(ctx context.Context, c Caller, projectSlug string, number int, in UpdateIssueInput) (*Issue, error)
	Assign(ctx context.Context, c Caller, projectSlug string, number int, assignee *uuid.UUID) (*Issue, error)
	Close(ctx context.Context, c Caller, projectSlug string, number int) error
	Reopen(ctx context.Context, c Caller, projectSlug string, number int) error
}

// ===== 输入 DTO =====
//
// 约定（适用于全部 Update*Input）：指针字段为 nil 表示"未提供，保持原值"；
// 非 nil 表示"用解引用值替换"。Filter 类型使用零值（""、nil）表示"不过滤"。

// CreateProjectInput 携带创建 Project 必需的字段。Visibility 留空时由 Service 默认 private。
type CreateProjectInput struct {
	Slug        string
	Name        string
	Description string
	Visibility  Visibility
}

// UpdateProjectInput 是 Project 的 patch 输入：每个非 nil 字段表示要替换的值；
// nil 字段保持现有值不变。Slug / Owner / ArchivedAt 不在此处修改。
type UpdateProjectInput struct {
	Name        *string
	Description *string
	Visibility  *Visibility
}

// CreateRequirementInput 创建一条需求。OwnerID 为 nil 时由 Service 默认为调用者。
type CreateRequirementInput struct {
	Title       string
	Description string
	OwnerID     *uuid.UUID
}

// UpdateRequirementInput 同 UpdateProjectInput 的 patch 语义。Phase / Status 不在此处修改，
// 走专用方法 ChangePhase / Close / Reopen 以便 audit 区分。
type UpdateRequirementInput struct {
	Title       *string
	Description *string
	OwnerID     *uuid.UUID
}

// RequirementFilter 控制 List 时的过滤维度。Phase / Status 留零值（"" / Status("")）表示
// 不限制；非零值必须落在对应枚举集合内（IsValid 校验在 Service 层做）。
type RequirementFilter struct {
	Phase  Phase
	Status Status
}

// CreateIssueInput 创建 Issue。RequirementNumber == nil 表示游离 Issue（不挂载到任何
// Requirement）；非 nil 时 Service 会校验 1) 该 Requirement 与目标 Project 同属，
// 2) 未关闭。
type CreateIssueInput struct {
	Title             string
	Description       string
	RequirementNumber *int
	AssigneeID        *uuid.UUID
}

// UpdateIssueInput 是 Issue 的 patch 输入。RequirementNumber 为指针的指针，承载三种状态：
//
//	nil       —— 未提供（不修改 issue.requirement_id）
//	*x == nil —— 已提供，但要求"取消挂载"（issue.requirement_id 置 NULL）
//	*x != nil —— 已提供，要求"挂载到本项目下 number=**x 的 Requirement"
//
// HTTP 层用 json.RawMessage 区分 "字段缺省 vs 显式 null vs 数字"，再翻译为本三态。
type UpdateIssueInput struct {
	Title             *string
	Description       *string
	RequirementNumber **int
}

// IssueFilter 控制 List 时的过滤。Requirement 字段三态（与 sqlc requirement_filter
// narg 对应）：
//
//	nil               —— 不按 requirement 过滤
//	*Requirement == 0 —— 仅游离（requirement_id IS NULL）—— 0 是 sentinel，因为
//	                     Issue.Number 自增从 1 起
//	*Requirement >  0 —— 仅匹配 number == *Requirement 的 Requirement
//
// AssigneeID nil 表示不按 assignee 过滤；Status 留零值表示不按状态过滤。
type IssueFilter struct {
	Status      Status
	Requirement *int
	AssigneeID  *uuid.UUID
}