menchuang/doc/API.md

API 接口文档

本文档记录自研系统的接口规范，并对照目标站已验证接口。目标站基址：https://zzc-serv.thinkerx.com/api/（仅作参照）。 自研系统基址：/api/（FastAPI 挂载）。 认证方式：Authorization: Bearer <JWT>（HS256，24h）；X-Requested-With: XMLHttpRequest；Accept: application/json。

0. 统一响应规范

{ "code": 1, "message": "获取成功", "data": {}, "other_data": "", "other_data2": "" }

• code=1 成功，其他为失败；message 为用户可读文案。
• 列表分页：data: { current_page, data: [], total, per_page, last_page, next_page_url, ... }。
• 业务错误：HTTP 200 + code≠1；认证失败：HTTP 401。

1. 认证模块

接口名称	方式	URL 路径	请求参数	响应示例
手机验证码登录	POST	/api/wechat-login-with-phone	{phone_number, code, ...}	{token, user}（原站登录入口，JWT iss 即此）
账号密码登录	POST	/api/login	{phone_number, password}	{token, ...}
验证码登录	POST	/api/code-login	{phone_number, code}	{token, ...}
发送验证码	POST	/api/verification-code-new	{phone_number, scene}	{code:1}
图形验证码	GET	/api/captcha	—	图形/{code:1,data}
注册并登录	POST	/api/register-and-login	{phone_number, password, code}	{token, ...}
忘记密码	POST	/api/forget-password	{phone_number, code, password}	{code:1}
微信登录	POST	/api/wechat-login	微信 OAuth code	{token, ...}

2. 用户模块

接口名称	方式	URL 路径	请求参数	响应示例（已验证 ✅ 节选）
当前用户信息	GET	/api/current-user	—	✅ {"id":3562856,"nickname":"...","phone_number":"...","company_id":1,"money":"0.00","try_expiration_time":"2026-09-23 00:00:00","son_account_type":1,"language":"zh-CN",...}
子账户列表	GET	/api/users?page=1	page	✅ Laravel 分页，data.data[]
邀请用户列表	GET	/api/invited_user_list?page=1	page	✅ 分页
修改密码	POST	/api/current-user/password	{old,new}	⏳
绑定微信	POST	/api/bind-wechat	code	⏳
解绑微信	POST	/api/unbind-wechat	—	⏳

3. 样板库模块（已全量采集 ✅）

接口名称	方式	URL 路径	请求参数	响应示例
窗型分类树	GET	/api/default_windoor_catelog	—	✅ 树：[{id:1,name:"推拉门",children:[{id:3,name:"平开"},...]}]
搜索官方模板	GET	/api/search_default_windoor	name（可选，按名称过滤）	✅ 无分页全量返回：data.data: [{id,name,pic_url,catelog_id,note,times}]，共 254 条
模板绘制详情	GET	/api/default_windoor_info/{id}	路径 id	✅ {id,drawing_data(编辑器画布JSON),pic_url,script_bar,script_glass,low/high_width,low/high_height,...}
用户自存窗型列表	GET	/api/windoor/	page	⏳（需服务端排序参数，待抓包）
用户窗型详情	GET	/api/windoor/{id}	路径 id	⏳（同 drawing_data 结构）
模板排序	POST	/api/windoor_template_sort	{ids:[...]}	⏳

drawing_data 结构参见《克隆实施方案.md》§2.2。

4. 客户模块

接口名称	方式	URL 路径	请求参数	响应示例
客户列表	GET	/api/customers_list	—	✅ [{id,name,phone,address,note,sort,type,salesmen,discount,balance,level,join_date}]
客户列表(分页)	GET	/api/customers	page,keywords	⏳
新增/编辑客户	POST	/api/customers	{name,phone,address,...}	⏳
客户跟进记录	GET	/api/customer_records/	customer_id	⏳
客户导入	POST	/api/customers_excel_in	Excel 文件	⏳

5. 合同/订单模块

