API 接口说明 — CodeNote Server

本文档为 CodeNote Server 端 REST API 的权威参考，涵盖所有后端接口。
数据模型说明见 /architecture/data-model.md，用户状态管理见 /designs/auth/user-state.md。

1. 概述

CodeNote Server 提供约 140 个 REST API 接口，管理 28 张 MySQL 数据表。

项目	详情
框架	Spring Boot 3.2.5 + Kotlin 1.9.23
认证	JWT (io.jsonwebtoken) + Spring Security
数据库	MySQL 8.0 + JPA (Hibernate) + Flyway 迁移
存储	阿里云 OSS

角色体系

角色	说明
GUEST（未登录）	仅可访问公开分享页，无需 JWT
USER（普通用户）	默认角色，可使用所有个人业务功能
ADMIN（系统管理员）	可访问管理后台 API，全局数据查看和管理权限

认证方式

JWT Token：Authorization: Bearer {token}，有效期 7 天
设备标识：X-Device-Id: {deviceId}（设备身份/会话标识；已登录请求校验与活跃会话匹配，无匿名认证）

2. 核心基础模块

M1 - 用户认证（AuthController）

端点	方法	说明
`/api/auth/register`	POST	用户注册
`/api/auth/login`	POST	用户登录
`/api/auth/device-login`	POST	设备登录（查 DEVICE identity，无则自动建用户+登记，返回 LoginResponse）
`/api/users/me/username`	PUT	设置用户名（独立入口，仅未设置时可用）
`/api/auth/password/set`	POST	设置密码（独立入口，仅未设置时可用）
`/api/auth/password/forgot-code`	POST	忘记密码发验证码 { credential }（含@→邮箱，11位数字→手机）
`/api/auth/password/reset`	POST	忘记密码重置
`/api/auth/password/change-code`	POST	修改密码发验证码 { channel: PHONE\|EMAIL }（发到当前用户已绑定凭证）
`/api/auth/password/change`	POST	修改密码
`/api/auth/email/unbind`	POST	解绑邮箱（无请求体）
`/api/auth/phone/unbind`	POST	解绑手机（无请求体）

| /api/auth/userinfo | GET | 获取个人信息 | | /api/auth/userinfo | PUT | 修改个人信息 | | /api/users/me/current-org | PUT | 设置当前活跃组织 | | /api/auth/refresh | POST | 刷新 Token | | /api/auth/logout | POST | 登出 | | /api/auth/sessions | POST | 创建会话 | | /api/auth/sessions | GET | 获取所有有效会话 | | /api/auth/sessions/{sessionId} | GET | 获取会话详情 | | /api/auth/sessions/{sessionId}/switch | POST | 切换到指定会话 | | /api/auth/sessions/{sessionId} | DELETE | 注销会话 | | /api/auth/accounts | GET | 获取关联账号列表 | | /api/auth/accounts/{targetUserId}/switch | POST | 切换到关联账号（已废弃，使用 link/switch）| | /api/auth/link | POST | 添加关联账号（verifyType: PASSWORD=linkedUserId+password / PHONE_CODE / EMAIL_CODE=credential+code）| | /api/auth/sms/link-code | POST | 发送关联账号短信验证码（目标账号手机号，需登录）| | /api/auth/email/link-code | POST | 发送关联账号邮箱验证码（目标账号邮箱，需登录）| | /api/auth/link/list | GET | 获取关联账号列表 | | /api/auth/link/{linkId}/switch | POST | 切换关联账号（推荐）| | /api/auth/link/{linkId} | DELETE | 移除关联账号 | | /api/auth/quotas | GET | 获取配额配置 | | /api/auth/devices | GET | 当前账号绑定设备列表 | | /api/auth/devices/{deviceId} | DELETE | 移除设备身份（设备丢失处置） | | /api/auth/sms/send-code | POST | 发送登录短信验证码（PNVS） | | /api/auth/sms/bind-code | POST | 发送绑定手机号验证码（需登录）| | /api/auth/phone-login | POST | 手机号+验证码登录（自动注册）| | /api/auth/phone-password-login | POST | 手机号+密码登录 | | /api/auth/phone-bind | POST | 绑定手机号（需登录+验证码）| | /api/auth/sms/oneclick-login | POST | 一键登录（Android SDK token 取号） | | /api/auth/sms/verify-mobile | POST | 本机号码校验绑定（需登录+SDK token）|

管理后台登录：

端点	方法	说明
`/api/admin/auth/login`	POST	管理员登录

会话管理特性：

(user_id, device_id) 唯一索引，同用户同设备仅保留一条有效会话
Token 携带 sessionId，用于验证会话有效性
活跃会话上限：10 个

设备身份特性（设备不再特殊，DEVICE 与 PHONE/EMAIL 平级）：

基于设备 ID 自动生成用户，无需手动注册
用户可随时绑定用户名密码，实现跨设备登录
凭据登录自动登记当前设备为账号的 DEVICE identity（一账号多设备）

M2 - 二维码 CRUD（QrCodeController）

职责：管理用户手动创建的二维码。业务二维码（资源/活动/签到/通行）由各业务模块独立管理，不写入 qr_codes 表。

