Tighten project board API for GitHub-style consumers

- Rename response timestamps to created_at / updated_at / closed_at - Replace is_closed bool with state ("open" / "closed") via api.StateType - Switch template_type / card_type / type to string enums with input validation - Embed creator User object on Project and ProjectColumn (batched lookup) - Add absolute html_url; drop relative url - Add POST /repos/.../projects/{id}/issues/{issue_id}/move with optional sorting - Validate column hex color and reject writes to closed projects - Document issue-only project scope in swagger - Push project-issue existence check into project_model.IsIssueInColumn - Add project_service.ErrIssueNotInProject sentinel for the move endpoint Co-Authored-By: Claude (Opus 4.7) <noreply@anthropic.com>
2026-09-21 22:37:45 +02:00 · 2026-05-03 14:32:39 +05:30
parent ed0ed680cf
commit 8fd9536150
9 changed files with 563 additions and 155 deletions
@@ -5,76 +5,189 @@ package convert

 import (
 	"context"
+	"fmt"

 	project_model "code.gitea.io/gitea/models/project"
+	user_model "code.gitea.io/gitea/models/user"
 	api "code.gitea.io/gitea/modules/structs"
 )

-// ToProject converts a project_model.Project to api.Project
-func ToProject(ctx context.Context, p *project_model.Project) *api.Project {
+func ProjectTemplateTypeToString(t project_model.TemplateType) string {
+	switch t {
+	case project_model.TemplateTypeBasicKanban:
+		return "basic_kanban"
+	case project_model.TemplateTypeBugTriage:
+		return "bug_triage"
+	default:
+		return "none"
+	}
+}
+
+func ProjectTemplateTypeFromString(s string) (project_model.TemplateType, error) {
+	switch s {
+	case "", "none":
+		return project_model.TemplateTypeNone, nil
+	case "basic_kanban":
+		return project_model.TemplateTypeBasicKanban, nil
+	case "bug_triage":
+		return project_model.TemplateTypeBugTriage, nil
+	default:
+		return 0, fmt.Errorf("invalid template_type %q (expected none, basic_kanban, bug_triage)", s)
+	}
+}
+
+func ProjectCardTypeToString(t project_model.CardType) string {
+	switch t {
+	case project_model.CardTypeImagesAndText:
+		return "images_and_text"
+	default:
+		return "text_only"
+	}
+}
+
+func ProjectCardTypeFromString(s string) (project_model.CardType, error) {
+	switch s {
+	case "", "text_only":
+		return project_model.CardTypeTextOnly, nil
+	case "images_and_text":
+		return project_model.CardTypeImagesAndText, nil
+	default:
+		return 0, fmt.Errorf("invalid card_type %q (expected text_only, images_and_text)", s)
+	}
+}
+
+func ProjectTypeToString(t project_model.Type) string {
+	switch t {
+	case project_model.TypeIndividual:
+		return "individual"
+	case project_model.TypeRepository:
+		return "repository"
+	case project_model.TypeOrganization:
+		return "organization"
+	default:
+		return ""
+	}
+}
+
+// loadProjectCreators batch-fetches creators for the given projects + columns and
+// returns a map keyed by user ID. Errors are surfaced; missing users are silently
+// skipped (their creator field stays nil), matching the convention of other list
+// converters that tolerate deleted users.
+func loadProjectCreators(ctx context.Context, projects []*project_model.Project, columns []*project_model.Column) (map[int64]*user_model.User, error) {
+	idSet := make(map[int64]struct{})
+	for _, p := range projects {
+		if p.CreatorID > 0 {
+			idSet[p.CreatorID] = struct{}{}
+		}
+	}
+	for _, c := range columns {
+		if c.CreatorID > 0 {
+			idSet[c.CreatorID] = struct{}{}
+		}
+	}
+	if len(idSet) == 0 {
+		return map[int64]*user_model.User{}, nil
+	}
+	ids := make([]int64, 0, len(idSet))
+	for id := range idSet {
+		ids = append(ids, id)
+	}
+	users, err := user_model.GetUserByIDs(ctx, ids)
+	if err != nil {
+		return nil, err
+	}
+	result := make(map[int64]*user_model.User, len(users))
+	for _, u := range users {
+		result[u.ID] = u
+	}
+	return result, nil
+}
+
+// ToProject converts a project_model.Project to api.Project.
+// Caller is expected to preload p.Repo / p.Owner to avoid N+1 lookups.
+func ToProject(ctx context.Context, p *project_model.Project, doer *user_model.User) *api.Project {
+	creators, _ := loadProjectCreators(ctx, []*project_model.Project{p}, nil)
+	return toProject(ctx, p, doer, creators)
+}
+
+func toProject(ctx context.Context, p *project_model.Project, doer *user_model.User, creators map[int64]*user_model.User) *api.Project {
+	state := api.StateOpen
+	if p.IsClosed {
+		state = api.StateClosed
+	}
+
 	project := &api.Project{
 		ID:              p.ID,
 		Title:           p.Title,
 		Description:     p.Description,
 		OwnerID:         p.OwnerID,
 		RepoID:          p.RepoID,
-		CreatorID:       p.CreatorID,
-		IsClosed:        p.IsClosed,
-		TemplateType:    int(p.TemplateType),
-		CardType:        int(p.CardType),
-		Type:            int(p.Type),
+		State:           state,
+		TemplateType:    ProjectTemplateTypeToString(p.TemplateType),
+		CardType:        ProjectCardTypeToString(p.CardType),
+		Type:            ProjectTypeToString(p.Type),
 		NumOpenIssues:   p.NumOpenIssues,
 		NumClosedIssues: p.NumClosedIssues,
 		NumIssues:       p.NumIssues,
-		Created:         p.CreatedUnix.AsTime(),
-		Updated:         p.UpdatedUnix.AsTime(),
+		CreatedAt:       p.CreatedUnix.AsTime(),
+		UpdatedAt:       p.UpdatedUnix.AsTime(),
 	}

 	if p.ClosedDateUnix > 0 {
 		t := p.ClosedDateUnix.AsTime()
-		project.ClosedDate = &t
+		project.ClosedAt = &t
+	}
+
+	if creator, ok := creators[p.CreatorID]; ok {
+		project.Creator = ToUser(ctx, creator, doer)
 	}

-	// Repo/Owner are expected to be preloaded by the caller to avoid N+1 lookups.
 	if p.Type == project_model.TypeRepository && p.Repo != nil {
-		project.URL = project_model.ProjectLinkForRepo(p.Repo, p.ID)
+		project.HTMLURL = p.Repo.HTMLURL() + fmt.Sprintf("/projects/%d", p.ID)
 	} else if p.Owner != nil {
-		project.URL = project_model.ProjectLinkForOrg(p.Owner, p.ID)
+		project.HTMLURL = p.Owner.HTMLURL(ctx) + fmt.Sprintf("/-/projects/%d", p.ID)
 	}

 	return project
 }

-// ToProjectColumn converts a project_model.Column to api.ProjectColumn
-func ToProjectColumn(ctx context.Context, column *project_model.Column) *api.ProjectColumn {
-	return &api.ProjectColumn{
+func ToProjectColumn(ctx context.Context, column *project_model.Column, doer *user_model.User) *api.ProjectColumn {
+	creators, _ := loadProjectCreators(ctx, nil, []*project_model.Column{column})
+	return toProjectColumn(ctx, column, doer, creators)
+}
+
+func toProjectColumn(ctx context.Context, column *project_model.Column, doer *user_model.User, creators map[int64]*user_model.User) *api.ProjectColumn {
+	apiColumn := &api.ProjectColumn{
 		ID:        column.ID,
 		Title:     column.Title,
 		Default:   column.Default,
 		Sorting:   column.Sorting,
 		Color:     column.Color,
 		ProjectID: column.ProjectID,
-		CreatorID: column.CreatorID,
 		NumIssues: column.NumIssues,
-		Created:   column.CreatedUnix.AsTime(),
-		Updated:   column.UpdatedUnix.AsTime(),
+		CreatedAt: column.CreatedUnix.AsTime(),
+		UpdatedAt: column.UpdatedUnix.AsTime(),
 	}
+	if creator, ok := creators[column.CreatorID]; ok {
+		apiColumn.Creator = ToUser(ctx, creator, doer)
+	}
+	return apiColumn
 }

-// ToProjectList converts a list of project_model.Project to a list of api.Project
-func ToProjectList(ctx context.Context, projects []*project_model.Project) []*api.Project {
+func ToProjectList(ctx context.Context, projects []*project_model.Project, doer *user_model.User) []*api.Project {
+	creators, _ := loadProjectCreators(ctx, projects, nil)
 	result := make([]*api.Project, len(projects))
 	for i, p := range projects {
-		result[i] = ToProject(ctx, p)
+		result[i] = toProject(ctx, p, doer, creators)
 	}
 	return result
 }

-// ToProjectColumnList converts a list of project_model.Column to a list of api.ProjectColumn
-func ToProjectColumnList(ctx context.Context, columns []*project_model.Column) []*api.ProjectColumn {
+func ToProjectColumnList(ctx context.Context, columns []*project_model.Column, doer *user_model.User) []*api.ProjectColumn {
+	creators, _ := loadProjectCreators(ctx, nil, columns)
 	result := make([]*api.ProjectColumn, len(columns))
 	for i, column := range columns {
-		result[i] = ToProjectColumn(ctx, column)
+		result[i] = toProjectColumn(ctx, column, doer, creators)
 	}
 	return result
 }