API接口文档

⚠ 接入须知 · 使用教程
快速接入（两步）：① 用账号密码调用 login 登录，成功后保存返回的 key（App 会话密钥，30 天无操作自动失效）；② 登录后的写操作接口携带 key（请求参数 key）；只读接口游客可直接访问，无需任何凭证。
基础接口地址：api.php
请求格式：POST 表单（Content-Type: application/x-www-form-urlencoded）；upload_img 图片上传 用 multipart/form-data 并带 file 字段。
返回格式：code=1 成功 / code=0 业务失败（msg 为原因）；data 承载数据；令牌无效返回 need_login=1，客户端应提示重新配置令牌。
注意事项：此页面仅限系统管理员查看；不需要对外提供接口时，建议将 api.php 改名或删除，减少接口暴露风险。修改令牌后所有已接入的 App/客户端立即失效，需用新令牌重新接入；写操作（增/删/改/出入库）请务必在服务端二次校验令牌与登录态。
调试建议：先在下方向"选择接口 act"下拉框选目标接口，面板会自动显示该接口的用途、参数与示例并预填参数区，再点"发送请求"即可。在线调试不携带当前登录Cookie，不会影响你网站的实际登录状态。

在线接口调试

✓ 调试模式：写操作接口调试时不会真的修改网站数据，可放心测试 
等待发送请求...
提示：upload_img 图片上传接口为 multipart 文件上传，选择 act=upload_img 后即可在下方选择本地图片直接调试（会自动带上 key 与参数）。

全部接口详细说明清单（包含接入地址、请求方式）

共 20 个接口
快速接入说明（各接口通用）
① 用账号密码调用 login 登录，成功后返回 key（App 会话密钥）；② 写操作接口携带 key（请求参数 key）即可；只读接口游客可直接访问，无需任何凭证。
统一返回格式：code=1 成功 / code=0 业务失败（msg 为失败原因）；登录失效返回 need_login=1，客户端应提示重新登录。
登录失效时机：手动退出 / 修改密码 / 30 天无操作自动过期。
act=login 账号密码登录（凭账号密码即可）
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：校验管理员账号密码，登录成功后签发 App 会话密钥 key（每次登录生成新 key，旧 key 立即失效），并同步建立网页 session 登录态。
参数：
admin_name【必填】管理员账号
password【必填】管理员密码
返回字段：key、admin_name、qq 
{"code":1,"msg":"登录成功","key":"xxxx","admin_name":"admin","qq":""}
act=logout 退出登录（清空会话密钥，所有端失效）
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：清空服务端会话密钥并退出网页 session，所有端立即失效。
参数：key【选填】（登录后会话密钥）传入登录拿到的 key 
{"code":1,"msg":"已退出登录"}
act=profile_info 【需登录】获取当前登录管理员信息
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：获取当前登录管理员账号、QQ信息。
参数：key【必填】（登录后会话密钥） 
{"code":1,"data":{"admin_name":"admin","qq":""}}
act=profile_change_pwd 【需登录】修改管理员登录密码
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：修改当前登录账号密码；修改成功自动清空会话密钥，返回need_login=1，客户端强制重新登录。
参数：
key【必填】（登录后会话密钥）
old_password【必填】旧密码
new_password【必填】新密码，最少4位 
{"code":1,"msg":"密码修改成功，请重新登录","need_login":1}
act=cate_list 【游客可访问】获取全部分类列表
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：读取所有元器件分类，按照sort排序升序返回。
参数：key【必填】（登录后会话密钥）无其他参数 
{"code":1,"data":[{"id":1,"name":"电阻","sort":1}]}
act=cate_detail 【游客可访问】获取单个分类详情
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：根据分类id读取单条分类信息。
参数：key【必填】（登录后会话密钥），cid【必填】分类ID 
{"code":1,"data":{"id":1,"name":"电阻","sort":1}}
act=cate_add 【需登录】新增分类
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：新增元器件分类，自动分配sort排序值；校验分类名称不能重复。
参数：key【必填】（登录后会话密钥），name【必填】分类名称 
{"code":1,"msg":"分类新增成功","new_id":2}
act=cate_edit 【需登录】编辑分类
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：修改已有分类名称；校验不能和其他分类重名。
参数：key【必填】（登录后会话密钥），cid【必填】分类ID，name【必填】新分类名称 
{"code":1,"msg":"分类修改成功"}
act=cate_del 【需登录】删除分类
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：删除分类；数据库事务，该分类下所有元器件cate_id重置为0（无分类）。
参数：key【必填】（登录后会话密钥），cid【必填】分类ID 
{"code":1,"msg":"分类已删除，关联元器件重置为无分类"}
act=cate_move 【需登录】分类上下移动排序
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：分类向上/向下调换sort排序序号；到达边界返回提示无法移动。
参数：key【必填】（登录后会话密钥），cid【必填】分类ID，move【必填】up=向上 / down=向下 
{"code":1,"msg":"排序调整成功"}
act=cate_drag_sort 【需登录】批量拖拽排序
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：接收id数组JSON字符串，批量重写全部分类sort排序；事务保证全部成功或全部回滚。
参数：key【必填】（登录后会话密钥），drag_ids【必填】JSON数组字符串，例 "[2,1,3]" 
{"code":1,"msg":"拖拽排序保存完成"}
act=comp_list 【游客可访问】元器件分页列表+搜索
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：元器件分页查询；支持按分类筛选，支持关键词搜索型号、封装spec；每页固定12条，按id倒序。
参数：
key【必填】（登录后会话密钥）
page【选填】页码，默认1
cate_id【选填】分类ID，0代表全部
kw【选填】搜索关键词，匹配型号、封装 
{"code":1,"data":[{"id":1,"model":"10k电阻","cate_name":"电阻","stock":100}]}
act=comp_add 【需登录】新增元器件
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：新增一条元器件记录；model型号为必填项。
参数：key【必填】（登录后会话密钥）
model【必填】型号
cate_id【选填】分类ID
silkscreen【选填】丝印
spec【选填】封装规格
stock【选填】初始库存
min_stock【选填】库存预警值
remark【选填】备注
img【选填】图片URL地址 
{"code":1,"msg":"新增成功","new_id":12}
act=comp_edit 【需登录】编辑元器件
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：修改已有元器件全部字段；cid元器件ID、model型号必填。
key【必填】（登录后会话密钥），cid【必填】元器件ID，其余参数同comp_add 
{"code":1,"msg":"修改成功"}
act=comp_del 【需登录】删除元器件
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：删除指定id的元器件记录。
key【必填】（登录后会话密钥），cid【必填】元器件ID 
{"code":1,"msg":"删除完成"}
act=comp_detail 【游客可访问】获取元器件单条详情
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：根据元器件ID获取完整一条元器件数据，附带分类名称cate_name。
key【必填】（登录后会话密钥），cid【必填】元器件ID 
{"code":1,"data":{"id":1,"model":"10k电阻","cate_name":"电阻","stock":100}}
act=stock_io 【需登录】入库/出库（自动写入日志）
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：元器件入库、出库；自动写入出入库日志表；出库自动校验库存是否充足。
● 入库（增加库存）：type=in，库存增加 num
● 出库（减少库存）：type=out，库存减少 num，库存不足时报错
num 变动数量最小为 1。
key【必填】（登录后会话密钥），cid【必填】元器件ID，type【必填】in=入库 / out=出库，num【必填】变动数量
入库示例请求：key=xxx&act=stock_io&cid=35&type=in&num=50 → 
{"code":1,"msg":"入库成功"}