端点	方法	说明
`/api/qr-codes`	GET	列表（分页+搜索+筛选）
`/api/qr-codes`	POST	创建
`/api/qr-codes/{id}`	GET	详情
`/api/qr-codes/{id}`	PUT	更新
`/api/qr-codes/{id}`	DELETE	软删除
`/api/qr-codes/batch`	POST	批量创建
`/api/qr-codes/batch/export`	POST	批量导出
`/api/qr-codes/{id}/pin`	PATCH	置顶/取消
`/api/qr-codes/{id}/public`	PATCH	公开/私有
`/api/qr-codes/trash`	GET	回收站列表
`/api/qr-codes/trash/restore/{id}`	PATCH	恢复
`/api/qr-codes/trash`	DELETE	清空回收站
`/api/qr-codes/stats`	GET	统计数据
`/api/qr-codes/public/{uuid}`	GET	公开分享页
`/api/qrcode/render`	GET	公开二维码渲染（无需登录，支持 content 参数指定内容，size 指定尺寸）

M3 - 分类管理（CategoryController）

端点	方法	说明
`/api/categories`	GET	列表
`/api/categories/{id}`	GET	获取分类详情
`/api/categories`	POST	创建 `{ name, color, parentId }`
`/api/categories/{id}`	PUT	更新 `{ name, color }`
`/api/categories/{id}`	DELETE	删除
`/api/categories/reorder`	PATCH	批量重排序
`/api/categories/{id}/parent`	PATCH	更新父分类
`/api/categories/{id}/deletable`	GET	检查可删除性
`/api/categories/tree`	GET	获取分类树
`/api/categories/{id}/pin`	PATCH	置顶/取消
`/api/categories/batch-pin`	PATCH	批量置顶

M4 - 扫码记录（ScanRecordController）

端点	方法	说明
`/api/scan-records`	GET	列表（分页）
`/api/scan-records`	POST	创建
`/api/scan-records/{id}`	PATCH	更新（收藏等）
`/api/scan-records/{id}`	DELETE	删除
`/api/scan-records/stats`	GET	统计数据

M5 - 登录记录（LoginRecordController）

端点	方法	说明
`/api/login-records`	POST	记录登录事件
`/api/login-records/user/{userId}`	GET	查询用户登录记录（分页）
`/api/login-records/recent?hours=24`	GET	查询近期登录记录
`/api/login-records/user/{userId}/recent?hours=24`	GET	查询用户近期登录记录
`/api/login-records/failed`	GET	查询失败登录记录

M5b - 文件上传（FileController）

端点	方法	说明
`/api/files/sts-token`	POST	获取 STS 临时凭证（15 分钟有效）
`/api/files/upload`	POST	Multipart 文件上传（保底兜底方案）
`/api/files/signed-url`	GET	获取私有资源签名 URL（用于直接访问）
`/api/files/{id}`	GET	获取文件元信息
`/api/files/{id}`	DELETE	删除文件
`/api/files/callback`	POST	OSS 回调处理（由 OSS 触发）

上传流程：客户端获取 STS 凭证 → 直传 OSS → 回调服务端记录元数据。

M6 - 通知中心（NotificationController）

端点	方法	说明
`/api/notifications`	GET	通知列表（分页，返回 `bodyPlain` 纯文本摘要）
`/api/notifications/{id}`	GET	通知详情（归属校验，返回 `bodyHtml` 供 MarkdownView 渲染）
`/api/notifications/{id}/read`	PATCH	标记已读
`/api/notifications/read-all`	PATCH	全部已读
`/api/notifications/unread-count`	GET	未读数量
`/api/notifications/total-count`	GET	通知总数（含已读）
`/api/notifications/{id}`	DELETE	删除通知

通知正文支持 Markdown：body 存 Markdown 原文，列表返回 bodyPlain（纯文本摘要），详情返回 bodyHtml（后端统一渲染，安全清洗）；系统通知（ORG_INVITE/ORG_APPROVED/ORG_REJECTED/ORG_APPROVAL_REQUEST/ACCOUNT_LINK）为纯文本 body，渲染后即段落，生成方零改动。

M7 - 云同步（SyncController）

端点	方法	说明
`/api/sync/pull?since={timestamp}`	GET	增量拉取（首次传 0，单位：毫秒）
`/api/sync/push`	POST	离线记录补传
`/api/sync/conflicts`	GET	冲突记录列表
`/api/sync/resolve`	POST	解决冲突

同步策略：首次全量 → 增量拉取 → 离线补传 → LWW 冲突仲裁 → 指数退避重试。

冲突解决机制（/api/sync/resolve）：

acceptServer=true：接受服务端版本，更新映射版本号，客户端下次拉取时获取服务端数据
acceptServer=false：拒绝服务端版本，重置映射版本号为0，客户端重新推送本地数据覆盖服务端

M8 - 协议公开接口（AgreementController）

端点	方法	说明
`/api/agreement/current?type=SERVICE`	GET	当前生效协议（公开，无需登录；type: SERVICE/PRIVACY；返回 `content` 原文 + `contentHtml` 渲染）

响应示例（version 为当前生效版本号）：

json

{
  "code": 200,
  "data": {
    "type": "SERVICE",
    "version": 3,
    "title": "CodeNote 用户服务协议",
    "content": "# 服务协议\n\n## 一、服务说明\n- xxx",
    "contentHtml": "<h1>服务协议</h1><h2>一、服务说明</h2><ul><li>xxx</li></ul>"
  }
}

