HHY
0d94fa2f29
- 采集 windoorcraft.com 全部前端路由(42条)、接口清单(约300条) - 样板库 254 套窗型模板全量采集(清单+分类+drawing_data 绘制数据) - 留存 16 个核心接口真实响应样本作为数据模型依据 - 输出克隆实施方案(架构/拖拽编辑器复刻/里程碑)与 API 对照文档 - 初始化 README 与 CHANGELOG
131 lines
7.9 KiB
Markdown
131 lines
7.9 KiB
Markdown
# API 接口文档
|
||
|
||
> 本文档记录自研系统的接口规范，并对照目标站已验证接口。目标站基址：`https://zzc-serv.thinkerx.com/api/`（仅作参照）。
|
||
> 自研系统基址：`/api/`（FastAPI 挂载）。
|
||
> 认证方式：`Authorization: Bearer <JWT>`（HS256，24h）；`X-Requested-With: XMLHttpRequest`；`Accept: application/json`。
|
||
|
||
## 0. 统一响应规范
|
||
|
||
```json
|
||
{ "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/`；⏳ = 写入/低频接口未对生产系统探测，自研时按功能语义实现，或抓包后补全。
|