ai-proj-helper/skills-dev/dev-coding-plugin/skills/SKILL.md

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

---

## 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` | 通用空白骨架 |

### 非阻断原则

架构信息缺失时**仅警告不阻止**。用户仍可继续，但会被告知"生成的建议可能不够准确"。