Core：用户与后台账户管理
API 逐项需求、源码归属、字段与验收条件
当前固定源码下本组共 15 项方法 + 路径。下列为接口需求 v0.1，Owner 为 Core，计划阶段为 CE-02；均未宣称 OceanWay 已运行。原路径/字段默认沿用，变化须进入差异台账。
每项适用统一接口需求规则，并列出上游字段声明、控制器观察与具体补差。OpenAPI 没列必填不表示运行时可缺省；观察到的 JSON key 也不等于可写入字段。下载完整接口台账及上游管理规范、模型规范可查看完整嵌套 Schema。
CORE-USER-001 · GET /api/user-agreement
用途与归属：获取用户协议。优先沿用，迁入/适配后验收。
鉴权：未挂 User/Admin/Token 认证；按处理器及配置校验。
请求：自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。
返回：200 成功（上游未声明响应 Schema）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：读取可有界重试，不新建调用或扣款；结果为空、权限失败与查询未知分开。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:31；controller.GetUserAgreement controller/misc.go:193；上游 api.json 中 GET /api/user-agreement。
CORE-USER-002 · GET /api/user/
用途与归属：获取所有用户。优先沿用，迁入/适配后验收。
鉴权：Admin 员工身份。
请求：OpenAPI 参数：query.p:integer; query.page_size:integer。处理器读取：query.sort_by, query.sort_order, query.p, query.page_size。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。
返回：200 成功（上游未声明响应 Schema）；处理器使用 common.ApiSuccess 包络。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：读取可有界重试，不新建调用或扣款；结果为空、权限失败与查询未知分开。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:147；controller.GetAllUsers controller/user.go:335；上游 api.json 中 GET /api/user/。
CORE-USER-003 · POST /api/user/
用途与归属：创建用户。优先沿用，迁入/适配后验收。
鉴权：Admin 员工身份。
请求：Body 字段（application/json）：id:integer [规范未列必填]; username:string [规范未列必填]; display_name:string [规范未列必填]; role:integer [规范未列必填]; status:integer [规范未列必填]; email:string [规范未列必填]; group:string [规范未列必填]; quota:integer [规范未列必填]; used_quota:integer [规范未列必填]; request_count:integer [规范未列必填]。
返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 Error, message, role, success, username（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：沿用原行为，不擅自要求所有旧接口新增 Idempotency-Key；创建/财务动作必须定义重复点击和响应丢失结果，客户端不得无条件自动重试。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:155；controller.CreateUser controller/user.go:969；上游 api.json 中 POST /api/user/。
CORE-USER-004 · PUT /api/user/
用途与归属：更新用户。优先沿用，迁入/适配后验收。
鉴权：Admin 员工身份。
请求：Body 字段（application/json）：id:integer [规范未列必填]; username:string [规范未列必填]; display_name:string [规范未列必填]; role:integer [规范未列必填]; status:integer [规范未列必填]; email:string [规范未列必填]; group:string [规范未列必填]; quota:integer [规范未列必填]; used_quota:integer [规范未列必填]; request_count:integer [规范未列必填]。
返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 Error, id, message, success, username（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：沿用原行为，不擅自要求所有旧接口新增 Idempotency-Key；创建/财务动作必须定义重复点击和响应丢失结果，客户端不得无条件自动重试。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:157；controller.UpdateUser controller/user.go:647；上游 api.json 中 PUT /api/user/。
CORE-USER-005 · DELETE /api/user/:id
用途与归属：删除用户。优先沿用，迁入/适配后验收。
鉴权：Admin 员工身份。
请求：Path：id（必填；以实际路由名为准）。OpenAPI 参数：path.id:integer（必填）。处理器读取：path.id。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。
返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 id, message, success, username（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：沿用原行为，不擅自要求所有旧接口新增 Idempotency-Key；创建/财务动作必须定义重复点击和响应丢失结果，客户端不得无条件自动重试。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:158；controller.DeleteUser controller/user.go:910；上游 api.json 中 DELETE /api/user/{id}。
CORE-USER-006 · GET /api/user/:id
用途与归属：获取指定用户。优先沿用，迁入/适配后验收。
鉴权：Admin 员工身份。
请求：Path：id（必填；以实际路由名为准）。OpenAPI 参数：path.id:integer（必填）。处理器读取：path.id。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。
返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 data, message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：读取可有界重试，不新建调用或扣款；结果为空、权限失败与查询未知分开。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:154；controller.GetUser controller/user.go:384；上游 api.json 中 GET /api/user/{id}。
CORE-USER-007 · GET /api/user/aff
用途与归属：获取邀请码。优先沿用，迁入/适配后验收。
鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。
请求：自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。
返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 data, message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：读取可有界重试，不新建调用或扣款；结果为空、权限失败与查询未知分开。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:112；controller.GetAffCode controller/user.go:437；上游 api.json 中 GET /api/user/aff。
CORE-USER-008 · GET /api/user/checkin
用途与归属：GetCheckinStatus。优先沿用，迁入/适配后验收。
鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。
请求：处理器读取：query.month。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。
返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构；代码 JSON/映射中观察到 data, enabled, max_quota, message, min_quota, stats, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：读取可有界重试，不新建调用或扣款；结果为空、权限失败与查询未知分开。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。
来源：router/api-router.go:136；controller.GetCheckinStatus controller/checkin.go:16。
CORE-USER-009 · POST /api/user/checkin
用途与归属：DoCheckin。优先沿用，迁入/适配后验收。
鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。
请求：Body/表单由下方处理器定义；上游未提供完整 Schema，本项要求迁入时补出字段白名单、必填、类型、默认和限制，缺失不作为“任意 JSON”开放。
返回：上游 OpenAPI 无本项响应规范；按处理器返回值补齐成功、拒绝和错误结构；代码 JSON/映射中观察到 checkin_date, data, message, quota_awarded, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：沿用原行为，不擅自要求所有旧接口新增 Idempotency-Key；创建/财务动作必须定义重复点击和响应丢失结果，客户端不得无条件自动重试。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：OPENAPI-MISSING：源码已注册，上游 OpenAPI 无匹配操作。
来源：router/api-router.go:137；controller.DoCheckin controller/checkin.go:47。
CORE-USER-010 · POST /api/user/manage
用途与归属：管理用户状态。优先沿用，迁入/适配后验收。
鉴权：Admin 员工身份。
请求：Body 字段（application/json）：id:integer [规范未列必填]; action:string [规范未列必填] enum=["disable", "enable", "delete", "promote", "demote"]。
返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 action, data, delete, demote, disable, enable, id, message, promote, success, username（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：沿用原行为，不擅自要求所有旧接口新增 Idempotency-Key；创建/财务动作必须定义重复点击和响应丢失结果，客户端不得无条件自动重试。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:156；controller.ManageUser controller/user.go:1051；上游 api.json 中 POST /api/user/manage。
CORE-USER-011 · GET /api/user/search
用途与归属：搜索用户。优先沿用，迁入/适配后验收。
鉴权：Admin 员工身份。
请求：OpenAPI 参数：query.keyword:string; query.group:string。处理器读取：query.keyword, query.group, query.role, query.status, query.sort_by, query.sort_order, query.p, query.page_size。自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。
返回：200 成功（上游未声明响应 Schema）；处理器使用 common.ApiSuccess 包络。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：读取可有界重试，不新建调用或扣款；结果为空、权限失败与查询未知分开。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:150；controller.SearchUsers controller/user.go:351；上游 api.json 中 GET /api/user/search。
CORE-USER-012 · DELETE /api/user/self
用途与归属：注销当前用户。优先沿用，迁入/适配后验收。
鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器安全证明用途：VerificationScopeAccountDelete。
请求：自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。
返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 data, message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：沿用原行为，不擅自要求所有旧接口新增 Idempotency-Key；创建/财务动作必须定义重复点击和响应丢失结果，客户端不得无条件自动重试。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:101；controller.DeleteSelf controller/user.go:942；上游 api.json 中 DELETE /api/user/self。
CORE-USER-013 · GET /api/user/self
用途与归属：获取当前用户信息。优先沿用，迁入/适配后验收。
鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。
请求：自动提取未发现请求体字段；是否接受 Body 及约束仍以处理器为准。
返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 data, message, success（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：读取可有界重试，不新建调用或扣款；结果为空、权限失败与查询未知分开。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:98；controller.GetSelf controller/user.go:462；上游 api.json 中 GET /api/user/self。
CORE-USER-014 · PUT /api/user/self
用途与归属：更新当前用户信息。优先沿用，迁入/适配后验收。
鉴权：客户登录身份（沿用上游 UserAuth 支持范围）；处理器安全证明用途：VerificationScopePasswordChange, VerificationScopePasswordSet。
请求：Body 字段（application/json）：username:string [规范未列必填]; display_name:string [规范未列必填]; password:string [规范未列必填]; original_password:string [规范未列必填]。
返回：200 成功（上游未声明响应 Schema）；代码 JSON/映射中观察到 access_expires_at, access_token, data, has_password, message, notification_failed, notification_warning, session, success, token_type（仅为字面键观察，含分支/内部映射，不等同完整响应契约）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：沿用原行为，不擅自要求所有旧接口新增 Idempotency-Key；创建/财务动作必须定义重复点击和响应丢失结果，客户端不得无条件自动重试。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:100；controller.UpdateSelf controller/user.go:759；上游 api.json 中 PUT /api/user/self。
CORE-USER-015 · PUT /api/user/setting
用途与归属：更新用户设置。优先沿用，迁入/适配后验收。
鉴权：客户登录身份（沿用上游 UserAuth 支持范围）。
请求：Body 字段（application/json）：notify_type:string [规范未列必填]; quota_warning_threshold:number [规范未列必填]; webhook_url:string [规范未列必填]; notification_email:string [规范未列必填]。
返回：200 成功（上游未声明响应 Schema）。
业务与副作用：自身接口从认证上下文确定用户；员工接口逐项校验角色。禁止请求体覆盖服务端归属、余额和未授权角色；用户禁用/删除需影响后续授权并保留必要账务事实。
幂等、重试与异常：沿用原行为，不擅自要求所有旧接口新增 Idempotency-Key；创建/财务动作必须定义重复点击和响应丢失结果，客户端不得无条件自动重试。 保留原 HTTP 状态、业务 success/message 或模型 error 包络，不将所有失败改成同一状态。区分参数、身份、权限、余额、限流、上游与执行未知；敏感栈和供应凭据不返回客户。
验收需求：成功与空态；缺失/非法字段；未登录/跨账户/无权限；限流；资源不存在；重试与状态冲突；数据库提交后响应丢失（写操作）；返回字段与既有协议兼容。
迁入差异：RESPONSE-SCHEMA-MISSING：上游响应未定义结构；以处理器和兼容用例补齐。
来源：router/api-router.go:126；controller.UpdateUserSetting controller/user.go:1283；上游 api.json 中 PUT /api/user/setting。