Skip to main content Home Creators chenychenyu jh-project-agent-ppt api-contract
api-contract Use when: designing API contracts between frontend and backend based on prototype page inventory, defining request/response field structures, establishing naming conventions, and generating an api.md file per page for team alignment before coding. Triggers on: api contract, interface design, 接口约定, 前后端对齐, 字段定义, 接口设计, api.md.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/ChenyCHENYU/jh-project-agent-ppt --skill api-contractThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository
Use when: auditing project source code against the 14 modular standards in .github/standards/. Outputs deviation report and component-extraction suggestions to reports/. Triggers on: 规范审计, 规范检查, 代码审计, 对齐规范, 规范偏差, 接手新项目, 存量代码分析, 项目体检, audit code, check conventions, onboard project.
Use when: generating complete Vue 3 page code (index.vue + data.ts + modal components + api.md + pages.ts registration) from a prototype page inventory and API contract, strictly following the cx-ui-produce project conventions. Read SKILL.md first (rules+constraints), then read the matching TPL-*.md for the template code. Triggers on: generate page, create page, code generation, 生成页面, 页面代码, 代码生成, vue页面, 按原型生成, 口述需求, 建个页面, 写个页面, 帮我生成, natural language page generation.
Related occupations SOC
Based on SOC occupation classification
name api-contract description Use when: designing API contracts between frontend and backend based on prototype page inventory, defining request/response field structures, establishing naming conventions, and generating an api.md file per page for team alignment before coding. Triggers on: api contract, interface design, 接口约定, 前后端对齐, 字段定义, 接口设计, api.md.
Skill: 接口约定（api-contract）
基于《页面清单》为每个页面生成 api.md 文件，放在页面目录下 （和 index.vue 同级）。
双重作用：
前端 — data.ts 中 API_CONFIG 的 URL 和字段名直接基于 api.md后端 — 拿到 api.md 直接出接口（Controller + Service + Entity），字段名一致，联调零成本
全局规范
URL 命名
/[服务缩写]/[资源名CamelCase]/[操作]
服务缩写 含义 示例 pm 生产管理 /pm/omptMillPlanOrder/listmmwr 精整作业 /mmwr/mmwrTechFinish/queryTechListmmsm 炼钢管理 /mmsm/mmsmRsltLadleUse/listsale 销售管理 /sale/saleOrder/listhrms 人力资源 /hrms/hrmsEmployee/listbase 基础数据 /base/cmUserGroup/list
标准操作集
基类 super({ url: { list } }) 自动调用
单条查询 GET /getById?id=xxxgetAction(API_CONFIG.getById, { id })
新增 POST /savepostAction(API_CONFIG.save, formData)
编辑 POST /updatepostAction(API_CONFIG.update, formData)
删除 POST /remove基类 super({ url: { remove } }) + this.remove(id)
导出 GET /exportgetAction(API_CONFIG.export, params)
业务操作命名规范 非标准 CRUD 操作按以下约定命名，URL 后缀使用动词原形 （camelCase）：
操作 方法 URL 后缀 请求说明 提交审批 POST /submit{ id } 或 { ids: [] }审批通过 POST /approve{ id, opinion? }审批驳回 POST /reject{ id, opinion }撤回 POST /withdraw{ id } 撤回已提交的单据启用/禁用 POST /changeStatus{ id, status }转化 POST /convert{ id } 临时→正式（如临时客户→正式）下发 POST /release{ id } 计划/工单下发执行关闭 POST /close{ id } 关闭订单/计划作废 POST /cancel{ id } 作废单据批量操作 POST /batchXxx如 /batchSubmit、/batchRemove 子表查询 POST /queryXxxList如 /queryDetailList，主从表场景
命名原则 ：/[服务缩写]/[资源名]/[动作]，动作用英文动词原形，不用中文拼音，不加 do / handle 前缀。
统一响应结构（基于真实后端契约）
⚠️ 重要 ：本项目后端响应外壳为 { code, message, data }（非 result ），成功码为 2000非 200 ）。
1. 分页查询响应 {
"code" : 2000 ,
"message" : "操作成功" ,
"data" : {
"records" : [
{
}
] ,
"total" : 100 ,
"current" : 1 ,
"size" : 20 ,
"pages" : 5 ,
"countId" : null ,
"maxLimit" : null ,
"orders" : [ ] ,
"searchCount" : true }
}
data 字段 类型 说明 recordsarray 当前页数据列表 totalnumber 总记录数 currentnumber 当前页码 sizenumber 每页条数 pagesnumber 总页数 countIdany MyBatis-Plus 分页计数 ID（前端忽略） maxLimitany 最大单页限制（前端忽略） ordersarray 排序条件回传（前端忽略，除非需回显排序） searchCountboolean 是否执行总数查询（前端忽略）
前端 BaseTable / AbstractPageQueryHook 已自动适配：取 data.records 渲染、data.total 设分页、其他字段透传或忽略。无需在 data.ts 中处理。
2. 单条 / 非分页查询响应 {
"code" : 2000 ,
"message" : "操作成功" ,
"data" : {
}
}
{
"code" : 2000 ,
"message" : "操作成功" ,
"data" : [
{
}
]
}
3. 字典查询响应 {
"code" : 2000 ,
"message" : "操作成功" ,
"data" : [
{ "value" : "01" , "label" : "已审批" , "extra" : null } ,
{ "value" : "02" , "label" : "驳回" , "extra" : null }
]
}
4. 增删改响应 { "code" : 2000 , "message" : "操作成功" , "data" : true }
{ "code" : 2000 , "message" : "操作成功" , "data" : "1234567890123456789" }
5. 失败响应 { "code" : 4001 , "message" : "参数缺失：customerName 不能为空" , "data" : null }
code 范围 含义 2000成功 4xxx客户端错误（参数/权限/校验） 5xxx服务端错误 401 / 403网关层未登录 / 无权限（统一拦截）
业务代码不需要 关心 code 判断，request.ts 拦截器统一处理：非 2000 自动 Promise.reject + Toast 提示。业务代码 .then() 拿到的就是 data 字段内容。
字段命名 端 规范 说明 前端 camelCase所有请求/响应字段名 后端 snake_case数据库字段，Jackson 自动转驼峰
执行步骤
Step 1：接收输入
业务服务缩写（如 pm）
资源名（camelCase，如 omptMillPlanOrder）
各页面的查询字段、表格列、表单字段
Step 2：为每个页面生成 api.md 文件放在页面目录下 （和 index.vue 同级），字段名与 data.ts 完全一致。
Step 3：同步生成 API_CONFIG api.md 中的接口 URL 直接对应 data.ts 中的 API_CONFIG：
export const API_CONFIG = {
list : "/pm/omptMillPlanOrder/list" ,
remove : "/pm/omptMillPlanOrder/remove" ,
getById : "/pm/omptMillPlanOrder/getById" ,
save : "/pm/omptMillPlanOrder/save" ,
update : "/pm/omptMillPlanOrder/update" ,
export : "/pm/omptMillPlanOrder/export" ,
release : "/pm/omptMillPlanOrder/release" ,
} as const ;
api.md 模板 # 接口约定 - [页面中文名]
> 页面路径：`src/views/[域]/[模块]/[子模块]/[目录]/`
> 服务缩写：[pm / mmwr / sale / ...]
> 资源名：[camelCase 实体名]
> 状态：🟡 待后端确认
---
## API_CONFIG
```typescript
export const API_ CONFIG = {
list: "/[服务缩写]/[资源名]/list",
remove: "/[服务缩写]/[资源名]/remove",
getById: "/[服务缩写]/[资源名]/getById",
save: "/[服务缩写]/[资源名]/save",
update: "/[服务缩写]/[资源名]/update",
export: "/[服务缩写]/[资源名]/export",
} as const;
```
---
## 实体定义
> 字段名与 data.ts 中 queryDef/columnsDef 使用的字段名**完全一致**
| 字段名 | 类型 | 说明 | 必填 | 字典(logicValue) | 备注 |
| ------------- | ------ | -------- | ---- | ---------------- | -------------------- |
| id | string | 主键 | 自动 | - | 后端生成 |
| [field1] | string | [说明] | ✅ | - | |
| [statusField] | string | [状态] | ✅ | [dictCode] | 前端 logicValue 对应 |
| [dateField] | string | [日期] | ❌ | - | YYYY-MM-DD |
| createTime | string | 创建时间 | 自动 | - | YYYY-MM-DD HH:mm:ss |
| updateTime | string | 更新时间 | 自动 | - | |
| createBy | string | 创建人 | 自动 | - | |
---
## 接口清单
### 1. 分页查询
```
POST /[服务缩写]/[资源名]/list
```
| 字段 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | ----------------------------------- |
| current | number | ✅ | 页码（基类自动传） |
| size | number | ✅ | 每页条数（基类自动传） |
| [queryField1] | string | ❌ | [说明] |
| [queryField2] | string | ❌ | [说明]，对应 logicValue: [dictCode] |
| [startDate] | string | ❌ | 开始日期 YYYY-MM-DD |
| [endDate] | string | ❌ | 结束日期 YYYY-MM-DD |
**响应 data.records：** 同实体定义；外壳 `{ code: 2000, message, data: { records, total, current, size, pages, countId, maxLimit, orders, searchCount } }`
### 2. 详情查询
```
GET /[服务缩写]/[资源名]/getById?id=xxx
```
**响应 data：** 单个 Entity；外壳 `{ code: 2000, message, data: {...} }`
### 3. 新增
```
POST /[服务缩写]/[资源名]/save
```
**请求：** 实体定义中必填字段（不含 id、createTime 等自动字段）
### 4. 编辑
```
POST /[服务缩写]/[资源名]/update
```
**请求：** 同新增 + `id`（必填）
### 5. 删除
```
POST /[服务缩写]/[资源名]/remove
```
**请求：** `{ "ids": ["xxx"] }` 或 `{ "id": "xxx" }`
### 6. 导出（如需要）
```
GET /[服务缩写]/[资源名]/export?[查询参数]
```
---
## 数据字典
| dictCode(logicValue) | 用途 | 出现位置 |
| -------------------- | ------ | ---------------------------- |
| [dictCode] | [说明] | queryDef / columnsDef / form |
---
## 联调注意
1. **响应外壳**：`{ code, message, data }`，成功 `code: 2000`（非 200，非 result）
2. 前端字段全部 camelCase，后端 JSON 序列化输出 camelCase
3. 时间字段统一 `YYYY-MM-DD HH:mm:ss`
4. 大数字 ID 后端转字符串（雪花 ID 超过 JS Number 精度）
5. 分页参数前端传 `current` / `size`（基类自动处理），后端响应 `data.records` / `data.total`
6. 枚举字段前端传 value，后端可返回 `[field]Label` 辅助展示，或前端自行通过 `logicValue` 字典翻译
7. 业务代码 `.then(res => res)` 拿到的就是 `data` 字段（拦截器已剥外壳）
状态标记
🟡 待后端确认 — 刚生成
🟢 已确认 — 双方对齐，可编码
🔴 有变更 — 需双方同步
