John Qiu
3706d7f32d
批次1: req-prd 瘦身 + req-design 重定位 + dev-coding 聚焦 批次2: dev-review 新建 + review-checklist 插件 批次3: dev-integration 新建 + req-compare 拆出 批次4: 插件完善 (req-research/db-migration/dev-scaffold/deploy-rollback) 批次5: 平台拆分 (dev-ios/dev-android/dev-mcp/dev-pda) + dev 分组更新 批次6: marketplace.json 32→44 plugins Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
493 lines
10 KiB
Markdown
493 lines
10 KiB
Markdown
---
|
||
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 <taskId>
|
||
|
||
# 3. 完成后
|
||
ai-proj task complete --id <taskId>
|
||
|
||
# 4. 记录文档
|
||
ai-proj task append-doc --id <taskId> --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
|
||
<!-- ✅ 正确 -->
|
||
<a-input data-testid="product-input-name" v-model:value="form.name" placeholder="商品名称" />
|
||
<a-button data-testid="product-btn-submit" type="primary">创建商品</a-button>
|
||
<a-select data-testid="product-select-brand" v-model:value="form.brandId" />
|
||
<a-table data-testid="product-table" :dataSource="list" />
|
||
|
||
<!-- ❌ 错误 — 交互元素无 data-testid -->
|
||
<a-input v-model:value="form.name" placeholder="商品名称" />
|
||
<a-button type="primary">创建商品</a-button>
|
||
```
|
||
|
||
**必须加:** 输入框、选择器、开关、按钮（提交/取消/删除）、表格、模态框确认按钮、导航菜单项
|
||
**不需要加:** 纯展示文本、图标、布局容器（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<ApiResult<PageResult<User>>>(
|
||
'/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 集成
|
||
<QueryProvider>
|
||
<AuthProvider>
|
||
<TimerProvider>
|
||
<ConfigProvider locale={zhCN}>
|
||
<Router>
|
||
<Routes />
|
||
</Router>
|
||
</ConfigProvider>
|
||
</TimerProvider>
|
||
</AuthProvider>
|
||
</QueryProvider>
|
||
|
||
// 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 <token>`
|
||
|
||
### 错误处理
|
||
|
||
```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 开发（插件，按需加载）|
|