sphere-feature-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sphere Feature Workflow

Sphere 功能工作流

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. Prefer repository conventions over generic architecture patterns unless the user explicitly requests otherwise.

在

go-sphere

脚手架项目中实现可合并的功能变更，同时保持

proto

、

schema

、

service

和

render

层同步。

本技能为脚手架专属，优先遵循仓库约定而非通用架构模式，除非用户明确提出其他要求。

Required Reading Order

必读顺序

Read these references before making edits:

references/workflow-matrix.md
references/source-of-truth-and-generated-boundaries.md
references/change-checklist.md

编辑前请先阅读以下参考文档：

references/workflow-matrix.md
references/source-of-truth-and-generated-boundaries.md
references/change-checklist.md

Scope

适用范围

Use this skill when the task involves one or more of the following:

HTTP/API contract changes in
```
proto/**
```
Ent schema updates in
```
internal/pkg/database/schema/**
```
Bind/map registration updates in
```
cmd/tools/bind/main.go
```
Service/DAO/render behavior updates that must stay generation-safe
Cross-layer refactors that require protocol-first consistency

当任务涉及以下一项或多项内容时使用本技能：

```
proto/**
```
目录下的HTTP/API契约变更
```
internal/pkg/database/schema/**
```
目录下的Ent schema更新
```
cmd/tools/bind/main.go
```
中的绑定/映射注册更新
必须保证生成安全的服务/DAO/render行为更新
需要协议优先一致性的跨层重构

Workflow Selection

工作流选择

Classify the task first, then run the matching workflow:

```
Contract-first
```

Start from
```
proto/**
```
Use when adding or changing service methods, HTTP annotations, errors, or validation

```
Schema-first
```

Start from
```
internal/pkg/database/schema/**
```
Use when adding/changing entities, fields, indexes, or relationships

```
Service-only
```

Start from
```
internal/service/**
```
and
```
internal/pkg/dao/**
```
Use when behavior changes without contract/schema changes

```
Cross-layer
```

Use
```
Contract-first
```
or
```
Schema-first
```
as entrypoint, then complete all impacted layers

If classification is unclear, follow the preflight checks in references/workflow-matrix.md.

首先对任务进行分类，然后运行匹配的工作流：

```
契约优先
```

从
```
proto/**
```
开始
适用于添加或修改服务方法、HTTP注解、错误定义或校验规则的场景

```
Schema优先
```

从
```
internal/pkg/database/schema/**
```
开始
适用于添加/修改实体、字段、索引或关联关系的场景

```
仅服务层
```

从
```
internal/service/**
```
和
```
internal/pkg/dao/**
```
开始
适用于不需要变更契约/schema的行为调整场景

```
跨层
```

以
```
契约优先
```
或
```
Schema优先
```
为切入点，然后完成所有受影响层的调整

如果分类不明确，请遵循references/workflow-matrix.md中的预检要求。

Reuse-First Policy

优先复用原则

Before implementing new framework-level capability, check existing Sphere packages first. Do not duplicate behavior already covered by:

Lifecycle and bootstrapping:
```
core/boot
```
HTTP transport and error flow:
```
server/httpz
```
Auth and authorization:
```
server/auth/*
```
,
```
server/middleware/auth
```

Common middleware:

server/middleware/cors

ratelimiter

selector

Infrastructure adapters and shared runtime packages:
```
cache/*
```
,
```
storage/*
```
,
```
log/*
```
,
```
utils/*
```
,
```
infra/*
```

When overlap exists, reuse existing packages and document the decision.

在实现新的框架级能力前，请先检查现有Sphere包。不要重复实现以下包已覆盖的功能：

生命周期与启动：
```
core/boot
```
HTTP传输与错误流：
```
server/httpz
```
身份验证与授权：
```
server/auth/*
```
、
```
server/middleware/auth
```

通用中间件：

server/middleware/cors

、

ratelimiter

、

selector

基础设施适配器与共享运行时包：
```
cache/*
```
、
```
storage/*
```
、
```
log/*
```
、
```
utils/*
```
、
```
infra/*
```

如果存在功能重叠，请复用现有包并记录该决策。

Execution Workflows

执行工作流

Contract-first Workflow

契约优先工作流

Edit
```
proto/**
```
(service/method, HTTP annotation, validation, errors).
Run
```
make gen/proto
```
.
Resolve compile and behavior impacts in:

```
internal/service/**
```
```
internal/pkg/dao/**
```
```
internal/pkg/render/**
```
non-generated files

If contract-facing docs or SDK are impacted, run
```
make gen/docs
```
and/or
```
make gen/dts
```
.
Run tests and ensure generated diffs are consumed by manual code.

编辑
```
proto/**
```
（服务/方法、HTTP注解、校验规则、错误定义）。
运行
```
make gen/proto
```
。
解决以下位置的编译和行为影响：

```
internal/service/**
```
```
internal/pkg/dao/**
```
```
internal/pkg/render/**
```
下的非生成文件

