--- 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 | --- ## 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 开发（插件，按需加载）|