团队工作流

wescode 帮助团队建立高效的协作工作流，涵盖代码规范、Review 流程、CI/CD 集成和知识共享。

功能概览

代码规范

项目规范配置

在项目根目录创建 .wescode/conventions.yaml 定义团队规范：

# .wescode/conventions.yaml
conventions:
  naming:
    # Go 命名规范
    packages: snake_case           # 包名使用小写
    exported_functions: PascalCase # 导出函数大驼峰
    variables: camelCase           # 变量小驼峰
    constants: ALL_CAPS            # 常量全大写（可选）

  structure:
    # 项目结构规范
    handler_layer: "internal/handler/"
    service_layer: "internal/service/"
    repository_layer: "internal/repository/"
    model_layer: "internal/model/"
    # 禁止跨层直接调用
    no_skip_layers: true

  error_handling:
    # 错误处理规范
    wrap_errors: true              # 错误必须 wrap
    custom_error_types: true       # 使用自定义错误类型
    no_panic_in_library: true      # 库代码禁止 panic

  testing:
    # 测试规范
    min_coverage: 70               # 最低覆盖率
    table_driven: true             # 优先使用表驱动测试
    test_naming: "Test<FuncName>_<Scenario>"

规范自动检查

AI 在你编码时自动检查规范合规性：

AI 提醒：
  ⚠ 规范违规：internal/handler/user.go
  - 第 15 行：Handler 直接调用 Repository，跳过了 Service 层
    规则：no_skip_layers
    修复：通过 UserService 中转

  ⚠ 命名建议：internal/service/order.go
  - 第 30 行：变量名 d 过于简短
    规则：variables should be descriptive
    建议：改为 discount 或 discountRate

团队规范文档生成

用户：生成团队编码规范文档

AI：生成 docs/coding-standards.md：

  # 编码规范

  ## 1. 项目结构

cmd/ — 程序入口，只做依赖注入和启动 internal/ ├── handler/ — HTTP 处理器（接收请求、返回响应） ├── service/ — 业务逻辑（核心规则、流程编排） ├── repository/ — 数据访问（数据库操作） └── model/ — 数据模型（领域实体）

规则：handler → service → repository，禁止跨层调用。

## 2. 命名规范

| 元素 | 规范 | 示例 |
|------|------|------|
| 包名 | 小写单词 | `userservice` |
| 接口 | 动词 + er | `Reader`, `UserFinder` |
| 导出函数 | 大驼峰 | `CreateOrder` |
| 私有函数 | 小驼峰 | `validateInput` |
| 常量 | 全大写 | `MaxRetryCount` |
| 错误变量 | Err 前缀 | `ErrNotFound` |

## 3. 错误处理

- 所有错误必须 wrap 上下文信息
- 使用自定义错误类型
- 禁止 `_ = err`