版本化策略：只增不改、发布即生效（version 自动 +1）、历史版本可回滚激活；后台接口见 A23。表结构与权限点见 /architecture/data-model.md「agreements 用户协议/隐私政策表」。

3. 组织模块

B1 - 组织管理（OrgController）

端点	方法	说明
`/api/orgs`	POST	创建组织（body 含 visibility：PUBLIC/INTERNAL；INTERNAL 强制 joinPolicy=INVITE）
`/api/orgs`	GET	我的组织列表
`/api/orgs/{id}`	GET	组织详情（PUBLIC 组织放行非成员只读，permissions/roleName 为空；INTERNAL 非成员 403）
`/api/orgs/{id}`	PUT	更新设置（可改 visibility；INTERNAL 时 joinPolicy 锁定 INVITE）
`/api/orgs/{id}/apply`	POST	申请加入公开组织（FREE 直接加入 / APPROVAL 提交申请 / INVITE·INTERNAL 拒绝 403）
`/api/orgs/{id}`	DELETE	解散（仅 OWNER）
`/api/orgs/{id}/transfer-ownership`	POST	转移所有权（管理后台专用）
`/api/orgs/{id}/transfer`	POST	转移所有权（Android 端，转让给成员）
`/api/orgs/{id}/qrcode`	GET	组织二维码
`/api/orgs/{id}/switch`	PATCH	切换当前组织
`/api/orgs/join-by-code`	POST	组织码加入
`/api/orgs/join-by-qrcode`	POST	扫码加入
`/api/orgs/{id}/leave`	POST	退出组织
`/api/orgs/{id}/stats`	GET	组织统计面板
`/api/orgs/{orgId}/members`	GET	成员列表
`/api/orgs/{orgId}/members/{userId}`	PUT	改角色/昵称
`/api/orgs/{orgId}/members/{userId}`	DELETE	移除成员
`/api/orgs/{id}/invite`	POST	邀请成员（批量，发通知）
`/api/orgs/{id}/invitations`	GET	组织侧邀请记录列表（OWNER/ADMIN）
`/api/orgs/{id}/invitations/{invitationId}/cancel`	POST	撤回邀请（OWNER/ADMIN，仅 PENDING）
`/api/orgs/users/search?q=`	GET	搜索用户（用户名/邮箱）
`/api/orgs/public/{code}`	GET	获取组织公开信息（无需登录）
`/api/orgs/invitation/{invitationId}`	GET	获取邀请详情
`/api/orgs/invitation/respond`	POST	回应邀请（接受/拒绝）
`/api/orgs/my-invitations`	GET	获取待处理邀请列表
`/api/orgs/{id}/pending`	GET	获取待审批成员（ADMIN/OWNER）
`/api/orgs/{id}/approve`	POST	审批成员（通过/拒绝）
`/api/orgs/{orgId}/locations`	GET	获取组织位置列表
`/api/orgs/{orgId}/locations`	POST	创建位置
`/api/orgs/{orgId}/locations/{locationId}`	PUT	编辑位置
`/api/orgs/{orgId}/locations/{locationId}`	DELETE	删除位置
`/api/orgs/{orgId}/locations/{locationId}/pin`	PATCH	置顶/取消置顶位置
`/api/orgs/{orgId}/locations/pin`	PATCH	批量置顶位置
`/api/orgs/{orgId}/locations/reorder`	PATCH	批量排序位置
`/api/orgs/{id}/shares`	POST	共享资源
`/api/orgs/{id}/shares`	GET	共享列表
`/api/orgs/{id}/shares/{shareId}`	DELETE	取消共享

组织角色：OWNER（所有者）→ ADMIN（管理员）→ MEMBER（成员）。

4. 业务模块

B4 - 固定资源管理（AssetController）

端点	方法	说明
`/api/assets`	GET	列表（分页+筛选）
`/api/assets`	POST	登记
`/api/assets/{id}`	GET	详情
`/api/assets/{id}`	PUT	更新
`/api/assets/{id}`	DELETE	删除
`/api/assets/import`	POST	Excel 导入
`/api/assets/export`	GET	Excel 导出
`/api/assets/{id}/transfer`	POST	资源流转
`/api/assets/{id}/transfers`	GET	流转记录
`/api/assets/inventories`	POST	创建盘点
`/api/assets/inventories`	GET	盘点列表
`/api/assets/inventories/{id}`	PUT	更新盘点
`/api/assets/inventories/{id}/scan`	POST	扫码盘点
`/api/assets/map`	GET	资源地图
`/api/assets/{id}/scrap`	POST	资源报废

资源分类：

端点	方法	说明
`/api/assets/categories?scope=PERSONAL&orgId=`	GET	资源分类树
`/api/assets/categories`	POST	创建分类
`/api/assets/categories/{id}`	PUT	更新分类
`/api/assets/categories/{id}`	DELETE	删除分类
`/api/assets/categories/reorder`	PATCH	批量重排序
`/api/assets/categories/{id}/parent`	PATCH	更新父分类
`/api/assets/categories/{id}/deletable`	GET	检查可删除性
`/api/assets/categories/{id}/pin`	PATCH	置顶/取消
`/api/assets/categories/batch-pin`	PATCH	批量置顶

