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

新增 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
2025-11-11 17:24:12 +08:00
parent 2d29e8f7c9
commit 2b1754728f
3 changed files with 174 additions and 158 deletions
--- a/.specify/memory/constitution.md
+++ b/.specify/memory/constitution.md
@@ -1,36 +1,42 @@
 <!--
 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

-MODIFIED PRINCIPLES:
- II. Code Quality Standards → Added "中文注释和输出规范" (Chinese Comments and Output Standards)
+NEW PRINCIPLES ADDED:
+- VII. Documentation Standards (文档规范) - NEW principle for feature documentation

-EXPANDED SECTIONS:
- Added "中文注释和输出规范" subsection to Principle II
-  - Rule: Code comments SHOULD be in Chinese for Chinese-speaking developers
-  - Rule: Log messages SHOULD be in Chinese
-  - Rule: User-facing error messages MUST be in Chinese (with bilingual support)
-  - Rule: Internal error messages and debug logs SHOULD be in Chinese
-  - Exceptions: Go doc comments for exported APIs may remain in English for ecosystem compatibility
-  - Examples of correct Chinese comments and log messages
-  - Rationale for Chinese-first approach
+MODIFIED SECTIONS:
+- Added new Principle VII with documentation structure and language requirements
+  - Rule: Summary docs MUST be placed in docs/{feature-id}/ mirroring specs/{feature-id}/
+  - Rule: Summary doc filenames MUST use Chinese
+  - Rule: Summary doc content MUST use Chinese
+  - Rule: README.md MUST be updated with brief Chinese summary for each feature
+  - Rule: Summary should be concise enough for first-time contributors to understand quickly
+  - Examples of correct documentation structure and naming
+  - Rationale for centralized Chinese documentation

 TEMPLATES REQUIRING UPDATES:
-✅ .specify/templates/plan-template.md - Will add Chinese comments check
-✅ .specify/templates/spec-template.md - Will add Chinese output requirement
-✅ .specify/templates/tasks-template.md - Will add Chinese usage quality gate
+✅ .specify/templates/plan-template.md - Added documentation structure guidance
+✅ .specify/templates/spec-template.md - No changes needed
+✅ .specify/templates/tasks-template.md - Added documentation task template in Polish phase

 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:
-PATCH version bump (2.1.1) - Clarification of existing code quality standards to
-prefer Chinese for comments and logs, targeting Chinese-speaking development team.
-This is not a breaking change but a refinement of communication standards within
-Principle II. The rule acknowledges the project's primary audience (Chinese developers)
-while maintaining ecosystem compatibility for exported APIs.
+MINOR version bump (2.2.0) - New principle added for documentation standards.
+This is a new governance rule that establishes how feature documentation should be
+organized, named, and written. The principle addresses:
+1. Documentation location consistency (docs/ mirrors specs/)
+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
@@ -250,47 +256,6 @@ func (s *Service) GetUserByID(ctx context.Context, id string) (*User, error) {
    
    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.Int("port", cfg.Server.Port))

-logger.Info("配置热重载成功",
-    zap.String("config_file", "config.yaml"),
-    zap.Time("reload_time", time.Now()))
-
 // 警告日志
 logger.Warn("Redis 连接延迟较高",
    zap.Duration("latency", latency),
@@ -314,95 +275,6 @@ logger.Error("数据库连接失败",
    zap.String("host", cfg.DB.Host),
    zap.Int("port", cfg.DB.Port),
    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):**
@@ -417,6 +289,12 @@ func (s *UserService) Create(ctx context.Context, req *CreateUserRequest) (*User
 5. **统一业务规则**：确保所有地方使用相同的业务规则值
 6. "3 次规则"提供明确的阈值，避免过早优化，同时确保重复值被及时抽取

+使用中文注释和日志的理由：
+1. **提高团队效率**：中文开发团队阅读中文注释更快速准确
+2. **降低理解成本**：减少翻译和理解偏差
+3. **改善调试体验**：中文日志更易于排查问题
+4. **保持生态兼容**：导出 API 的文档注释可保留英文
+
 ---

 ### 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 (开发工作流程)

 ### 分支管理
@@ -980,6 +963,7 @@ Go 语言的设计哲学强调简单性、直接性和实用性。Java 风格的
  - 无安全漏洞（SQL 注入、XSS、命令注入等）
  - 性能影响可接受
  - 代码通过 `gofmt`、`go vet`、`golangci-lint` 检查
+  - **文档已按规范更新（docs/ 和 README.md）**

 ---

@@ -1004,6 +988,8 @@ Go 语言的设计哲学强调简单性、直接性和实用性。Java 风格的
 - [ ] **无 Java 风格反模式**（无 getter/setter、无不必要接口、无过度抽象）
 - [ ] **遵循 Go 命名约定**（缩写大小写一致、包名简短、无下划线）
 - [ ] **使用 Go 惯用并发模式**（goroutines/channels，无线程池类）
+- [ ] **功能总结文档已创建**（在 `docs/{feature-id}/` 目录下，中文命名和内容）
+- [ ] **README.md 已更新**（添加功能简短描述，2-3 句话）

 ### 上线前检查

@@ -1038,12 +1024,13 @@ Go 语言的设计哲学强调简单性、直接性和实用性。Java 风格的
 - 违反宪章的代码 **MUST** 在合并前修正
 - 特别关注 Go 惯用法原则，拒绝 Java 风格的代码
 - 特别关注常量使用规范，拒绝不必要的硬编码
+- 特别关注文档规范，确保每个功能都有完整的中文文档
 - 任何复杂性增加（新依赖、新架构层）**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
--- a/.specify/templates/plan-template.md
+++ b/.specify/templates/plan-template.md
@@ -59,6 +59,13 @@
 - [ ] Code formatted with `gofmt`
 - [ ] 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**:
 - [ ] Package structure is flat (max 2-3 levels), organized by feature
 - [ ] Interfaces are small (1-3 methods), defined at use site
@@ -105,6 +112,7 @@

 ### Documentation (this feature)

+**设计文档（specs/ 目录）**：开发前的规划和设计
 ```text
 specs/[###-feature]/
 ├── 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)
 ```

+**总结文档（docs/ 目录）**：开发完成后的总结和使用指南（遵循 Constitution Principle VII）
+```text
+docs/[###-feature]/
+├── 功能总结.md          # 功能概述、核心实现、技术要点（MUST 使用中文命名和内容）
+├── 使用指南.md          # 如何使用该功能的详细说明（MUST 使用中文命名和内容）
+└── 架构说明.md          # 架构设计和技术决策（可选，MUST 使用中文命名和内容）
+```
+
+**README.md 更新**：每次完成功能后 MUST 在 README.md 添加简短描述（2-3 句话，中文）
+
 ### Source Code (repository root)
 <!--
  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
--- a/.specify/templates/tasks-template.md
+++ b/.specify/templates/tasks-template.md
@@ -166,7 +166,15 @@ Foundational tasks for 君鸿卡管系统 tech stack:

 **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 Performance optimization and load testing (verify P95 < 200ms, P99 < 500ms)
 - [ ] 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 error handling is explicit (no panic/recover abuse)
 - [ ] 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)

 ---