接口与数据约定

本页记录 OpenAPI 不易表达的跨接口规则与主要数据关系。接口的路径、参数和请求/响应字段以运行中的 OpenAPI 文档 为准。

模块与数据

后端由 weiran-framework（通用响应和认证）、weiran-system（账号、权限与平台能力）、weiran-region（行政区划）和 weiran-app（可执行应用）组成。业务模块按 api、domain、application、infrastructure、adapter 五层组织，依赖方向见架构说明。

数据表	作用与重要约束
sys_user	统一账号与资料；用户名、非空手机号全局唯一；avatar 为只含 text 和 background 的 JSON 文字头像，另存性别、偏好和收藏菜单；token_version 用于吊销令牌。
sys_user_identity	外部身份；(provider, external_id) 唯一，不按用户名关联。
sys_role、sys_user_role	角色与用户角色关系；关系表有自增 ID，并保留 (user_id, role_id) 唯一约束。
sys_menu、sys_role_menu	目录、菜单和按钮权限；角色菜单关系表有自增 ID，并保留 (role_id, menu_id) 唯一约束。
sys_group、sys_dict_item	字典与配置共享分组表，按 type 隔离；字典项通过 group_id 关联。
sys_config	配置值和字段元数据；公开配置按 config_system、config_sms 分域，内部 system.security.settings 保存密码规则与手机多因素认证设置，不对通用配置接口开放。
sys_media、sys_media_reference	资源文件及其引用；删除前检查引用，细节见资源库引用与删除设计。
sys_login_log、sys_operation_log	登录事件与操作审计。
region	行政区划；代码保持唯一，父子关系由区划代码关联。

表结构由 Flyway 迁移维护。已执行过的迁移不得修改；后续变更追加新脚本。

路由、响应与错误码

• /api-{type}/{module}/... 是登录后入口；/api-{type}/n/{module}/... 是未鉴权入口。当前 type 为 backend。
• 统一响应为 {code, message, data}。成功 code 是数字 0；失败为六位数字，按 {服务号}{资源号}{错误号} 编码，每段两位。框架服务号 10、系统 11、地区 12。HTTP 状态码由错误定义单独决定。
• 列表默认按 ID 降序，保证跨页稳定。树形列表保留父子层级，同级按 ID 降序。
• 按钮权限码登记在菜单数据中；超级管理员的权限集合为 ["*"]。隐藏的菜单仍可注册路由，只从导航中隐藏。

模块	服务号	菜单 ID	权限前缀
通用框架	10	—	—
系统管理	11	1–999	system:
行政区划	12	2000–2099	region:

新业务模块应在实现前分配独立的错误码服务号、菜单 ID 段和权限前缀，避免与已有模块重叠。

认证与账号

浏览器使用 HttpOnly 的 weiran_token Cookie。写请求还需携带 X-CSRF-Token，其值来自非 HttpOnly 的 weiran_csrf Cookie。脚本登录可带 X-Auth-Mode: token 获取令牌，然后使用 Bearer 请求。生产环境前后端应同源部署，详见部署与运维。

用户名不存在和密码错误统一返回 110101；禁用账号返回 110103。改密、重置密码和禁用账号会递增 token_version；每次请求都查库核对 JWT 的 ver。外部身份登录支持 OIDC 和 CAS；身份只按提供方与外部 ID 映射，本地同名账号不会自动关联。

用户名须为 2–32 位，仅含小写英文字母、数字和下划线，且全局唯一。本人可在个人中心修改用户名；修改后现有会话继续有效，新用户名立即用于登录。历史用户名不自动改写。

手机号登录在配置开关、短信发送器和验证码模板都就绪后可用。发码前若手机号未绑定或账号已禁用，分别返回 110106「手机号不存在」或 110107「手机号已禁用」。验证码有效期为 5 分钟且只能使用一次，并限制发送与尝试频率。本人修改手机号须先向新号码发送验证码，再验证并保存；个人资料接口不能直接改手机号。验证码当前保存在单实例内存中；多实例部署需使用共享存储。

安全设置支持密码长度与必需字符类型，并在新建、重置和修改密码时执行。启用手机多因素认证后，已绑定手机号的密码或外部身份登录先验短信再建立会话；未绑定账号暂时免验。验证后同一浏览器可在配置的有效期内免验，0 天表示每次登录都验证。修改安全设置或密码会撤销此前的设备信任。

local 短信模式会把替换后的验证码正文写入应用日志，并在登录日志的验证码事件中明文记录验证码，仅供受控开发环境使用。生产环境应选择 disabled 或 aliyun。

系统配置与资源

配置键遵循 {range}.{group}.{value}，如 system.general.title、sms.general.sign_name、sms.system_tpl.captcha_local。range 为 system 或 sms，group 对应分组编码。内置配置不能删除，内置键不能改名；匿名配置读取只允许 system.general.title。配置页操作见系统配置。

文件选中后立即上传并登记到资源管理；表单保存时才写入 URL、按顺序排列的 URL 数组或 HTML 引用。移除文件只修改业务配置，资源管理删除时会再次核对所有来源的引用。图片、PDF 与视频可在页面内预览，其余文件提供下载。图片、视频和普通文件的格式与大小上限在「文件系统 → 上传配置」Tab 中维护；视频默认上限 100 MB，普通文件默认上限 10 MB，两者均可设至 1024 MB。多文件组件默认最多 9 个。

行政区划

区划代码创建后不可修改。父级必须存在，层级必须正确，不能形成循环；有子级的节点不能删除。关键词命中后代时管理树保留祖先；供选择器使用的树只包含启用节点及其启用祖先。错误码 120101 表示父级或层级无效，120102 表示代码重复，120103 表示节点仍有子级。