@pzy560117/codex-harness 0.1.3 → 0.1.4

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/examples/go-microservice-CLAUDE.md

@@ -1,267 +0,0 @@
-# Go 微服务 — 项目 CLAUDE.md
-
-> 一个使用 PostgreSQL、gRPC 和 Docker 的 Go 微服务真实示例。
-> 将此文件复制到您的项目根目录，并根据您的服务进行自定义。
-
-## 项目概述
-
-**技术栈:** Go 1.22+, PostgreSQL, gRPC + REST (grpc-gateway), Docker, sqlc (类型安全的 SQL), Wire (依赖注入)
-
-**架构:** 采用领域、仓库、服务和处理器层的清晰架构。gRPC 作为主要传输方式，REST 网关用于外部客户端。
-
-## 关键规则
-
-### Go 规范
-
-* 遵循 Effective Go 和 Go Code Review Comments 指南
-* 使用 `errors.New` / `fmt.Errorf` 配合 `%w` 进行包装 — 绝不对错误进行字符串匹配
-* 不使用 `init()` 函数 — 在 `main()` 或构造函数中进行显式初始化
-* 没有全局可变状态 — 通过构造函数传递依赖项
-* Context 必须是第一个参数，并在所有层中传播
-
-### 数据库
-
-* `queries/` 中的所有查询都使用纯 SQL — sqlc 生成类型安全的 Go 代码
-* 在 `migrations/` 中使用 golang-migrate 进行迁移 — 绝不直接更改数据库
-* 通过 `pgx.Tx` 为多步骤操作使用事务
-* 所有查询必须使用参数化占位符 (`$1`, `$2`) — 绝不使用字符串格式化
-
-### 错误处理
-
-* 返回错误，不要 panic — panic 仅用于真正无法恢复的情况
-* 使用上下文包装错误：`fmt.Errorf("creating user: %w", err)`
-* 在 `domain/errors.go` 中定义业务逻辑的哨兵错误
-* 在处理器层将领域错误映射到 gRPC 状态码
-
-```go
-// Domain layer — sentinel errors
-var (
-    ErrUserNotFound  = errors.New("user not found")
-    ErrEmailTaken    = errors.New("email already registered")
-)
-
-// Handler layer — map to gRPC status
-func toGRPCError(err error) error {
-    switch {
-    case errors.Is(err, domain.ErrUserNotFound):
-        return status.Error(codes.NotFound, err.Error())
-    case errors.Is(err, domain.ErrEmailTaken):
-        return status.Error(codes.AlreadyExists, err.Error())
-    default:
-        return status.Error(codes.Internal, "internal error")
-    }
-}
-```
-
-### 代码风格
-
-* 代码或注释中不使用表情符号
-* 导出的类型和函数必须有文档注释
-* 函数保持在 50 行以内 — 提取辅助函数
-* 对所有具有多个用例的逻辑使用表格驱动测试
-* 对于信号通道，优先使用 `struct{}`，而不是 `bool`
-
-## 文件结构
-
-```
-cmd/
-  server/
-    main.go              # 入口点，Wire注入，优雅关闭
-internal/
-  domain/                # 业务类型和接口
-    user.go              # 用户实体和仓库接口
-    errors.go            # 哨兵错误
-  service/               # 业务逻辑
-    user_service.go
-    user_service_test.go
-  repository/            # 数据访问（sqlc生成 + 自定义）
-    postgres/
-      user_repo.go
-      user_repo_test.go  # 使用testcontainers的集成测试
-  handler/               # gRPC + REST处理程序
-    grpc/
-      user_handler.go
-    rest/
-      user_handler.go
-  config/                # 配置加载
-    config.go
-proto/                   # Protobuf定义
-  user/v1/
-    user.proto
-queries/                 # sqlc的SQL查询
-  user.sql
-migrations/              # 数据库迁移
-  001_create_users.up.sql
-  001_create_users.down.sql
-```
-
-## 关键模式
-
-### 仓库接口
-
-```go
-type UserRepository interface {
-    Create(ctx context.Context, user *User) error
-    FindByID(ctx context.Context, id uuid.UUID) (*User, error)
-    FindByEmail(ctx context.Context, email string) (*User, error)
-    Update(ctx context.Context, user *User) error
-    Delete(ctx context.Context, id uuid.UUID) error
-}
-```
-
-### 使用依赖注入的服务
-
-```go
-type UserService struct {
-    repo   domain.UserRepository
-    hasher PasswordHasher
-    logger *slog.Logger
-}
-
-func NewUserService(repo domain.UserRepository, hasher PasswordHasher, logger *slog.Logger) *UserService {
-    return &UserService{repo: repo, hasher: hasher, logger: logger}
-}
-
-func (s *UserService) Create(ctx context.Context, req CreateUserRequest) (*domain.User, error) {
-    existing, err := s.repo.FindByEmail(ctx, req.Email)
-    if err != nil && !errors.Is(err, domain.ErrUserNotFound) {
-        return nil, fmt.Errorf("checking email: %w", err)
-    }
-    if existing != nil {
-        return nil, domain.ErrEmailTaken
-    }
-
-    hashed, err := s.hasher.Hash(req.Password)
-    if err != nil {
-        return nil, fmt.Errorf("hashing password: %w", err)
-    }
-
-    user := &domain.User{
-        ID:       uuid.New(),
-        Name:     req.Name,
-        Email:    req.Email,
-        Password: hashed,
-    }
-    if err := s.repo.Create(ctx, user); err != nil {
-        return nil, fmt.Errorf("creating user: %w", err)
-    }
-    return user, nil
-}
-```
-
-### 表格驱动测试
-
-```go
-func TestUserService_Create(t *testing.T) {
-    tests := []struct {
-        name    string
-        req     CreateUserRequest
-        setup   func(*MockUserRepo)
-        wantErr error
-    }{
-        {
-            name: "valid user",
-            req:  CreateUserRequest{Name: "Alice", Email: "alice@example.com", Password: "secure123"},
-            setup: func(m *MockUserRepo) {
-                m.On("FindByEmail", mock.Anything, "alice@example.com").Return(nil, domain.ErrUserNotFound)
-                m.On("Create", mock.Anything, mock.Anything).Return(nil)
-            },
-            wantErr: nil,
-        },
-        {
-            name: "duplicate email",
-            req:  CreateUserRequest{Name: "Alice", Email: "taken@example.com", Password: "secure123"},
-            setup: func(m *MockUserRepo) {
-                m.On("FindByEmail", mock.Anything, "taken@example.com").Return(&domain.User{}, nil)
-            },
-            wantErr: domain.ErrEmailTaken,
-        },
-    }
-
-    for _, tt := range tests {
-        t.Run(tt.name, func(t *testing.T) {
-            repo := new(MockUserRepo)
-            tt.setup(repo)
-            svc := NewUserService(repo, &bcryptHasher{}, slog.Default())
-
-            _, err := svc.Create(context.Background(), tt.req)
-
-            if tt.wantErr != nil {
-                assert.ErrorIs(t, err, tt.wantErr)
-            } else {
-                assert.NoError(t, err)
-            }
-        })
-    }
-}
-```
-
-## 环境变量
-
-```bash
-# Database
-DATABASE_URL=postgres://user:pass@localhost:5432/myservice?sslmode=disable
-
-# gRPC
-GRPC_PORT=50051
-REST_PORT=8080
-
-# Auth
-JWT_SECRET=           # Load from vault in production
-TOKEN_EXPIRY=24h
-
-# Observability
-LOG_LEVEL=info        # debug, info, warn, error
-OTEL_ENDPOINT=        # OpenTelemetry collector
-```
-
-## 测试策略
-
-```bash
-/go-test             # TDD workflow for Go
-/go-review           # Go-specific code review
-/go-build            # Fix build errors
-```
-
-### 测试命令
-
-```bash
-# Unit tests (fast, no external deps)
-go test ./internal/... -short -count=1
-
-# Integration tests (requires Docker for testcontainers)
-go test ./internal/repository/... -count=1 -timeout 120s
-
-# All tests with coverage
-go test ./... -coverprofile=coverage.out -count=1
-go tool cover -func=coverage.out  # summary
-go tool cover -html=coverage.out  # browser
-
-# Race detector
-go test ./... -race -count=1
-```
-
-## ECC 工作流
-
-```bash
-# Planning
-/plan "Add rate limiting to user endpoints"
-
-# Development
-/go-test                  # TDD with Go-specific patterns
-
-# Review
-/go-review                # Go idioms, error handling, concurrency
-/security-scan            # Secrets and vulnerabilities
-
-# Before merge
-go vet ./...
-staticcheck ./...
-```
-
-## Git 工作流
-
-* `feat:` 新功能，`fix:` 错误修复，`refactor:` 代码更改
-* 从 `main` 创建功能分支，需要 PR
-* CI: `go vet`, `staticcheck`, `go test -race`, `golangci-lint`
-* 部署: 在 CI 中构建 Docker 镜像，部署到 Kubernetes

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/examples/rust-api-CLAUDE.md