如果面向契约的文档或SDK受影响，运行
```
make gen/docs
```
和/或
```
make gen/dts
```
。
运行测试，确保生成的差异已被手动编写的代码适配。

Schema-first Workflow

Schema优先工作流

Edit
```
internal/pkg/database/schema/**
```
(field policy, relation, index strategy).
Verify bind/map registration impact in
```
cmd/tools/bind/main.go#createFilesConf
```
.
Review
```
WithIgnoreFields
```
for system-managed and sensitive fields.
Run
```
make gen/proto
```
.
Resolve compile and behavior impacts across service/dao/render.
Run tests and verify query paths align with index intent.

编辑
```
internal/pkg/database/schema/**
```
（字段策略、关联关系、索引策略）。
检查
```
cmd/tools/bind/main.go#createFilesConf
```
中的绑定/映射注册影响。
检查系统管理字段和敏感字段的
```
WithIgnoreFields
```
配置。
运行
```
make gen/proto
```
。
解决service/dao/render各层的编译和行为影响。
运行测试，验证查询路径与索引设计意图一致。

Service-only Workflow

仅服务层工作流

Edit only non-generated business code:

```
internal/service/**
```
```
internal/pkg/dao/**
```
```
internal/pkg/render/**
```
non-generated files
optional shared orchestration in
```
internal/biz/**
```

Keep contract/schema stable unless explicitly requested.
Run targeted or full tests and confirm no API behavior regression.

仅编辑非生成的业务代码：

```
internal/service/**
```
```
internal/pkg/dao/**
```
```
internal/pkg/render/**
```
下的非生成文件
可选的
```
internal/biz/**
```
下的共享编排代码

除非明确要求，否则保持契约/schema稳定。
运行定向或全量测试，确认无API行为回归。

Hard Rules

硬性规则

Edit source-of-truth files only; never patch generated files directly.
Run
```
make gen/proto
```
after any proto/schema change.
Run
```
make gen/docs
```
when HTTP contract output changes.
Run
```
make gen/wire
```
when dependency wiring signatures change.
New entity exposure must be reviewed in
```
cmd/tools/bind/main.go#createFilesConf
```
.
```
WithIgnoreFields
```
must cover system-managed and sensitive fields.
Keep service-specific business errors in the owning service proto unless explicitly shared.
Block delivery on route conflicts, cross-layer drift, or unconsumed generated changes.

Never manually edit

internal/pkg/render/entbind/**

internal/pkg/render/entmap/**

仅编辑可信数据源文件；绝对不要直接修改生成的文件。
任何proto/schema变更后都要运行
```
make gen/proto
```
。
HTTP契约输出变更时运行
```
make gen/docs
```
。
依赖绑定签名变更时运行
```
make gen/wire
```
。
新实体暴露必须在
```
cmd/tools/bind/main.go#createFilesConf
```
中审核。
```
WithIgnoreFields
```
必须覆盖系统管理字段和敏感字段。
服务专属的业务错误应保存在所属服务的proto中，除非明确需要共享。
存在路由冲突、跨层不一致或未适配的生成变更时，禁止交付。

绝对不要手动编辑

internal/pkg/render/entbind/**

或

internal/pkg/render/entmap/**

。

Standard Commands

标准命令

bash

undefined

bash

undefined

ent + proto + bind/map generation chain

ent + proto + bind/map 生成链路

make gen/proto

openapi/swagger generation

openapi/swagger 生成

make gen/docs

dependency injection generation

依赖注入生成

make gen/wire

validation

校验

go test ./...

undefined

go test ./...

undefined

Failure Conditions

失败条件

Do not mark the task complete if any of the following is true:

Workflow type is not explicitly classified.
Required generation commands were skipped.
Generated diffs exist but are not reflected in service/dao/render logic.
Generated files were manually edited.
Bind/map or ignore-field policy impact was missed for schema-affecting changes.
Compatibility impact and residual risks were not reported.

When a failure condition is hit, output

Blocking Issues

first, then a fix plan.

如果出现以下任意情况，不要标记任务完成：

未明确分类工作流类型。
跳过了必须的生成命令。
存在生成的差异，但未在service/dao/render逻辑中体现。
手动编辑了生成文件。
影响schema的变更遗漏了绑定/映射或忽略字段策略的影响检查。
未报告兼容性影响和残留风险。

当遇到失败条件时，首先输出

阻塞问题

，然后输出修复方案。

Final Output Contract

最终输出规范

Use this exact section order when reporting completion:

```
Scope
```
```
Workflow Selection
```
```
Reuse Decision
```
```
Source-of-Truth Files
```
```
Generation Commands
```
```
Behavior/Compatibility Notes
```
```
Validation
```
```
Blocking Issues
```
(only when applicable)

报告完成时请严格遵循以下章节顺序：

```
适用范围
```
```
工作流选择
```
```
复用决策
```
```
可信数据源文件
```
```
生成命令
```
```
行为/兼容性说明
```
```
校验结果
```
```
阻塞问题
```
（仅适用于存在阻塞问题的场景）