csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

docs: 修订宪章至 v2.2.0（新增文档规范原则）

Browse Source 
新增 Principle VII: Documentation Standards（文档规范）

主要变更：
- 规定功能总结文档必须放在 docs/{feature-id}/ 目录，对应 specs/{feature-id}/
- 要求总结文档使用中文命名（功能总结.md、使用指南.md、架构说明.md）
- 要求总结文档内容使用中文编写，方便中文团队阅读
- 强制要求每次完成功能后更新 README.md，添加 2-3 句简短描述
- 目标：让首次接触项目的开发者能快速了解功能

模板同步更新：
- plan-template.md: 添加文档结构说明和 Documentation Standards 检查项
- tasks-template.md: 新增文档任务模板和文档相关质量检查项

版本升级理由：
MINOR 版本升级（2.1.1 → 2.2.0），因为新增了影响开发工作流程的强制性原则，
要求所有功能完成后必须创建中文总结文档并更新 README.md
This commit is contained in:
huang
2025-11-11 17:24:12 +08:00
parent 2d29e8f7c9
commit 2b1754728f
3 changed files with 174 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

301
.specify/memory/constitution.md
View File

@@ -1,36 +1,42 @@
<!-- <!--
SYNC IMPACT REPORT - Constitution Amendment SYNC IMPACT REPORT - Constitution Amendment
============================================ ============================================
Version Change: 2.1.0 → 2.1.1 Version Change: 2.1.1 → 2.2.0
Date: 2025-11-11 Date: 2025-11-11
MODIFIED PRINCIPLES: NEW PRINCIPLES ADDED:
- II. Code Quality Standards → Added "中文注释和输出规范" (Chinese Comments and Output Standards) - VII. Documentation Standards (文档规范) - NEW principle for feature documentation
EXPANDED SECTIONS: MODIFIED SECTIONS:
- Added "中文注释和输出规范" subsection to Principle II - Added new Principle VII with documentation structure and language requirements
- Rule: Code comments SHOULD be in Chinese for Chinese-speaking developers - Rule: Summary docs MUST be placed in docs/{feature-id}/ mirroring specs/{feature-id}/
- Rule: Log messages SHOULD be in Chinese - Rule: Summary doc filenames MUST use Chinese
- Rule: User-facing error messages MUST be in Chinese (with bilingual support) - Rule: Summary doc content MUST use Chinese
- Rule: Internal error messages and debug logs SHOULD be in Chinese - Rule: README.md MUST be updated with brief Chinese summary for each feature
- Exceptions: Go doc comments for exported APIs may remain in English for ecosystem compatibility - Rule: Summary should be concise enough for first-time contributors to understand quickly
- Examples of correct Chinese comments and log messages - Examples of correct documentation structure and naming
- Rationale for Chinese-first approach - Rationale for centralized Chinese documentation
TEMPLATES REQUIRING UPDATES: TEMPLATES REQUIRING UPDATES:
✅ .specify/templates/plan-template.md - Will add Chinese comments check ✅ .specify/templates/plan-template.md - Added documentation structure guidance
✅ .specify/templates/spec-template.md - Will add Chinese output requirement ✅ .specify/templates/spec-template.md - No changes needed
✅ .specify/templates/tasks-template.md - Will add Chinese usage quality gate ✅ .specify/templates/tasks-template.md - Added documentation task template in Polish phase
FOLLOW-UP ACTIONS: FOLLOW-UP ACTIONS:
- Update templates with Chinese comments/logs checks - Update plan-template.md with docs/ structure
- Update tasks-template.md with documentation tasks in Polish phase
RATIONALE: RATIONALE:
PATCH version bump (2.1.1) - Clarification of existing code quality standards to MINOR version bump (2.2.0) - New principle added for documentation standards.
prefer Chinese for comments and logs, targeting Chinese-speaking development team. This is a new governance rule that establishes how feature documentation should be
This is not a breaking change but a refinement of communication standards within organized, named, and written. The principle addresses:
Principle II. The rule acknowledges the project's primary audience (Chinese developers) 1. Documentation location consistency (docs/ mirrors specs/)
while maintaining ecosystem compatibility for exported APIs. 2. Language requirements (Chinese for accessibility)
3. README.md update requirements (brief summaries)
4. Target audience (first-time contributors)
This is a MINOR bump (not PATCH) because it adds a new mandatory principle that
affects the development workflow, requiring documentation tasks for all features.
--> -->
# 君鸿卡管系统 Constitution # 君鸿卡管系统 Constitution
@@ -250,47 +256,6 @@ func (s *Service) GetUserByID(ctx context.Context, id string) (*User, error) {
return user, nil return user, nil
} }
// CreateOrder 创建新订单
func (s *Service) CreateOrder(ctx context.Context, req *CreateOrderRequest) (*Order, error) {
// 开启事务
tx := s.db.Begin()
defer func() {
if r := recover(); r != nil {
tx.Rollback()
s.logger.Error("创建订单时发生panic", zap.Any("panic", r))
}
}()
// 验证库存
if err := s.validateStock(ctx, req.ProductID, req.Quantity); err != nil {
tx.Rollback()
return nil, fmt.Errorf("库存验证失败: %w", err)
}
// 创建订单记录
order := &Order{
UserID: req.UserID,
ProductID: req.ProductID,
Quantity: req.Quantity,
Status: constants.OrderStatusPending,
}
if err := tx.Create(order).Error; err != nil {
tx.Rollback()
s.logger.Error("创建订单失败",
zap.String("user_id", req.UserID),
zap.Error(err))
return nil, err
}
tx.Commit()
s.logger.Info("订单创建成功",
zap.String("order_id", order.ID),
zap.String("user_id", req.UserID))
return order, nil
}
``` ```
**正确的中文日志使用：** **正确的中文日志使用：**
@@ -300,10 +265,6 @@ logger.Info("服务启动成功",
zap.String("host", cfg.Server.Host), zap.String("host", cfg.Server.Host),
zap.Int("port", cfg.Server.Port)) zap.Int("port", cfg.Server.Port))
logger.Info("配置热重载成功",
zap.String("config_file", "config.yaml"),
zap.Time("reload_time", time.Now()))
// 警告日志 // 警告日志
logger.Warn("Redis 连接延迟较高", logger.Warn("Redis 连接延迟较高",
zap.Duration("latency", latency), zap.Duration("latency", latency),
@@ -314,95 +275,6 @@ logger.Error("数据库连接失败",
zap.String("host", cfg.DB.Host), zap.String("host", cfg.DB.Host),
zap.Int("port", cfg.DB.Port), zap.Int("port", cfg.DB.Port),
zap.Error(err)) zap.Error(err))
logger.Error("令牌验证失败",
zap.String("token", token[:10]+"..."),
zap.String("client_ip", clientIP),
zap.Error(err))
// 调试日志
logger.Debug("处理用户请求",
zap.String("request_id", requestID),
zap.String("method", c.Method()),
zap.String("path", c.Path()),
zap.String("user_id", userID))
```
**用户可见错误消息（双语支持）：**
```go
// pkg/errors/codes.go
var errorMessages = map[int]ErrorMessage{
CodeSuccess: {"Success", "成功"},
CodeInternalError: {"Internal server error", "内部服务器错误"},
CodeMissingToken: {"Missing authentication token", "缺失认证令牌"},
CodeInvalidToken: {"Invalid or expired token", "令牌无效或已过期"},
CodeTooManyRequests: {"Too many requests", "请求过于频繁"},
CodeAuthServiceUnavailable: {"Authentication service unavailable", "认证服务不可用"},
}
// 使用时根据语言返回对应消息
message := errors.GetMessage(code, "zh") // 返回中文消息
```
**错误的英文注释（不推荐）：**
```go
// ❌ 全英文注释（可读性较差，不便于中文团队维护）
// GetUserByID retrieves user information by user ID
// Returns NotFoundError if user does not exist
func (s *Service) GetUserByID(ctx context.Context, id string) (*User, error) {
// Validate parameters
if id == "" {
return nil, errors.New(errors.CodeInvalidParam, "用户 ID 不能为空")
}
// Fetch user from store
user, err := s.store.GetByID(ctx, id)
if err != nil {
s.logger.Error("Failed to get user", // ❌ 英文日志
zap.String("user_id", id),
zap.Error(err))
return nil, fmt.Errorf("failed to get user: %w", err)
}
return user, nil
}
```
**例外情况（可使用英文）：**
```go
// ✅ 导出的包级别文档注释可使用英文（生态兼容性）
// Package user provides user management functionality.
// It includes user CRUD operations, authentication, and authorization.
package user
// ✅ 导出的 API 文档注释可使用英文
// UserService provides user-related business logic operations.
type UserService struct {
store UserStorer
logger *zap.Logger
}
// ✅ 但内部实现注释应使用中文
func (s *UserService) Create(ctx context.Context, req *CreateUserRequest) (*User, error) {
// 验证用户输入
if err := req.Validate(); err != nil {
return nil, err
}
// 检查用户是否已存在
existing, _ := s.store.GetByEmail(ctx, req.Email)
if existing != nil {
return nil, errors.New(errors.CodeUserExists, "用户邮箱已存在")
}
// 创建用户记录
user := &User{
Name: req.Name,
Email: req.Email,
}
return s.store.Create(ctx, user)
}
``` ```
**理由 (RATIONALE):** **理由 (RATIONALE):**
@@ -417,6 +289,12 @@ func (s *UserService) Create(ctx context.Context, req *CreateUserRequest) (*User
5. **统一业务规则**：确保所有地方使用相同的业务规则值 5. **统一业务规则**：确保所有地方使用相同的业务规则值
6. "3 次规则"提供明确的阈值，避免过早优化，同时确保重复值被及时抽取 6. "3 次规则"提供明确的阈值，避免过早优化，同时确保重复值被及时抽取
使用中文注释和日志的理由：
1. **提高团队效率**：中文开发团队阅读中文注释更快速准确
2. **降低理解成本**：减少翻译和理解偏差
3. **改善调试体验**：中文日志更易于排查问题
4. **保持生态兼容**：导出 API 的文档注释可保留英文
--- ---
### III. Testing Standards (测试标准) ### III. Testing Standards (测试标准)
@@ -950,6 +828,111 @@ Go 语言的设计哲学强调简单性、直接性和实用性。Java 风格的
--- ---
### VII. Documentation Standards (文档规范)
**规则 (RULES):**
- 每个功能完成后 **MUST** 在 `docs/` 目录创建总结文档
- 总结文档路径 **MUST** 遵循规范：`docs/{feature-id}/` 对应 `specs/{feature-id}/`
- 总结文档文件名 **MUST** 使用中文命名（例如：`功能总结.md`、`使用指南.md`、`架构说明.md`）
- 总结文档内容 **MUST** 使用中文编写
- 每次添加新功能总结文档时 **MUST** 同步更新 `README.md`
- `README.md` 中的功能描述 **MUST** 简短精炼，让首次接触项目的开发者能快速了解
- `README.md` 的功能描述 **SHOULD** 控制在 2-3 句话以内
**文档结构示例：**
```
specs/001-fiber-middleware-integration/ # 功能规划文档（设计阶段）
├── spec.md
├── plan.md
├── tasks.md
└── quickstart.md
docs/001-fiber-middleware-integration/ # 功能总结文档（完成阶段）
├── 功能总结.md # 功能概述和实现要点
├── 使用指南.md # 如何使用该功能
└── 架构说明.md # 架构设计和技术决策（可选）
README.md # 项目主文档
## 核心功能
- **认证中间件**：基于 Redis 的 Token 认证
- **限流中间件**：基于 IP 的限流，支持可配置的限制和存储后端
```
**正确的文档组织：**
```markdown
<!-- docs/002-user-management/功能总结.md -->
# 用户管理功能总结
## 功能概述
实现了完整的用户 CRUD 操作，包括用户创建、查询、更新、删除和列表分页。
## 核心实现
- Handler: `internal/handler/user.go`
- Service: `internal/service/user.go`
- Store: `internal/store/postgres/user.go`
- Model: `internal/model/user.go`
## API 端点
- `POST /api/v1/users` - 创建用户
- `GET /api/v1/users/:id` - 获取用户
- `PUT /api/v1/users/:id` - 更新用户
- `DELETE /api/v1/users/:id` - 删除用户
- `GET /api/v1/users` - 用户列表（分页）
## 技术要点
- 使用 GORM 进行数据访问
- 使用 Validator 进行参数验证
- 支持事务处理
- 统一错误处理和响应格式
详细使用说明请参阅 [使用指南.md](./使用指南.md)
```
```markdown
<!-- README.md 更新示例 -->
## 核心功能
- **认证中间件**：基于 Redis 的 Token 认证
- **限流中间件**：IP 限流，支持 Memory 和 Redis 存储
- **用户管理**：完整的用户 CRUD 和分页列表功能
- **日志系统**：Zap 结构化日志，自动轮转和请求追踪
详细文档：
- [认证中间件](docs/001-fiber-middleware-integration/功能总结.md)
- [用户管理](docs/002-user-management/功能总结.md)
```
**错误的文档组织（禁止）：**
```
❌ docs/feature-summary.md # 所有功能混在一个文件
❌ docs/001-summary.md # 英文命名
❌ docs/001/summary.md # 英文内容
❌ specs/001.../implementation.md # 总结文档放在 specs/ 下
❌ README.md 中没有更新新功能 # 遗漏 README 更新
❌ README.md 功能描述过长（超过 5 句话） # 描述冗长
```
**README.md 更新要求：**
- **简洁性**：每个功能 2-3 句话描述核心价值
- **可读性**：使用中文，便于中文开发者快速理解
- **链接性**：提供到详细文档的链接
- **分类性**：按功能模块分组（如"核心功能"、"中间件"、"业务模块"等）
**理由 (RATIONALE):**
统一的文档结构使新成员快速了解项目功能和架构。中文文档降低中文团队的阅读门槛，提高协作效率。将总结文档与设计文档分离（`docs/` vs `specs/`），清晰区分"计划做什么"和"做了什么"。强制更新 README.md 确保项目主文档始终反映最新功能。简短的 README 描述让首次接触项目的开发者能在 5 分钟内了解项目全貌。
---
## Development Workflow (开发工作流程) ## Development Workflow (开发工作流程)
### 分支管理 ### 分支管理
@@ -980,6 +963,7 @@ Go 语言的设计哲学强调简单性、直接性和实用性。Java 风格的
- 无安全漏洞（SQL 注入、XSS、命令注入等） - 无安全漏洞（SQL 注入、XSS、命令注入等）
- 性能影响可接受 - 性能影响可接受
- 代码通过 `gofmt`、`go vet`、`golangci-lint` 检查 - 代码通过 `gofmt`、`go vet`、`golangci-lint` 检查
- **文档已按规范更新（docs/ 和 README.md）**
--- ---
@@ -1004,6 +988,8 @@ Go 语言的设计哲学强调简单性、直接性和实用性。Java 风格的
- [ ] **无 Java 风格反模式**（无 getter/setter、无不必要接口、无过度抽象） - [ ] **无 Java 风格反模式**（无 getter/setter、无不必要接口、无过度抽象）
- [ ] **遵循 Go 命名约定**（缩写大小写一致、包名简短、无下划线） - [ ] **遵循 Go 命名约定**（缩写大小写一致、包名简短、无下划线）
- [ ] **使用 Go 惯用并发模式**（goroutines/channels，无线程池类） - [ ] **使用 Go 惯用并发模式**（goroutines/channels，无线程池类）
- [ ] **功能总结文档已创建**（在 `docs/{feature-id}/` 目录下，中文命名和内容）
- [ ] **README.md 已更新**（添加功能简短描述，2-3 句话）
### 上线前检查 ### 上线前检查
@@ -1038,12 +1024,13 @@ Go 语言的设计哲学强调简单性、直接性和实用性。Java 风格的
- 违反宪章的代码 **MUST** 在合并前修正 - 违反宪章的代码 **MUST** 在合并前修正
- 特别关注 Go 惯用法原则，拒绝 Java 风格的代码 - 特别关注 Go 惯用法原则，拒绝 Java 风格的代码
- 特别关注常量使用规范，拒绝不必要的硬编码 - 特别关注常量使用规范，拒绝不必要的硬编码
- 特别关注文档规范，确保每个功能都有完整的中文文档
- 任何复杂性增加（新依赖、新架构层）**MUST** 在设计文档中明确说明必要性 - 任何复杂性增加（新依赖、新架构层）**MUST** 在设计文档中明确说明必要性
### 运行时开发指导 ### 运行时开发指导
开发时参考本宪章确保一致性。如有疑问，优先遵守原则，再讨论例外情况。记住：**写 Go 代码，不是用 Go 语法写 Java**。记住：**定义常量是为了使用，不是为了装饰**。 开发时参考本宪章确保一致性。如有疑问，优先遵守原则，再讨论例外情况。记住：**写 Go 代码，不是用 Go 语法写 Java**。记住：**定义常量是为了使用，不是为了装饰**。记住：**写文档是为了团队协作，不是为了应付检查**。
--- ---
**Version**: 2.1.1 | **Ratified**: 2025-11-10 | **Last Amended**: 2025-11-11 **Version**: 2.2.0 | **Ratified**: 2025-11-10 | **Last Amended**: 2025-11-11

18
.specify/templates/plan-template.md
View File

@@ -59,6 +59,13 @@
- [ ] Code formatted with `gofmt` - [ ] Code formatted with `gofmt`
- [ ] Follows Effective Go and Go Code Review Comments - [ ] Follows Effective Go and Go Code Review Comments
**Documentation Standards** (Constitution Principle VII):
- [ ] Feature summary docs placed in `docs/{feature-id}/` mirroring `specs/{feature-id}/`
- [ ] Summary doc filenames use Chinese (功能总结.md, 使用指南.md, etc.)
- [ ] Summary doc content uses Chinese
- [ ] README.md updated with brief Chinese summary (2-3 sentences)
- [ ] Documentation is concise for first-time contributors
**Go Idiomatic Design**: **Go Idiomatic Design**:
- [ ] Package structure is flat (max 2-3 levels), organized by feature - [ ] Package structure is flat (max 2-3 levels), organized by feature
- [ ] Interfaces are small (1-3 methods), defined at use site - [ ] Interfaces are small (1-3 methods), defined at use site
@@ -105,6 +112,7 @@
### Documentation (this feature) ### Documentation (this feature)
**设计文档（specs/ 目录）**：开发前的规划和设计
```text ```text
specs/[###-feature]/ specs/[###-feature]/
├── plan.md # This file (/speckit.plan command output) ├── plan.md # This file (/speckit.plan command output)
@@ -115,6 +123,16 @@ specs/[###-feature]/
└── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan) └── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
``` ```
**总结文档（docs/ 目录）**：开发完成后的总结和使用指南（遵循 Constitution Principle VII）
```text
docs/[###-feature]/
├── 功能总结.md # 功能概述、核心实现、技术要点（MUST 使用中文命名和内容）
├── 使用指南.md # 如何使用该功能的详细说明（MUST 使用中文命名和内容）
└── 架构说明.md # 架构设计和技术决策（可选，MUST 使用中文命名和内容）
```
**README.md 更新**：每次完成功能后 MUST 在 README.md 添加简短描述（2-3 句话，中文）
### Source Code (repository root) ### Source Code (repository root)
<!-- <!--
ACTION REQUIRED: Replace the placeholder tree below with the concrete layout ACTION REQUIRED: Replace the placeholder tree below with the concrete layout

13
.specify/templates/tasks-template.md
View File

@@ -166,7 +166,15 @@ Foundational tasks for 君鸿卡管系统 tech stack:
**Purpose**: Improvements that affect multiple user stories and final quality checks **Purpose**: Improvements that affect multiple user stories and final quality checks
- [ ] TXXX [P] Documentation updates in docs/ ### Documentation (Constitution Principle VII - REQUIRED)
- [ ] TXXX [P] Create feature summary doc in docs/{feature-id}/功能总结.md (Chinese filename and content)
- [ ] TXXX [P] Create usage guide in docs/{feature-id}/使用指南.md (Chinese filename and content)
- [ ] TXXX [P] Create architecture doc in docs/{feature-id}/架构说明.md (optional, Chinese filename and content)
- [ ] TXXX Update README.md with brief feature description (2-3 sentences in Chinese)
### Code Quality
- [ ] TXXX Code cleanup and refactoring - [ ] TXXX Code cleanup and refactoring
- [ ] TXXX Performance optimization and load testing (verify P95 < 200ms, P99 < 500ms) - [ ] TXXX Performance optimization and load testing (verify P95 < 200ms, P99 < 500ms)
- [ ] TXXX [P] Additional unit tests to reach 70%+ coverage (90%+ for core business) - [ ] TXXX [P] Additional unit tests to reach 70%+ coverage (90%+ for core business)
@@ -190,6 +198,9 @@ Foundational tasks for 君鸿卡管系统 tech stack:
- [ ] TXXX Quality Gate: Verify Go naming conventions (UserID not userId, HTTPServer not HttpServer) - [ ] TXXX Quality Gate: Verify Go naming conventions (UserID not userId, HTTPServer not HttpServer)
- [ ] TXXX Quality Gate: Verify error handling is explicit (no panic/recover abuse) - [ ] TXXX Quality Gate: Verify error handling is explicit (no panic/recover abuse)
- [ ] TXXX Quality Gate: Verify uses goroutines/channels (not thread pool patterns) - [ ] TXXX Quality Gate: Verify uses goroutines/channels (not thread pool patterns)
- [ ] TXXX Quality Gate: Verify feature summary docs created in docs/{feature-id}/ with Chinese filenames
- [ ] TXXX Quality Gate: Verify summary doc content uses Chinese
- [ ] TXXX Quality Gate: Verify README.md updated with brief feature description (2-3 sentences)
--- ---