@@ -1,285 +0,0 @@
-# Rust API 服务 — 项目 CLAUDE.md
-
-> 使用 Axum、PostgreSQL 和 Docker 构建 Rust API 服务的真实示例。
-> 将此文件复制到您的项目根目录，并根据您的服务进行自定义。
-
-## 项目概述
-
-**技术栈：** Rust 1.78+, Axum (Web 框架), SQLx (异步数据库), PostgreSQL, Tokio (异步运行时), Docker
-
-**架构：** 采用分层架构，包含 handler → service → repository 分离。Axum 用于 HTTP，SQLx 用于编译时类型检查的 SQL，Tower 中间件用于横切关注点。
-
-## 关键规则
-
-### Rust 约定
-
-* 库错误使用 `thiserror`，仅在二进制 crate 或测试中使用 `anyhow`
-* 生产代码中不使用 `.unwrap()` 或 `.expect()` — 使用 `?` 传播错误
-* 函数参数中优先使用 `&str` 而非 `String`；所有权转移时返回 `String`
-* 使用 `clippy` 和 `#![deny(clippy::all, clippy::pedantic)]` — 修复所有警告
-* 在所有公共类型上派生 `Debug`；仅在需要时派生 `Clone`、`PartialEq`
-* 除非有 `// SAFETY:` 注释说明理由，否则不使用 `unsafe` 块
-
-### 数据库
-
-* 所有查询使用 SQLx 的 `query!` 或 `query_as!` 宏 — 针对模式进行编译时验证
-* 在 `migrations/` 中使用 `sqlx migrate` 进行迁移 — 切勿直接修改数据库
-* 使用 `sqlx::Pool<Postgres>` 作为共享状态 — 切勿为每个请求创建连接
-* 所有查询使用参数化占位符 (`$1`, `$2`) — 切勿使用字符串格式化
-
-```rust
-// BAD: String interpolation (SQL injection risk)
-let q = format!("SELECT * FROM users WHERE id = '{}'", id);
-
-// GOOD: Parameterized query, compile-time checked
-let user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id)
-    .fetch_optional(&pool)
-    .await?;
-```
-
-### 错误处理
-
-* 为每个模块使用 `thiserror` 定义一个领域错误枚举
-* 通过 `IntoResponse` 将错误映射到 HTTP 响应 — 切勿暴露内部细节
-* 使用 `tracing` 进行结构化日志记录 — 切勿使用 `println!` 或 `eprintln!`
-
-```rust
-use thiserror::Error;
-
-#[derive(Debug, Error)]
-pub enum AppError {
-    #[error("Resource not found")]
-    NotFound,
-    #[error("Validation failed: {0}")]
-    Validation(String),
-    #[error("Unauthorized")]
-    Unauthorized,
-    #[error(transparent)]
-    Internal(#[from] anyhow::Error),
-}
-
-impl IntoResponse for AppError {
-    fn into_response(self) -> Response {
-        let (status, message) = match &self {
-            Self::NotFound => (StatusCode::NOT_FOUND, self.to_string()),
-            Self::Validation(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
-            Self::Unauthorized => (StatusCode::UNAUTHORIZED, self.to_string()),
-            Self::Internal(err) => {
-                tracing::error!(?err, "internal error");
-                (StatusCode::INTERNAL_SERVER_ERROR, "Internal error".into())
-            }
-        };
-        (status, Json(json!({ "error": message }))).into_response()
-    }
-}
-```
-
-### 测试
-
-* 单元测试放在每个源文件内的 `#[cfg(test)]` 模块中
-* 集成测试放在 `tests/` 目录中，使用真实的 PostgreSQL (Testcontainers 或 Docker)
-* 使用 `#[sqlx::test]` 进行数据库测试，包含自动迁移和回滚
-* 使用 `mockall` 或 `wiremock` 模拟外部服务
-
-### 代码风格
-
-* 最大行长度：100 个字符（由 rustfmt 强制执行）
-* 导入分组：`std`、外部 crate、`crate`/`super` — 用空行分隔
-* 模块：每个模块一个文件，`mod.rs` 仅用于重新导出
-* 类型：PascalCase，函数/变量：snake\_case，常量：UPPER\_SNAKE\_CASE
-
-## 文件结构
-
-```
-src/
-  main.rs              # 入口点、服务器设置、优雅关闭
-  lib.rs               # 用于集成测试的重新导出
-  config.rs            # 使用 envy 或 figment 的环境配置
-  router.rs            # 包含所有路由的 Axum 路由器
-  middleware/
-    auth.rs            # JWT 提取与验证
-    logging.rs         # 请求/响应追踪
-  handlers/
-    mod.rs             # 路由处理器（精简版——委托给服务层）
-    users.rs
-    orders.rs
-  services/
-    mod.rs             # 业务逻辑
-    users.rs
-    orders.rs
-  repositories/
-    mod.rs             # 数据库访问（SQLx 查询）
-    users.rs
-    orders.rs
-  domain/
-    mod.rs             # 领域类型、错误枚举
-    user.rs
-    order.rs
-migrations/
-  001_create_users.sql
-  002_create_orders.sql
-tests/
-  common/mod.rs        # 共享测试辅助工具、测试服务器设置
-  api_users.rs         # 用户端点的集成测试
-  api_orders.rs        # 订单端点的集成测试
-```
-
-## 关键模式
-
-### Handler (薄层)
-
-```rust
-async fn create_user(
-    State(ctx): State<AppState>,
-    Json(payload): Json<CreateUserRequest>,
-) -> Result<(StatusCode, Json<UserResponse>), AppError> {
-    let user = ctx.user_service.create(payload).await?;
-    Ok((StatusCode::CREATED, Json(UserResponse::from(user))))
-}
-```
-
-### Service (业务逻辑)
-
-```rust
-impl UserService {
-    pub async fn create(&self, req: CreateUserRequest) -> Result<User, AppError> {
-        if self.repo.find_by_email(&req.email).await?.is_some() {
-            return Err(AppError::Validation("Email already registered".into()));
-        }
-
-        let password_hash = hash_password(&req.password)?;
-        let user = self.repo.insert(&req.email, &req.name, &password_hash).await?;
-
-        Ok(user)
-    }
-}
-```
-
-### Repository (数据访问)
-
-```rust
-impl UserRepository {
-    pub async fn find_by_email(&self, email: &str) -> Result<Option<User>, sqlx::Error> {
-        sqlx::query_as!(User, "SELECT * FROM users WHERE email = $1", email)
-            .fetch_optional(&self.pool)
-            .await
-    }
-
-    pub async fn insert(
-        &self,
-        email: &str,
-        name: &str,
-        password_hash: &str,
-    ) -> Result<User, sqlx::Error> {
-        sqlx::query_as!(
-            User,
-            r#"INSERT INTO users (email, name, password_hash)
-               VALUES ($1, $2, $3) RETURNING *"#,
-            email, name, password_hash,
-        )
-        .fetch_one(&self.pool)
-        .await
-    }
-}
-```
-
-### 集成测试
-
-```rust
-#[tokio::test]
-async fn test_create_user() {
-    let app = spawn_test_app().await;
-
-    let response = app
-        .client
-        .post(&format!("{}/api/v1/users", app.address))
-        .json(&json!({
-            "email": "alice@example.com",
-            "name": "Alice",
-            "password": "securepassword123"
-        }))
-        .send()
-        .await
-        .expect("Failed to send request");
-
-    assert_eq!(response.status(), StatusCode::CREATED);
-    let body: serde_json::Value = response.json().await.unwrap();
-    assert_eq!(body["email"], "alice@example.com");
-}
-
-#[tokio::test]
-async fn test_create_user_duplicate_email() {
-    let app = spawn_test_app().await;
-    // Create first user
-    create_test_user(&app, "alice@example.com").await;
-    // Attempt duplicate
-    let response = create_user_request(&app, "alice@example.com").await;
-    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
-}
-```
-
-## 环境变量
-
-```bash
-# Server
-HOST=0.0.0.0
-PORT=8080
-RUST_LOG=info,tower_http=debug
-
-# Database
-DATABASE_URL=postgres://user:pass@localhost:5432/myapp
-
-# Auth
-JWT_SECRET=your-secret-key-min-32-chars
-JWT_EXPIRY_HOURS=24
-
-# Optional
-CORS_ALLOWED_ORIGINS=http://localhost:3000
-```
-
-## 测试策略
-
-```bash
-# Run all tests
-cargo test
-
-# Run with output
-cargo test -- --nocapture
-
-# Run specific test module
-cargo test api_users
-
-# Check coverage (requires cargo-llvm-cov)
-cargo llvm-cov --html
-open target/llvm-cov/html/index.html
-
-# Lint
-cargo clippy -- -D warnings
-
-# Format check
-cargo fmt -- --check
-```
-
-## ECC 工作流
-
-```bash
-# Planning
-/plan "Add order fulfillment with Stripe payment"
-
-# Development with TDD
-/tdd                    # cargo test-based TDD workflow
-
-# Review
-/code-review            # Rust-specific code review
-/security-scan          # Dependency audit + unsafe scan
-
-# Verification
-/verify                 # Build, clippy, test, security scan
-```
-
-## Git 工作流
-
-* `feat:` 新功能，`fix:` 错误修复，`refactor:` 代码变更
-* 从 `main` 创建功能分支，需要 PR
-* CI：`cargo fmt --check`、`cargo clippy`、`cargo test`、`cargo audit`
-* 部署：使用 `scratch` 或 `distroless` 基础镜像的 Docker 多阶段构建

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/examples/saas-nextjs-CLAUDE.md