出库示例请求：key=xxx&act=stock_io&cid=35&type=out&num=50 → 
{"code":1,"msg":"出库成功"}
act=log_list 【游客可访问】出入库日志分页
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：出入库操作日志分页查询；cid=0查询全部元器件日志；cid>0查询指定元器件日志；每页固定15条，时间倒序。
key【必填】（登录后会话密钥），page【选填】页码，cid【选填】元器件id，0查全部 
{"code":1,"data":[{"id":1,"type":1,"num":10,"model":"10k电阻","log_time":"2026-09-17 10:00:00"}]}
act=stat_data 【游客可访问】首页统计数据
请求地址：api.php
请求方式：POST
Content-Type：application/x-www-form-urlencoded
作用：返回统计：总元器件数量、库存总价值、预警库存数量、缺货(stock=0)元器件数量。
key【必填】（登录后会话密钥），无其他参数 
{
"code":1,
"data":{
    "total":23,
    "money_sum":1256.30,
    "low_stock":2,
    "empty_stock":3
}
}
act=upload_img 【需登录】图片文件上传
请求地址：api.php
请求方式：POST
Content-Type：multipart/form-data
作用：上传元器件图片；限制jpg/jpeg/png/gif/webp，最大10MB；返回图片相对路径url，保存到元器件img字段。 ⚠本调试页面不支持文件上传，使用Postman测试。
key【必填】（登录后会话密钥），cid【必填】元器件ID，file【必填】图片文件字段 
{"code":1,"msg":"上传成功","url":"upload/1/172xxxxxx_1234.jpg"}