通用动态数据模型（meta_*，起替代旧字段自定义系统；P2 三控制器已上线）：

端点	方法	说明
`/api/meta/objects`	GET	可见业务对象列表
`/api/meta/objects/{objectName}/fields`	GET	可见字段（GLOBAL ∪ ORG ∪ USER 合并；?entityId=&orgId=）
`/api/meta/objects/{objectName}/fields`	POST	新建字段（USER 级）
`/api/meta/objects/{objectName}/fields/{id}`	PUT/DELETE	更新/软删字段
`/api/meta/objects/{objectName}/templates`	GET/POST	可见模板列表（?categoryScope= 过滤）/新建模板
`/api/meta/templates/{id}`	PUT/DELETE	更新/软删模板
`/api/meta/templates/{id}/fork`	POST	个人 fork（scope=USER）
`/api/meta/templates/{id}/fields`	GET/PUT	模板字段明细查询/批量全量替换
`/api/meta/objects/{objectName}/entities/{entityId}/templates`	GET/POST	实体模板绑定列表/绑定（空 templateIds→自动绑默认模板）
`/api/meta/objects/{objectName}/entities/{entityId}/templates/{templateId}`	DELETE	解绑模板
`/api/meta/objects/{objectName}/entities/{entityId}/values`	GET/PUT	可见字段+值 / 批量写值（服务端按 config 校验）
`/api/meta/objects/{objectName}/values`	GET	按类型筛选（?fieldId=&min=&max=&orgId=）

组织级（OrgMetaController，/api/orgs/{orgId}/meta/...）：fields/templates CRUD + POST /api/orgs/{orgId}/meta/templates/{id}/fork（fork 全局模板为本组织模板，深复制字段）+ entities/{entityId}/templates 绑定管理。写操作校验 ORG 域 meta_* 权限点（OWNER/ADMIN 有，MEMBER 无）。

Admin 级（AdminMetaController，/api/admin/meta/...）：objects 注册/启停（仅 SYSTEM_ADMIN）、fields/templates 全量管理（跨 scope，可指定 orgId）、orgs/{orgId}/templates 查看任意组织模板；GET /api/admin/assets/{id}/fields 保留（admin 视角字段详情，meta 数据源）。

说明：/api/assets/field-definitions、/api/assets/categories/{id}/field-bindings、/api/assets/{id}/fields 旧端点已移除；分类创建请求体改为 templateIds: List<Long>（不再接收 templateFields）；值读写前校验实体归属（个人/组织）。

B6 - 活动管理（ActivityController）

端点	方法	说明
`/api/activities`	POST	创建活动（含签到/通行配置）
`/api/activities`	GET	活动列表
`/api/activities/{id}`	GET	详情（含配置+统计）
`/api/activities/{id}`	PUT	更新
`/api/activities/{id}`	DELETE	删除
`/api/activities/{id}/status`	PATCH	变更状态
`/api/activities/{id}/qr-code`	GET	获取活动二维码列表
`/api/activities/{id}/invite-code`	PATCH	重置邀请码（仅 INVITE_ONLY，旧码作废，qr_content 联动）
`/api/discover/activities`	GET	发现页公开活动（PUBLIC+ACTIVE，分页，含 ownerName）
`/api/discover/orgs`	GET	发现页公开组织（PUBLIC+ACTIVE，分页，含 memberCount）

状态流转：DRAFT → ACTIVE → ENDED / CANCELLED。
容器模式：活动是签到和通行证的容器，通过 has_check_in / has_pass 开关子功能。
活动字段（新增 region）：region（所在地区，省市区）+ location（详细地址+门牌号）；Create/UpdateActivityRequest 均支持 region（可选）。
可见性（§可见性架构）：owner_type（PERSONAL/ORGANIZATION）+ owner_id 归属容器；visibility 三态——PUBLIC（发现页展示）/ RESTRICTED（restricted_scope_type/id 指向容器成员，个人活动禁选）/ INVITE_ONLY（invite_code 凭证，默认）；二维码内容：INVITE_ONLY → activity:{id}:{code}，其余 → activity:{id}；详情/签到/通行证/落地页统一走 ActivityVisibility 校验（非 PUBLIC 不泄露 H5 内容）。

B7 - 签到系统（CheckInController）

端点	方法	说明
`/api/activities/{id}/check-in`	POST	签到（扫活动码或签到码）
`/api/activities/{id}/check-in/records`	GET	签到记录列表
`/api/activities/{id}/check-in/stats`	GET	签到统计

特性：GPS 校验（可选）、次数限制、离线签到、手动签到码。

B8 - 通行证系统（PassController）

端点	方法	说明
`/api/activities/{id}/pass/issue`	POST	签发通行证
`/api/activities/{id}/pass/verify`	POST	核验通行证（无需登录，扫码即核验）
`/api/activities/{id}/pass/passes`	GET	已签发通行证列表
`/api/activities/{id}/pass/records`	GET	通行使用记录
`/api/passes/{passId}/revoke`	PUT	撤销通行证
`/api/passes/{passId}/records`	GET	通行证使用记录
`/api/pass/templates`	GET	通行证模板列表
`/api/pass/templates`	POST	创建通行证模板
`/api/pass/templates/{templateId}`	PUT	更新通行证模板
`/api/pass/templates/{templateId}`	DELETE	删除通行证模板
`/api/pass/templates/{templateId}/issue`	POST	通过模板签发通行证