@@ -1,166 +0,0 @@
-# SaaS 应用程序 — 项目 CLAUDE.md
-
-> 一个 Next.js + Supabase + Stripe SaaS 应用程序的真实示例。
-> 将此复制到您的项目根目录，并根据您的技术栈进行自定义。
-
-## 项目概览
-
-**技术栈：** Next.js 15（App Router）、TypeScript、Supabase（身份验证 + 数据库）、Stripe（计费）、Tailwind CSS、Playwright（端到端测试）
-
-**架构：** 默认使用服务器组件。仅在需要交互性时使用客户端组件。API 路由用于 Webhook，服务器操作用于数据变更。
-
-## 关键规则
-
-### 数据库
-
-* 所有查询均使用启用 RLS 的 Supabase 客户端 — 绝不要绕过 RLS
-* 迁移在 `supabase/migrations/` 中 — 绝不要直接修改数据库
-* 使用带有明确列列表的 `select()`，而不是 `select('*')`
-* 所有面向用户的查询必须包含 `.limit()` 以防止返回无限制的结果
-
-### 身份验证
-
-* 在服务器组件中使用来自 `@supabase/ssr` 的 `createServerClient()`
-* 在客户端组件中使用来自 `@supabase/ssr` 的 `createBrowserClient()`
-* 受保护的路由检查 `getUser()` — 绝不要仅依赖 `getSession()` 进行身份验证
-* `middleware.ts` 中的中间件会在每个请求上刷新身份验证令牌
-
-### 计费
-
-* Stripe webhook 处理程序在 `app/api/webhooks/stripe/route.ts` 中
-* 绝不要信任客户端的定价数据 — 始终在服务器端从 Stripe 获取
-* 通过 `subscription_status` 列检查订阅状态，由 webhook 同步
-* 免费层用户：3 个项目，每天 100 次 API 调用
-
-### 代码风格
-
-* 代码或注释中不使用表情符号
-* 仅使用不可变模式 — 使用展开运算符，永不直接修改
-* 服务器组件：不使用 `'use client'` 指令，不使用 `useState`/`useEffect`
-* 客户端组件：`'use client'` 放在顶部，保持最小化 — 将逻辑提取到钩子中
-* 所有输入验证（API 路由、表单、环境变量）优先使用 Zod 模式
-
-## 文件结构
-
-```
-src/
-  app/
-    (auth)/          # 认证页面（登录、注册、忘记密码）
-    (dashboard)/     # 受保护的仪表板页面
-    api/
-      webhooks/      # Stripe、Supabase webhooks
-    layout.tsx       # 根布局（包含 providers）
-  components/
-    ui/              # Shadcn/ui 组件
-    forms/           # 带验证的表单组件
-    dashboard/       # 仪表板专用组件
-  hooks/             # 自定义 React hooks
-  lib/
-    supabase/        # Supabase 客户端工厂
-    stripe/          # Stripe 客户端与辅助工具
-    utils.ts         # 通用工具函数
-  types/             # 共享 TypeScript 类型
-supabase/
-  migrations/        # 数据库迁移
-  seed.sql           # 开发用种子数据
-```
-
-## 关键模式
-
-### API 响应格式
-
-```typescript
-type ApiResponse<T> =
-  | { success: true; data: T }
-  | { success: false; error: string; code?: string }
-```
-
-### 服务器操作模式
-
-```typescript
-'use server'
-
-import { z } from 'zod'
-import { createServerClient } from '@/lib/supabase/server'
-
-const schema = z.object({
-  name: z.string().min(1).max(100),
-})
-
-export async function createProject(formData: FormData) {
-  const parsed = schema.safeParse({ name: formData.get('name') })
-  if (!parsed.success) {
-    return { success: false, error: parsed.error.flatten() }
-  }
-
-  const supabase = await createServerClient()
-  const { data: { user } } = await supabase.auth.getUser()
-  if (!user) return { success: false, error: 'Unauthorized' }
-
-  const { data, error } = await supabase
-    .from('projects')
-    .insert({ name: parsed.data.name, user_id: user.id })
-    .select('id, name, created_at')
-    .single()
-
-  if (error) return { success: false, error: 'Failed to create project' }
-  return { success: true, data }
-}
-```
-
-## 环境变量
-
-```bash
-# Supabase
-NEXT_PUBLIC_SUPABASE_URL=
-NEXT_PUBLIC_SUPABASE_ANON_KEY=
-SUPABASE_SERVICE_ROLE_KEY=     # Server-only, never expose to client
-
-# Stripe
-STRIPE_SECRET_KEY=
-STRIPE_WEBHOOK_SECRET=
-NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
-
-# App
-NEXT_PUBLIC_APP_URL=http://localhost:3000
-```
-
-## 测试策略
-
-```bash
-/tdd                    # Unit + integration tests for new features
-/e2e                    # Playwright tests for auth flow, billing, dashboard
-/test-coverage          # Verify 80%+ coverage
-```
-
-### 关键的端到端测试流程
-
-1. 注册 → 邮箱验证 → 创建第一个项目
-2. 登录 → 仪表盘 → CRUD 操作
-3. 升级计划 → Stripe 结账 → 订阅激活
-4. Webhook：订阅取消 → 降级到免费层
-
-## ECC 工作流
-
-```bash
-# Planning a feature
-/plan "Add team invitations with email notifications"
-
-# Developing with TDD
-/tdd
-
-# Before committing
-/code-review
-/security-scan
-
-# Before release
-/e2e
-/test-coverage
-```
-
-## Git 工作流
-
-* `feat:` 新功能，`fix:` 错误修复，`refactor:` 代码变更
-* 从 `main` 创建功能分支，需要 PR
-* CI 运行：代码检查、类型检查、单元测试、端到端测试
-* 部署：在 PR 上部署到 Vercel 预览环境，在合并到 `main` 时部署到生产环境