sphere-feature-workflow（球体特征工作流程）

Sphere Feature Workflow

Overview

Implement merge-ready feature changes in go-sphere scaffold projects while keeping proto, schema, service, and render layers synchronized.

This skill is scaffold-specific and required for any go-sphere feature work. Prefer repository conventions over generic architecture patterns unless the user explicitly requests otherwise.

Required Reading Order

Read these references in order before making edits:

1. references/workflow-matrix.md - Classify change type and select workflow
2. references/source-of-truth-and-generated-boundaries.md - Understand what files to edit vs. regenerate
3. references/change-checklist.md - Verify complete coverage before delivery

Scope

You MUST use this skill when the task involves any of the following:

Workflow Selection (Critical - Do Not Skip)

Classify the task FIRST, then run the matching workflow. See references/workflow-matrix.md for detailed preflight checks.

If classification is unclear, answer these questions first:

1. Does the request change external API behavior, route shape, validation, or error contract? → Contract-first
2. Does the request change persisted fields, entity relations, or index/query strategy? → Schema-first
3. Does the request only change orchestration/query/render logic? → Service-only
4. If multiple "yes", treat as Cross-layer

Reuse-First Policy (Required)

Before implementing new capability, check existing Sphere packages first. DO NOT duplicate behavior already covered by:

Always document your reuse decision in the final output.

Execution Workflows

Contract-first Workflow

1. Edit proto/** (service/method, HTTP annotation, validation, errors)
2. Run: make gen/proto
3. Resolve impacts in:
   - internal/service/**    (implement generated interface)
   - internal/pkg/dao/**   (query/mutation support)
   - internal/pkg/render/** non-generated files
4. If docs changed: make gen/docs
5. Run: go test ./...
6. Verify generated diffs are consumed

Schema-first Workflow

1. Edit internal/pkg/database/schema/** (field, relation, index)
2. Verify bind/map: cmd/tools/bind/main.go#createFilesConf
3. Review WithIgnoreFields for sensitive/system fields
4. Run: make gen/proto
5. Resolve impacts in service/dao/render
6. Run: go test ./...
7. Verify query paths align with index intent

Service-only Workflow

1. Edit ONLY non-generated code:
   - internal/service/**
   - internal/pkg/dao/**
   - internal/pkg/render/** (non-generated)
   - optional: internal/biz/**
2. Keep proto/schema STABLE
3. Run: go test ./...
4. Verify no API regression

Hard Rules (Non-Negotiable)

Standard Commands

Proto Organization

Code Generation Chain: protoc-gen-go → protoc-gen-sphere-binding → protoc-gen-sphere → protoc-gen-sphere-errors → protoc-gen-route

HTTP Framework (httpx)

The server/httpz package uses httpx as its foundation - a unified HTTP framework abstraction that supports multiple backends:

• ginx (Gin), fiberx (Fiber), echox (Echo), hertzx (Hertz)

Core interfaces: Handler, Middleware, Router, Engine, Context. All Sphere HTTP services use these abstractions.

Failure Conditions (Block Delivery If)

1. Workflow type not explicitly classified
2. Required generation commands skipped
3. Generated diffs exist but NOT consumed by service/dao/render
4. Generated files manually edited
5. Bind/map or ignore-field policy missed
6. Compatibility impact NOT reported

When a failure condition is hit, output Blocking Issues first, then a fix plan.

Final Output Contract (Required Format)

Use this exact section order when reporting completion:

## Scope
[What was changed]

## Workflow Selection
[Contract-first / Schema-first / Service-only / Cross-layer]

## Reuse Decision
[What existing packages were used, or why new code was needed]

## Source-of-Truth Files
[List of files edited]

## Generation Commands
[Commands run: make gen/proto, make gen/docs, etc.]

## Behavior/Compatibility Notes
[API changes, breaking changes, migration needs]

## Validation
[Tests run, results]

## Blocking Issues
[Only if applicable - describe issue + fix plan]