云谱光学工具箱-小程序API接口连接与落地方案.docx
云谱光学工具箱 小程序 API 接口连接与落地方案 （技术实施方案） 编制单位：双色云谱（杭州双色智能检测仪器有限公司） 文档版本：V1.0 适用对象：产品、前端、后端、硬件与测试团队 目录 1 项目背景与目标 4 1.1 项目背景 4 1.2 建设目标与差异化 4 1.3 与官网技术栈的关系 4 2 总体架构设计 5 2.1 系统架构 5 2.2 技术选型 5 2.3 与官网后端的关系 5 3 小程序端设计 5 3.1 页面与功能模块映射 5 3.2 请求封装与错误处理 6 3.3 登录与会话 6 4 后端 API 接口设计 6 4.1 接口规范 6 4.2 用户与账号 6 4.3 工具计算类接口 6 4.4 合规判定接口 7 4.5 招标条款生成接口 7 4.6 国标速查接口 7 4.7 测评与报告接口 8 4.8 仪器对接接口 8 4.9 商城与服务接口 8 4.10 收藏与最近使用接口 8 5 数据库设计 9 5.1 数据表清单 9 5.2 关键表字段设计 9 6 AI 能力接入（DeepSeek） 9 6.1 一句话计算 / 粘贴识别 9 6.2 招标条款生成 9 6.3 报告智能摘要与判定 10 7 仪器硬件对接方案 10 7.1 BLE 蓝牙对接流程 10 7.2 光谱 / 照度计数据协议 10 7.3 本地计算与云端判定分工 10 8 安全与合规 10 8.1 接口鉴权 10 8.2 数据安全与隐私 10 9 部署与运维 11 9.1 环境与发布 11 9.2 日志监控与限流 11 10 里程碑与工作量估算 11 10.1 分期规划 11 10.2 资源与排期 11 1 项目背景与目标 1.1 项目背景 云谱光学工具箱是双色云谱旗下面向照明与光学检测领域的小程序，定位为“专业光学，随手可算”。小程序集照明计算、光学标准速查、专业名词词典、在线测评与仪器对接、商城与服务于一体，目标用户为照明设计工程师、检测人员、院校科研机构及行业采购方。 在功能规划阶段，团队对标了同类产品“叙光录LED工具箱”，吸收其“一句话计算/粘贴识别、合规判定（能效等级、LPD、频闪）、招标条款生成、国标速查与算灯数”等高效交互，并结合双色云谱自有仪器（HP350 手持光谱照度计、SS200 光谱仪、成像亮度/色度计等）形成差异化优势——即“仪器直连实测 + 云端判定 + 一键出报告”，这是纯计算类小程序所不具备的能力。 1.2 建设目标与差异化 本项目的建设目标包括： （1）提供覆盖照明设计、光色、电与热、合规判定、标准速查、术语词典的全专业计算与速查能力； （2）通过 BLE 蓝牙与仪器直连，实现“实测数据自动带入、逐项对标国标判合格、一键生成 CNAS 式报告”； （3）接入 DeepSeek 大模型，提供“一句话计算”参数自动识别与招标条款智能生成； （4）打通商城与服务，实现仪器选型、灯具采购、上门检测预约的业务闭环。 1.3 与官网技术栈的关系 官网（doublecloudspectrum.com）采用 Vue3 + Vite + Element Plus + Pinia 前端技术栈，后端接口统一以 /api/v1 为前缀，并已内置 DeepSeek 大模型调用配置。本小程序后端优先复用官网现有后端服务：新增模块以 /api/v1/toolkit/* 前缀划分，保留统一鉴权、日志、限流与错误码体系，避免重复建设；对计算密集或与仪器相关的能力，可独立拆分服务以支持水平扩展。 2 总体架构设计 2.1 系统架构 系统总体架构分为四层：客户端层、接入层、服务层与数据层。客户端层包含微信小程序与官网 Web 端；接入层负责登录鉴权、请求路由与限流；服务层承载工具计算、标准速查、AI 能力、仪器对接、测评报告与商城订单等业务；数据层使用 MySQL（业务数据）、Redis（缓存与会话）、对象存储 OSS（报告与图片）。 2.2 技术选型 表2-1 技术选型清单 2.3 与官网后端的关系 推荐采用“单体优先、按需拆分”的策略：一期复用官网 Spring Boot 后端，在 /api/v1 下新增 toolkit 前缀；当工具计算请求量增大或需要独立部署时，将 toolkit 模块拆分为独立微服务。对 BLE 仪器对接相关的状态机与数据暂存，单独设计内存态服务以保证实时性。 3 小程序端设计 3.1 页面与功能模块映射 小程序端页面与 UI 原型 v2 保持一致，采用底部六页导航：首页、计算、合规、标准、测评、我的。各页面调用的主要后端模块如下表所示。 表3-1 页面与后端模块映射 3.2 请求封装与错误处理 小程序端统一封装 request 请求层，携带 Token 与租户标识，统一处理 401 重新登录、业务错误码展示、网络超时与重试；对计算类接口支持服务端渲染与本地缓存。 3.3 登录与会话 小程序端调用 wx.login 获取 code，后端通过 code2session 换取 openid，生成 JWT Token 返回；Token 有效期结合 Redis 会话管理，敏感操作（下单、上传）二次校验。 4 后端 API 接口设计 4.1 接口规范 所有接口遵循 RESTful 风格，统一前缀 /api/v1/toolkit，响应格式为：{ code, message, data }。code=0 表示成功，非 0 为业务错误码。接口鉴权采用 Authorization: Bearer 。 表4-1 统一响应格式 4.2 用户与账号 用户通过微信授权登录，建立小程序端用户与官网账号体系打通。 表4-2 用户账号接口 4.3 工具计算类接口 工具计算接口接收参数并返回结果，支持服务端计算以保证一致性。以下为核心计算接口。 表4-3 工具计算接口 4.4 合规判定接口 合规判定接口接收产品与场所参数，按对应国标逐项判定并返回是否合格及具体依据条款。 表4-4 合规判定接口 4.5 招标条款生成接口 根据场所类型与产品类型，结合标准库生成可进入招标文件或技术协议的参数条款清单，每条注明依据。 表4-5 招标条款接口 4.6 国标速查接口 提供场所标准值查询与“按 lx 算灯数”联动。 表4-6 国标速查接口 4.7 测评与报告接口 测评中心支持仪器直连与数据上传，自动判定并生成报告。 表4-7 测评与报告接口 4.8 仪器对接接口 仪器通过 BLE 蓝牙与小程序的连接与数据采集。 表4-8 仪器对接接口 4.9 商城与服务接口 复用官网商城能力，小程序端提供商品浏览、询价与上门检测预约。 表4-9 商城与服务接口 4.10 收藏与最近使用接口 提供工具收藏与最近使用记录，支撑首页快捷入口。 表4-10 用户行为接口 5 数据库设计 5.1 数据表清单 数据库以业务域划分，核心表如下： 表5-1 数据表清单 5.2 关键表字段设计 以测评记录表 test_record 为例，核心字段包括： 表5-2 测评记录关键字段 6 AI 能力接入（DeepSeek） 6.1 一句话计算 / 粘贴识别 用户粘贴规格书或聊天参数后，后端调用 DeepSeek 进行结构化抽取：识别产品类型、光通量、功率、色温、Ra、光束角等关键参数，并推荐匹配的工具。抽取结果以 JSON 返回，前端自动填表。对识别置信度低的字段标记“待核对”，不强制改写用户输入。 6.2 招标条款生成 基于场所与产品类型，结合标准库检索对应条款，由大模型整合为可直接进入招标文件的参数条款，每条注明依据标准编号。生成前对标准内容做向量检索（RAG）以提升准确性，避免模型臆造条款。 6.3 报告智能摘要与判定 测评数据入库后，AI 生成结论摘要、合格/不合格判定及整改建议，并映射到 CNAS 风格报告模板。AI 判定仅作辅助，正式报告以规则引擎逐项校核为准，保证结果可复现、可追溯。 7 仪器硬件对接方案 7.1 BLE 蓝牙对接流程 小程序通过微信 BLE API 与 HP350 等支持蓝牙的仪器连接：扫描→配对→订阅特征值→接收光谱/照度数据。数据帧按仪器协议解析，实时显示并暂存本地，用户确认后上传云端判定。 7.2 光谱 / 照度计数据协议 仪器返回的光谱数据（波长-辐照度数组）、照度、色温、显色指数等按统一 JSON 结构上传，后端解析后写入测评记录。对不支持蓝牙的仪器（如串口成像色度计），提供“数据文件上传”通道（Excel/CSV/PDF 解析）。 7.3 本地计算与云端判定分工 实时曲线与基础换算在端上完成以保证流畅；合规判定、多标准交叉校核、报告生成在云端完成，保证判定逻辑与标准库版本一致、可审计。 8 安全与合规 8.1 接口鉴权 使用微信 code2session 换取 openid，签发 JWT Token；Token 短时有效并配合 Redis 刷新机制。敏感接口校验用户权限与数据归属，防止越权访问他人测评记录与报告。 8.2 数据安全与隐私 用户手机号、订单信息等敏感数据加密存储；测评数据与报告按用户隔离，报告下载走 OSS 签名 URL 并设有效期；遵循《个人信息保护法》与微信平台用户隐私保护指引，仅采集实现功能所必需的数据。 9 部署与运维 9.1 环境与发布 小程序端经微信审核后发布；后端按开发/测试/生产三环境管理，使用 Docker 容器化部署，配置 CI/CD 流水线；域名配置 HTTPS 并加入微信 request 合法域名。 9.2 日志监控与限流 统一接入日志采集与链路追踪，监控计算接口耗时、AI 调用成功率与错误率；对 AI 与计算接口做基于用户与 IP 的限流，防止恶意刷接口。 10 里程碑与工作量估算 10.1 分期规划 表10-1 分期规划 10.2 资源与排期 建议配置前端 1 人、后端 1-2 人、AI/算法 0.5 人、硬件固件 1 人、测试 1 人。一期核心功能（登录、计算、标准、合规）约 6-8 周；BLE 仪器对接与报告约 4-6 周；AI 能力约 3-4 周。总工期视团队规模与并行度调整，详见项目排期。 模块 | 技术选型 | 说明 小程序端 | 微信小程序原生 / uni-app | 原生优先；uni-app 便于后续多端复用 后端服务 | Spring Boot 3 / Node.js(NestJS) | 与官网后端统一技术栈，复用 /api/v1 数据库 | MySQL 8 + Redis | 业务数据 + 缓存/会话/限流 对象存储 | 阿里云 OSS / 腾讯 COS | 报告 PDF、图片、Excel 附件 AI 能力 | DeepSeek 大模型 | 一句话计算识别、条款生成、报告摘要 推送 | 微信订阅消息 | 报告生成、预约提醒 页面 | 主要功能 | 调用后端模块 首页 | 一句话计算、最近使用、快捷入口 | AI识别、用户行为 计算 | 照明设计/光色/电与热/光效/单位换算 | 工具计算 合规 | 能效等级/LPD/频闪/检测合规/招标条款/国标速查 | 合规判定、AI条款 标准 | 标准速查、术语词典 | 标准库 测评 | 连接仪器/上传数据/历史/报告 | 仪器对接、测评报告 我的 | 商城、收藏、最近使用、服务 | 商城订单、用户中心 字段 | 类型 | 说明 code | int | 0 成功；非 0 业务错误码 message | string | 提示信息 data | object/array | 业务数据 接口 | 方法 | 路径 | 说明 小程序登录 | POST | /api/v1/toolkit/auth/login | code 换 token 获取用户信息 | GET | /api/v1/toolkit/user/profile | 昵称/手机号 更新用户信息 | PUT | /api/v1/toolkit/user/profile | 资料维护 手机号绑定 | POST | /api/v1/toolkit/user/phone | 绑定手机 接口 | 方法 | 路径 | 说明 照度估算 | POST | /api/v1/toolkit/calc/illuminance | 利用系数法算灯数 光效计算 | POST | /api/v1/toolkit/calc/efficacy | 灯珠→整灯光效 色坐标转色温 | POST | /api/v1/toolkit/calc/cct | x,y→CCT/Duv 光束与光斑 | POST | /api/v1/toolkit/calc/beam | 射灯光斑计算 道路照明间距 | POST | /api/v1/toolkit/calc/road | 路灯间距 串并联驱动匹配 | POST | /api/v1/toolkit/calc/driver | 驱动匹配 结温估算 | POST | /api/v1/toolkit/calc/junction | 结温 光衰寿命推算 | POST | /api/v1/toolkit/calc/lifespan | LM-80→TM-21 L70 低压线路压降 | POST | /api/v1/toolkit/calc/voltagedrop | 线路压降 单位换算 | POST | /api/v1/toolkit/calc/unit | 单位换算 接口 | 方法 | 路径 | 依据标准 能效等级判定 | POST | /api/v1/toolkit/compliance/efficiency | GB 30255 检测报告合规 | POST | /api/v1/toolkit/compliance/report | 多标准 LPD 校核 | POST | /api/v1/toolkit/compliance/lpd | GB 55015 / GB/T 50034 频闪风险判定 | POST | /api/v1/toolkit/compliance/flicker | IEEE 1789 接口 | 方法 | 路径 | 说明 生成招标条款 | POST | /api/v1/toolkit/ai/tender | 返回条款列表 保存条款模板 | POST | /api/v1/toolkit/ai/tender/save | 保存常用 获取条款历史 | GET | /api/v1/toolkit/ai/tender/history | 历史记录 接口 |…