接口名称	方式	URL 路径	请求参数	响应示例
合同列表	GET	/api/contracts	—	✅ {"contracts":{current_page,data:[{id,contract_no:"FG20260818009",customer,area,count,money,status:"意向单",cut_status,sign_status,contract_type,confirmed,discount,oids[],agency_money}]}}
意向单转合同	POST	/api/convert-contract/	{contract_id,...}	⏳
订单列表/搜索	POST	/api/orders/	搜索条件 JSON	⏳（只读采集未探测 POST）
订单详情	GET	/api/order-by-pid	pid	⏳
订单进度	GET	/api/get_order_process(_list)	order_id	⏳
合同确认	POST	/api/up-contract-confirmed/	{contract_id}	⏳
电子签名上传	POST	/api/update-contract-sign-status	{contract_id, sign_picture}	⏳
收款记录	GET	/api/contract_receipt_list/	contract_id	⏳
收款统计	GET	/api/contract_receipt_statistics(_tb)	date_range	⏳

6. 产品/价格模块

接口名称	方式	URL 路径	请求参数	响应示例
产品分类树	GET	/api/product-catelog	—	✅ 树（is_reference、lang、children）
全部产品	GET	/api/all-product	—	✅ data:[]（当前账户为空）
产品详情	GET	/api/product/{id}	路径 id	⏳
产品搜索	GET	/api/search-product	keywords	⏳
团队折扣	GET	/api/team-discount	—	⏳
报价单	GET	/api/quotations?page=1	page	✅ 分页（当前账户为空）

7. 仓库/库存模块

接口名称	方式	URL 路径	请求参数	响应示例
材料库存列表	GET	/api/warehouse_list	分页参数	✅ [{id,bom_code,name,material:"profile",cost,price,color,pricing_method,length,count,warning,unit,meter_weight,thick,agency_price}]
库存分类	GET	/api/warehouse_catelogs	—	⏳
收款账户	GET	/api/receipt_accounts	—	✅ [{id,type,name,number,bank,pic_url,is_default,balance}]
材料入库	POST	/api/product_move_in/	{...}	⏳
材料出库	POST	/api/product_move_out/	{...}	⏳
配件配置	GET	/api/materials_config	—	⏳

8. 优化下料/生产模块

接口名称	方式	URL 路径	请求参数	响应示例
一维优化	POST	/api/optimize1d	{bars:[], stock:[]}	⏳
切割方案	GET	/api/cut_solution(_new)/{contract_id}	路径	⏳
合同型材清单	GET	/api/contract_bars(_with_stock)	contract_id	⏳
更新切割状态	POST	/api/up-cut-status	{...}	⏳
订单打印模板	GET	/api/order_format/	—	⏳

9. 渲染/3D 模块

接口名称	方式	URL 路径	请求参数	响应示例
渲染信息	GET	/api/rendering-info	—	⏳
3D 数据	POST	/api/three-d-data	{drawing_data}	⏳
按订单取绘图	GET	/api/drawing_data_by_oid/{oid}	路径 oid	⏳
照片生成窗型(AI)	POST	/api/sketch-to-window-info	图片	⏳

10. 平台模块

接口名称	方式	URL 路径	请求参数	响应示例
公告列表	GET	/api/announcements	—	✅ [{id,name,desc,pic_url,content(富文本)}]
商城模块配置	GET	/api/company-module-info	—	✅ 25 个模块（名称/图标/描述/价格/试用天数）
帮助文档菜单	GET	/api/get-showdoc-menu	—	✅ showdoc 目录结构
操作日志	GET	/api/operation_logs?page=1	page	✅ 分页
业务员列表	GET	/api/salesmen	—	✅（当前账户为空）
反馈	POST	/api/feedback	{content}	⏳

标注说明：✅ = 已用只读请求实测并留存样本于 data/api-samples/；⏳ = 写入/低频接口未对生产系统探测，自研时按功能语义实现，或抓包后补全。