B9 - 水印相册（AlbumController）

端点	方法	说明
`/api/album`	GET	相册列表
`/api/album`	POST	上传照片
`/api/album/{id}`	GET	照片详情
`/api/album/{id}`	DELETE	删除照片
`/api/album/qr-code/{qrCodeId}`	GET	按二维码筛选照片

业务二维码渲染 & 落地页（PublicQrCodeController）

端点	方法	说明
`/api/qrcode/render?content=activity:123&size=300`	GET	即时渲染二维码图片（PNG）
`/s/{type}/{id}`	GET	业务二维码 H5 落地页

支持的落地页类型：/s/activity/{id}、/s/check-in/{id}、/s/pass/{code}、/s/asset/{code}。

5. 管理后台模块

所有管理后台接口前缀：/api/admin/。需要 ADMIN 角色（@PreAuthorize("hasRole('ADMIN')")）。

A1 - 仪表盘

端点	方法	说明
`/api/admin/statistics`	GET	全局统计数据

A2 - 用户管理

端点	方法	说明
`/api/admin/users`	GET	用户列表
`/api/admin/users/{userId}`	GET	用户详情
`/api/admin/users`	POST	创建用户
`/api/admin/users/{userId}`	PUT	更新用户
`/api/admin/users/{userId}/role`	PATCH	更新角色
`/api/admin/users/{userId}/status`	PATCH	更新状态
`/api/admin/users/{userId}/memberships`	GET	获取用户组织成员关系
`/api/admin/users/{userId}/orgs/{orgId}`	POST	将用户加入组织
`/api/admin/users/{userId}/orgs/{orgId}`	DELETE	从组织移除用户

A3 - 组织管理

端点	方法	说明
`/api/admin/orgs`	GET	组织列表
`/api/admin/orgs/{orgId}`	GET	组织详情
`/api/admin/orgs`	POST	创建组织
`/api/admin/orgs/{orgId}`	PUT	更新组织
`/api/admin/orgs/{orgId}`	DELETE	解散组织
`/api/admin/orgs/{orgId}/transfer-ownership`	POST	转移所有权
`/api/admin/orgs/{orgId}/members`	GET	组织成员列表
`/api/admin/orgs/{orgId}/members`	POST	添加组织成员
`/api/admin/orgs/{orgId}/members/{userId}/role`	PUT	修改成员角色
`/api/admin/orgs/{orgId}/members/{userId}`	DELETE	移除组织成员

A5 - 二维码审计

端点	方法	说明
`/api/admin/qr-codes`	GET	二维码列表
`/api/admin/qr-codes/{qrCodeId}`	DELETE	强制删除

A6 - 资源管理

端点	方法	说明
`/api/admin/assets`	GET	资源列表
`/api/admin/assets/{id}/fields`	GET	获取资源动态字段值
`/api/admin/assets/{id}/scrap`	PUT	直接报废（将资源状态设为 SCRAPPED）
`/api/admin/assets/{id}`	DELETE	强制删除

A8 - 活动管理

端点	方法	说明
`/api/admin/activities`	GET	活动列表
`/api/admin/activities`	POST	创建活动
`/api/admin/activities/{activityId}`	GET	活动详情
`/api/admin/activities/{activityId}`	PUT	更新活动
`/api/admin/activities/{activityId}`	DELETE	删除活动

A9 - 签到管理

端点	方法	说明
`/api/admin/check-in`	GET	签到记录列表
`/api/admin/check-in/{recordId}`	DELETE	删除签到记录

A10 - 通行证管理

端点	方法	说明
`/api/admin/passes`	GET	通行证列表
`/api/admin/passes/{passId}/revoke`	PUT	撤销通行证
`/api/admin/passes/{passId}`	DELETE	删除通行证

A11 - 水印相册管理

端点	方法	说明
`/api/admin/albums`	GET	照片列表
`/api/admin/albums/{photoId}`	DELETE	删除照片

A12 - 分类管理

端点	方法	说明
`/api/admin/categories`	GET	分类列表
`/api/admin/categories/{categoryId}`	DELETE	删除分类

A13 - 资源分类管理

端点	方法	说明
`/api/admin/asset-categories`	GET	全局资源分类列表
`/api/admin/asset-categories/{id}`	DELETE	强制删除资源分类

A14 - 通知管理

端点	方法	说明
`/api/admin/notifications`	GET	通知列表
`/api/admin/notifications/{notificationId}`	DELETE	删除通知
`/api/admin/notifications`	POST	发送系统通知

A15 - 分享记录管理

端点	方法	说明
`/api/admin/shares`	GET	分享记录列表
`/api/admin/shares/{shareId}`	DELETE	删除分享

A16 - 系统配置

端点	方法	说明
`/api/admin/settings`	GET	获取系统配置
`/api/admin/settings`	PUT	更新系统配置

A17 - 操作日志

端点	方法	说明
`/api/admin/logs`	GET	操作日志列表（按操作类型/时间筛选）

A18 - 文件管理

