OnlineCenter 使用说明与接口文档

图书资源与数据中心 — 上传文件、按书代号查看文件、对外统一资源 / 数据接口

本页为只读文档页面，不触达数据库。访问地址：/（站点首页）

上半部分「使用说明」面向使用者，讲怎么上传 / 查看文件；下半部分「接口参考」面向开发对接，讲请求结构、鉴权与返回值。

另可查看图书资源统计：文件资产总览、资源类型统计、资源分布与图书资源列表（只读，无需权限）。

使用说明

这是什么
系统模块总览
一、上传文件
二、查看 / 获取文件
三、条形码与二维码
四、常见问题

接口参考

通用约定（Bearer 鉴权 / 统一响应）
数据接口（api/get-book 已下线，改用 api/catalog/*）
资源接口：api/image / api/barcode / api/qrcode
上传接口：api/resource/upload
受控资源 / 头像（占位）
SSO 接入（授权码 / password 过渡）
账户接口（Web API）
鉴权现状与后续方向

这是什么

OnlineCenter 是图书资源的存放中心。你把一本书的图片（封面、缩略图等）或 PDF 上传进来，系统会用这本书的书代号把文件归档保存；之后任何系统或浏览器，只要知道书代号，就能随时把这张图取回来，还能按需要的尺寸缩放，或生成对应的条形码、二维码。

文件会同时保存在本地服务器和阿里云 OSS 两处，互为备份，因此上传成功后可以稳定地长期取用。

数据存储：生产环境的业务数据（图书、文件资产、用户与登录记录等）直接对接阿里云 RDS SQL Server；文件二进制则由本地磁盘 + 阿里云 OSS 双写承载。数据库连接由部署环境的配置提供，应用不在页面暴露任何连接信息。

系统模块总览

OnlineCenter 由若干相对独立的模块组成，围绕「图书资源」与「统一身份」两条主线。下面按模块说明各自负责什么、对外提供哪些能力。每个模块名后标注了它对应的服务角色（如 resource-service、sso-platform）。

1. 资源服务 resource-service

图书图片 / PDF / 视频的上传与读取出口，是本系统最核心的对外能力。分读、写两侧：

子模块	负责	对外入口
读取 (Open)	按书代号取图片、生成条形码 / 二维码；支持缩放、尺寸预设、fc→th 回退、ETag/304 缓存、可选 IP 白名单	/api/image、/api/barcode、/api/qrcode、/api/image/custom
上传 (Upload)	接收图片 / PDF / 视频等文件上传，经 Bearer 令牌 + scope `resource:write` 鉴权，再过大小 / 扩展名 / 可选 IP 白名单 / 文件头多层校验后，本地原子写入 + OSS 双写，并维护文件资产与作品汇总	/api/resource/upload

文件二进制本地 + 阿里云 OSS 双写；若某次云端同步失败，后台补偿任务自动重试拉齐。详见下方资源接口与上传接口。

2. 数据查询 data

对外提供图书作品 / 版本信息的只读查询，输出稳定 DTO。可按书代号批量取版本，按时间做增量拉取，或按关键词检索。

入口：api/catalog/*；走 Bearer 令牌 + scope catalog:read。原 POST /api/get-book（DES 鉴权）已下线。详见数据接口。

3. 统一身份认证 sso-platform

集中管理登录、账户与第三方绑定，业务系统通过它完成单点登录，不再各自维护账号体系。包含三部分：

子模块	负责	对外入口
统一登录 (Sso)	登录页、账号 / 手机号 + 密码登录、短信验证码登录、登出；成功后跳回业务系统 returnUrl	/Sso/Login、/Sso/LoginBySms、/Sso/Logout
微信登录 (Wechat)	发起微信网页授权并处理回调，用 openid 建立 / 识别统一身份，未绑定引导至登录页绑定	/Wechat/Login、/Wechat/WechatCallback
账户 API (Auth)	注册、微信绑定 / 解绑、资料查看 / 修改、改密、手机号绑定 / 解绑；REST 风格，Bearer 令牌鉴权	api/account/*

业务系统推荐用授权码模式接入（/oauth/authorize + /oauth/token）。详见 SSO 接入与账户接口。

4. 基础能力服务 sms / captcha

供登录 / 注册等流程调用的通用能力：

子模块	负责	对外入口
短信 (Sms)	按用途发送与校验短信验证码，内置频控；人机校验可作前置（受开关控制）	/api/sms/send、/api/sms/verify
人机校验 (Captcha)	对接阿里云行为验证码，仅做人机校验；接入方凭据（ClientId + AccessKey）直传校验，并要求该接入方已被授予 scope `captcha:verify`，另有可选 IP 白名单	/api/captcha/verify

5. 受限 / 辅助出口 limit

头像读取（支持缩放与默认头像兜底）。原受控文档 / Excel / PDF 占位下载入口已下线，对外资源下载统一走带 scope 鉴权的 /api/resource/download。

入口：/Limit/GetAvatar（可用）。详见受控资源 / 头像。

6. 站点入口 home

站点首页，即本页。渲染使用说明与接口文档的只读静态页，不触达数据库。

历史遗留（已停用）：早期基于 ASP.NET Identity 脚手架的 Account / Manage 控制器业务已全部停用，登录迁移至统一登录（Sso），账户管理迁移至账户 API（api/account），对外不再提供可用入口。

一、上传文件

上传一个文件，通常按下面几步：

准备文件。支持的格式：图片 .jpg / .jpeg / .png，文档 .pdf，视频 .mp4。大小上限：图片默认 10 MB，PDF / 视频默认 50 MB（可由管理员在配置中调整）。
确定书代号（BookCode）。这是文件归档的关键，长度 2–8 位，只能是字母和数字。同一本书的不同图片用同一个书代号、不同的"类型"区分。
选择图片类型（Type）。比如封面、缩略图、3D 图等，用短码表示（如 fc 表示封面、th 表示缩略图）。
提交上传。上传成功后，系统会返回一个形如 {书代号}_{类型} 的标识（例如 abc123_fc），表示这张图已经存好了。

POST /api/resource/upload 需要授权

上传接口。提交方式为表单（multipart/form-data），包含文件本身和一段描述信息（书代号、类型等）。

你要提供	说明
文件	要上传的图片 / 文档，格式和大小见上面的限制
书代号	2–8 位字母数字，文件归档依据
类型	封面 fc / 缩略图 th / 3D 图 3d 等

上传需要平台授权（对接方在请求头携带 Bearer 访问令牌，且该接入方须被授予 resource:write），普通浏览器不能直接上传。令牌怎么换、字段怎么填，见下方上传接口。

二、查看 / 获取文件

文件存好之后，知道书代号就能取回。下面这些地址直接在浏览器打开就能看到图片。

GET /api/image

按书代号读取图片，可以指定类型和缩放尺寸。

参数	默认	说明
cd	必填	书代号
tp	fc（封面）	图片类型短码
w	原图宽	想要的宽度（像素）
h	原图高	想要的高度（像素）

例子：

取封面原图：     /api/image?cd=ABC123
取宽 300 的封面： /api/image?cd=ABC123&tp=fc&w=300
取缩略图：       /api/image?cd=ABC123&tp=th

找不到所请求类型时，封面（fc）会自动回退到缩略图（th）；都没有则返回占位图。

GET /api/image/custom 需在白名单内

需要自定义尺寸、又对来源有更严格控制时使用。用法和上面类似，但访问方的 IP 必须在白名单内才放行。

/api/image/custom?cd=ABC123&tp=fc&w=600&h=800

三、条形码与二维码

除了取图，系统还能即时生成条形码和二维码图片。

GET /api/barcode

生成条形码 PNG 图片。

参数	默认	说明
cd	必填	条码内容（比如 ISBN）
w	200	宽度
h	120	高度

/api/barcode?cd=9787000000000&w=240&h=120

GET /api/qrcode

生成二维码 PNG 图片。

参数	默认	说明
cd	必填	二维码内容（文字或网址）
size	180	边长（像素）

/api/qrcode?cd=https://example.com&size=200

四、常见问题

打开图片地址显示的是一张占位图？

说明该书代号 + 类型还没有上传过对应文件，或文件已被删除。请确认书代号、类型是否正确，或先完成上传。

图片太大 / 太小怎么办？

在地址后加 w（宽）和 h（高）参数即可按需缩放，例如 ?cd=ABC123&w=300。只传一个时会按比例缩放。

为什么我打不开 `/api/image/custom`？

这个地址有 IP 白名单保护，只有名单内的来源才能访问。日常查看图片请用 /api/image。

同一张图反复打开会不会很慢？

不会。系统对图片做了缓存（ETag / Last-Modified），浏览器和中间环节会复用，没有变化时直接走缓存。

上传后多久能取到？

上传成功即可取用。文件会先写本地、再同步到云端 OSS；万一某次云端同步没成功，后台补偿任务会自动重试拉齐，不影响读取。

通用约定接口参考

状态图例： 可用已上线可调用占位路由存在但返回空新增本轮新增

鉴权：Bearer 访问令牌

对外写接口与开放平台接口统一走 OAuth2 客户端凭据模式：先用接入方凭据向 POST /oauth/token （grant_type=client_credentials）换取访问令牌，再在业务请求头携带：

Authorization: Bearer <access_token>

令牌无效返回 401（invalid_token）；接入方未被授予该接口所需 scope 返回 403（insufficient_scope）。各接口所需 scope 见下方各接口说明。原基于固定密钥 DES 签名（nm + tkcd）的鉴权已下线。

请求包袱 InterfaceModel<T>

api/resource/upload 的业务请求仍用如下结构包装（字段名为缩写），但其中的身份字段已废弃，仅保留业务字段：

{
  "acnm":   "动作名 actionname",
  "potdta": { /* 业务负载 T，postdata */ }
}

