# 一码通文档（全量镜像） > 北京引瓴数智科技有限公司一码通产品公开文档的单文件镜像，供 AI 助手一次性加载。人类读者请访问 https://docs.yinlingshuzhi.com（本文件由构建脚本自动生成，请勿手工编辑） --- ## 身份与租户 URL: https://docs.yinlingshuzhi.com/developers/authentication --- title: 身份与租户 description: API 凭证、租户解析和访问边界 --- # 身份与租户 ## 核心规则 - Token 中的 `tenant_id`、`user_id` 和会话版本由服务端签发； - 客户端不能通过修改请求参数或租户 Header 切换授权企业； - 门户不读取或保存控制台业务 Token； - 跨子域登录使用一次性授权结果，禁止在 URL 中传递长期 Token； - 沙箱与生产凭证严格分离。 ## 日志要求日志可以记录请求 ID、脱敏主体和结果码，不得记录完整 Token、短信验证码、微信授权响应或客户业务数据。 --- ## 错误与重试 URL: https://docs.yinlingshuzhi.com/developers/errors --- title: 错误与重试 description: API 错误分类、请求 ID 与安全重试原则 --- # 错误与重试 ## 分类原则 | 类型 | 建议动作 | |---|---| | 参数错误 | 修正请求，不自动重试 | | 身份或权限错误 | 刷新授权或联系管理员，不循环重试 | | 幂等冲突 | 核对原请求和业务意图 | | 限流 | 按服务端提示退避 | | 服务暂时不可用 | 保留请求 ID，有限次数退避重试 | 支持请求时提供请求 ID、时间、接口路径和脱敏参数，不要粘贴 Token、手机号、OpenID 或完整业务数据。 --- ## 请求幂等 URL: https://docs.yinlingshuzhi.com/developers/idempotency --- title: 请求幂等 description: 写操作的幂等键、冲突处理和安全重试 --- # 请求幂等 ## 什么时候需要创建码包、提交任务、创建订单或其他可能被网络重试的写操作需要幂等保护。 ## 约定 - 每个业务意图生成一个不可猜测的幂等键； - 相同键和相同请求摘要返回同一结果； - 相同键但请求内容不同返回冲突； - 超时后先查询原请求状态，不要立即换新键重复创建； - 具体 Header 名称和有效期以正式 OpenAPI 为准。 --- ## 开发者快速开始 URL: https://docs.yinlingshuzhi.com/developers/ --- title: 开发者快速开始 description: 一码通 API 接入前的身份、沙箱和安全准备 --- # 开发者快速开始 > [!CAUTION] > 当前公开 OpenAPI 和沙箱尚未发布。本文只定义接入顺序和安全要求，示例地址与凭证均不可用于生产。 ## 最短成功路径 ```text 创建测试应用 → 获取受限凭证 → 调用沙箱接口 → 接收 Webhook → 验签与幂等 → 查看调用日志 → 申请生产权限 ``` ## 示例请求 ```bash curl -X GET \ https://api-sandbox.yinlingshuzhi.com/v1/products/demo-product \ -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \ -H "Content-Type: application/json" ``` `YOUR_SANDBOX_TOKEN` 是明显的占位符。不要将真实凭证写入源码、文档、截图或工单。 ## 继续阅读 - [身份与租户](./authentication) - [请求幂等](./idempotency) - [错误与重试](./errors) --- ## 创建批次与码包 URL: https://docs.yinlingshuzhi.com/getting-started/create-code-package --- title: 创建批次与码包 description: 为商品 SKU 创建测试批次和二维码码包 --- # 创建批次与码包 ## 目标为一个明确的“商品 + SKU”创建测试批次和码包，并能核对生成数量、状态和归属。 ## 操作步骤 1. 进入“批次管理”，选择商品后再选择该商品的 SKU。 2. 填写测试批次号、计划数量和必要日期。 3. 保存批次后进入“码包管理”，选择该批次创建码包。 4. 输入测试数量并提交生成任务。 5. 等待任务完成，核对成功数量、失败数量和码包状态。 6. 仅导出测试用途的二维码，避免与生产码混用。 ## 异常处理 - 生成数量超过套餐额度：停止任务并查看额度说明； - 任务长时间处理中：记录任务编号后查看任务状态，不要重复提交； - 部分失败：下载失败明细，确认原因后创建新的补充任务。 ## 完成检查码包必须能追溯到商品名称、SKU 编码和批次号。 --- ## 创建第一个商品 URL: https://docs.yinlingshuzhi.com/getting-started/create-product --- title: 创建第一个商品 description: 创建商品与 SKU 主数据并完成字段核对 --- # 创建第一个商品 ## 目标创建一个商品及至少一个归属于该商品的 SKU。任何 SKU 都必须能看出所属商品，不能作为脱离商品语境的孤立编码出现。 ## 准备资料 - 商品名称、品牌和类目； - SKU 名称与 SKU 编码； - 规格、单位和必要图片； - 企业内部已有编码时，先确认唯一性。 ## 操作步骤 1. 登录控制台，进入“商品管理”。 2. 点击“新增商品”，填写商品基础资料并保存。 3. 在商品详情中新增 SKU，填写规格与编码。 4. 返回列表，通过“商品 → SKU”联动筛选核对关系。 ## 成功证据 - 商品列表能找到新商品； - SKU 列表同时显示商品名称与 SKU 编码； - 导出时包含商品名称和 SKU 编码； - 重复编码会被系统明确拒绝。 --- ## 完成第一次扫码 URL: https://docs.yinlingshuzhi.com/getting-started/first-scan --- title: 完成第一次扫码 description: 扫描测试二维码并核对商品展示与扫码事件 --- # 完成第一次扫码 > [!WARNING] > 隔离扫码 Demo 尚未完成。正式文档发布前需替换为可公开测试、不会产生真实奖励的 Demo 地址。 ## 操作步骤 1. 使用手机相机或微信扫描测试二维码。 2. 确认页面域名、品牌名称和商品信息正确。 3. 查看验真结果、批次和溯源信息。 4. 返回控制台，进入扫码记录查看对应事件。 ## 成功证据 - 扫码页面与二维码关联的是同一商品、SKU 和批次； - 测试页面明确标识 Demo，不产生真实奖励； - 后台事件包含时间、码状态和必要的脱敏信息； - 重复扫码策略符合当前配置。 --- ## 试点开通与第一次扫码 URL: https://docs.yinlingshuzhi.com/getting-started/ --- title: 试点开通与第一次扫码 description: 企业从手机号验证开通工作台，到完成第一次商品扫码的路径 --- # 试点开通与第一次扫码 > [!IMPORTANT] > 当前为 **SaaS 试点**：手机号验证即可开通企业工作台，邀请码选填（填写后须有效）。微信扫码登录与在线支付不在本阶段范围。 ## 目标完成手机号验证与企业开户，进入真实控制台，创建商品与码包，并用手机完成第一次扫码。 ## 前置条件 - 可以接收短信的中国大陆手机号； - 邀请码或邀请链接（含 `inviteCode`）：选填，有则填写； - 企业名称与基本商品资料； - 测试阶段不得使用真实生产码投入市场。 ## 操作路径 1. 按[开通与首次登录](./register-login)完成验证与企业空间创建。 2. 按[创建第一个商品](./create-product)建立商品主数据。 3. 按[创建批次与码包](./create-code-package)生成测试二维码。 4. 按[完成第一次扫码](./first-scan)验证展示内容和扫码事件。 ## 完成检查 - [ ] 能进入属于当前企业的控制台（同域 `/console/`）； - [ ] 商品、SKU 与批次关系正确； - [ ] 测试码状态可查询； - [ ] 手机扫码能看到预期商品信息； - [ ] 后台能看到对应测试扫码事件。 ## 下一步阅读[组织与权限](/guides/organization-permissions)，邀请同事并按职责授权。尚未受邀的企业请[预约产品演示](https://www.yinlingshuzhi.com/contact?type=demo)。 --- ## 开通与首次登录 URL: https://docs.yinlingshuzhi.com/getting-started/register-login --- title: 开通与首次登录 description: 企业使用手机号验证码开通一码通工作台的流程与安全边界 --- # 开通与首次登录 > [!IMPORTANT] > 正式入口为 `www.yinlingshuzhi.com/login`。手机号验证即可开通，**邀请码选填**：填写后必须有效，并按邀请方展示品牌与归属渠道。微信扫码登录将在后续阶段开放。 ## 开通（手机号） 1. 打开登录页；如有邀请链接（含 `inviteCode`）会自动带入邀请码，也可手动填写运营提供的邀请码，不填同样可以继续。 2. 输入手机号，点击「获取验证码」，先完成图形验证（滑动拼图、文字点选或算式，按平台配置显示），再接收 6 位短信验证码。 3. 填写短信验证码，勾选服务协议与隐私政策。 4. 若该手机号尚未开户：填写企业名称，系统创建企业空间、Owner、FREE（试点）订阅与基础权限。 5. 若该手机号已开户或已被企业邀请为成员：验证通过后直接进入对应企业的控制台。 6. 浏览器经一次性凭证跳转到同域 `/console/`，地址栏不会出现长期 Token。验证码 6 位、约 5 分钟有效、一次性消费；连续输错 5 次即作废，需重新获取。同一手机号 60 秒内只能获取一次，并有每日次数上限。填写了无效或已停用的邀请码时无法完成开户。 ## 本阶段不做 - 微信扫码登录 - 在线支付与自助升档（PRO 由线下合同 / 人工开通） ## 成功证据成功后进入自己的企业控制台。浏览器不能通过修改租户参数进入其他企业。 ## 常见问题收不到验证码或登录后没有权限时，参阅[登录故障排查](/help/login-troubleshooting)。 --- ## 渠道与风控 URL: https://docs.yinlingshuzhi.com/guides/channel-risk --- title: 渠道与风控 description: 渠道流向、异常识别与处置闭环 --- # 渠道与风控 ## 目标围绕出库、运输、到货和签收形成可核对证据，在发现异常流向时定位商品、SKU、批次和渠道节点。 ## 处置原则预警只是线索，不直接等同于违规事实。处置前应核对规则版本、渠道授权、业务单据和扫码证据，并保留处理记录。 --- ## 码管理 URL: https://docs.yinlingshuzhi.com/guides/code-management --- title: 码管理 description: 码包、生成任务、导出和状态管理概览 --- # 码管理 ## 核心对象 - 码规则：定义编码和使用约束； - 码包：一组归属于商品、SKU 和批次的编码； - 生成任务：异步产生或导出码文件； - 单码状态：未使用、已赋码、已激活、已作废等受控状态。 ## 安全边界码文件属于敏感生产资料。下载链接应短时有效，操作需要审计，不应通过聊天或公共网盘传递。 --- ## 组织与权限 URL: https://docs.yinlingshuzhi.com/guides/organization-permissions --- title: 组织与权限 description: 邀请成员、配置角色和验证数据权限 --- # 组织与权限 ## 基本原则 - 默认最小权限； - 成员通过角色获得菜单、页面和操作权限； - 数据范围必须与企业、组织和业务职责一致； - 停用成员后，旧会话必须失效。 ## 配置步骤 1. 在“组织管理”创建部门或业务组。 2. 在“角色管理”创建角色并勾选所需菜单和按钮权限。 3. 邀请成员，分配组织与角色。 4. 使用测试账号重新登录，验证列表、详情、导出和操作按钮。 > [!TIP] > 新增页面、菜单或按钮权限后，需要在 `系统管理 → 角色管理` 中授权，否则 `v-auth` 可能隐藏入口。 --- ## 商品与主数据 URL: https://docs.yinlingshuzhi.com/guides/product-master-data --- title: 商品与主数据 description: 商品、SKU、类目和规格之间的数据关系 --- # 商品与主数据 ## 数据关系商品描述可对外识别的产品主体，SKU 描述可库存、可销售或可赋码的具体规格。列表、详情、筛选和导出都应保留“商品 → SKU”的上下文。 ## 管理建议 - 先确定商品，再维护所属 SKU； - SKU 编码在企业范围内保持唯一； - 导入前先下载当前版本模板； - 导入结果必须区分成功、失败和未处理； - 删除前检查批次、码包、库存和订单引用。 --- ## 登录故障排查 URL: https://docs.yinlingshuzhi.com/help/login-troubleshooting --- title: 登录故障排查 description: 验证码、微信二维码、企业状态和权限问题的安全排查路径 --- # 登录故障排查 ## 收不到短信验证码 1. 确认手机号和国家/地区正确。 2. 查看是否仍在重发等待时间内。 3. 检查手机拦截、欠费或运营商延迟。 4. 不要连续频繁点击发送。 5. 仍失败时，提供时间、页面和脱敏手机号，不要提供验证码。 ## 微信二维码过期刷新二维码后重新扫码。不要重复使用旧回调页面或把授权链接发送给他人。 ## 登录后看不到功能请企业管理员在 `系统管理 → 角色管理` 检查页面、菜单和按钮权限，并确认成员仍为启用状态。 ## 提交支持信息可以提供浏览器版本、发生时间、请求 ID 和页面地址。不要提供密码、Token、短信验证码、微信 OpenID 或客户完整数据。 --- ## 一码通文档中心 - 快速上手与产品指南 URL: https://docs.yinlingshuzhi.com/ --- layout: false title: 一码通文档中心 - 快速上手与产品指南 titleTemplate: false description: 快速上手、产品指南、场景教程、开发者和实施运维文档 --- --- ## 短信与微信登录配置 URL: https://docs.yinlingshuzhi.com/operations/sms-wechat-login --- title: 短信与微信登录配置 description: 阿里云短信和微信开放平台网页应用的开发与生产配置边界 --- # 短信与微信登录配置 > [!CAUTION] > 本页只公开安全边界，不公开 AccessKey、AppSecret、签名密钥、回调校验材料或管理接口。 ## 阿里云短信 - 购买短信资源不等于可以直接上线； - 需要完成短信签名、模板审核和发送域名/账号配置； - AccessKey 只放在受控服务端环境或密钥管理系统； - 开发环境优先使用模拟适配器，不向真实手机号批量发送； - 日志不得记录验证码或完整手机号。 ## 微信扫码登录 - 使用微信开放平台“网站应用”的扫码登录能力； - 开发和测试需要同一公司备案主域下的固定测试子域，不能使用本机回环地址； - 授权回调域名只填写主机名，回调路径由服务端固定； - `state` 必须由服务端随机生成、一次性使用并绑定浏览器会话； - 微信首次注册仍需验证手机号，用于账号唯一性和找回。 ## 上线检查 - [ ] 测试与生产 AppID、密钥和回调地址隔离； - [ ] 短信签名主体为北京引瓴数智科技有限公司； - [ ] 回调只通过 HTTPS； - [ ] 敏感响应不进入日志； - [ ] 登录失败不会泄露账号是否存在。 --- ## 套餐与价格 URL: https://docs.yinlingshuzhi.com/plans/pricing --- title: 套餐与价格 description: 一码通 FREE、PRO 与 ENTERPRISE 首发价格、适用范围和费用边界 --- # 套餐与价格公开价格均为人民币含税价。最终权益、额度和服务期以购买页、订单、报价单或合同为准。 | 套餐 | 价格 | 适用场景 | 购买方式 | | --- | ---: | --- | --- | | FREE | ¥0 | 验证商品、批次、二维码、扫码验真与基础追溯 | 手机号验证即可开通，邀请码选填 | | PRO | ¥1,280/月；¥12,800/年 | 品牌装修、会员、积分、券、扫码活动、渠道流向与团队协作 | 线下合同 / 人工开通（试点阶段） | | ENTERPRISE | ¥49,800/年起 | 高码量、复杂组织、系统集成、专属应用和服务保障 | 联系顾问并签署合同 | ## FREE - 1 个商品、3 个成员； - 每年最多 1,000 个码； - 每年最多 10,000 次扫码记录； - 1 GB 存储； - 基础商品与批次建档； - 扫码验真与基础追溯； - 扫码记录保留 90 天； - 文档自助支持。 FREE 用于验证闭环，不适合作为长期大规模生产环境。 ## PRO - 品牌装修与多品牌管理； - 会员、积分、优惠券和扫码活动； - 渠道流向与基础风险管控； - 20 个成员席位； - 500 个商品； - 每年 10,000 个码、100,000 次扫码记录； - 100 GB 存储。年付价格约等于 10 个月月付价格。首发价格将在上线后 90 天根据使用量、支持成本和客户转化情况复盘；已经生效的订单在原服务期内不追溯涨价。 ## ENTERPRISE ENTERPRISE 为合同制方案，¥49,800/年是软件订阅起价，不代表固定交付范围。最终价格由实际用量、组织规模、集成范围、专属应用、迁移和服务保障共同确定。 ## 不默认包含的费用以下费用应在购买页、报价单或合同中单独列明： - 实施与数据迁移； - 定制开发； - 短信； - 额外专属消费者应用； - 第三方支付通道费； - 超出套餐的存储、接口或其他资源； - 外部认证、硬件、标签印刷及合作伙伴服务。 ## 支付、发票与退款 - 在线支付支持范围以正式收银台为准； - 可开票金额以实际支付且未退款金额为准； - 年度订阅支付后七个自然日内，如未启用付费权益且未产生付费资源消耗，可申请全额退款； - 权益已激活、资源已消耗或实施服务已交付后，按照服务协议、订单和合同处理退款； - 重复支付或平台确认无法交付的部分，经核实后原路退款或协商恢复服务。购买前请阅读门户的[服务协议](https://www.yinlingshuzhi.com/terms)与[隐私政策](https://www.yinlingshuzhi.com/privacy)。 --- ## 更新日志 URL: https://docs.yinlingshuzhi.com/releases/ --- title: 更新日志 description: 一码通公开版本更新、迁移和弃用说明 --- # 更新日志当前尚未发布正式对外版本号。首个公开版本发布后，本页将记录： - 新功能与行为变化； - 修复内容； - 权限和配置变化； - 破坏性变更与迁移指南； - 弃用能力和停止支持日期。没有文档、迁移说明和验证证据的功能，不会在这里标记为已发布。 ## 订阅更新支持 RSS 订阅：；AI 助手可通过 [llms-full.txt](https://docs.yinlingshuzhi.com/llms-full.txt) 一次性加载全站内容。 --- ## 多租户隔离 URL: https://docs.yinlingshuzhi.com/security/tenant-isolation --- title: 多租户隔离 description: 一码通租户身份、成员关系和数据访问的公开安全原则 --- # 多租户隔离 ## 公开原则 - 用户身份、企业租户、成员资格和会话是不同事实； - 授权租户来自服务端签发的会话，不能由前端选择； - 所有业务查询和写入都必须受租户边界约束； - 成员停用、租户冻结和安全事件会触发会话失效； - 管理权限采用最小授权并保留操作审计。本页不公开内部表结构、攻击路径、管理接口和防护规则细节。 --- ## 食品追溯上线教程 URL: https://docs.yinlingshuzhi.com/tutorials/food-traceability --- title: 食品追溯上线教程 description: 食品饮料从生产赋码到消费者扫码的实施路径 --- # 食品追溯上线教程 ## 业务目标让每个测试商品能够核对生产批次、关键流通节点和消费者扫码结果。 ## 完整流程 1. 确认追溯主体、字段来源和审核责任人。 2. 建立商品、SKU、批次和必要检测信息。 3. 创建码包并完成生产赋码核验。 4. 记录出库、运输、到货和签收节点。 5. 配置公开扫码页面，只展示已审核信息。 6. 使用测试码扫码，核对前台展示与后台事件。 ## 验收验收口径应在实施前确认，至少包括数据归属、字段完整性、码状态、关键节点和异常回退。