端点	方法	说明
`/api/admin/files`	GET	文件列表（按类型/实体/用户筛选）
`/api/admin/files/{fileId}`	DELETE	删除单个文件
`/api/admin/files/batch-delete`	POST	批量删除
`/api/admin/files/stats`	GET	文件存储统计
`/api/admin/files/orphaned`	GET	检测孤儿文件
`/api/admin/files/cleanup-orphaned`	POST	清理孤儿文件记录

A19 - 登录记录管理

端点	方法	说明
`/api/admin/login-records`	GET	登录记录查询
`/api/login-records/user/{userId}`	GET	查询指定用户登录记录
`/api/login-records/recent?hours=24`	GET	查询近期登录记录
`/api/login-records/failed`	GET	查询失败登录记录

A20 - 会话管理

端点	方法	说明
`/api/admin/auth/sessions?userId=`	GET	查询用户会话列表
`/api/admin/auth/sessions/{sessionId}`	DELETE	强制注销会话
`/api/admin/auth/link/list?userId=`	GET	查询用户关联账号列表
`/api/admin/auth/link`	POST	添加关联账号
`/api/admin/auth/link/{linkId}`	DELETE	移除关联账号

A21 - 元数据管理（meta_*，替代原字段定义管理）

原 /api/admin/field-definitions 4 端点已移除；管理端元数据管理由 AdminMetaController（/api/admin/meta）提供（P2 已上线）。

端点	方法	权限点	说明
`/api/admin/meta/objects`	GET/POST	meta_object:read/create	对象列表（含停用）/注册业务对象（仅 SYSTEM_ADMIN）
`/api/admin/meta/objects/{objectName}/status`	PATCH	meta_object:update	启停业务对象（仅 SYSTEM_ADMIN）
`/api/admin/meta/fields?objectName=&scope=&orgId=`	GET	meta_field:read	全量字段（跨 scope）
`/api/admin/meta/fields`	POST	meta_field:create	建字段（scope 任意，可指定 orgId/entityColumn）
`/api/admin/meta/fields/{id}`	PUT/DELETE	meta_field:update/delete	更新/软删字段
`/api/admin/meta/templates?objectName=&scope=`	GET	meta_template:read	模板列表
`/api/admin/meta/templates`	POST	meta_template:create	新建模板（GLOBAL 或指定组织 ORG）
`/api/admin/meta/templates/{id}`	PUT	meta_template:update	更新模板（改名/默认标记/配置）
`/api/admin/meta/templates/{id}/fields`	GET/PUT	meta_template:read/update	模板字段明细查询/批量替换
`/api/admin/meta/templates/{id}`	DELETE	meta_template:delete	软删模板
`/api/admin/meta/orgs/{orgId}/templates`	GET	meta_template:read	查看任意组织的 ORG 模板
`/api/admin/assets/{id}/fields`	GET	asset:read	admin 资产详情字段（meta 视角，保留）

A22 - 扫码记录

端点	方法	说明
`/api/admin/scan-records`	GET	全局扫码记录查询

A23 - 协议管理（AdminAgreementController）与 Markdown 渲染

端点	方法	权限点	说明
`/api/admin/agreements?type=SERVICE`	GET	agreement:read	协议版本列表（新版在前）
`/api/admin/agreements`	POST	agreement:create	发布新版本（版本号自动 +1，发布即生效）
`/api/admin/agreements/{id}/activate`	POST	agreement:activate	切换生效版本
`/api/admin/common/render-markdown`	POST	content:render	Markdown 渲染预览（每用户每分钟 60 次限流）

6. 安全架构

公开路径（permitAll，无需认证）

路径	说明
`/api/auth/register`	用户注册
`/api/auth/login`	用户登录
`/api/admin/auth/login`	管理员登录
`/api/admin/auth/refresh`	管理员 Token 刷新
`/api/auth/refresh`	Token 刷新
`/api/auth/device-login`	设备登录（自动注册）
`/api/qr-codes/public/**`	公开二维码访问
`/api/qrcode/render/**`	公开二维码渲染
`/api/orgs/public/**`	公开组织信息
`/public/**`	静态公共资源
`/s/**`	公开分享落地页
`/ws/**`	WebSocket 握手
`/actuator/health`	健康检查
~~`/actuator/**`~~	（修正：仅 health 端点公开，其他 actuator 端点需 ADMIN 权限）

权限校验

所有其他路径 → 必须认证（anyRequest().authenticated()）
管理员接口 → @PreAuthorize("hasRole('ADMIN')") 类级注解
组织权限 → 业务逻辑校验（查询 org_members 表）

设备用户认证

bash

# 设备用户访问业务接口（JwtAuthFilter 自动注入 DeviceIdAuthentication）
curl http://localhost:8080/api/qr-codes -H "X-Device-Id: device_abc123"
# 响应：200 OK

# 无认证访问 → 401
curl http://localhost:8080/api/qr-codes
# 响应：401 Unauthorized

# 普通用户访问管理员接口 → 403
curl http://localhost:8080/api/admin/users -H "Authorization: Bearer <普通用户token>"
# 响应：403 Forbidden

附录：认证端点补充契约

改造端点