统一响应 GeneralResponse<T>

{
  "success":    true,
  "statusCode": 200,
  "message":    "",
  "errors":     [],
  "data":       /* 业务数据 T，可能是被序列化的 JSON 字符串 */
}

数据接口

POST /api/catalog/books 图书目录接口可用

原 /api/get-book 与 /api/get-book-profile（老 DES 令牌鉴权）已下线。图书数据的只读能力由经开放平台 OAuth 鉴权的图书目录接口承担： /api/catalog/books（检索）、/api/catalog/books/batch（批量）、 /api/catalog/books/changes（增量），所需授权范围 catalog:read。

接入方式：先以 ClientId + AccessKey 走 client_credentials 换取令牌，再在请求头带 Authorization: Bearer <token>。详见「通用约定」与接入指南。

资源接口（公开图片 / 条码）

GET /api/image 路由：api/image 可用

按书代号 + 类型读取图片，支持缩放、fc→th 回退、可选 IP 白名单。

参数	类型	默认	说明
cd	string	必填	书代号，长度 2–8
tp	string	fc	图片类型短码（fc/th/hd/bc/3d/png/pho1..10 等）
ext	string	按类型	扩展名（可选）
h	int	0	缩放高度
w	int	0	缩放宽度

GET /api/image?cd=ABC123&tp=fc&w=300

