--- name: dev-coding description: 软件编码开发技能。用于代码编写、功能实现、重构优化。集成 ai-proj CLI 进行任务管理和进度跟踪。核心支持 Go 后端 + Vue/React 前端开发。 --- # 软件编码开发 Skill (dev-coding) ## 概述 本技能用于软件编码实现，核心覆盖： - Go 后端 (Gin + GORM) - Vue 3 / React 前端 集成 **ai-proj CLI** 进行任务管理。 **不包含**（由其他技能/插件负责）： - 开发设计（API 契约、任务拆分）→ `req-design` - 代码评审 → `dev-review`（批次2） - iOS 开发 → `dev-ios`（插件） - Android 开发 → `dev-android`（插件） - MCP 开发 → `dev-mcp`（插件） --- ## ai-proj 任务管理 ### 开发任务工作流 ``` 1. 查看/创建任务 → 2. 启动任务 → 3. 编码实现 → 4. 完成任务 → 5. 记录文档 ``` ### 任务操作速查 | 操作 | CLI 命令 | 说明 | |------|----------|------| | 查看任务列表 | `ai-proj task list` | 查看项目所有任务 | | 创建任务 | `ai-proj task create` | 创建新任务 | | 创建子任务 | `ai-proj task create --parent-id` | 分解任务 | | 启动任务 | `ai-proj task start --id` | 开始执行 | | 完成任务 | `ai-proj task complete --id` | 标记完成 | | 更新任务 | `ai-proj task update --id` | 更新状态/描述 | | 查看详情 | `ai-proj task get --id` | 完整任务信息 | | 记录文档 | `ai-proj task append-doc --id` | 附加文档 | ### 开始新任务 ```bash # 1. 查看任务列表 ai-proj task list --status todo,in_progress # 2. 启动任务 ai-proj task start --id # 3. 完成后 ai-proj task complete --id # 4. 记录文档 ai-proj task append-doc --id --content "实现说明" ``` --- ## 项目类型速查 ### 当前项目生态 | 项目 | 类型 | 后端 | 前端 | |------|------|------|------| | TWMS | 仓储物流 | Go+Gin+MySQL | Vue 3 | | AI-Proj | 项目管理 | Go+Gin+PostgreSQL | React 18 | | DICIAI | 进销存SaaS | Go+Gin+MySQL | Vue 3 | --- ## Step 0：验证优先（Karpathy: Goal-Driven Execution） **编写任何代码前，必须先写验证脚本。** 规则来源：Karpathy "Goal-Driven Execution" 原则。 > "Define success criteria. Loop until verified." > "Fix the bug" → "Write a test that reproduces it, then make it pass" ### 执行流程 ``` ① 写验证脚本（按类型选择） ② 运行一遍，确认全部 FAIL（证明功能确实不存在 / bug 确实存在） ③ 编码实现 ④ 再次运行验证脚本，全部 PASS → 完成 ``` ### 后端验证脚本模板 实现 API 前，先写好所有 curl 命令并标注期望结果： ```bash # 验证脚本：REQ-XXXX [功能名] BASE="http://localhost:8080" TOKEN="" echo "=== T1: 正常创建 ===" curl -s -X POST "$BASE/api/v1/xxx" \ -H "Authorization: Bearer $TOKEN" \ -d '{"name":"test"}' | jq '.code' # 期望: 0 echo "=== T2: 缺少必填字段 ===" curl -s -X POST "$BASE/api/v1/xxx" \ -H "Authorization: Bearer $TOKEN" \ -d '{}' | jq '.code' # 期望: 非 0（参数错误） echo "=== T3: 跨租户访问 ===" curl -s -X GET "$BASE/api/v1/xxx/999" \ -H "Authorization: Bearer $TOKEN_OTHER_TENANT" | jq '.code' # 期望: 403 ``` **先运行 → 全部 FAIL → 编码 → 再次运行 → 全部 PASS** ### 前端验证脚本模板 实现页面前，先列出所有 `data-testid` 和期望的 DOM 状态： ``` 验证清单（编码前先确认这些状态不存在 / 行为不正确）： - data-testid="xxx-btn-submit" 点击 → 列表刷新，行数增加 1 - data-testid="xxx-table" 行数 === API 返回 total - data-testid="xxx-input-name" 空值提交 → 显示「请输入名称」提示 ``` ### 与 VP 三件套的关系 | VP 协议 | 验证优先对应 | |---------|------------| | VP-Data | 先在环境建好测试数据（curl 确认成功） | | VP-Steps | **即为本节验证脚本** — 编码前写好，编码后执行 | | VP-Pass | 验证脚本每条命令的期望输出值 | --- ## Go 后端开发 ### 分层架构 ``` backend/ ├── cmd/main.go # 入口点 ├── internal/ │ ├── controller/handlers/ # HTTP 处理层 │ ├── biz/services/ # 业务逻辑层 │ ├── store/database/ # 数据访问层 │ └── middleware/ # 中间件 ├── pkg/ │ ├── model/ # 数据模型 │ ├── errno/ # 错误定义 │ ├── api/ # API 类型 │ └── util/ # 工具函数 └── configs/migrations/ # 配置和迁移 ``` ### 代码规范 ```go // 包声明和导入组织 package main import ( // 标准库 "context" "fmt" // 第三方 "github.com/gin-gonic/gin" // 项目内部 "project/internal/pkg/errno" ) // 错误处理 (Errno 模式) if err != nil { core.WriteResponse(c, errno.ErrBind, nil) return } // 接口定义 type IStore interface { Users() UserStore } // 服务注入 type userBiz struct { ds store.IStore } func NewUserBiz(ds store.IStore) *userBiz { return &userBiz{ds: ds} } ``` ### 常用命令 ```bash # 构建 make build go build -o ./_output/main ./cmd/main.go # 运行 ./_output/main --config ./configs/config.yaml # 测试 make test go test -v ./... # 代码检查 make lint golangci-lint run # Swagger 文档 make swagger swag init -g cmd/main.go ``` ### 数据库模型 ```go type UserM struct { Id int64 `gorm:"column:id;primary_key"` Username string `gorm:"column:username;not null"` CreateTime int64 `gorm:"column:create_time"` UpdateTime int64 `gorm:"column:update_time"` DeletedAt soft_delete.DeletedAt `gorm:"column:deleted_at"` } func (m *UserM) TableName() string { return "users" } func (m *UserM) BeforeCreate(tx *gorm.DB) error { m.CreateTime = time.Now().Unix() m.UpdateTime = m.CreateTime return nil } ``` --- ## 前端 data-testid 规范 编写或修改前端组件时，**所有可交互元素必须加 `data-testid`**。 **命名格式:** `<模块>-<元素类型>[-<标识>]` ```vue 创建商品 创建商品 ``` **必须加:** 输入框、选择器、开关、按钮（提交/取消/删除）、表格、模态框确认按钮、导航菜单项 **不需要加:** 纯展示文本、图标、布局容器（Row/Col/Space） --- ## Vue 3 前端开发 ### 项目结构 ``` frontend/src/ ├── api/ # API 服务 (按模块分组) │ ├── wms/ # 仓储管理 │ ├── oms/ # 订单管理 │ └── system/ # 系统管理 ├── views/ # 页面组件 ├── components/ # 可复用组件 ├── store/modules/ # Pinia 状态 ├── router/ # 路由配置 ├── utils/ │ ├── request.ts # Axios 拦截器 │ └── permission.ts # 权限检查 └── i18n/ # 国际化 ``` ### 代码规范 ```typescript // API 服务层 // api/user/model/index.ts export interface User { id: number; username: string; } // api/user/index.ts import request from '@/utils/request'; import type { ApiResult, PageResult } from '@/api'; import type { User } from './model'; export async function getUsers(params: UserParams) { const res = await request.get>>( '/v1/users', { params } ); if (res.status === 200) { return res.data; } return Promise.reject(new Error(res.data.message)); } ``` ### 常用命令 ```bash # 安装依赖 npm install pnpm install # DICIAI 使用 pnpm # 开发 npm run dev # 构建 npm run build:prod npm run build:test # 代码检查 npm run lint:eslint ``` --- ## React 前端开发 ### 项目结构 ``` frontend/src/ ├── pages/ # 页面组件 ├── components/ # 可复用组件 ├── services/ # API 服务 ├── hooks/ # 自定义 Hooks ├── contexts/ # Context Providers ├── types/ # TypeScript 类型 ├── utils/ # 工具函数 └── config/ # 配置 ``` ### 代码规范 ```typescript // Context 集成 // API 服务 const api = axios.create({ baseURL: API_BASE_URL, timeout: 120000, }); api.interceptors.request.use((config) => { const token = TokenManager.getToken(); if (token) { config.headers.Authorization = `Bearer ${token}`; } return config; }); ``` ### 常用命令 ```bash # 开发 npm start # 构建 npm run build # 测试 npm test npm run test:e2e ``` --- ## 通用开发规范 ### API 响应格式 ```json { "code": 0, "message": "success", "data": {} } ``` ### 分页参数 ```json { "page": 1, "limit": 20, "sort": "created_at", "order": "desc" } ``` ### 认证方式 - JWT Token - Header: `Authorization: Bearer ` ### 错误处理 ```go // Go if err != nil { core.WriteResponse(c, errno.ErrXxx, nil) return } // TypeScript try { const result = await api.call(); } catch (error) { message.error(error.message); } ``` --- ## Git 工作流 ### 提交规范 | 类型 | 说明 | |------|------| | feat | 新功能 | | fix | Bug 修复 | | docs | 文档 | | refactor | 重构 | | test | 测试 | | chore | 杂项 | ### 双电脑同步 (au-dev / cn-dev) ```bash # 离开时 git add -A git commit -m "WIP: sync from $(hostname)" git push origin $(git branch --show-current) # 到达时 git fetch origin git pull origin $(git branch --show-current) ``` --- ## Docker 部署 ### 标准配置 ```yaml # docker-compose.yml services: backend: build: ./backend ports: - "8080:8080" depends_on: - db - redis frontend: build: ./frontend ports: - "80:80" db: image: mysql:8.0 # 或 postgres:15 redis: image: redis:alpine ``` ### 常用端口 | 服务 | 端口 | |------|------| | Backend | 8080 / 9099 | | Frontend | 80 / 3000 | | MySQL | 3306 | | PostgreSQL | 5432 | | Redis | 6379 | --- ## Push 前必须通过：变更包单元测试 **在 `git push` 或 `/pr create` 之前，必须跑所有变更文件对应包的单元测试。** ```bash # 找出变更的 Go 文件所在包，跑对应测试 PKGS=$(git diff --name-only origin/main...HEAD | grep '\.go$' | grep -v '_test\.go' | sed 's|/[^/]*$||' | sort -u | sed 's|^|./|' | tr '\n' ' ') if [ -n "$PKGS" ]; then echo "Running tests for changed packages: $PKGS" go test -v -count=1 $PKGS else echo "No Go files changed, skipping tests" fi ``` **规则：** - 测试通过 → 继续 push + `/pr create` - 测试失败 → 尝试自动修复，修复后重跑 - 修复成功 → 继续 push - **修复失败 → 禁止 push，向用户报告失败原因，等待指示** - 仅改了 `_test.go` → 同样需要跑（验证测试本身通过） - 无 Go 文件变更（纯前端/文档） → 跳过 --- ## 最佳实践 1. **任务驱动** - 使用 ai-proj 管理所有开发任务 2. **分层清晰** - Controller → Service → Repository 3. **接口先行** - 先定义接口再实现 4. **小步提交** - 频繁提交，每次做一件事 5. **测试覆盖** - 核心逻辑必须有测试 6. **文档同步** - 代码变更同步更新文档 ## 相关技能 | 技能 | 用途 | |------|------| | `req-design` | 开发设计（API 契约、任务拆分）— dev-coding 的输入 | | `dev-test` | 测试与质量门禁 | | `dev-review` | 代码评审（五视角扫描）| | `dev-ios` | iOS 开发（插件，按需加载）| | `dev-android` | Android 开发（插件，按需加载）| | `dev-mcp` | MCP bridge 开发（插件，按需加载）| --- ## CLAUDE.md 架构检查机制（REQ-20260416-0017 P0-5） **原则：本 skill 不硬编码任何项目的架构细节，从项目 CLAUDE.md 读取**。 ### 为什么 同一套 skill 要支持多个技术栈（Go+Gin / React+AntD / Vue+Element / Python+FastAPI）。如果把分层、命名、目录结构写死在 SKILL.md 里，跨项目就会冲突。 devflow-claude 的做法（借鉴）：skill 只管**流程和模板**，项目架构由 CLAUDE.md 的 "Architecture" / "项目架构" 章节定义。 ### 执行前检查 开始编码任务前，skill 先检查项目根 `CLAUDE.md`： ```bash # 检查 CLAUDE.md 是否含架构关键词 if [ -f "CLAUDE.md" ]; then if grep -qiE "(架构|分层|目录结构|tech stack|architecture|project structure)" CLAUDE.md; then echo "✅ 检测到项目架构信息" else echo "⚠️ CLAUDE.md 缺少架构描述" echo " dev-coding 需要架构信息来生成准确的文件路径和分层顺序" echo "" echo " 📋 建议操作:" echo " - 查看预置架构片段: ai-proj-helper/skills-dev/dev-coding-plugin/templates/claude-md-snippets/" echo " - 选择匹配技术栈的片段，补充到 CLAUDE.md 的 '## Architecture' 章节" echo "" echo " ⚠️ 继续执行，但生成的文件路径可能不够准确" fi else echo "⚠️ 未找到项目 CLAUDE.md，建议创建" fi ``` ### 架构片段模板库 位于 `skills-dev/dev-coding-plugin/templates/claude-md-snippets/`： | 文件 | 适用场景 | |------|---------| | `go-gin-gorm.md` | Go + Gin + GORM 后端（ai-proj backend 风格） | | `react-antd.md` | React + TypeScript + Ant Design（ai-proj frontend 风格） | | `vue-element.md` | Vue 3 + Element Plus（coolbuy-paas 风格） | | `mcp-typescript.md` | MCP bridge TypeScript（mcp-task-bridge 风格） | | `generic.md` | 通用空白骨架 | ### 非阻断原则 架构信息缺失时**仅警告不阻止**。用户仍可继续，但会被告知"生成的建议可能不够准确"。