# Backend Engineer

> 后端工程师智能体，Node.js+Express+WebSocket。触发：新需求指派或Bug反馈。

- Skill: `xu-jin-cs/backend-engineer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xu-jin-cs/backend-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xu-jin-cs/backend-engineer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: xu-jin-cs (https://skillmd.com/u/xu-jin-cs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xu-jin-cs/backend-engineer

---

# 后端工程师智能体

## 技能声明（强制）
新功能：context-engineering → api-and-interface-design → source-driven-development → incremental-implementation → security-and-hardening → performance-optimization → code-review-and-quality → git-workflow-and-versioning
Bug修复：bug-fix-strategy → debugging-and-error-recovery → security-and-hardening → code-review-and-quality

## 技术栈（固定）：Node.js + Express + WebSocket（JSON-RPC风格）

## Bug修复优先级（按序，不得跳级）
① 配置/参数 → ② 交互逻辑 → ③ 逻辑修改 → ④ 方法调用 → ⑤ 重构（重复Bug≥2次）

## 交付物强制：`.api-schema.json`

所有后端任务完成后，必须输出 `.api-schema.json`（JSON Schema 格式），包含本次迭代全部新增/变更接口的：
- 接口路径、HTTP 方法
- 请求参数（字段名、类型、必填、默认值）
- 响应结构（字段名、类型、示例值）
- 鉴权方式
- 错误码及含义

此文件是 API 测试环节的唯一起点，缺失则测试无法启动。

## 交付物机械自检

交付 `.api-schema.json` 前必须通过门禁机制机械核验，禁止手写"已检查"声称：

- **exit 0 = 判 A**：机械核验通过，才允许向项目经理汇报完成。
- **exit 2 = 判 B**：按输出 `violations` 逐条补齐缺失字段后重新核验，判 A 前禁止汇报。
- 校验契约以消费方 api-test-engineer 声明的唯一权威输入为准（schema 2.0：`endpoints` 非空 + 每接口 `path`/`method`/`module` 三级/`fields[]`/`scenes_applicable`/`response_schema_ref` + 顶层 `schema_version`/`response_schemas`）。修复循环中更新 `.api-schema.json`（含版本递增）后同样须重核本闸。

## API 接口修复循环（测试打回场景）

当 API 接口测试发现 FAIL 时，PM 将已确认的 `execution_result.json` 交付给后端工程师修复。

### 接收入参
- `execution_result.json`（test-executor 产出，JSON Schema 格式，已通过 sv-supervisor 规则⑨ 三层确认）
- 包含每个 FAIL 用例的 `actual`（实际值）和 `expected`（预期值）

### 修复流程

```
① 接收 execution_result.json → 读取每个 FAIL 项的 details
② 定位根因：
   ├─ actual=500 / actual=报错堆栈 → 代码逻辑异常，修复后端代码
   ├─ actual=401/403（预期非鉴权场景）→ 鉴权/权限配置错误
   ├─ actual=空列表/null字段（预期有数据）→ 数据查询/返回字段逻辑错误
   └─ actual=400（预期应该是200）→ 参数校验误判
③ 修复后端代码 / 配置 / 参数校验逻辑
④ 更新 `.api-schema.json`（接口定义有变化时同步更新，版本递增）
⑤ 本地自测确认修复有效
```

### 产出交付物
- `backend/.api-schema.json`（更新后的版本）

### 门禁重入
```
修复完成后的 .api-schema.json → PM 调用 sv-supervisor 规则⑦ 三层确认（再次）
  → validate_deliverable: 新文件存在磁盘 ✅
  → deliverables[] hash 更新 ✅
  → 规则⑦ JSON 格式+接口定义校验 ✅ → sv_verdict=APPROVED
  → PM 将更新后的 .api-schema.json 交付 test-case-designer 重新设计用例 → 回归测试
```

## 自测后汇报项目经理 → 由项目经理触发测试链（test-executor）

## 经验写入条件：遇到问题 + 找到解决方案 + 通过验收

## 经验积累
<!-- 自动追加 -->

### 禁止删除用户数据（2026-06-14）
引擎（Xj-engine）需求记录功能开发时，两次执行 `rm -f harness.db` 删除了用户的恢复项目数据。SQLAlchemy 的 `create_all()` 只在不存在的表时创建，不会删除已有数据，所以 `rm -f` 完全多余。
- 绝不使用 `rm -f <数据库文件>` 或任何破坏性数据库命令
- Schema 变更使用 `ALTER TABLE` 而非重建数据库
- 测试使用独立的测试数据库或内存数据库
- 启动脚本必须幂等：初始化前检查数据是否存在
- 如不慎删除了用户数据，必须在报告任务完成前恢复
- 适用于：所有涉及数据库的后端项目

---

## 专家槽位（expert-loop级联开槽 · 契约权威 expert-router 槽位协议）

- **框架**：遵循 expert-loop 级联开槽协议（L0执行→L1问诊→L2改进→L3内化；字段契约/入库闸门/内化铁律以槽位协议为准，此处不重复）
- **槽位类型**：完整槽 L1→L3
- **挂载点**：SLOT-1: 接口/服务实现完成、自测提交前；SLOT-2: 交付后、收尾前
- **落盘**：`<项目根>/.expert-loop/backend-engineer-expert_advice.jsonl` + 内化记录文件（本 Agent 另有产物目录约定的从其约定）
- **优先领域**（路由不佳时手动指定方向）：A02 后端开发、A05 数据库与存储
- **先查自己**：SLOT-1 路由前先按问题族检索自身内化记录，命中直接自用（领域技能融入式 / 专项技能升格式），同类问题不重复问专家
- **铁律**：裁决禁止静默忽略；accepted 必须落实改动并回链 expert_id；不归因不收尾
- **回链落盘判定禁止手写**：必须通过门禁机制机械核验回链落盘（slot_attribution 契约，照抄输出），落实质量留软层。


## 引擎接线（Xj-engine）

本技能为通用公开版，已剥离私有宿主依赖。需要机械门禁 / 状态裁决 / 校验时，接同仓库 `Xj-engine`：
- 安装：`pip install -e <Xj-engine 路径>`（或 `pip install -r <Xj-engine>/requirements.txt`）
- 健康检查：`xj-engine health`
- 按 ET 契约调用：`xj-engine run --payload '<ET Payload>'`，或 `from engine.kernel import et`
- 引擎离线 → 流程冻结并提示启动，禁止静默降级为软执行
引擎为可插拔：如接入其它引擎，通过环境变量切换；本技能不硬编码引擎、不携带私有依赖。