销售统计系统 Web API 文档

基于ASP.NET Web API构建的后端接口服务

版本: v1.0.0 响应格式: JSON 跨域支持: 已启用

文档信息

基本信息
项目 说明
API名称 销售统计系统 Web API
版本 v1.0.0
基础URL https://localhost:44337/api/ (开发环境)
响应格式 JSON
字符编码 UTF-8
跨域支持 已启用 (CORS)
提示: 所有API都支持跨域请求,可以直接在前端项目中调用。

通用约定

响应格式

所有API响应都遵循以下标准格式:

{ "Success": true, // 操作是否成功 "Message": "操作成功", // 操作消息 "Data": { ... }, // 返回的数据 "Timestamp": "2024-01-15 10:30:00" // 响应时间戳 }

错误响应

{ "Success": false, "Message": "错误描述信息", "Timestamp": "2024-01-15 10:30:00" }
日期格式: 所有日期参数请使用 yyyy-MM-dd 格式,例如:"2024-01-15"

系统状态检查

GET

检查API状态

/api/test/ping

功能: 检查Web API服务是否正常运行

请求参数

响应示例
{ "Success": true, "Message": "Web API 运行正常", "Timestamp": "2026-02-09 11:26:49", "Version": "1.0.0" }

GET

回显测试

/api/test/echo/{text}

功能: 测试接口回显功能

路径参数
参数名 类型 必填 说明
text string 需要回显的文本
响应示例
{ "Success": true, "Message": "回显成功", "Original": "HelloWorld", "Echo": "你输入的是: HelloWorld", "Timestamp": "2026-02-09 11:27:36" }

仪表板数据

GET

获取仪表板统计数据

/api/dashboard/stats

功能: 获取首页仪表板的关键统计数据

请求参数

响应字段说明
字段名 类型 说明
TotalSales decimal 今日销售额
TotalInventory decimal 库存进价金额
TotalProfit decimal 今日毛利
TotalDebt decimal 总欠款金额
响应示例
{ "Success": true, "TotalSales": 123456.78, "TotalInventory": 45678.90, "TotalProfit": 23456.78, "TotalDebt": 56789.12, "Message": "获取成功", "Timestamp": "2024-01-15 10:30:00" }

门店管理

GET

获取门店列表

/api/stores/list

功能: 获取所有有效门店列表

请求参数

响应数据结构
{ "Success": boolean, "Data": [ { "id": number, // 门店ID "name": string // 门店名称 } ], "Count": number, "Message": string, "Timestamp": string }
响应示例
{ "Success": true, "Data": [ {"id": 1, "name": "北京分店"}, {"id": 2, "name": "上海分店"}, {"id": 3, "name": "广州分店"} ], "Count": 3, "Message": "获取成功", "Timestamp": "2024-01-15 10:30:00" }

供应商管理

GET

获取供应商分组列表

/api/suppliers/groups

功能: 获取供应商分组信息

请求参数

响应示例
{ "Success": true, "Data": ["全部", "华北区", "华东区", "华南区"], "Count": 4, "Message": "获取成功", "Timestamp": "2024-01-15 10:30:00" }

小组管理

POST

获取小组列表

/api/groups/list

功能: 根据门店ID获取对应的小组列表

请求头
Content-Type: application/json
请求参数
参数名 类型 必填 说明
StoreId integer 门店ID
请求示例
{ "StoreId": 1 }
响应示例
{ "Success": true, "Data": [ {"id": 1, "name": "销售一组"}, {"id": 2, "name": "销售二组"}, {"id": 3, "name": "售后组"} ], "Count": 3, "Message": "获取成功", "Timestamp": "2024-01-15 10:30:00" }

库存管理

POST

获取库存数据

/api/inventory/data

功能: 根据门店和截止日期获取库存统计

请求头
Content-Type: application/json
请求参数
参数名 类型 必填 说明
StoreId integer 门店ID
EndDate string 截止日期 (yyyy-MM-dd)
请求示例
{ "StoreId": 1, "EndDate": "2024-01-31" }
响应数据结构
{ "Success": boolean, "Data": [ { "Group": string, // 小组名称 "Quantity": integer, // 数量 "CostAmount": decimal, // 进价金额 "SaleAmount": decimal // 卖价金额 } ], "Count": number, "Message": string, "Timestamp": string }
响应示例
{ "Success": true, "Data": [ { "Group": "销售一组", "Quantity": 150, "CostAmount": 45000.00, "SaleAmount": 67500.00 } ], "Count": 1, "Message": "获取成功", "Timestamp": "2024-01-15 10:30:00" }

销售管理

POST

获取销售统计数据

/api/sales/total

功能: 获取销售统计数据,包括小组销售和其他相关数据

请求参数
参数名 类型 必填 说明
StoreId integer 门店ID
StartDate string 开始日期 (yyyy-MM-dd)
EndDate string 结束日期 (yyyy-MM-dd)
请求示例
{ "StoreId": 1, "StartDate": "2024-01-01", "EndDate": "2024-01-31" }
此接口返回复杂数据结构,包含三部分数据:小组销售数据、其他数据、汇总数据。
响应示例(简化版)
{ "Success": true, "GroupSales": [ { "group": "销售一组", "quantity": 120, "amount": 36000.00, "profit": 10800.00, "profitRate": "30%" } ], "OtherData": { "memberRecharge": 5000.00, "rechargeGift": 500.00, "storedValueConsume": 3000.00, "pointsOffset": 200.00, "manualDiscount": 800.00, "fullReduction": 300.00 }, "Summary": { "TotalQuantity": 120, "TotalAmount": 36000.00, "TotalProfit": 10800.00 }, "Message": "获取成功", "Timestamp": "2024-01-15 10:30:00" }

POST

获取销售明细数据

/api/sales/detail

功能: 获取详细的销售明细数据

请求参数
参数名 类型 必填 说明 默认值
StoreId integer? 可选 门店ID 0
GroupId integer? 可选 小组ID 0
StartDate string 开始日期 (yyyy-MM-dd) -
EndDate string 结束日期 (yyyy-MM-dd) -
响应示例
{ "Success": true, "Data": [ { "供应商": "XX供应商", "商品名称": "商品A", "销售": 50.00, "采购价": "100.00", "零售价": "150.00", "会员价": "130.00", "销售均价": 145.00, "销售额": 7250.00, "首批日期": "2024-01-10", "首批数量": "100.00", "库存": 50.00, "标签备注": "热销商品", "分店备注": "需补货", "类别": "电子产品" } ], "Count": 1, "Message": "获取成功", "Timestamp": "2024-01-15 10:30:00" }

欠款管理

POST

获取欠款统计数据

/api/debt/summary

功能: 获取供应商欠款统计数据

请求参数
参数名 类型 必填 说明
SupplierGroup string 供应商分组
StartDate string 开始日期 (yyyy-MM-dd)
EndDate string 结束日期 (yyyy-MM-dd)
请求示例
{ "SupplierGroup": "全部", "StartDate": "2024-01-01", "EndDate": "2024-01-31" }
注意: 此接口返回动态列结构,月份列会根据查询时间范围动态生成。
响应示例
{ "Success": true, "Data": [ { "供应商": "供应商A", "分店名称": "北京分店", "期初欠款": "10000.00", "2024-01": "5000.00", "2024-02": "3000.00", "期末欠款": "18000.00", "合计": "" } ], "ColumnOrder": [ "供应商", "分店名称", "期初欠款", "2024-01", "2024-02", "期末欠款", "合计" ], "DynamicColumns": ["2024-01", "2024-02"], "Count": 1, "Message": "获取成功", "Timestamp": "2024-01-15 10:30:00" }

前端调用示例

JavaScript Fetch API 示例

1. 获取仪表板数据 (GET)
// 异步函数方式 async function getDashboardStats() { try { const response = await fetch('https://localhost:44337/api/dashboard/stats'); const data = await response.json(); if (data.Success) { console.log('销售额:', data.TotalSales); console.log('库存金额:', data.TotalInventory); // 处理数据... return data; } else { console.error('获取失败:', data.Message); return null; } } catch (error) { console.error('网络错误:', error); return null; } } // 调用示例 getDashboardStats().then(data => { if (data) { // 更新UI document.getElementById('sales').textContent = '¥' + data.TotalSales.toFixed(2); document.getElementById('inventory').textContent = '¥' + data.TotalInventory.toFixed(2); } });
2. 获取销售统计 (POST)
async function getSalesTotal(storeId, startDate, endDate) { const response = await fetch('https://localhost:44337/api/sales/total', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ StoreId: storeId, StartDate: startDate, EndDate: endDate }) }); const data = await response.json(); return data; } // 调用示例 getSalesTotal(1, '2024-01-01', '2024-01-31') .then(result => { if (result.Success) { // 处理小组销售数据 result.GroupSales.forEach(group => { console.log(`${group.group}: ${group.quantity}件, ¥${group.amount}`); }); // 处理汇总数据 console.log(`总计: ${result.Summary.TotalQuantity}件, ¥${result.Summary.TotalAmount}`); } });

jQuery AJAX 示例

使用jQuery调用
// 获取门店列表 $.ajax({ url: 'https://localhost:44337/api/stores/list', type: 'GET', success: function(data) { if (data.Success) { // 填充下拉菜单 var select = $('#storeSelect'); select.empty(); data.Data.forEach(store => { select.append(`<option value="${store.id}">${store.name}</option>`); }); } }, error: function(error) { console.error('获取门店列表失败:', error); } }); // POST请求示例 - 获取小组列表 $('#storeSelect').change(function() { var storeId = $(this).val(); $.ajax({ url: 'https://localhost:44337/api/groups/list', type: 'POST', contentType: 'application/json', data: JSON.stringify({ StoreId: storeId }), success: function(data) { if (data.Success) { // 处理小组数据 console.log('获取到', data.Count, '个小组'); } } }); });
重要: 在生产环境中,请将基础URL替换为实际的生产环境地址。

错误代码说明

错误情况 处理建议
网络连接失败 检查网络连接和API地址是否正确
返回 Success: false 查看Message字段获取错误详情,根据错误信息调整请求
跨域错误 (CORS) 确保API已正确启用CORS配置,检查请求头设置
参数格式错误 检查JSON格式是否正确,参数类型是否符合要求
日期格式错误 确保使用 yyyy-MM-dd 格式,例如:"2024-01-15"
返回空数据 检查查询条件是否匹配数据库中的数据
数据库连接失败 检查数据库连接字符串,确保数据库服务正常运行
调试建议: 使用浏览器开发者工具的"网络"标签查看请求和响应详情,有助于快速定位问题。

部署说明

开发环境配置

生产环境部署

1. 修改前端配置
// 前端JavaScript配置 const API_CONFIG = { // 开发环境 development: { baseUrl: 'https://localhost:44337/api/' }, // 生产环境 production: { baseUrl: 'https://api.your-domain.com/api/' } }; // 根据环境使用不同的配置 const currentEnv = process.env.NODE_ENV || 'development'; const API_BASE_URL = API_CONFIG[currentEnv].baseUrl;
2. 配置生产环境连接字符串
<!-- Web.config --> <connectionStrings> <add name="MyConnectionString" connectionString="Data Source=生产服务器IP;Initial Catalog=SalesDB;User ID=sa;Password=生产密码;Integrated Security=False;Connect Timeout=30" providerName="System.Data.SqlClient" /> </connectionStrings>

IIS部署步骤

  1. 在IIS中创建新的应用程序池(.NET Framework 4.x,集成模式)
  2. 创建新的网站或应用程序,指向发布目录
  3. 配置正确的身份验证和权限
  4. 配置SSL证书(如果需要HTTPS)
  5. 测试API接口是否正常响应
安全建议: 生产环境建议启用HTTPS,限制CORS源,并配置适当的防火墙规则。