IP 白名单由 GetImageIpWhitelistEnabled / GetImageIpWhitelist 配置控制，默认关闭。

GET /api/barcode 路由：api/barcode 可用

生成条形码 PNG。

参数	类型	默认	说明
cd	string	必填	条码内容
tp	string	—	条码类型
w	int	200	宽度
h	int	120	高度

GET /api/barcode?cd=9787000000000&w=240&h=120

GET /api/qrcode 路由：api/qrcode 可用

生成二维码 PNG。

参数	类型	默认	说明
cd	string	必填	二维码内容
size	int	180	边长（像素）

GET /api/qrcode?cd=https://example.com&size=200

上传接口

POST /api/resource/upload 路由：api/resource/upload 可用

上传图片 / PDF / 视频（.jpg/.jpeg/.png/.pdf/.mp4）。鉴权走 Bearer 令牌 + scope resource:write，另有可选 IP 白名单；原子替换写盘，落 OpenFiles 记录。

请求格式：multipart/form-data；请求头：Authorization: Bearer <access_token>

表单字段	说明
（文件）	第一个文件项；允许扩展名 .jpg/.jpeg/.png/.pdf/.mp4；上限：图片 10 MB，PDF / 视频 50 MB
data	JSON 字符串，结构为 InterfaceModel<UploadFileModel>