端点	变更
POST /api/auth/password/set	新增：设置密码（仅未设置时可用，不强制登出）
PUT /api/users/me/username	新增：设置用户名（仅未设置时可用，用户名不可修改）
POST /api/auth/email-bind、phone-bind、sms/verify-mobile	补唯一性检查（排除自身，换绑=覆盖旧值）；成功后 verified=true + recalculateIdentity
PUT /api/users/userinfo	不再接受 username 变更；新增 signature 支持（≤100 字符，null 不改）；新增 nickname 支持（≤50 字符，null 不改，空串清空）
POST /api/auth/sms/send-code、sms/bind-code、email/send-code、email/bind-code	发送前凭证归一化（normalizePhone/normalizeEmail）

响应变更

登录/用户信息类响应统一补 nickname；UserInfoResponse 包含 phone/identities/hasPassword/hasRecoverableCredential
device-login 返回统一 LoginResponse（含 hasRecoverableCredential/isNewUser）
新增 admin 端点：/api/admin/nickname/adjectives|nouns CRUD ×8（仅 ADMIN）

附录：密码/解绑端点完整契约

忘记密码（公开，无需登录）

POST /api/auth/password/forgot-code
Request: { credential: string }   # 含@→邮箱，11位数字→手机；凭证须已注册，未注册返回「该账号未注册」
响应：成功 code=200；限频 60s 重发 / 日上限（邮箱 5、短信 10/号、IP 20/日）

POST /api/auth/password/reset
Request: { credential, code, newPassword }   # newPassword ≥6 位
成功后：password 更新 + tokenVersion+1（全部旧 token 失效）

修改密码（登录态）

POST /api/auth/password/change-code
Request: { channel: "PHONE" | "EMAIL" }   # 发码到当前用户已绑定凭证（防向任意号码/邮箱轰炸）；未绑定对应凭证 → 400

POST /api/auth/password/change
Request: { verifyType: "OLD_PASSWORD"|"PHONE_CODE"|"EMAIL_CODE",
           oldPassword?, code?, newPassword }
校验：OLD_PASSWORD 需原密码匹配（password=null 时拒绝「尚未设置密码，请先设置用户名和密码」）；
      PHONE/EMAIL_CODE 需 phone_verified/email_verified
成功后：password 更新 + tokenVersion+1（全部旧 token 失效，客户端需重新登录）

解绑（登录态）

POST /api/auth/email/unbind   # 无请求体 → 删除 EMAIL identity；仅剩 DEVICE 且无密码时响应提示绑定
POST /api/auth/phone/unbind   # 无请求体 → 删除 PHONE identity；同上

set-username / set-password 契约（重构版）

PUT /api/users/me/username（登录态，设置用户名，独立入口）
Request: { username }
校验顺序：
  1. username 非空
  2. 当前 username 非空 → 400「用户名已设置，不可修改」
  3. existsByUsername 拒绝「该用户名已注册，请直接登录」
成功后：username 赋值（密码不动）

POST /api/auth/password/set（登录态，设置密码，独立入口）
Request: { password }
校验顺序：
  1. 当前 password 非空 → 400「已设置密码，请使用修改密码」（已设置走 /password/change）
  2. 密码 ≥6 位
成功后：password 加密赋值；不强制登出（与 change-password 的 tokenVersion+1 区分）

绑定端点补强（最终版）

email-bind / phone-bind / verify-mobile：绑定前唯一性检查（排除自身，换绑=覆盖旧值）；成功后 verified=true + recalculateIdentity
发送侧（sms/send-code、sms/bind-code、email/send-code、email/bind-code）：凭证先归一化（normalizePhone/normalizeEmail）
register：密码 ≥6 位校验（补）

RBAC 权限接口（新增）

方法	路径	权限	说明
GET	`/api/rbac/my-permissions`	登录即可	当前用户权限点集合（APP + PLATFORM + 当前组织 ORG）
GET	`/api/rbac/permissions?domain=`	PLATFORM rbac_permission:read	权限点列表（可按域过滤）
POST	`/api/rbac/permissions`	PLATFORM rbac_permission:create	新增权限点（domain/resource/action 唯一）
PUT	`/api/rbac/permissions/{id}`	PLATFORM rbac_permission:update	编辑权限点（启停/描述；无物理删除）
GET	`/api/rbac/roles?domain=&scopeId=`	PLATFORM rbac_role:read	角色列表（PLATFORM/APP 域）
POST	`/api/rbac/roles?domain=`	PLATFORM rbac_role:create	创建角色 + 权限搭配
PUT	`/api/rbac/roles/{id}`	PLATFORM rbac_role:update	更新角色名称/权限（全量替换）
DELETE	`/api/rbac/roles/{id}`	PLATFORM rbac_role:delete	删除角色（系统角色不可删）
GET	`/api/rbac/users/{userId}/roles`	PLATFORM rbac_user_role:read	用户已授权角色
POST	`/api/rbac/users/{userId}/roles`	PLATFORM rbac_user_role:grant	授予用户角色（初始 admin 保护）
DELETE	`/api/rbac/users/{userId}/roles/{roleId}`	PLATFORM rbac_user_role:revoke	撤销用户角色

响应模型变更（§6.6，不再返回 role 编码）：

