feat(cordis): add OpenFlare Cordis 架构改造设计

docs(changelog): 修正表述笔误 refactor(cordis): 磁盘缓存改用上上游能力并清理本地副本按上游/下游归属规约：类型断言守卫已回流 Wavelet（f3d85d5，附回归用例），本仓库删除 OpenFlare/plugins/server/pkg/cache 整包并改 import 到 Wavelet/pkg/cache/disk，同步后与上游零漂移。验证：go build 通过；go test ./... exit 0（137 包 ok）；256 条路由对拍与 232 条 swagger 操作均零差异；make build-all 四进制；前端零改动。 docs(cordis): 记录 T1 清理结果与五个复用阻塞点 refactor(cordis): server 复用上游 pkg 能力并删除等价本地副本按上游/下游归属规约清理重复实现，删除 7 个与上游等价的本地包并改 import： shared/response→pkg/response、pkg/{logger,mail,trace,httppool,cache/ram}→ 上游同名包、infra/persistence/batchwriter→pkg/batchwriter。逐项核过差异： httppool 逐字节相同；logger 的 Config 字段完全一致；response 的 7 个 Abort* 一致；cache/ram 换过去顺带把裸 go 变回带 panic 恢复的 util.Go。两处非等价差异按语义处理： - batchwriter.Stats 与 status DTO 原为类型别名，改为消费侧逐字段转换，避免 model 反向依赖基础设施类型； - 上游 pkg/idgen 要求显式 Init（本地副本为懒加载自动初始化），本次保留本地副本，待与 infra 初始化一并迁移（已登记在清理计划）。验证：go build 通过；go test ./... exit 0（138 包 ok）；256 条路由对拍零差异； make swagger 232 条操作零增减，且归一化后与旧文档深度相等——差异仅为 response.Any / logger.LogEntry 两个定义名随包路径改名，接口形状未变。 chore(cordis): 回流内核与 pkg/util 通用能力并清理 vendoring 污染按新增的上游/下游归属规约：HandleRaw/BasePath 与版本比较、网络、格式化助手属通用能力，已提交到 Wavelet 分支 feat/cordis-router-raw-routes，本仓库改为纯同步获取（pkg/util 已零漂移），补丁登记保留至上游合并。同时修掉我此前 git add -A 造成的污染：首次 vendoring 把上游工作区里被 gitignore 的运行期产物一起提交进来（upload 的 diskcache 缓存块 650 个与 driver_http/dist 前端构建物 380 个，共 12872 行/1030 文件）。sync-upstream.sh 现显式排除 uploads/dist/data/*.db，.gitignore 补上对应兜底规则。 AGENTS.md 增加上游/下游改动归属规约，并把仍指向前 Cordis 布局的硬性约束（internal/router + Serve、internal/repository/logstore、internal/platform/bootstrap、 internal/cmd）改到当前插件路径。验证：go build 通过；go test ./... exit 0（144 包 ok）；make swagger 232 条操作与基线逐条一致；make build-all 四进制；gofmt 干净。 feat(cordis): server 插件化并改由内核挂载控制面路由新增 plugins/server/plugin.go：Apply 以 ctx.Router().Group(app.api_prefix) 声明根级与 /v1 全部路由；33 个注册函数由 *gin.RouterGroup 改为 core.RouterExtension，RegisterCollection 改用内核新增的 HandleRaw 保留尾部斜杠变体，AdminMiddlewares 返回 []any（Go 不允许把 []T 展开为 ...any）。删除 router.Serve 与 registerRoutes，装配根改为 core.App + driver_http.New(WithEngine(router.BuildEngine()))，监听、信号与优雅退出归内核；前端 SPA 的 NoRoute 兜底因内核暂无贡献点而保留在引擎层。路由保真证据：plugin_parity_test 对拍 baseline/routes-engine.txt 的 256 条 (方法路径) 零差异；go test ./... exit 0（144 包 ok，含真实 handler 的 openflare/integration 用例走同一条挂载路径）；make swagger 232 条操作与基线逐条一致；golangci-lint 0 issues；make build-all 四进制；embed_frontend 标签编译通过；前端零改动。已知待补：带 Redis 的实机 HTTP 冒烟（本机 6379 未启动，session store 与改造前一样在建店阶段即 fatal），以及 bootstrap 的任务/设置/迁移注册迁入 Apply。 feat(core): RouterExtension 增加 HandleRaw 与 BasePath 以保真尾部斜杠路由 server 插件化的前置：Handle 经 cleanPath 会剥掉尾部斜杠，无法表达 /resource 与 /resource/ 两条不同路由，而 OpenFlare 有 20 个历史 list 端点两者都注册且部署关闭了 RedirectTrailingSlash，缺失即 404。新增 HandleRaw 与 BasePath（作用域包装器同样登记反注册），补 extpoints 用例；并把 router.Serve 拆出 BuildEngine 以便交给 driver_http.WithEngine 复用，新增路由表导出 harness，固化 256 条 (方法路径) 基线供插件化对拍。上游补丁登记于 backend/OpenFlare/upstream-patches.md，同步脚本改为按目录前缀输出差异并在同步后提醒确认补丁是否仍在。验证：go build 通过；go test ./... exit 0（143 包 ok）；gofmt 干净。 docs(cordis): 记录 server 插件接入内核的可行路径与内核能力缺口 feat(cordis): agent/relay/flared 落地为内核驱动插件三个边缘守护进程各新增 plugin.go，实现 core.Plugin + core.Driver （自定义 DriverType 与同名 profile），装配与生命周期从 main 迁入 Apply/Start/Stop：Apply 负责 JSON 配置加载、运行环境与用户确保、 openresty/frps/frpc 管理器与各服务装配；Start 以 util.Go 拉起阻塞式 runner 与 GeoIP 周期更新；Stop 收敛主循环结果并在超时时报错而非静默。入口改为 core.NewApp(core.WithProfile(...)) + Prepare/Run，保持 -config 旗标、默认路径、退出码与启动/停止日志不变。验证：go build 通过；go test ./... exit 0（143 包 ok，含 3 个插件身份与配置失败路径测试）；make build-all 四进制产出；三进制实跑缺失配置均 exit 1 且错误链保留 load {agent,relay,flared} config 原因；gofmt 干净。 refactor(cordis): 按功能职责拆分为 4 个插件与 share 共享层 backend/OpenFlare 不再平铺遗留分层，改为 plugins/{server,agent,relay,flared} 加 share/：控制面业务（openflare/admin/oauth/user/upload/cap/config/health 与 repository/model/infra/router 等支撑层）归 server；三个边缘守护进程各自成插件；被两个以上插件消费的 protocol/geoip/wsclient/render/pagesarchive/edge 归 share。同时把 pkg/util 与 buildinfo 合并回上游 pkg（上游已覆盖全部符号，仅 8 个函数与 2 个类型为 OpenFlare 独有，已一并迁入），装配根统一到 backend/cmd（含三个 daemon 入口），Dockerfile 与 release 工作流的构建路径和 -X 注入路径同步更新。验证：go build 通过；go test ./... exit 0（141 包 ok）；make swagger exit 0 且 232 条 API 操作与基线逐条一致；make build-all 产出 4 进制；-X 注入经二进制 strings 实测生效；日志后端直连门禁改写为按 server 插件业务域扫描并在扫描数为 0 时报错（防门禁静默失效）；前端零改动。 feat(cordis): 落地 backend/share 共享层与上游同步脚本跨插件共享资源（控制消息协议、GeoIP+iputil、边缘守护进程日志）从下游包移入 backend/share，并声明其只能依赖 core/pkg 与标准/第三方库，禁止反向引用下游业务与具体插件实现；新增 scripts/sync-upstream.sh 只覆盖 backend/{core,pkg,plugins}，同步后 --check 报告零差异，证明与上游逐字一致。 go build 通过，go test ./... exit 0（142 包 ok），前端零改动。 refactor(cordis): 采用与 Wavelet 同构的单模块布局并引入上游内核按上游结构落位：backend/{core,pkg,plugins} 为 Wavelet 上游拷贝，OpenFlare 全部业务收拢到上游 downstream 所对应的位置 backend/OpenFlare/，模块名保持 Wavelet 以保证上游 import 路径逐字一致、同步零改写；三个 daemon 入口移至 backend/OpenFlare/cmd，backend/cmd 与 main.go 作为控制面装配根。行为不变：go build 通过，142 个测试包全绿（含上游插件测试），232 条 API 操作与改造前逐条一致，四进制产物正常，前端零改动。swagger 暂只扫描下游代码，待 P4 挂载上游路由后再纳入 plugins/。 style: 修正模块路径改写导致的 import 分组排序漂移 refactor(layout): Go 代码迁入 backend/ 并将模块名简化为 OpenFlare 对齐上游 Wavelet 的仓库布局，为以第二 module 形态 vendoring Cordis 内核与平台插件做准备：模块路径整体改写为 OpenFlare，Go 目标加 cd backend， swaggo 产物移至 backend/docs 并把 json/yaml 复制回 docs/ 供站点消费， Dockerfile 与 release 工作流的构建目录、ldflags 模块路径同步更新。行为保持不变：232 条路由与改造前逐条一致，95 个测试包全绿，四进制产物正常，前端零改动。 chore(cordis): 落地改造计划与 schema/路由基线新增 legacy_dump_test 迁移快照 harness：在临时 sqlite 库上按生产顺序（goose.UpTo → zone 导入 → goose.Up）跑完 76 个历史迁移并导出 schema 与版本序列，作为改造前后一致性门禁的唯一事实来源。同时记录 232 条路由清单与 foundation 实施计划。 docs(cordis): add OpenFlare Cordis 架构改造设计明确上游以第二 module 形态 vendoring 进 backend/Wavelet、4 个插件 (server/agent/relay/flared) 全部装载内核，并规定保留 76 个历史 goose 迁移 + 一次性版本 stamp 桥接的迁移方案，配套三方 schema 一致性门禁，确保已部署库不重跑历史、不丢数据。
2026-10-05 23:26:38 +08:00 · 2026-08-29 19:28:39 +08:00
parent 9f79fb9969
commit dbaa3bf140
1327 changed files with 91634 additions and 4157 deletions
@@ -0,0 +1,43 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+// HTTP 响应错误文案
+const (
+	errInvalidParams = "无效的请求参数"
+	errUserNotFound  = "用户不存在"
+	//nolint:gosec // error message, not hardcoded credentials
+	errPasswordMismatch = "用户名或密码错误"
+	//nolint:gosec // error message, not hardcoded credentials
+	errOldPasswordIncorrect = "原密码不正确"
+	//nolint:gosec // error message, not hardcoded credentials
+	errTokenNotFound    = "访问令牌不存在"
+	errCreateUserFailed = "创建用户失败: "
+	//nolint:gosec // error message, not hardcoded credentials
+	errCreateTokenFailed = "创建令牌失败"
+	//nolint:gosec // error message, not hardcoded credentials
+	errPasswordEncryptFailed = "密码加密失败"
+	//nolint:gosec // error message, not hardcoded credentials
+	errPasswordUpdateFailed = "密码更新失败"
+	// error message, not hardcoded credentials
+	errPasswordEmpty = "password cannot be empty"
+)
+
+// Service 层业务校验错误文案，取值被上游插件按字符串精确匹配消费，禁止改写
+const (
+	errUsernameEmpty        = "用户名不能为空"
+	errEmailEmpty           = "邮箱不能为空"
+	errUsernameTaken        = "用户名已被使用"
+	errEmailTaken           = "邮箱已被使用"
+	errCannotRevokeSelf     = "不能取消自己的管理员权限"
+	errAdminCannotDisable   = "管理员账号无法被禁用"
+	errAdminCannotDelete    = "管理员账号无法被删除"
+	errCannotDeleteSelf     = "不能删除当前登录用户"
+	errServiceUsernameEmpty = "user: username cannot be empty"
+	// error message, not hardcoded credentials
+	errServiceOldPasswordIncorrect = "user: incorrect old password"
+	//nolint:gosec // error message, not hardcoded credentials
+	errServicePasswordTooShort = "密码长度至少为 8 位"
+	errUniqueUsernameFailed    = "failed to generate unique username"
+)
@@ -0,0 +1,349 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/logger"
+	"Wavelet/pkg/response"
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"net/http"
+	"strconv"
+	"sync"
+
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-gonic/gin"
+)
+
+var (
+	authMu  sync.RWMutex
+	authSvc contracts.AuthService
+)
+
+// SetAuthService binds the AuthService for cache synchronization.
+func SetAuthService(s contracts.AuthService) {
+	authMu.Lock()
+	defer authMu.Unlock()
+	authSvc = s
+}
+
+func getAuthService() contracts.AuthService {
+	authMu.RLock()
+	defer authMu.RUnlock()
+	return authSvc
+}
+
+func getUserIDFromSession(c *gin.Context) uint64 {
+	defer func() { _ = recover() }()
+	session := sessions.Default(c)
+	val := session.Get(contracts.AuthUserIDKey)
+	if val == nil {
+		return 0
+	}
+	switch v := val.(type) {
+	case uint64:
+		return v
+	case int64:
+		if v < 0 {
+			return 0
+		}
+		return uint64(v)
+	case float64:
+		if v < 0 {
+			return 0
+		}
+		return uint64(v)
+	case string:
+		id, _ := strconv.ParseUint(v, 10, 64)
+		return id
+	default:
+		return 0
+	}
+}
+
+func invalidateUserCache(ctx context.Context, userID uint64) {
+	if s := getAuthService(); s != nil {
+		s.InvalidateCachedUser(ctx, userID)
+	}
+}
+
+func invalidateTokenCache(ctx context.Context, tokenHash string) {
+	if s := getAuthService(); s != nil {
+		s.InvalidateCachedToken(ctx, tokenHash)
+	}
+}
+
+// Login handles username and password authentication.
+func Login(c *gin.Context) {
+	var req loginRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, errInvalidParams)
+		return
+	}
+
+	user, err := GetUserByUsername(c.Request.Context(), req.Username)
+	if err != nil {
+		response.AbortUnauthorized(c, errPasswordMismatch)
+		return
+	}
+
+	if !user.CheckPassword(req.Password) {
+		response.AbortUnauthorized(c, errPasswordMismatch)
+		return
+	}
+
+	sess := sessions.Default(c)
+	sess.Set(contracts.AuthUserIDKey, user.ID)
+	sess.Set(contracts.AuthUserNameKey, user.Username)
+	needChange := user.NeedChangePassword || user.IsPlaintextPassword()
+	user.NeedChangePassword = needChange
+	sess.Set("need_change_password", needChange)
+	if err := sess.Save(); err != nil {
+		logger.ErrorF(c.Request.Context(), "save session failed on login: %v", err)
+	}
+
+	c.JSON(http.StatusOK, response.OK(user))
+}
+
+// Register registers a new user.
+func Register(c *gin.Context) {
+	var req registerRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, errInvalidParams)
+		return
+	}
+
+	newUser := &User{
+		Username: req.Username,
+		Email:    req.Email,
+		IsActive: true,
+	}
+	if err := newUser.SetEncryptedPassword(req.Password); err != nil {
+		response.AbortInternal(c, errPasswordEncryptFailed)
+		return
+	}
+
+	if err := CreateUser(c.Request.Context(), newUser); err != nil {
+		response.AbortBadRequest(c, errCreateUserFailed+err.Error())
+		return
+	}
+
+	sess := sessions.Default(c)
+	sess.Set(contracts.AuthUserIDKey, newUser.ID)
+	sess.Set(contracts.AuthUserNameKey, newUser.Username)
+	if err := sess.Save(); err != nil {
+		logger.ErrorF(c.Request.Context(), "save session failed on register: %v", err)
+	}
+
+	c.JSON(http.StatusOK, response.OK(newUser))
+}
+
+// Logout logs out the current session.
+func Logout(c *gin.Context) {
+	sess := sessions.Default(c)
+	sess.Options(sessions.Options{
+		Path:   "/",
+		MaxAge: -1,
+	})
+	sess.Clear()
+	if err := sess.Save(); err != nil {
+		logger.ErrorF(c.Request.Context(), "clear session failed on logout: %v", err)
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// SendEmailCode sends an email verification code.
+func SendEmailCode(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK(gin.H{"sent": true}))
+}
+
+// ChangePassword changes the current user password.
+func ChangePassword(c *gin.Context) {
+	var req changePasswordRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, errInvalidParams)
+		return
+	}
+
+	userID := getUserIDFromSession(c)
+	user, err := GetUserByID(c.Request.Context(), userID)
+	if err != nil {
+		response.AbortNotFound(c, errUserNotFound)
+		return
+	}
+
+	if !user.CheckPassword(req.OldPassword) {
+		response.AbortBadRequest(c, errOldPasswordIncorrect)
+		return
+	}
+
+	if err := user.SetEncryptedPassword(req.NewPassword); err != nil {
+		response.AbortInternal(c, errPasswordUpdateFailed)
+		return
+	}
+
+	if err := UpdateUser(c.Request.Context(), user); err != nil {
+		logger.ErrorF(c.Request.Context(), "persist changed password failed: %v", err)
+	}
+	invalidateUserCache(c.Request.Context(), user.ID)
+
+	sess := sessions.Default(c)
+	sess.Set("need_change_password", false)
+	if err := sess.Save(); err != nil {
+		logger.ErrorF(c.Request.Context(), "save session failed on change-password: %v", err)
+	}
+
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// UpdateProfile updates profile info.
+func UpdateProfile(c *gin.Context) {
+	var req updateProfileRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, errInvalidParams)
+		return
+	}
+
+	userID := getUserIDFromSession(c)
+	user, err := GetUserByID(c.Request.Context(), userID)
+	if err != nil {
+		response.AbortNotFound(c, errUserNotFound)
+		return
+	}
+
+	user.Nickname = req.Nickname
+	user.AvatarURL = req.AvatarURL
+	user.Bio = req.Bio
+	user.Phone = req.Phone
+	user.Gender = req.Gender
+	user.Website = req.Website
+	user.Location = req.Location
+
+	if err := UpdateUser(c.Request.Context(), user); err != nil {
+		logger.ErrorF(c.Request.Context(), "persist updated profile failed: %v", err)
+	}
+	invalidateUserCache(c.Request.Context(), user.ID)
+
+	c.JSON(http.StatusOK, response.OK(user))
+}
+
+// ListAccessTokens lists access tokens for the current user.
+func ListAccessTokens(c *gin.Context) {
+	userID := getUserIDFromSession(c)
+	tokens, err := listAccessTokensByUser(c.Request.Context(), userID)
+	if err != nil {
+		logger.ErrorF(c.Request.Context(), "list access tokens failed: %v", err)
+	}
+	c.JSON(http.StatusOK, response.OK(tokens))
+}
+
+const (
+	tokenEntropyByteLength = 24
+	tokenMaskMinLength     = 8
+)
+
+// CreateAccessToken generates a new access token.
+func CreateAccessToken(c *gin.Context) {
+	var req createAccessTokenRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, errInvalidParams)
+		return
+	}
+
+	userID := getUserIDFromSession(c)
+	rawBytes := make([]byte, tokenEntropyByteLength)
+	_, _ = rand.Read(rawBytes)
+	rawToken := "wvt_" + hex.EncodeToString(rawBytes)
+	hash := sha256.Sum256([]byte(rawToken))
+	tokenHash := hex.EncodeToString(hash[:])
+
+	masked := rawToken
+	if len(rawToken) > tokenMaskMinLength {
+		masked = rawToken[:4] + "..." + rawToken[len(rawToken)-4:]
+	}
+
+	token := AccessToken{
+		UserID:      userID,
+		Name:        req.Name,
+		TokenHash:   tokenHash,
+		MaskedToken: masked,
+		IsAdmin:     req.IsAdmin,
+	}
+
+	if err := createAccessTokenRow(c.Request.Context(), &token); err != nil {
+		response.AbortInternal(c, errCreateTokenFailed)
+		return
+	}
+
+	c.JSON(http.StatusOK, response.OK(gin.H{
+		"token":     token,
+		"raw_token": rawToken,
+	}))
+}
+
+// DeleteAccessToken deletes a specific access token.
+func DeleteAccessToken(c *gin.Context) {
+	idStr := c.Param("id")
+	id, err := strconv.ParseUint(idStr, 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, errInvalidParams)
+		return
+	}
+
+	userID := getUserIDFromSession(c)
+	token, err := getAccessTokenOfUser(c.Request.Context(), id, userID)
+	if err != nil {
+		response.AbortNotFound(c, errTokenNotFound)
+		return
+	}
+
+	if err := deleteAccessTokenRow(c.Request.Context(), token); err != nil {
+		logger.ErrorF(c.Request.Context(), "delete access token failed: %v", err)
+	}
+	invalidateTokenCache(c.Request.Context(), token.TokenHash)
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// RotateAccessToken rotates an access token value.
+func RotateAccessToken(c *gin.Context) {
+	idStr := c.Param("id")
+	id, err := strconv.ParseUint(idStr, 10, 64)
+	if err != nil {
+		response.AbortBadRequest(c, errInvalidParams)
+		return
+	}
+
+	userID := getUserIDFromSession(c)
+	token, err := getAccessTokenOfUser(c.Request.Context(), id, userID)
+	if err != nil {
+		response.AbortNotFound(c, errTokenNotFound)
+		return
+	}
+
+	invalidateTokenCache(c.Request.Context(), token.TokenHash)
+
+	rawBytes := make([]byte, tokenEntropyByteLength)
+	_, _ = rand.Read(rawBytes)
+	rawToken := "wvt_" + hex.EncodeToString(rawBytes)
+	hash := sha256.Sum256([]byte(rawToken))
+	token.TokenHash = hex.EncodeToString(hash[:])
+
+	masked := rawToken
+	if len(rawToken) > tokenMaskMinLength {
+		masked = rawToken[:4] + "..." + rawToken[len(rawToken)-4:]
+	}
+	token.MaskedToken = masked
+
+	if err := saveAccessTokenRow(c.Request.Context(), token); err != nil {
+		logger.ErrorF(c.Request.Context(), "rotate access token failed: %v", err)
+	}
+
+	c.JSON(http.StatusOK, response.OK(gin.H{
+		"token":     token,
+		"raw_token": rawToken,
+	}))
+}
@@ -0,0 +1,41 @@
+-- +goose Up
+-- +goose StatementBegin
+CREATE TABLE IF NOT EXISTS w_users (
+    id BIGINT PRIMARY KEY,
+    username VARCHAR(64) NOT NULL UNIQUE,
+    password VARCHAR(255),
+    nickname VARCHAR(255),
+    email VARCHAR(255),
+    avatar_url VARCHAR(255),
+    is_active BOOLEAN DEFAULT TRUE,
+    is_admin BOOLEAN DEFAULT FALSE,
+    bio VARCHAR(500),
+    phone VARCHAR(32),
+    gender VARCHAR(16),
+    website VARCHAR(255),
+    location VARCHAR(255),
+    last_login_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_w_users_email ON w_users (email);
+CREATE INDEX IF NOT EXISTS idx_w_users_is_active ON w_users (is_active);
+CREATE INDEX IF NOT EXISTS idx_w_users_last_login_at ON w_users (last_login_at);
+CREATE INDEX IF NOT EXISTS idx_w_users_created_at ON w_users (created_at);
+
+-- Seed system user
+INSERT INTO w_users (id, username, password, nickname, avatar_url, is_active, is_admin, last_login_at, created_at, updated_at)
+VALUES (999, 'system', '*', '系统', '', TRUE, FALSE, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+ON CONFLICT (username) DO NOTHING;
+
+-- Seed default administrator user (username: admin, password: 12345678)
+INSERT INTO w_users (id, username, password, nickname, email, is_active, is_admin, last_login_at, created_at, updated_at)
+VALUES (1, 'admin', '12345678', '管理员', 'admin@wavelet.local', TRUE, TRUE, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+ON CONFLICT (username) DO NOTHING;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+DELETE FROM w_users WHERE username = 'system';
+DROP TABLE IF EXISTS w_users;
+-- +goose StatementEnd
@@ -0,0 +1,41 @@
+-- +goose Up
+-- +goose StatementBegin
+CREATE TABLE IF NOT EXISTS w_users (
+    id BIGINT PRIMARY KEY,
+    username VARCHAR(64) NOT NULL UNIQUE,
+    password VARCHAR(255),
+    nickname VARCHAR(255),
+    email VARCHAR(255),
+    avatar_url VARCHAR(255),
+    is_active BOOLEAN DEFAULT 1,
+    is_admin BOOLEAN DEFAULT 0,
+    bio VARCHAR(500),
+    phone VARCHAR(32),
+    gender VARCHAR(16),
+    website VARCHAR(255),
+    location VARCHAR(255),
+    last_login_at DATETIME,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_w_users_email ON w_users (email);
+CREATE INDEX IF NOT EXISTS idx_w_users_is_active ON w_users (is_active);
+CREATE INDEX IF NOT EXISTS idx_w_users_last_login_at ON w_users (last_login_at);
+CREATE INDEX IF NOT EXISTS idx_w_users_created_at ON w_users (created_at);
+
+-- Seed system user
+INSERT INTO w_users (id, username, password, nickname, avatar_url, is_active, is_admin, last_login_at, created_at, updated_at)
+VALUES (999, 'system', '*', '系统', '', 1, 0, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+ON CONFLICT (username) DO NOTHING;
+
+-- Seed default administrator user (username: admin, password: 12345678)
+INSERT INTO w_users (id, username, password, nickname, email, is_active, is_admin, last_login_at, created_at, updated_at)
+VALUES (1, 'admin', '12345678', '管理员', 'admin@wavelet.local', 1, 1, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+ON CONFLICT (username) DO NOTHING;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+DELETE FROM w_users WHERE username = 'system';
+DROP TABLE IF EXISTS w_users;
+-- +goose StatementEnd
@@ -0,0 +1,140 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"Wavelet/pkg/util"
+	"errors"
+	"strings"
+	"time"
+)
+
+// AccessToken 个人访问令牌实体
+type AccessToken struct {
+	ID          uint64    `json:"id" gorm:"primaryKey;autoIncrement"`
+	UserID      uint64    `json:"user_id" gorm:"index;not null"`
+	Name        string    `json:"name" gorm:"size:128;not null"`
+	TokenHash   string    `json:"-" gorm:"size:64;uniqueIndex;not null"`
+	MaskedToken string    `json:"masked_token" gorm:"size:64;not null"`
+	IsAdmin     bool      `json:"is_admin" gorm:"default:false"`
+	CreatedAt   time.Time `json:"created_at" gorm:"autoCreateTime"`
+	UpdatedAt   time.Time `json:"updated_at" gorm:"autoUpdateTime"`
+}
+
+// TableName 表名
+func (AccessToken) TableName() string {
+	return "w_access_tokens"
+}
+
+// User 用户表实体
+type User struct {
+	ID                 uint64    `json:"id,string" gorm:"primaryKey;not null"`
+	Username           string    `json:"username" gorm:"size:64;uniqueIndex"`
+	Password           string    `json:"password,omitempty" gorm:"size:255"`
+	Nickname           string    `json:"nickname" gorm:"size:255"`
+	Email              string    `json:"email" gorm:"size:255;index"`
+	AvatarURL          string    `json:"avatar_url" gorm:"size:255"`
+	IsActive           bool      `json:"is_active" gorm:"default:true;index"`
+	IsAdmin            bool      `json:"is_admin" gorm:"default:false"`
+	NeedChangePassword bool      `json:"need_change_password,omitempty" gorm:"-"`
+	Bio                string    `json:"bio" gorm:"size:500"`
+	Phone              string    `json:"phone" gorm:"size:32"`
+	Gender             string    `json:"gender" gorm:"size:16"`
+	Website            string    `json:"website" gorm:"size:255"`
+	Location           string    `json:"location" gorm:"size:255"`
+	LastLoginAt        time.Time `json:"last_login_at" gorm:"index"`
+	CreatedAt          time.Time `json:"created_at" gorm:"autoCreateTime;index"`
+	UpdatedAt          time.Time `json:"updated_at" gorm:"autoUpdateTime;index"`
+}
+
+// TableName 表名
+func (User) TableName() string {
+	return "w_users"
+}
+
+// IsPlaintextPassword 检查当前密码是否为未加密的明文密码（如初始默认密码）
+func (u *User) IsPlaintextPassword() bool {
+	if u.Password == "" {
+		return false
+	}
+	return !strings.HasPrefix(u.Password, "$2a$") &&
+		!strings.HasPrefix(u.Password, "$2b$") &&
+		!strings.HasPrefix(u.Password, "$2y$") &&
+		!strings.HasPrefix(u.Password, "$2x$")
+}
+
+// SetEncryptedPassword 设置加密密码
+func (u *User) SetEncryptedPassword(password string) error {
+	trimmed := strings.TrimSpace(password)
+	if trimmed == "" {
+		return errors.New(errPasswordEmpty)
+	}
+	hash, err := util.HashPassword(trimmed)
+	if err != nil {
+		return err
+	}
+	u.Password = hash
+	return nil
+}
+
+// CheckPassword 校验密码（支持 bcrypt 哈希校验与初始明文密码校验）
+func (u *User) CheckPassword(password string) bool {
+	if u.Password == "" {
+		util.DummyCheckPassword(password)
+		return false
+	}
+	if !u.IsPlaintextPassword() {
+		return util.CheckPasswordHash(u.Password, password)
+	}
+
+	// 明文密码兼容比对（识别初始默认密码向用户警告修改密码）
+	if u.Password == password {
+		u.NeedChangePassword = true
+		return true
+	}
+	return false
+}
+
+// loginRequest 登录请求参数
+type loginRequest struct {
+	Username string `json:"username" binding:"required"`
+	Password string `json:"password" binding:"required"`
+}
+
+// registerRequest 注册请求参数
+type registerRequest struct {
+	Username string `json:"username" binding:"required"`
+	Password string `json:"password" binding:"required"`
+	Email    string `json:"email"`
+}
+
+// changePasswordRequest 修改密码请求参数
+type changePasswordRequest struct {
+	OldPassword string `json:"old_password" binding:"required"`
+	NewPassword string `json:"new_password" binding:"required"`
+}
+
+// updateProfileRequest 资料更新请求参数
+type updateProfileRequest struct {
+	Nickname  string `json:"nickname"`
+	AvatarURL string `json:"avatar_url"`
+	Bio       string `json:"bio"`
+	Phone     string `json:"phone"`
+	Gender    string `json:"gender"`
+	Website   string `json:"website"`
+	Location  string `json:"location"`
+}
+
+// createAccessTokenRequest 创建访问令牌请求参数
+type createAccessTokenRequest struct {
+	Name      string     `json:"name" binding:"required"`
+	ExpiresAt *time.Time `json:"expires_at"`
+	IsAdmin   bool       `json:"is_admin"`
+}
+
+// userAdminFlags 用户写操作前置校验所需的最小列投影
+type userAdminFlags struct {
+	ID      uint64
+	IsAdmin bool
+}
@@ -0,0 +1,254 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package user provides the user profile, credential management, role management, and access token domain plugin for Cordis.
+package user
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/core/extpoints"
+	"Wavelet/pkg/ginutil"
+	"context"
+	"embed"
+	"reflect"
+
+	"github.com/gin-gonic/gin"
+)
+
+//go:embed migrations/*/*.sql
+var userMigrations embed.FS
+
+// Option configures the user plugin.
+type Option func(*Plugin)
+
+// WithUserService sets a custom UserService implementation.
+func WithUserService(svc contracts.UserService) Option {
+	return func(p *Plugin) {
+		p.userSvc = svc
+	}
+}
+
+// Plugin implements core.Plugin to provide user account and credential domain services.
+type Plugin struct {
+	userSvc contracts.UserService
+}
+
+// New creates a new user domain plugin.
+func New(opts ...Option) *Plugin {
+	p := &Plugin{}
+	for _, opt := range opts {
+		if opt != nil {
+			opt(p)
+		}
+	}
+	return p
+}
+
+// PluginName 用户插件唯一名称标识
+const PluginName = "user"
+
+// Name returns the unique identifier for the user domain plugin.
+func (p *Plugin) Name() string {
+	return PluginName
+}
+
+// Inject declares required dependencies for the user domain plugin.
+func (p *Plugin) Inject() []reflect.Type {
+	return []reflect.Type{
+		reflect.TypeFor[contracts.DBService](),
+		// Apply resolves AuthService to build the route auth middleware. The
+		// kernel only gates Apply on declared deps, so leaving this out lets
+		// user mount before auth and fall back to a pass-through middleware.
+		reflect.TypeFor[contracts.AuthService](),
+	}
+}
+
+// Manifest returns the plugin metadata.
+func (p *Plugin) Manifest() core.Manifest {
+	return core.Manifest{
+		Name:        PluginName,
+		Version:     "1.0.0",
+		Description: "User profiles, credentials, role management, and access token domain plugin",
+		Author:      "Wavelet Team",
+	}
+}
+
+// Apply registers user migrations, services, routes, tasks, schedules, and settings into the Context.
+func (p *Plugin) Apply(ctx *core.Context) error {
+	// 0. Bind DBService from Context
+	if db, err := core.Inject[contracts.DBService](ctx); err == nil && db != nil {
+		SetDBService(db)
+	} else {
+		core.When[contracts.DBService](ctx, func(db contracts.DBService) {
+			SetDBService(db)
+		})
+	}
+	ctx.OnDispose(func() error {
+		SetDBService(nil)
+		return nil
+	})
+
+	// 0.1 Resolve auth service for middleware and cache invalidation (via IoC, not direct import)
+	denyAuth := ginutil.AuthUnavailable()
+	loginMW := denyAuth
+	noTokenMW := denyAuth
+	if authSvc, err := core.Inject[contracts.AuthService](ctx); err == nil && authSvc != nil {
+		SetAuthService(authSvc)
+		if mw, ok := authSvc.RequireAuthMiddleware().(gin.HandlerFunc); ok {
+			loginMW = mw
+		}
+		if mw, ok := authSvc.DisallowTokenAuthMiddleware().(gin.HandlerFunc); ok {
+			noTokenMW = mw
+		}
+	} else {
+		core.When[contracts.AuthService](ctx, func(svc contracts.AuthService) {
+			SetAuthService(svc)
+		})
+	}
+	ctx.OnDispose(func() error {
+		SetAuthService(nil)
+		return nil
+	})
+
+	// 1. Register migrations
+	ctx.Migrations().Register("user", userMigrations)
+
+	// 2. Initialize and provide UserService
+	if p.userSvc == nil {
+		p.userSvc = newUserService(ctx.Events())
+	}
+	core.Provide[contracts.UserService](ctx, p.userSvc)
+
+	// 3. Register HTTP Routes
+	userGroup := ctx.Router().Group("/api/v1/user")
+	{
+		userGroup.POST("/login", Login)
+		userGroup.POST("/register", Register)
+		userGroup.GET("/logout", Logout)
+		userGroup.POST("/send-email-code", SendEmailCode)
+		userGroup.POST("/change-password", loginMW, ChangePassword)
+		userGroup.PUT("/profile", loginMW, UpdateProfile)
+
+		// Access Tokens
+		tokensGroup := userGroup.Group("/access-tokens", loginMW, noTokenMW)
+		{
+			tokensGroup.GET("", ListAccessTokens)
+			tokensGroup.POST("", CreateAccessToken)
+			tokensGroup.DELETE("/:id", DeleteAccessToken)
+			tokensGroup.POST("/:id/rotate", RotateAccessToken)
+		}
+	}
+
+	const (
+		defaultUserTaskRetry = 3
+		paramTypeString      = "string"
+		paramNameEmail       = "email"
+	)
+
+	// 4. Register background tasks
+	ctx.Task().Register("user:send_email_code", func(_ context.Context, _ []byte) error {
+		return nil
+	},
+		extpoints.WithTaskType("send_email_code"),
+		extpoints.WithTaskName("发送邮箱验证码"),
+		extpoints.WithTaskDescription("异步发送用户注册与验证邮箱验证码"),
+		extpoints.WithTaskCategory("user"),
+		extpoints.WithTaskRetry(defaultUserTaskRetry),
+		extpoints.WithTaskQueue("default"),
+		extpoints.WithTaskRetryable(true),
+		extpoints.WithTaskParams(
+			contracts.TaskParamDTO{
+				Name:        paramNameEmail,
+				Label:       "目标邮箱",
+				Type:        paramTypeString,
+				Required:    true,
+				Placeholder: "user@example.com",
+				Description: "接收验证码的目标邮箱",
+			},
+			contracts.TaskParamDTO{
+				Name:        "code",
+				Label:       "验证码",
+				Type:        paramTypeString,
+				Required:    true,
+				Placeholder: "123456",
+				Description: "6 位数字验证码",
+			},
+		),
+	)
+
+	ctx.Task().Register("mail:send", func(_ context.Context, _ []byte) error {
+		return nil
+	},
+		extpoints.WithTaskType("send_email"),
+		extpoints.WithTaskName("发送邮件"),
+		extpoints.WithTaskDescription("异步发送系统邮件"),
+		extpoints.WithTaskCategory("mail"),
+		extpoints.WithTaskRetry(defaultUserTaskRetry),
+		extpoints.WithTaskQueue("default"),
+		extpoints.WithTaskRetryable(true),
+		extpoints.WithTaskParams(
+			contracts.TaskParamDTO{
+				Name:        "to",
+				Label:       "接收邮箱 (To)",
+				Type:        paramTypeString,
+				Required:    true,
+				Placeholder: "receiver@example.com",
+				Description: "接收邮件的目标邮箱地址",
+			},
+			contracts.TaskParamDTO{
+				Name:        "subject",
+				Label:       "邮件主题 (Subject)",
+				Type:        paramTypeString,
+				Required:    true,
+				Placeholder: "请输入邮件主题",
+				Description: "发送邮件的主题标题",
+			},
+			contracts.TaskParamDTO{
+				Name:        "body",
+				Label:       "邮件内容 (Body)",
+				Type:        "text",
+				Required:    true,
+				Placeholder: "请输入邮件内容（支持 HTML格式）",
+				Description: "发送邮件的内容主体",
+			},
+		),
+	)
+
+	ctx.Task().Register("user:cleanup_inactive", func(_ context.Context, _ []byte) error {
+		return nil
+	},
+		extpoints.WithTaskType("cleanup_inactive_users"),
+		extpoints.WithTaskName("清理未激活用户"),
+		extpoints.WithTaskDescription("清理长期未激活的注册用户与临时凭据"),
+		extpoints.WithTaskCategory("user"),
+		extpoints.WithTaskQueue("default"),
+	)
+
+	// 5. Register Settings Schemas
+	ctx.Settings().Register(extpoints.SettingSchema{
+		Key:         "user.registration_enabled",
+		Default:     true,
+		Description: "Whether new user registration is enabled",
+		Type:        "boolean",
+		Category:    "general",
+		Public:      true,
+	})
+	ctx.Settings().Register(extpoints.SettingSchema{
+		Key:         "user.password_login_enabled",
+		Default:     true,
+		Description: "Whether password login is enabled",
+		Type:        "boolean",
+		Category:    "general",
+		Public:      true,
+	})
+	ctx.Settings().Register(extpoints.SettingSchema{
+		Key:         "user.min_password_length",
+		Default:     8,
+		Description: "Minimum password length required for user accounts",
+		Type:        "integer",
+		Category:    "security",
+	})
+
+	return nil
+}
@@ -0,0 +1,200 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user_test
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/idgen"
+	"Wavelet/plugins/domain/user"
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-contrib/sessions/cookie"
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+
+	database "Wavelet/plugins/infra/database"
+)
+
+func setupTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	_ = idgen.Init(1)
+	dbPath := filepath.Join(t.TempDir(), "user_test.db")
+	testDB, err := gorm.Open(sqlite.Open(dbPath), &gorm.Config{})
+	require.NoError(t, err)
+
+	require.NoError(t, testDB.AutoMigrate(
+		&user.User{},
+		&user.AccessToken{},
+	))
+
+	database.SetDB(testDB)
+	return testDB
+}
+
+func TestUserPluginUnit(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+	ctx.Config().SetSource(core.NewMapSource(nil))
+	require.NoError(t, ctx.Config().Resolve())
+	testDB := setupTestDB(t)
+
+	dbPlugin := database.New(database.WithDB(testDB))
+	require.NoError(t, dbPlugin.Apply(ctx))
+
+	p := user.New()
+	assert.Equal(t, "user", p.Name())
+	assert.Equal(t, "1.0.0", p.Manifest().Version)
+	require.NoError(t, p.Apply(ctx))
+
+	userSvc, err := core.Inject[contracts.UserService](ctx)
+	require.NoError(t, err)
+	require.NotNil(t, userSvc)
+
+	testCtx := context.Background()
+
+	// 1. Create User
+	u, err := userSvc.CreateUser(testCtx, contracts.CreateUserRequest{
+		Username: "charlie",
+		Password: "Password789!",
+		Email:    "charlie@example.com",
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "charlie", u.Username)
+
+	// 2. Empty username error
+	_, err = userSvc.CreateUser(testCtx, contracts.CreateUserRequest{})
+	assert.Error(t, err)
+
+	// 3. Verify Password
+	assert.True(t, userSvc.VerifyPassword(testCtx, u.ID, "Password789!"))
+	assert.False(t, userSvc.VerifyPassword(testCtx, u.ID, "Wrong"))
+
+	// 4. Update Password with wrong old password
+	err = userSvc.UpdatePassword(testCtx, u.ID, "WrongOld", "NewPass999!")
+	assert.Error(t, err)
+
+	// Update Password success
+	err = userSvc.UpdatePassword(testCtx, u.ID, "Password789!", "NewPass999!")
+	require.NoError(t, err)
+	assert.True(t, userSvc.VerifyPassword(testCtx, u.ID, "NewPass999!"))
+
+	// 5. Update Profile
+	nickname := "Charlie Brown"
+	email := "charlie.new@example.com"
+	gender := "male"
+	website := "https://charlie.me"
+	loc := "SF"
+	updated, err := userSvc.UpdateProfile(testCtx, u.ID, contracts.UpdateUserProfileRequest{
+		Nickname: &nickname,
+		Email:    &email,
+		Gender:   &gender,
+		Website:  &website,
+		Location: &loc,
+	})
+	require.NoError(t, err)
+	assert.Equal(t, "Charlie Brown", updated.Nickname)
+	assert.Equal(t, "charlie.new@example.com", updated.Email)
+	assert.Equal(t, "male", updated.Gender)
+	assert.Equal(t, "https://charlie.me", updated.Website)
+	assert.Equal(t, "SF", updated.Location)
+
+	// 6. List and Status
+	require.NoError(t, userSvc.SetUserAdmin(testCtx, u.ID, true))
+	require.NoError(t, userSvc.SetUserActive(testCtx, u.ID, true))
+
+	list, total, err := userSvc.ListUsers(testCtx, 1, 10, "")
+	require.NoError(t, err)
+	assert.GreaterOrEqual(t, total, int64(1))
+	assert.NotEmpty(t, list)
+}
+
+func TestUserLoginHTTPHandler(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+	ctx.Config().SetSource(core.NewMapSource(nil))
+	require.NoError(t, ctx.Config().Resolve())
+	testDB := setupTestDB(t)
+
+	dbPlugin := database.New(database.WithDB(testDB))
+	require.NoError(t, dbPlugin.Apply(ctx))
+
+	p := user.New()
+	require.NoError(t, p.Apply(ctx))
+
+	userSvc, err := core.Inject[contracts.UserService](ctx)
+	require.NoError(t, err)
+
+	_, err = userSvc.CreateUser(context.Background(), contracts.CreateUserRequest{
+		Username: "admin",
+		Password: "Password123!",
+		Email:    "admin@example.com",
+	})
+	require.NoError(t, err)
+
+	r := gin.New()
+	cookieStore := cookie.NewStore([]byte("test-session-secret"))
+	r.Use(sessions.Sessions("wavelet_session", cookieStore))
+	r.POST("/api/v1/user/login", user.Login)
+
+	reqBody := `{"username":"admin","password":"Password123!"}`
+	req, _ := http.NewRequest(http.MethodPost, "/api/v1/user/login", bytes.NewBufferString(reqBody))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	r.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Contains(t, w.Body.String(), `"username":"admin"`)
+	setCookie := w.Header().Get("Set-Cookie")
+	assert.NotEmpty(t, setCookie)
+	assert.Contains(t, setCookie, "wavelet_session=")
+
+	// Plaintext default password seeded user
+	plainUser := &user.User{
+		Username: "plain_admin",
+		Password: "12345678", // Plaintext seed
+		Email:    "plain@example.com",
+		IsActive: true,
+	}
+	require.NoError(t, user.CreateUser(context.Background(), plainUser))
+
+	reqBodyPlain := `{"username":"plain_admin","password":"12345678"}`
+	reqPlain, _ := http.NewRequest(http.MethodPost, "/api/v1/user/login", bytes.NewBufferString(reqBodyPlain))
+	reqPlain.Header.Set("Content-Type", "application/json")
+	wPlain := httptest.NewRecorder()
+
+	r.ServeHTTP(wPlain, reqPlain)
+
+	assert.Equal(t, http.StatusOK, wPlain.Code)
+	assert.Contains(t, wPlain.Body.String(), `"username":"plain_admin"`)
+	assert.Contains(t, wPlain.Body.String(), `"need_change_password":true`)
+	cookieHeader := wPlain.Header().Get("Set-Cookie")
+	assert.NotEmpty(t, cookieHeader)
+
+	// Change password
+	r.POST("/api/v1/user/change-password", user.ChangePassword)
+	changeBody := `{"old_password":"12345678","new_password":"NewStrongPassword123!"}`
+	reqChange, _ := http.NewRequest(http.MethodPost, "/api/v1/user/change-password", bytes.NewBufferString(changeBody))
+	reqChange.Header.Set("Content-Type", "application/json")
+	reqChange.Header.Set("Cookie", cookieHeader)
+	wChange := httptest.NewRecorder()
+
+	r.ServeHTTP(wChange, reqChange)
+	assert.Equal(t, http.StatusOK, wChange.Code)
+
+	// Verify updated user model has encrypted password and need_change_password is false
+	updatedUser, err := user.GetUserByUsername(context.Background(), "plain_admin")
+	require.NoError(t, err)
+	assert.False(t, updatedUser.IsPlaintextPassword())
+	assert.True(t, updatedUser.CheckPassword("NewStrongPassword123!"))
+	assert.False(t, updatedUser.NeedChangePassword)
+}
@@ -0,0 +1,366 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/util"
+	"context"
+	"strings"
+	"sync"
+
+	"gorm.io/gorm"
+)
+
+var (
+	dbMu  sync.RWMutex
+	dbSvc contracts.DBService
+)
+
+// SetDBService sets the active DBService contract for the user domain plugin.
+func SetDBService(s contracts.DBService) {
+	dbMu.Lock()
+	defer dbMu.Unlock()
+	dbSvc = s
+}
+
+func getDB(ctx context.Context) *gorm.DB {
+	if c, ok := ctx.(*core.Context); ok && c != nil {
+		if s, err := core.Inject[contracts.DBService](c); err == nil && s != nil {
+			return s.DB(ctx)
+		}
+	}
+
+	dbMu.RLock()
+	s := dbSvc
+	dbMu.RUnlock()
+	if s != nil {
+		return s.DB(ctx)
+	}
+
+	return nil
+}
+
+// GetUserByID 通过 ID 获取用户
+func GetUserByID(ctx context.Context, id uint64) (*User, error) {
+	var u User
+	if err := getDB(ctx).First(&u, id).Error; err != nil {
+		return nil, err
+	}
+	return &u, nil
+}
+
+// GetUsersByIDs 一次性批量获取多个用户，避免调用方按 ID 逐条查询。
+func GetUsersByIDs(ctx context.Context, ids []uint64) ([]User, error) {
+	if len(ids) == 0 {
+		return []User{}, nil
+	}
+	var users []User
+	if err := getDB(ctx).Where("id IN ?", ids).Find(&users).Error; err != nil {
+		return nil, err
+	}
+	return users, nil
+}
+
+// GetUserByUsername 通过用户名获取用户
+func GetUserByUsername(ctx context.Context, username string) (*User, error) {
+	var u User
+	if err := getDB(ctx).Where("username = ?", username).First(&u).Error; err != nil {
+		return nil, err
+	}
+	return &u, nil
+}
+
+// GetUserByEmail 通过邮箱获取用户
+func GetUserByEmail(ctx context.Context, email string) (*User, error) {
+	var u User
+	if err := getDB(ctx).Where("email = ?", email).First(&u).Error; err != nil {
+		return nil, err
+	}
+	return &u, nil
+}
+
+// CreateUser 创建用户
+func CreateUser(ctx context.Context, u *User) error {
+	return getDB(ctx).Create(u).Error
+}
+
+// UpdateUser 更新用户
+func UpdateUser(ctx context.Context, u *User) error {
+	return getDB(ctx).Save(u).Error
+}
+
+// ListUsers 分页查询用户
+func ListUsers(ctx context.Context, page, pageSize int, keyword string) ([]*User, int64, error) {
+	db := getDB(ctx).Model(&User{})
+	if keyword != "" {
+		escaped := util.EscapeLike(keyword)
+		db = db.Where("username LIKE ? ESCAPE '\\' OR nickname LIKE ? ESCAPE '\\' OR email LIKE ? ESCAPE '\\'", "%"+escaped+"%", "%"+escaped+"%", "%"+escaped+"%")
+	}
+
+	var total int64
+	if err := db.Count(&total).Error; err != nil {
+		return nil, 0, err
+	}
+
+	var users []*User
+	offset := (page - 1) * pageSize
+	if err := db.Offset(offset).Limit(pageSize).Order("id DESC").Find(&users).Error; err != nil {
+		return nil, 0, err
+	}
+	return users, total, nil
+}
+
+// GetAccessTokenByHash 通过 Hash 查询访问令牌
+func GetAccessTokenByHash(ctx context.Context, tokenHash string) (*AccessToken, error) {
+	var token AccessToken
+	if err := getDB(ctx).Where("token_hash = ?", tokenHash).First(&token).Error; err != nil {
+		return nil, err
+	}
+	return &token, nil
+}
+
+// AdminUserListFilter 包含后台用户列表过滤条件
+type AdminUserListFilter struct {
+	Username string
+	Keyword  string
+	Page     int
+	PageSize int
+}
+
+// ListAdminUsers 获取后台管理用户列表
+func ListAdminUsers(ctx context.Context, filter AdminUserListFilter) (int64, []User, error) {
+	query := getDB(ctx).Model(&User{})
+	if filter.Username != "" {
+		escaped := util.EscapeLike(strings.ToLower(filter.Username))
+		query = query.Where("LOWER(username) LIKE ? ESCAPE '\\'", "%"+escaped+"%")
+	}
+	if filter.Keyword != "" {
+		escaped := util.EscapeLike(strings.ToLower(filter.Keyword))
+		query = query.Where("LOWER(username) LIKE ? ESCAPE '\\' OR LOWER(nickname) LIKE ? ESCAPE '\\' OR LOWER(email) LIKE ? ESCAPE '\\'",
+			"%"+escaped+"%", "%"+escaped+"%", "%"+escaped+"%")
+	}
+
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return 0, nil, err
+	}
+
+	var users []User
+	offset := (filter.Page - 1) * filter.PageSize
+	if err := query.Order("id DESC").Offset(offset).Limit(filter.PageSize).Find(&users).Error; err != nil {
+		return 0, nil, err
+	}
+	return total, users, nil
+}
+
+// UpdateUserActive 更新用户激活状态
+func UpdateUserActive(ctx context.Context, id uint64, active bool) error {
+	return getDB(ctx).Model(&User{}).Where("id = ?", id).Update("is_active", active).Error
+}
+
+// GetActiveUserByID 获取处于激活状态的用户
+func GetActiveUserByID(ctx context.Context, id uint64) (*User, error) {
+	var u User
+	if err := getDB(ctx).Where("id = ? AND is_active = ?", id, true).First(&u).Error; err != nil {
+		return nil, err
+	}
+	return &u, nil
+}
+
+// DeleteUserWithRelations 删除用户及其级联关系
+func DeleteUserWithRelations(ctx context.Context, id uint64) error {
+	return getDB(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Where("user_id = ?", id).Delete(&AccessToken{}).Error; err != nil {
+			return err
+		}
+		return tx.Where("id = ?", id).Delete(&User{}).Error
+	})
+}
+
+// GetFirstAdminUser 获取第一个管理员用户
+func GetFirstAdminUser(ctx context.Context) (*User, error) {
+	var u User
+	if err := getDB(ctx).Where("is_admin = ?", true).Order("id ASC").First(&u).Error; err != nil {
+		return nil, err
+	}
+	return &u, nil
+}
+
+// ListUsernamesMatchingBase 列出匹配基础用户名的所有用户名
+func ListUsernamesMatchingBase(ctx context.Context, base string) ([]string, error) {
+	var usernames []string
+	escaped := util.EscapeLike(strings.ToLower(base))
+	if err := getDB(ctx).Model(&User{}).
+		Where("LOWER(username) LIKE ? ESCAPE '\\'", escaped+"%").
+		Pluck("username", &usernames).Error; err != nil {
+		return nil, err
+	}
+	return usernames, nil
+}
+
+// adminUserColumns 后台用户查询显式列清单
+const adminUserColumns = "id, username, nickname, email, avatar_url, is_active, is_admin, bio, phone, gender, website, location, last_login_at, created_at, updated_at"
+
+// updateUserColumns 按列局部更新指定用户行
+func updateUserColumns(ctx context.Context, id uint64, updates map[string]any) error {
+	return getDB(ctx).Model(&User{}).Where("id = ?", id).Updates(updates).Error
+}
+
+// setUserAdminFlag 更新指定用户的管理员标记列
+func setUserAdminFlag(ctx context.Context, id uint64, admin bool) error {
+	return getDB(ctx).Model(&User{}).Where("id = ?", id).Update("is_admin", admin).Error
+}
+
+// setUserActiveColumn 后台启用/禁用用户，沿用无 schema 的按表直写语义
+// （与导出函数 UpdateUserActive 不同，后者经由 Model 会额外刷新 updated_at）
+func setUserActiveColumn(ctx context.Context, id uint64, active bool) error {
+	return getDB(ctx).Table("w_users").Where("id = ?", id).Update("is_active", active).Error
+}
+
+// countAllUsers 统计用户总数
+func countAllUsers(ctx context.Context) (int64, error) {
+	var count int64
+	err := getDB(ctx).Model(&User{}).Count(&count).Error
+	return count, err
+}
+
+// countActiveUsers 统计激活状态用户数
+func countActiveUsers(ctx context.Context) (int64, error) {
+	var count int64
+	err := getDB(ctx).Model(&User{}).Where("is_active = ?", true).Count(&count).Error
+	return count, err
+}
+
+// countUsersByUsername 统计同名用户数量
+func countUsersByUsername(ctx context.Context, username string) (int64, error) {
+	var count int64
+	err := getDB(ctx).Table("w_users").Where("username = ?", username).Count(&count).Error
+	return count, err
+}
+
+// countUsersByEmail 统计同邮箱用户数量
+func countUsersByEmail(ctx context.Context, email string) (int64, error) {
+	var count int64
+	err := getDB(ctx).Table("w_users").Where("email = ?", email).Count(&count).Error
+	return count, err
+}
+
+// countOtherUsersByEmail 统计除指定用户外的同邮箱数量
+func countOtherUsersByEmail(ctx context.Context, email string, id uint64) (int64, error) {
+	var count int64
+	err := getDB(ctx).Table("w_users").Where("email = ? AND id != ?", email, id).Count(&count).Error
+	return count, err
+}
+
+// adminListUserRows 后台条件分页查询用户
+func adminListUserRows(ctx context.Context, filter contracts.AdminListUsersFilter) (int64, []*contracts.UserDTO, error) {
+	query := getDB(ctx).Table("w_users")
+	if filter.UserID != nil {
+		query = query.Where("id = ?", *filter.UserID)
+	}
+	if filter.Username != "" {
+		query = query.Where("username LIKE ? ESCAPE '\\'", util.EscapeLike(filter.Username)+"%")
+	}
+	if filter.Email != "" {
+		query = query.Where("email LIKE ? ESCAPE '\\'", util.EscapeLike(filter.Email)+"%")
+	}
+
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return 0, nil, err
+	}
+
+	var users []*contracts.UserDTO
+	offset := (filter.Page - 1) * filter.PageSize
+	if err := query.
+		Select(adminUserColumns).
+		Order("id ASC").
+		Offset(offset).
+		Limit(filter.PageSize).
+		Find(&users).Error; err != nil {
+		return 0, nil, err
+	}
+	return total, users, nil
+}
+
+// adminGetUserRow 后台按 ID 读取用户视图
+func adminGetUserRow(ctx context.Context, id uint64) (*contracts.UserDTO, error) {
+	var user contracts.UserDTO
+	if err := getDB(ctx).Table("w_users").
+		Select(adminUserColumns).
+		Where("id = ?", id).
+		First(&user).Error; err != nil {
+		return nil, err
+	}
+	return &user, nil
+}
+
+// getUserRow 按 ID 整行读取用户视图
+func getUserRow(ctx context.Context, id uint64) (*contracts.UserDTO, error) {
+	var user contracts.UserDTO
+	if err := getDB(ctx).Table("w_users").Where("id = ?", id).First(&user).Error; err != nil {
+		return nil, err
+	}
+	return &user, nil
+}
+
+// insertUserRow 以显式列映射写入用户行
+func insertUserRow(ctx context.Context, row map[string]any) error {
+	return getDB(ctx).Table("w_users").Create(row).Error
+}
+
+// getUserAdminFlags 读取指定用户的管理员标记
+func getUserAdminFlags(ctx context.Context, id uint64) (userAdminFlags, error) {
+	var flags userAdminFlags
+	if err := getDB(ctx).Table("w_users").Select("id, is_admin").Where("id = ?", id).First(&flags).Error; err != nil {
+		return userAdminFlags{}, err
+	}
+	return flags, nil
+}
+
+// deleteUserCascadeAdmin 在事务中删除用户的访问令牌、外部账号绑定与用户行
+func deleteUserCascadeAdmin(ctx context.Context, id uint64) error {
+	return getDB(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Table("w_access_tokens").Where("user_id = ?", id).Delete(map[string]any{}).Error; err != nil {
+			return err
+		}
+		if err := tx.Table("w_external_accounts").Where("user_id = ?", id).Delete(map[string]any{}).Error; err != nil {
+			return err
+		}
+		return tx.Table("w_users").Where("id = ?", id).Delete(map[string]any{}).Error
+	})
+}
+
+// listAccessTokensByUser 列出指定用户的访问令牌
+func listAccessTokensByUser(ctx context.Context, userID uint64) ([]AccessToken, error) {
+	var tokens []AccessToken
+	err := getDB(ctx).Where("user_id = ?", userID).Find(&tokens).Error
+	return tokens, err
+}
+
+// getAccessTokenOfUser 按 ID 与所属用户读取访问令牌
+func getAccessTokenOfUser(ctx context.Context, id, userID uint64) (*AccessToken, error) {
+	var token AccessToken
+	if err := getDB(ctx).Where("id = ? AND user_id = ?", id, userID).First(&token).Error; err != nil {
+		return nil, err
+	}
+	return &token, nil
+}
+
+// createAccessTokenRow 写入访问令牌记录
+func createAccessTokenRow(ctx context.Context, token *AccessToken) error {
+	return getDB(ctx).Create(token).Error
+}
+
+// saveAccessTokenRow 全量保存访问令牌记录
+func saveAccessTokenRow(ctx context.Context, token *AccessToken) error {
+	return getDB(ctx).Save(token).Error
+}
+
+// deleteAccessTokenRow 删除访问令牌记录
+func deleteAccessTokenRow(ctx context.Context, token *AccessToken) error {
+	return getDB(ctx).Delete(token).Error
+}
@@ -0,0 +1,494 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package user provides user profiles, credentials, role management, and access token domain services.
+package user
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/idgen"
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	pkgu "Wavelet/pkg/util"
+)
+
+const columnUpdatedAt = "updated_at"
+
+func toUserDTO(u *User) *contracts.UserDTO {
+	if u == nil {
+		return nil
+	}
+	return &contracts.UserDTO{
+		ID:                 u.ID,
+		Username:           u.Username,
+		Nickname:           u.Nickname,
+		Email:              u.Email,
+		AvatarURL:          u.AvatarURL,
+		IsActive:           u.IsActive,
+		IsAdmin:            u.IsAdmin,
+		NeedChangePassword: u.NeedChangePassword || u.IsPlaintextPassword(),
+		Bio:                u.Bio,
+		Phone:              u.Phone,
+		Gender:             u.Gender,
+		Website:            u.Website,
+		Location:           u.Location,
+		LastLoginAt:        u.LastLoginAt,
+		CreatedAt:          u.CreatedAt,
+		UpdatedAt:          u.UpdatedAt,
+	}
+}
+
+type userServiceImpl struct {
+	events *core.EventBus
+}
+
+func newUserService(events ...*core.EventBus) contracts.UserService {
+	var bus *core.EventBus
+	if len(events) > 0 {
+		bus = events[0]
+	}
+	return &userServiceImpl{events: bus}
+}
+
+func (s *userServiceImpl) GetUserByID(ctx context.Context, id uint64) (*contracts.UserDTO, error) {
+	u, err := GetUserByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+	return toUserDTO(u), nil
+}
+
+func (s *userServiceImpl) GetUsersByIDs(ctx context.Context, ids []uint64) ([]*contracts.UserDTO, error) {
+	users, err := GetUsersByIDs(ctx, ids)
+	if err != nil {
+		return nil, err
+	}
+	dtos := make([]*contracts.UserDTO, 0, len(users))
+	for i := range users {
+		dtos = append(dtos, toUserDTO(&users[i]))
+	}
+	return dtos, nil
+}
+
+func (s *userServiceImpl) GetUserByUsername(ctx context.Context, username string) (*contracts.UserDTO, error) {
+	u, err := GetUserByUsername(ctx, username)
+	if err != nil {
+		return nil, err
+	}
+	return toUserDTO(u), nil
+}
+
+func (s *userServiceImpl) GetUserByEmail(ctx context.Context, email string) (*contracts.UserDTO, error) {
+	u, err := GetUserByEmail(ctx, email)
+	if err != nil {
+		return nil, err
+	}
+	return toUserDTO(u), nil
+}
+
+func (s *userServiceImpl) CreateUser(ctx context.Context, req contracts.CreateUserRequest) (*contracts.UserDTO, error) {
+	if req.Username == "" {
+		return nil, errors.New(errServiceUsernameEmpty)
+	}
+
+	user := User{
+		ID:          idgen.NextUint64ID(),
+		Username:    req.Username,
+		Nickname:    req.Nickname,
+		Email:       req.Email,
+		IsActive:    true,
+		IsAdmin:     req.IsAdmin,
+		CreatedAt:   time.Now(),
+		UpdatedAt:   time.Now(),
+		LastLoginAt: time.Now(),
+	}
+
+	if user.Nickname == "" {
+		user.Nickname = req.Username
+	}
+
+	if req.Password != "" {
+		if err := user.SetEncryptedPassword(req.Password); err != nil {
+			return nil, err
+		}
+	}
+
+	if err := CreateUser(ctx, &user); err != nil {
+		return nil, err
+	}
+
+	return toUserDTO(&user), nil
+}
+
+func (s *userServiceImpl) UpdateProfile(ctx context.Context, id uint64, req contracts.UpdateUserProfileRequest) (*contracts.UserDTO, error) {
+	updates := make(map[string]any)
+	if req.Nickname != nil {
+		updates["nickname"] = *req.Nickname
+	}
+	if req.Email != nil {
+		updates["email"] = *req.Email
+	}
+	if req.AvatarURL != nil {
+		updates["avatar_url"] = *req.AvatarURL
+	}
+	if req.Bio != nil {
+		updates["bio"] = *req.Bio
+	}
+	if req.Phone != nil {
+		updates["phone"] = *req.Phone
+	}
+	if req.Gender != nil {
+		updates["gender"] = *req.Gender
+	}
+	if req.Website != nil {
+		updates["website"] = *req.Website
+	}
+	if req.Location != nil {
+		updates["location"] = *req.Location
+	}
+	updates[columnUpdatedAt] = time.Now()
+
+	if err := updateUserColumns(ctx, id, updates); err != nil {
+		return nil, err
+	}
+
+	return s.GetUserByID(ctx, id)
+}
+
+func (s *userServiceImpl) UpdatePassword(ctx context.Context, id uint64, oldPassword, newPassword string) error {
+	user, err := GetUserByID(ctx, id)
+	if err != nil {
+		return err
+	}
+
+	if !user.CheckPassword(oldPassword) {
+		return errors.New(errServiceOldPasswordIncorrect)
+	}
+
+	if err := user.SetEncryptedPassword(newPassword); err != nil {
+		return err
+	}
+
+	if err := updateUserColumns(ctx, id, map[string]any{
+		"password":      user.Password,
+		columnUpdatedAt: time.Now(),
+	}); err != nil {
+		return err
+	}
+	invalidateUserCache(ctx, id)
+	return nil
+}
+
+func (s *userServiceImpl) VerifyPassword(ctx context.Context, id uint64, password string) bool {
+	user, err := GetUserByID(ctx, id)
+	if err != nil {
+		pkgu.DummyCheckPassword(password)
+		return false
+	}
+	return user.CheckPassword(password)
+}
+
+func (s *userServiceImpl) UpdateLastLogin(ctx context.Context, id uint64, _ string) error {
+	return updateUserColumns(ctx, id, map[string]any{
+		"last_login_at": time.Now(),
+		columnUpdatedAt: time.Now(),
+	})
+}
+
+func (s *userServiceImpl) ListUsers(ctx context.Context, page, pageSize int, keyword string) ([]*contracts.UserDTO, int64, error) {
+	if page <= 0 {
+		page = 1
+	}
+	if pageSize <= 0 {
+		pageSize = 20
+	}
+
+	filter := AdminUserListFilter{
+		Username: keyword,
+		Page:     page,
+		PageSize: pageSize,
+	}
+
+	total, users, err := ListAdminUsers(ctx, filter)
+	if err != nil {
+		return nil, 0, err
+	}
+
+	dtos := make([]*contracts.UserDTO, 0, len(users))
+	for i := range users {
+		dtos = append(dtos, toUserDTO(&users[i]))
+	}
+
+	return dtos, total, nil
+}
+
+func (s *userServiceImpl) SetUserActive(ctx context.Context, id uint64, active bool) error {
+	return UpdateUserActive(ctx, id, active)
+}
+
+func (s *userServiceImpl) SetUserAdmin(ctx context.Context, id uint64, admin bool) error {
+	return setUserAdminFlag(ctx, id, admin)
+}
+
+func (s *userServiceImpl) VerifyAccessToken(ctx context.Context, tokenHash string) (*contracts.UserDTO, bool, error) {
+	tokenRecord, err := GetAccessTokenByHash(ctx, tokenHash)
+	if err != nil {
+		return nil, false, err
+	}
+
+	user, err := GetActiveUserByID(ctx, tokenRecord.UserID)
+	if err != nil {
+		return nil, false, err
+	}
+
+	return toUserDTO(user), tokenRecord.IsAdmin, nil
+}
+
+func (s *userServiceImpl) DeleteUser(ctx context.Context, id uint64) error {
+	return DeleteUserWithRelations(ctx, id)
+}
+
+func (s *userServiceImpl) CountUsers(ctx context.Context) (int64, error) {
+	return countAllUsers(ctx)
+}
+
+func (s *userServiceImpl) CountActiveUsers(ctx context.Context) (int64, error) {
+	return countActiveUsers(ctx)
+}
+
+func (s *userServiceImpl) GetFirstAdminUser(ctx context.Context) (*contracts.UserDTO, error) {
+	u, err := GetFirstAdminUser(ctx)
+	if err != nil {
+		return nil, err
+	}
+	return toUserDTO(u), nil
+}
+
+func (s *userServiceImpl) UniqueUsername(ctx context.Context, base string) (string, error) {
+	base = strings.TrimSpace(base)
+	if base == "" {
+		base = PluginName
+	}
+
+	existingUsernames, err := ListUsernamesMatchingBase(ctx, base)
+	if err != nil {
+		return "", err
+	}
+
+	exists := make(map[string]bool, len(existingUsernames))
+	for _, u := range existingUsernames {
+		exists[strings.ToLower(u)] = true
+	}
+
+	if !exists[strings.ToLower(base)] {
+		return base, nil
+	}
+
+	for i := 1; i <= 1000; i++ {
+		candidate := fmt.Sprintf("%s-%d", base, i)
+		if !exists[strings.ToLower(candidate)] {
+			return candidate, nil
+		}
+	}
+
+	return "", errors.New(errUniqueUsernameFailed)
+}
+
+func (s *userServiceImpl) AdminListUsers(ctx context.Context, filter contracts.AdminListUsersFilter) (int64, []*contracts.UserDTO, error) {
+	if filter.Page <= 0 {
+		filter.Page = 1
+	}
+	if filter.PageSize <= 0 {
+		filter.PageSize = 20
+	}
+	return adminListUserRows(ctx, filter)
+}
+
+func (s *userServiceImpl) AdminGetUser(ctx context.Context, id uint64) (*contracts.UserDTO, error) {
+	return adminGetUserRow(ctx, id)
+}
+
+func (s *userServiceImpl) AdminCreateUser(ctx context.Context, req contracts.AdminCreateUserRequest) (*contracts.UserDTO, error) {
+	req.Username = strings.TrimSpace(req.Username)
+	req.Nickname = strings.TrimSpace(req.Nickname)
+	req.Password = strings.TrimSpace(req.Password)
+	req.Email = strings.TrimSpace(req.Email)
+
+	if req.Username == "" {
+		return nil, errors.New(errUsernameEmpty)
+	}
+	if req.Email == "" {
+		return nil, errors.New(errEmailEmpty)
+	}
+	const minPasswordLen = 8
+	if len(req.Password) < minPasswordLen {
+		return nil, errors.New(errServicePasswordTooShort)
+	}
+
+	count, err := countUsersByUsername(ctx, req.Username)
+	if err != nil {
+		return nil, err
+	}
+	if count > 0 {
+		return nil, errors.New(errUsernameTaken)
+	}
+
+	emailCount, err := countUsersByEmail(ctx, req.Email)
+	if err != nil {
+		return nil, err
+	}
+	if emailCount > 0 {
+		return nil, errors.New(errEmailTaken)
+	}
+
+	hash, err := pkgu.HashPassword(req.Password)
+	if err != nil {
+		return nil, err
+	}
+
+	if req.Nickname == "" {
+		req.Nickname = req.Username
+	}
+
+	now := time.Now()
+	newUser := contracts.UserDTO{
+		ID:        idgen.NextUint64ID(),
+		Username:  req.Username,
+		Nickname:  req.Nickname,
+		Email:     req.Email,
+		IsActive:  req.IsActive,
+		IsAdmin:   req.IsAdmin,
+		CreatedAt: now,
+		UpdatedAt: now,
+	}
+
+	row := map[string]any{
+		"id":            newUser.ID,
+		"username":      newUser.Username,
+		"password":      hash,
+		"nickname":      newUser.Nickname,
+		"email":         newUser.Email,
+		"is_active":     newUser.IsActive,
+		"is_admin":      newUser.IsAdmin,
+		"created_at":    now,
+		columnUpdatedAt: now,
+	}
+	if err := insertUserRow(ctx, row); err != nil {
+		return nil, err
+	}
+
+	if s.events != nil {
+		_ = s.events.Emit(ctx, contracts.EventTopicUserCreated, contracts.UserCreatedEvent{
+			User:     &newUser,
+			Password: req.Password,
+		})
+	}
+
+	return &newUser, nil
+}
+
+func (s *userServiceImpl) AdminUpdateUser(ctx context.Context, currentUserID uint64, req contracts.AdminUpdateUserRequest) error {
+	req.Nickname = strings.TrimSpace(req.Nickname)
+	req.Email = strings.TrimSpace(req.Email)
+	req.Password = strings.TrimSpace(req.Password)
+
+	if req.Email == "" {
+		return errors.New(errEmailEmpty)
+	}
+
+	targetUser, err := getUserRow(ctx, req.ID)
+	if err != nil {
+		return err
+	}
+
+	if currentUserID == req.ID && !req.IsAdmin && targetUser.IsAdmin {
+		return errors.New(errCannotRevokeSelf)
+	}
+
+	if targetUser.Email != req.Email {
+		count, err := countOtherUsersByEmail(ctx, req.Email, req.ID)
+		if err != nil {
+			return err
+		}
+		if count > 0 {
+			return errors.New(errEmailTaken)
+		}
+	}
+
+	const minPasswordLen = 8
+	if req.Password != "" && len(req.Password) < minPasswordLen {
+		return errors.New(errServicePasswordTooShort)
+	}
+
+	if req.Nickname == "" {
+		req.Nickname = targetUser.Username
+	}
+
+	updates := map[string]any{
+		"nickname":      req.Nickname,
+		"email":         req.Email,
+		"is_admin":      req.IsAdmin,
+		columnUpdatedAt: time.Now(),
+	}
+	if req.Password != "" {
+		hash, err := pkgu.HashPassword(req.Password)
+		if err != nil {
+			return err
+		}
+		updates["password"] = hash
+	}
+
+	err = updateUserColumns(ctx, req.ID, updates)
+	if err == nil && s.events != nil {
+		_ = s.events.Emit(ctx, contracts.EventTopicUserUpdated, targetUser)
+	}
+	return err
+}
+
+func (s *userServiceImpl) AdminUpdateUserStatus(ctx context.Context, id uint64, active bool) error {
+	flags, err := getUserAdminFlags(ctx, id)
+	if err != nil {
+		return err
+	}
+	if !active && flags.IsAdmin {
+		return errors.New(errAdminCannotDisable)
+	}
+
+	err = setUserActiveColumn(ctx, id, active)
+	if err == nil && s.events != nil {
+		_ = s.events.Emit(ctx, contracts.EventTopicUserStatusChanged, contracts.UserStatusChangedEvent{
+			UserID:   id,
+			IsActive: active,
+		})
+	}
+	return err
+}
+
+func (s *userServiceImpl) AdminDeleteUser(ctx context.Context, currentUserID, targetID uint64) error {
+	if currentUserID == targetID {
+		return errors.New(errCannotDeleteSelf)
+	}
+	flags, err := getUserAdminFlags(ctx, targetID)
+	if err != nil {
+		return err
+	}
+	if flags.IsAdmin {
+		return errors.New(errAdminCannotDelete)
+	}
+
+	if err := deleteUserCascadeAdmin(ctx, targetID); err != nil {
+		return err
+	}
+	if s.events != nil {
+		_ = s.events.Emit(ctx, contracts.EventTopicUserDeleted, contracts.UserDeletedEvent{
+			CurrentUserID: currentUserID,
+			TargetUserID:  targetID,
+		})
+	}
+	return nil
+}
@@ -0,0 +1,67 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package user_test
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/plugins/domain/user"
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+
+	database "Wavelet/plugins/infra/database"
+)
+
+// TestGetUsersByIDsUsesSingleQuery 回归：批量取用户必须只发一条 SQL，
+// 否则调用方（如访问日志按用户补全）会按 ID 逐条打库。
+func TestGetUsersByIDsUsesSingleQuery(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+	ctx.Config().SetSource(core.NewMapSource(nil))
+	require.NoError(t, ctx.Config().Resolve())
+	testDB := setupTestDB(t)
+	require.NoError(t, database.New(database.WithDB(testDB)).Apply(ctx))
+	require.NoError(t, user.New().Apply(ctx))
+
+	userSvc, err := core.Inject[contracts.UserService](ctx)
+	require.NoError(t, err)
+
+	bg := context.Background()
+	ids := make([]uint64, 0, 3)
+	for _, name := range []string{"batch_a", "batch_b", "batch_c"} {
+		u, err := userSvc.CreateUser(bg, contracts.CreateUserRequest{
+			Username: name,
+			Password: "Password789!",
+			Email:    name + "@example.com",
+		})
+		require.NoError(t, err)
+		ids = append(ids, u.ID)
+	}
+
+	queries := 0
+	require.NoError(t, testDB.Callback().Query().Register("count_queries", func(_ *gorm.DB) {
+		queries++
+	}))
+
+	got, err := userSvc.GetUsersByIDs(bg, ids)
+	require.NoError(t, err)
+	assert.Len(t, got, 3)
+	assert.Equal(t, 1, queries, "batch lookup must issue exactly one query")
+
+	queries = 0
+	for _, id := range ids {
+		_, err := userSvc.GetUserByID(bg, id)
+		require.NoError(t, err)
+	}
+	assert.Equal(t, 3, queries, "per-id lookups cost one query each")
+
+	queries = 0
+	empty, err := userSvc.GetUsersByIDs(bg, nil)
+	require.NoError(t, err)
+	assert.Empty(t, empty)
+	assert.Equal(t, 0, queries, "empty id list must not touch storage")
+}