data.potdta（UploadFileModel）关键字段：

字段	说明
Type	图片类型短码（fc/th/3d/pho1.. 等）
BookCode	书代号，长度 2–8
IsbnCode / ScriptCode	ISBN 代码 / 稿件号（可选）
Version	版次，默认 1
Order	印次/序号，默认 1

POST /api/resource/upload  (multipart/form-data)
Authorization: Bearer <access_token>

file: <binary>
data: {
  "acnm": "UploadFile",
  "potdta": { "BookCode": "ABC123", "Type": "fc", "Version": 1, "Order": 1 }
}

acnm 取值：UploadFile（推荐；旧值 CipUploadBookImage / UpImage 仍兼容）。成功时 data = {bookcode}_{type}。

受控资源 / 头像

GET /api/resource/download 可用

对外资源下载统一入口，走开放平台 Client + JWT + scope resource:read 鉴权，本地优先、未命中回源 OSS。原 /Limit/Doc / /Limit/Excel / /Limit/Pdf 占位路由已下线。

GET /Limit/GetAvatar 可用

读取头像，支持缩放与默认头像兜底。

参数	说明
id	头像标识（长度 ≥ 2）
al	别名（长度 ≥ 3）
ext	扩展名 .jpg/.jpeg/.png
h / w	缩放高 / 宽

SSO 接入（授权码 / password 过渡）新增

GET /oauth/authorize 新增

推荐接入方式。业务系统将浏览器重定向到统一登录授权端点；用户已登录时直接颁发一次性授权码，未登录时跳转统一登录页。

参数	说明
response_type	固定为 `code`
client_id	登记在 Clients 表的 ClientId
redirect_uri	必须命中该 Client 的 RedirectUris 白名单
state	接入系统生成并校验，用于防 CSRF

GET /oauth/authorize?response_type=code&client_id=book-web&redirect_uri=https%3A%2F%2Fbook.example.com%2Fsso%2Fcallback&state=<opaque>

POST /oauth/token 新增

授权码换取 JWT。Client 凭据可用 HTTP Basic，也可用表单 client_id / client_secret。

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=<code>&redirect_uri=<callback>&client_id=<client_id>&client_secret=<secret>

授权码一次性、短时有效；重复使用、过期、Client 未登记、secret 错误、回调不匹配均拒绝。

POST /oauth/token 过渡

兼容未改造系统的 password grant。仅作迁移期过渡；新系统必须使用授权码模式。

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=<username-or-phone>&password=<password>&client_id=<client_id>&client_secret=<secret>

该模式会校验 Client 凭据与用户密码，但不能提供浏览器单点免登；灰度完成后下线。

账户接口（Web API）

POST /api/account/register 可用

用户注册（依赖短信校验）。请求体为 RegisterViewModel。

POST /api/account/bind-wechat 可用

绑定微信。参数 wechatCode。

注：Web API 路由本轮已在 Global.asax 注册（此前未注册，相关接口曾 404）。

鉴权现状与后续方向

现状：对外接口鉴权已统一收敛到 OAuth2 客户端凭据模式（Bearer 令牌 + scope 授权），由接入方管理表（Clients）统一维护身份与授权范围。原基于固定密钥的 DES 签名鉴权（nm + tkcd）连同其依赖的接口已全部下线。

现有 scope：catalog:read（图书目录只读）、resource:read（资源清单 / 下载）、 resource:write（资源上传）、sms:send（短信下发 / 校验）、 captcha:verify（行为验证码校验）。

后续方向：设计文档 §14 另有一套 HMAC-SHA256 请求签名方案（X-Client-Id / X-Timestamp / X-Nonce / X-Signature，含时间窗与防重放），算法组件 SignatureService 已实现并通过单测但尚未接入任何端点。它定位为面向高安全要求场景的补充手段（防重放、请求完整性），而非替代当前的 Bearer 令牌鉴权；是否启用待评审。