OrgResponse：role → permissions: List<String> + roleName: String?
OrgMemberDto（/api/orgs/{orgId}/members）：role → roleName + isOwner
OrgMemberSummary（后台组织详情）：orgRole → roleName
LoginResponse / UserInfoResponse：新增 permissions；UserInfoResponse 删 role 加 roleName
switchOrg 响应：role 键 → permissions + roleName
OrgShareDto：entityId → sourceId + copyId；分享创建 body 用 sourceId（原件 id）

组织分享（§1.2.9 复制副本）：

POST /api/orgs/{orgId}/shares（ORG share:create）：body {entityType: QR_CODE|ALBUM_PHOTO, sourceId} → 服务端复制副本（qr/album 加 org_id，文件共用 file_id）→ 返回映射记录
GET /api/orgs/{orgId}/shares（ORG share:read）：分享映射列表
DELETE /api/orgs/{orgId}/shares/{shareId}（ORG share:delete，OWNER/ADMIN）：物理删除副本 + 映射
组织副本列表：GET /api/qr-codes?orgId=（ORG qrcode:read）/ GET /api/album/org/{orgId}（ORG album:read）

权限判定行为：所有端点逐方法 @RequirePermission；双域接口（asset/activity/qrcode/album）orgId 为空降级 APP 域；未命中返回 403 {"code":403,"message":"无权限执行该操作"}。

联系人聊天（IM）接口（新增）

完整契约见专用文档 /designs/messaging/contacts-chat.md（§6.1-6.3 端点、§6.7 DTO 字段级定义）。此处仅列端点索引。

联系人（/api/contacts）：申请（POST requests / GET incoming·outgoing·pending-count / POST {id}/accept·reject）、列表（GET / GET {contactId} / PUT {contactId}/remark·tags / DELETE {contactId}）、黑名单（POST {contactId}/block·unblock）、搜索与名片码（GET search / my-qrcode / by-qr-code/{code}，POST my-qrcode/refresh）、隐私设置（GET/PUT settings）

会话（/api/chats/conversations）：列表/详情（GET）、置顶（POST {id}/pin）、免打扰（PUT {id}/mute）、草稿（PUT {id}/draft）、删除会话（DELETE {id}）、清空记录（DELETE {id}/messages）、历史（GET {id}/messages?beforeId=&limit=）、已读（POST {id}/read）

消息（/api/chats/messages）：发送（POST，client_msg_id 幂等 + attachments 多图拆条）、撤回（POST {id}/recall，2 分钟）、转发（POST forward，多联系人）、增量同步（GET /api/chats/sync?afterId=）

管理后台（/api/admin/chat）：设置（GET/PUT settings，chat_setting:read/update）、统计（GET stats）

WebSocket：/ws/chat?token= 多设备长连接，事件协议见专用文档 §3.3；NPM /ws/ 反代已支持。

业务错误码：4011 对方开启了朋友验证 / 4012 消息被拒收 / 4014 撤回超时 / 4015 会话无权限 / 4020 未知消息类型 / 4021 content 校验失败 / 4022 配额或限流。

API 接口说明 — CodeNote Server ​

目录 ​

1. 概述 ​

角色体系 ​

认证方式 ​

2. 核心基础模块 ​

M1 - 用户认证（AuthController） ​

M2 - 二维码 CRUD（QrCodeController） ​

M3 - 分类管理（CategoryController） ​

M4 - 扫码记录（ScanRecordController） ​

M5 - 登录记录（LoginRecordController） ​

M5b - 文件上传（FileController） ​

M6 - 通知中心（NotificationController） ​

M7 - 云同步（SyncController） ​

M8 - 协议公开接口（AgreementController） ​

3. 组织模块 ​

B1 - 组织管理（OrgController） ​

4. 业务模块 ​

B4 - 固定资源管理（AssetController） ​

B6 - 活动管理（ActivityController） ​

B7 - 签到系统（CheckInController） ​

B8 - 通行证系统（PassController） ​

B9 - 水印相册（AlbumController） ​

业务二维码渲染 & 落地页（PublicQrCodeController） ​

5. 管理后台模块 ​

A1 - 仪表盘 ​

A2 - 用户管理 ​

A3 - 组织管理 ​

A5 - 二维码审计 ​

A6 - 资源管理 ​

A8 - 活动管理 ​

A9 - 签到管理 ​

A10 - 通行证管理 ​

A11 - 水印相册管理 ​

A12 - 分类管理 ​

A13 - 资源分类管理 ​

A14 - 通知管理 ​

A15 - 分享记录管理 ​

A16 - 系统配置 ​

A17 - 操作日志 ​

A18 - 文件管理 ​

A19 - 登录记录管理 ​

A20 - 会话管理 ​

A21 - 元数据管理（meta_*，替代原字段定义管理） ​

A22 - 扫码记录 ​

A23 - 协议管理（AdminAgreementController）与 Markdown 渲染 ​

6. 安全架构 ​

公开路径（permitAll，无需认证） ​

权限校验 ​

设备用户认证 ​

附录：认证端点补充契约 ​

改造端点 ​

响应变更 ​

附录：密码/解绑端点完整契约 ​

忘记密码（公开，无需登录） ​

修改密码（登录态） ​

解绑（登录态） ​

set-username / set-password 契约（重构版） ​

绑定端点补强（最终版） ​

RBAC 权限接口（新增） ​

联系人聊天（IM）接口（新增） ​