```go
// ✓ 正确
if err != nil {
    return fmt.Errorf("create order: %w", err)
}

// ✗ 错误
if err != nil {
    return err  // 缺少上下文
}

4. 测试规范

...

---

## Review 流程

### AI 辅助 Code Review

在提交 PR 前，让 AI 进行预审查：

用户：review 我的代码变更

AI：代码审查报告：

📋 变更概述 修改 5 个文件，新增 189 行，删除 34 行 涉及模块：auth、handler、service

✓ 优点：

• 错误处理完善，所有错误都有 wrap
• 测试覆盖了核心路径
• 命名清晰，代码可读性好

⚠ 建议改进（3 个）：

1. internal/service/auth.go:45 → 登录尝试没有记录审计日志 → 建议：添加登录事件记录（成功和失败）

2. internal/handler/auth.go:30 → 返回的 JSON 中包含了内部错误信息 → 建议：生产环境应返回通用错误，详细信息只记录日志

3. internal/service/auth_test.go → 缺少 token 过期场景的测试 → 建议：添加 TestLogin_ExpiredToken 测试用例

📊 质量评分：8/10 → 建议修复后再提交 PR

### Review Checklist

AI 会按照团队定义的 checklist 检查代码：

代码审查清单：

功能正确性 ✓ 实现了需求中的所有功能点 ✓ 边界条件处理正确 ✓ 错误情况有合理的返回

代码质量 ✓ 遵循项目命名规范 ✓ 没有重复代码 ⚠ 有一个函数超过 80 行，建议拆分

安全性 ✓ 无 SQL 注入风险 ✓ 无硬编码凭据 ⚠ 缺少输入长度限制

测试 ✓ 核心路径有测试 ⚠ 测试覆盖率 65%（低于 70% 标准） ✗ 缺少集成测试

文档 ✓ 新增的导出函数有注释 ⚠ README 未更新 API 变更

### Review 意见管理

用户：整理 PR 上的 review 意见

AI：Review 意见汇总：

需要修复（3 个）：

1. @reviewer1: 数据库查询缺少索引 [line 45] → 已创建 TODO，计划本次一起修复

2. @reviewer2: 并发场景未加锁 [line 78] → 需要讨论是否用 sync.Mutex 还是 channel

3. @reviewer1: 测试数据不应该硬编码 [line 120] → 改用 faker 库生成

讨论中（1 个）： 4. @reviewer2: 是否需要添加缓存？ → 当前 QPS 较低，建议 v2 再考虑

已完成（2 个）： 5. ✓ 变量命名修复 6. ✓ 日志级别调整

---

## CI/CD 集成

### CI 配置生成

用户：生成 GitHub Actions CI 配置

AI：生成 .github/workflows/ci.yml：

name: CI

on: push: branches: [main] pull_request: branches: [main]

jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-go@v5 with: go-version: '1.22' - name: Lint uses: golangci/golangci-lint-action@v6 with: version: latest

test:
  runs-on: ubuntu-latest
  services:
    postgres:
      image: postgres:16
      env:
        POSTGRES_PASSWORD: test
      ports:
        - 5432:5432
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-go@v5
      with:
        go-version: '1.22'
    - name: Run Tests
      run: go test -race -coverprofile=coverage.out ./...
      env:
        DB_HOST: localhost
        DB_PASSWORD: test
    - name: Check Coverage
      run: |
        go tool cover -func=coverage.out | tail -1
        # 检查覆盖率是否达标

security:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Security Scan
      run: |
        go install golang.org/x/vuln/cmd/govulncheck@latest
        govulncheck ./...

build:
  needs: [lint, test, security]
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Build
      run: make build

### CI 失败分析

用户：CI 挂了，帮我看看

AI：分析 CI 失败日志：

✗ test job 失败

失败测试：TestCreateOrder_ConcurrentAccess 错误： race detected during execution of test

分析： 在 service/order.go:89 存在数据竞争 两个 goroutine 同时访问 order.Status 字段

修复建议：

1. 为 Order 的状态变更添加互斥锁
2. 或使用 atomic 操作
3. 或重构为 channel 通信

→ 是否应用修复？

---

## 知识共享

### 项目知识库

wescode 的项目知识库（DocSync）自动索引项目中的文档和代码注释：

用户：项目中关于数据库迁移的规范是什么？

AI：根据项目知识库中的信息：

数据库迁移规范（来源：docs/database-migration.md）：

1. 迁移文件命名：{序号}_{描述}.{up|down}.sql 示例：004_add_user_phone.up.sql

2. 每个 up 迁移必须有对应的 down 迁移

3. 迁移必须幂等（可重复执行）

4. 禁止在迁移中删除列或表 → 先废弃，下个版本再删除

5. 大表变更使用 online DDL → ALTER TABLE ... ALGORITHM=INPLACE, LOCK=NONE

### 团队最佳实践积累

AI 会通过记忆系统记住团队的最佳实践：

用户：团队之前处理并发问题用的什么方案？

AI：根据记忆（agent_memory 层）：

团队并发处理惯例：

1. 简单计数器 → sync/atomic
2. 共享状态保护 → sync.RWMutex
3. 生产者-消费者 → buffered channel
4. 并发任务编排 → errgroup.Group
5. 超时控制 → context.WithTimeout

相关代码示例：

• internal/service/inventory.go — 使用 RWMutex 保护库存
• internal/worker/processor.go — 使用 errgroup 并行处理

### 新人入职指引

用户：帮新同事快速了解项目

AI：项目入职指引：

🚀 快速上手（预计 2 小时）

第一步：环境搭建

1. 克隆仓库，安装依赖
2. 复制 .env.example 并配置
3. 运行 make setup
4. 验证：make test 全部通过

第二步：了解项目结构

1. 阅读 README.md
2. 打开项目概览面板，浏览调用图
3. 重点了解 internal/ 的分层架构

第三步：核心流程

1. 跟踪一个 API 请求的完整路径 推荐：POST /api/v1/orders handler → service → repository → database

第四步：开始编码

1. 认领一个标记为 "good first issue" 的任务
2. 创建分支，实现功能
3. 运行测试，提交 PR

💡 推荐阅读：

• docs/architecture.md — 系统架构
• docs/coding-standards.md — 编码规范
• docs/api-reference.md — API 文档

---

## 协作模式

### workspace 隔离

wescode 采用 **1 workspace = 1 Cell** 的隔离模型：

- 每个 workspace 是独立的 Cell 隔离域
- CKG 索引、Memory、Skills、KB 物理隔离
- 切换 workspace = 切换 Cell = 切换所有数据面

### 多人协作建议

| 场景 | 建议 |
|------|------|
| 同一项目多人开发 | 各自的 workspace Cell 独立，知识通过 Git 共享 |
| 代码冲突解决 | AI 可以分析冲突，推荐合并策略 |
| 技术方案讨论 | 在 Chat 中讨论，结论记入项目文档 |
| 代码交接 | AI 可以解释代码逻辑，生成交接文档 |

### 分支管理建议

用户：推荐分支管理策略

AI：推荐 Git Flow 简化版：

main ─────────────────────────────► 生产 │ ▲ └── develop ─────────┤──────────► 开发 │ ▲ │ └── feature/xxx ──────────► 功能分支 └── hotfix/xxx ───────────► 紧急修复

规则：

1. main 只接受 develop 的合并（Release）和 hotfix
2. develop 是日常开发分支
3. feature/* 从 develop 切出，完成后合并回 develop
4. hotfix/* 从 main 切出，修复后同时合并到 main 和 develop

命名规范：

• feature/user-auth
• feature/order-refund
• hotfix/fix-login-crash
• release/v1.2.0

### 代码冲突解决

用户：合并冲突了，帮我解决

AI：冲突分析：

文件：internal/service/order.go

<<<<<<< HEAD (你的分支) func (s *OrderService) Cancel(ctx context.Context, id int64) error { order, err := s.repo.FindByID(ctx, id) if err != nil { return fmt.Errorf("find order: %w", err) } order.Status = "cancelled" order.CancelledAt = time.Now() return s.repo.Update(ctx, order) }

func (s *OrderService) Cancel(ctx context.Context, id int64, reason string) error { order, err := s.repo.FindByID(ctx, id) if err != nil { return fmt.Errorf("find order: %w", err) } if order.Status == "shipped" { return ErrCannotCancelShipped } order.Status = "cancelled" order.CancelReason = reason return s.repo.Update(ctx, order) }

develop

建议合并结果（取两者优点）： func (s *OrderService) Cancel(ctx context.Context, id int64, reason string) error { order, err := s.repo.FindByID(ctx, id) if err != nil { return fmt.Errorf("find order: %w", err) } if order.Status == "shipped" { return ErrCannotCancelShipped } order.Status = "cancelled" order.CancelledAt = time.Now() // 来自你的分支 order.CancelReason = reason // 来自 develop return s.repo.Update(ctx, order) }

→ 保留了两边的修改：

• 你的分支：记录取消时间
• develop：支持取消原因 + 已发货不可取消

---

## 注意事项

- 代码规范配置应团队讨论后统一，不要频繁变更
- AI Code Review 是辅助，不替代人工 Review
- CI 配置变更需要在 staging 环境验证
- 知识库内容随代码自动更新，无需手动维护
- workspace 隔离意味着 AI 的记忆不跨项目共享——这是特性，不是限制