From 2304fe1f7b45dbb7e329f70cdd200249ca4e9103 Mon Sep 17 00:00:00 2001 From: idleRain Date: Tue, 13 Oct 2026 14:00:02 +0800 Subject: [PATCH 1/5] =?UTF-8?q?fix(errors):=20=E4=B8=9A=E5=8A=A1=E9=94=99?= =?UTF-8?q?=E8=AF=AF=E5=BD=92=E5=93=A8=E5=85=B5=E5=B9=B6=E7=BB=8F=E5=94=AF?= =?UTF-8?q?=E4=B8=80=E6=98=A0=E5=B0=84=E7=82=B9=E5=88=86=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 service.ErrUnauthenticated 哨兵,contracts/errors.yaml 增补 401 分类并删除实现偏差节 - service 层 30 处裸 errors.New 与 fmt.Errorf 改为包装哨兵:认证失败归 401、业务校验归 400、资源未找到归 404 - Login、RefreshToken、CreateSession 的私有 401 分支与媒体上传、角色转换的私有 400 分支统一改走 HandleServiceError - 同步契约金样本、受影响测试替身与 server/docs/api 错误码表格 - docs/debt/architecture.md 第 7 条更新为已修复,基线由 30 处归零 --- AGENTS.md | 2 +- contracts/errors.yaml | 11 +++---- contracts/fixtures/login.wrong-password.json | 2 +- docs/architecture-rules.md | 2 +- docs/debt/README.md | 2 +- docs/debt/architecture.md | 8 ++--- docs/development.md | 2 +- server/docs/api/api-specification.md | 6 ++-- server/docs/api/category-api.md | 8 ++--- server/docs/api/friendly-link-api.md | 8 ++--- server/docs/api/media-api.md | 3 +- server/docs/api/session-api.md | 6 ++-- server/docs/api/tag-api.md | 8 ++--- server/docs/api/user-api.md | 20 ++++++------ server/internal/handler/README.md | 2 +- server/internal/handler/error.go | 3 +- server/internal/handler/error_test.go | 16 ++++++++++ server/internal/handler/login_fixture_test.go | 7 ++-- server/internal/handler/media.go | 2 +- server/internal/handler/session.go | 2 +- server/internal/handler/session_test.go | 6 ++-- server/internal/handler/user.go | 6 ++-- server/internal/service/README.md | 4 +-- server/internal/service/article.go | 4 +-- server/internal/service/category.go | 7 ++-- server/internal/service/category_test.go | 21 ++++++++++++ server/internal/service/errors.go | 5 +++ server/internal/service/friendly_link.go | 5 ++- server/internal/service/friendly_link_test.go | 9 ++++++ server/internal/service/media.go | 4 +-- server/internal/service/media_test.go | 8 +++++ server/internal/service/tag.go | 4 +-- server/internal/service/tag_test.go | 5 +++ server/internal/service/token.go | 8 ++--- server/internal/service/token_test.go | 5 +++ server/internal/service/user.go | 32 +++++++++---------- server/internal/service/user_login_test.go | 12 +++++++ server/internal/service/user_profile_test.go | 8 +++++ server/internal/service/user_refresh_test.go | 8 +++++ 39 files changed, 190 insertions(+), 91 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 57591e4..99fa192 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -85,7 +85,7 @@ pnpm run go:lint-install / go:quality / go:vulncheck / audit:deps - **POST-Only**:业务接口一律 `POST`(查询类同样 `POST`),参数承载于 JSON 请求体,纯 id 类短参数可放 path;健康探针属基础设施端点,按编排器标准用 `GET`(`internal/router/health.go`)。 - **校验**:handler 用 `ShouldBindJSON` + `binding` tag 完成必填、长度、格式、枚举校验,业务规则在 service 校验,校验通过才进入数据访问层;跨接口复用的校验必须提取公共方法,禁止复制(`service/user.go` 的密码强度校验为存量私有实现,触碰时迁移)。 - **分层**:`handler`(HTTP 与 DTO 映射)→ `service`(业务)→ `repository`(持久化);路由注册见 `internal/router/router.go` 与各模块 `internal/router/.go`。 -- **错误分档**:handler 的 `binding` 校验失败直接经 `response.BadRequest` 返回 400;service 返回的错误交 `internal/handler/error.go` 的 `HandleServiceError` 统一映射(`ErrPermissionDenied` → 403、12 个 not-found 哨兵 → 404、`ErrInvalidRequest`/`ErrUsernameTaken`/`ErrEmailTaken` → 400、其余脱敏为 500「服务器内部错误」并只把原文写日志),禁止模块内新增私有映射;新增 not-found 哨兵须同步扩展映射集合与 `contracts/errors.yaml`。 +- **错误分档**:handler 的 `binding` 校验失败直接经 `response.BadRequest` 返回 400;service 返回的错误交 `internal/handler/error.go` 的 `HandleServiceError` 统一映射(`ErrUnauthenticated` → 401、`ErrPermissionDenied` → 403、12 个 not-found 哨兵 → 404、`ErrInvalidRequest`/`ErrUsernameTaken`/`ErrEmailTaken` → 400、其余脱敏为 500「服务器内部错误」并只把原文写日志),禁止模块内新增私有映射;新增哨兵须同步扩展映射集合与 `contracts/errors.yaml`。 - **统一响应**:统一经 `pkg/response`,结构为 `{code, message, data?}`;响应码 `CodeSuccess=200`、`CodeError=500`、`CodeInvalid=400`、`CodeAuth=401`、`CodeForbid=403`、`CodeNotFound=404`。 - **类型归属**:领域实体统一在 `internal/domain`(`domain.User` 等),`internal/model` 保留各业务 GORM 实体,`repository` 只承载持久化实现,禁止在 repository 新增实体或 DTO。请求/响应 DTO 以所在业务域的 service 包内定义为常态(如 `service.CreateArticleRequest`),用户域的 `CreateUserRequest`/`UpdateUserRequest` 在 `internal/domain/dto.go`,少数 handler 就地声明(`SessionRequest`、`LogoutRequest`、`deleteDictRequest`);对外响应优先经 `domain` 的响应形状或窄化视图,禁止直出 GORM 实体(存量违例见 `docs/debt/security-runtime.md` 第 1 条)。 - **命名与接口位置**:Go 字段与 json tag 用小驼峰;接口与实现同包声明,统一 `XxxInterface` 后缀(存量 `UserService`、`RBACService`、`UserRepository` 未带后缀,触碰时统一);各层依赖接口而非实现,`router` 不得重复定义接口。 diff --git a/contracts/errors.yaml b/contracts/errors.yaml index fa778a1..b81f5d1 100644 --- a/contracts/errors.yaml +++ b/contracts/errors.yaml @@ -24,6 +24,10 @@ transport: # 禁止模块私有映射出现第二套权威;handler 层的 binding 校验失败与中间件权限判定不经此处, # 直接经 pkg/response 返回 400 / 401 / 403。 mapping: + '401': + # 登录凭据错误、账号状态异常与令牌校验失败统一包装该哨兵, + # 登录、刷新与会话建立三个入口均经 HandleServiceError 分档,不再有 handler 私有 401 分支 + - service.ErrUnauthenticated '403': - service.ErrPermissionDenied '404': @@ -49,13 +53,6 @@ mapping: # 原始错误仅写入日志,防止表名、列名与 SQL 片段经响应体泄漏。 [] -# 实现偏差:以下路径与上表冲突,契约口径以上表为准,修复方向是让这些路径改走唯一映射点, -# 不要按现状修改契约;偏差清除后删除本节。 -# - 登录与刷新失败的 401 由 handler 私有分支产生:handler/user.go 的 Login 与 RefreshToken -# 直接调用 response.Unauthorized(c, err.Error()) 返回,绕过 HandleServiceError, -# 构成第二套映射权威。修复方向是为认证失败定义哨兵并在本表增补 '401' 分类; -# 对应的 service 侧裸错误清单见 docs/debt/architecture.md 第 7 条。 - # 业务错误码命名空间(目标态,本轮不启用) # 决策:响应体不新增 bizCode 字段,code 语义维持传输层码;命名空间与业务码 # 待出现真实消费方后再启用,启用时须同时补齐双端常量与锚定测试。 diff --git a/contracts/fixtures/login.wrong-password.json b/contracts/fixtures/login.wrong-password.json index 2bc5871..6820abe 100644 --- a/contracts/fixtures/login.wrong-password.json +++ b/contracts/fixtures/login.wrong-password.json @@ -1,4 +1,4 @@ { "code": 401, - "message": "密码错误" + "message": "认证失败:密码错误" } diff --git a/docs/architecture-rules.md b/docs/architecture-rules.md index cf40a15..fa8eb2c 100644 --- a/docs/architecture-rules.md +++ b/docs/architecture-rules.md @@ -300,7 +300,7 @@ git grep -n "replicas" -- docker-compose.yml | 阶段 | 内容 | 完成的债务 | 验收口径 | |---|---|---|---| -| 阶段一 结构归位与错误分档 | 删 router 重复接口与不可达代码;错误分档(哨兵错误→404/403/400);令牌表加锁;web 死 load 清理;建立 `contracts/` 目录 | router 重复接口、web 死 load、401 判定均已修复;令牌表已加锁;`RBACService` 生产实例化点仅 1 处;not-found 哨兵→404 已落地,403/400 随错误码契约落地 | ✅ `AGENTS.md` 第 2 节自检命令全绿 | +| 阶段一 结构归位与错误分档 | 删 router 重复接口与不可达代码;错误分档(哨兵错误→404/403/400);令牌表加锁;web 死 load 清理;建立 `contracts/` 目录 | router 重复接口、web 死 load、401 判定均已修复;令牌表已加锁;`RBACService` 生产实例化点仅 1 处;not-found 哨兵→404 已落地,403/400 随错误码契约落地;全部业务错误归哨兵完成,认证失败经 `ErrUnauthenticated`→401,handler 私有映射分支清零 | ✅ `AGENTS.md` 第 2 节自检命令全绿 | | 阶段二 类型归位 | 建立 `internal/domain`,合并双 User,service/middleware/router 签名切换为 domain 类型;前端 auth 下沉共享包、影子类型清除 | 双 User 模型与影子类型层已修复;两 app 重复代码大幅减少(auth store 下沉);service 层 repository 依赖由 12 降至 11 | ✅ 依赖方向基线下降;auth store diff 为零 | | 阶段三 契约切换 | handler DTO 分离;`contracts/` + 三把锁双向锚定(替代 codegen);401 改错误码判定 | 401 文案匹配与审计字段泄漏已修复;三把锁已落地(`pnpm run contract:check`) | ✅ 影子类型归零;漂移必当天变红 | | 阶段四 横切归位与权限下发 | 中间件坍缩为 IdentityProvider 策略;组合根按域装配;RBAC 权限表迁数据源并下发;admin 胖组件拆分、users 搜索推回后端 | `RBACService` 生产实例化点仅 1 处;users 跨页补偿与 admin 分页均已修复;RBAC 迁 config.yaml 完成;permissions 下发完成;follow API 模块已补齐;IdentityProvider 中间件坍缩完成(router 依赖 repository 归零、middleware 1 处);认证工具已统一 | 权限定义全栈唯一;认证工具单轨 ✅ | diff --git a/docs/debt/README.md b/docs/debt/README.md index 5a2a254..8019148 100644 --- a/docs/debt/README.md +++ b/docs/debt/README.md @@ -13,7 +13,7 @@ 合计 20 条,与 `docs/architecture-rules.md` 第 8 节的索引表一一对应。 -> 相邻登记:契约与实现之间仍存在的映射冲突登记在 `contracts/errors.yaml` 的「实现偏差」节,该节清除后自行删除;业务错误未归哨兵的存量清单登记在本目录 `architecture.md` 第 7 条。 +> 相邻登记:契约与实现之间若再现映射冲突,登记在 `contracts/errors.yaml` 的「实现偏差」节,该节清除后自行删除;历史偏差(登录与刷新的私有 401 分支)已随 `architecture.md` 第 7 条修复一并清除。 ## 条目格式 diff --git a/docs/debt/architecture.md b/docs/debt/architecture.md index 5f1f56a..ed21127 100644 --- a/docs/debt/architecture.md +++ b/docs/debt/architecture.md @@ -47,9 +47,9 @@ ## 7. 业务错误未归哨兵导致分档退化为 500 -- **状态**:存量,只减不增。 -- **基线**:以裸 `errors.New` 或 `fmt.Errorf`(不含 `%w`)表达的业务错误共 **30 处**,分布于 **7** 个文件:`internal/service/user.go` 16、`internal/service/token.go` 4、`internal/service/category.go` 3、`internal/service/friendly_link.go` 2、`internal/service/media.go` 2、`internal/service/tag.go` 2、`internal/service/article.go` 1。`*_test.go` 与 `internal/service/errors.go` 的哨兵定义不计入。这些错误未归入 `service` 或 `domain` 哨兵,经 `HandleServiceError` 落入兜底分支,响应退化为 500「服务器内部错误」并丢失可修正提示。其中登录与刷新失败当前依赖 `handler/user.go` 的私有 `response.Unauthorized` 分支才返回 401,构成第二套映射权威,已在 `contracts/errors.yaml` 的实现偏差节登记。 +- **状态**:已修复。 +- **基线**:以裸 `errors.New` 或 `fmt.Errorf`(不含 `%w`)表达的业务错误共 **0 处**。修复前基线为 30 处、分布于 7 个文件(`internal/service/user.go` 16、`token.go` 4、`category.go` 3、`friendly_link.go` 2、`media.go` 2、`tag.go` 2、`article.go` 1);现全部改为包装哨兵:认证失败包装新增的 `service.ErrUnauthenticated`(映射 401)、业务规则校验失败包装 `service.ErrInvalidRequest`(400)、资源未找到包装 `domain.ErrUserNotFound` 与 `domain.ErrCategoryNotFound`(404)。`contracts/errors.yaml` 增补 `'401'` 分类,其「实现偏差」节随之清空删除;`handler/user.go` 的 Login 与 RefreshToken 私有 401 分支、`handler/session.go` 的 CreateSession 私有 401 分支、`handler/media.go` 的上传私有 400 分支与 `handler/user.go` 的角色转换私有 400 分支均改走 `HandleServiceError` 唯一映射点。 - **验证命令**:在 `server/` 目录下执行 `{ git grep -n 'fmt.Errorf(' -- internal/service ':(exclude)*_test.go' | grep -v '%w'; git grep -n 'errors.New(' -- internal/service ':(exclude)*_test.go' ':(exclude)internal/service/errors.go'; } | wc -l` - 应输出 30;需要单文件分布时去掉 `| wc -l` 后按路径归并核对。 -- **红线**:新增业务校验失败、认证失败与资源未找到必须包装对应哨兵(`service.ErrInvalidRequest`、`domain.ErrXxxNotFound` 等),并同步登记 `contracts/errors.yaml` 的 mapping 节与 `handler` 分档注册表;禁止以裸错误表达同类语义,禁止在模块内新增私有映射分支。 + 应输出 0;分档一致性由 `go test ./internal/handler/ -run TestErrorMappingMatchesContract -count=1` 与 `pnpm run contract:check` 锚定。 +- **红线**:新增业务校验失败、认证失败与资源未找到必须包装对应哨兵(`service.ErrUnauthenticated`、`service.ErrInvalidRequest`、`domain.ErrXxxNotFound` 等),并同步登记 `contracts/errors.yaml` 的 mapping 节与 `handler` 分档注册表;禁止以裸错误表达同类语义,禁止在模块内新增私有映射分支。 diff --git a/docs/development.md b/docs/development.md index 0aa88a0..846c745 100644 --- a/docs/development.md +++ b/docs/development.md @@ -404,7 +404,7 @@ func NewUserService(userRepo repository.UserRepository, tokenService TokenServic ```go // 错误映射唯一权威:统一经 handler/error.go 的 HandleServiceError 映射—— -// not-found 哨兵集合 → 404、ErrPermissionDenied → 403、 +// ErrUnauthenticated → 401、not-found 哨兵集合 → 404、ErrPermissionDenied → 403、 // service.ErrInvalidRequest / ErrUsernameTaken / ErrEmailTaken → 400、 // 其余 → 500 且响应体脱敏为固定文案(原始错误仅入日志)。 // 禁止在模块内新增私有映射函数产生第二套权威。 diff --git a/server/docs/api/api-specification.md b/server/docs/api/api-specification.md index 53a59c2..954fef7 100644 --- a/server/docs/api/api-specification.md +++ b/server/docs/api/api-specification.md @@ -188,8 +188,10 @@ Content-Type: application/json ### 常见错误信息 - `"请求参数错误: {具体错误信息}"`(`binding` 校验失败) -- `"用户名已存在"` / `"邮箱已存在"` / `"邮箱已被其他用户使用"` -- `"用户不存在"` +- `"用户名已存在"` / `"邮箱已被其他用户使用"` +- `"认证失败:{具体原因}"`(登录凭据、账号状态与令牌校验失败,业务码 401) +- `"请求参数不合法:{具体原因}"`(业务规则校验失败,业务码 400) +- `"用户不存在"`(资源未找到,业务码 404) - `"没有执行此操作的权限"` / `"权限不足,无法访问该资源"` - `"服务器内部错误"`(未分类错误的脱敏文案,原始错误只写入服务日志) diff --git a/server/docs/api/category-api.md b/server/docs/api/category-api.md index 6079024..5b025fd 100644 --- a/server/docs/api/category-api.md +++ b/server/docs/api/category-api.md @@ -262,9 +262,9 @@ curl -X POST http://localhost:3000/api/admin/categories/create \ | 状态码 | 说明 | |--------|------| | 400 | 请求参数错误(binding 校验或翻译语言键非法) | -| 500 | 父分类不存在 | +| 404 | 分类不存在:父分类不存在 | -> 父分类不存在的校验错误当前归入未分类错误,实际响应码为 500。 +> 父分类不存在经 `domain.ErrCategoryNotFound` 哨兵映射为 404。 ### 5. 更新分类 @@ -358,9 +358,9 @@ curl -X POST http://localhost:3000/api/admin/categories/delete \ | 状态码 | 说明 | |--------|------| | 404 | 分类不存在 | -| 500 | 分类下存在子分类,无法删除 | +| 400 | 请求参数不合法:存在子分类,无法删除 | -> 存在子分类的校验错误当前归入未分类错误,实际响应码为 500。 +> 存在子分类经 `ErrInvalidRequest` 哨兵映射为 400。 ### 7. 分类列表 diff --git a/server/docs/api/friendly-link-api.md b/server/docs/api/friendly-link-api.md index 9a3365c..c9e0da3 100644 --- a/server/docs/api/friendly-link-api.md +++ b/server/docs/api/friendly-link-api.md @@ -142,9 +142,9 @@ curl -X POST http://localhost:3000/api/admin/friendlyLinks/create \ | 状态码 | 说明 | |--------|------| | 400 | 请求参数错误(binding 校验) | -| 500 | 该站点 URL 已存在 | +| 400 | 请求参数不合法:该站点 URL 已存在 | -> URL 重复校验错误当前归入未分类错误,实际响应码为 500。 +> URL 重复经 `ErrInvalidRequest` 哨兵映射为 400。 ### 3. 更新友情链接 @@ -344,6 +344,6 @@ curl -X POST http://localhost:3000/api/friendlyLinks/apply \ | 状态码 | 说明 | |--------|------| | 400 | 请求参数错误(binding 校验) | -| 500 | 该站点已提交过申请 | +| 400 | 请求参数不合法:该站点已提交过申请,请等待审核 | -> 重复申请校验错误当前归入未分类错误,实际响应码为 500。 +> 重复申请经 `ErrInvalidRequest` 哨兵映射为 400。 diff --git a/server/docs/api/media-api.md b/server/docs/api/media-api.md index 12c810f..b505888 100644 --- a/server/docs/api/media-api.md +++ b/server/docs/api/media-api.md @@ -111,8 +111,9 @@ curl -X POST http://localhost:3000/api/media/upload \ | 状态码 | 说明 | |--------|------| -| 400 | 表单缺少 file 字段、打开或读取上传文件失败、文件大小超过限制、文件类型不在白名单、创建目录或写入文件失败、保存媒体记录失败 | +| 400 | 表单缺少 file 字段、请求参数不合法:文件大小超过限制 / 文件类型不在白名单(哨兵错误 `ErrInvalidRequest`) | | 401 | 未登录或令牌无效 | +| 500 | 打开或读取上传文件失败、创建目录或写入文件失败、保存媒体记录失败(错误原文仅落日志) | > 相同内容的文件会通过 SHA256 哈希命中已有记录,返回已存在的媒体文件(秒传去重); > 哈希比对先于类型白名单校验,白名单调整后旧文件仍可按哈希命中。 diff --git a/server/docs/api/session-api.md b/server/docs/api/session-api.md index 04c98f9..db975d5 100644 --- a/server/docs/api/session-api.md +++ b/server/docs/api/session-api.md @@ -79,13 +79,13 @@ curl -X POST http://localhost:3000/api/auth/session \ | 业务码 | 错误信息 | 说明 | |--------|----------|------| | 400 | 缺少刷新令牌 | 请求体与 Cookie 均未提供刷新令牌 | -| 401 | 令牌无效或已失效 / 令牌已过期 / 令牌类型不符 | 令牌未登记、已过期,或提交的是访问令牌 | -| 401 | 用户不存在或已失效 / 用户已被禁用 | 旋转前查库校验失败,令牌不再续期 | +| 401 | 认证失败:令牌无效或已失效 / 认证失败:令牌已过期 / 认证失败:令牌类型不符 | 令牌未登记、已过期,或提交的是访问令牌(哨兵错误 `ErrUnauthenticated`) | +| 401 | 认证失败:用户不存在或已失效 / 认证失败:用户已被禁用 | 旋转前查库校验失败,令牌不再续期 | ```json { "code": 401, - "message": "令牌无效或已失效" + "message": "认证失败:令牌无效或已失效" } ``` diff --git a/server/docs/api/tag-api.md b/server/docs/api/tag-api.md index 0972806..bcfcc47 100644 --- a/server/docs/api/tag-api.md +++ b/server/docs/api/tag-api.md @@ -237,9 +237,9 @@ curl -X POST http://localhost:3000/api/admin/tags/create \ | 状态码 | 说明 | |--------|------| | 400 | 请求参数错误(binding 校验或翻译语言键非法) | -| 500 | 标签名称已存在 | +| 400 | 请求参数不合法:标签名称已存在 | -> 名称重复校验错误当前归入未分类错误,实际响应码为 500。 +> 名称重复经 `ErrInvalidRequest` 哨兵映射为 400。 ### 5. 更新标签 @@ -281,9 +281,9 @@ curl -X POST http://localhost:3000/api/admin/tags/update \ | 状态码 | 说明 | |--------|------| | 404 | 标签不存在 | -| 500 | 标签名称已存在 | +| 400 | 请求参数不合法:标签名称已存在 | -> 名称重复校验错误当前归入未分类错误,实际响应码为 500。 +> 名称重复经 `ErrInvalidRequest` 哨兵映射为 400。 ### 6. 删除标签 diff --git a/server/docs/api/user-api.md b/server/docs/api/user-api.md index 12c16e9..56e7916 100644 --- a/server/docs/api/user-api.md +++ b/server/docs/api/user-api.md @@ -100,15 +100,15 @@ curl -X POST http://localhost:3000/api/users/login \ #### 错误响应 -登录失败全部映射为业务码 401,`message` 区分原因: +登录失败全部经 `ErrUnauthenticated` 哨兵映射为业务码 401,`message` 在哨兵文案后追加具体原因: | 状态码 | 错误信息 | 说明 | |--------|----------|------| -| 401 | 用户不存在 | 用户名与邮箱两种查找方式均未命中 | -| 401 | 密码错误 | 密码校验失败,失败计数自增 | -| 401 | 密码错误,失败次数过多,账户已被锁定,请稍后再试 | 本次失败使计数达到阈值并写入锁定 | -| 401 | 账户已被锁定,请稍后再试 | 请求落在锁定窗口内,未做密码校验 | -| 401 | 用户已被禁用 | 密码正确但账号状态非启用 | +| 401 | 认证失败:用户不存在 | 用户名与邮箱两种查找方式均未命中 | +| 401 | 认证失败:密码错误 | 密码校验失败,失败计数自增 | +| 401 | 认证失败:密码错误,失败次数过多,账户已被锁定,请稍后再试 | 本次失败使计数达到阈值并写入锁定 | +| 401 | 认证失败:账户已被锁定,请稍后再试 | 请求落在锁定窗口内,未做密码校验 | +| 401 | 认证失败:用户已被禁用 | 密码正确但账号状态非启用 | --- @@ -517,17 +517,17 @@ curl -X POST http://localhost:3000/api/auth/logout \ | 400 | 用户名已存在 | 创建用户时用户名冲突(哨兵错误 `ErrUsernameTaken`) | | 400 | 邮箱已被其他用户使用 | 更新用户时邮箱被占用(哨兵错误 `ErrEmailTaken`) | | 400 | 不能删除自己的账户 | `users/delete` 目标为当前操作者本人 | -| 400 | 超级管理员角色只能通过系统管理员设置 / 超级管理员角色不能被降级 / 无效的目标角色: x | 更新用户的角色转换校验失败 | +| 400 | 请求参数不合法:超级管理员角色只能通过系统管理员设置 / 超级管理员角色不能被降级 / 无效的目标角色 x / 无效的当前角色 x | 更新用户的角色转换校验失败(哨兵错误 `ErrInvalidRequest`) | | 400 | 请求参数不合法:批量操作的目标不能为空 / 批量操作的单次人数不能超过 100 / 批量操作不能包含自己 / 用户 N 不存在 | 批量接口的业务规则校验失败 | | 401 | 未提供认证令牌 / 无效的认证令牌 | 缺少访问令牌,或令牌未登记、已过期、类型不符 | -| 401 | 用户不存在 / 密码错误 / 用户已被禁用 / 账户已被锁定,请稍后再试 | 登录失败,`users/login` 全部错误映射为 401 | +| 401 | 认证失败:用户不存在 / 认证失败:密码错误 / 认证失败:用户已被禁用 / 认证失败:账户已被锁定,请稍后再试 | 登录失败,`users/login` 全部错误经 `ErrUnauthenticated` 映射为 401 | | 401 | 未登录 | 认证中间件通过但上下文缺少用户ID,自助接口直接返回 | | 403 | 权限不足,无法访问该资源 | 缺少接口所需 RBAC 权限 | | 403 | 权限不足,无法管理该角色的用户 / 权限不足,无法分配该角色 / 权限不足,无法删除该角色的用户 | 角色管理规则拒绝,操作者级别低于目标用户 | | 404 | 用户不存在 | `users/get`、`users/delete`、`users/profile` 等目标用户不存在 | | 500 | 服务器内部错误 | 未归入哨兵错误的业务失败与内部异常,错误原文仅落日志 | -> 现行实现中「邮箱已存在」(创建用户邮箱冲突)、「用户名已被其他用户使用」(更新用户用户名冲突)、「密码长度不能少于6位」等密码强度错误、「旧密码不正确」均未使用哨兵错误,实际统一返回 500 服务器内部错误,见各接口小节。 +> 各接口的业务失败均已归入哨兵错误经 `HandleServiceError` 统一分档,`message` 为空值、权限与业务规则的原文说明,内部异常一律脱敏为「服务器内部错误」。 ### 错误响应示例 @@ -703,7 +703,7 @@ curl -X POST http://localhost:3000/api/users/profile/update \ | 状态码 | 说明 | |--------|------| | 401 | 未提供或无效的认证令牌 | -| 500 | 旧密码不正确或新密码强度不足:实现未使用哨兵错误,错误原文不进入响应体,统一返回「服务器内部错误」 | +| 400 | 请求参数不合法:旧密码不正确 / 密码长度不能少于 6 位等强度校验原因(哨兵错误 `ErrInvalidRequest`) | --- diff --git a/server/internal/handler/README.md b/server/internal/handler/README.md index a418d92..263f872 100644 --- a/server/internal/handler/README.md +++ b/server/internal/handler/README.md @@ -6,7 +6,7 @@ HTTP 协议层:参数绑定与校验、调用 service、以统一格式输出 - 各模块的处理器接口声明在 handler 包内,命名统一为 `XxxHandlerInterface`(用户模块为 `UserHandlerInterface`),经 `router.Dependencies` 由组合根注入;禁止包内私自实例化 service。 - 请求参数经 `c.ShouldBindJSON` 与 DTO 的 `binding` tag 完成必填、长度、格式、枚举校验,校验失败返回 400;业务规则由 service 校验。 -- service 返回的错误统一交 `HandleServiceError`(`error.go`)分档:哨兵错误映射 404/403/400,未分类错误脱敏为「服务器内部错误」。禁止在 handler 内直接 `response.InternalError(c, err.Error())`,也禁止另起私有映射分支;新增 not-found 哨兵须同步扩展该映射集合与 `contracts/errors.yaml`。 +- service 返回的错误统一交 `HandleServiceError`(`error.go`)分档:哨兵错误映射 401/404/403/400,未分类错误脱敏为「服务器内部错误」。禁止在 handler 内直接 `response.InternalError(c, err.Error())`,也禁止另起私有映射分支;新增哨兵须同步扩展该映射集合与 `contracts/errors.yaml`。 - DTO 与领域类型取自 `internal/domain`;**禁止直接序列化 `internal/model` 实体**(公开端点直出实体是已登记债务,见 `docs/debt/security-runtime.md` 第 1 条,触碰时应改为窄化 DTO 或字段白名单)。 - 路由注册在 `internal/router/.go`,业务接口一律 `POST`;`GET` 仅用于健康探针(`internal/router/health.go`)。 - 请求语言经 `getRequestLanguage`(`common.go`)读取 language 中间件写入上下文的语言标识。 diff --git a/server/internal/handler/error.go b/server/internal/handler/error.go index 8ce4b28..b3ee4ba 100644 --- a/server/internal/handler/error.go +++ b/server/internal/handler/error.go @@ -31,6 +31,7 @@ type serviceErrorMapping struct { // 新增哨兵错误必须同时登记本表与 contracts/errors.yaml 的 mapping 节, // 任一侧缺失由 TestErrorMappingMatchesContract 拦截,禁止在模块内另起私有映射分支。 var serviceErrorMappings = []serviceErrorMapping{ + {Name: "service.ErrUnauthenticated", Err: service.ErrUnauthenticated, Code: response.CodeAuth}, {Name: "service.ErrPermissionDenied", Err: service.ErrPermissionDenied, Code: response.CodeForbid}, {Name: "domain.ErrArticleNotFound", Err: domain.ErrArticleNotFound, Code: response.CodeNotFound}, @@ -52,7 +53,7 @@ var serviceErrorMappings = []serviceErrorMapping{ } // HandleServiceError 将 service 层返回的错误按注册表映射为对应的 HTTP 响应。 -// 命中哨兵错误时分档返回 403 / 404 / 400;未命中时归入内部错误, +// 命中哨兵错误时分档返回 401 / 403 / 404 / 400;未命中时归入内部错误, // 响应固定为脱敏文案,原始错误只写日志,避免内部细节经响应体泄漏。 // 注册表由 contracts/errors.yaml 的 mapping 节锚定,契约变更须先改契约再改表。 func HandleServiceError(c *gin.Context, err error) { diff --git a/server/internal/handler/error_test.go b/server/internal/handler/error_test.go index 2f1c20d..1e54c30 100644 --- a/server/internal/handler/error_test.go +++ b/server/internal/handler/error_test.go @@ -42,6 +42,22 @@ func TestHandleServiceError(t *testing.T) { }) } + t.Run("认证失败返回401", func(t *testing.T) { + recorder := httptest.NewRecorder() + ctx, _ := gin.CreateTestContext(recorder) + HandleServiceError(ctx, service.ErrUnauthenticated) + + assertResponseCode(t, recorder, 401) + }) + + t.Run("包装后的认证失败经errors.Is识别返回401", func(t *testing.T) { + recorder := httptest.NewRecorder() + ctx, _ := gin.CreateTestContext(recorder) + HandleServiceError(ctx, fmt.Errorf("%w:密码错误", service.ErrUnauthenticated)) + + assertResponseCode(t, recorder, 401) + }) + t.Run("业务校验失败返回400", func(t *testing.T) { recorder := httptest.NewRecorder() ctx, _ := gin.CreateTestContext(recorder) diff --git a/server/internal/handler/login_fixture_test.go b/server/internal/handler/login_fixture_test.go index c5e80b9..94e3dd2 100644 --- a/server/internal/handler/login_fixture_test.go +++ b/server/internal/handler/login_fixture_test.go @@ -3,7 +3,7 @@ package handler import ( "bytes" "encoding/json" - "errors" + "fmt" "net/http" "net/http/httptest" "os" @@ -57,8 +57,9 @@ func assertResponseMatchesFixture(t *testing.T, recorder *httptest.ResponseRecor func TestLoginWrongPasswordMatchesFixture(t *testing.T) { gin.SetMode(gin.TestMode) - handler := NewUserHandler(&fakeLoginUserService{loginErr: errors.New("密码错误")}, - testSessionCookieConfig()) + handler := NewUserHandler(&fakeLoginUserService{ + loginErr: fmt.Errorf("%w:密码错误", service.ErrUnauthenticated), + }, testSessionCookieConfig()) recorder := httptest.NewRecorder() ctx, _ := gin.CreateTestContext(recorder) diff --git a/server/internal/handler/media.go b/server/internal/handler/media.go index f9f5bf2..f7817ef 100644 --- a/server/internal/handler/media.go +++ b/server/internal/handler/media.go @@ -58,7 +58,7 @@ func (h *MediaHandler) UploadFile(c *gin.Context) { c.ClientIP(), ) if err != nil { - response.BadRequest(c, err.Error()) + HandleServiceError(c, err) return } diff --git a/server/internal/handler/session.go b/server/internal/handler/session.go index 28ccd49..b69fe8e 100644 --- a/server/internal/handler/session.go +++ b/server/internal/handler/session.go @@ -48,7 +48,7 @@ func (h *UserHandler) CreateSession(c *gin.Context) { tokenPair, err := h.userService.RefreshToken(refreshToken) if err != nil { - response.Unauthorized(c, err.Error()) + HandleServiceError(c, err) return } diff --git a/server/internal/handler/session_test.go b/server/internal/handler/session_test.go index 9870b89..f84bdda 100644 --- a/server/internal/handler/session_test.go +++ b/server/internal/handler/session_test.go @@ -2,7 +2,7 @@ package handler import ( "encoding/json" - "errors" + "fmt" "net/http" "net/http/httptest" "strings" @@ -211,7 +211,9 @@ func TestCreateSessionWithoutToken(t *testing.T) { // TestCreateSessionWithInvalidToken 刷新令牌无效时返回业务码 401 且不写入 Cookie。 func TestCreateSessionWithInvalidToken(t *testing.T) { - fake := &sessionUserService{refreshErr: errors.New("刷新令牌验证失败")} + fake := &sessionUserService{ + refreshErr: fmt.Errorf("%w:刷新令牌验证失败", service.ErrUnauthenticated), + } handler := newSessionTestHandler(fake) recorder := performSessionRequest(handler, `{"refreshToken":"revoked-token"}`) diff --git a/server/internal/handler/user.go b/server/internal/handler/user.go index 7f4b1c9..e851d04 100644 --- a/server/internal/handler/user.go +++ b/server/internal/handler/user.go @@ -107,7 +107,7 @@ func (h *UserHandler) UpdateUser(c *gin.Context) { // 如果要修改角色,需要验证角色转换 if req.Role != "" && req.Role != targetUser.Role { if err := h.userService.ValidateRoleTransition(targetUser.Role, req.Role); err != nil { - response.BadRequest(c, err.Error()) + HandleServiceError(c, err) return } @@ -347,7 +347,7 @@ func (h *UserHandler) Login(c *gin.Context) { loginResp, err := h.userService.Login(req.Username, req.Password) if err != nil { - response.Unauthorized(c, err.Error()) + HandleServiceError(c, err) return } @@ -376,7 +376,7 @@ func (h *UserHandler) RefreshToken(c *gin.Context) { tokenPair, err := h.userService.RefreshToken(req.RefreshToken) if err != nil { - response.Unauthorized(c, err.Error()) + HandleServiceError(c, err) return } diff --git a/server/internal/service/README.md b/server/internal/service/README.md index 595986d..fda965a 100644 --- a/server/internal/service/README.md +++ b/server/internal/service/README.md @@ -6,13 +6,13 @@ - 各业务域接口声明在 service 包内,命名统一为 `XxxServiceInterface`(存量例外 `UserService`、`RBACService`),各层只依赖接口。 - 依赖一律经构造函数注入,组合根为 `cmd/myblog/`(`main.go` 管生命周期、`deps.go` 按域装配);可选依赖用选项函数注入,如 `NewUserService(userRepo, tokenService, rbacService, WithLoginLockoutPolicy(...))`。 -- 业务错误集中在 `errors.go` 的哨兵错误(`ErrPermissionDenied`、`ErrInvalidRequest`、`ErrUsernameTaken`、`ErrEmailTaken`),handler 经 `errors.Is` 分档映射,不得另起裸 `errors.New` 表达同类语义。 +- 业务错误集中在 `errors.go` 的哨兵错误(`ErrUnauthenticated`、`ErrPermissionDenied`、`ErrInvalidRequest`、`ErrUsernameTaken`、`ErrEmailTaken`)与 `domain` 的 not-found 哨兵,handler 经 `errors.Is` 分档映射,不得另起裸 `errors.New` 表达同类语义;业务侧原因以 `fmt.Errorf("%w:<原因>", 哨兵)` 追加。 - 多段写库在 repository 的事务方法内完成,service 不自行拼装事务。 - 权限判定经 `RBACService`,权限映射的生产环境唯一权威为 `configs/config.yaml` 的 `rbac` 节,由 `LoadRBACConfig` 加载(见 `cmd/myblog/deps.go`)。 ## 认证与密码 -- 登录先按用户名查找,未命中回退邮箱;锁定检查先于密码校验;失败计数原子自增,达到 `security.login_lockout` 阈值写入 `locked_until`,登录成功清零。 +- 登录先按用户名查找,未命中回退邮箱;锁定检查先于密码校验;失败计数原子自增,达到 `security.login_lockout` 阈值写入 `locked_until`,登录成功清零。登录、令牌校验与刷新失败统一包装 `ErrUnauthenticated` 供 handler 分档为 401。 - 密码使用 bcrypt,成本常量 `BcryptCost = 12`;强度校验 `ValidatePasswordStrength`(`password.go`)要求 6 至 100 位、同时含字母与数字、拒绝常见弱密码,校验失败统一包装 `ErrInvalidRequest` 供 handler 分档为 400。 - 刷新令牌换取新令牌对前查库校验用户存在且状态正常;改密成功后经 `RevokeUserTokens` 撤销该用户全部既有令牌。 diff --git a/server/internal/service/article.go b/server/internal/service/article.go index 60f2bf8..cf64ca1 100644 --- a/server/internal/service/article.go +++ b/server/internal/service/article.go @@ -1,8 +1,8 @@ package service import ( - "errors" "fmt" + "regexp" "time" "unicode/utf8" @@ -177,7 +177,7 @@ func (s *ArticleService) CreateArticle(req *CreateArticleRequest, authorID uint) // 获取用户信息以检查角色权限 user, err := s.userRepo.GetByID(authorID) if err != nil { - return nil, errors.New("用户不存在") + return nil, domain.ErrUserNotFound } // 权限检查 diff --git a/server/internal/service/category.go b/server/internal/service/category.go index 93ebfc3..a3008d6 100644 --- a/server/internal/service/category.go +++ b/server/internal/service/category.go @@ -2,7 +2,6 @@ package service import ( - "errors" "fmt" "MyBlog/internal/domain" @@ -276,7 +275,7 @@ func (s *CategoryService) DeleteCategory(id uint, operatorID uint) error { return err } if childCount > 0 { - return errors.New("存在子分类,无法删除") + return fmt.Errorf("%w:存在子分类,无法删除", ErrInvalidRequest) } return s.categoryRepo.Delete(id) @@ -339,7 +338,7 @@ func (s *CategoryService) resolveParent(parentID *uint) (*model.Category, error) parent, err := s.categoryRepo.GetByID(*parentID) if err != nil { - return nil, errors.New("父分类不存在") + return nil, fmt.Errorf("%w:父分类不存在", domain.ErrCategoryNotFound) } return parent, nil } @@ -350,7 +349,7 @@ func (s *CategoryService) updateCategoryPath(category *model.Category) error { if category.ParentID != nil { parent, err := s.categoryRepo.GetByID(*category.ParentID) if err != nil { - return errors.New("父分类不存在") + return fmt.Errorf("%w:父分类不存在", domain.ErrCategoryNotFound) } path = parent.Path + fmt.Sprintf("/%d", category.ID) } diff --git a/server/internal/service/category_test.go b/server/internal/service/category_test.go index f2c8b64..20d922f 100644 --- a/server/internal/service/category_test.go +++ b/server/internal/service/category_test.go @@ -147,6 +147,27 @@ func TestDeleteCategoryWithChildren(t *testing.T) { if err == nil { t.Fatal("存在子分类时删除应返回错误") } + // 子分类冲突属业务校验失败,handler 据此分档为 400 而非内部错误。 + if !errors.Is(err, ErrInvalidRequest) { + t.Errorf("存在子分类应包装 ErrInvalidRequest,实际为 %v", err) + } +} + +// TestCreateCategoryWithMissingParent 父分类不存在时归入 not-found 哨兵, +// 避免降级为内部错误而丢失可修正提示。 +func TestCreateCategoryWithMissingParent(t *testing.T) { + missingParentID := uint(404) + repo := &fakeCategoryRepo{ + getByID: func(id uint) (*model.Category, error) { + return nil, domain.ErrCategoryNotFound + }, + } + svc := NewCategoryService(repo) + + _, err := svc.CreateCategory(&CreateCategoryRequest{Name: "后端开发", ParentID: &missingParentID}, 1) + if !errors.Is(err, domain.ErrCategoryNotFound) { + t.Errorf("父分类不存在应返回 ErrCategoryNotFound,实际为 %v", err) + } } // TestDeleteCategoryNotFound 验证删除不存在的分类返回哨兵错误。 diff --git a/server/internal/service/errors.go b/server/internal/service/errors.go index 2be716f..5614743 100644 --- a/server/internal/service/errors.go +++ b/server/internal/service/errors.go @@ -7,6 +7,11 @@ import "errors" // 业务侧的具体动作经 fmt.Errorf 以 %w 包装本错误追加,禁止再以裸 errors.New 产生权限错误。 var ErrPermissionDenied = errors.New("没有执行此操作的权限") +// ErrUnauthenticated 认证失败的哨兵错误,handler 层经 errors.Is 识别后映射为 401。 +// 登录凭据错误、账号状态异常与令牌校验失败统一包装本错误, +// 使认证失败只经 handler 的唯一映射点分档,不再由各入口的私有分支产出 401。 +var ErrUnauthenticated = errors.New("认证失败") + // ErrInvalidRequest 业务规则校验失败的哨兵错误,handler 层经 errors.Is 识别后映射为 400。 // binding 层无法覆盖的业务校验失败统一包装本错误,避免散落的私有映射分支。 var ErrInvalidRequest = errors.New("请求参数不合法") diff --git a/server/internal/service/friendly_link.go b/server/internal/service/friendly_link.go index 071e3b3..6ceb8e9 100644 --- a/server/internal/service/friendly_link.go +++ b/server/internal/service/friendly_link.go @@ -2,7 +2,6 @@ package service import ( - "errors" "fmt" "MyBlog/internal/model" @@ -129,7 +128,7 @@ func NewFriendlyLinkService(linkRepo repository.FriendlyLinkRepositoryInterface) func (s *FriendlyLinkService) CreateLink(req *CreateFriendlyLinkRequest) (*model.FriendlyLink, error) { // 校验站点 URL 唯一。 if existing, err := s.linkRepo.GetByURL(req.URL); err == nil && existing != nil { - return nil, errors.New("该站点 URL 已存在") + return nil, fmt.Errorf("%w:该站点 URL 已存在", ErrInvalidRequest) } sortOrder := 0 @@ -163,7 +162,7 @@ func (s *FriendlyLinkService) CreateLink(req *CreateFriendlyLinkRequest) (*model func (s *FriendlyLinkService) ApplyLink(req *ApplyFriendlyLinkRequest) (*FriendlyLinkPublic, error) { // 同一站点 URL 不论处于何种状态均不重复申请。 if existing, err := s.linkRepo.GetByURL(req.URL); err == nil && existing != nil { - return nil, errors.New("该站点已提交过申请,请等待审核") + return nil, fmt.Errorf("%w:该站点已提交过申请,请等待审核", ErrInvalidRequest) } link := &model.FriendlyLink{ diff --git a/server/internal/service/friendly_link_test.go b/server/internal/service/friendly_link_test.go index 121d74e..8582ae8 100644 --- a/server/internal/service/friendly_link_test.go +++ b/server/internal/service/friendly_link_test.go @@ -2,6 +2,7 @@ package service import ( "encoding/json" + "errors" "strings" "testing" @@ -110,6 +111,10 @@ func TestCreateLinkDuplicateURL(t *testing.T) { if err == nil { t.Fatal("重复 URL 创建应返回错误") } + // URL 冲突属业务校验失败,handler 据此分档为 400 而非内部错误。 + if !errors.Is(err, ErrInvalidRequest) { + t.Errorf("重复 URL 应包装 ErrInvalidRequest,实际为 %v", err) + } } // TestApproveLinkStatus 验证审核通过更新状态为 active。 @@ -178,6 +183,10 @@ func TestApplyLinkRejectsDuplicateURL(t *testing.T) { if err == nil { t.Fatal("重复申请应返回错误") } + // 重复申请属业务校验失败,handler 据此分档为 400 而非内部错误。 + if !errors.Is(err, ErrInvalidRequest) { + t.Errorf("重复申请应包装 ErrInvalidRequest,实际为 %v", err) + } } // TestListVisibleLinksHidesContactFields 验证公开友链列表不含联系邮箱与管理员备注。 diff --git a/server/internal/service/media.go b/server/internal/service/media.go index 7ec925d..4d1876f 100644 --- a/server/internal/service/media.go +++ b/server/internal/service/media.go @@ -82,7 +82,7 @@ func (s *MediaService) UploadFile(filename string, reader io.Reader, size int64, // 校验文件大小是否超限。 maxSize := int64(s.cfg.Media.MaxSizeMB) * 1024 * 1024 if maxSize > 0 && size > maxSize { - return nil, fmt.Errorf("文件大小超过限制 %dMB", s.cfg.Media.MaxSizeMB) + return nil, fmt.Errorf("%w:文件大小超过限制 %dMB", ErrInvalidRequest, s.cfg.Media.MaxSizeMB) } // 读取文件内容并计算哈希。 @@ -228,7 +228,7 @@ func (s *MediaService) validateUploadType(mimeType string) error { return nil } } - return fmt.Errorf("不支持的文件类型 %s", mimeType) + return fmt.Errorf("%w:不支持的文件类型 %s", ErrInvalidRequest, mimeType) } // storedExtensionForMime 从白名单映射推导存储扩展名,映射缺失时回退原始扩展名。 diff --git a/server/internal/service/media_test.go b/server/internal/service/media_test.go index 98dad9a..1b54ac8 100644 --- a/server/internal/service/media_test.go +++ b/server/internal/service/media_test.go @@ -87,6 +87,10 @@ func TestUploadFileOversize(t *testing.T) { if !strings.Contains(err.Error(), "大小超过限制") { t.Errorf("错误信息不符合预期: %v", err) } + // 超限属业务校验失败,handler 据此分档为 400 而非内部错误。 + if !errors.Is(err, ErrInvalidRequest) { + t.Errorf("超限上传应包装 ErrInvalidRequest,实际为 %v", err) + } } // TestUploadFileDeduplicates 验证相同内容文件通过哈希去重复用已有记录。 @@ -199,6 +203,10 @@ func TestUploadFileRejectsDisallowedType(t *testing.T) { if !strings.Contains(err.Error(), "不支持的文件类型") { t.Errorf("错误信息不符合预期: %v", err) } + // 类型不在白名单属业务校验失败,handler 据此分档为 400 而非内部错误。 + if !errors.Is(err, ErrInvalidRequest) { + t.Errorf("非白名单类型应包装 ErrInvalidRequest,实际为 %v", err) + } if len(repo.media) != 0 { t.Error("被拒绝的文件不应落库") } diff --git a/server/internal/service/tag.go b/server/internal/service/tag.go index a518947..8e55da1 100644 --- a/server/internal/service/tag.go +++ b/server/internal/service/tag.go @@ -95,7 +95,7 @@ func NewTagService(tagRepo repository.TagRepositoryInterface, options ...TagServ func (s *TagService) CreateTag(req *CreateTagRequest, operatorID uint) (*model.Tag, error) { // 校验标签名称唯一。 if _, err := s.tagRepo.GetByName(req.Name); err == nil { - return nil, fmt.Errorf("标签名称已存在") + return nil, fmt.Errorf("%w:标签名称已存在", ErrInvalidRequest) } // 默认状态为启用。 @@ -150,7 +150,7 @@ func (s *TagService) UpdateTag(req *UpdateTagRequest, operatorID uint) (*model.T // 名称变更时校验唯一性。 if req.Name != nil && *req.Name != tag.Name { if existing, err := s.tagRepo.GetByName(*req.Name); err == nil && existing.ID != req.ID { - return nil, fmt.Errorf("标签名称已存在") + return nil, fmt.Errorf("%w:标签名称已存在", ErrInvalidRequest) } } diff --git a/server/internal/service/tag_test.go b/server/internal/service/tag_test.go index 29a1582..13ddb68 100644 --- a/server/internal/service/tag_test.go +++ b/server/internal/service/tag_test.go @@ -1,6 +1,7 @@ package service import ( + "errors" "testing" "MyBlog/internal/domain" @@ -71,6 +72,10 @@ func TestCreateTagUniqueName(t *testing.T) { if err == nil { t.Fatal("重复标签名称应返回错误") } + // 名称冲突属业务校验失败,handler 据此分档为 400 而非内部错误。 + if !errors.Is(err, ErrInvalidRequest) { + t.Errorf("重复标签名称应包装 ErrInvalidRequest,实际为 %v", err) + } } // TestCreateTagDefaults 验证创建标签时默认状态启用、颜色为默认值。 diff --git a/server/internal/service/token.go b/server/internal/service/token.go index a563c24..ff7ddce 100644 --- a/server/internal/service/token.go +++ b/server/internal/service/token.go @@ -155,7 +155,7 @@ func (s *tokenService) ValidateRefreshToken(tokenString string) (*TokenIdentity, // validateToken 查表校验令牌并核对类型,访问令牌与刷新令牌不可互换使用。 func (s *tokenService) validateToken(tokenString string, tokenType TokenType) (*TokenIdentity, error) { if tokenString == "" { - return nil, fmt.Errorf("令牌为空") + return nil, fmt.Errorf("%w:令牌为空", ErrUnauthenticated) } s.mu.RLock() @@ -163,13 +163,13 @@ func (s *tokenService) validateToken(tokenString string, tokenType TokenType) (* s.mu.RUnlock() if !exists { - return nil, fmt.Errorf("令牌无效或已失效") + return nil, fmt.Errorf("%w:令牌无效或已失效", ErrUnauthenticated) } if record.tokenType != tokenType { - return nil, fmt.Errorf("令牌类型不符") + return nil, fmt.Errorf("%w:令牌类型不符", ErrUnauthenticated) } if !record.expiresAt.After(time.Now()) { - return nil, fmt.Errorf("令牌已过期") + return nil, fmt.Errorf("%w:令牌已过期", ErrUnauthenticated) } return &TokenIdentity{UserID: record.userID, ExpiresAt: record.expiresAt}, nil diff --git a/server/internal/service/token_test.go b/server/internal/service/token_test.go index 4a0d1a1..7e38fa3 100644 --- a/server/internal/service/token_test.go +++ b/server/internal/service/token_test.go @@ -1,6 +1,7 @@ package service import ( + "errors" "strings" "sync" "testing" @@ -79,6 +80,8 @@ func TestForgedTokenRejected(t *testing.T) { for _, forged := range forgedTokens { if _, err := svc.ValidateAccessToken(forged); err == nil { t.Errorf("自造令牌通过了访问令牌校验: %q", forged) + } else if !errors.Is(err, ErrUnauthenticated) { + t.Errorf("令牌校验失败应包装 ErrUnauthenticated,实际为 %v", err) } if _, err := svc.ValidateRefreshToken(forged); err == nil { t.Errorf("自造令牌通过了刷新令牌校验: %q", forged) @@ -97,6 +100,8 @@ func TestTokenTypeNotInterchangeable(t *testing.T) { if _, err := svc.ValidateRefreshToken(pair.AccessToken); err == nil { t.Error("访问令牌通过了刷新令牌校验,令牌类型未被区分") + } else if !errors.Is(err, ErrUnauthenticated) { + t.Errorf("类型不符应包装 ErrUnauthenticated,实际为 %v", err) } if _, err := svc.ValidateAccessToken(pair.RefreshToken); err == nil { t.Error("刷新令牌通过了访问令牌校验,令牌类型未被区分") diff --git a/server/internal/service/user.go b/server/internal/service/user.go index c523254..acfa70a 100644 --- a/server/internal/service/user.go +++ b/server/internal/service/user.go @@ -164,7 +164,7 @@ func (s *userService) CreateUser(req *domain.CreateUserRequest) (*domain.User, e // 验证角色是否有效 if !s.rbacService.IsValidRole(user.Role) { - return nil, fmt.Errorf("无效的用户角色: %s", user.Role) + return nil, fmt.Errorf("%w:无效的用户角色 %s", ErrInvalidRequest, user.Role) } // 创建用户 @@ -217,7 +217,7 @@ func (s *userService) UpdateUser(req *domain.UpdateUserRequest) (*domain.User, e // 验证角色是否有效 if !s.rbacService.IsValidRole(existingUser.Role) { - return nil, fmt.Errorf("无效的用户角色: %s", existingUser.Role) + return nil, fmt.Errorf("%w:无效的用户角色 %s", ErrInvalidRequest, existingUser.Role) } // 如果提供了新密码,则更新密码 @@ -403,7 +403,7 @@ func (s *userService) ChangePassword(userID uint, req *ChangePasswordRequest) er } if !s.verifyPassword(req.OldPassword, user.Password) { - return fmt.Errorf("旧密码不正确") + return fmt.Errorf("%w:旧密码不正确", ErrInvalidRequest) } if err := ValidatePasswordStrength(req.NewPassword); err != nil { @@ -448,13 +448,13 @@ func (s *userService) Login(username, password string) (*LoginResponse, error) { // 如果用户名未找到,尝试通过邮箱查找 user, err = s.userRepo.GetByEmail(username) if err != nil { - return nil, fmt.Errorf("用户不存在") + return nil, fmt.Errorf("%w:用户不存在", ErrUnauthenticated) } } // 锁定检查先于密码校验,锁定期间即使密码正确也拒绝,阻断持续爆破。 if user.IsLocked() { - return nil, fmt.Errorf("账户已被锁定,请稍后再试") + return nil, fmt.Errorf("%w:账户已被锁定,请稍后再试", ErrUnauthenticated) } // 验证密码 @@ -464,7 +464,7 @@ func (s *userService) Login(username, password string) (*LoginResponse, error) { // 检查用户状态 if user.Status != model.UserStatusActive { - return nil, fmt.Errorf("用户已被禁用") + return nil, fmt.Errorf("%w:用户已被禁用", ErrUnauthenticated) } // 登录成功后清零失败计数并解除历史锁定标记。 @@ -491,7 +491,7 @@ func (s *userService) Login(username, password string) (*LoginResponse, error) { // 落库失败不掩盖原始的密码错误结果,仅代表本次计数未持久化。 func (s *userService) recordLoginFailure(user *domain.User) error { if err := s.userRepo.IncrementLoginFailures(user.ID); err != nil { - return fmt.Errorf("密码错误") + return fmt.Errorf("%w:密码错误", ErrUnauthenticated) } // 阈值判断由条件更新自身完成,返回落库成功标记用于选择响应文案。 @@ -499,16 +499,16 @@ func (s *userService) recordLoginFailure(user *domain.User) error { lockedUntil := time.Now().Add(s.lockoutPolicy.LockDuration) locked, err := s.userRepo.LockUserAfterFailures(user.ID, s.lockoutPolicy.MaxFailedLogins, lockedUntil) if err != nil { - return fmt.Errorf("密码错误") + return fmt.Errorf("%w:密码错误", ErrUnauthenticated) } if locked { // 同步内存实体,保证登录失败响应与库中状态一致,不写回其他字段。 user.LockedUntil = &lockedUntil - return fmt.Errorf("密码错误,失败次数过多,账户已被锁定,请稍后再试") + return fmt.Errorf("%w:密码错误,失败次数过多,账户已被锁定,请稍后再试", ErrUnauthenticated) } } - return fmt.Errorf("密码错误") + return fmt.Errorf("%w:密码错误", ErrUnauthenticated) } // resetLoginFailure 登录成功后清零失败计数并清除锁定截止时间。 @@ -541,11 +541,11 @@ func (s *userService) RefreshToken(refreshToken string) (*TokenPair, error) { user, err := s.userRepo.GetByID(identity.UserID) if err != nil { // 不透出仓储层原始错误,避免数据库细节经响应体泄漏。 - return nil, fmt.Errorf("用户不存在或已失效") + return nil, fmt.Errorf("%w:用户不存在或已失效", ErrUnauthenticated) } if user.Status != model.UserStatusActive { - return nil, fmt.Errorf("用户已被禁用") + return nil, fmt.Errorf("%w:用户已被禁用", ErrUnauthenticated) } return s.tokenService.RefreshAccessToken(refreshToken) @@ -574,22 +574,22 @@ func (s *userService) CanUserManageRole(managerRole, targetRole string) bool { func (s *userService) ValidateRoleTransition(currentRole, newRole string) error { // 检查新角色是否有效 if !s.rbacService.IsValidRole(newRole) { - return fmt.Errorf("无效的目标角色: %s", newRole) + return fmt.Errorf("%w:无效的目标角色 %s", ErrInvalidRequest, newRole) } // 检查当前角色是否有效 if !s.rbacService.IsValidRole(currentRole) { - return fmt.Errorf("无效的当前角色: %s", currentRole) + return fmt.Errorf("%w:无效的当前角色 %s", ErrInvalidRequest, currentRole) } // 超级管理员角色只能由系统设置,不能通过API变更 if newRole == string(RoleSuperAdmin) { - return fmt.Errorf("超级管理员角色只能通过系统管理员设置") + return fmt.Errorf("%w:超级管理员角色只能通过系统管理员设置", ErrInvalidRequest) } // 从超级管理员降级需要特殊处理 if currentRole == string(RoleSuperAdmin) { - return fmt.Errorf("超级管理员角色不能被降级") + return fmt.Errorf("%w:超级管理员角色不能被降级", ErrInvalidRequest) } return nil diff --git a/server/internal/service/user_login_test.go b/server/internal/service/user_login_test.go index 193b15e..32edcfc 100644 --- a/server/internal/service/user_login_test.go +++ b/server/internal/service/user_login_test.go @@ -145,6 +145,10 @@ func TestLoginUserNotFound(t *testing.T) { if err == nil || !strings.Contains(err.Error(), "用户不存在") { t.Errorf("应返回用户不存在,实际为 %v", err) } + // 登录失败必须归属认证哨兵,handler 据此分档为 401 而非内部错误。 + if !errors.Is(err, ErrUnauthenticated) { + t.Errorf("登录失败应包装 ErrUnauthenticated,实际为 %v", err) + } } // TestLoginWrongPassword 验证密码错误时返回密码错误。 @@ -159,6 +163,10 @@ func TestLoginWrongPassword(t *testing.T) { if err == nil || !strings.Contains(err.Error(), "密码错误") { t.Errorf("应返回密码错误,实际为 %v", err) } + // 登录失败必须归属认证哨兵,handler 据此分档为 401 而非内部错误。 + if !errors.Is(err, ErrUnauthenticated) { + t.Errorf("登录失败应包装 ErrUnauthenticated,实际为 %v", err) + } // 失败计数必须经原子自增路径落库,未达到阈值时不应写锁定。 if repo.failureCalls != 1 { @@ -241,6 +249,10 @@ func TestLoginDisabledUser(t *testing.T) { if err == nil || !strings.Contains(err.Error(), "禁用") { t.Errorf("禁用用户应被拒绝,实际为 %v", err) } + // 账号状态异常同属认证失败,不得退化为内部错误。 + if !errors.Is(err, ErrUnauthenticated) { + t.Errorf("禁用用户登录应包装 ErrUnauthenticated,实际为 %v", err) + } } // TestLoginFallsBackToEmail 验证用户名未命中时回退到邮箱查找。 diff --git a/server/internal/service/user_profile_test.go b/server/internal/service/user_profile_test.go index abd6d98..1f923f0 100644 --- a/server/internal/service/user_profile_test.go +++ b/server/internal/service/user_profile_test.go @@ -1,6 +1,7 @@ package service import ( + "errors" "strings" "testing" @@ -82,4 +83,11 @@ func TestChangePasswordRejectsWrongOldPassword(t *testing.T) { if err == nil || !strings.Contains(err.Error(), "旧密码不正确") { t.Errorf("旧密码错误应被拒绝, 实际为 %v", err) } + // 归属业务校验哨兵而非认证哨兵,避免客户端把改密重试当作会话失效处理。 + if !errors.Is(err, ErrInvalidRequest) { + t.Errorf("旧密码错误应包装 ErrInvalidRequest,实际为 %v", err) + } + if errors.Is(err, ErrUnauthenticated) { + t.Errorf("旧密码错误不应包装 ErrUnauthenticated,实际为 %v", err) + } } diff --git a/server/internal/service/user_refresh_test.go b/server/internal/service/user_refresh_test.go index aa0cc7b..5bc1aed 100644 --- a/server/internal/service/user_refresh_test.go +++ b/server/internal/service/user_refresh_test.go @@ -51,6 +51,10 @@ func TestRefreshTokenRejectsDisabledUser(t *testing.T) { if err == nil || !strings.Contains(err.Error(), "禁用") { t.Errorf("禁用用户的刷新请求应被拒绝,实际为 %v", err) } + // 刷新失败同属认证失败,handler 据此分档为 401 而非内部错误。 + if !errors.Is(err, ErrUnauthenticated) { + t.Errorf("禁用用户刷新应包装 ErrUnauthenticated,实际为 %v", err) + } if tokenFake.refreshCalled { t.Error("状态校验失败时不应执行令牌旋转") } @@ -67,6 +71,10 @@ func TestRefreshTokenRejectsMissingUser(t *testing.T) { if err == nil { t.Fatal("用户不存在时刷新应被拒绝") } + // 令牌指向的用户已失效时按认证失败返回,不透出仓储层错误。 + if !errors.Is(err, ErrUnauthenticated) { + t.Errorf("用户失效应包装 ErrUnauthenticated,实际为 %v", err) + } if tokenFake.refreshCalled { t.Error("用户不存在时不应执行令牌旋转") } From 380079e0763696de3f7884190ad543940415ee29 Mon Sep 17 00:00:00 2001 From: idleRain Date: Tue, 13 Oct 2026 15:20:12 +0800 Subject: [PATCH 2/5] =?UTF-8?q?refactor(admin):=20=E6=8B=86=E5=88=86=207?= =?UTF-8?q?=20=E4=B8=AA=E7=AE=A1=E7=90=86=E9=A1=B5=E8=83=96=E7=BB=84?= =?UTF-8?q?=E4=BB=B6=E5=B9=B6=E5=BD=92=E4=BD=8D=E5=8F=96=E6=95=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - dicts/tags/links/users/comments/media/categories 改为 +page.ts 的 load + 页面状态模块 + 纯渲染页面 - 行数口径由 7 个超过 300 行的页面降至 0;剩余 6 个非胖页面的 onMount 取数仍为存量 - 新增 7 个页面状态模块与配套单测,admin 单测由 1 个文件 19 例增至 9 个文件 146 例 - 修复字典页类型列表的按钮嵌套:选择区与操作区改为并列元素,操作按钮补 size=icon 与含上下文 aria-label,选择区补焦点环与 aria-current - 字典页与评论页表格按断点折叠次要列,卡片头部允许换行;加载态与空态统一改用 $ui/spinner 与 $ui/empty - 常量模块剥离图标库依赖,图标映射随唯一消费者组件声明,comments 单测耗时由 126 秒降至 5 秒 - 同步更新 docs/debt/frontend.md 第 3、8 条与 docs/architecture-rules.md 索引及分期状态 --- .../admin/article/article-table.svelte | 23 +- .../admin/category/category-table.svelte | 74 +++ .../admin/comment/comment-table.svelte | 130 ++++++ .../admin/dict/dict-item-table.svelte | 131 ++++++ .../admin/dict/dict-type-list.svelte | 98 ++++ .../components/admin/link/link-table.svelte | 128 ++++++ .../components/admin/media/media-grid.svelte | 64 +++ .../lib/components/admin/tag/tag-table.svelte | 111 +++++ apps/admin/src/lib/constants/article.ts | 10 +- apps/admin/src/lib/constants/category.ts | 30 +- apps/admin/src/lib/constants/comment.ts | 11 +- apps/admin/src/lib/constants/dict.test.ts | 18 + apps/admin/src/lib/constants/dict.ts | 26 ++ apps/admin/src/lib/constants/link.ts | 22 +- apps/admin/src/lib/constants/media.ts | 24 + apps/admin/src/lib/constants/user.ts | 5 + apps/admin/src/lib/utils/tag-display.test.ts | 57 +++ apps/admin/src/lib/utils/tag-display.ts | 29 ++ .../routes/(admin)/categories/+page.svelte | 316 ++++--------- .../src/routes/(admin)/categories/+page.ts | 21 + .../categories/category-page-state.svelte.ts | 152 ++++++ .../categories/category-page-state.test.ts | 289 ++++++++++++ .../src/routes/(admin)/comments/+page.svelte | 301 +++--------- .../src/routes/(admin)/comments/+page.ts | 23 + .../comments/comment-page-state.svelte.ts | 160 +++++++ .../comments/comment-page-state.test.ts | 332 ++++++++++++++ .../src/routes/(admin)/dicts/+page.svelte | 252 ++-------- .../src/routes/(admin)/links/+page.svelte | 378 ++++----------- apps/admin/src/routes/(admin)/links/+page.ts | 25 + .../(admin)/links/link-page-state.svelte.ts | 166 +++++++ .../(admin)/links/link-page-state.test.ts | 329 +++++++++++++ .../src/routes/(admin)/media/+page.svelte | 292 ++++-------- apps/admin/src/routes/(admin)/media/+page.ts | 23 + .../(admin)/media/media-page-state.svelte.ts | 142 ++++++ .../(admin)/media/media-page-state.test.ts | 307 +++++++++++++ .../src/routes/(admin)/tags/+page.svelte | 376 +++------------ apps/admin/src/routes/(admin)/tags/+page.ts | 32 ++ .../(admin)/tags/tag-page-state.svelte.ts | 204 +++++++++ .../(admin)/tags/tag-page-state.test.ts | 303 ++++++++++++ .../src/routes/(admin)/users/+page.svelte | 384 +++++----------- apps/admin/src/routes/(admin)/users/+page.ts | 28 ++ .../(admin)/users/user-page-state.svelte.ts | 256 +++++++++++ .../(admin)/users/user-page-state.test.ts | 432 ++++++++++++++++++ docs/architecture-rules.md | 6 +- docs/debt/frontend.md | 19 +- 45 files changed, 4750 insertions(+), 1789 deletions(-) create mode 100644 apps/admin/src/lib/components/admin/category/category-table.svelte create mode 100644 apps/admin/src/lib/components/admin/comment/comment-table.svelte create mode 100644 apps/admin/src/lib/components/admin/dict/dict-item-table.svelte create mode 100644 apps/admin/src/lib/components/admin/dict/dict-type-list.svelte create mode 100644 apps/admin/src/lib/components/admin/link/link-table.svelte create mode 100644 apps/admin/src/lib/components/admin/media/media-grid.svelte create mode 100644 apps/admin/src/lib/components/admin/tag/tag-table.svelte create mode 100644 apps/admin/src/lib/constants/dict.test.ts create mode 100644 apps/admin/src/lib/constants/dict.ts create mode 100644 apps/admin/src/lib/constants/media.ts create mode 100644 apps/admin/src/lib/utils/tag-display.test.ts create mode 100644 apps/admin/src/lib/utils/tag-display.ts create mode 100644 apps/admin/src/routes/(admin)/categories/+page.ts create mode 100644 apps/admin/src/routes/(admin)/categories/category-page-state.svelte.ts create mode 100644 apps/admin/src/routes/(admin)/categories/category-page-state.test.ts create mode 100644 apps/admin/src/routes/(admin)/comments/+page.ts create mode 100644 apps/admin/src/routes/(admin)/comments/comment-page-state.svelte.ts create mode 100644 apps/admin/src/routes/(admin)/comments/comment-page-state.test.ts create mode 100644 apps/admin/src/routes/(admin)/links/+page.ts create mode 100644 apps/admin/src/routes/(admin)/links/link-page-state.svelte.ts create mode 100644 apps/admin/src/routes/(admin)/links/link-page-state.test.ts create mode 100644 apps/admin/src/routes/(admin)/media/+page.ts create mode 100644 apps/admin/src/routes/(admin)/media/media-page-state.svelte.ts create mode 100644 apps/admin/src/routes/(admin)/media/media-page-state.test.ts create mode 100644 apps/admin/src/routes/(admin)/tags/+page.ts create mode 100644 apps/admin/src/routes/(admin)/tags/tag-page-state.svelte.ts create mode 100644 apps/admin/src/routes/(admin)/tags/tag-page-state.test.ts create mode 100644 apps/admin/src/routes/(admin)/users/+page.ts create mode 100644 apps/admin/src/routes/(admin)/users/user-page-state.svelte.ts create mode 100644 apps/admin/src/routes/(admin)/users/user-page-state.test.ts diff --git a/apps/admin/src/lib/components/admin/article/article-table.svelte b/apps/admin/src/lib/components/admin/article/article-table.svelte index 049cfd4..053daf0 100644 --- a/apps/admin/src/lib/components/admin/article/article-table.svelte +++ b/apps/admin/src/lib/components/admin/article/article-table.svelte @@ -1,15 +1,25 @@ + + +
+ {#each rows as row (row.category.id)} + {@const statusConfig = CATEGORY_STATUS_CONFIG[row.category.status]!} +
+
+ {#if row.depth > 0} + └ + {/if} + + {row.category.name} + + {statusConfig.label} + {#if row.category.isFeatured} + 精选 + {/if} +
+ + {row.category.articleCount} 篇文章 + + + + + + + + onCreateChild(row.category)}> + + 新建子分类 + + onEdit(row.category)}> + + 编辑 + + onDelete(row.category)}> + + 删除 + + + +
+ {/each} +
diff --git a/apps/admin/src/lib/components/admin/comment/comment-table.svelte b/apps/admin/src/lib/components/admin/comment/comment-table.svelte new file mode 100644 index 0000000..33543d3 --- /dev/null +++ b/apps/admin/src/lib/components/admin/comment/comment-table.svelte @@ -0,0 +1,130 @@ + + + + + + + 评论内容 + 评论者 + + 状态 + + 操作 + + + + {#each comments as comment (comment.id)} + + +
+

{comment.content}

+ + + {getArticleTitle(comment)} + + {formatCreatedAt(comment)} + +
+
+ + {getAuthorName(comment)} + + + + + {COMMENT_STATUS_CONFIG[comment.status].label} + + + + +
+ + + + + + {#each COMMENT_ACTIONS[comment.status] as action (action)} + {@const ActionIcon = COMMENT_ACTION_ICONS[action]} + onAction(comment, action)} + > + + {COMMENT_ACTION_LABELS[action]} + + {/each} + + +
+
+
+ {/each} +
+
diff --git a/apps/admin/src/lib/components/admin/dict/dict-item-table.svelte b/apps/admin/src/lib/components/admin/dict/dict-item-table.svelte new file mode 100644 index 0000000..66d113b --- /dev/null +++ b/apps/admin/src/lib/components/admin/dict/dict-item-table.svelte @@ -0,0 +1,131 @@ + + + + + + + 字典项 + {#if type} + {type.code} + {/if} + + + + + {#if !type} +
+

请先选择字典类型

+
+ {:else if isLoading} +
+ +
+ {:else if items.length === 0} + + + + + + 暂无字典项 + 为当前字典类型添加可选值 + + + + + + {:else} + + + + 值 + 显示名 + + + 状态 + 操作 + + + + {#each items as item (item.id)} + {@const status = dictStatusOf(item.status)} + + + + {item.value} + + + + {item.label} + + {#if item.description} + + {item.description} + + {/if} + + + + + {status.label} + + +
+ + +
+
+
+ {/each} +
+
+ {/if} +
+
diff --git a/apps/admin/src/lib/components/admin/dict/dict-type-list.svelte b/apps/admin/src/lib/components/admin/dict/dict-type-list.svelte new file mode 100644 index 0000000..772f9f7 --- /dev/null +++ b/apps/admin/src/lib/components/admin/dict/dict-type-list.svelte @@ -0,0 +1,98 @@ + + + + + + + + 字典类型 + + + + {#if isLoading} +
+ +
+ {:else if types.length === 0} + + + + + + 暂无字典类型 + 创建第一个字典类型开始使用 + + + + + + {:else} +
    + {#each types as type (type.id)} + {@const isSelected = type.id === selectedTypeId} + {@const status = dictStatusOf(type.status)} +
  • +
    + +
    + + +
    +
    +
  • + {/each} +
+ {/if} +
+
diff --git a/apps/admin/src/lib/components/admin/link/link-table.svelte b/apps/admin/src/lib/components/admin/link/link-table.svelte new file mode 100644 index 0000000..1f8d982 --- /dev/null +++ b/apps/admin/src/lib/components/admin/link/link-table.svelte @@ -0,0 +1,128 @@ + + + + + + + 站点 + + + 状态 + + 操作 + + + + {#each links as link (link.id)} + + +
+ {#if link.logo} + {link.name} + {/if} +
+

{link.name}

+ + + {#if link.description} + + {link.description} + + {/if} + {#if link.isReciprocal} + 已回链 + {/if} +
+
+
+ + + + + {LINK_STATUS_CONFIG[link.status].label} + + + + +
+ + + + + + + {#each LINK_STATUS_ACTIONS[link.status] as action (action.key)} + {@const ActionIcon = LINK_ACTION_ICONS[action.key]} + onReview(link, action.key)}> + + {action.label} + + {/each} + onDelete(link)}> + + 删除 + + + +
+
+
+ {/each} +
+
diff --git a/apps/admin/src/lib/components/admin/media/media-grid.svelte b/apps/admin/src/lib/components/admin/media/media-grid.svelte new file mode 100644 index 0000000..12cdbbb --- /dev/null +++ b/apps/admin/src/lib/components/admin/media/media-grid.svelte @@ -0,0 +1,64 @@ + + + +
+ {#each media as file (file.id)} +
+
+ {#if file.mimeType.startsWith(MEDIA_IMAGE_MIME_PREFIX)} + {file.filename} + {:else} + {@const IconComponent = typeIcon(file)} + + {/if} +
+
+

{file.filename}

+

+ {getFileSize(file.fileSize)} · {file.mimeType} +

+
+ + +
+
+
+ {/each} +
diff --git a/apps/admin/src/lib/components/admin/tag/tag-table.svelte b/apps/admin/src/lib/components/admin/tag/tag-table.svelte new file mode 100644 index 0000000..758f6b8 --- /dev/null +++ b/apps/admin/src/lib/components/admin/tag/tag-table.svelte @@ -0,0 +1,111 @@ + + + + + + + 标签 + + 使用次数 + 状态 + + 操作 + + + + {#each tags as tag (tag.id)} + + +
+ + + {tag.name} + {#if tag.isHot} + + {#if tag.description} +

{tag.description}

+ {/if} + + + {tag.slug} + +
+
+ + + + {tag.usageCount} + + + + + {resolveTagStatusLabel(statusDict, tag.status)} + + + + +
+ + +
+
+
+ {/each} +
+
diff --git a/apps/admin/src/lib/constants/article.ts b/apps/admin/src/lib/constants/article.ts index 701dc8f..5449d8d 100644 --- a/apps/admin/src/lib/constants/article.ts +++ b/apps/admin/src/lib/constants/article.ts @@ -1,6 +1,6 @@ // 文章模块常量:状态配置、筛选选项与排序选项,供列表与编辑页共用。 -import { Archive, Lock, Send, Undo2, type LucideIcon } from '@lucide/svelte' +// 本文件不得引入图标库:页面状态模块与单元测试都会引用它,图标桶进入编译图会把测试启动代价放大两个数量级。 import type { ArticleStatus } from '@myblog/api/modules/article/types' import type { BadgeVariant } from '$ui/badge' @@ -59,11 +59,3 @@ export const ARTICLE_ACTION_LABELS: Record = { archive: '归档', private: '设为私有' } - -// 状态操作的图标映射,与 ARTICLE_ACTION_LABELS 一一对应,供下拉菜单渲染。 -export const ARTICLE_ACTION_ICONS: Record = { - publish: Send, - unpublish: Undo2, - archive: Archive, - private: Lock -} diff --git a/apps/admin/src/lib/constants/category.ts b/apps/admin/src/lib/constants/category.ts index a04e74e..9632593 100644 --- a/apps/admin/src/lib/constants/category.ts +++ b/apps/admin/src/lib/constants/category.ts @@ -1,19 +1,43 @@ -// 分类模块常量:状态配置与筛选选项。 +// 分类模块常量:状态配置、筛选选项与树形展示的缩进口径。 +import type { Category } from '@myblog/api/modules/category/types' import type { BadgeVariant } from '$ui/badge' +// 分类树扁平化后的展示行,depth 为层级深度,由渲染层换算为缩进量。 +export interface CategoryRow { + category: Category + depth: number +} + // 分类状态配置,0 隐藏 / 1 显示。 export const CATEGORY_STATUS_CONFIG: Record = { 0: { label: '隐藏', variant: 'secondary' }, 1: { label: '显示', variant: 'default' } } -// 分类状态筛选选项 +// 分类状态筛选选项,取值为状态枚举本身,供展示型筛选使用。 export const CATEGORY_STATUS_OPTIONS: Array<{ value: number | null; label: string }> = [ { value: null, label: '全部状态' }, { value: 1, label: '显示' }, { value: 0, label: '隐藏' } ] -// 分类默认分页大小 +// 状态筛选的不限制取值,空串表示全部状态。 +export const CATEGORY_STATUS_FILTER_ALL = '' + +// 状态筛选项的界面取值,与 CATEGORY_STATUS_OPTIONS 同序。 +// 取值统一为字符串,与切换组的字符串取值口径保持一致。 +export const CATEGORY_STATUS_FILTER_OPTIONS: ReadonlyArray<{ value: string; label: string }> = + CATEGORY_STATUS_OPTIONS.map(option => ({ + value: option.value === null ? CATEGORY_STATUS_FILTER_ALL : String(option.value), + label: option.label + })) + +// 分类树行的基础左内边距,单位为 rem。 +export const CATEGORY_ROW_BASE_PADDING_REM = 1 + +// 分类树行每深入一层追加的左内边距,单位为 rem,用于呈现父子归属。 +export const CATEGORY_ROW_INDENT_PER_LEVEL_REM = 1.5 + +// 分类默认分页大小,供后续分页形态的分类列表复用。 export const CATEGORY_PAGE_SIZE = 10 diff --git a/apps/admin/src/lib/constants/comment.ts b/apps/admin/src/lib/constants/comment.ts index 4a02560..1c67041 100644 --- a/apps/admin/src/lib/constants/comment.ts +++ b/apps/admin/src/lib/constants/comment.ts @@ -1,6 +1,6 @@ // 评论模块常量:状态配置、筛选选项与审核动作映射。 +// 本文件不得引入图标库:状态模块与单元测试都会引用它,图标桶进入编译图会把测试启动代价放大两个数量级。 -import { ArchiveX, Ban, CircleCheck, CircleX, Trash2, type LucideIcon } from '@lucide/svelte' import type { CommentStatus } from '@myblog/api/modules/comment/types' import type { BadgeVariant } from '$ui/badge' @@ -47,14 +47,5 @@ export const COMMENT_ACTION_LABELS: Record = { delete: '删除' } -// 审核动作的图标映射,与 COMMENT_ACTION_LABELS 一一对应,供下拉菜单渲染。 -export const COMMENT_ACTION_ICONS: Record = { - approve: CircleCheck, - reject: CircleX, - spam: Ban, - trash: ArchiveX, - delete: Trash2 -} - // 评论默认分页大小 export const COMMENT_PAGE_SIZE = 10 diff --git a/apps/admin/src/lib/constants/dict.test.ts b/apps/admin/src/lib/constants/dict.test.ts new file mode 100644 index 0000000..9c6fc60 --- /dev/null +++ b/apps/admin/src/lib/constants/dict.test.ts @@ -0,0 +1,18 @@ +import { describe, expect, it } from 'vitest' + +import { DICT_STATUS_DISABLED, DICT_STATUS_ENABLED, dictStatusOf } from './dict' + +describe('字典状态展示配置', () => { + it('生效状态返回主色样式与生效文案', () => { + expect(dictStatusOf(DICT_STATUS_ENABLED)).toEqual({ label: '生效', variant: 'default' }) + }) + + it('停用状态返回次级样式与停用文案', () => { + expect(dictStatusOf(DICT_STATUS_DISABLED)).toEqual({ label: '停用', variant: 'secondary' }) + }) + + // 后端新增状态取值而前端未同步时,列表必须保留可见的状态标注而不是空白。 + it('未知状态回退为未知文案与次级样式', () => { + expect(dictStatusOf(99)).toEqual({ label: '未知', variant: 'secondary' }) + }) +}) diff --git a/apps/admin/src/lib/constants/dict.ts b/apps/admin/src/lib/constants/dict.ts new file mode 100644 index 0000000..2f42a5c --- /dev/null +++ b/apps/admin/src/lib/constants/dict.ts @@ -0,0 +1,26 @@ +// 字典模块常量:生效状态取值与展示配置。 +// 字典类型与字典项共用同一状态枚举,1 生效 / 0 停用。 + +import type { BadgeVariant } from '$ui/badge' + +// 字典生效状态取值。 +export const DICT_STATUS_ENABLED = 1 + +// 字典停用状态取值。 +export const DICT_STATUS_DISABLED = 0 + +// 状态展示配置,仅作后端状态文案未下发时的降级来源。 +export const DICT_STATUS_CONFIG: Record = { + [DICT_STATUS_ENABLED]: { label: '生效', variant: 'default' }, + [DICT_STATUS_DISABLED]: { label: '停用', variant: 'secondary' } +} + +// 查询状态展示配置,未知取值回退为停用样式,避免列表出现无标注的状态格。 +export function dictStatusOf(status: number): { label: string; variant: BadgeVariant } { + return ( + DICT_STATUS_CONFIG[status] ?? { + label: '未知', + variant: 'secondary' + } + ) +} diff --git a/apps/admin/src/lib/constants/link.ts b/apps/admin/src/lib/constants/link.ts index bed9c2b..ff4c5b6 100644 --- a/apps/admin/src/lib/constants/link.ts +++ b/apps/admin/src/lib/constants/link.ts @@ -1,4 +1,4 @@ -// 友情链接模块常量:状态配置与筛选选项。 +// 友情链接模块常量:状态配置、筛选选项与审核动作。 import type { LinkStatus } from '@myblog/api/modules/friendlyLink/types' import type { BadgeVariant } from '$ui/badge' @@ -20,5 +20,25 @@ export const LINK_STATUS_OPTIONS: Array<{ value: LinkStatus | ''; label: string { value: 'rejected', label: '已拒绝' } ] +// 友链审核动作键,与友情链接接口的同名审核方法一致。 +export type LinkStatusAction = 'approve' | 'hide' | 'reject' + +// 各状态下可执行的审核动作;同一动作在不同状态下的文案不同,故文案随状态声明。 +export const LINK_STATUS_ACTIONS: Record< + LinkStatus, + Array<{ key: LinkStatusAction; label: string }> +> = { + pending: [ + { key: 'approve', label: '通过' }, + { key: 'reject', label: '拒绝' } + ], + active: [{ key: 'hide', label: '下架' }], + hidden: [ + { key: 'approve', label: '重新上架' }, + { key: 'reject', label: '拒绝' } + ], + rejected: [{ key: 'approve', label: '重新上架' }] +} + // 友链默认分页大小 export const LINK_PAGE_SIZE = 10 diff --git a/apps/admin/src/lib/constants/media.ts b/apps/admin/src/lib/constants/media.ts new file mode 100644 index 0000000..06b1f33 --- /dev/null +++ b/apps/admin/src/lib/constants/media.ts @@ -0,0 +1,24 @@ +// 媒体模块常量:分页容量、类型筛选项与上传文件约束,供媒体页与网格组件共用。 + +// 媒体库每页加载数量,与分页组件取值保持一致。 +export const MEDIA_PAGE_SIZE = 12 + +// 图片 MIME 前缀,决定列表项是否走缩略图预览。 +export const MEDIA_IMAGE_MIME_PREFIX = 'image/' + +// 视频 MIME 前缀,决定列表项使用视频图标。 +export const MEDIA_VIDEO_MIME_PREFIX = 'video/' + +// 文档 MIME 前缀,未命中图片与视频时按文档图标展示。 +export const MEDIA_APPLICATION_MIME_PREFIX = 'application/' + +// 媒体类型筛选项,value 为传给后端 mimeType 的 MIME 前缀,空串表示不筛选。 +export const MEDIA_TYPE_FILTERS: Array<{ value: string; label: string }> = [ + { value: '', label: '全部' }, + { value: MEDIA_IMAGE_MIME_PREFIX, label: '图片' }, + { value: MEDIA_VIDEO_MIME_PREFIX, label: '视频' }, + { value: MEDIA_APPLICATION_MIME_PREFIX, label: '文档' } +] + +// 文件选择框接受的文件类型,与后端媒体上传的白名单保持同一口径。 +export const MEDIA_FILE_ACCEPT = 'image/*,video/*,audio/*,application/pdf,text/*' diff --git a/apps/admin/src/lib/constants/user.ts b/apps/admin/src/lib/constants/user.ts index 75d101c..c244858 100644 --- a/apps/admin/src/lib/constants/user.ts +++ b/apps/admin/src/lib/constants/user.ts @@ -10,6 +10,11 @@ export const USER_STATUS_CONFIG: Record = { superadmin: '超级管理员', diff --git a/apps/admin/src/lib/utils/tag-display.test.ts b/apps/admin/src/lib/utils/tag-display.test.ts new file mode 100644 index 0000000..e44376a --- /dev/null +++ b/apps/admin/src/lib/utils/tag-display.test.ts @@ -0,0 +1,57 @@ +import type { EnabledDictGroup } from '@myblog/api/modules/dict/types' +import { describe, expect, it } from 'vitest' + +import { resolveTagStatusLabel, resolveTagStatusVariant } from './tag-display' + +// 构造最小可用的状态字典分组,仅覆盖解析所需的字段。 +function statusDictWithVariant(variant: string, label: string): EnabledDictGroup { + return { + id: 1, + code: 'tag_status', + name: '标签状态', + description: '', + status: 1, + sortOrder: 0, + extra: null, + createdAt: '', + updatedAt: '', + items: [ + { + id: 1, + typeId: 1, + value: '1', + label, + description: '', + sortOrder: 0, + status: 1, + extra: { variant }, + createdAt: '', + updatedAt: '' + } + ] + } +} + +describe('标签状态展示解析', () => { + it('字典缺失时回退内置配置', () => { + expect(resolveTagStatusLabel(null, 1)).toBe('启用') + expect(resolveTagStatusVariant(null, 1)).toBe('default') + }) + + it('字典命中时以字典文案与样式为准', () => { + const dict = statusDictWithVariant('outline', '已上线') + expect(resolveTagStatusLabel(dict, 1)).toBe('已上线') + expect(resolveTagStatusVariant(dict, 1)).toBe('outline') + }) + + // 运维在字典里填入非法样式时必须回退,否则 Badge 会丢掉全部样式。 + it('字典样式取值非法时回退内置配置', () => { + const dict = statusDictWithVariant('primary', '已上线') + expect(resolveTagStatusVariant(dict, 1)).toBe('default') + }) + + it('未知状态取值返回未知文案与次级样式', () => { + expect(resolveTagStatusLabel(null, 99)).toBe('未知') + expect(resolveTagStatusVariant(null, 99)).toBe('secondary') + }) +}) diff --git a/apps/admin/src/lib/utils/tag-display.ts b/apps/admin/src/lib/utils/tag-display.ts new file mode 100644 index 0000000..b854e9c --- /dev/null +++ b/apps/admin/src/lib/utils/tag-display.ts @@ -0,0 +1,29 @@ +// 标签状态展示解析:优先读取标签状态字典的扩展元数据,缺失或非法时回退内置配置。 +// 页面与表格组件共用同一解析口径,避免两处各自维护降级规则。 + +import type { EnabledDictGroup } from '@myblog/api/modules/dict/types' +import { findDictItem, dictItemLabel } from '@myblog/api' +import type { BadgeVariant } from '$ui/badge' + +import { TAG_STATUS_CONFIG } from '$lib/constants/tag' + +// Badge 合法样式集合,用于校验字典扩展元数据中的样式取值。 +const BADGE_VARIANTS: BadgeVariant[] = ['default', 'secondary', 'destructive', 'outline'] + +// 解析标签状态的展示文案。 +export function resolveTagStatusLabel(statusDict: EnabledDictGroup | null, status: number): string { + return dictItemLabel(statusDict, String(status), TAG_STATUS_CONFIG[status]?.label ?? '未知') +} + +// 解析标签状态的徽标样式,扩展元数据取值非法时回退内置配置。 +export function resolveTagStatusVariant( + statusDict: EnabledDictGroup | null, + status: number +): BadgeVariant { + const fallback = TAG_STATUS_CONFIG[status]?.variant ?? 'secondary' + const variant = findDictItem(statusDict, String(status))?.extra?.variant + if (typeof variant === 'string' && BADGE_VARIANTS.includes(variant as BadgeVariant)) { + return variant as BadgeVariant + } + return fallback +} diff --git a/apps/admin/src/routes/(admin)/categories/+page.svelte b/apps/admin/src/routes/(admin)/categories/+page.svelte index 5cea8ce..d073493 100644 --- a/apps/admin/src/routes/(admin)/categories/+page.svelte +++ b/apps/admin/src/routes/(admin)/categories/+page.svelte @@ -1,47 +1,34 @@ @@ -172,7 +78,7 @@ onMount(loadCategories) crumb="分类管理" > {#snippet actions()} - @@ -180,118 +86,84 @@ onMount(loadCategories) +
- +
- - 全部状态 - 显示 - 隐藏 + + {#each CATEGORY_STATUS_FILTER_OPTIONS as option (option.value)} + {option.label} + {/each} -
- {#if isLoading} + {#if categoryPageState.isLoading}
- -
- {:else if filteredRows.length === 0} -
-
- -
-
-

- {rows.length === 0 ? '暂无分类' : '没有匹配的分类'} -

-

- {rows.length === 0 ? '创建第一个分类来组织文章' : '调整或重置筛选条件后再试'} -

-
- {#if rows.length === 0} - - {:else} - - {/if} +
+ {:else if categoryPageState.filteredRows.length === 0} + + + + + + + {categoryPageState.hasCategories ? '没有匹配的分类' : '暂无分类'} + + + {categoryPageState.hasCategories + ? '调整或重置筛选条件后再试' + : '创建第一个分类来组织文章'} + + + + {#if categoryPageState.hasCategories} + + {:else} + + {/if} + + {:else} -
- {#each filteredRows as row (row.category.id)} - {@const statusConfig = CATEGORY_STATUS_CONFIG[row.category.status]!} -
-
- {#if row.depth > 0} - └ - {/if} - - {row.category.name} - - {statusConfig.label} - {#if row.category.isFeatured} - 精选 - {/if} -
- - {row.category.articleCount} 篇文章 - - - - - - - - openCreate()}> - - 新建子分类 - - { - dialogTarget = row.category - isDialogOpen = true - }} - > - - 编辑 - - (deleteTarget = row.category)} - > - - 删除 - - - -
- {/each} -
+ openDialog(null)} + onEdit={category => openDialog(category)} + onDelete={category => (deleteTarget = category)} + />
-

共 {rows.length} 个分类

+

共 {categoryPageState.total} 个分类

- 当前显示 {filteredRows.length} 个 + 当前显示 {categoryPageState.filteredRows.length} 个

{/if} @@ -302,7 +174,7 @@ onMount(loadCategories) {isSubmitting} open={isDialogOpen} target={dialogTarget} - categories={flatCategories} + categories={categoryPageState.flatCategories} onOpenChange={open => (isDialogOpen = open)} onConfirm={handleConfirm} /> diff --git a/apps/admin/src/routes/(admin)/categories/+page.ts b/apps/admin/src/routes/(admin)/categories/+page.ts new file mode 100644 index 0000000..9180224 --- /dev/null +++ b/apps/admin/src/routes/(admin)/categories/+page.ts @@ -0,0 +1,21 @@ +import type { PageLoad } from './$types' + +import { emptyCategoryPageData } from './category-page-state.svelte' +import { CategoryAPI } from '$lib/api' + +// 分类管理页初始数据:分类树一次拉取全量,页面扁平化后在客户端筛选,不走服务端分页。 +// 加载失败不抛错,回退空数据并由页面状态模块在后续操作中继续提示。 +export const load: PageLoad = async () => { + const pageData = emptyCategoryPageData() + try { + const response = await CategoryAPI.getTree() + if (response.code === 200 && response.data) { + pageData.tree = response.data.tree ?? [] + } else { + console.error('加载分类树失败:', response.message) + } + } catch (error) { + console.error('加载分类树失败:', error) + } + return pageData +} diff --git a/apps/admin/src/routes/(admin)/categories/category-page-state.svelte.ts b/apps/admin/src/routes/(admin)/categories/category-page-state.svelte.ts new file mode 100644 index 0000000..33220ba --- /dev/null +++ b/apps/admin/src/routes/(admin)/categories/category-page-state.svelte.ts @@ -0,0 +1,152 @@ +import type { + Category, + CategoryTreeNode, + CreateCategoryRequest, + UpdateCategoryRequest +} from '@myblog/api/modules/category/types' +import { toast } from 'svelte-sonner' + +import { CATEGORY_STATUS_FILTER_ALL, type CategoryRow } from '$lib/constants/category' +import { CategoryAPI } from '$lib/api' + +// 网络异常的统一提示文案。 +const NETWORK_ERROR_MESSAGE = '网络错误,请稍后重试' + +// 初始页面数据形状,由 +page.ts 的 load 函数提供。 +export interface CategoryPageData { + tree: CategoryTreeNode[] +} + +// 空页面数据,load 失败或无数据时使用。 +export function emptyCategoryPageData(): CategoryPageData { + return { tree: [] } +} + +// 将分类树递归扁平化为带缩进深度的行序列,深度由渲染层换算为缩进量。 +function flattenTree(nodes: CategoryTreeNode[], depth = 0): CategoryRow[] { + return nodes.flatMap(node => [ + { category: node, depth }, + ...flattenTree(node.children ?? [], depth + 1) + ]) +} + +// 分类管理页状态:集中持有分类树行、筛选条件与全部读写操作,页面组件只做渲染。 +class CategoryPageState { + rows = $state([]) + searchQuery = $state('') + // 状态筛选使用字符串值:空串为全部,其余为分类状态值的字符串形式。 + statusFilter = $state(CATEGORY_STATUS_FILTER_ALL) + // 初始数据由 load 提供,首次渲染不需要加载态。 + isLoading = $state(false) + + // 按名称与 URL 标识匹配后再按显示状态过滤,树数据为全量,无需服务端分页。 + get filteredRows(): CategoryRow[] { + const query = this.searchQuery.trim().toLowerCase() + return this.rows.filter(row => { + const nameHit = !query || row.category.name.toLowerCase().includes(query) + const slugHit = !query || (row.category.slug ?? '').toLowerCase().includes(query) + const statusHit = + this.statusFilter === CATEGORY_STATUS_FILTER_ALL || + row.category.status === Number(this.statusFilter) + return (nameHit || slugHit) && statusHit + }) + } + + // 全量分类列表,供表单弹窗选择父分类,由扁平行去掉缩进深度得到。 + get flatCategories(): Category[] { + return this.rows.map(row => row.category) + } + + // 树中是否已存在分类,用于空态区分无数据与无匹配。 + get hasCategories(): boolean { + return this.rows.length > 0 + } + + // 分类总数,取全量树行的数量,客户端筛选不改变该口径。 + get total(): number { + return this.rows.length + } + + // 用 load 结果初始化页面状态,重复挂载时以最新数据覆盖。 + initialize(data: CategoryPageData) { + this.rows = flattenTree(data.tree) + } + + // 重置筛选条件并清空搜索结果。 + resetFilters() { + this.searchQuery = '' + this.statusFilter = CATEGORY_STATUS_FILTER_ALL + } + + // 加载分类树并重新生成扁平行,树为全量数据,刷新后保留当前筛选条件。 + async loadCategories() { + this.isLoading = true + try { + const response = await CategoryAPI.getTree() + if (response.code === 200 && response.data) { + this.rows = flattenTree(response.data.tree ?? []) + } else { + toast.error(response.message || '加载分类失败') + } + } catch (error) { + console.error('加载分类失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + this.isLoading = false + } + } + + // 创建分类,成功后重新加载分类树。 + async createCategory(payload: CreateCategoryRequest): Promise { + try { + const response = await CategoryAPI.create(payload) + if (response.code === 200 && response.data) { + toast.success('分类创建成功') + await this.loadCategories() + return true + } + toast.error(response.message || '保存分类失败') + } catch (error) { + console.error('保存分类失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } + + // 更新分类,成功后重新加载分类树。 + async updateCategory(payload: UpdateCategoryRequest): Promise { + try { + const response = await CategoryAPI.update(payload) + if (response.code === 200 && response.data) { + toast.success('分类更新成功') + await this.loadCategories() + return true + } + toast.error(response.message || '保存分类失败') + } catch (error) { + console.error('保存分类失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } + + // 删除分类,存在子分类时后端拒绝,拒绝原因沿用后端文案提示。 + async removeCategory(id: number): Promise { + try { + const response = await CategoryAPI.delete(id) + if (response.code === 200) { + toast.success('分类删除成功') + await this.loadCategories() + return true + } + toast.error(response.message || '删除分类失败') + } catch (error) { + console.error('删除分类失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } +} + +// 页面级共享状态实例。 +export const categoryPageState = new CategoryPageState() diff --git a/apps/admin/src/routes/(admin)/categories/category-page-state.test.ts b/apps/admin/src/routes/(admin)/categories/category-page-state.test.ts new file mode 100644 index 0000000..3c6b541 --- /dev/null +++ b/apps/admin/src/routes/(admin)/categories/category-page-state.test.ts @@ -0,0 +1,289 @@ +import type { CategoryTreeNode } from '@myblog/api/modules/category/types' +import { beforeEach, describe, expect, it, vi } from 'vitest' + +import { CATEGORY_STATUS_FILTER_ALL } from '$lib/constants/category' + +// 接口与提示均以替身注入,测试只验证页面状态的编排逻辑,不触达网络与界面。 +const categoryApiMock = { + getTree: vi.fn(), + create: vi.fn(), + update: vi.fn(), + delete: vi.fn() +} + +const toastMock = { + success: vi.fn(), + error: vi.fn() +} + +vi.mock('$lib/api', () => ({ CategoryAPI: categoryApiMock })) +vi.mock('svelte-sonner', () => ({ toast: toastMock })) + +const { emptyCategoryPageData, categoryPageState } = await import('./category-page-state.svelte') + +// 后端统一响应的成功业务码。 +const SUCCESS_CODE = 200 + +// 网络异常的统一提示文案,与页面状态模块内的取值一致。 +const NETWORK_ERROR_MESSAGE = '网络错误,请稍后重试' + +// 构造分类树节点替身,字段取值只覆盖被测逻辑关心的部分。 +function makeNode( + id: number, + options: { name?: string; slug?: string; status?: number; children?: CategoryTreeNode[] } = {} +): CategoryTreeNode { + const { name = `分类${id}`, slug = `category-${id}`, status = 1, children = [] } = options + return { id, name, slug, status, children } as unknown as CategoryTreeNode +} + +// 两级分类树替身:顶级分类 1 带子分类 11,顶级分类 2 为隐藏分类。 +function makeTree(): CategoryTreeNode[] { + return [ + makeNode(1, { + name: '技术', + slug: 'tech', + children: [makeNode(11, { name: '前端', slug: 'fe' })] + }), + makeNode(2, { name: '生活', slug: 'life', status: 0 }) + ] +} + +// 当前筛选结果中的分类 ID 序列,用于断言筛选后的行集合与顺序。 +function filteredIds(): number[] { + return categoryPageState.filteredRows.map(row => row.category.id) +} + +// 重置替身调用记录与页面状态,避免用例之间互相污染。 +function resetState() { + vi.clearAllMocks() + categoryPageState.initialize(emptyCategoryPageData()) + categoryPageState.searchQuery = '' + categoryPageState.statusFilter = CATEGORY_STATUS_FILTER_ALL + categoryPageState.isLoading = false +} + +describe('分类页状态:初始化', () => { + beforeEach(resetState) + + it('按树层级扁平化 load 结果并记录缩进深度', () => { + categoryPageState.initialize({ tree: makeTree() }) + + expect(categoryPageState.rows.map(row => [row.category.id, row.depth])).toEqual([ + [1, 0], + [11, 1], + [2, 0] + ]) + expect(categoryPageState.flatCategories.map(category => category.id)).toEqual([1, 11, 2]) + expect(categoryPageState.hasCategories).toBe(true) + expect(categoryPageState.total).toBe(3) + }) + + it('空数据下无分类且筛选结果为空', () => { + categoryPageState.initialize(emptyCategoryPageData()) + + expect(categoryPageState.hasCategories).toBe(false) + expect(categoryPageState.filteredRows).toEqual([]) + }) + + it('重复初始化时以最新的树覆盖既有行', () => { + categoryPageState.initialize({ tree: makeTree() }) + categoryPageState.initialize({ tree: [makeNode(5, { name: '随笔' })] }) + + expect(filteredIds()).toEqual([5]) + }) +}) + +describe('分类页状态:树加载', () => { + beforeEach(resetState) + + it('加载成功后替换扁平行且不携带参数', async () => { + categoryApiMock.getTree.mockResolvedValue({ code: SUCCESS_CODE, data: { tree: makeTree() } }) + + await categoryPageState.loadCategories() + + expect(categoryApiMock.getTree).toHaveBeenCalledWith() + expect(filteredIds()).toEqual([1, 11, 2]) + expect(categoryPageState.isLoading).toBe(false) + }) + + it('加载失败时提示后端文案或默认文案且保留现有行', async () => { + categoryPageState.initialize({ tree: makeTree() }) + categoryApiMock.getTree.mockResolvedValue({ code: 500, message: '查询失败' }) + + await categoryPageState.loadCategories() + expect(toastMock.error).toHaveBeenCalledWith('查询失败') + + // 响应缺少数据且未携带文案时回退到模块内的默认失败文案。 + categoryApiMock.getTree.mockResolvedValue({ code: SUCCESS_CODE }) + await categoryPageState.loadCategories() + expect(toastMock.error).toHaveBeenLastCalledWith('加载分类失败') + expect(categoryPageState.rows).toHaveLength(3) + }) + + it('请求抛错时提示网络错误并复位加载态', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + categoryApiMock.getTree.mockRejectedValue(new Error('断网')) + + await categoryPageState.loadCategories() + + expect(toastMock.error).toHaveBeenCalledWith(NETWORK_ERROR_MESSAGE) + expect(categoryPageState.isLoading).toBe(false) + expect(consoleError).toHaveBeenCalled() + consoleError.mockRestore() + }) + + it('请求未完成期间处于加载态', async () => { + let resolveTree: (value: unknown) => void = () => {} + categoryApiMock.getTree.mockReturnValue( + new Promise(resolve => { + resolveTree = resolve + }) + ) + + const loading = categoryPageState.loadCategories() + expect(categoryPageState.isLoading).toBe(true) + + resolveTree({ code: SUCCESS_CODE, data: { tree: [] } }) + await loading + + expect(categoryPageState.isLoading).toBe(false) + }) +}) + +describe('分类页状态:客户端筛选', () => { + beforeEach(() => { + resetState() + categoryPageState.initialize({ tree: makeTree() }) + }) + + it('按名称匹配且忽略大小写', () => { + categoryPageState.searchQuery = '技术' + + expect(filteredIds()).toEqual([1]) + }) + + it('按 URL 标识匹配', () => { + categoryPageState.searchQuery = 'LIFE' + + expect(filteredIds()).toEqual([2]) + }) + + it('按显示状态匹配', () => { + categoryPageState.statusFilter = '0' + + expect(filteredIds()).toEqual([2]) + }) + + it('名称或标识命中后再与状态取交集', () => { + categoryPageState.searchQuery = '前端' + categoryPageState.statusFilter = '1' + expect(filteredIds()).toEqual([11]) + + categoryPageState.statusFilter = '0' + expect(filteredIds()).toEqual([]) + + // 名称命中但状态不符的行不展示。 + categoryPageState.searchQuery = '生活' + categoryPageState.statusFilter = '1' + expect(filteredIds()).toEqual([]) + }) + + it('重置筛选清空条件并恢复全量行', () => { + categoryPageState.searchQuery = '技术' + categoryPageState.statusFilter = '0' + + categoryPageState.resetFilters() + + expect(categoryPageState.searchQuery).toBe('') + expect(categoryPageState.statusFilter).toBe(CATEGORY_STATUS_FILTER_ALL) + expect(filteredIds()).toEqual([1, 11, 2]) + }) + + it('筛选无命中时仍保留全量行,供空态区分无数据与无匹配', () => { + categoryPageState.searchQuery = '不存在的分类' + + expect(filteredIds()).toEqual([]) + expect(categoryPageState.hasCategories).toBe(true) + }) +}) + +describe('分类页状态:写操作', () => { + beforeEach(() => { + resetState() + categoryPageState.initialize({ tree: makeTree() }) + categoryApiMock.getTree.mockResolvedValue({ code: SUCCESS_CODE, data: { tree: makeTree() } }) + }) + + it('创建成功后提示并重新加载分类树', async () => { + categoryApiMock.create.mockResolvedValue({ code: SUCCESS_CODE, data: makeNode(9) }) + + const created = await categoryPageState.createCategory({ name: '新分类' }) + + expect(created).toBe(true) + expect(toastMock.success).toHaveBeenCalledWith('分类创建成功') + expect(categoryApiMock.getTree).toHaveBeenCalledTimes(1) + }) + + it('创建失败时提示后端文案且不刷新分类树', async () => { + categoryApiMock.create.mockResolvedValue({ code: 400, message: '分类名称已存在' }) + + const created = await categoryPageState.createCategory({ name: '重复' }) + + expect(created).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('分类名称已存在') + expect(categoryApiMock.getTree).not.toHaveBeenCalled() + }) + + it('更新成功后提示并重新加载分类树', async () => { + categoryApiMock.update.mockResolvedValue({ code: SUCCESS_CODE, data: makeNode(1) }) + + const updated = await categoryPageState.updateCategory({ id: 1, name: '改名' }) + + expect(updated).toBe(true) + expect(toastMock.success).toHaveBeenCalledWith('分类更新成功') + expect(categoryApiMock.getTree).toHaveBeenCalledTimes(1) + }) + + it('更新失败时提示后端文案且不刷新分类树', async () => { + categoryApiMock.update.mockResolvedValue({ code: 400, message: '分类不存在' }) + + const updated = await categoryPageState.updateCategory({ id: 1, name: '改名' }) + + expect(updated).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('分类不存在') + expect(categoryApiMock.getTree).not.toHaveBeenCalled() + }) + + it('删除成功后提示并重新加载分类树', async () => { + categoryApiMock.delete.mockResolvedValue({ code: SUCCESS_CODE }) + + const removed = await categoryPageState.removeCategory(2) + + expect(removed).toBe(true) + expect(toastMock.success).toHaveBeenCalledWith('分类删除成功') + expect(categoryApiMock.getTree).toHaveBeenCalledTimes(1) + }) + + // 存在子分类的删除由后端拒绝,前端必须原样转达后端文案且不刷新列表。 + it('删除被后端拒绝时提示后端文案且不刷新分类树', async () => { + categoryApiMock.delete.mockResolvedValue({ code: 400, message: '该分类下存在子分类,无法删除' }) + + const removed = await categoryPageState.removeCategory(1) + + expect(removed).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('该分类下存在子分类,无法删除') + expect(categoryApiMock.getTree).not.toHaveBeenCalled() + }) + + it('写操作请求抛错时提示网络错误且不刷新分类树', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + categoryApiMock.create.mockRejectedValue(new Error('断网')) + + const created = await categoryPageState.createCategory({ name: '新分类' }) + + expect(created).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith(NETWORK_ERROR_MESSAGE) + expect(categoryApiMock.getTree).not.toHaveBeenCalled() + consoleError.mockRestore() + }) +}) diff --git a/apps/admin/src/routes/(admin)/comments/+page.svelte b/apps/admin/src/routes/(admin)/comments/+page.svelte index 84813cd..508a0ae 100644 --- a/apps/admin/src/routes/(admin)/comments/+page.svelte +++ b/apps/admin/src/routes/(admin)/comments/+page.svelte @@ -1,172 +1,56 @@ @@ -176,14 +60,15 @@ onMount(loadComments) +
@@ -191,123 +76,69 @@ onMount(loadComments) type="single" variant="outline" size="sm" - value={statusFilter} - onValueChange={handleStatusFilterChange} + value={commentPageState.statusFilter} + onValueChange={value => commentPageState.setStatusFilter(value)} > {#each COMMENT_STATUS_OPTIONS as option (option.label)} {option.label} {/each} -
- {#if isLoading} + {#if commentPageState.isLoading}
- +
- {:else if comments.length === 0} -
-
- -
-
-

- {hasActiveFilters ? '没有匹配的评论' : '暂无评论'} -

-

- {hasActiveFilters ? '调整或重置筛选条件后再试' : '文章收到评论后会展示在这里'} -

-
- {#if hasActiveFilters} - + {:else if commentPageState.comments.length === 0} + + + + + + + {commentPageState.hasActiveFilters ? '没有匹配的评论' : '暂无评论'} + + + {commentPageState.hasActiveFilters + ? '调整或重置筛选条件后再试' + : '文章收到评论后会展示在这里'} + + + {#if commentPageState.hasActiveFilters} + + + {/if} -
+ {:else} - - - - 评论内容 - 评论者 - 所属文章 - 状态 - - 操作 - - - - {#each comments as comment (comment.id)} - - -

{comment.content}

-
- - {getAuthorName(comment)} - - - - {comment.article?.title ?? `#${comment.articleId}`} - - - - - {COMMENT_STATUS_CONFIG[comment.status].label} - - - - -
- - - - - - {#each COMMENT_ACTIONS[comment.status] as action (action)} - {@const ActionIcon = COMMENT_ACTION_ICONS[action]} - handleAction(comment, action)} - > - - {COMMENT_ACTION_LABELS[action]} - - {/each} - - -
-
-
- {/each} -
-
+
-

共 {total} 条评论

+

共 {commentPageState.total} 条评论

commentPageState.changePage(page)} > - 第 {currentPage} 页,共 {Math.max(1, Math.ceil(total / COMMENT_PAGE_SIZE))} 页 + 第 {commentPageState.currentPage} 页,共 {commentPageState.totalPages} 页 diff --git a/apps/admin/src/routes/(admin)/comments/+page.ts b/apps/admin/src/routes/(admin)/comments/+page.ts new file mode 100644 index 0000000..69f2609 --- /dev/null +++ b/apps/admin/src/routes/(admin)/comments/+page.ts @@ -0,0 +1,23 @@ +import type { PageLoad } from './$types' + +import { emptyCommentPageData } from './comment-page-state.svelte' +import { COMMENT_PAGE_SIZE } from '$lib/constants/comment' +import { CommentAPI } from '$lib/api' + +// 评论管理页初始数据:固定加载第一页且不带筛选条件,与页面初始筛选状态一致。 +// 加载失败时回退空数据并记录日志,由页面呈现空态,不中断路由。 +export const load: PageLoad = async () => { + const pageData = emptyCommentPageData() + + try { + const response = await CommentAPI.adminList({ page: 1, pageSize: COMMENT_PAGE_SIZE }) + if (response.code === 200 && response.data) { + pageData.comments = response.data.comments ?? [] + pageData.total = response.data.total ?? 0 + } + } catch (error) { + console.error('加载评论列表失败:', error) + } + + return pageData +} diff --git a/apps/admin/src/routes/(admin)/comments/comment-page-state.svelte.ts b/apps/admin/src/routes/(admin)/comments/comment-page-state.svelte.ts new file mode 100644 index 0000000..dc00adb --- /dev/null +++ b/apps/admin/src/routes/(admin)/comments/comment-page-state.svelte.ts @@ -0,0 +1,160 @@ +import type { + AdminComment, + CommentActionResponse, + CommentStatus +} from '@myblog/api/modules/comment/types' +import { + COMMENT_ACTION_LABELS, + COMMENT_PAGE_SIZE, + type CommentAction +} from '$lib/constants/comment' +import { debounce } from '@myblog/shared' +import { toast } from 'svelte-sonner' + +import { CommentAPI } from '$lib/api' + +// 搜索输入停顿时长,避免每次按键都触发请求。 +const SEARCH_DEBOUNCE_MS = 300 + +// 网络异常的统一提示文案。 +const NETWORK_ERROR_MESSAGE = '网络错误,请稍后重试' + +// 审核动作到接口方法的映射,spam 对应 markSpam 方法名。 +const ACTION_METHODS: Record< + Exclude, + (id: number) => Promise +> = { + approve: CommentAPI.approve, + reject: CommentAPI.reject, + spam: CommentAPI.markSpam, + trash: CommentAPI.trash +} + +// 除永久删除外的审核动作,删除需经页面确认对话框后另行提交。 +type CommentReviewAction = Exclude + +// 初始页面数据形状,由 +page.ts 的 load 函数提供。 +export interface CommentPageData { + comments: AdminComment[] + total: number +} + +// 空页面数据,load 失败时使用。 +export function emptyCommentPageData(): CommentPageData { + return { comments: [], total: 0 } +} + +// 评论管理页状态:集中持有列表、筛选条件与全部读写操作,页面组件只做渲染。 +class CommentPageState { + // 管理端列表在公开契约之上携带审计字段与文章归属,列表项按 AdminComment 声明。 + comments = $state([]) + total = $state(0) + currentPage = $state(1) + keyword = $state('') + // 状态筛选使用审核状态枚举值:空串为全部,与筛选选项中的空值项对应。 + statusFilter = $state('') + isLoading = $state(false) + + // 总页数,分页控件与页码文案共用同一口径;无评论时仍按一页展示。 + get totalPages(): number { + return Math.max(1, Math.ceil(this.total / COMMENT_PAGE_SIZE)) + } + + // 是否存在生效中的筛选条件,用于空态区分无数据与无匹配。 + get hasActiveFilters(): boolean { + return this.keyword.trim() !== '' || this.statusFilter !== '' + } + + // 用 load 结果初始化页面状态,重复挂载时以最新数据覆盖。 + initialize(data: CommentPageData) { + this.comments = data.comments + this.total = data.total + } + + // 加载评论列表,携带状态与关键词筛选。 + async loadComments() { + this.isLoading = true + try { + const response = await CommentAPI.adminList({ + page: this.currentPage, + pageSize: COMMENT_PAGE_SIZE, + ...(this.statusFilter ? { status: this.statusFilter } : {}), + ...(this.keyword.trim() ? { keyword: this.keyword.trim() } : {}) + }) + if (response.code === 200 && response.data) { + this.comments = response.data.comments ?? [] + this.total = response.data.total ?? 0 + } else { + toast.error(response.message || '加载评论失败') + } + } catch (error) { + console.error('加载评论失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + this.isLoading = false + } + } + + // 搜索词防抖应用,连续输入只在停顿后请求一次。 + applyKeywordDebounced = debounce(() => { + this.currentPage = 1 + void this.loadComments() + }, SEARCH_DEBOUNCE_MS) + + // 状态筛选变更后回到第一页并重新加载。 + setStatusFilter(value: string) { + this.statusFilter = value as CommentStatus | '' + this.currentPage = 1 + void this.loadComments() + } + + // 重置全部筛选条件并回到第一页。 + resetFilters() { + this.keyword = '' + this.statusFilter = '' + this.currentPage = 1 + void this.loadComments() + } + + // 切换页码并重新加载。 + changePage(page: number) { + this.currentPage = page + void this.loadComments() + } + + // 提交审核动作,成功后按动作文案提示并刷新列表。 + async runAction(comment: AdminComment, action: CommentReviewAction) { + try { + const response = await ACTION_METHODS[action](comment.id) + if (response.code === 200) { + toast.success(`${COMMENT_ACTION_LABELS[action]}成功`) + void this.loadComments() + } else { + toast.error(response.message || '操作失败') + } + } catch (error) { + console.error('评论操作失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + } + + // 永久删除评论,仅回收站内的评论可达该操作,成功后刷新当前页。 + async deleteComment(id: number): Promise { + try { + const response = await CommentAPI.delete(id) + if (response.code === 200) { + toast.success('评论删除成功') + void this.loadComments() + return true + } + toast.error(response.message || '删除评论失败') + } catch (error) { + console.error('删除评论失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } +} + +// 页面级共享状态实例。 +export const commentPageState = new CommentPageState() diff --git a/apps/admin/src/routes/(admin)/comments/comment-page-state.test.ts b/apps/admin/src/routes/(admin)/comments/comment-page-state.test.ts new file mode 100644 index 0000000..5a4afbd --- /dev/null +++ b/apps/admin/src/routes/(admin)/comments/comment-page-state.test.ts @@ -0,0 +1,332 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import type { AdminComment } from '@myblog/api/modules/comment/types' + +import { COMMENT_PAGE_SIZE } from '$lib/constants/comment' + +// 接口与提示均以替身注入,测试只验证页面状态的编排逻辑,不触达网络与界面。 +const commentApiMock = { + adminList: vi.fn(), + approve: vi.fn(), + reject: vi.fn(), + markSpam: vi.fn(), + trash: vi.fn(), + delete: vi.fn() +} + +const toastMock = { + success: vi.fn(), + error: vi.fn() +} + +vi.mock('$lib/api', () => ({ CommentAPI: commentApiMock })) +vi.mock('svelte-sonner', () => ({ toast: toastMock })) + +const { emptyCommentPageData, commentPageState } = await import('./comment-page-state.svelte') + +// 后端统一响应的成功业务码。 +const SUCCESS_CODE = 200 + +// 搜索防抖时长,与页面状态模块内的取值一致。 +const SEARCH_DEBOUNCE_MS = 300 + +// 构造一条评论替身,字段取值只覆盖被测逻辑关心的部分。 +function makeComment(id: number, status = 'pending'): AdminComment { + return { + id, + status, + content: `评论内容 ${id}`, + articleId: 9, + authorName: `游客${id}`, + createdAt: '2024-01-01T00:00:00.000Z' + } as unknown as AdminComment +} + +// 重置替身调用记录与页面状态,避免用例之间互相污染。 +function resetState() { + vi.clearAllMocks() + commentPageState.initialize(emptyCommentPageData()) + commentPageState.keyword = '' + commentPageState.statusFilter = '' + commentPageState.currentPage = 1 +} + +describe('评论页状态:初始化', () => { + beforeEach(resetState) + + it('用 load 结果填充列表与总数', () => { + const comments = [makeComment(1), makeComment(2)] + + commentPageState.initialize({ comments, total: 2 }) + + expect(commentPageState.comments).toEqual(comments) + expect(commentPageState.total).toBe(2) + }) + + it('空数据下无生效筛选条件且总页数按一页展示', () => { + expect(commentPageState.hasActiveFilters).toBe(false) + expect(commentPageState.totalPages).toBe(1) + }) + + // 空白关键词不构成筛选,避免只输入空格时误判为空态文案分支。 + it('关键词仅含空白字符时不视为生效筛选条件', () => { + commentPageState.keyword = ' ' + + expect(commentPageState.hasActiveFilters).toBe(false) + }) +}) + +describe('评论页状态:列表加载', () => { + beforeEach(resetState) + + it('默认只携带分页参数', async () => { + commentApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { comments: [makeComment(1)], total: 1 } + }) + + await commentPageState.loadComments() + + expect(commentApiMock.adminList).toHaveBeenCalledWith({ page: 1, pageSize: COMMENT_PAGE_SIZE }) + expect(commentPageState.comments).toHaveLength(1) + expect(commentPageState.total).toBe(1) + }) + + it('筛选条件生效时按状态与去空白关键词查询', async () => { + commentApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { comments: [], total: 0 } + }) + commentPageState.statusFilter = 'trash' + commentPageState.keyword = ' 测试 ' + commentPageState.currentPage = 3 + + await commentPageState.loadComments() + + expect(commentApiMock.adminList).toHaveBeenCalledWith({ + page: 3, + pageSize: COMMENT_PAGE_SIZE, + status: 'trash', + keyword: '测试' + }) + }) + + it('业务码非成功时提示后端文案且不清空现有列表', async () => { + commentApiMock.adminList.mockResolvedValue({ code: 500, message: '查询失败' }) + commentPageState.initialize({ comments: [makeComment(1)], total: 1 }) + + await commentPageState.loadComments() + + expect(toastMock.error).toHaveBeenCalledWith('查询失败') + expect(commentPageState.comments).toHaveLength(1) + }) + + it('请求抛错时提示网络错误并结束加载态', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + commentApiMock.adminList.mockRejectedValue(new Error('断网')) + + await commentPageState.loadComments() + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(commentPageState.isLoading).toBe(false) + consoleError.mockRestore() + }) +}) + +describe('评论页状态:筛选与分页', () => { + beforeEach(resetState) + + it('状态筛选变更后回到第一页并重新加载', async () => { + commentApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { comments: [], total: 0 } + }) + commentPageState.currentPage = 4 + + commentPageState.setStatusFilter('spam') + + await vi.waitFor(() => expect(commentApiMock.adminList).toHaveBeenCalledTimes(1)) + expect(commentPageState.statusFilter).toBe('spam') + expect(commentPageState.currentPage).toBe(1) + }) + + it('重置筛选清空全部条件并回到第一页', async () => { + commentApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { comments: [], total: 0 } + }) + commentPageState.keyword = '评论' + commentPageState.statusFilter = 'approved' + commentPageState.currentPage = 5 + + commentPageState.resetFilters() + + expect(commentPageState.keyword).toBe('') + expect(commentPageState.statusFilter).toBe('') + expect(commentPageState.currentPage).toBe(1) + expect(commentPageState.hasActiveFilters).toBe(false) + }) + + it('切换页码后按目标页加载并刷新总页数', async () => { + commentApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { comments: [], total: 50 } + }) + + commentPageState.changePage(2) + + await vi.waitFor(() => + expect(commentApiMock.adminList).toHaveBeenCalledWith({ + page: 2, + pageSize: COMMENT_PAGE_SIZE + }) + ) + expect(commentPageState.totalPages).toBe(5) + }) +}) + +describe('评论页状态:搜索防抖', () => { + beforeEach(() => { + resetState() + vi.useFakeTimers() + }) + + afterEach(() => { + vi.useRealTimers() + }) + + // 连续输入必须在停顿后只请求一次,且回到第一页,避免翻页后搜索命中空页。 + it('连续输入只在停顿后触发一次请求并回到第一页', () => { + commentApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { comments: [], total: 0 } + }) + commentPageState.currentPage = 3 + + commentPageState.applyKeywordDebounced() + commentPageState.applyKeywordDebounced() + expect(commentApiMock.adminList).not.toHaveBeenCalled() + + vi.advanceTimersByTime(SEARCH_DEBOUNCE_MS) + + expect(commentApiMock.adminList).toHaveBeenCalledTimes(1) + expect(commentPageState.currentPage).toBe(1) + }) +}) + +describe('评论页状态:审核操作', () => { + beforeEach(resetState) + + it('通过动作调用 approve 并提示成功、刷新列表', async () => { + commentApiMock.approve.mockResolvedValue({ code: SUCCESS_CODE }) + commentApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { comments: [], total: 0 } + }) + + await commentPageState.runAction(makeComment(1), 'approve') + + expect(commentApiMock.approve).toHaveBeenCalledWith(1) + expect(toastMock.success).toHaveBeenCalledWith('通过成功') + await vi.waitFor(() => expect(commentApiMock.adminList).toHaveBeenCalledTimes(1)) + }) + + it('拒绝动作调用 reject 并提示成功', async () => { + commentApiMock.reject.mockResolvedValue({ code: SUCCESS_CODE }) + commentApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { comments: [], total: 0 } + }) + + await commentPageState.runAction(makeComment(1), 'reject') + + expect(commentApiMock.reject).toHaveBeenCalledWith(1) + expect(toastMock.success).toHaveBeenCalledWith('拒绝成功') + }) + + it('标记垃圾动作走 markSpam 方法名', async () => { + commentApiMock.markSpam.mockResolvedValue({ code: SUCCESS_CODE }) + commentApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { comments: [], total: 0 } + }) + + await commentPageState.runAction(makeComment(1), 'spam') + + expect(commentApiMock.markSpam).toHaveBeenCalledWith(1) + expect(toastMock.success).toHaveBeenCalledWith('标记垃圾成功') + }) + + it('移入回收站动作调用 trash 并提示成功', async () => { + commentApiMock.trash.mockResolvedValue({ code: SUCCESS_CODE }) + commentApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { comments: [], total: 0 } + }) + + await commentPageState.runAction(makeComment(1), 'trash') + + expect(commentApiMock.trash).toHaveBeenCalledWith(1) + expect(toastMock.success).toHaveBeenCalledWith('移入回收站成功') + }) + + it('业务码非成功时提示后端文案且不刷新列表', async () => { + commentApiMock.approve.mockResolvedValue({ code: 403, message: '无权操作该评论' }) + + await commentPageState.runAction(makeComment(1), 'approve') + + expect(toastMock.error).toHaveBeenCalledWith('无权操作该评论') + expect(toastMock.success).not.toHaveBeenCalled() + expect(commentApiMock.adminList).not.toHaveBeenCalled() + }) + + it('请求抛错时提示网络错误且不刷新列表', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + commentApiMock.approve.mockRejectedValue(new Error('断网')) + + await commentPageState.runAction(makeComment(1), 'approve') + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(commentApiMock.adminList).not.toHaveBeenCalled() + consoleError.mockRestore() + }) +}) + +describe('评论页状态:删除', () => { + beforeEach(resetState) + + it('删除成功后提示并刷新列表', async () => { + commentApiMock.delete.mockResolvedValue({ code: SUCCESS_CODE }) + commentApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { comments: [], total: 0 } + }) + + const removed = await commentPageState.deleteComment(1) + + expect(removed).toBe(true) + expect(commentApiMock.delete).toHaveBeenCalledWith(1) + expect(toastMock.success).toHaveBeenCalledWith('评论删除成功') + await vi.waitFor(() => expect(commentApiMock.adminList).toHaveBeenCalledTimes(1)) + }) + + it('删除失败时提示后端文案且不刷新列表', async () => { + commentApiMock.delete.mockResolvedValue({ code: 404, message: '评论不存在' }) + + const removed = await commentPageState.deleteComment(1) + + expect(removed).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('评论不存在') + expect(commentApiMock.adminList).not.toHaveBeenCalled() + }) + + it('删除请求抛错时提示网络错误并返回失败', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + commentApiMock.delete.mockRejectedValue(new Error('断网')) + + const removed = await commentPageState.deleteComment(1) + + expect(removed).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + consoleError.mockRestore() + }) +}) diff --git a/apps/admin/src/routes/(admin)/dicts/+page.svelte b/apps/admin/src/routes/(admin)/dicts/+page.svelte index b5f9419..d32007a 100644 --- a/apps/admin/src/routes/(admin)/dicts/+page.svelte +++ b/apps/admin/src/routes/(admin)/dicts/+page.svelte @@ -7,20 +7,22 @@ import type { UpdateDictItemRequest, UpdateDictTypeRequest } from '@myblog/api/modules/dict/types' -import { BookText, ListTree, Pencil, Plus, Trash2 } from '@lucide/svelte' import { SITE_NAME_ZH } from '@myblog/shared' +import { Plus } from '@lucide/svelte' import { Button } from '$ui/button' -import * as Table from '$ui/table' -import { Badge } from '$ui/badge' -import * as Card from '$ui/card' import DictTypeFormDialog from '$lib/components/admin/dict/dict-type-form-dialog.svelte' import DictItemFormDialog from '$lib/components/admin/dict/dict-item-form-dialog.svelte' +import DictItemTable from '$lib/components/admin/dict/dict-item-table.svelte' +import DictTypeList from '$lib/components/admin/dict/dict-type-list.svelte' import { dictPageState, emptyDictPageData } from './dict-page-state.svelte' import ConfirmDialog from '$lib/components/admin/confirm-dialog.svelte' import PageHeader from '$lib/components/admin/page-header.svelte' import type { PageProps } from './$types' +// 删除确认的目标,种类决定分发到类型删除还是字典项删除。 +type DeleteTarget = { kind: 'type' | 'item'; id: number; name: string } + let { data }: PageProps = $props() // 初始数据经 load 注入后交给页面状态模块接管,组件只做渲染与交互分发。 @@ -31,29 +33,32 @@ $effect(() => { dictPageState.initialize(data ?? emptyDictPageData()) }) -// 字典生效状态的展示配置,本页为字典体系自身的管理界面,直接使用其内置枚举。 -const DICT_STATUS_CONFIG: Record = { - 1: { label: '生效', variant: 'default' }, - 0: { label: '停用', variant: 'secondary' } -} - // 弹窗与删除确认状态 let isTypeDialogOpen = $state(false) let typeDialogTarget = $state(null) let isItemDialogOpen = $state(false) let itemDialogTarget = $state(null) let isSubmitting = $state(false) -let deleteTarget = $state<{ kind: 'type' | 'item'; id: number; name: string } | null>(null) +let deleteTarget = $state(null) + +// 打开字典类型弹窗,目标为空表示新建。 +function openTypeDialog(target: DictType | null) { + typeDialogTarget = target + isTypeDialogOpen = true +} -// 新建字典项前必须选中一个字典类型。 -function openCreateItem() { - if (!dictPageState.selectedType) { - return - } - itemDialogTarget = null +// 打开字典项弹窗,新建前必须已选中字典类型。 +function openItemDialog(target: DictItem | null) { + if (!target && !dictPageState.selectedType) return + itemDialogTarget = target isItemDialogOpen = true } +// 记录待删除目标,弹窗提交后按种类分发。 +function openDeleteDialog(kind: 'type' | 'item', id: number, name: string) { + deleteTarget = { kind, id, name } +} + // 提交字典类型表单,新建与编辑分别调用对应写操作。 // 弹窗载荷为动态键值结构,与既有表单弹窗约定一致地经类型断言收窄。 async function handleTypeConfirm(payload: Record) { @@ -109,206 +114,31 @@ async function handleDelete() { crumb="字典管理" > {#snippet actions()} - {/snippet}
- - - - - 字典类型 - - - - {#if dictPageState.isLoadingTypes} -
- -
- {:else if dictPageState.types.length === 0} -
-
- -
-
-

暂无字典类型

-

创建第一个字典类型开始使用

-
- -
- {:else} -
    - {#each dictPageState.types as type (type.id)} -
  • - - - -
- - - {/each} - - {/if} - - - - - - - 字典项 - {#if dictPageState.selectedType} - - {dictPageState.selectedType.code} - - {/if} - - - - - {#if !dictPageState.selectedType} -
-

请先选择字典类型

-
- {:else if dictPageState.isLoadingItems} -
- -
- {:else if dictPageState.items.length === 0} -
-
- -
-
-

暂无字典项

-

为当前字典类型添加可选值

-
- -
- {:else} - - - - 值 - 显示名 - - 排序 - 状态 - 操作 - - - - {#each dictPageState.items as item (item.id)} - - - - {item.value} - - - - {item.label} - - - - {item.sortOrder} - - - - {DICT_STATUS_CONFIG[item.status]?.label ?? '未知'} - - - -
- - -
-
-
- {/each} -
-
- {/if} -
-
+ void dictPageState.selectType(id)} + onEdit={type => openTypeDialog(type)} + onDelete={type => openDeleteDialog('type', type.id, type.name)} + onCreate={() => openTypeDialog(null)} + /> + + openItemDialog(null)} + onEdit={item => openItemDialog(item)} + onDelete={item => openDeleteDialog('item', item.id, item.label)} + />
-import { - Plus, - MoreHorizontal, - Pencil, - Trash2, - Link as LinkIcon, - CircleCheck, - CircleX, - EyeOff, - RotateCcw, - type LucideIcon -} from '@lucide/svelte' import type { CreateFriendlyLinkRequest, FriendlyLink, - LinkStatus, UpdateFriendlyLinkRequest } from '@myblog/api/modules/friendlyLink/types' -import { LINK_PAGE_SIZE, LINK_STATUS_CONFIG, LINK_STATUS_OPTIONS } from '$lib/constants/link' import LinkFormDialog from '$lib/components/admin/link/link-form-dialog.svelte' +import { linkPageState, emptyLinkPageData } from './link-page-state.svelte' +import { LINK_PAGE_SIZE, LINK_STATUS_OPTIONS } from '$lib/constants/link' import ConfirmDialog from '$lib/components/admin/confirm-dialog.svelte' +import LinkTable from '$lib/components/admin/link/link-table.svelte' +import { Plus, RotateCcw, Link as LinkIcon } from '@lucide/svelte' import PageHeader from '$lib/components/admin/page-header.svelte' -import * as DropdownMenu from '$ui/dropdown-menu' import * as ToggleGroup from '$ui/toggle-group' import { SITE_NAME_ZH } from '@myblog/shared' import * as Pagination from '$ui/pagination' -import { FriendlyLinkAPI } from '$lib/api' +import type { PageProps } from './$types' +import { Spinner } from '$ui/spinner' import { Button } from '$ui/button' -import * as Table from '$ui/table' -import { Badge } from '$ui/badge' +import * as Empty from '$ui/empty' import * as Card from '$ui/card' -import { onMount } from 'svelte' -// 各状态下可执行的审核动作,icon 供下拉菜单项渲染语义图标。 -const STATUS_ACTIONS: Record< - LinkStatus, - Array<{ key: 'approve' | 'hide' | 'reject'; label: string; icon: LucideIcon }> -> = { - pending: [ - { key: 'approve', label: '通过', icon: CircleCheck }, - { key: 'reject', label: '拒绝', icon: CircleX } - ], - active: [{ key: 'hide', label: '下架', icon: EyeOff }], - hidden: [ - { key: 'approve', label: '重新上架', icon: CircleCheck }, - { key: 'reject', label: '拒绝', icon: CircleX } - ], - rejected: [{ key: 'approve', label: '重新上架', icon: CircleCheck }] -} +let { data }: PageProps = $props() -let links = $state([]) -let isLoading = $state(true) -let total = $state(0) -let currentPage = $state(1) -let statusFilter = $state('') +// 初始数据经 load 注入后交给页面状态模块接管,组件只做渲染与交互分发。 +let initialized = false +$effect(() => { + if (initialized) return + initialized = true + linkPageState.initialize(data ?? emptyLinkPageData()) +}) +// 弹窗与删除确认状态 let isDialogOpen = $state(false) let dialogTarget = $state(null) let deleteTarget = $state(null) let isDeleting = $state(false) let isSubmitting = $state(false) -// 是否存在生效中的筛选条件,用于空态区分「无数据」与「无匹配」。 -const hasActiveFilters = $derived(statusFilter !== '') - -/** - * 加载友链列表。 - */ -async function loadLinks() { - isLoading = true - try { - const response = await FriendlyLinkAPI.adminList({ - page: currentPage, - pageSize: LINK_PAGE_SIZE, - ...(statusFilter ? { status: statusFilter } : {}) - }) - if (response.code === 200 && response.data) { - links = response.data.links ?? [] - total = response.data.total ?? 0 - } else { - toast.error(response.message || '加载友链失败') - } - } catch (error) { - console.error('加载友链失败:', error) - toast.error('网络错误,请稍后重试') - } finally { - isLoading = false - } -} - -/** - * 状态筛选变更后立即回到第一页并重新加载。 - */ -function handleStatusFilterChange(value: string) { - statusFilter = value as LinkStatus | '' - currentPage = 1 - loadLinks() -} - -/** - * 重置筛选并回到第一页。 - */ -function resetAndReload() { - statusFilter = '' - currentPage = 1 - loadLinks() -} - -/** - * 打开添加友链弹窗。 - */ -function openCreateDialog() { - dialogTarget = null +// 打开友链弹窗,目标为空表示新建。 +function openDialog(target: FriendlyLink | null) { + dialogTarget = target isDialogOpen = true } -/** - * 提交友链表单,新建与编辑分别调用对应接口。 - */ +// 提交友链表单,新建与编辑分别调用对应写操作。 +// 弹窗载荷为动态键值结构,与既有表单弹窗约定一致地经类型断言收窄。 async function handleConfirm(payload: Record) { if (isSubmitting) return isSubmitting = true - try { - const response = dialogTarget - ? await FriendlyLinkAPI.update({ - id: dialogTarget.id, - ...payload - } as UpdateFriendlyLinkRequest) - : await FriendlyLinkAPI.create(payload as unknown as CreateFriendlyLinkRequest) - if (response.code === 200 && response.data) { - toast.success(dialogTarget ? '友链更新成功' : '友链添加成功') - isDialogOpen = false - loadLinks() - } else { - toast.error(response.message || '保存友链失败') - } - } catch (error) { - console.error('保存友链失败:', error) - toast.error('网络错误,请稍后重试') - } finally { - isSubmitting = false - } + const success = dialogTarget + ? await linkPageState.updateLink({ + id: dialogTarget.id, + ...payload + } as UpdateFriendlyLinkRequest) + : await linkPageState.createLink(payload as unknown as CreateFriendlyLinkRequest) + isSubmitting = false + if (success) isDialogOpen = false } -/** - * 执行友链审核动作。 - */ -async function handleStatusAction(link: FriendlyLink, key: 'approve' | 'hide' | 'reject') { - try { - const response = await FriendlyLinkAPI[key](link.id) - if (response.code === 200) { - toast.success(`${STATUS_ACTIONS[link.status].find(item => item.key === key)?.label}成功`) - loadLinks() - } else { - toast.error(response.message || '操作失败') - } - } catch (error) { - console.error('友链操作失败:', error) - toast.error('网络错误,请稍后重试') - } -} - -/** - * 删除友链。 - */ +// 确认后删除目标友链。 async function handleDelete() { if (!deleteTarget || isDeleting) return isDeleting = true - try { - const response = await FriendlyLinkAPI.delete(deleteTarget.id) - if (response.code === 200) { - toast.success('友链删除成功') - deleteTarget = null - loadLinks() - } else { - toast.error(response.message || '删除友链失败') - } - } catch (error) { - console.error('删除友链失败:', error) - toast.error('网络错误,请稍后重试') - } finally { - isDeleting = false - } -} - -function handlePageChange(page: number) { - currentPage = page - loadLinks() + const success = await linkPageState.removeLink(deleteTarget.id) + isDeleting = false + if (success) deleteTarget = null } - -onMount(loadLinks) @@ -198,7 +74,7 @@ onMount(loadLinks) {#snippet actions()} - @@ -206,173 +82,85 @@ onMount(loadLinks) +
linkPageState.setStatusFilter(value)} > {#each LINK_STATUS_OPTIONS as option (option.label)} {option.label} {/each} -
- {#if isLoading} + {#if linkPageState.isLoading}
- +
- {:else if links.length === 0} -
-
- -
-
-

- {hasActiveFilters ? '没有匹配的友链' : '暂无友链'} -

-

- {hasActiveFilters + {:else if linkPageState.links.length === 0} + + + + + + + {linkPageState.hasActiveFilters ? '没有匹配的友链' : '暂无友链'} + + + {linkPageState.hasActiveFilters ? '调整或重置筛选条件后再试' : '添加第一条友情链接,与友邻站点互相推荐'} -

-
- {#if hasActiveFilters} - - {:else} - - {/if} -
+ + + + {#if linkPageState.hasActiveFilters} + + {:else} + + {/if} + + {:else} - - - - 站点 - 描述 - 回链 - 状态 - 添加时间 - 操作 - - - - {#each links as link (link.id)} - - -
- {#if link.logo} - {link.name} - {/if} -
-

{link.name}

- -
-
-
- - - {link.description || '—'} - - - - {#if link.isReciprocal} - 已回链 - {:else} - — - {/if} - - - - {LINK_STATUS_CONFIG[link.status].label} - - - - - {new Date(link.createdAt).toLocaleDateString('zh-CN')} - - - -
- - - - - - - {#each STATUS_ACTIONS[link.status] as action (action.key)} - {@const ActionIcon = action.icon} - handleStatusAction(link, action.key)}> - - {action.label} - - {/each} - (deleteTarget = link)} - > - - 删除 - - - -
-
-
- {/each} -
-
+ openDialog(link)} + onReview={(link, key) => void linkPageState.reviewLink(link, key)} + onDelete={link => (deleteTarget = link)} + />
-

共 {total} 个友链

+

共 {linkPageState.total} 个友链

linkPageState.changePage(page)} > - 第 {currentPage} 页,共 {Math.max(1, Math.ceil(total / LINK_PAGE_SIZE))} 页 + 第 {linkPageState.currentPage} 页,共 {linkPageState.totalPages} 页 diff --git a/apps/admin/src/routes/(admin)/links/+page.ts b/apps/admin/src/routes/(admin)/links/+page.ts new file mode 100644 index 0000000..5692770 --- /dev/null +++ b/apps/admin/src/routes/(admin)/links/+page.ts @@ -0,0 +1,25 @@ +import type { PageLoad } from './$types' + +import { emptyLinkPageData } from './link-page-state.svelte' +import { LINK_PAGE_SIZE } from '$lib/constants/link' +import { FriendlyLinkAPI } from '$lib/api' + +// 友链管理页初始数据:首屏第一页列表,筛选条件为空。 +// 页面由 load 注入的数据渲染,加载失败回退空数据并记录日志,不阻断页面挂载。 +export const load: PageLoad = async () => { + const pageData = emptyLinkPageData() + + try { + const response = await FriendlyLinkAPI.adminList({ page: 1, pageSize: LINK_PAGE_SIZE }) + if (response.code === 200 && response.data) { + pageData.links = response.data.links ?? [] + pageData.total = response.data.total ?? 0 + } else { + console.error('加载友链列表失败:', response.message) + } + } catch (error) { + console.error('加载友链列表失败:', error) + } + + return pageData +} diff --git a/apps/admin/src/routes/(admin)/links/link-page-state.svelte.ts b/apps/admin/src/routes/(admin)/links/link-page-state.svelte.ts new file mode 100644 index 0000000..e803590 --- /dev/null +++ b/apps/admin/src/routes/(admin)/links/link-page-state.svelte.ts @@ -0,0 +1,166 @@ +import type { + CreateFriendlyLinkRequest, + FriendlyLink, + LinkStatus, + UpdateFriendlyLinkRequest +} from '@myblog/api/modules/friendlyLink/types' +import { toast } from 'svelte-sonner' + +import { LINK_PAGE_SIZE, LINK_STATUS_ACTIONS, type LinkStatusAction } from '$lib/constants/link' +import { FriendlyLinkAPI } from '$lib/api' + +// 网络异常的统一提示文案。 +const NETWORK_ERROR_MESSAGE = '网络错误,请稍后重试' + +// 初始页面数据形状,由 +page.ts 的 load 函数提供。 +export interface LinkPageData { + links: FriendlyLink[] + total: number +} + +// 空页面数据,load 失败时使用。 +export function emptyLinkPageData(): LinkPageData { + return { links: [], total: 0 } +} + +// 友链管理页状态:集中持有列表、筛选条件与全部读写操作,页面组件只做渲染。 +class LinkPageState { + links = $state([]) + total = $state(0) + currentPage = $state(1) + // 状态筛选使用字符串值:空串为全部,其余为友链状态枚举值。 + statusFilter = $state('') + // 初始数据由 load 提供,首次渲染不需要加载态。 + isLoading = $state(false) + + // 总页数,分页控件与页码文案共用同一口径。 + get totalPages(): number { + return Math.max(1, Math.ceil(this.total / LINK_PAGE_SIZE)) + } + + // 是否存在生效中的筛选条件,用于空态区分无数据与无匹配。 + get hasActiveFilters(): boolean { + return this.statusFilter !== '' + } + + // 用 load 结果初始化页面状态,重复挂载时以最新数据覆盖。 + initialize(data: LinkPageData) { + this.links = data.links + this.total = data.total + } + + // 加载友链列表,携带当前页码与状态筛选,未筛选时不传 status 字段。 + async loadLinks() { + this.isLoading = true + try { + const response = await FriendlyLinkAPI.adminList({ + page: this.currentPage, + pageSize: LINK_PAGE_SIZE, + ...(this.statusFilter ? { status: this.statusFilter } : {}) + }) + if (response.code === 200 && response.data) { + this.links = response.data.links ?? [] + this.total = response.data.total ?? 0 + } else { + toast.error(response.message || '加载友链失败') + } + } catch (error) { + console.error('加载友链失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + this.isLoading = false + } + } + + // 状态筛选变更后回到第一页并重新加载。 + setStatusFilter(value: string) { + this.statusFilter = value as LinkStatus | '' + this.currentPage = 1 + void this.loadLinks() + } + + // 重置筛选条件并回到第一页。 + resetAndReload() { + this.statusFilter = '' + this.currentPage = 1 + void this.loadLinks() + } + + // 切换页码并重新加载。 + changePage(page: number) { + this.currentPage = page + void this.loadLinks() + } + + // 创建友链,成功后刷新当前页。 + async createLink(payload: CreateFriendlyLinkRequest): Promise { + try { + const response = await FriendlyLinkAPI.create(payload) + if (response.code === 200 && response.data) { + toast.success('友链添加成功') + await this.loadLinks() + return true + } + toast.error(response.message || '保存友链失败') + } catch (error) { + console.error('保存友链失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } + + // 更新友链,成功后刷新当前页。 + async updateLink(payload: UpdateFriendlyLinkRequest): Promise { + try { + const response = await FriendlyLinkAPI.update(payload) + if (response.code === 200 && response.data) { + toast.success('友链更新成功') + await this.loadLinks() + return true + } + toast.error(response.message || '保存友链失败') + } catch (error) { + console.error('保存友链失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } + + // 执行审核动作,成功提示由该动作在当前状态下的文案拼接,随后刷新列表。 + async reviewLink(link: FriendlyLink, key: LinkStatusAction): Promise { + try { + const response = await FriendlyLinkAPI[key](link.id) + if (response.code === 200) { + const actionLabel = LINK_STATUS_ACTIONS[link.status].find(item => item.key === key)?.label + toast.success(`${actionLabel}成功`) + await this.loadLinks() + return true + } + toast.error(response.message || '操作失败') + } catch (error) { + console.error('友链操作失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } + + // 删除友链,成功判定只要求业务码,响应无数据同样视为完成。 + async removeLink(id: number): Promise { + try { + const response = await FriendlyLinkAPI.delete(id) + if (response.code === 200) { + toast.success('友链删除成功') + await this.loadLinks() + return true + } + toast.error(response.message || '删除友链失败') + } catch (error) { + console.error('删除友链失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } +} + +// 页面级共享状态实例。 +export const linkPageState = new LinkPageState() diff --git a/apps/admin/src/routes/(admin)/links/link-page-state.test.ts b/apps/admin/src/routes/(admin)/links/link-page-state.test.ts new file mode 100644 index 0000000..cc78909 --- /dev/null +++ b/apps/admin/src/routes/(admin)/links/link-page-state.test.ts @@ -0,0 +1,329 @@ +import type { FriendlyLink, LinkStatus } from '@myblog/api/modules/friendlyLink/types' +import { beforeEach, describe, expect, it, vi } from 'vitest' + +import { LINK_PAGE_SIZE } from '$lib/constants/link' + +// 接口与提示均以替身注入,测试只验证页面状态的编排逻辑,不触达网络与界面。 +const friendlyLinkApiMock = { + adminList: vi.fn(), + create: vi.fn(), + update: vi.fn(), + delete: vi.fn(), + approve: vi.fn(), + hide: vi.fn(), + reject: vi.fn() +} + +const toastMock = { + success: vi.fn(), + error: vi.fn() +} + +vi.mock('$lib/api', () => ({ FriendlyLinkAPI: friendlyLinkApiMock })) +vi.mock('svelte-sonner', () => ({ toast: toastMock })) + +const { emptyLinkPageData, linkPageState } = await import('./link-page-state.svelte') + +// 后端统一响应的成功业务码。 +const SUCCESS_CODE = 200 + +// 构造一个友链替身,字段取值只覆盖被测逻辑关心的部分。 +function makeLink(id: number, status: LinkStatus = 'pending', name = `友链${id}`): FriendlyLink { + return { + id, + name, + status, + url: `https://link-${id}.example.com` + } as unknown as FriendlyLink +} + +// 重置替身调用记录与页面状态,避免用例之间互相污染。 +function resetState() { + vi.clearAllMocks() + linkPageState.initialize(emptyLinkPageData()) + linkPageState.statusFilter = '' + linkPageState.currentPage = 1 +} + +describe('友链页状态:初始化', () => { + beforeEach(resetState) + + it('用 load 结果填充列表与总数', () => { + const links = [makeLink(1), makeLink(2, 'active')] + + linkPageState.initialize({ links, total: 2 }) + + expect(linkPageState.links).toEqual(links) + expect(linkPageState.total).toBe(2) + }) + + it('空数据下无生效筛选条件且总页数为 1', () => { + expect(linkPageState.hasActiveFilters).toBe(false) + expect(linkPageState.totalPages).toBe(1) + }) +}) + +describe('友链页状态:列表加载', () => { + beforeEach(resetState) + + it('默认只携带分页参数', async () => { + friendlyLinkApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { links: [makeLink(1)], total: 1 } + }) + + await linkPageState.loadLinks() + + expect(friendlyLinkApiMock.adminList).toHaveBeenCalledWith({ + page: 1, + pageSize: LINK_PAGE_SIZE + }) + expect(linkPageState.links).toHaveLength(1) + expect(linkPageState.total).toBe(1) + }) + + it('筛选生效时携带状态与当前页码', async () => { + friendlyLinkApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { links: [], total: 0 } + }) + linkPageState.statusFilter = 'hidden' + linkPageState.currentPage = 2 + + await linkPageState.loadLinks() + + expect(friendlyLinkApiMock.adminList).toHaveBeenCalledWith({ + page: 2, + pageSize: LINK_PAGE_SIZE, + status: 'hidden' + }) + }) + + it('业务码非成功时提示后端文案且不清空现有列表', async () => { + friendlyLinkApiMock.adminList.mockResolvedValue({ code: 500, message: '查询失败' }) + linkPageState.initialize({ links: [makeLink(1)], total: 1 }) + + await linkPageState.loadLinks() + + expect(toastMock.error).toHaveBeenCalledWith('查询失败') + expect(linkPageState.links).toHaveLength(1) + }) + + it('请求抛错时提示网络错误并复位加载态', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + friendlyLinkApiMock.adminList.mockRejectedValue(new Error('断网')) + + await linkPageState.loadLinks() + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(linkPageState.isLoading).toBe(false) + consoleError.mockRestore() + }) +}) + +describe('友链页状态:筛选与分页', () => { + beforeEach(resetState) + + it('状态筛选变更后回到第一页并重新加载', async () => { + friendlyLinkApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { links: [], total: 0 } + }) + linkPageState.currentPage = 4 + + linkPageState.setStatusFilter('active') + + await vi.waitFor(() => + expect(friendlyLinkApiMock.adminList).toHaveBeenCalledWith({ + page: 1, + pageSize: LINK_PAGE_SIZE, + status: 'active' + }) + ) + expect(linkPageState.currentPage).toBe(1) + expect(linkPageState.hasActiveFilters).toBe(true) + }) + + it('重置筛选清空条件并回到第一页', async () => { + friendlyLinkApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { links: [], total: 0 } + }) + linkPageState.statusFilter = 'rejected' + linkPageState.currentPage = 5 + + linkPageState.resetAndReload() + + expect(linkPageState.statusFilter).toBe('') + expect(linkPageState.currentPage).toBe(1) + expect(linkPageState.hasActiveFilters).toBe(false) + await vi.waitFor(() => + expect(friendlyLinkApiMock.adminList).toHaveBeenCalledWith({ + page: 1, + pageSize: LINK_PAGE_SIZE + }) + ) + }) + + it('切换页码后按目标页加载且总页数向上取整', async () => { + friendlyLinkApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { links: [], total: 21 } + }) + + linkPageState.changePage(3) + + await vi.waitFor(() => + expect(friendlyLinkApiMock.adminList).toHaveBeenCalledWith({ + page: 3, + pageSize: LINK_PAGE_SIZE + }) + ) + expect(linkPageState.totalPages).toBe(3) + }) +}) + +describe('友链页状态:写操作', () => { + beforeEach(resetState) + + it('创建成功后提示并刷新列表', async () => { + friendlyLinkApiMock.create.mockResolvedValue({ code: SUCCESS_CODE, data: makeLink(9) }) + friendlyLinkApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { links: [], total: 0 } + }) + + const created = await linkPageState.createLink({ name: '新友链' } as never) + + expect(created).toBe(true) + expect(toastMock.success).toHaveBeenCalledWith('友链添加成功') + expect(friendlyLinkApiMock.adminList).toHaveBeenCalledTimes(1) + }) + + it('创建失败时提示后端文案且不刷新列表', async () => { + friendlyLinkApiMock.create.mockResolvedValue({ code: 400, message: '站点链接已存在' }) + + const created = await linkPageState.createLink({ name: '重复' } as never) + + expect(created).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('站点链接已存在') + expect(friendlyLinkApiMock.adminList).not.toHaveBeenCalled() + }) + + it('更新成功后提示并刷新列表', async () => { + friendlyLinkApiMock.update.mockResolvedValue({ code: SUCCESS_CODE, data: makeLink(1) }) + friendlyLinkApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { links: [], total: 0 } + }) + + const updated = await linkPageState.updateLink({ id: 1, name: '改名' } as never) + + expect(updated).toBe(true) + expect(toastMock.success).toHaveBeenCalledWith('友链更新成功') + expect(friendlyLinkApiMock.adminList).toHaveBeenCalledTimes(1) + }) + + it('更新抛错时提示网络错误且不刷新列表', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + friendlyLinkApiMock.update.mockRejectedValue(new Error('断网')) + + const updated = await linkPageState.updateLink({ id: 1, name: '改名' } as never) + + expect(updated).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(friendlyLinkApiMock.adminList).not.toHaveBeenCalled() + consoleError.mockRestore() + }) + + it('删除只要求业务码,成功时提示并刷新列表', async () => { + friendlyLinkApiMock.delete.mockResolvedValue({ code: SUCCESS_CODE }) + friendlyLinkApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { links: [], total: 0 } + }) + + const removed = await linkPageState.removeLink(1) + + expect(removed).toBe(true) + expect(friendlyLinkApiMock.delete).toHaveBeenCalledWith(1) + expect(toastMock.success).toHaveBeenCalledWith('友链删除成功') + expect(friendlyLinkApiMock.adminList).toHaveBeenCalledTimes(1) + }) + + it('删除失败时提示后端文案且不刷新列表', async () => { + friendlyLinkApiMock.delete.mockResolvedValue({ code: 400, message: '删除友链失败' }) + + const removed = await linkPageState.removeLink(1) + + expect(removed).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('删除友链失败') + expect(friendlyLinkApiMock.adminList).not.toHaveBeenCalled() + }) +}) + +describe('友链页状态:审核操作', () => { + beforeEach(resetState) + + it('待审核友链通过后提示通过并刷新列表', async () => { + friendlyLinkApiMock.approve.mockResolvedValue({ code: SUCCESS_CODE }) + friendlyLinkApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { links: [], total: 0 } + }) + + const reviewed = await linkPageState.reviewLink(makeLink(1, 'pending'), 'approve') + + expect(reviewed).toBe(true) + expect(friendlyLinkApiMock.approve).toHaveBeenCalledWith(1) + expect(toastMock.success).toHaveBeenCalledWith('通过成功') + expect(friendlyLinkApiMock.adminList).toHaveBeenCalledTimes(1) + }) + + it('已隐藏友链重新上架后提示重新上架', async () => { + friendlyLinkApiMock.approve.mockResolvedValue({ code: SUCCESS_CODE }) + friendlyLinkApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { links: [], total: 0 } + }) + + await linkPageState.reviewLink(makeLink(1, 'hidden'), 'approve') + + expect(toastMock.success).toHaveBeenCalledWith('重新上架成功') + }) + + it('展示中友链下架后提示下架', async () => { + friendlyLinkApiMock.hide.mockResolvedValue({ code: SUCCESS_CODE }) + friendlyLinkApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { links: [], total: 0 } + }) + + const reviewed = await linkPageState.reviewLink(makeLink(1, 'active'), 'hide') + + expect(reviewed).toBe(true) + expect(friendlyLinkApiMock.hide).toHaveBeenCalledWith(1) + expect(toastMock.success).toHaveBeenCalledWith('下架成功') + }) + + it('审核业务码非成功时提示后端文案且不刷新列表', async () => { + friendlyLinkApiMock.reject.mockResolvedValue({ code: 400, message: '状态不允许该操作' }) + + const reviewed = await linkPageState.reviewLink(makeLink(1, 'pending'), 'reject') + + expect(reviewed).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('状态不允许该操作') + expect(friendlyLinkApiMock.adminList).not.toHaveBeenCalled() + }) + + it('审核请求抛错时提示网络错误', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + friendlyLinkApiMock.approve.mockRejectedValue(new Error('断网')) + + const reviewed = await linkPageState.reviewLink(makeLink(1, 'pending'), 'approve') + + expect(reviewed).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + consoleError.mockRestore() + }) +}) diff --git a/apps/admin/src/routes/(admin)/media/+page.svelte b/apps/admin/src/routes/(admin)/media/+page.svelte index 671fc96..91931c5 100644 --- a/apps/admin/src/routes/(admin)/media/+page.svelte +++ b/apps/admin/src/routes/(admin)/media/+page.svelte @@ -1,170 +1,60 @@ @@ -177,11 +67,11 @@ onMount(loadMedia) bind:this={fileInput} type="file" class="hidden" - accept="image/*,video/*,audio/*,application/pdf,text/*" + accept={MEDIA_FILE_ACCEPT} onchange={handleUpload} /> -
- {#if isLoading} + {#if mediaPageState.isLoading}
- +
- {:else if media.length === 0} -
-
- -
-
-

- {hasActiveFilters ? '没有匹配的文件' : '暂无媒体文件'} -

-

- {hasActiveFilters + {:else if mediaPageState.media.length === 0} + + + + + + + {mediaPageState.hasActiveFilters ? '没有匹配的文件' : '暂无媒体文件'} + + + {mediaPageState.hasActiveFilters ? '调整或重置筛选条件后再试' : '上传第一个文件,丰富博客的图片与素材'} -

-
- {#if hasActiveFilters} - - {:else} - - {/if} -
+ + + + {#if mediaPageState.hasActiveFilters} + + {:else} + + {/if} + + {:else} -
- {#each media as file (file.id)} -
-
- {#if file.mimeType.startsWith('image/')} - {file.filename} - {:else} - {@const IconComponent = typeIcon(file)} - - {/if} -
-
-

{file.filename}

-

- {getFileSize(file.fileSize)} · {file.mimeType} -

-
- - -
-
-
- {/each} -
+ void mediaPageState.copyFileUrl(file)} + onDelete={file => (deleteTarget = file)} + />
-

共 {total} 个文件

+

共 {mediaPageState.total} 个文件

mediaPageState.changePage(page)} > - 第 {currentPage} 页,共 {Math.max(1, Math.ceil(total / MEDIA_PAGE_SIZE))} 页 + 第 {mediaPageState.currentPage} 页,共 {mediaPageState.totalPages} 页 diff --git a/apps/admin/src/routes/(admin)/media/+page.ts b/apps/admin/src/routes/(admin)/media/+page.ts new file mode 100644 index 0000000..e5b136a --- /dev/null +++ b/apps/admin/src/routes/(admin)/media/+page.ts @@ -0,0 +1,23 @@ +import type { PageLoad } from './$types' + +import { emptyMediaPageData } from './media-page-state.svelte' +import { MEDIA_PAGE_SIZE } from '$lib/constants/media' +import { MediaAPI } from '$lib/api' + +// 媒体库页初始数据:首屏加载第一页且不带类型筛选。 +// 列表加载失败不抛错,回退空数据并由页面状态模块在后续操作中继续提示。 +export const load: PageLoad = async () => { + const pageData = emptyMediaPageData() + try { + const response = await MediaAPI.list({ page: 1, pageSize: MEDIA_PAGE_SIZE }) + if (response.code === 200 && response.data) { + pageData.media = response.data.media ?? [] + pageData.total = response.data.total ?? 0 + } else { + console.error('加载媒体列表失败:', response.message) + } + } catch (error) { + console.error('加载媒体列表失败:', error) + } + return pageData +} diff --git a/apps/admin/src/routes/(admin)/media/media-page-state.svelte.ts b/apps/admin/src/routes/(admin)/media/media-page-state.svelte.ts new file mode 100644 index 0000000..6bc2689 --- /dev/null +++ b/apps/admin/src/routes/(admin)/media/media-page-state.svelte.ts @@ -0,0 +1,142 @@ +import type { MediaFile } from '@myblog/api/modules/media/types' +import { toast } from 'svelte-sonner' + +import { MEDIA_PAGE_SIZE } from '$lib/constants/media' +import { MediaAPI } from '$lib/api' + +// 网络异常的统一提示文案。 +const NETWORK_ERROR_MESSAGE = '网络错误,请稍后重试' + +// 初始页面数据形状,由 +page.ts 的 load 函数提供。 +export interface MediaPageData { + media: MediaFile[] + total: number +} + +// 空页面数据,load 失败时使用。 +export function emptyMediaPageData(): MediaPageData { + return { media: [], total: 0 } +} + +// 媒体库页状态:集中持有列表、筛选条件与全部读写操作,页面组件只做渲染。 +class MediaPageState { + media = $state([]) + total = $state(0) + currentPage = $state(1) + // 类型筛选使用 MIME 前缀字符串,空串为全部,与后端 mimeType 参数口径一致。 + typeFilter = $state('') + isLoading = $state(false) + isUploading = $state(false) + + // 总页数,分页控件与页码文案共用同一口径。 + get totalPages(): number { + return Math.max(1, Math.ceil(this.total / MEDIA_PAGE_SIZE)) + } + + // 是否存在生效中的筛选条件,用于空态区分无数据与无匹配。 + get hasActiveFilters(): boolean { + return this.typeFilter !== '' + } + + // 用 load 结果初始化页面状态,重复挂载时以最新数据覆盖。 + initialize(data: MediaPageData) { + this.media = data.media + this.total = data.total + } + + // 加载媒体列表,携带类型筛选与分页参数。 + async loadMedia() { + this.isLoading = true + try { + const response = await MediaAPI.list({ + page: this.currentPage, + pageSize: MEDIA_PAGE_SIZE, + ...(this.typeFilter ? { mimeType: this.typeFilter } : {}) + }) + if (response.code === 200 && response.data) { + this.media = response.data.media ?? [] + this.total = response.data.total ?? 0 + } else { + toast.error(response.message || '加载媒体失败') + } + } catch (error) { + console.error('加载媒体失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + this.isLoading = false + } + } + + // 类型筛选变更后立即回到第一页并重新加载。 + setTypeFilter(value: string) { + this.typeFilter = value + this.currentPage = 1 + void this.loadMedia() + } + + // 重置筛选并回到第一页。 + resetFilters() { + this.typeFilter = '' + this.currentPage = 1 + void this.loadMedia() + } + + // 切换页码并重新加载。 + changePage(page: number) { + this.currentPage = page + void this.loadMedia() + } + + // 上传单个文件,成功后回到第一页并刷新列表。 + async uploadFile(file: File): Promise { + if (this.isUploading) return false + this.isUploading = true + try { + const response = await MediaAPI.upload(file) + if (response.code === 200 && response.data) { + toast.success('文件上传成功') + this.currentPage = 1 + void this.loadMedia() + return true + } + toast.error(response.message || '上传失败') + } catch (error) { + console.error('上传失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + this.isUploading = false + } + return false + } + + // 复制文件 URL 到剪贴板并提示结果,剪贴板不可用时提示手动复制。 + async copyFileUrl(file: MediaFile) { + try { + await navigator.clipboard.writeText(file.fileUrl) + toast.success('链接已复制') + } catch (error) { + console.error('复制链接失败:', error) + toast.error('复制失败,请手动复制') + } + } + + // 删除媒体文件,成功后刷新列表。 + async removeMedia(id: number): Promise { + try { + const response = await MediaAPI.delete(id) + if (response.code === 200) { + toast.success('文件删除成功') + void this.loadMedia() + return true + } + toast.error(response.message || '删除失败') + } catch (error) { + console.error('删除失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } +} + +// 页面级共享状态实例。 +export const mediaPageState = new MediaPageState() diff --git a/apps/admin/src/routes/(admin)/media/media-page-state.test.ts b/apps/admin/src/routes/(admin)/media/media-page-state.test.ts new file mode 100644 index 0000000..ad68607 --- /dev/null +++ b/apps/admin/src/routes/(admin)/media/media-page-state.test.ts @@ -0,0 +1,307 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import type { MediaFile } from '@myblog/api/modules/media/types' + +import { + MEDIA_IMAGE_MIME_PREFIX, + MEDIA_PAGE_SIZE, + MEDIA_VIDEO_MIME_PREFIX +} from '$lib/constants/media' + +// 接口、提示与剪贴板均以替身注入,测试只验证页面状态的编排逻辑,不触达网络与浏览器接口。 +const mediaApiMock = { + upload: vi.fn(), + list: vi.fn(), + delete: vi.fn() +} + +const toastMock = { + success: vi.fn(), + error: vi.fn() +} + +const clipboardMock = { + writeText: vi.fn() +} + +vi.mock('$lib/api', () => ({ MediaAPI: mediaApiMock })) +vi.mock('svelte-sonner', () => ({ toast: toastMock })) + +const { emptyMediaPageData, mediaPageState } = await import('./media-page-state.svelte') + +// 后端统一响应的成功业务码。 +const SUCCESS_CODE = 200 + +// 网络异常的统一提示文案,与页面状态模块内的取值一致。 +const NETWORK_ERROR_MESSAGE = '网络错误,请稍后重试' + +// 构造一个媒体文件替身,字段取值只覆盖被测逻辑关心的部分。 +function makeMedia(id: number, mimeType = 'image/png'): MediaFile { + return { + id, + filename: `文件${id}.png`, + fileUrl: `https://cdn.example.com/${id}.png`, + thumbnailUrl: '', + mimeType, + fileSize: 1024 + } as unknown as MediaFile +} + +// 构造一个上传文件替身,Node 环境不依赖真实的 File 实现。 +function makeUploadFile(): File { + return { name: 'photo.png', type: 'image/png', size: 1024 } as unknown as File +} + +// 重置替身调用记录与页面状态,避免用例之间互相污染。 +function resetState() { + vi.clearAllMocks() + mediaApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: { media: [], total: 0 } }) + mediaPageState.initialize(emptyMediaPageData()) + mediaPageState.typeFilter = '' + mediaPageState.currentPage = 1 + mediaPageState.isLoading = false + mediaPageState.isUploading = false +} + +describe('媒体页状态:初始化', () => { + beforeEach(resetState) + + it('用 load 结果填充列表与总数', () => { + const media = [makeMedia(1), makeMedia(2)] + + mediaPageState.initialize({ media, total: 2 }) + + expect(mediaPageState.media).toEqual(media) + expect(mediaPageState.total).toBe(2) + }) + + it('空数据下无生效筛选条件且总页数为 1', () => { + expect(mediaPageState.hasActiveFilters).toBe(false) + expect(mediaPageState.totalPages).toBe(1) + }) +}) + +describe('媒体页状态:列表加载', () => { + beforeEach(resetState) + + it('默认只携带分页参数', async () => { + mediaApiMock.list.mockResolvedValue({ + code: SUCCESS_CODE, + data: { media: [makeMedia(1)], total: 1 } + }) + + await mediaPageState.loadMedia() + + expect(mediaApiMock.list).toHaveBeenCalledWith({ page: 1, pageSize: MEDIA_PAGE_SIZE }) + expect(mediaPageState.media).toHaveLength(1) + expect(mediaPageState.total).toBe(1) + }) + + it('类型筛选生效时按 MIME 前缀查询', async () => { + mediaPageState.typeFilter = MEDIA_IMAGE_MIME_PREFIX + mediaPageState.currentPage = 3 + + await mediaPageState.loadMedia() + + expect(mediaApiMock.list).toHaveBeenCalledWith({ + page: 3, + pageSize: MEDIA_PAGE_SIZE, + mimeType: MEDIA_IMAGE_MIME_PREFIX + }) + expect(mediaPageState.hasActiveFilters).toBe(true) + }) + + it('业务码非成功时提示后端文案且不清空现有列表', async () => { + mediaApiMock.list.mockResolvedValue({ code: 500, message: '查询失败' }) + mediaPageState.initialize({ media: [makeMedia(1)], total: 1 }) + + await mediaPageState.loadMedia() + + expect(toastMock.error).toHaveBeenCalledWith('查询失败') + expect(mediaPageState.media).toHaveLength(1) + }) + + it('请求抛错时提示网络错误并结束加载态', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + mediaApiMock.list.mockRejectedValue(new Error('断网')) + + await mediaPageState.loadMedia() + + expect(toastMock.error).toHaveBeenCalledWith(NETWORK_ERROR_MESSAGE) + expect(mediaPageState.isLoading).toBe(false) + consoleError.mockRestore() + }) +}) + +describe('媒体页状态:筛选与分页', () => { + beforeEach(resetState) + + it('类型筛选变更后回到第一页并重新加载', async () => { + mediaPageState.currentPage = 4 + + mediaPageState.setTypeFilter(MEDIA_VIDEO_MIME_PREFIX) + + expect(mediaPageState.typeFilter).toBe(MEDIA_VIDEO_MIME_PREFIX) + expect(mediaPageState.currentPage).toBe(1) + await vi.waitFor(() => + expect(mediaApiMock.list).toHaveBeenCalledWith({ + page: 1, + pageSize: MEDIA_PAGE_SIZE, + mimeType: MEDIA_VIDEO_MIME_PREFIX + }) + ) + }) + + it('重置筛选清空条件并回到第一页', async () => { + mediaPageState.typeFilter = MEDIA_IMAGE_MIME_PREFIX + mediaPageState.currentPage = 5 + + mediaPageState.resetFilters() + + expect(mediaPageState.typeFilter).toBe('') + expect(mediaPageState.currentPage).toBe(1) + expect(mediaPageState.hasActiveFilters).toBe(false) + await vi.waitFor(() => + expect(mediaApiMock.list).toHaveBeenCalledWith({ page: 1, pageSize: MEDIA_PAGE_SIZE }) + ) + }) + + it('切换页码后按目标页加载', async () => { + mediaApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: { media: [], total: 25 } }) + + mediaPageState.changePage(3) + + await vi.waitFor(() => + expect(mediaApiMock.list).toHaveBeenCalledWith({ page: 3, pageSize: MEDIA_PAGE_SIZE }) + ) + expect(mediaPageState.currentPage).toBe(3) + }) + + it('总页数按分页容量向上取整,无数据时为 1 页', async () => { + expect(mediaPageState.totalPages).toBe(1) + + mediaApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: { media: [], total: 25 } }) + await mediaPageState.loadMedia() + + expect(mediaPageState.totalPages).toBe(3) + }) +}) + +describe('媒体页状态:上传', () => { + beforeEach(resetState) + + it('上传成功后提示、回到第一页并刷新列表', async () => { + const file = makeUploadFile() + mediaApiMock.upload.mockResolvedValue({ code: SUCCESS_CODE, data: makeMedia(9) }) + mediaPageState.currentPage = 4 + + const uploaded = await mediaPageState.uploadFile(file) + + expect(uploaded).toBe(true) + expect(mediaApiMock.upload).toHaveBeenCalledWith(file) + expect(toastMock.success).toHaveBeenCalledWith('文件上传成功') + expect(mediaPageState.currentPage).toBe(1) + expect(mediaPageState.isUploading).toBe(false) + await vi.waitFor(() => + expect(mediaApiMock.list).toHaveBeenCalledWith({ page: 1, pageSize: MEDIA_PAGE_SIZE }) + ) + }) + + it('上传失败时提示后端文案且不刷新列表', async () => { + mediaApiMock.upload.mockResolvedValue({ code: 400, message: '文件类型不支持' }) + + const uploaded = await mediaPageState.uploadFile(makeUploadFile()) + + expect(uploaded).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('文件类型不支持') + expect(mediaApiMock.list).not.toHaveBeenCalled() + expect(mediaPageState.isUploading).toBe(false) + }) + + it('上传请求抛错时提示网络错误并复位上传态', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + mediaApiMock.upload.mockRejectedValue(new Error('断网')) + + const uploaded = await mediaPageState.uploadFile(makeUploadFile()) + + expect(uploaded).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith(NETWORK_ERROR_MESSAGE) + expect(mediaPageState.isUploading).toBe(false) + consoleError.mockRestore() + }) + + it('上传进行中重复提交直接忽略', async () => { + mediaPageState.isUploading = true + + const uploaded = await mediaPageState.uploadFile(makeUploadFile()) + + expect(uploaded).toBe(false) + expect(mediaApiMock.upload).not.toHaveBeenCalled() + expect(mediaApiMock.list).not.toHaveBeenCalled() + }) +}) + +describe('媒体页状态:复制链接', () => { + beforeEach(() => { + resetState() + vi.stubGlobal('navigator', { clipboard: clipboardMock }) + }) + + afterEach(() => { + vi.unstubAllGlobals() + }) + + it('复制成功后提示链接已复制', async () => { + clipboardMock.writeText.mockResolvedValue(undefined) + + await mediaPageState.copyFileUrl(makeMedia(1)) + + expect(clipboardMock.writeText).toHaveBeenCalledWith('https://cdn.example.com/1.png') + expect(toastMock.success).toHaveBeenCalledWith('链接已复制') + }) + + it('复制失败时提示手动复制', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + clipboardMock.writeText.mockRejectedValue(new Error('剪贴板不可用')) + + await mediaPageState.copyFileUrl(makeMedia(1)) + + expect(toastMock.error).toHaveBeenCalledWith('复制失败,请手动复制') + consoleError.mockRestore() + }) +}) + +describe('媒体页状态:删除', () => { + beforeEach(resetState) + + it('删除成功后提示并刷新列表', async () => { + mediaApiMock.delete.mockResolvedValue({ code: SUCCESS_CODE }) + + const removed = await mediaPageState.removeMedia(1) + + expect(removed).toBe(true) + expect(mediaApiMock.delete).toHaveBeenCalledWith(1) + expect(toastMock.success).toHaveBeenCalledWith('文件删除成功') + await vi.waitFor(() => expect(mediaApiMock.list).toHaveBeenCalledTimes(1)) + }) + + it('删除失败时提示后端文案且不刷新列表', async () => { + mediaApiMock.delete.mockResolvedValue({ code: 400, message: '文件不存在' }) + + const removed = await mediaPageState.removeMedia(1) + + expect(removed).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('文件不存在') + expect(mediaApiMock.list).not.toHaveBeenCalled() + }) + + it('删除请求抛错时提示网络错误', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + mediaApiMock.delete.mockRejectedValue(new Error('断网')) + + const removed = await mediaPageState.removeMedia(1) + + expect(removed).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith(NETWORK_ERROR_MESSAGE) + consoleError.mockRestore() + }) +}) diff --git a/apps/admin/src/routes/(admin)/tags/+page.svelte b/apps/admin/src/routes/(admin)/tags/+page.svelte index 9be7c9d..43ed142 100644 --- a/apps/admin/src/routes/(admin)/tags/+page.svelte +++ b/apps/admin/src/routes/(admin)/tags/+page.svelte @@ -1,41 +1,30 @@ @@ -234,7 +71,7 @@ onMount(() => { crumb="标签管理" > {#snippet actions()} - @@ -249,8 +86,8 @@ onMount(() => {
@@ -258,11 +95,11 @@ onMount(() => { type="single" variant="outline" size="sm" - value={statusFilter} - onValueChange={handleStatusFilterChange} + value={tagPageState.statusFilter} + onValueChange={value => tagPageState.setStatusFilter(value)} > 全部 - {#each statusFilterOptions as option (option.value)} + {#each tagPageState.statusFilterOptions as option (option.value)} {option.label} {/each} @@ -271,157 +108,76 @@ onMount(() => { type="single" variant="outline" size="sm" - value={hotFilter} - onValueChange={handleHotFilterChange} + value={tagPageState.hotFilter} + onValueChange={value => tagPageState.setHotFilter(value)} > 全部 仅热门 - - {#if isLoading} + {#if tagPageState.isLoading}
- +
- {:else if tags.length === 0} + {:else if tagPageState.tags.length === 0}
-
+

- {hasActiveFilters ? '没有匹配的标签' : '暂无标签'} + {tagPageState.hasActiveFilters ? '没有匹配的标签' : '暂无标签'}

- {hasActiveFilters ? '调整或重置筛选条件后再试' : '创建第一个标签,开始组织文章内容'} + {tagPageState.hasActiveFilters + ? '调整或重置筛选条件后再试' + : '创建第一个标签,开始组织文章内容'}

- {#if hasActiveFilters} - {:else} - {/if}
{:else} - - - - 标签 - - 使用次数 - 状态 - - 操作 - - - - {#each tags as tag (tag.id)} - - -
- - - {tag.name} - {#if tag.isHot} - - {#if tag.description} -

- {tag.description} -

- {/if} -
-
- - - - {tag.usageCount} - - - - - {resolveStatusLabel(tag.status)} - - - - -
- - -
-
-
- {/each} -
-
+ openDialog(tag)} + onDelete={tag => (deleteTarget = tag)} + />
-

共 {total} 个标签

+

共 {tagPageState.total} 个标签

tagPageState.changePage(page)} > - 第 {currentPage} 页,共 {Math.max(1, Math.ceil(total / TAG_PAGE_SIZE))} 页 + 第 {tagPageState.currentPage} 页,共 {tagPageState.totalPages} 页 diff --git a/apps/admin/src/routes/(admin)/tags/+page.ts b/apps/admin/src/routes/(admin)/tags/+page.ts new file mode 100644 index 0000000..2b50f58 --- /dev/null +++ b/apps/admin/src/routes/(admin)/tags/+page.ts @@ -0,0 +1,32 @@ +import type { PageLoad } from './$types' + +import { emptyTagPageData } from './tag-page-state.svelte' +import { DICT_TYPE_CODE_TAG_STATUS } from '@myblog/api' +import { TAG_PAGE_SIZE } from '$lib/constants/tag' +import { DictAPI, TagAPI } from '$lib/api' + +// 标签管理页初始数据:首屏标签列表与标签状态字典并行加载。 +// 字典加载失败不阻断页面,状态展示回退内置配置,故失败仅记录日志。 +export const load: PageLoad = async () => { + const [tagsResult, dictResult] = await Promise.allSettled([ + TagAPI.adminList({ page: 1, pageSize: TAG_PAGE_SIZE }), + DictAPI.getByType(DICT_TYPE_CODE_TAG_STATUS) + ]) + + const pageData = emptyTagPageData() + + if (tagsResult.status === 'fulfilled' && tagsResult.value.code === 200 && tagsResult.value.data) { + pageData.tags = tagsResult.value.data.tags ?? [] + pageData.total = tagsResult.value.data.total ?? 0 + } else if (tagsResult.status === 'rejected') { + console.error('加载标签列表失败:', tagsResult.reason) + } + + if (dictResult.status === 'fulfilled' && dictResult.value.code === 200 && dictResult.value.data) { + pageData.statusDict = dictResult.value.data + } else if (dictResult.status === 'rejected') { + console.error('加载标签状态字典失败:', dictResult.reason) + } + + return pageData +} diff --git a/apps/admin/src/routes/(admin)/tags/tag-page-state.svelte.ts b/apps/admin/src/routes/(admin)/tags/tag-page-state.svelte.ts new file mode 100644 index 0000000..baf1daf --- /dev/null +++ b/apps/admin/src/routes/(admin)/tags/tag-page-state.svelte.ts @@ -0,0 +1,204 @@ +import type { + CreateTagRequest, + Tag, + TagStatus, + UpdateTagRequest +} from '@myblog/api/modules/tag/types' +import type { EnabledDictGroup } from '@myblog/api/modules/dict/types' +import { DICT_TYPE_CODE_TAG_STATUS } from '@myblog/api' +import { debounce } from '@myblog/shared' +import { toast } from 'svelte-sonner' + +import { TAG_PAGE_SIZE } from '$lib/constants/tag' +import { DictAPI, TagAPI } from '$lib/api' + +// 搜索输入停顿时长,避免每次按键都触发请求。 +const SEARCH_DEBOUNCE_MS = 300 + +// 网络异常的统一提示文案。 +const NETWORK_ERROR_MESSAGE = '网络错误,请稍后重试' + +// 标签状态筛选项的降级来源,字典不可用时使用。 +const FALLBACK_STATUS_OPTIONS = [ + { value: '1', label: '启用' }, + { value: '0', label: '隐藏' } +] + +// 初始页面数据形状,由 +page.ts 的 load 函数提供。 +export interface TagPageData { + tags: Tag[] + total: number + statusDict: EnabledDictGroup | null +} + +// 空页面数据,load 失败时使用。 +export function emptyTagPageData(): TagPageData { + return { tags: [], total: 0, statusDict: null } +} + +// 标签管理页状态:集中持有列表、筛选条件与全部读写操作,页面组件只做渲染。 +class TagPageState { + tags = $state([]) + total = $state(0) + currentPage = $state(1) + search = $state('') + // 状态筛选使用字符串值:空串为全部,其余为字典项值,与标签整型状态的字符串形式对齐。 + statusFilter = $state('') + // 热门筛选使用字符串值:空串为全部,'1' 为仅热门。 + hotFilter = $state('') + statusDict = $state(null) + isLoading = $state(false) + + // 总页数,分页控件与页码文案共用同一口径。 + get totalPages(): number { + return Math.max(1, Math.ceil(this.total / TAG_PAGE_SIZE)) + } + + // 状态筛选项按字典项排序生成;停用字典项仍参与筛选,保证存量数据可被过滤。 + get statusFilterOptions(): { value: string; label: string }[] { + if (!this.statusDict) { + return FALLBACK_STATUS_OPTIONS + } + return [...this.statusDict.items] + .sort((left, right) => left.sortOrder - right.sortOrder) + .map(item => ({ value: item.value, label: item.label })) + } + + // 是否存在生效中的筛选条件,用于空态区分无数据与无匹配。 + get hasActiveFilters(): boolean { + return this.search.trim() !== '' || this.statusFilter !== '' || this.hotFilter !== '' + } + + // 用 load 结果初始化页面状态,重复挂载时以最新数据覆盖。 + initialize(data: TagPageData) { + this.tags = data.tags + this.total = data.total + this.statusDict = data.statusDict + } + + // 加载标签列表,携带搜索、状态与热门筛选。 + async loadTags() { + this.isLoading = true + try { + const response = await TagAPI.adminList({ + page: this.currentPage, + pageSize: TAG_PAGE_SIZE, + ...(this.statusFilter !== '' ? { status: Number(this.statusFilter) as TagStatus } : {}), + ...(this.hotFilter === '1' ? { isHot: true } : {}), + ...(this.search.trim() ? { search: this.search.trim() } : {}) + }) + if (response.code === 200 && response.data) { + this.tags = response.data.tags ?? [] + this.total = response.data.total ?? 0 + } else { + toast.error(response.message || '加载标签失败') + } + } catch (error) { + console.error('加载标签失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + this.isLoading = false + } + } + + // 搜索词防抖应用,连续输入只在停顿后请求一次。 + applySearchDebounced = debounce(() => { + this.currentPage = 1 + void this.loadTags() + }, SEARCH_DEBOUNCE_MS) + + // 状态筛选变更后回到第一页并重新加载。 + setStatusFilter(value: string) { + this.statusFilter = value + this.currentPage = 1 + void this.loadTags() + } + + // 热门筛选变更后回到第一页并重新加载。 + setHotFilter(value: string) { + this.hotFilter = value + this.currentPage = 1 + void this.loadTags() + } + + // 重置全部筛选条件并回到第一页。 + resetFilters() { + this.search = '' + this.statusFilter = '' + this.hotFilter = '' + this.currentPage = 1 + void this.loadTags() + } + + // 切换页码并重新加载。 + changePage(page: number) { + this.currentPage = page + void this.loadTags() + } + + // 创建标签,成功后刷新当前页。 + async createTag(payload: CreateTagRequest): Promise { + try { + const response = await TagAPI.create(payload) + if (response.code === 200 && response.data) { + toast.success('标签创建成功') + await this.loadTags() + return true + } + toast.error(response.message || '保存标签失败') + } catch (error) { + console.error('保存标签失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } + + // 更新标签,成功后刷新当前页。 + async updateTag(payload: UpdateTagRequest): Promise { + try { + const response = await TagAPI.update(payload) + if (response.code === 200 && response.data) { + toast.success('标签更新成功') + await this.loadTags() + return true + } + toast.error(response.message || '保存标签失败') + } catch (error) { + console.error('保存标签失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } + + // 删除标签,已挂载文章的标签处理由后端裁决。 + async removeTag(id: number): Promise { + try { + const response = await TagAPI.delete(id) + if (response.code === 200) { + toast.success('标签删除成功') + await this.loadTags() + return true + } + toast.error(response.message || '删除标签失败') + } catch (error) { + console.error('删除标签失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } + + // 加载标签状态字典,失败时静默回退内置配置,不阻断列表使用。 + async loadStatusDict() { + try { + const response = await DictAPI.getByType(DICT_TYPE_CODE_TAG_STATUS) + if (response.code === 200 && response.data) { + this.statusDict = response.data + } + } catch (error) { + console.error('加载标签状态字典失败:', error) + } + } +} + +// 页面级共享状态实例。 +export const tagPageState = new TagPageState() diff --git a/apps/admin/src/routes/(admin)/tags/tag-page-state.test.ts b/apps/admin/src/routes/(admin)/tags/tag-page-state.test.ts new file mode 100644 index 0000000..6e51606 --- /dev/null +++ b/apps/admin/src/routes/(admin)/tags/tag-page-state.test.ts @@ -0,0 +1,303 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import type { EnabledDictGroup } from '@myblog/api/modules/dict/types' +import type { Tag } from '@myblog/api/modules/tag/types' + +import { TAG_PAGE_SIZE } from '$lib/constants/tag' + +// 接口与提示均以替身注入,测试只验证页面状态的编排逻辑,不触达网络与界面。 +const tagApiMock = { + adminList: vi.fn(), + create: vi.fn(), + update: vi.fn(), + delete: vi.fn() +} + +const dictApiMock = { + getByType: vi.fn() +} + +const toastMock = { + success: vi.fn(), + error: vi.fn() +} + +vi.mock('$lib/api', () => ({ TagAPI: tagApiMock, DictAPI: dictApiMock })) +vi.mock('svelte-sonner', () => ({ toast: toastMock })) + +const { emptyTagPageData, tagPageState } = await import('./tag-page-state.svelte') + +// 后端统一响应的成功业务码。 +const SUCCESS_CODE = 200 + +// 搜索防抖时长,与页面状态模块内的取值一致。 +const SEARCH_DEBOUNCE_MS = 300 + +// 构造一个标签替身,字段取值只覆盖被测逻辑关心的部分。 +function makeTag(id: number, name = `标签${id}`): Tag { + return { id, name, slug: `tag-${id}`, status: 1, usageCount: 0, isHot: false } as unknown as Tag +} + +// 构造标签状态字典替身。 +function makeStatusDict(): EnabledDictGroup { + return { + code: 'tag_status', + items: [{ value: '1', label: '启用', sortOrder: 1 }] + } as unknown as EnabledDictGroup +} + +// 重置替身调用记录与页面状态,避免用例之间互相污染。 +function resetState() { + vi.clearAllMocks() + tagPageState.initialize(emptyTagPageData()) + tagPageState.search = '' + tagPageState.statusFilter = '' + tagPageState.hotFilter = '' + tagPageState.currentPage = 1 +} + +describe('标签页状态:初始化', () => { + beforeEach(resetState) + + it('用 load 结果填充列表、总数与状态字典', () => { + const tags = [makeTag(1), makeTag(2)] + const statusDict = makeStatusDict() + + tagPageState.initialize({ tags, total: 2, statusDict }) + + expect(tagPageState.tags).toEqual(tags) + expect(tagPageState.total).toBe(2) + expect(tagPageState.statusDict).toEqual(statusDict) + }) + + it('空数据下无生效筛选条件', () => { + expect(tagPageState.hasActiveFilters).toBe(false) + expect(tagPageState.totalPages).toBe(1) + }) +}) + +describe('标签页状态:列表加载', () => { + beforeEach(resetState) + + it('默认只携带分页参数', async () => { + tagApiMock.adminList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { tags: [makeTag(1)], total: 1 } + }) + + await tagPageState.loadTags() + + expect(tagApiMock.adminList).toHaveBeenCalledWith({ page: 1, pageSize: TAG_PAGE_SIZE }) + expect(tagPageState.tags).toHaveLength(1) + expect(tagPageState.total).toBe(1) + }) + + it('筛选条件生效时按状态、热门与搜索词查询', async () => { + tagApiMock.adminList.mockResolvedValue({ code: SUCCESS_CODE, data: { tags: [], total: 0 } }) + tagPageState.statusFilter = '0' + tagPageState.hotFilter = '1' + tagPageState.search = ' 博客 ' + tagPageState.currentPage = 3 + + await tagPageState.loadTags() + + expect(tagApiMock.adminList).toHaveBeenCalledWith({ + page: 3, + pageSize: TAG_PAGE_SIZE, + status: 0, + isHot: true, + search: '博客' + }) + }) + + it('业务码非成功时提示后端文案且不清空现有列表', async () => { + tagApiMock.adminList.mockResolvedValue({ code: 500, message: '查询失败' }) + tagPageState.initialize({ tags: [makeTag(1)], total: 1, statusDict: null }) + + await tagPageState.loadTags() + + expect(toastMock.error).toHaveBeenCalledWith('查询失败') + expect(tagPageState.tags).toHaveLength(1) + }) + + it('请求抛错时提示网络错误', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + tagApiMock.adminList.mockRejectedValue(new Error('断网')) + + await tagPageState.loadTags() + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(tagPageState.isLoading).toBe(false) + consoleError.mockRestore() + }) +}) + +describe('标签页状态:筛选项与分页', () => { + beforeEach(resetState) + + it('字典缺失时状态筛选项回退内置配置', () => { + expect(tagPageState.statusFilterOptions).toEqual([ + { value: '1', label: '启用' }, + { value: '0', label: '隐藏' } + ]) + }) + + it('字典可用时按排序值生成状态筛选项', () => { + tagPageState.statusDict = { + items: [ + { value: '0', label: '隐藏', sortOrder: 2 }, + { value: '1', label: '启用', sortOrder: 1 } + ] + } as unknown as EnabledDictGroup + + expect(tagPageState.statusFilterOptions).toEqual([ + { value: '1', label: '启用' }, + { value: '0', label: '隐藏' } + ]) + }) + + it('状态与热门筛选变更后回到第一页并重新加载', async () => { + tagApiMock.adminList.mockResolvedValue({ code: SUCCESS_CODE, data: { tags: [], total: 0 } }) + tagPageState.currentPage = 4 + + tagPageState.setStatusFilter('0') + await vi.waitFor(() => expect(tagApiMock.adminList).toHaveBeenCalledTimes(1)) + expect(tagPageState.currentPage).toBe(1) + + tagPageState.setHotFilter('1') + await vi.waitFor(() => expect(tagApiMock.adminList).toHaveBeenCalledTimes(2)) + expect(tagPageState.hotFilter).toBe('1') + }) + + it('重置筛选清空全部条件并回到第一页', async () => { + tagApiMock.adminList.mockResolvedValue({ code: SUCCESS_CODE, data: { tags: [], total: 0 } }) + tagPageState.search = '博客' + tagPageState.statusFilter = '1' + tagPageState.hotFilter = '1' + tagPageState.currentPage = 5 + + tagPageState.resetFilters() + + expect(tagPageState.search).toBe('') + expect(tagPageState.statusFilter).toBe('') + expect(tagPageState.hotFilter).toBe('') + expect(tagPageState.currentPage).toBe(1) + expect(tagPageState.hasActiveFilters).toBe(false) + }) + + it('切换页码后按目标页加载', async () => { + tagApiMock.adminList.mockResolvedValue({ code: SUCCESS_CODE, data: { tags: [], total: 50 } }) + + tagPageState.changePage(2) + + await vi.waitFor(() => + expect(tagApiMock.adminList).toHaveBeenCalledWith({ page: 2, pageSize: TAG_PAGE_SIZE }) + ) + expect(tagPageState.totalPages).toBe(5) + }) +}) + +describe('标签页状态:搜索防抖', () => { + beforeEach(() => { + resetState() + vi.useFakeTimers() + }) + + afterEach(() => { + vi.useRealTimers() + }) + + // 连续输入必须在停顿后只请求一次,且回到第一页,避免翻页后搜索命中空页。 + it('连续输入只在停顿后触发一次请求并回到第一页', () => { + tagApiMock.adminList.mockResolvedValue({ code: SUCCESS_CODE, data: { tags: [], total: 0 } }) + tagPageState.currentPage = 3 + + tagPageState.applySearchDebounced() + tagPageState.applySearchDebounced() + expect(tagApiMock.adminList).not.toHaveBeenCalled() + + vi.advanceTimersByTime(SEARCH_DEBOUNCE_MS) + + expect(tagApiMock.adminList).toHaveBeenCalledTimes(1) + expect(tagPageState.currentPage).toBe(1) + }) +}) + +describe('标签页状态:写操作', () => { + beforeEach(resetState) + + it('创建成功后提示并刷新列表', async () => { + tagApiMock.create.mockResolvedValue({ code: SUCCESS_CODE, data: makeTag(9) }) + tagApiMock.adminList.mockResolvedValue({ code: SUCCESS_CODE, data: { tags: [], total: 0 } }) + + const created = await tagPageState.createTag({ name: '新标签' } as never) + + expect(created).toBe(true) + expect(toastMock.success).toHaveBeenCalledWith('标签创建成功') + expect(tagApiMock.adminList).toHaveBeenCalledTimes(1) + }) + + it('创建失败时提示后端文案且不刷新列表', async () => { + tagApiMock.create.mockResolvedValue({ code: 400, message: '标签名称已存在' }) + + const created = await tagPageState.createTag({ name: '重复' } as never) + + expect(created).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('标签名称已存在') + expect(tagApiMock.adminList).not.toHaveBeenCalled() + }) + + it('更新成功后提示并刷新列表', async () => { + tagApiMock.update.mockResolvedValue({ code: SUCCESS_CODE, data: makeTag(1) }) + tagApiMock.adminList.mockResolvedValue({ code: SUCCESS_CODE, data: { tags: [], total: 0 } }) + + const updated = await tagPageState.updateTag({ id: 1, name: '改名' } as never) + + expect(updated).toBe(true) + expect(toastMock.success).toHaveBeenCalledWith('标签更新成功') + }) + + it('删除成功后提示并刷新列表', async () => { + tagApiMock.delete.mockResolvedValue({ code: SUCCESS_CODE }) + tagApiMock.adminList.mockResolvedValue({ code: SUCCESS_CODE, data: { tags: [], total: 0 } }) + + const removed = await tagPageState.removeTag(1) + + expect(removed).toBe(true) + expect(toastMock.success).toHaveBeenCalledWith('标签删除成功') + expect(tagApiMock.adminList).toHaveBeenCalledTimes(1) + }) + + it('删除失败时不刷新列表', async () => { + tagApiMock.delete.mockResolvedValue({ code: 400, message: '标签仍被引用' }) + + const removed = await tagPageState.removeTag(1) + + expect(removed).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('标签仍被引用') + expect(tagApiMock.adminList).not.toHaveBeenCalled() + }) +}) + +describe('标签页状态:状态字典', () => { + beforeEach(resetState) + + it('加载成功后覆盖状态字典', async () => { + const statusDict = makeStatusDict() + dictApiMock.getByType.mockResolvedValue({ code: SUCCESS_CODE, data: statusDict }) + + await tagPageState.loadStatusDict() + + expect(tagPageState.statusDict).toEqual(statusDict) + }) + + // 字典是展示增强而非列表前提,加载失败必须静默降级。 + it('加载失败时保持原有字典且不抛错', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + dictApiMock.getByType.mockRejectedValue(new Error('断网')) + + await expect(tagPageState.loadStatusDict()).resolves.toBeUndefined() + expect(tagPageState.statusDict).toBeNull() + expect(toastMock.error).not.toHaveBeenCalled() + consoleError.mockRestore() + }) +}) diff --git a/apps/admin/src/routes/(admin)/users/+page.svelte b/apps/admin/src/routes/(admin)/users/+page.svelte index 1148327..4dd2d68 100644 --- a/apps/admin/src/routes/(admin)/users/+page.svelte +++ b/apps/admin/src/routes/(admin)/users/+page.svelte @@ -1,34 +1,30 @@ @@ -253,7 +91,7 @@ onMount(() => { {#snippet actions()} - @@ -261,99 +99,115 @@ onMount(() => { +
-
- {#if selectedIds.length > 0} + + {#if userPageState.selectedIds.length > 0}
- 已选择 {selectedIds.length} 个用户 + + 已选择 {userPageState.selectedIds.length} 个用户 +
- - - +
{/if} - {#if isLoading} + {#if userPageState.isLoading}
- -
- {:else if users.length === 0} -
-
- -
-
-

- {hasActiveFilters ? '没有匹配的用户' : '暂无用户'} -

-

- {hasActiveFilters ? '调整或重置搜索条件后再试' : '创建第一个用户账号'} -

-
- {#if hasActiveFilters} - - {:else} - - {/if} +
+ {:else if userPageState.users.length === 0} + + + + + + + {userPageState.hasActiveFilters ? '没有匹配的用户' : '暂无用户'} + + + {userPageState.hasActiveFilters ? '调整或重置搜索条件后再试' : '创建第一个用户账号'} + + + + {#if userPageState.hasActiveFilters} + + {:else} + + {/if} + + {:else} { - dialogTarget = user - isDialogOpen = true - }} - onToggleStatus={handleToggleStatus} + users={userPageState.users} + selectedIds={userPageState.selectedIds} + isAllSelected={userPageState.isAllSelected} + onToggleSelectAll={() => userPageState.toggleSelectAll()} + onToggleSelect={id => userPageState.toggleSelect(id)} + onEdit={user => openDialog(user)} + onToggleStatus={user => void userPageState.toggleUserStatus(user)} onDelete={user => (deleteTarget = user)} />
-

共 {total} 个用户

+

共 {userPageState.total} 个用户

userPageState.changePage(page)} > - 第 {currentPage} 页,共 {Math.max(1, Math.ceil(total / USER_PAGE_SIZE))} 页 + 第 {userPageState.currentPage} 页,共 {userPageState.totalPages} 页 @@ -365,7 +219,7 @@ onMount(() => { (isDialogOpen = open)} @@ -386,19 +240,19 @@ onMount(() => { /> { if (!open && !isBatchExecuting) batchConfirm = null }} - onConfirm={executeBatch} + onConfirm={handleBatchConfirm} /> diff --git a/apps/admin/src/routes/(admin)/users/+page.ts b/apps/admin/src/routes/(admin)/users/+page.ts new file mode 100644 index 0000000..bcd0e62 --- /dev/null +++ b/apps/admin/src/routes/(admin)/users/+page.ts @@ -0,0 +1,28 @@ +import type { PageLoad } from './$types' + +import { emptyUserPageData } from './user-page-state.svelte' +import { USER_PAGE_SIZE } from '$lib/constants/user' +import { UserAPI } from '$lib/api' + +// 首屏页码固定为第一页,筛选条件留空,与页面初次渲染的可视状态一致。 +const FIRST_PAGE = 1 + +// 用户管理页初始数据:首屏加载第一页且不带关键词的用户列表。 +// 加载失败不阻断页面渲染,降级返回空数据并记录日志,后续由页面内交互重新加载。 +export const load: PageLoad = async () => { + try { + const response = await UserAPI.getUserList(FIRST_PAGE, USER_PAGE_SIZE) + if (response.code !== 200 || !response.data) { + console.error('加载用户列表失败:', response.message) + return emptyUserPageData() + } + + return { + users: response.data.users ?? [], + total: response.data.total ?? 0 + } + } catch (error) { + console.error('加载用户列表失败:', error) + return emptyUserPageData() + } +} diff --git a/apps/admin/src/routes/(admin)/users/user-page-state.svelte.ts b/apps/admin/src/routes/(admin)/users/user-page-state.svelte.ts new file mode 100644 index 0000000..6dafbb0 --- /dev/null +++ b/apps/admin/src/routes/(admin)/users/user-page-state.svelte.ts @@ -0,0 +1,256 @@ +import type { + CreateUserRequest, + UpdateUserRequest, + User, + UserRole +} from '@myblog/api/modules/user/types' +import { USER_PAGE_SIZE, USER_STATUS_DISABLED, USER_STATUS_ENABLED } from '$lib/constants/user' +import { getAssignableRoles } from '$lib/utils/permissions' +import { authStore } from '$lib/stores/auth' +import { debounce } from '@myblog/shared' +import { toast } from 'svelte-sonner' +import { UserAPI } from '$lib/api' + +// 搜索输入停顿时长,避免每次按键都触发请求。 +const SEARCH_DEBOUNCE_MS = 300 + +// 网络异常的统一提示文案。 +const NETWORK_ERROR_MESSAGE = '网络错误,请稍后重试' + +// 登录态尚未就绪时的角色选项降级值,保留完整角色集合。 +const DEFAULT_ASSIGNABLE_ROLES: UserRole[] = ['user', 'editor', 'admin', 'superadmin'] + +// 启用与禁用两态的动作文案,单条状态切换的提示语与批量操作共用。 +const STATUS_ACTION_LABELS: Record< + typeof USER_STATUS_DISABLED | typeof USER_STATUS_ENABLED, + string +> = { + [USER_STATUS_DISABLED]: '禁用', + [USER_STATUS_ENABLED]: '启用' +} + +// 批量操作动作,与二次确认弹窗的语义一一对应。 +export type BatchAction = 'enable' | 'disable' | 'delete' + +// 批量操作的动作文案,用于成功与失败提示语的拼装。 +const BATCH_ACTION_LABELS: Record = { + enable: STATUS_ACTION_LABELS[USER_STATUS_ENABLED], + disable: STATUS_ACTION_LABELS[USER_STATUS_DISABLED], + delete: '删除' +} + +// 初始页面数据形状,由 +page.ts 的 load 函数提供。 +export interface UserPageData { + users: User[] + total: number +} + +// 空页面数据,load 失败时使用。 +export function emptyUserPageData(): UserPageData { + return { users: [], total: 0 } +} + +// 用户管理页状态:集中持有列表、筛选、批量选择与全部读写操作,页面组件只做渲染。 +class UserPageState { + users = $state([]) + total = $state(0) + currentPage = $state(1) + keyword = $state('') + // 批量选择的目标用户标识,列表重新加载成功后清空。 + selectedIds = $state([]) + isLoading = $state(false) + // 当前用户可分配角色,由登录态经权限工具推导,作为表单角色选项的数据源。 + assignableRoles = $state(DEFAULT_ASSIGNABLE_ROLES) + + // 总页数,分页控件与页码文案共用同一口径。 + get totalPages(): number { + return Math.max(1, Math.ceil(this.total / USER_PAGE_SIZE)) + } + + // 是否存在生效中的搜索条件,用于空态区分无数据与无匹配。 + get hasActiveFilters(): boolean { + return this.keyword.trim() !== '' + } + + // 当前页是否已全选,页内无数据时恒为未全选。 + get isAllSelected(): boolean { + return this.users.length > 0 && this.selectedIds.length === this.users.length + } + + // 用 load 结果初始化页面状态,可分配角色按当前登录态重新推导。 + initialize(data: UserPageData) { + this.users = data.users + this.total = data.total + this.assignableRoles = getAssignableRoles(authStore.getCurrentState().user) + } + + // 加载用户列表,搜索词经 keyword 参数交由后端模糊匹配。 + // 写操作成功后经此方法刷新且不等待刷新结果,保证弹窗与确认框即时关闭。 + async loadUsers() { + this.isLoading = true + try { + const response = await UserAPI.getUserList( + this.currentPage, + USER_PAGE_SIZE, + this.keyword.trim() + ) + if (response.code === 200 && response.data) { + this.users = response.data.users ?? [] + this.total = response.data.total ?? 0 + this.selectedIds = [] + } else { + toast.error(response.message || '加载用户列表失败') + } + } catch (error) { + console.error('加载用户列表失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + this.isLoading = false + } + } + + // 搜索词防抖应用,连续输入只在停顿后请求一次,并回到第一页。 + applySearchDebounced = debounce(() => { + this.currentPage = 1 + void this.loadUsers() + }, SEARCH_DEBOUNCE_MS) + + // 清空搜索并回到第一页。 + resetAndReload() { + this.keyword = '' + this.currentPage = 1 + void this.loadUsers() + } + + // 切换页码并重新加载。 + changePage(page: number) { + this.currentPage = page + void this.loadUsers() + } + + // 全选当前页;已全选时取消全部选择。 + toggleSelectAll() { + this.selectedIds = + this.selectedIds.length === this.users.length ? [] : this.users.map(user => user.id) + } + + // 切换单个用户的选择状态。 + toggleSelect(id: number) { + this.selectedIds = this.selectedIds.includes(id) + ? this.selectedIds.filter(item => item !== id) + : [...this.selectedIds, id] + } + + // 清空批量选择。 + clearSelection() { + this.selectedIds = [] + } + + // 创建用户,成功后刷新列表。 + async createUser(payload: CreateUserRequest): Promise { + try { + const response = await UserAPI.createUser(payload) + if (response.code === 200 && response.data) { + toast.success('用户创建成功') + void this.loadUsers() + return true + } + toast.error(response.message || '保存用户失败') + } catch (error) { + console.error('保存用户失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } + + // 更新用户,成功后刷新列表。 + async updateUser(payload: UpdateUserRequest): Promise { + try { + const response = await UserAPI.updateUser(payload) + if (response.code === 200 && response.data) { + toast.success('用户更新成功') + void this.loadUsers() + return true + } + toast.error(response.message || '保存用户失败') + } catch (error) { + console.error('保存用户失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } + + // 切换用户启用与禁用状态,状态 2 为锁定态,按原口径归入启用方向。 + async toggleUserStatus(user: User): Promise { + const nextStatus = + user.status === USER_STATUS_ENABLED ? USER_STATUS_DISABLED : USER_STATUS_ENABLED + const action = STATUS_ACTION_LABELS[nextStatus] + try { + const response = await UserAPI.updateUser({ + id: user.id, + username: user.username, + email: user.email, + nickname: user.nickname || '', + role: user.role || 'user', + birthday: user.birthday || '', + status: nextStatus + }) + if (response.code === 200) { + toast.success(`用户${action}成功`) + void this.loadUsers() + } else { + toast.error(response.message || `${action}用户失败`) + } + } catch (error) { + console.error(`切换用户状态失败:`, error) + toast.error(NETWORK_ERROR_MESSAGE) + } + } + + // 删除单个用户,成功后刷新列表。 + async removeUser(id: number): Promise { + try { + const response = await UserAPI.deleteUser(id) + if (response.code === 200) { + toast.success('用户删除成功') + void this.loadUsers() + return true + } + toast.error(response.message || '删除用户失败') + } catch (error) { + console.error('删除用户失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + return false + } + + // 执行确认后的批量操作,单次请求交由后端原子处理。 + // 后端在事务内完成,任一目标违规整批拒绝,前端仅接收整体成败。 + // 列表刷新沿用原实现的 finally 语义,成功与失败均重新加载当前页。 + async executeBatch(action: BatchAction): Promise { + const ids = [...this.selectedIds] + try { + const response = + action === 'delete' + ? await UserAPI.batchDeleteUsers({ ids }) + : await UserAPI.batchUpdateUserStatus({ + ids, + status: action === 'enable' ? USER_STATUS_ENABLED : USER_STATUS_DISABLED + }) + if (response.code === 200) { + toast.success(`批量${BATCH_ACTION_LABELS[action]}成功`) + return true + } + toast.error(response.message || `批量${BATCH_ACTION_LABELS[action]}失败`) + } catch (error) { + console.error('批量操作失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + void this.loadUsers() + } + return false + } +} + +// 页面级共享状态实例。 +export const userPageState = new UserPageState() diff --git a/apps/admin/src/routes/(admin)/users/user-page-state.test.ts b/apps/admin/src/routes/(admin)/users/user-page-state.test.ts new file mode 100644 index 0000000..6390f8c --- /dev/null +++ b/apps/admin/src/routes/(admin)/users/user-page-state.test.ts @@ -0,0 +1,432 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import type { User } from '@myblog/api/modules/user/types' + +import { USER_PAGE_SIZE } from '$lib/constants/user' + +// 接口与提示均以替身注入,测试只验证页面状态的编排逻辑,不触达网络与界面。 +const userApiMock = { + getUserList: vi.fn(), + createUser: vi.fn(), + updateUser: vi.fn(), + deleteUser: vi.fn(), + batchDeleteUsers: vi.fn(), + batchUpdateUserStatus: vi.fn() +} + +const toastMock = { + success: vi.fn(), + error: vi.fn() +} + +// 登录态以最小替身提供,可分配角色由权限工具按当前用户实时推导。 +const authState: { user: User | null } = { user: null } + +vi.mock('$lib/api', () => ({ UserAPI: userApiMock })) +vi.mock('svelte-sonner', () => ({ toast: toastMock })) +vi.mock('$lib/stores/auth', () => ({ + authStore: { getCurrentState: () => authState } +})) + +const { emptyUserPageData, userPageState } = await import('./user-page-state.svelte') + +// 后端统一响应的成功业务码。 +const SUCCESS_CODE = 200 + +// 后端统一响应的失败业务码,用于校验失败分支的提示文案。 +const ERROR_CODE = 500 + +// 当前登录用户的标识,与列表中的用户区分开。 +const CURRENT_USER_ID = 100 + +// 搜索防抖时长,与页面状态模块内的取值一致。 +const SEARCH_DEBOUNCE_MS = 300 + +// 构造一个用户替身,字段取值只覆盖被测逻辑关心的部分。 +function makeUser(id: number, overrides: Partial = {}): User { + return { + id, + username: `user${id}`, + email: `user${id}@blog.test`, + nickname: `用户${id}`, + avatar: '', + birthday: null, + role: 'user', + status: 1, + createdAt: '2024-01-01T00:00:00Z', + updatedAt: '2024-01-01T00:00:00Z', + ...overrides + } +} + +// 列表加载成功的统一响应替身。 +const LIST_SUCCESS = { code: SUCCESS_CODE, data: { users: [], total: 0 } } + +// 先等待上一用例触发的列表刷新结束,再清理替身与页面状态,避免用例之间互相污染。 +async function resetState() { + await new Promise(resolve => setTimeout(resolve, 0)) + vi.clearAllMocks() + authState.user = makeUser(CURRENT_USER_ID, { role: 'superadmin' }) + userPageState.initialize(emptyUserPageData()) + userPageState.keyword = '' + userPageState.currentPage = 1 + userPageState.selectedIds = [] + userPageState.isLoading = false +} + +describe('用户页状态:初始化', () => { + beforeEach(resetState) + + it('用 load 结果填充列表与总数', () => { + const users = [makeUser(1), makeUser(2)] + + userPageState.initialize({ users, total: 2 }) + + expect(userPageState.users).toEqual(users) + expect(userPageState.total).toBe(2) + }) + + it('按当前登录用户推导可分配角色', () => { + authState.user = makeUser(CURRENT_USER_ID, { role: 'superadmin' }) + userPageState.initialize(emptyUserPageData()) + expect(userPageState.assignableRoles).toEqual(['user', 'editor', 'admin', 'superadmin']) + + authState.user = makeUser(CURRENT_USER_ID, { role: 'admin' }) + userPageState.initialize(emptyUserPageData()) + expect(userPageState.assignableRoles).toEqual(['user', 'editor']) + }) + + it('空数据下派生状态取默认值', () => { + userPageState.initialize(emptyUserPageData()) + + expect(userPageState.totalPages).toBe(1) + expect(userPageState.hasActiveFilters).toBe(false) + expect(userPageState.isAllSelected).toBe(false) + }) +}) + +describe('用户页状态:列表加载', () => { + beforeEach(resetState) + + it('默认只携带第一页与既定分页容量', async () => { + userApiMock.getUserList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { users: [makeUser(1)], total: 1 } + }) + + await userPageState.loadUsers() + + expect(userApiMock.getUserList).toHaveBeenCalledWith(1, USER_PAGE_SIZE, '') + expect(userPageState.users).toHaveLength(1) + expect(userPageState.total).toBe(1) + }) + + it('搜索词去除首尾空白后按当前页码查询', async () => { + userApiMock.getUserList.mockResolvedValue(LIST_SUCCESS) + userPageState.keyword = ' 博客 ' + userPageState.currentPage = 3 + + await userPageState.loadUsers() + + expect(userApiMock.getUserList).toHaveBeenCalledWith(3, USER_PAGE_SIZE, '博客') + }) + + it('业务码非成功时提示后端文案且保留现有列表', async () => { + userApiMock.getUserList.mockResolvedValue({ code: ERROR_CODE, message: '查询失败' }) + userPageState.initialize({ users: [makeUser(1)], total: 1 }) + + await userPageState.loadUsers() + + expect(toastMock.error).toHaveBeenCalledWith('查询失败') + expect(userPageState.users).toHaveLength(1) + expect(userPageState.isLoading).toBe(false) + }) + + it('请求抛错时提示网络错误并结束加载态', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + userApiMock.getUserList.mockRejectedValue(new Error('断网')) + + await userPageState.loadUsers() + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(userPageState.isLoading).toBe(false) + consoleError.mockRestore() + }) + + it('加载成功后清空批量选择', async () => { + userApiMock.getUserList.mockResolvedValue({ + code: SUCCESS_CODE, + data: { users: [makeUser(1), makeUser(2)], total: 2 } + }) + userPageState.selectedIds = [1, 2] + + await userPageState.loadUsers() + + expect(userPageState.selectedIds).toEqual([]) + }) +}) + +describe('用户页状态:筛选与分页', () => { + beforeEach(resetState) + + it('切换页码后按目标页加载,总页数按分页容量向上取整', () => { + userApiMock.getUserList.mockResolvedValue(LIST_SUCCESS) + + userPageState.changePage(2) + + expect(userPageState.currentPage).toBe(2) + expect(userApiMock.getUserList).toHaveBeenCalledWith(2, USER_PAGE_SIZE, '') + + userPageState.total = 25 + expect(userPageState.totalPages).toBe(3) + }) + + it('重置搜索清空关键词并回到第一页', () => { + userApiMock.getUserList.mockResolvedValue(LIST_SUCCESS) + userPageState.keyword = '博客' + userPageState.currentPage = 5 + + userPageState.resetAndReload() + + expect(userPageState.keyword).toBe('') + expect(userPageState.currentPage).toBe(1) + expect(userPageState.hasActiveFilters).toBe(false) + expect(userApiMock.getUserList).toHaveBeenCalledWith(1, USER_PAGE_SIZE, '') + }) + + it('关键词仅含空白时不视为生效筛选', () => { + userPageState.keyword = ' ' + + expect(userPageState.hasActiveFilters).toBe(false) + }) +}) + +describe('用户页状态:搜索防抖', () => { + beforeEach(async () => { + await resetState() + vi.useFakeTimers() + }) + + afterEach(() => { + vi.useRealTimers() + }) + + // 连续输入必须在停顿后只请求一次,且回到第一页,避免翻页后搜索命中空页。 + it('连续输入只在停顿后触发一次请求并回到第一页', () => { + userApiMock.getUserList.mockResolvedValue(LIST_SUCCESS) + userPageState.currentPage = 3 + + userPageState.applySearchDebounced() + userPageState.applySearchDebounced() + expect(userApiMock.getUserList).not.toHaveBeenCalled() + + vi.advanceTimersByTime(SEARCH_DEBOUNCE_MS) + + expect(userApiMock.getUserList).toHaveBeenCalledTimes(1) + expect(userPageState.currentPage).toBe(1) + }) +}) + +describe('用户页状态:批量选择', () => { + beforeEach(resetState) + + it('全选与取消全选按当前页用户切换', () => { + userPageState.users = [makeUser(1), makeUser(2)] + + userPageState.toggleSelectAll() + expect(userPageState.selectedIds).toEqual([1, 2]) + expect(userPageState.isAllSelected).toBe(true) + + userPageState.toggleSelectAll() + expect(userPageState.selectedIds).toEqual([]) + expect(userPageState.isAllSelected).toBe(false) + }) + + it('单项选择支持追加已选与移除已选', () => { + userPageState.toggleSelect(1) + userPageState.toggleSelect(2) + expect(userPageState.selectedIds).toEqual([1, 2]) + + userPageState.toggleSelect(1) + expect(userPageState.selectedIds).toEqual([2]) + }) + + it('清空选择移除全部标识', () => { + userPageState.selectedIds = [1, 2] + + userPageState.clearSelection() + + expect(userPageState.selectedIds).toEqual([]) + }) +}) + +describe('用户页状态:增删改', () => { + beforeEach(resetState) + + it('创建用户成功时提示并刷新列表,失败时提示后端文案且不刷新', async () => { + userApiMock.getUserList.mockResolvedValue(LIST_SUCCESS) + userApiMock.createUser.mockResolvedValueOnce({ code: SUCCESS_CODE, data: makeUser(9) }) + + const created = await userPageState.createUser({ + username: '新用户', + email: 'new@blog.test', + password: 'secret123' + }) + + expect(created).toBe(true) + expect(toastMock.success).toHaveBeenCalledWith('用户创建成功') + expect(userApiMock.getUserList).toHaveBeenCalledTimes(1) + + userApiMock.getUserList.mockClear() + userApiMock.createUser.mockResolvedValueOnce({ code: ERROR_CODE, message: '用户名已存在' }) + + const duplicated = await userPageState.createUser({ + username: '重复', + email: 'dup@blog.test', + password: 'secret123' + }) + + expect(duplicated).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('用户名已存在') + expect(userApiMock.getUserList).not.toHaveBeenCalled() + }) + + it('更新用户成功时提示并刷新列表,异常时提示网络错误', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + userApiMock.getUserList.mockResolvedValue(LIST_SUCCESS) + userApiMock.updateUser.mockResolvedValueOnce({ code: SUCCESS_CODE, data: makeUser(1) }) + + const updated = await userPageState.updateUser({ + id: 1, + username: 'user1', + email: 'user1@blog.test' + }) + + expect(updated).toBe(true) + expect(toastMock.success).toHaveBeenCalledWith('用户更新成功') + expect(userApiMock.getUserList).toHaveBeenCalledTimes(1) + + userApiMock.getUserList.mockClear() + userApiMock.updateUser.mockRejectedValueOnce(new Error('断网')) + + const failed = await userPageState.updateUser({ + id: 1, + username: 'user1', + email: 'user1@blog.test' + }) + + expect(failed).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(userApiMock.getUserList).not.toHaveBeenCalled() + consoleError.mockRestore() + }) + + it('删除用户成功时提示并刷新列表,失败时提示后端文案且不刷新', async () => { + userApiMock.getUserList.mockResolvedValue(LIST_SUCCESS) + userApiMock.deleteUser.mockResolvedValueOnce({ code: SUCCESS_CODE }) + + const removed = await userPageState.removeUser(1) + + expect(removed).toBe(true) + expect(toastMock.success).toHaveBeenCalledWith('用户删除成功') + expect(userApiMock.getUserList).toHaveBeenCalledTimes(1) + + userApiMock.getUserList.mockClear() + userApiMock.deleteUser.mockResolvedValueOnce({ code: ERROR_CODE, message: '不能删除当前用户' }) + + const refused = await userPageState.removeUser(2) + + expect(refused).toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('不能删除当前用户') + expect(userApiMock.getUserList).not.toHaveBeenCalled() + }) +}) + +describe('用户页状态:状态切换', () => { + beforeEach(resetState) + + it('按目标状态提交完整用户资料,锁定态归入启用方向', async () => { + userApiMock.getUserList.mockResolvedValue(LIST_SUCCESS) + userApiMock.updateUser.mockResolvedValue({ code: SUCCESS_CODE, data: makeUser(1) }) + + await userPageState.toggleUserStatus(makeUser(1, { status: 1 })) + + expect(userApiMock.updateUser).toHaveBeenCalledWith({ + id: 1, + username: 'user1', + email: 'user1@blog.test', + nickname: '用户1', + role: 'user', + birthday: '', + status: 0 + }) + expect(toastMock.success).toHaveBeenCalledWith('用户禁用成功') + expect(userApiMock.getUserList).toHaveBeenCalledTimes(1) + + await userPageState.toggleUserStatus(makeUser(2, { status: 2 })) + + expect(userApiMock.updateUser).toHaveBeenLastCalledWith( + expect.objectContaining({ id: 2, status: 1 }) + ) + expect(toastMock.success).toHaveBeenCalledWith('用户启用成功') + }) + + it('状态切换异常时提示网络错误且不刷新列表', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + userApiMock.updateUser.mockRejectedValue(new Error('断网')) + + await userPageState.toggleUserStatus(makeUser(1)) + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(userApiMock.getUserList).not.toHaveBeenCalled() + consoleError.mockRestore() + }) +}) + +describe('用户页状态:批量操作', () => { + beforeEach(resetState) + + it('批量删除与批量状态切换均按选中标识提交', async () => { + userApiMock.getUserList.mockResolvedValue(LIST_SUCCESS) + userApiMock.batchDeleteUsers.mockResolvedValue({ code: SUCCESS_CODE }) + userApiMock.batchUpdateUserStatus.mockResolvedValue({ code: SUCCESS_CODE }) + + userPageState.selectedIds = [1, 2] + await expect(userPageState.executeBatch('delete')).resolves.toBe(true) + expect(userApiMock.batchDeleteUsers).toHaveBeenCalledWith({ ids: [1, 2] }) + expect(toastMock.success).toHaveBeenCalledWith('批量删除成功') + + userPageState.selectedIds = [3] + await expect(userPageState.executeBatch('enable')).resolves.toBe(true) + expect(userApiMock.batchUpdateUserStatus).toHaveBeenCalledWith({ ids: [3], status: 1 }) + expect(toastMock.success).toHaveBeenCalledWith('批量启用成功') + + userPageState.selectedIds = [4] + await expect(userPageState.executeBatch('disable')).resolves.toBe(true) + expect(userApiMock.batchUpdateUserStatus).toHaveBeenCalledWith({ ids: [4], status: 0 }) + expect(toastMock.success).toHaveBeenCalledWith('批量禁用成功') + }) + + // 批量操作无论成败均在 finally 中刷新列表,避免选中项与后端状态脱节。 + it('批量操作失败与异常均提示错误并刷新当前页', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + userApiMock.getUserList.mockResolvedValue(LIST_SUCCESS) + + userPageState.selectedIds = [1] + userApiMock.batchDeleteUsers.mockResolvedValue({ + code: ERROR_CODE, + message: '存在不可删除的用户' + }) + + await expect(userPageState.executeBatch('delete')).resolves.toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('存在不可删除的用户') + expect(userApiMock.getUserList).toHaveBeenCalledTimes(1) + + userPageState.selectedIds = [2] + userApiMock.batchUpdateUserStatus.mockRejectedValue(new Error('断网')) + + await expect(userPageState.executeBatch('enable')).resolves.toBe(false) + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(userApiMock.getUserList).toHaveBeenCalledTimes(2) + consoleError.mockRestore() + }) +}) diff --git a/docs/architecture-rules.md b/docs/architecture-rules.md index fa8eb2c..ff3cf60 100644 --- a/docs/architecture-rules.md +++ b/docs/architecture-rules.md @@ -279,12 +279,12 @@ git grep -n "replicas" -- docker-compose.yml | 业务错误未归哨兵导致分档退化为 500 | [`debt/architecture.md`](./debt/architecture.md) 第 7 条 | 新增业务错误必须包装哨兵并同步登记契约 | | 两 app 基础设施逐字重复 | [`debt/frontend.md`](./debt/frontend.md) 第 1 条 | 修改任一必须同步另一份 | | admin 认证工具三轨并行 | [`debt/frontend.md`](./debt/frontend.md) 第 2 条 | 禁止新增认证工具文件与双轨回退 | -| admin 胖组件 + onMount 取数 | [`debt/frontend.md`](./debt/frontend.md) 第 3 条 | 新页面禁用 onMount 取数,缺口推回后端 | +| admin 胖组件 + onMount 取数 | [`debt/frontend.md`](./debt/frontend.md) 第 3 条 | 新页面禁用 onMount 取数;行数口径已清零,constants 不得引入图标库 | | web 首页 load 死代码 | [`debt/frontend.md`](./debt/frontend.md) 第 4 条 | 新页面禁用 load 调认证接口 | | 401 文案匹配 | [`debt/frontend.md`](./debt/frontend.md) 第 5 条 | 禁止回退文案匹配 | | admin 重写 `$ui` 已有组件(含 web 分页例外) | [`debt/frontend.md`](./debt/frontend.md) 第 6 条 | 新分页一律 `$ui`,禁止新增第三处实现 | | web 界面多语言局部接入 | [`debt/frontend.md`](./debt/frontend.md) 第 7 条 | 已接入文件禁止回退硬编码 | -| 字典页窄屏交互与工具栏布局遗留 | [`debt/frontend.md`](./debt/frontend.md) 第 8 条 | 触碰该页必须顺带处理 | +| 字典页窄屏交互与工具栏布局遗留 | [`debt/frontend.md`](./debt/frontend.md) 第 8 条 | 禁止回退为嵌套交互元素,窄屏列折叠与焦点环不得移除 | | 公开端点直出实体泄漏个人信息 | [`debt/security-runtime.md`](./debt/security-runtime.md) 第 1 条 | 个人信息须经窄化 DTO 或字段白名单 | | 文章响应泄漏作者审计字段 | [`debt/security-runtime.md`](./debt/security-runtime.md) 第 2 条 | 新增审计字段默认 `json:"-"` | | WAF 内容级黑名单的固有误伤面 | [`debt/security-runtime.md`](./debt/security-runtime.md) 第 3 条 | 阻止模式必须先红后绿并配两组用例 | @@ -303,7 +303,7 @@ git grep -n "replicas" -- docker-compose.yml | 阶段一 结构归位与错误分档 | 删 router 重复接口与不可达代码;错误分档(哨兵错误→404/403/400);令牌表加锁;web 死 load 清理;建立 `contracts/` 目录 | router 重复接口、web 死 load、401 判定均已修复;令牌表已加锁;`RBACService` 生产实例化点仅 1 处;not-found 哨兵→404 已落地,403/400 随错误码契约落地;全部业务错误归哨兵完成,认证失败经 `ErrUnauthenticated`→401,handler 私有映射分支清零 | ✅ `AGENTS.md` 第 2 节自检命令全绿 | | 阶段二 类型归位 | 建立 `internal/domain`,合并双 User,service/middleware/router 签名切换为 domain 类型;前端 auth 下沉共享包、影子类型清除 | 双 User 模型与影子类型层已修复;两 app 重复代码大幅减少(auth store 下沉);service 层 repository 依赖由 12 降至 11 | ✅ 依赖方向基线下降;auth store diff 为零 | | 阶段三 契约切换 | handler DTO 分离;`contracts/` + 三把锁双向锚定(替代 codegen);401 改错误码判定 | 401 文案匹配与审计字段泄漏已修复;三把锁已落地(`pnpm run contract:check`) | ✅ 影子类型归零;漂移必当天变红 | -| 阶段四 横切归位与权限下发 | 中间件坍缩为 IdentityProvider 策略;组合根按域装配;RBAC 权限表迁数据源并下发;admin 胖组件拆分、users 搜索推回后端 | `RBACService` 生产实例化点仅 1 处;users 跨页补偿与 admin 分页均已修复;RBAC 迁 config.yaml 完成;permissions 下发完成;follow API 模块已补齐;IdentityProvider 中间件坍缩完成(router 依赖 repository 归零、middleware 1 处);认证工具已统一 | 权限定义全栈唯一;认证工具单轨 ✅ | +| 阶段四 横切归位与权限下发 | 中间件坍缩为 IdentityProvider 策略;组合根按域装配;RBAC 权限表迁数据源并下发;admin 胖组件拆分、users 搜索推回后端 | `RBACService` 生产实例化点仅 1 处;users 跨页补偿与 admin 分页均已修复;RBAC 迁 config.yaml 完成;permissions 下发完成;follow API 模块已补齐;IdentityProvider 中间件坍缩完成(router 依赖 repository 归零、middleware 1 处);认证工具已统一;admin 胖组件行数口径 7→0,7 个页面取数归位到 load + 页面状态模块 | 权限定义全栈唯一;认证工具单轨 ✅ | | 阶段五 扩展点 | 后端 ContentRenderer 内容策略接口(当前 `pkg/markdown` 已直接承接 Markdown 渲染,策略接口化待做);web 业务页面已按"公开数据 SSR + 个性化数据客户端补拉"现状接入,token 迁 cookie 已完成 | — | 新文章类型 = 插入实现,非逐层打洞 | --- diff --git a/docs/debt/frontend.md b/docs/debt/frontend.md index 64db540..b5666c5 100644 --- a/docs/debt/frontend.md +++ b/docs/debt/frontend.md @@ -19,10 +19,13 @@ ## 3. admin 胖组件 + onMount 取数 -- **状态**:存量。 -- **基线**:口径为「`apps/admin/src/routes` 下单文件 > 300 行」,当前 **7 个**,降序为 tags 454 / links 405 / users 404 / dicts 344 / comments 331 / media 323 / categories 322;路由 svelte 文件共 19 个。`onMount` 取数命中 14 个路由文件。users 跨页补偿已移除,`users/list` 支持 keyword。 -- **验证命令**:`git grep -ln "onMount" -- "apps/admin/src/routes"`;行数按上述口径统计。 -- **红线**:新页面禁用 onMount 取数,优先 load + 页面状态模块(`.svelte.ts`);禁止复制 300 行以上胖组件;后端能力缺口推回后端修复。 +- **状态**:存量,行数口径已清零,仅余非胖页面的 onMount 取数。 +- **基线**: + - 行数口径:`apps/admin/src/routes` 下单文件 > 300 行的页面为 **0** 个;修复前为 7 个,降序为 tags 454 / links 405 / users 404 / dicts 344 / comments 332 / media 323 / categories 322。路由 svelte 文件仍为 19 个,新增的 7 个展示组件下沉在 `lib/components/admin//`,不进入该口径。 + - 取数口径:`onMount` 命中 **8** 个路由文件,其中 2 个属鉴权重定向而非取数,不计入:`(admin)/+layout.svelte`、`(auth)/login/+page.svelte`;剩余取数 **6** 个页面为存量:`(admin)/+page.svelte`(仪表盘)、notifications、posts、`posts/[id]`、settings、stats。修复前取数命中 12 个页面。 + - 已按「`+page.ts` 的 load 取首屏 → `-page-state.svelte.ts` 持有列表与全部读写操作 → `+page.svelte` 只做渲染」重构 7 个原胖页面,页面状态模块 7 个(含 dicts 原有)与配套单测 7 个,合计 146 个用例经 `pnpm run test:apps` 门禁。 +- **验证命令**:`git grep -ln "onMount" -- "apps/admin/src/routes"`(应为 8 个文件,鉴权 2 + 取数 6);行数按「`apps/admin/src/routes` 下单文件 > 300 行」统计;在 `apps/admin` 下执行 `pnpm run check && pnpm run test`。 +- **红线**:新页面禁用 onMount 取数,一律 load + 页面状态模块;禁止复制 300 行以上胖组件;后端能力缺口推回后端修复;`lib/constants/*.ts` 不得引入 `@lucide/svelte`,图标映射随其唯一消费者组件声明,否则页面状态模块与单测的编译图会带入图标桶(comments 单测实测由 126 秒降至 5 秒)。 ## 4. web 首页 load 死代码 @@ -54,7 +57,7 @@ ## 8. 字典页窄屏交互与工具栏布局遗留 -- **状态**:存量。 -- **基线**:`apps/admin/src/routes/(admin)/dicts/+page.svelte` 的类型列表窄屏交互与工具栏布局打磨未完成。该页同时是 7 个胖组件之一(344 行),两个问题可在同一次触碰中一并处理。 -- **验证命令**:读该页的类型列表与工具栏区块在窄屏下的布局。 -- **红线**:触碰该页时必须顺带处理,不得再次遗留;不得以「已记录在提交信息」替代债务登记。 +- **状态**:已修复。 +- **基线**:`apps/admin/src/routes/(admin)/dicts/+page.svelte` 由 344 行收敛至 174 行,类型列表与字典项表格分别下沉 `lib/components/admin/dict/dict-type-list.svelte` 与 `dict-item-table.svelte`,状态展示配置下沉 `lib/constants/dict.ts`。窄屏交互修复项:类型列表行原先把编辑与删除按钮嵌在选择行按钮内部,构成非法的按钮嵌套并导致窄屏点击区域争抢,现改为选择区按钮与行内操作按钮并列;操作按钮统一 `size="icon"` 并带含字典类型名的 `aria-label`;选择区补 `focus-visible` 焦点环与 `aria-current`。工具栏与表格修复项:字典项卡片头部改 `flex-wrap` 避免窄屏挤压,描述列在窄屏并入显示名列副行并按 `md` 断点恢复独立列,排序列在 `sm` 以下折叠;加载态改用 `$ui/spinner`,空态改用 `$ui/empty`,替换原先手写的旋转圆环与空态容器。 +- **验证命令**:读 `lib/components/admin/dict/dict-type-list.svelte` 确认选择区与操作区为并列元素;`get-childitem "apps/admin/src/routes/(admin)/dicts/+page.svelte"` 行数应低于 300;在 `apps/admin` 下执行 `pnpm run check` 与 `pnpm run test`。 +- **红线**:触碰该页时必须顺带处理,不得再次遗留;列表行的选择与操作不得回退为嵌套交互元素。 From ad3ab543533fd0eebaa29b2e2ee76ae156bc1087 Mon Sep 17 00:00:00 2001 From: idleRain Date: Tue, 13 Oct 2026 15:52:11 +0800 Subject: [PATCH 3/5] =?UTF-8?q?refactor(test):=20=E5=89=8D=E7=AB=AF?= =?UTF-8?q?=E6=B5=8B=E8=AF=95=E6=96=87=E4=BB=B6=E5=BD=92=E5=85=A5=20=5F=5F?= =?UTF-8?q?tests=5F=5F=20=E7=9B=AE=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 测试文件不再与业务文件平级,17 个 *.test.ts 移入被测模块同级的 __tests__/; packages/auth 的测试替身独立为 src/test/fixtures.ts。同步修正移动后的相对导入 层级、server 侧契约锚点常量,以及 contracts 与 docs 中的引用路径。 --- AGENTS.md | 1 + .../constants/{ => __tests__}/dict.test.ts | 2 +- .../utils/{ => __tests__}/tag-display.test.ts | 2 +- .../category-page-state.test.ts | 2 +- .../comment-page-state.test.ts | 2 +- .../{ => __tests__}/dict-page-state.test.ts | 2 +- .../{ => __tests__}/link-page-state.test.ts | 2 +- .../{ => __tests__}/media-page-state.test.ts | 2 +- .../{ => __tests__}/tag-page-state.test.ts | 2 +- .../{ => __tests__}/user-page-state.test.ts | 2 +- .../markdown/{ => __tests__}/render.test.ts | 2 +- .../lib/service/{ => __tests__}/ssr.test.ts | 0 .../utils/{ => __tests__}/format-date.test.ts | 2 +- contracts/README.md | 2 +- contracts/errors.yaml | 2 +- docs/architecture-rules.md | 4 +-- docs/development.md | 1 + .../contracts/{ => __tests__}/errors.test.ts | 2 +- .../{ => __tests__}/fixtures.test.ts | 36 +++++++++---------- .../dict/{ => __tests__}/helpers.test.ts | 4 +-- .../src/{ => __tests__}/auth-store.test.ts | 4 +-- .../{test-fixtures.ts => test/fixtures.ts} | 0 .../http/src/{ => __tests__}/client.test.ts | 2 +- .../internal/handler/fixture_coverage_test.go | 2 +- 24 files changed, 42 insertions(+), 40 deletions(-) rename apps/admin/src/lib/constants/{ => __tests__}/dict.test.ts (97%) rename apps/admin/src/lib/utils/{ => __tests__}/tag-display.test.ts (99%) rename apps/admin/src/routes/(admin)/categories/{ => __tests__}/category-page-state.test.ts (99%) rename apps/admin/src/routes/(admin)/comments/{ => __tests__}/comment-page-state.test.ts (99%) rename apps/admin/src/routes/(admin)/dicts/{ => __tests__}/dict-page-state.test.ts (99%) rename apps/admin/src/routes/(admin)/links/{ => __tests__}/link-page-state.test.ts (99%) rename apps/admin/src/routes/(admin)/media/{ => __tests__}/media-page-state.test.ts (99%) rename apps/admin/src/routes/(admin)/tags/{ => __tests__}/tag-page-state.test.ts (99%) rename apps/admin/src/routes/(admin)/users/{ => __tests__}/user-page-state.test.ts (99%) rename apps/web/src/lib/markdown/{ => __tests__}/render.test.ts (98%) rename apps/web/src/lib/service/{ => __tests__}/ssr.test.ts (100%) rename apps/web/src/lib/utils/{ => __tests__}/format-date.test.ts (95%) rename packages/api/src/contracts/{ => __tests__}/errors.test.ts (99%) rename packages/api/src/contracts/{ => __tests__}/fixtures.test.ts (79%) rename packages/api/src/modules/dict/{ => __tests__}/helpers.test.ts (94%) rename packages/auth/src/{ => __tests__}/auth-store.test.ts (98%) rename packages/auth/src/{test-fixtures.ts => test/fixtures.ts} (100%) rename packages/http/src/{ => __tests__}/client.test.ts (99%) diff --git a/AGENTS.md b/AGENTS.md index 99fa192..25da13a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -111,6 +111,7 @@ pnpm run go:lint-install / go:quality / go:vulncheck / audit:deps - **导入排序**:prettier 挂载 `prettier-plugin-sort-imports`,排序依据是单条 import 语句的字符长度,语句越长越靠前,既不看模块名字母序也不区分外部依赖与相对路径。这是既定规范,导入块看似错乱时不要手工调整,手工修改会被下次格式化还原。 - **格式化覆盖范围**:lint-staged 仅对 `apps/**/src/**` 运行 prettier,对 `server/**/*.go` 运行 gofmt 与 goimports;`packages/**` 不在任何 format 门禁覆盖内,新增或改动 packages 文件须手动执行 `npx prettier --write `。 - **注释**:只解释代码无法直接表达的意图、业务规则、约束、原因、风险与副作用,不复述代码;具体要求遵循全局规范。 +- **测试文件位置**:前端测试文件不与业务文件同级,一律置于被测模块同级的 `__tests__/` 目录;跨用例共享的测试替身与夹具置于包内 `src/test/`,不放入 `__tests__/`。vitest 的 `include` 与各 tsconfig 的 `src/**/*.ts` 已覆盖这两类目录。 - **测试现状**:后端 `service`、`repository`、`handler`、`middleware`、`router`、`config`、`database`、`pkg/*` 均有 `*_test.go`,新增后端关键逻辑必须配套同目录测试。`packages/api`、`packages/auth`、`packages/http` 均已有 `typecheck` 与 vitest 单测,并经 `pnpm run test:packages` 串联纳入门禁;两应用单测经 `pnpm run test:apps`(admin 覆盖 `dict-page-state.svelte.ts`,web 覆盖 `render.ts` 的原始 HTML 丢弃守卫与目录日期格式化)。新增 packages 公共逻辑与页面状态模块(`.svelte.ts`)须配套 `*.test.ts`,并为所在 package 补 `typecheck`、`test` 脚本且登记进根 `test:packages`。`pnpm run check` 与 `typecheck:web` 只做类型检查,不是单元测试。 - **提交**:提交信息用简体中文、符合 commitlint 的 conventional commits(type 枚举见 `commitlint.config.js`);单次提交跨度过大时补充正文说明。 diff --git a/apps/admin/src/lib/constants/dict.test.ts b/apps/admin/src/lib/constants/__tests__/dict.test.ts similarity index 97% rename from apps/admin/src/lib/constants/dict.test.ts rename to apps/admin/src/lib/constants/__tests__/dict.test.ts index 9c6fc60..b8f1a23 100644 --- a/apps/admin/src/lib/constants/dict.test.ts +++ b/apps/admin/src/lib/constants/__tests__/dict.test.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from 'vitest' -import { DICT_STATUS_DISABLED, DICT_STATUS_ENABLED, dictStatusOf } from './dict' +import { DICT_STATUS_DISABLED, DICT_STATUS_ENABLED, dictStatusOf } from '../dict' describe('字典状态展示配置', () => { it('生效状态返回主色样式与生效文案', () => { diff --git a/apps/admin/src/lib/utils/tag-display.test.ts b/apps/admin/src/lib/utils/__tests__/tag-display.test.ts similarity index 99% rename from apps/admin/src/lib/utils/tag-display.test.ts rename to apps/admin/src/lib/utils/__tests__/tag-display.test.ts index e44376a..bc1e6bf 100644 --- a/apps/admin/src/lib/utils/tag-display.test.ts +++ b/apps/admin/src/lib/utils/__tests__/tag-display.test.ts @@ -1,7 +1,7 @@ import type { EnabledDictGroup } from '@myblog/api/modules/dict/types' import { describe, expect, it } from 'vitest' -import { resolveTagStatusLabel, resolveTagStatusVariant } from './tag-display' +import { resolveTagStatusLabel, resolveTagStatusVariant } from '../tag-display' // 构造最小可用的状态字典分组,仅覆盖解析所需的字段。 function statusDictWithVariant(variant: string, label: string): EnabledDictGroup { diff --git a/apps/admin/src/routes/(admin)/categories/category-page-state.test.ts b/apps/admin/src/routes/(admin)/categories/__tests__/category-page-state.test.ts similarity index 99% rename from apps/admin/src/routes/(admin)/categories/category-page-state.test.ts rename to apps/admin/src/routes/(admin)/categories/__tests__/category-page-state.test.ts index 3c6b541..d239889 100644 --- a/apps/admin/src/routes/(admin)/categories/category-page-state.test.ts +++ b/apps/admin/src/routes/(admin)/categories/__tests__/category-page-state.test.ts @@ -19,7 +19,7 @@ const toastMock = { vi.mock('$lib/api', () => ({ CategoryAPI: categoryApiMock })) vi.mock('svelte-sonner', () => ({ toast: toastMock })) -const { emptyCategoryPageData, categoryPageState } = await import('./category-page-state.svelte') +const { emptyCategoryPageData, categoryPageState } = await import('../category-page-state.svelte') // 后端统一响应的成功业务码。 const SUCCESS_CODE = 200 diff --git a/apps/admin/src/routes/(admin)/comments/comment-page-state.test.ts b/apps/admin/src/routes/(admin)/comments/__tests__/comment-page-state.test.ts similarity index 99% rename from apps/admin/src/routes/(admin)/comments/comment-page-state.test.ts rename to apps/admin/src/routes/(admin)/comments/__tests__/comment-page-state.test.ts index 5a4afbd..447b0b8 100644 --- a/apps/admin/src/routes/(admin)/comments/comment-page-state.test.ts +++ b/apps/admin/src/routes/(admin)/comments/__tests__/comment-page-state.test.ts @@ -21,7 +21,7 @@ const toastMock = { vi.mock('$lib/api', () => ({ CommentAPI: commentApiMock })) vi.mock('svelte-sonner', () => ({ toast: toastMock })) -const { emptyCommentPageData, commentPageState } = await import('./comment-page-state.svelte') +const { emptyCommentPageData, commentPageState } = await import('../comment-page-state.svelte') // 后端统一响应的成功业务码。 const SUCCESS_CODE = 200 diff --git a/apps/admin/src/routes/(admin)/dicts/dict-page-state.test.ts b/apps/admin/src/routes/(admin)/dicts/__tests__/dict-page-state.test.ts similarity index 99% rename from apps/admin/src/routes/(admin)/dicts/dict-page-state.test.ts rename to apps/admin/src/routes/(admin)/dicts/__tests__/dict-page-state.test.ts index 521af06..a8b6667 100644 --- a/apps/admin/src/routes/(admin)/dicts/dict-page-state.test.ts +++ b/apps/admin/src/routes/(admin)/dicts/__tests__/dict-page-state.test.ts @@ -22,7 +22,7 @@ vi.mock('$lib/api', () => ({ DictAPI: apiMock })) vi.mock('svelte-sonner', () => ({ toast: toastMock })) const { DICT_PAGE_SIZE, emptyDictPageData, dictPageState } = - await import('./dict-page-state.svelte') + await import('../dict-page-state.svelte') // 后端统一响应的成功业务码。 const SUCCESS_CODE = 200 diff --git a/apps/admin/src/routes/(admin)/links/link-page-state.test.ts b/apps/admin/src/routes/(admin)/links/__tests__/link-page-state.test.ts similarity index 99% rename from apps/admin/src/routes/(admin)/links/link-page-state.test.ts rename to apps/admin/src/routes/(admin)/links/__tests__/link-page-state.test.ts index cc78909..b6ed237 100644 --- a/apps/admin/src/routes/(admin)/links/link-page-state.test.ts +++ b/apps/admin/src/routes/(admin)/links/__tests__/link-page-state.test.ts @@ -22,7 +22,7 @@ const toastMock = { vi.mock('$lib/api', () => ({ FriendlyLinkAPI: friendlyLinkApiMock })) vi.mock('svelte-sonner', () => ({ toast: toastMock })) -const { emptyLinkPageData, linkPageState } = await import('./link-page-state.svelte') +const { emptyLinkPageData, linkPageState } = await import('../link-page-state.svelte') // 后端统一响应的成功业务码。 const SUCCESS_CODE = 200 diff --git a/apps/admin/src/routes/(admin)/media/media-page-state.test.ts b/apps/admin/src/routes/(admin)/media/__tests__/media-page-state.test.ts similarity index 99% rename from apps/admin/src/routes/(admin)/media/media-page-state.test.ts rename to apps/admin/src/routes/(admin)/media/__tests__/media-page-state.test.ts index ad68607..ed60c58 100644 --- a/apps/admin/src/routes/(admin)/media/media-page-state.test.ts +++ b/apps/admin/src/routes/(admin)/media/__tests__/media-page-state.test.ts @@ -26,7 +26,7 @@ const clipboardMock = { vi.mock('$lib/api', () => ({ MediaAPI: mediaApiMock })) vi.mock('svelte-sonner', () => ({ toast: toastMock })) -const { emptyMediaPageData, mediaPageState } = await import('./media-page-state.svelte') +const { emptyMediaPageData, mediaPageState } = await import('../media-page-state.svelte') // 后端统一响应的成功业务码。 const SUCCESS_CODE = 200 diff --git a/apps/admin/src/routes/(admin)/tags/tag-page-state.test.ts b/apps/admin/src/routes/(admin)/tags/__tests__/tag-page-state.test.ts similarity index 99% rename from apps/admin/src/routes/(admin)/tags/tag-page-state.test.ts rename to apps/admin/src/routes/(admin)/tags/__tests__/tag-page-state.test.ts index 6e51606..43237c3 100644 --- a/apps/admin/src/routes/(admin)/tags/tag-page-state.test.ts +++ b/apps/admin/src/routes/(admin)/tags/__tests__/tag-page-state.test.ts @@ -24,7 +24,7 @@ const toastMock = { vi.mock('$lib/api', () => ({ TagAPI: tagApiMock, DictAPI: dictApiMock })) vi.mock('svelte-sonner', () => ({ toast: toastMock })) -const { emptyTagPageData, tagPageState } = await import('./tag-page-state.svelte') +const { emptyTagPageData, tagPageState } = await import('../tag-page-state.svelte') // 后端统一响应的成功业务码。 const SUCCESS_CODE = 200 diff --git a/apps/admin/src/routes/(admin)/users/user-page-state.test.ts b/apps/admin/src/routes/(admin)/users/__tests__/user-page-state.test.ts similarity index 99% rename from apps/admin/src/routes/(admin)/users/user-page-state.test.ts rename to apps/admin/src/routes/(admin)/users/__tests__/user-page-state.test.ts index 6390f8c..0515b36 100644 --- a/apps/admin/src/routes/(admin)/users/user-page-state.test.ts +++ b/apps/admin/src/routes/(admin)/users/__tests__/user-page-state.test.ts @@ -27,7 +27,7 @@ vi.mock('$lib/stores/auth', () => ({ authStore: { getCurrentState: () => authState } })) -const { emptyUserPageData, userPageState } = await import('./user-page-state.svelte') +const { emptyUserPageData, userPageState } = await import('../user-page-state.svelte') // 后端统一响应的成功业务码。 const SUCCESS_CODE = 200 diff --git a/apps/web/src/lib/markdown/render.test.ts b/apps/web/src/lib/markdown/__tests__/render.test.ts similarity index 98% rename from apps/web/src/lib/markdown/render.test.ts rename to apps/web/src/lib/markdown/__tests__/render.test.ts index f1fecef..1d85647 100644 --- a/apps/web/src/lib/markdown/render.test.ts +++ b/apps/web/src/lib/markdown/__tests__/render.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from 'vitest' -import { renderMarkdown } from './render' +import { renderMarkdown } from '../render' // 正文渲染是存储型注入的唯一入口:文章源文本由作者提供,渲染结果经 {@html} 挂载。 // 当前纵深防御完全依赖两条配置常数——remark-rehype 未开启 allowDangerousHtml, diff --git a/apps/web/src/lib/service/ssr.test.ts b/apps/web/src/lib/service/__tests__/ssr.test.ts similarity index 100% rename from apps/web/src/lib/service/ssr.test.ts rename to apps/web/src/lib/service/__tests__/ssr.test.ts diff --git a/apps/web/src/lib/utils/format-date.test.ts b/apps/web/src/lib/utils/__tests__/format-date.test.ts similarity index 95% rename from apps/web/src/lib/utils/format-date.test.ts rename to apps/web/src/lib/utils/__tests__/format-date.test.ts index cbbd979..c743d13 100644 --- a/apps/web/src/lib/utils/format-date.test.ts +++ b/apps/web/src/lib/utils/__tests__/format-date.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from 'vitest' -import { formatDate } from './format-date' +import { formatDate } from '../format-date' describe('目录日期格式化', () => { it('截取 ISO 字符串的日期段,输出 YYYY-MM-DD', () => { diff --git a/contracts/README.md b/contracts/README.md index 90a3b88..d5b4b49 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -30,5 +30,5 @@ - 新增 not-found 哨兵错误须同步扩展 `handler/error.go` 的映射注册表与 `errors.yaml`, 两侧由 `TestErrorMappingMatchesContract` 双向锚定,任一侧漏登记即变红。 - 响应码常量新增或改值须同步 `server/pkg/response`、`packages/shared/src/constants/api.ts` - 与 `errors.yaml` 的 `transport` 节,并登记 `packages/api/src/contracts/errors.test.ts` 的名称对应表。 + 与 `errors.yaml` 的 `transport` 节,并登记 `packages/api/src/contracts/__tests__/errors.test.ts` 的名称对应表。 - 前端不新增权限/类型/刷新的手写副本,一律消费后端下发值或 `@myblog/api` 类型。 diff --git a/contracts/errors.yaml b/contracts/errors.yaml index b81f5d1..ae1c854 100644 --- a/contracts/errors.yaml +++ b/contracts/errors.yaml @@ -4,7 +4,7 @@ # 锚定方式复用 docs/architecture-rules.md §3.4 的双向锚定,不引入 codegen: # - 后端:internal/handler/error_contract_test.go 的 TestErrorMappingMatchesContract, # 校验本文件 transport 节与 pkg/response 常量一致、mapping 节与 handler 分档注册表双向一致; -# - 前端:packages/api/src/contracts/errors.test.ts, +# - 前端:packages/api/src/contracts/__tests__/errors.test.ts, # 校验 @myblog/shared 的响应码常量与 pkg/response 逐值一致。 # 任一侧单独改动即变红,门禁入口为 pnpm run contract:check。 diff --git a/docs/architecture-rules.md b/docs/architecture-rules.md index ff3cf60..08f7caa 100644 --- a/docs/architecture-rules.md +++ b/docs/architecture-rules.md @@ -107,7 +107,7 @@ git grep -n "interface BaseApiResponse" -- apps | 锁 | 机制 | 落地状态 | |---|---|---| | ① | Go handler 测试断言响应与 `contracts/fixtures/` 语义逐字节一致 | ✅ `handler/{fixture_locks,login_fixture,session_fixture,article_fixture,comment_fixture}_test.go`(**15/15 金样本**,覆盖认证会话、文章、评论三条核心链路) | -| ② | TS 侧 `tsc --noEmit`(挂入 contract:check)+ `expectTypeOf(fixture).toExtend>` 单向合法实例校验 | ✅ `packages/api/src/contracts/fixtures.test.ts`(15 用例,与 ① 一一对应) | +| ② | TS 侧 `tsc --noEmit`(挂入 contract:check)+ `expectTypeOf(fixture).toExtend>` 单向合法实例校验 | ✅ `packages/api/src/contracts/__tests__/fixtures.test.ts`(15 用例,与 ① 一一对应) | | ③ | eslint `no-restricted-imports` 禁止应用层定义同构类型 | ✅ `apps/admin` 与 `apps/web` 双侧 eslint.config.js | **覆盖对齐**:`TestFixtureCoverage` 以目录扫描为准,校验每个金样本都同时被 Go 侧断言与 TS 侧锚定引用,且引用的金样本确实存在;新增金样本却漏写任一端锚点即变红,金样本清单不依赖人工登记表维护。 @@ -120,7 +120,7 @@ git grep -n "interface BaseApiResponse" -- apps **错误码契约的同类锚定**:`contracts/errors.yaml` 同样不引入 codegen 生成物,改用双向锚定: Go 侧 `internal/handler/error_contract_test.go` 的 `TestErrorMappingMatchesContract` 校验 `transport` 节与 `pkg/response` 常量一致、 -`mapping` 节与 `handler` 分档注册表双向一致;前端侧 `packages/api/src/contracts/errors.test.ts` 校验 `@myblog/shared` 的响应码常量与 `pkg/response` 逐值一致。 +`mapping` 节与 `handler` 分档注册表双向一致;前端侧 `packages/api/src/contracts/__tests__/errors.test.ts` 校验 `@myblog/shared` 的响应码常量与 `pkg/response` 逐值一致。 两侧任一方单独改动即变红,门禁入口同上。 **升级触发器**(命中任一则改用 codegen 方案): diff --git a/docs/development.md b/docs/development.md index 846c745..97a07dc 100644 --- a/docs/development.md +++ b/docs/development.md @@ -630,6 +630,7 @@ pnpm run build:web # 构建前端静态文件 - **文档更新**: 架构规则变更时按 [`architecture-rules.md`](./architecture-rules.md) 同步规则本体与第 8 节债务索引;债务条目的状态与基线数值按 [`debt/README.md`](./debt/README.md) 的维护纪律更新对应分册,历史分期状态更新第 9 节 - **自动化测试**: 后端关键逻辑配套 `*_test.go`(service/repository 层已有存量);前端 packages 公共逻辑与页面状态模块应补 `*.test.ts`。应用侧单测经根 `test:apps` 汇聚(`@myblog/web` 覆盖 markdown 渲染守卫、日期格式化与服务端会话 Cookie 转发,`@myblog/admin` 覆盖字典页状态模块),并与 `test:packages` 一样纳入 `pnpm run test` 与 CI。 +- **测试文件位置**: 前端测试文件不与业务文件同级,一律置于被测模块同级的 `__tests__/` 目录(例如 `apps/admin/src/lib/utils/__tests__/tag-display.test.ts`);跨用例共享的测试替身与夹具置于包内 `src/test/`(例如 `packages/auth/src/test/fixtures.ts`),不放入 `__tests__/`。移动测试文件后须同步修正其相对导入层级,并检查写死测试文件路径的外部锚点(如 `server/internal/handler/fixture_coverage_test.go` 的 TS 锚点常量)。 ## 更多资源 diff --git a/packages/api/src/contracts/errors.test.ts b/packages/api/src/contracts/__tests__/errors.test.ts similarity index 99% rename from packages/api/src/contracts/errors.test.ts rename to packages/api/src/contracts/__tests__/errors.test.ts index b9063f1..34c5d43 100644 --- a/packages/api/src/contracts/errors.test.ts +++ b/packages/api/src/contracts/__tests__/errors.test.ts @@ -7,7 +7,7 @@ import { dirname, resolve } from 'node:path' import { fileURLToPath } from 'node:url' import { readFileSync } from 'node:fs' -const repositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..') +const repositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../..') const goResponsePath = resolve(repositoryRoot, 'server/pkg/response/response.go') const sharedConstantsPath = resolve(repositoryRoot, 'packages/shared/src/constants/api.ts') diff --git a/packages/api/src/contracts/fixtures.test.ts b/packages/api/src/contracts/__tests__/fixtures.test.ts similarity index 79% rename from packages/api/src/contracts/fixtures.test.ts rename to packages/api/src/contracts/__tests__/fixtures.test.ts index 164311c..fd2fd45 100644 --- a/packages/api/src/contracts/fixtures.test.ts +++ b/packages/api/src/contracts/__tests__/fixtures.test.ts @@ -9,24 +9,24 @@ import type { ArticleActionData, ArticleArchiveYear, ArticleListData -} from '../modules/article/types' -import type { AdminCommentListData, Comment, CommentListData } from '../modules/comment/types' -import loginWrongPassword from '../../../../contracts/fixtures/login.wrong-password.json' -import commentAdminList from '../../../../contracts/fixtures/comment.admin-list.json' -import articleNotFound from '../../../../contracts/fixtures/article.not-found.json' -import commentApproved from '../../../../contracts/fixtures/comment.approved.json' -import articleArchives from '../../../../contracts/fixtures/article.archives.json' -import type { LoginData, SessionData, UserListData } from '../modules/user/types' -import sessionCreated from '../../../../contracts/fixtures/session.created.json' -import commentCreated from '../../../../contracts/fixtures/comment.created.json' -import articleDeleted from '../../../../contracts/fixtures/article.deleted.json' -import articleCreated from '../../../../contracts/fixtures/article.created.json' -import logoutSuccess from '../../../../contracts/fixtures/logout.success.json' -import articleDetail from '../../../../contracts/fixtures/article.detail.json' -import loginSuccess from '../../../../contracts/fixtures/login.success.json' -import commentList from '../../../../contracts/fixtures/comment.list.json' -import articleList from '../../../../contracts/fixtures/article.list.json' -import usersList from '../../../../contracts/fixtures/users.list.json' +} from '../../modules/article/types' +import type { AdminCommentListData, Comment, CommentListData } from '../../modules/comment/types' +import loginWrongPassword from '../../../../../contracts/fixtures/login.wrong-password.json' +import commentAdminList from '../../../../../contracts/fixtures/comment.admin-list.json' +import articleNotFound from '../../../../../contracts/fixtures/article.not-found.json' +import commentApproved from '../../../../../contracts/fixtures/comment.approved.json' +import articleArchives from '../../../../../contracts/fixtures/article.archives.json' +import type { LoginData, SessionData, UserListData } from '../../modules/user/types' +import sessionCreated from '../../../../../contracts/fixtures/session.created.json' +import commentCreated from '../../../../../contracts/fixtures/comment.created.json' +import articleDeleted from '../../../../../contracts/fixtures/article.deleted.json' +import articleCreated from '../../../../../contracts/fixtures/article.created.json' +import logoutSuccess from '../../../../../contracts/fixtures/logout.success.json' +import articleDetail from '../../../../../contracts/fixtures/article.detail.json' +import loginSuccess from '../../../../../contracts/fixtures/login.success.json' +import commentList from '../../../../../contracts/fixtures/comment.list.json' +import articleList from '../../../../../contracts/fixtures/article.list.json' +import usersList from '../../../../../contracts/fixtures/users.list.json' import { describe, expect, expectTypeOf, it } from 'vitest' // 将字面量与联合类型放宽为对应基础类型,用于与 JSON 导入值的推导类型做精确比对。 diff --git a/packages/api/src/modules/dict/helpers.test.ts b/packages/api/src/modules/dict/__tests__/helpers.test.ts similarity index 94% rename from packages/api/src/modules/dict/helpers.test.ts rename to packages/api/src/modules/dict/__tests__/helpers.test.ts index b435442..ec7ab89 100644 --- a/packages/api/src/modules/dict/helpers.test.ts +++ b/packages/api/src/modules/dict/__tests__/helpers.test.ts @@ -1,7 +1,7 @@ import { describe, expect, it } from 'vitest' -import { dictItemLabel, findDictItem } from './helpers.ts' -import type { EnabledDictGroup } from './types.ts' +import { dictItemLabel, findDictItem } from '../helpers.ts' +import type { EnabledDictGroup } from '../types.ts' // 构造标签状态字典分组的测试夹具。 function buildTagStatusGroup(): EnabledDictGroup { diff --git a/packages/auth/src/auth-store.test.ts b/packages/auth/src/__tests__/auth-store.test.ts similarity index 98% rename from packages/auth/src/auth-store.test.ts rename to packages/auth/src/__tests__/auth-store.test.ts index c7a8af1..e12c992 100644 --- a/packages/auth/src/auth-store.test.ts +++ b/packages/auth/src/__tests__/auth-store.test.ts @@ -1,6 +1,6 @@ // 认证 store 的登录持久化、单飞续期调度与跨标签页同步单元测试。 -import { installFakeBrowserEnv, AUTH_USER_KEY, UNRELATED_KEY } from './test-fixtures' -import { createAuthStore, type AuthStoreDeps } from './auth-store' +import { installFakeBrowserEnv, AUTH_USER_KEY, UNRELATED_KEY } from '../test/fixtures' +import { createAuthStore, type AuthStoreDeps } from '../auth-store' import { afterEach, describe, expect, it, vi } from 'vitest' import type { User } from '@myblog/api/modules/user/types' import { get } from 'svelte/store' diff --git a/packages/auth/src/test-fixtures.ts b/packages/auth/src/test/fixtures.ts similarity index 100% rename from packages/auth/src/test-fixtures.ts rename to packages/auth/src/test/fixtures.ts diff --git a/packages/http/src/client.test.ts b/packages/http/src/__tests__/client.test.ts similarity index 99% rename from packages/http/src/client.test.ts rename to packages/http/src/__tests__/client.test.ts index 0c2ad24..0b8996a 100644 --- a/packages/http/src/client.test.ts +++ b/packages/http/src/__tests__/client.test.ts @@ -1,6 +1,6 @@ // HTTP 请求器会话续期与重放行为的单元测试。 // 覆盖 401 之后"续期一次、重放一次、再失败即判定认证失效"的完整语义。 -import { createHttpClient, type HttpClientAuthHooks } from './client' +import { createHttpClient, type HttpClientAuthHooks } from '../client' import { beforeEach, describe, expect, it, vi } from 'vitest' import type { AfterResponseHook } from 'ky' diff --git a/server/internal/handler/fixture_coverage_test.go b/server/internal/handler/fixture_coverage_test.go index 5b126d9..630b2f1 100644 --- a/server/internal/handler/fixture_coverage_test.go +++ b/server/internal/handler/fixture_coverage_test.go @@ -13,7 +13,7 @@ import ( var fixtureAssertCallPattern = regexp.MustCompile(`assertResponseMatchesFixture\([^)]*"([^"]+\.json)"\)`) // fixtureTSAnchorPath TS 侧契约锚定文件路径,用于校验金样本在双端均有锚点。 -const fixtureTSAnchorPath = "../../../packages/api/src/contracts/fixtures.test.ts" +const fixtureTSAnchorPath = "../../../packages/api/src/contracts/__tests__/fixtures.test.ts" // fixtureTSAnchorPattern 匹配 TS 锚定文件中对金样本的引用路径,捕获金样本文件名。 var fixtureTSAnchorPattern = regexp.MustCompile(`contracts/fixtures/([A-Za-z0-9._-]+\.json)`) From 169bd34c517f99b63105c683320cff389544df0a Mon Sep 17 00:00:00 2001 From: idleRain Date: Tue, 13 Oct 2026 16:26:53 +0800 Subject: [PATCH 4/5] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=E5=B7=A5?= =?UTF-8?q?=E7=A8=8B=E8=A7=84=E8=8C=83=E8=BF=87=E6=97=B6=E8=A1=A8=E8=BF=B0?= =?UTF-8?q?=E5=B9=B6=E7=BB=9F=E4=B8=80=E6=96=87=E6=A1=A3=E5=BC=95=E7=94=A8?= =?UTF-8?q?=E6=96=B9=E5=90=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 修正后端校验、测试清单、lint-staged 覆盖范围与响应信封语义等与实现不符的表述 - 按实际实现订正应用层 DTO 归属口径,同步接口文档 - 其他文档不再按节引用根规范文件,相关条文改由各文档自持 - 合并条文搬迁产生的重复内容并收敛根规范体量 --- AGENTS.md | 92 +++++++++++++--------------- deploy/observability/alerts.yml | 2 +- docs/architecture-rules.md | 6 +- docs/database-architecture.md | 6 +- docs/development.md | 16 ++--- docs/ui-design-system.md | 2 +- server/docs/api/api-specification.md | 2 +- server/internal/config/README.md | 2 +- server/internal/handler/README.md | 2 - server/internal/middleware/README.md | 4 +- server/internal/repository/README.md | 2 +- server/internal/service/README.md | 2 +- server/pkg/response/README.md | 2 +- 13 files changed, 64 insertions(+), 76 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 25da13a..d47b97d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,8 @@ # MyBlog 工程规范 -> 本文件只保留结构性红线与高频约定;完整裁决标准、历史案例见 `docs/architecture-rules.md`,债务完整条目见 `docs/debt/`。 +> 本文件是 Agent 的默认加载规范,只保留结构性红线、自检口径与文档路由;完整裁决标准与历史案例见 `docs/architecture-rules.md`,债务条目见 `docs/debt/`,各层与各包的实现约束见 `server/internal/*/README.md` 与 `server/pkg/*/README.md`。 > 裁决顺序:全局规范(`~/.dsh/AGENTS.md`)< 本文件 < `docs/architecture-rules.md` 细则,冲突时以更具体者为准。 +> 文档引用方向单向:本文件可引用其他文档,其他文档不得引用本文件,因此本文件的结构可自由调整。 ## 1. 结构红线 @@ -9,17 +10,17 @@ 1. **依赖只准向下**。后端 `handler → service → repository → domain`,禁止 service import handler、repository import service/handler、handler/middleware/router 直接 import repository;前端 `apps → @myblog/api → @myblog/http → @myblog/shared`,禁止 packages 反向 import apps,禁止页面/组件直接 import `ky`(唯一豁免:各应用 `src/lib/service/index.ts` 的令牌刷新直连)。 验证:在 `server/` 下执行 `git grep -ln "MyBlog/internal/repository" -- internal/service internal/middleware internal/router ':(exclude)*_test.go'`,基线 13 个文件(service 12 + middleware 仅 `identity.go` + router 0),只减不增。 -2. **类型唯一真相源**。后端 `internal/domain` 与 `internal/model` 的 json tag 即 API 契约;前端接口类型唯一来源为 `@myblog/api/modules/*/types`,apps 内禁止定义与后端请求/响应同构的 interface/type;通用响应信封 `{code, message, data}` 唯一来源为 `@myblog/shared` 的 `ApiResponse`。 - 验证:`git grep -n "BaseApiResponse" -- apps` 应为空。 +2. **类型唯一真相源**。后端 `internal/domain` 与 `internal/model` 的 json tag 即 API 契约;前端接口类型唯一来源为 `@myblog/api/modules/*/types`,apps 内禁止定义与后端请求/响应同构的 interface/type;通用响应信封唯一来源为 `@myblog/shared` 的 `ApiResponse`(底层为 `BaseApiResponse`)。 + 验证:`git grep -n "interface BaseApiResponse" -- apps` 应为空。 3. **契约先行,双端对齐**。改 wire 格式(请求/响应结构、错误码语义、认证协议)必须同一变更窗口内同步两端,禁止"先改后端、前端以后再说";改认证协议先更新 `contracts/auth-protocol.md`,改类型镜像跑 `pnpm run contract:check`。新增业务模块必须同时落地后端四层、`packages/api/src/modules//` 与两应用 `lib/api/index.ts` 注册。 4. **单一权威,禁止私自实例化**。业务规则(状态流转、slug 生成、密码强度、权限判定)权威在后端,前端只做展示层优化;RBAC 权限表权威为生产 `server/configs/config.yaml` 的 `rbac` 节,权限经登录响应 `permissions[]` 下发,`apps/admin/src/lib/constants/auth.ts` 的映射仅作未下发时的降级;依赖一律构造函数注入,生产实例化点仅组合根 `server/cmd/myblog/`(`main.go` 管生命周期、`deps.go` 按域装配),禁止在 service/router/middleware 内 `NewXxxService()`。 验证:`git grep -n "NewRBACService()" -- server` 的生产命中应仅 `cmd/myblog/deps.go` 一处。 5. **禁止复制粘贴式共享**。两 app 间禁止新增逐字或近似重复文件,公共逻辑下沉 packages;存量逐字重复仅 `src/lib/stores/auth.ts`(15 行 ×2)与 `src/lib/components/theme-toggle.svelte`(45 行 ×2),改任一份必须同步另一份。 验证:`git diff --no-index` 上述两份文件应零差异。 -6. **数据加载归位**。`apps/web` 新页面禁止 `onMount` 取数,用 `+page.server.ts` / `+page.ts` 的 load;`apps/admin` 新页面优先 load + 页面状态模块(`.svelte.ts`),禁止复制 300 行以上胖组件;API 调用不得深入叶子组件。 +6. **数据加载归位**。`apps/web` 新页面禁止 `onMount` 取数,用 `+page.server.ts` / `+page.ts` 的 load;`apps/admin` 新页面优先 load + 页面状态模块(`.svelte.ts`);API 调用不得深入叶子组件。 7. **部署形态为单实例**(有意取舍,非待修缺陷)。应用进程、MySQL、网关各一份,无副本与故障转移;会话令牌表与限流计数均为进程内存结构,服务重启或发布将导致全体用户登出,发布窗口需提前预告;故障即停站,无 RTO 承诺,RPO 为 24 小时。扩容前必须完成令牌表持久化、限流器外置、补 `SetTrustedProxies` 三项改造。 验证:`git grep -n "SetTrustedProxies" -- server` 与 `git grep -n "replicas" -- docker-compose.yml` 均应为空。 -8. **先确认产品定位**。单作者个人博客,不开放注册、无找回密码通道:账号由管理员创建(首次部署 `pnpm run seed:admin`,之后在后台用户管理页新增),忘记密码由超级管理员经 `POST /api/users/update` 重置;游客可浏览并提交评论(受审核设置约束),点赞/收藏/关注需登录。以上为有意取舍,功能提案前先确认是否与之冲突;新增数据收集场景须先同步 `apps/web` 的 `/privacy` 页告知。 +8. **先确认产品定位**。单作者个人博客,不开放注册、无找回密码通道:账号由管理员创建(首次部署 `pnpm run seed:admin`,之后在后台用户管理页新增),忘记密码由超级管理员经 `POST /api/users/update` 重置;游客可浏览并提交评论(受审核设置约束),点赞/收藏/关注需登录。功能提案前先确认是否与之冲突;新增数据收集场景须先同步 `apps/web` 的 `/privacy` 页告知。 ## 2. 完成前自检 @@ -29,21 +30,15 @@ pnpm run check # 两应用 Svelt pnpm run lint && pnpm run format # 静态检查与格式零告警 ``` -触碰以下区域时追加: - -- 认证/权限:确认未新增权限定义副本、未新增认证工具文件。 -- `domain`/`model` 输出字段:评估 `@myblog/api` 类型与页面消费点,跑 `pnpm run contract:check`。 -- 两 app 重复文件:确认另一份已同步。 -- 新增模块:确认双端对齐。 -- 依赖(`server/go.mod`、`go.sum`、根 lockfile、`pnpm-workspace.yaml` 的 `overrides`):`pnpm run go:vulncheck` 与 `pnpm run audit:deps` 须零阻塞项。 +触碰以下区域时追加动作:认证/权限与两 app 重复文件按第 1 节对应条目自检;改 `domain`/`model` 输出字段须评估 `@myblog/api` 类型与页面消费点并跑 `pnpm run contract:check`;新增模块须确认双端对齐;改依赖(`server/go.mod`、`go.sum`、根 lockfile、`pnpm-workspace.yaml` 的 `overrides`)须 `pnpm run go:vulncheck` 与 `pnpm run audit:deps` 零阻塞项。 ## 3. 仓库概览 ``` MyBlog/ ├── apps/ -│ ├── web/ # 前台(Svelte 5 + TS + TailwindCSS v4,SSR 博客 + demo + i18n) -│ └── admin/ # 后台(SvelteKit SPA,管理控制台 + 登录页,基准路径 /admin) +│ ├── web/ # 前台 toC:SSR 博客 + demo + i18n +│ └── admin/ # 后台 toB:SPA 管理控制台 + 登录页,基准路径 /admin ├── packages/ │ ├── shared/ # 公共纯工具与通用类型(ApiResponse、响应码常量) │ ├── http/ # HTTP 请求器(ky 封装,认证回调注入) @@ -63,67 +58,62 @@ MyBlog/ ## 4. 常用命令 ```bash -pnpm run setup # 一键环境设置 pnpm run dev # 智能启动(环境与端口检查、健康监控) pnpm run dev:server / dev:web / dev:admin # 分别启动后端 / 前台 / 后台 pnpm run build # 生产构建,可加 --clean --production --skip-tests --skip-lint --server-only --web-only -pnpm run build:clean / build:production / build:server / build:web / build:fast -pnpm run test # test:server + test:packages + test:apps + contract:check -pnpm run test:server / test:packages / test:apps # 分开执行三类测试 -pnpm run check # 两应用 svelte-check 类型检查 +pnpm run test / check # 三类测试串联 / 两应用 svelte-check 类型检查 pnpm run lint / format / quality # 静态检查 / 格式化 / 全量质量门禁 pnpm run contract:check # 契约三把锁(Go fixture + tsc + vitest 锚定) -pnpm run seed:admin # 初始化或提升超级管理员,幂等 -pnpm run migrate [create|up|down|goto|force|version] -pnpm run go:lint-install / go:quality / go:vulncheck / audit:deps +pnpm run seed:admin / migrate [create|up|down|goto|force|version] +pnpm run go:quality / go:vulncheck / audit:deps ``` -> 各脚本的用途、参数与 pnpm 入口对照见 `scripts/README.md`。 +> 环境设置 `pnpm run setup`,各脚本的用途、参数与 pnpm 入口对照见 `scripts/README.md`。 ## 5. 后端约定(server/) -- **POST-Only**:业务接口一律 `POST`(查询类同样 `POST`),参数承载于 JSON 请求体,纯 id 类短参数可放 path;健康探针属基础设施端点,按编排器标准用 `GET`(`internal/router/health.go`)。 -- **校验**:handler 用 `ShouldBindJSON` + `binding` tag 完成必填、长度、格式、枚举校验,业务规则在 service 校验,校验通过才进入数据访问层;跨接口复用的校验必须提取公共方法,禁止复制(`service/user.go` 的密码强度校验为存量私有实现,触碰时迁移)。 -- **分层**:`handler`(HTTP 与 DTO 映射)→ `service`(业务)→ `repository`(持久化);路由注册见 `internal/router/router.go` 与各模块 `internal/router/.go`。 -- **错误分档**:handler 的 `binding` 校验失败直接经 `response.BadRequest` 返回 400;service 返回的错误交 `internal/handler/error.go` 的 `HandleServiceError` 统一映射(`ErrUnauthenticated` → 401、`ErrPermissionDenied` → 403、12 个 not-found 哨兵 → 404、`ErrInvalidRequest`/`ErrUsernameTaken`/`ErrEmailTaken` → 400、其余脱敏为 500「服务器内部错误」并只把原文写日志),禁止模块内新增私有映射;新增哨兵须同步扩展映射集合与 `contracts/errors.yaml`。 -- **统一响应**:统一经 `pkg/response`,结构为 `{code, message, data?}`;响应码 `CodeSuccess=200`、`CodeError=500`、`CodeInvalid=400`、`CodeAuth=401`、`CodeForbid=403`、`CodeNotFound=404`。 -- **类型归属**:领域实体统一在 `internal/domain`(`domain.User` 等),`internal/model` 保留各业务 GORM 实体,`repository` 只承载持久化实现,禁止在 repository 新增实体或 DTO。请求/响应 DTO 以所在业务域的 service 包内定义为常态(如 `service.CreateArticleRequest`),用户域的 `CreateUserRequest`/`UpdateUserRequest` 在 `internal/domain/dto.go`,少数 handler 就地声明(`SessionRequest`、`LogoutRequest`、`deleteDictRequest`);对外响应优先经 `domain` 的响应形状或窄化视图,禁止直出 GORM 实体(存量违例见 `docs/debt/security-runtime.md` 第 1 条)。 -- **命名与接口位置**:Go 字段与 json tag 用小驼峰;接口与实现同包声明,统一 `XxxInterface` 后缀(存量 `UserService`、`RBACService`、`UserRepository` 未带后缀,触碰时统一);各层依赖接口而非实现,`router` 不得重复定义接口。 -- **数据库**:MySQL 单库 + GORM;开发模式 `AutoMigrate`、生产 golang-migrate,由 `internal/database/migrate.go` 与 `pnpm run migrate` 管理。表设计须含生命周期字段、状态字段与字段级 `comment`,唯一字段加唯一索引、外键与高频查询加普通索引,显式声明 GORM 关联与删除策略(`OnDelete:CASCADE` / `OnDelete:SET NULL`),时间字段统一 `datetime(3)`;多段写库必须事务化(`CreateArticle`、`UpdateArticle`、`ViewArticle` 为先例,事务内统一走事务句柄)。 -- **认证与密码**:bcrypt 成本 `BcryptCost = 12`(`service/user.go`);令牌为服务端签发的不透明随机串,内存令牌表是身份唯一权威(单实例前提),刷新即旋转、登出撤销令牌对、改密撤销该用户全部令牌。 -- **配置与中间件**:`internal/config` 经 Viper 读 `configs/config.yaml`(YAML 为唯一来源,含 `server`、`database`、`logger`、`api`、`token`、`security`、`cors`、`media`、`rbac`、`i18n`、`metrics` 节);中间件含 logger(结构化 JSON 访问日志与 RequestID)、recovery(panic 结构化记录)、cors、security、auth、rbac、ratelimit、language 与 identity,认证/权限中间件只依赖 `IdentityProvider` 抽象。 -- **入口与工具包**:服务入口 `cmd/myblog/`,种子入口 `cmd/seed/`(逻辑 `internal/database/seed.go`);通用包 `pkg/response`、`pkg/datetime`、`pkg/slug`、`pkg/markdown`、`pkg/storage`。 +- **POST-Only**:业务接口一律 `POST`,参数承载于 JSON 请求体,纯 id 类短参数可放 path;健康探针属基础设施端点,按编排器标准用 `GET`(`internal/router/health.go`)。 +- **校验**:handler 用 `ShouldBindJSON` + `binding` tag 完成必填、长度、格式、枚举校验,业务规则在 service 校验且校验通过才进入数据访问层;跨接口复用的校验必须提取公共方法,禁止复制(密码强度校验 `service/password.go` 已按此三处复用)。 +- **分层**:`handler`(HTTP 与 DTO 映射)→ `service`(业务)→ `repository`(持久化),路由注册在 `internal/router/`;各层职责与边界见 `docs/development.md`「分层设计」与 `internal/{handler,service,repository,middleware}/README.md`。 +- **错误分档**:service 错误唯一经 `internal/handler/error.go` 的 `HandleServiceError` 分档为 401/403/404/400,未分类错误脱敏为 500「服务器内部错误」且只把原文写日志;`binding` 校验失败由 handler 直接 `response.BadRequest` 返回 400;禁止模块内新增私有映射,新增哨兵须同步扩展映射集合与 `contracts/errors.yaml`。完整口径见 `internal/handler/README.md`。 +- **统一响应**:统一经 `pkg/response`,业务结果一律 HTTP 200 并以 `code` 区分;信封结构、响应码常量与 404/503 例外见 `server/pkg/response/README.md`。 +- **类型归属**:领域实体在 `internal/domain`,GORM 实体在 `internal/model`,`repository` 不得新增实体或 DTO,对外响应禁止直出 GORM 实体(存量违例见 `docs/debt/security-runtime.md` 第 1 条);请求/响应 DTO 以所属业务域的 service 包内定义为常态(如 `service.CreateArticleRequest`),用户域的 `CreateUserRequest`/`UpdateUserRequest` 在 `internal/domain/dto.go`,短参数 DTO 可就地声明在 handler。 +- **命名与接口位置**:Go 字段与 json tag 用小驼峰;接口与实现同包声明并统一 `XxxInterface` 后缀(存量 `UserService`、`RBACService`、`UserRepository` 未带后缀,触碰时统一);各层依赖接口而非实现,`router` 不得重复定义接口。 +- **数据库**:表结构硬性约定(生命周期与状态字段、字段级 `comment`、唯一索引与普通索引、删除策略、时间精度、多段写库事务化)与迁移双轨(开发 `AutoMigrate`、生产 golang-migrate)见 `docs/database-architecture.md`,迁移入口为 `internal/database/migrate.go` 与 `pnpm run migrate`。 +- **认证与密码**:bcrypt 成本 `BcryptCost = 12`;令牌为服务端签发的不透明随机串,内存令牌表是身份唯一权威(单实例前提),刷新即旋转、登出撤销令牌对、改密撤销该用户全部令牌。线格式与撤销语义见 `contracts/auth-protocol.md`,实现要点见 `internal/service/README.md`。 +- **配置与中间件**:`internal/config` 经 Viper 读 `configs/config.yaml`(YAML 为唯一来源);中间件覆盖访问日志与 panic 恢复及 RequestID、CORS、安全、认证、RBAC、限流、语言协商与身份解析,认证/权限中间件只依赖 `IdentityProvider` 抽象。配置项与中间件清单以 `internal/config/README.md`、`internal/middleware/README.md` 为准。 +- **入口与工具包**:服务入口 `cmd/myblog/`,种子入口 `cmd/seed/`(逻辑 `internal/database/seed.go`),通用包见 `server/pkg/`。 ## 6. 前端约定(apps/ + packages/) -- **框架**:SvelteKit + Svelte 5 runes + TypeScript,不使用 Options API。`apps/web` 为前台 toC、SSR 路线(adapter-node);`apps/admin` 为后台 toB、SPA 路线(`ssr=false`、adapter-static,`paths.base='/admin'`),无 i18n。 -- **组件库**:shadcn-svelte 基础组件统一在 `packages/ui`(保持 stock,主题经各应用设计令牌注入),经 `$ui` 与 `$ui/*` 引入;禁止在应用内重写 `$ui` 已有组件。 -- **别名**:各应用 `svelte.config.js` 声明 `$ui`、`$ui/*`、`@/*`(应用自身 `src`),前台另有 `$i18n`(指向 `src/lib/paraglide/messages`);`$lib` 由 SvelteKit 隐式提供;前台另有构建期 `#fonts` 别名,dev 走本地 fontsource、prod 走 CDN 模块,见 `apps/web/vite.config.ts`。 -- **样式**:TailwindCSS v4(`@tailwindcss/vite`);`app.css` 只做聚合入口(含 `@source '../../../packages/ui/src'`),设计令牌定义在同应用 `src/styles/tokens.css`——前台为编辑杂志主题(暖纸墨色系,含 `--signal` 与 `--color-line` 别名),后台为原始主题(无 `--signal`),`packages/ui` 不携带全局样式。视觉与动效准则见 `docs/ui-design-system.md`。 -- **API 层**:`packages/http` 提供 `createHttpClient` 工厂,`packages/api` 提供 12 个模块工厂;认证会话由 `@myblog/auth` 的 `createAuthStore` 组装;应用侧 `src/lib/service` 注入认证与提示回调、`src/lib/api` 实例化接口,一律 `POST` 调用后端。新增接口必须先加在 `packages/api`,禁止页面直连 ky。 +- **框架**:SvelteKit + Svelte 5 runes + TypeScript,不使用 Options API;`apps/web` 为前台 toC、SSR 路线(adapter-node),`apps/admin` 为后台 toB、SPA 路线(`ssr=false`、adapter-static,`paths.base='/admin'`)且无 i18n。 +- **组件库**:shadcn-svelte 基础组件统一在 `packages/ui` 并保持 stock,经 `$ui` 与 `$ui/*` 引入;组件归属、禁止在应用内重写与主题注入细则见 `docs/ui-design-system.md`。 +- **别名**:各应用 `svelte.config.js` 声明 `$ui`、`$ui/*`、`@/*`(应用自身 `src`),前台另有 `$i18n` 与构建期 `#fonts` 别名,`$lib` 由 SvelteKit 隐式提供;对照见 `docs/development.md`「关键技术配置」。 +- **样式**:TailwindCSS v4(`@tailwindcss/vite`);`app.css` 只做聚合入口(含 `@source '../../../packages/ui/src'`),设计令牌在同应用 `src/styles/tokens.css`,`packages/ui` 不携带全局样式;前台为编辑杂志主题(含 `--signal` 与 `--color-line` 别名),后台为原始主题(无 `--signal`)。 +- **API 层**:`packages/http` 提供 `createHttpClient` 工厂,`packages/api` 提供 12 个模块工厂,认证会话由 `@myblog/auth` 的 `createAuthStore` 组装;应用侧 `src/lib/service` 注入认证与提示回调、`src/lib/api` 实例化接口,一律 `POST` 调用后端。新增接口必须先加在 `packages/api`,禁止页面直连 ky。 - **状态**:认证 store 逻辑已下沉 `@myblog/auth`(两应用各持薄封装),新公共状态逻辑必须下沉 packages,禁止第三处复制。 -- **i18n(仅前台)**:`@inlang/paraglide-js` + `project.inlang` / `messages/*.json5`(必须保持 JSON 兼容写法,否则编译失败)。已接入 Header、Footer、NotificationBell、FriendlyLinkDialog、错误页与 demo 页,已接入文件禁止回退硬编码;新增用户可见文案优先经 `m['ui:...']()` 取词,其余页面待页面大变动后分批接入。 -- **类型**:接口类型唯一来源 `@myblog/api`;影子类型层已清除,两应用 eslint 以 patterns 拦截 `$lib/types` 引入形态,禁止重新引入。 +- **i18n(仅前台)**:`@inlang/paraglide-js` + `project.inlang` / `messages/*.json5`(必须保持 JSON 兼容写法,否则编译失败);已接入文件禁止回退硬编码,新增用户可见文案优先经 `m['ui:...']()` 取词,已接入面与其余页面分批口径见 `docs/debt/frontend.md` 第 7 条。 +- **类型**:接口类型唯一来源 `@myblog/api`;影子类型层已清除,两应用 eslint 以 patterns 拦截 `$lib/types` 引入形态,禁止重新引入。镜像关系与三把锁见 `docs/architecture-rules.md` 第 3 节。 ## 7. 代码风格、注释与测试 - prettier 配置(根 `prettier.config.js`):`semi: false`、`singleQuote: true`、`arrowParens: 'avoid'`、`printWidth: 100`、`tabWidth: 2`、`trailingComma: 'none'`。 - **导入排序**:prettier 挂载 `prettier-plugin-sort-imports`,排序依据是单条 import 语句的字符长度,语句越长越靠前,既不看模块名字母序也不区分外部依赖与相对路径。这是既定规范,导入块看似错乱时不要手工调整,手工修改会被下次格式化还原。 -- **格式化覆盖范围**:lint-staged 仅对 `apps/**/src/**` 运行 prettier,对 `server/**/*.go` 运行 gofmt 与 goimports;`packages/**` 不在任何 format 门禁覆盖内,新增或改动 packages 文件须手动执行 `npx prettier --write `。 -- **注释**:只解释代码无法直接表达的意图、业务规则、约束、原因、风险与副作用,不复述代码;具体要求遵循全局规范。 -- **测试文件位置**:前端测试文件不与业务文件同级,一律置于被测模块同级的 `__tests__/` 目录;跨用例共享的测试替身与夹具置于包内 `src/test/`,不放入 `__tests__/`。vitest 的 `include` 与各 tsconfig 的 `src/**/*.ts` 已覆盖这两类目录。 -- **测试现状**:后端 `service`、`repository`、`handler`、`middleware`、`router`、`config`、`database`、`pkg/*` 均有 `*_test.go`,新增后端关键逻辑必须配套同目录测试。`packages/api`、`packages/auth`、`packages/http` 均已有 `typecheck` 与 vitest 单测,并经 `pnpm run test:packages` 串联纳入门禁;两应用单测经 `pnpm run test:apps`(admin 覆盖 `dict-page-state.svelte.ts`,web 覆盖 `render.ts` 的原始 HTML 丢弃守卫与目录日期格式化)。新增 packages 公共逻辑与页面状态模块(`.svelte.ts`)须配套 `*.test.ts`,并为所在 package 补 `typecheck`、`test` 脚本且登记进根 `test:packages`。`pnpm run check` 与 `typecheck:web` 只做类型检查,不是单元测试。 +- **格式化覆盖范围**:lint-staged 只对 `apps/**/src/**` 的脚本与组件文件、任意目录下的 `*.{json,yaml,yml}` 运行 prettier,对 `server/**/*.go` 运行 gofmt 与 goimports;`packages/**` 的源码不在任何 format 门禁覆盖内,新增或改动 packages 文件须手动执行 `npx prettier --write `。 +- **注释**:只解释代码无法直接表达的意图、业务规则、约束、原因、风险与副作用,不复述代码;完整写作要求遵循全局规范 `~/.dsh/AGENTS.md` 第 4 节。 +- **测试文件位置**:前端测试文件不与业务文件同级,一律置于被测模块同级的 `__tests__/` 目录;跨用例共享的测试替身与夹具置于包内 `src/test/`,不放入 `__tests__/`。 +- **测试纪律**:后端各层与 `pkg/*` 均有 `*_test.go`,新增后端关键逻辑必须配套同目录测试;`packages/api`、`packages/auth`、`packages/http` 与两应用单测分别经 `pnpm run test:packages`、`pnpm run test:apps` 纳入门禁,新增 packages 公共逻辑与页面状态模块(`.svelte.ts`)须配套 `*.test.ts`,并为所在 package 补 `typecheck`、`test` 脚本且登记进根 `test:packages`。`pnpm run check` 与 `typecheck:web` 只做类型检查,不是单元测试。 - **提交**:提交信息用简体中文、符合 commitlint 的 conventional commits(type 枚举见 `commitlint.config.js`);单次提交跨度过大时补充正文说明。 ## 8. 文档地图 -- `docs/architecture-rules.md`:铁律细则、债务索引与验证命令、历史教训(与本文冲突时以该文件为准)。 -- `docs/debt/`:债务完整条目分册(结构类型 / 前端复用 / 安全运行时 / 测试),基线只减不增。 -- `docs/development.md`:环境设置、开发工作流、工具陷阱、代码风格示例。 -- `docs/database-architecture.md` 与 `docs/database/schema.sql`:数据库设计说明与参考 DDL(仅供设计参考,实际结构以 GORM 模型为准,生产经 `server/migrations/` 增量迁移)。 +- `docs/architecture-rules.md`:第 1 节红线的完整裁决细则、债务索引与验证命令、历史教训与重构分期(与本文冲突时以该文件为准)。 +- `docs/debt/`:债务条目分册(结构类型 / 前端复用 / 安全运行时 / 测试),基线只减不增。 +- `docs/development.md`:环境设置、开发工作流、分层与模块设计、工具陷阱、代码风格示例。 +- `docs/database-architecture.md` 与 `docs/database/schema.sql`:数据库设计说明与参考 DDL(实际结构以 GORM 模型为准,生产经 `server/migrations/` 增量迁移)。 - `docs/ui-design-system.md`:视觉、动效与可访问性准则。 -- `docs/operations/backup-restore.md`:备份与恢复流程、RPO 口径。 -- `docs/operations/observability.md`:指标抓取与告警规则、结构化日志字段与处置流程。 +- `docs/operations/`:备份恢复与 RPO 口径、指标抓取与告警规则、结构化日志字段与处置流程。 - `contracts/`:认证协议、i18n 协议、错误码口径与契约金样本。 +- `server/internal/*/README.md` 与 `server/pkg/*/README.md`:各层与各包的实现约束、字段口径与已知陷阱,改对应目录前先读。 - `server/docs/api/`:接口总数口径与逐模块接口说明。 - `scripts/README.md`:脚本用途、参数与 pnpm 入口对照。 diff --git a/deploy/observability/alerts.yml b/deploy/observability/alerts.yml index d0e4081..8f54491 100644 --- a/deploy/observability/alerts.yml +++ b/deploy/observability/alerts.yml @@ -4,7 +4,7 @@ # docs/operations/observability.md。数值为经验初值,无压测数据支撑, # 需在真实负载下观测后调整。 # -# 部署形态为单实例(AGENTS.md 结构红线第 7 条):故障即停站,无故障转移, +# 部署形态为单实例:故障即停站,无故障转移, # 因此可用性与重启类告警的处置动作是人工介入而非自动切换。 groups: diff --git a/docs/architecture-rules.md b/docs/architecture-rules.md index 08f7caa..d9cc98a 100644 --- a/docs/architecture-rules.md +++ b/docs/architecture-rules.md @@ -1,10 +1,10 @@ # MyBlog 架构铁律与纪律手册 -> 本手册是 `AGENTS.md` 第 1 节「结构红线」的完整裁决细则,效力高于普通文档。 +> 本手册是项目结构红线(依赖方向、类型真相源、契约先行、单一权威、复用纪律、数据加载)的完整裁决细则,效力高于普通文档。 > 本项目的抽象设计基本正确(分层骨架、packages 单向依赖、工厂注入),但历史上被长期系统性绕行, > 形成了若干结构性顽疾。本手册的使命是让"绕行"在代码评审与自检命令层面被拦截。 > -> **裁决顺序**:`~/.dsh/AGENTS.md`(全局)< `AGENTS.md`(项目)< 本手册(细则)。冲突时以更具体者为准。 +> **效力**:本手册效力高于普通文档;与更具体的细则冲突时以更具体者为准。 > > **分册**:第 1 至 7 节为规则本体,第 8 节为债务索引,第 9 至 10 节为历史登记;债务的完整条目(状态、基线数值、验证命令、完整红线)按关注域分册在 [`debt/`](./debt/README.md)。 @@ -300,7 +300,7 @@ git grep -n "replicas" -- docker-compose.yml | 阶段 | 内容 | 完成的债务 | 验收口径 | |---|---|---|---| -| 阶段一 结构归位与错误分档 | 删 router 重复接口与不可达代码;错误分档(哨兵错误→404/403/400);令牌表加锁;web 死 load 清理;建立 `contracts/` 目录 | router 重复接口、web 死 load、401 判定均已修复;令牌表已加锁;`RBACService` 生产实例化点仅 1 处;not-found 哨兵→404 已落地,403/400 随错误码契约落地;全部业务错误归哨兵完成,认证失败经 `ErrUnauthenticated`→401,handler 私有映射分支清零 | ✅ `AGENTS.md` 第 2 节自检命令全绿 | +| 阶段一 结构归位与错误分档 | 删 router 重复接口与不可达代码;错误分档(哨兵错误→404/403/400);令牌表加锁;web 死 load 清理;建立 `contracts/` 目录 | router 重复接口、web 死 load、401 判定均已修复;令牌表已加锁;`RBACService` 生产实例化点仅 1 处;not-found 哨兵→404 已落地,403/400 随错误码契约落地;全部业务错误归哨兵完成,认证失败经 `ErrUnauthenticated`→401,handler 私有映射分支清零 | ✅ 项目自检命令(后端 build/vet/test、两应用类型检查、lint 与 format)全绿 | | 阶段二 类型归位 | 建立 `internal/domain`,合并双 User,service/middleware/router 签名切换为 domain 类型;前端 auth 下沉共享包、影子类型清除 | 双 User 模型与影子类型层已修复;两 app 重复代码大幅减少(auth store 下沉);service 层 repository 依赖由 12 降至 11 | ✅ 依赖方向基线下降;auth store diff 为零 | | 阶段三 契约切换 | handler DTO 分离;`contracts/` + 三把锁双向锚定(替代 codegen);401 改错误码判定 | 401 文案匹配与审计字段泄漏已修复;三把锁已落地(`pnpm run contract:check`) | ✅ 影子类型归零;漂移必当天变红 | | 阶段四 横切归位与权限下发 | 中间件坍缩为 IdentityProvider 策略;组合根按域装配;RBAC 权限表迁数据源并下发;admin 胖组件拆分、users 搜索推回后端 | `RBACService` 生产实例化点仅 1 处;users 跨页补偿与 admin 分页均已修复;RBAC 迁 config.yaml 完成;permissions 下发完成;follow API 模块已补齐;IdentityProvider 中间件坍缩完成(router 依赖 repository 归零、middleware 1 处);认证工具已统一;admin 胖组件行数口径 7→0,7 个页面取数归位到 load + 页面状态模块 | 权限定义全栈唯一;认证工具单轨 ✅ | diff --git a/docs/database-architecture.md b/docs/database-architecture.md index b62106e..9fd7ec7 100644 --- a/docs/database-architecture.md +++ b/docs/database-architecture.md @@ -18,7 +18,7 @@ ## 设计原则 -表结构的生命周期与 comment 约定、唯一索引与普通索引、OnDelete 策略、时间字段精度、多段写库事务化已被根 `AGENTS.md` 第 5 节「后端约定」的数据库条文覆盖,本文档不再复述。本节仅保留该处未覆盖的三条本架构约定: +表结构统一遵循以下硬性约定:表须含生命周期字段、状态字段与字段级 `comment`;唯一字段加唯一索引,外键与高频查询加普通索引;GORM 关联与删除策略必须显式声明(`OnDelete:CASCADE` / `OnDelete:SET NULL`);时间字段统一 `datetime(3)`;多段写库必须在同一事务内完成。本节另列三条本架构约定: 1. **规范化设计**:遵循第三范式,多对多关系使用独立关联表,避免冗余存储。 2. **树形结构**:分类与评论统一使用 parent_id、root_id、level 三件套,分类额外使用 path 物化路径支持整棵子树的一次查询。 @@ -181,7 +181,7 @@ ## 数据一致性约定 -状态类字段的命名常量枚举与软删除列以 `internal/model` 的常量定义与实体 tag 为准,时间字段精度与多段写库事务口径以根 `AGENTS.md` 第 5 节「后端约定」为准,本文档不再复述。本架构的实现结果:冗余计数字段为 view_count、like_count、bookmark_count、comment_count、reply_count、article_count、usage_count,在业务写入时同步维护。 +状态类字段的命名常量枚举与软删除列以 `internal/model` 的常量定义与实体 tag 为准,时间字段精度与多段写库事务口径见「设计原则」的表结构硬性约定。本架构的实现结果:冗余计数字段为 view_count、like_count、bookmark_count、comment_count、reply_count、article_count、usage_count,在业务写入时同步维护。 ## 演进与运维约定 @@ -201,4 +201,4 @@ **文档版本**:v3.1 **最后更新**:表清单与模型层对齐 -**更新内容**:表数量由 23 张校正为 30 张,补入内容翻译表 3 张与字典模块 4 张;补齐全文索引、字典与翻译表的索引清单;按模型层修正删除策略(媒体上传者外键无 OnDelete 声明);设计原则与数据一致性约定中与根 `AGENTS.md` 重复的条文压缩为指针,仅保留规范化、树形结构与状态/删除形态约定。 +**更新内容**:表数量由 23 张校正为 30 张,补入内容翻译表 3 张与字典模块 4 张;补齐全文索引、字典与翻译表的索引清单;按模型层修正删除策略(媒体上传者外键无 OnDelete 声明);设计原则与数据一致性约定中的通用条文收敛为「设计原则」首段的表结构硬性约定,各节仅保留规范化、树形结构与状态/删除形态约定。 diff --git a/docs/development.md b/docs/development.md index 97a07dc..f17d457 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,6 +1,6 @@ # 开发指南 -本文档提供 MyBlog Monorepo 的环境设置、开发工作流、工具陷阱与代码风格示例;架构层面的结构性规则与裁决细则见根 `AGENTS.md` 与 [`architecture-rules.md`](./architecture-rules.md)。 +本文档提供 MyBlog Monorepo 的环境设置、开发工作流、工具陷阱与代码风格示例;架构层面的结构性规则与裁决细则见 [`architecture-rules.md`](./architecture-rules.md)。 ## 目录 @@ -16,7 +16,7 @@ ### Monorepo 结构 -MyBlog 采用 Monorepo 架构,将前后端代码统一管理在一个仓库中。仓库目录树与各包职责见根 `AGENTS.md` 第 3 节「仓库概览」,本节不复述。 +MyBlog 采用 Monorepo 架构,将前后端代码统一管理在一个仓库中:`apps/` 放两个可部署前端应用,`packages/` 放被应用消费的共享前端包,`server/` 放 Go 后端,`contracts/` 承载跨端契约,`scripts/` 承载构建与开发脚本。各分区内部职责见本文件「后端架构」「前端架构」两节。 ### 后端架构 (server/) @@ -80,7 +80,7 @@ MyBlog 采用 Monorepo 架构,将前后端代码统一管理在一个仓库中 #### 依赖注入 -依赖一律由组合根 `cmd/myblog/`(`main.go` 管生命周期、`deps.go` 按域装配)构造,再经 `router.Dependencies` 逐层注入,禁止在 service / router / middleware 内私自 `New`;规则原文与验证命令见根 `AGENTS.md` 第 1 节第 4 条与 [`architecture-rules.md`](./architecture-rules.md) §5.2。 +依赖一律由组合根 `cmd/myblog/`(`main.go` 管生命周期、`deps.go` 按域装配)构造,再经 `router.Dependencies` 逐层注入,禁止在 service / router / middleware 内私自 `New`;规则原文与验证命令见 [`architecture-rules.md`](./architecture-rules.md) §5.2。 ### 前端架构(apps/ + packages/) @@ -349,7 +349,7 @@ git diff --cached --name-only # 核对清单后再执行 git commit ## 代码规范 -> 本节仅覆盖风格约定。**架构层面的硬性规则(依赖方向、类型唯一真相源、契约先行、单一权威、禁止复制、数据加载)见 [`architecture-rules.md`](./architecture-rules.md) 与根目录 `AGENTS.md` 第 1 节,违反必须返工。** +> 本节仅覆盖风格约定。**架构层面的硬性规则(依赖方向、类型唯一真相源、契约先行、单一权威、禁止复制、数据加载)见 [`architecture-rules.md`](./architecture-rules.md),违反必须返工。** ### Go 代码规范 @@ -447,7 +447,7 @@ type User struct { UpdatedAt time.Time `json:"updatedAt"` } -// 请求 DTO(internal/domain/dto.go):承载校验,禁止 gorm tag +// 请求 DTO(用户域在 internal/domain/dto.go,其余按业务域就近定义):承载校验,禁止 gorm tag type CreateUserRequest struct { Username string `json:"username" binding:"required,min=1,max=50"` Email string `json:"email" binding:"required,email"` @@ -576,13 +576,13 @@ pnpm run build:web # 构建前端静态文件 ### 1. 代码组织 -- **架构铁律**: 依赖方向、类型唯一真相源等结构性约束见 [`architecture-rules.md`](./architecture-rules.md) 与根 `AGENTS.md` 第 1 节 +- **架构铁律**: 依赖方向、类型唯一真相源等结构性约束见 [`architecture-rules.md`](./architecture-rules.md) - **事务化模式**: 多段写库必须包裹单事务;repository 提取 `xxxTx(db *gorm.DB, ...)` 私有方法供事务与独立公开方法复用(`createTx`/`syncTagsTx`/`syncCategoriesTx`/`updateTx`/`recordArticleView` 先例,事务内所有查询与写入均走事务句柄,禁止混用 `r.db`),跨仓储共享的写逻辑下沉为包内共享 helper(`upsertContentStat` 先例),不引入仓储间依赖 - **安全配置默认值双源对齐**: `security.login_lockout` 的 viper 默认值与 service 层 `defaultLoginLockoutPolicy` 必须一致(5 次 / 15 分钟),修改任一处必须同步另一处 ### 2. 错误处理 -- **错误分档与统一响应**: 哨兵错误到响应码的映射口径与响应信封结构见根 `AGENTS.md` 第 5 节,唯一映射点为 `internal/handler/error.go`,本节不复述。 +- **错误分档与统一响应**: 哨兵错误到响应码的映射口径见 `server/internal/handler/README.md`,响应信封与响应码常量见 `server/pkg/response/README.md`,唯一映射点为 `internal/handler/error.go`,本节不复述。 ### 3. 性能优化 @@ -592,7 +592,7 @@ pnpm run build:web # 构建前端静态文件 ### 4. 安全考虑 -- **输入验证与注入防护**: 入参经 `binding` tag 完成必填、长度、格式与枚举校验(口径见根 `AGENTS.md` 第 5 节「校验」);数据访问一律经 GORM 参数化查询,禁止字符串拼接 SQL +- **输入验证与注入防护**: 入参经 `binding` tag 完成必填、长度、格式与枚举校验(口径见 `server/internal/handler/README.md`);数据访问一律经 GORM 参数化查询,禁止字符串拼接 SQL - **跨域配置**: 跨域来源一律改 `server/configs/config.yaml` 的 `cors` 节白名单(精确匹配),禁止代码内硬编码 Origin 或恢复全放行;生产同源网关形态白名单保持为空 - **WAF 阻止模式**: 新增或修改 `getDefaultBlockedPatterns()` 模式必须先红后绿配"攻击拦截 + 误伤回归"两组用例,模式经词首边界或取值上下文锚定,禁止回退宽匹配 - **WAF 正文豁免**: JSON 请求体按字段路径扫描,正文(`content` 与 `i18n.*.content`)不参与模式扫描,标题/摘要/SEO/URL 参数/请求头/表单参数保持全量扫描;豁免以渲染层消毒为前提,扩大豁免清单前必须确认该字段的每处输出都经消毒渲染或转义输出,放宽渲染层消毒时必须同步收回豁免 diff --git a/docs/ui-design-system.md b/docs/ui-design-system.md index 1b08a85..a32d27f 100644 --- a/docs/ui-design-system.md +++ b/docs/ui-design-system.md @@ -23,7 +23,7 @@ ### 1.2 `packages/ui` 边界(stock 原则) -- 组件归属、stock 原则与「禁止在应用内重写」见根 `AGENTS.md` 第 6 节,本节不重复;组件源码**禁止硬编码业务色与业务样式**,外观一律通过各应用 `src/styles/tokens.css` 的语义 token 与调用处 `className` prop 定制,前后台的外观差异全部落在该文件,**不得**通过修改 `packages/ui` 组件源码实现。 +- 基础组件统一归属 `packages/ui` 并保持 stock,应用内**禁止重写 `$ui` 已有组件**;组件源码**禁止硬编码业务色与业务样式**,外观一律通过各应用 `src/styles/tokens.css` 的语义 token 与调用处 `className` prop 定制,前后台的外观差异全部落在该文件,**不得**通过修改 `packages/ui` 组件源码实现。 - 组件库内仅使用标准 shadcn token(`--background` / `--foreground` / `--card` / `--primary` / `--muted` / `--border` / `--ring` / `--destructive` / `--radius` 等)。 - 组件库**只提供逐组件子路径入口**,不提供包级聚合入口:`@myblog/ui` 的 `exports` 仅保留 `./*`,原 `packages/ui/src/index.ts` 聚合文件已删除,两个应用的 eslint 对 `$ui` 与 `@myblog/ui` 裸导入设为 error。 - 聚合入口的代价是可量化的:包内 `packages/ui/src` 共 394 个文件,其中 334 个是 `.svelte`,类型检查需要逐个转换 `.svelte`;按两个应用实际引用的 24 个组件入口做静态可达分析,可达文件为 166 个(其中 `.svelte` 142 个)。 diff --git a/server/docs/api/api-specification.md b/server/docs/api/api-specification.md index 954fef7..676b35a 100644 --- a/server/docs/api/api-specification.md +++ b/server/docs/api/api-specification.md @@ -235,7 +235,7 @@ POST /api/{模块}/{操作} ## 服务端实现约定 -- 请求 DTO 统一定义在 `internal/domain/dto.go`;`binding` tag 只出现在请求 DTO 上,GORM 实体只携带 `json` 与 `gorm` tag。 +- 请求 DTO 以所属业务域的 service 包内定义为常态(如 `service.CreateArticleRequest`),用户域的 `CreateUserRequest`/`UpdateUserRequest` 在 `internal/domain/dto.go`,短参数 DTO 可就地声明在 handler;`binding` tag 只出现在请求 DTO 上,GORM 实体只携带 `json` 与 `gorm` tag。 - 响应统一经 `pkg/response` 构建:成功用 `response.Success`,错误经 `handler.HandleServiceError` 分档,不把内部错误原文写入 `message`。 - Go 结构体命名、注释与代码风格示例见 [`docs/development.md`](../../../docs/development.md) 「代码规范」。 diff --git a/server/internal/config/README.md b/server/internal/config/README.md index 33b80c4..6b4e744 100644 --- a/server/internal/config/README.md +++ b/server/internal/config/README.md @@ -24,4 +24,4 @@ - 权限映射的生产环境唯一权威为 `rbac` 节,服务层经 `service.LoadRBACConfig` 读取,见 `cmd/myblog/deps.go`。 - 各子配置节的字段含义以 `configs/config.yaml` 注释为准。 -相关约束见 `AGENTS.md` 第 5 节与 `docs/development.md`「核心模块」。 +相关约束见 `docs/development.md`「核心模块」。 diff --git a/server/internal/handler/README.md b/server/internal/handler/README.md index 263f872..6b9cfb2 100644 --- a/server/internal/handler/README.md +++ b/server/internal/handler/README.md @@ -14,5 +14,3 @@ HTTP 协议层:参数绑定与校验、调用 service、以统一格式输出 ## 端点清单 各模块的路由、请求体与响应字段以 `server/docs/api/README.md` 为唯一索引,本文件不重复罗列。 - -相关约束见 `AGENTS.md` 第 5 节。 diff --git a/server/internal/middleware/README.md b/server/internal/middleware/README.md index 09b80da..c0e712f 100644 --- a/server/internal/middleware/README.md +++ b/server/internal/middleware/README.md @@ -20,5 +20,5 @@ HTTP 横切层。认证与权限中间件只依赖 `IdentityProvider` 抽象, - 全局中间件顺序见 `internal/router/router.go`:RequestID、指标记录、Logger、Recovery、CORS、Security、Language;管理员分组额外挂 `AdminSecurityMiddlewareFromConfig`。 - 日志输出为 JSON 行,初始化与请求标识读取见 `internal/logger`;请求级记录统一经 `logger.FromGin(c)` 取日志器,字段键取自 `logger.Field*` 常量。 - 权限清单唯一权威为 `configs/config.yaml` 的 `rbac.role_permissions`,本文件不重复罗列。 -- 限流计数与令牌表均为进程内存结构,单实例部署前提下的取舍见 `AGENTS.md` 第 1.7 节。 -- 实例化纪律(依赖由组合根注入)见 `AGENTS.md` 第 1.4 节。 +- 限流计数与令牌表均为进程内存结构,单实例部署前提下的取舍与扩容前置改造见 `docs/architecture-rules.md` §7。 +- 实例化纪律(依赖由组合根注入)见 `docs/architecture-rules.md` §5.2。 diff --git a/server/internal/repository/README.md b/server/internal/repository/README.md index f482fcb..75d3421 100644 --- a/server/internal/repository/README.md +++ b/server/internal/repository/README.md @@ -12,4 +12,4 @@ 方法签名(含分页与过滤参数,如用户仓库的 `List(offset, limit int, keyword string)`)以各 `repository/*.go` 的接口声明为准。 -相关约束见 `AGENTS.md` 第 5 节「类型归属」「数据库」。 +表结构设计的硬性约定见 `docs/database-architecture.md`「设计原则」,本包只在实体 tag 层面声明索引与删除策略。 diff --git a/server/internal/service/README.md b/server/internal/service/README.md index fda965a..e7c2961 100644 --- a/server/internal/service/README.md +++ b/server/internal/service/README.md @@ -16,4 +16,4 @@ - 密码使用 bcrypt,成本常量 `BcryptCost = 12`;强度校验 `ValidatePasswordStrength`(`password.go`)要求 6 至 100 位、同时含字母与数字、拒绝常见弱密码,校验失败统一包装 `ErrInvalidRequest` 供 handler 分档为 400。 - 刷新令牌换取新令牌对前查库校验用户存在且状态正常;改密成功后经 `RevokeUserTokens` 撤销该用户全部既有令牌。 -方法与字段清单以各 `service/*.go` 的接口声明为准。相关约束见 `AGENTS.md` 第 5 节与 `docs/architecture-rules.md` 第 5 节。 +方法与字段清单以各 `service/*.go` 的接口声明为准。相关约束见 `docs/architecture-rules.md` 第 5 节。 diff --git a/server/pkg/response/README.md b/server/pkg/response/README.md index 6a1b0ae..96dfa60 100644 --- a/server/pkg/response/README.md +++ b/server/pkg/response/README.md @@ -23,4 +23,4 @@ - 具体错误信息放在 `message` 字段,前端直接展示;`Response` 无 `error` 字段。 - handler 不把内部错误原文写入 `message`:service 错误统一经 `handler.HandleServiceError` 分档,未分类错误脱敏为「服务器内部错误」。 -- 前端响应类型唯一来源为 `@myblog/shared` 的 `ApiResponse`;响应码常量见 `AGENTS.md` 第 5 节「统一响应」。 +- 前端响应类型唯一来源为 `@myblog/shared` 的 `ApiResponse`;响应码常量以上表为唯一口径,与 `contracts/errors.yaml` 的 `transport` 节逐值一致。 From cf7cca6818eaf55dc66e48fecc45a69e6a5cdbb0 Mon Sep 17 00:00:00 2001 From: idleRain Date: Tue, 13 Oct 2026 17:18:50 +0800 Subject: [PATCH 5/5] =?UTF-8?q?refactor(admin):=20=E8=A1=A5=E5=85=A8=206?= =?UTF-8?q?=20=E4=B8=AA=E7=AE=A1=E7=90=86=E9=A1=B5=E5=8F=96=E6=95=B0?= =?UTF-8?q?=E5=BD=92=E4=BD=8D=E5=B9=B6=E6=B8=85=E9=9B=B6=20admin=20?= =?UTF-8?q?=E5=8F=96=E6=95=B0=E5=8F=A3=E5=BE=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 仪表盘、notifications、posts、posts/[id]、settings、stats 由 onMount 取数改为 +page.ts 的 load 取首屏 - 新增 notifications、settings、stats、posts 四个页面状态模块与配套单测,列表与全部读写操作归入模块 - 仪表盘与 posts/[id] 为只读页,无客户端读写,由 load 直出 page data,不建仅转发数据的空转模块 - 仪表盘与 posts 的权限裁剪移入 load,读 @myblog/auth 的本地认证状态,load 内不调用认证接口 - 仪表盘与 posts/[id] 移除页内首屏 loading 分支,取数在 load 完成后渲染 - stats 页趋势天数与选项收敛到 lib/constants/stats.ts,替换页面内的 7/14/30 字面量 - 6 页合计由 996 行降至 596 行;onMount 命中由 8 降至 2,剩余两处均为鉴权重定向 - 新增 57 个用例,admin 单测由 9 个文件 146 例增至 13 个文件 203 例,页面状态模块累计 11 个 196 例 - 同步更新 docs/debt/frontend.md 第 3 条、architecture-rules.md 第 6.2 与第 8、9 节 - 同步更新 docs/development.md 测试口径与 AGENTS.md 第 1 节第 6 条 --- AGENTS.md | 2 +- apps/admin/src/lib/constants/stats.ts | 7 + apps/admin/src/routes/(admin)/+page.svelte | 292 +++++++---------- apps/admin/src/routes/(admin)/+page.ts | 99 ++++++ .../routes/(admin)/notifications/+page.svelte | 160 +++------- .../src/routes/(admin)/notifications/+page.ts | 24 ++ .../notifications-page-state.test.ts | 288 +++++++++++++++++ .../notifications-page-state.svelte.ts | 128 ++++++++ .../src/routes/(admin)/posts/+page.svelte | 205 +++--------- apps/admin/src/routes/(admin)/posts/+page.ts | 39 +++ .../routes/(admin)/posts/[id]/+page.svelte | 51 +-- .../src/routes/(admin)/posts/[id]/+page.ts | 23 ++ .../posts/__tests__/posts-page-state.test.ts | 294 ++++++++++++++++++ .../(admin)/posts/posts-page-state.svelte.ts | 163 ++++++++++ .../src/routes/(admin)/settings/+page.svelte | 123 ++------ .../src/routes/(admin)/settings/+page.ts | 21 ++ .../__tests__/settings-page-state.test.ts | 237 ++++++++++++++ .../settings/settings-page-state.svelte.ts | 119 +++++++ .../src/routes/(admin)/stats/+page.svelte | 73 ++--- apps/admin/src/routes/(admin)/stats/+page.ts | 31 ++ .../stats/__tests__/stats-page-state.test.ts | 138 ++++++++ .../(admin)/stats/stats-page-state.svelte.ts | 68 ++++ docs/architecture-rules.md | 8 +- docs/debt/frontend.md | 12 +- docs/development.md | 2 +- 25 files changed, 1928 insertions(+), 679 deletions(-) create mode 100644 apps/admin/src/lib/constants/stats.ts create mode 100644 apps/admin/src/routes/(admin)/+page.ts create mode 100644 apps/admin/src/routes/(admin)/notifications/+page.ts create mode 100644 apps/admin/src/routes/(admin)/notifications/__tests__/notifications-page-state.test.ts create mode 100644 apps/admin/src/routes/(admin)/notifications/notifications-page-state.svelte.ts create mode 100644 apps/admin/src/routes/(admin)/posts/+page.ts create mode 100644 apps/admin/src/routes/(admin)/posts/[id]/+page.ts create mode 100644 apps/admin/src/routes/(admin)/posts/__tests__/posts-page-state.test.ts create mode 100644 apps/admin/src/routes/(admin)/posts/posts-page-state.svelte.ts create mode 100644 apps/admin/src/routes/(admin)/settings/+page.ts create mode 100644 apps/admin/src/routes/(admin)/settings/__tests__/settings-page-state.test.ts create mode 100644 apps/admin/src/routes/(admin)/settings/settings-page-state.svelte.ts create mode 100644 apps/admin/src/routes/(admin)/stats/+page.ts create mode 100644 apps/admin/src/routes/(admin)/stats/__tests__/stats-page-state.test.ts create mode 100644 apps/admin/src/routes/(admin)/stats/stats-page-state.svelte.ts diff --git a/AGENTS.md b/AGENTS.md index d47b97d..da2a6ca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,7 @@ 验证:`git grep -n "NewRBACService()" -- server` 的生产命中应仅 `cmd/myblog/deps.go` 一处。 5. **禁止复制粘贴式共享**。两 app 间禁止新增逐字或近似重复文件,公共逻辑下沉 packages;存量逐字重复仅 `src/lib/stores/auth.ts`(15 行 ×2)与 `src/lib/components/theme-toggle.svelte`(45 行 ×2),改任一份必须同步另一份。 验证:`git diff --no-index` 上述两份文件应零差异。 -6. **数据加载归位**。`apps/web` 新页面禁止 `onMount` 取数,用 `+page.server.ts` / `+page.ts` 的 load;`apps/admin` 新页面优先 load + 页面状态模块(`.svelte.ts`);API 调用不得深入叶子组件。 +6. **数据加载归位**。`apps/web` 新页面禁止 `onMount` 取数,用 `+page.server.ts` / `+page.ts` 的 load;`apps/admin` 新页面同样禁止 `onMount` 取数,含客户端读写操作的页面配 load + 页面状态模块(`.svelte.ts`),只读页由 load 直出 page data,load 内禁止调用认证接口;API 调用不得深入叶子组件。 7. **部署形态为单实例**(有意取舍,非待修缺陷)。应用进程、MySQL、网关各一份,无副本与故障转移;会话令牌表与限流计数均为进程内存结构,服务重启或发布将导致全体用户登出,发布窗口需提前预告;故障即停站,无 RTO 承诺,RPO 为 24 小时。扩容前必须完成令牌表持久化、限流器外置、补 `SetTrustedProxies` 三项改造。 验证:`git grep -n "SetTrustedProxies" -- server` 与 `git grep -n "replicas" -- docker-compose.yml` 均应为空。 8. **先确认产品定位**。单作者个人博客,不开放注册、无找回密码通道:账号由管理员创建(首次部署 `pnpm run seed:admin`,之后在后台用户管理页新增),忘记密码由超级管理员经 `POST /api/users/update` 重置;游客可浏览并提交评论(受审核设置约束),点赞/收藏/关注需登录。功能提案前先确认是否与之冲突;新增数据收集场景须先同步 `apps/web` 的 `/privacy` 页告知。 diff --git a/apps/admin/src/lib/constants/stats.ts b/apps/admin/src/lib/constants/stats.ts new file mode 100644 index 0000000..d2fe846 --- /dev/null +++ b/apps/admin/src/lib/constants/stats.ts @@ -0,0 +1,7 @@ +// 站点统计模块常量:浏览量趋势的可选天数与默认天数。 + +// 趋势可选天数,取值与后端趋势接口的 days 参数一致。 +export const TREND_DAY_OPTIONS = ['7', '14', '30'] + +// 趋势默认天数,首屏取数与切换控件共用同一默认值。 +export const DEFAULT_TREND_DAYS = '7' diff --git a/apps/admin/src/routes/(admin)/+page.svelte b/apps/admin/src/routes/(admin)/+page.svelte index 7a7b3da..f67f135 100644 --- a/apps/admin/src/routes/(admin)/+page.svelte +++ b/apps/admin/src/routes/(admin)/+page.svelte @@ -13,95 +13,24 @@ import { } from '@lucide/svelte' import ViewsTrendChart from '$lib/components/admin/stats/views-trend-chart.svelte' import StatCard from '$lib/components/admin/dashboard/stat-card.svelte' -import type { StatsOverview } from '@myblog/api/modules/stats/types' import PageHeader from '$lib/components/admin/page-header.svelte' -import type { Article } from '@myblog/api/modules/article/types' import type { UserRole } from '@myblog/api/modules/user/types' -import { hasPermission } from '$lib/utils/permissions' -import { PERMISSIONS } from '$lib/constants/auth' -import { ArticleAPI, StatsAPI } from '$lib/api' import { SITE_NAME_ZH } from '@myblog/shared' import { goto } from '$lib/utils/navigation' -import { authStore } from '$lib/stores/auth' +import type { PageProps } from './$types' import { Button } from '$ui/button' import * as Card from '$ui/card' -import { onMount } from 'svelte' -// 当前用户角色与昵称,区块裁剪依据后端登录下发的权限列表。 -let userRole = $state('user') -let canViewStats = $state(false) -let canViewArticles = $state(false) -let canCreateArticle = $state(false) -let canManageUsers = $state(false) -let nickname = $state('') +// 仪表盘区块可见性与各区块首屏数据均由 load 注入,组件只做渲染与跳转分发。 +let { data }: PageProps = $props() -let overview = $state(null) -let isLoading = $state(true) -let trendDates = $state([]) -let trendValues = $state([]) -let recentArticles = $state([]) - -/** - * 加载仪表盘数据。 - * 统计概览与趋势仅具备 system:stats 权限的角色可读取,按下发权限做前端区块裁剪; - * 最新文章列表对具备 article:list 权限的角色统一走 /api/articles/list,状态可见性由后端判定。 - */ -async function loadDashboard() { - isLoading = true - try { - const currentState = authStore.getCurrentState() - const currentUser = currentState.user - userRole = currentUser?.role ?? 'user' - nickname = currentUser?.nickname ?? '' - // 权限判定与后端各接口判定一致,修改权限表后重新登录即可联动变化。 - canViewStats = hasPermission(currentUser, PERMISSIONS.SYSTEM_STATS) - canViewArticles = hasPermission(currentUser, PERMISSIONS.ARTICLE_LIST) - canCreateArticle = hasPermission(currentUser, PERMISSIONS.ARTICLE_CREATE) - canManageUsers = hasPermission(currentUser, PERMISSIONS.USER_LIST) - - if (canViewStats) { - const [overviewResult, trendResult] = await Promise.all([ - StatsAPI.getOverview().catch(() => null), - StatsAPI.getArticleViewsTrend(7).catch(() => null) - ]) - - if (overviewResult?.code === 200 && overviewResult.data) { - overview = overviewResult.data - } - if (trendResult?.code === 200 && trendResult.data) { - trendDates = trendResult.data.dates ?? [] - trendValues = trendResult.data.values ?? [] - } - } - - if (canViewArticles) { - const articleResult = await ArticleAPI.list({ page: 1, pageSize: 5 }).catch(() => null) - if (articleResult?.code === 200 && articleResult.data) { - recentArticles = articleResult.data.articles ?? [] - } - } - } catch (error) { - console.error('加载仪表盘数据失败:', error) - toast.error('网络错误,请稍后重试') - } finally { - isLoading = false - } +// 角色到仪表盘标题的映射,标题跟随后端下发的角色。 +const WELCOME_TITLES: Record = { + superadmin: '超级管理员仪表盘', + admin: '管理员仪表盘', + editor: '编辑工作台', + user: '个人工作台' } - -/** - * 依据角色计算仪表盘标题。 - */ -function welcomeTitle(): string { - const map: Record = { - superadmin: '超级管理员仪表盘', - admin: '管理员仪表盘', - editor: '编辑工作台', - user: '个人工作台' - } - return map[userRole] -} - -onMount(loadDashboard) @@ -109,123 +38,116 @@ onMount(loadDashboard) - {#if isLoading} -
- + {#if data.overview} +
+ + + + + + + +
- {:else} - {#if overview} -
- - - - - - - - + {/if} + +
+ {#if data.overview} +
+ + + 近 7 天浏览量趋势 + 每日文章访问量统计 + + + + +
{/if} -
- {#if overview} -
- - - 近 7 天浏览量趋势 - 每日文章访问量统计 - - - - - -
- {/if} +
+ + + 快速操作 + 常用的管理操作 + + + {#if data.canCreateArticle} + + {/if} + {#if data.canViewArticles} + + {/if} + {#if data.canManageUsers} + + {/if} + + -
+ {#if data.canViewArticles} - 快速操作 - 常用的管理操作 + 最新文章 - - {#if canCreateArticle} - - {/if} - {#if canViewArticles} - - {/if} - {#if canManageUsers} - - {/if} + {article.title} + + {new Date(article.createdAt).toLocaleDateString('zh-CN')} + + + {:else} +

暂无文章

+ {/each}
- - {#if canViewArticles} - - - 最新文章 - - - {#each recentArticles as article (article.id)} - - {:else} -

暂无文章

- {/each} -
-
- {/if} -
+ {/if}
- {/if} +
diff --git a/apps/admin/src/routes/(admin)/+page.ts b/apps/admin/src/routes/(admin)/+page.ts new file mode 100644 index 0000000..9d6e92e --- /dev/null +++ b/apps/admin/src/routes/(admin)/+page.ts @@ -0,0 +1,99 @@ +import type { PageLoad } from './$types' + +import type { StatsOverview } from '@myblog/api/modules/stats/types' +import type { Article } from '@myblog/api/modules/article/types' +import type { UserRole } from '@myblog/api/modules/user/types' +import { hasPermission } from '$lib/utils/permissions' +import { PERMISSIONS } from '$lib/constants/auth' +import { ArticleAPI, StatsAPI } from '$lib/api' +import { authStore } from '$lib/stores/auth' + +// 统计概览与趋势的取数天数,与区块标题「近 7 天」一致。 +const DASHBOARD_TREND_DAYS = 7 + +// 最新文章区块的展示条数。 +const RECENT_ARTICLE_LIMIT = 5 + +// 仪表盘页面数据,区块可见性标记与各区块首屏数据一并经 load 注入。 +interface DashboardPageData { + userRole: UserRole + nickname: string + canViewArticles: boolean + canCreateArticle: boolean + canManageUsers: boolean + overview: StatsOverview | null + trendDates: string[] + trendValues: number[] + recentArticles: Article[] +} + +// 统计区块取数。概览与趋势任一失败只影响本区块,其余区块照常渲染。 +async function loadStatsSection(): Promise< + Pick +> { + const section: Pick = { + overview: null, + trendDates: [], + trendValues: [] + } + + const [overviewResult, trendResult] = await Promise.allSettled([ + StatsAPI.getOverview(), + StatsAPI.getArticleViewsTrend(DASHBOARD_TREND_DAYS) + ]) + + if (overviewResult.status === 'fulfilled' && overviewResult.value.code === 200) { + section.overview = overviewResult.value.data ?? null + } else if (overviewResult.status === 'rejected') { + console.error('加载统计概览失败:', overviewResult.reason) + } + + if (trendResult.status === 'fulfilled' && trendResult.value.code === 200) { + section.trendDates = trendResult.value.data?.dates ?? [] + section.trendValues = trendResult.value.data?.values ?? [] + } else if (trendResult.status === 'rejected') { + console.error('加载浏览量趋势失败:', trendResult.reason) + } + + return section +} + +// 最新文章区块取数。该列表对具备 article:list 权限的角色统一走 /api/articles/list, +// 状态可见性由后端判定,前端不再按角色裁剪状态。 +async function loadRecentArticles(): Promise { + try { + const response = await ArticleAPI.list({ page: 1, pageSize: RECENT_ARTICLE_LIMIT }) + if (response.code === 200 && response.data) { + return response.data.articles ?? [] + } + console.error('加载最新文章失败:', response.message) + } catch (error) { + console.error('加载最新文章失败:', error) + } + return [] +} + +// 仪表盘初始数据。区块可见性按后端登录下发的权限列表裁剪,权限读取走本地认证状态, +// 该状态在 store 创建时已同步水合,load 内不调用认证接口。 +export const load: PageLoad = async () => { + const currentUser = authStore.getCurrentState().user + const canViewStats = hasPermission(currentUser, PERMISSIONS.SYSTEM_STATS) + const canViewArticles = hasPermission(currentUser, PERMISSIONS.ARTICLE_LIST) + + const statsSection = canViewStats + ? await loadStatsSection() + : { overview: null, trendDates: [], trendValues: [] } + const recentArticles = canViewArticles ? await loadRecentArticles() : [] + + const pageData: DashboardPageData = { + userRole: currentUser?.role ?? 'user', + nickname: currentUser?.nickname ?? '', + canViewArticles, + canCreateArticle: hasPermission(currentUser, PERMISSIONS.ARTICLE_CREATE), + canManageUsers: hasPermission(currentUser, PERMISSIONS.USER_LIST), + ...statsSection, + recentArticles + } + + return pageData +} diff --git a/apps/admin/src/routes/(admin)/notifications/+page.svelte b/apps/admin/src/routes/(admin)/notifications/+page.svelte index e34f5a2..a6d0908 100644 --- a/apps/admin/src/routes/(admin)/notifications/+page.svelte +++ b/apps/admin/src/routes/(admin)/notifications/+page.svelte @@ -4,116 +4,30 @@ import { NOTIFICATION_TYPE_LABELS, NOTIFICATION_TYPE_OPTIONS } from '$lib/constants/notification' -import type { Notification, NotificationType } from '@myblog/api/modules/notification/types' +import { + notificationsPageState, + emptyNotificationsPageData +} from './notifications-page-state.svelte' import { Bell, CheckCheck, Inbox, RotateCcw } from '@lucide/svelte' import PageHeader from '$lib/components/admin/page-header.svelte' import * as ToggleGroup from '$ui/toggle-group' import { SITE_NAME_ZH } from '@myblog/shared' import * as Pagination from '$ui/pagination' -import { NotificationAPI } from '$lib/api' +import type { PageProps } from './$types' +import { Spinner } from '$ui/spinner' import { Button } from '$ui/button' import { Badge } from '$ui/badge' import * as Card from '$ui/card' -import { onMount } from 'svelte' - -let notifications = $state([]) -let isLoading = $state(true) -let total = $state(0) -let unreadCount = $state(0) -let currentPage = $state(1) -let typeFilter = $state('') - -// 是否存在生效中的筛选条件,用于空态区分「无数据」与「无匹配」。 -const hasActiveFilters = $derived(typeFilter !== '') - -/** - * 加载通知列表并同步未读数。 - */ -async function loadNotifications() { - isLoading = true - try { - const response = await NotificationAPI.list({ - page: currentPage, - pageSize: NOTIFICATION_PAGE_SIZE, - ...(typeFilter ? { type: typeFilter } : {}) - }) - if (response.code === 200 && response.data) { - notifications = response.data.notifications ?? [] - total = response.data.total ?? 0 - unreadCount = response.data.unreadCount ?? 0 - } else { - toast.error(response.message || '加载通知失败') - } - } catch (error) { - console.error('加载通知失败:', error) - toast.error('网络错误,请稍后重试') - } finally { - isLoading = false - } -} - -/** - * 类型筛选变更后立即回到第一页并重新加载。 - */ -function handleTypeFilterChange(value: string) { - typeFilter = value as NotificationType | '' - currentPage = 1 - loadNotifications() -} -/** - * 重置筛选并回到第一页。 - */ -function resetAndReload() { - typeFilter = '' - currentPage = 1 - loadNotifications() -} +let { data }: PageProps = $props() -/** - * 标记单条通知为已读。 - */ -async function handleMarkRead(notification: Notification) { - if (notification.isRead) return - try { - const response = await NotificationAPI.markRead(notification.id) - if (response.code === 200) { - notification.isRead = true - unreadCount = Math.max(0, unreadCount - 1) - } else { - toast.error(response.message || '操作失败') - } - } catch (error) { - console.error('标记已读失败:', error) - toast.error('网络错误,请稍后重试') - } -} - -/** - * 标记全部通知为已读。 - */ -async function handleMarkAllRead() { - try { - const response = await NotificationAPI.markAllRead() - if (response.code === 200) { - unreadCount = 0 - notifications = notifications.map(item => ({ ...item, isRead: true })) - toast.success('全部通知已标记为已读') - } else { - toast.error(response.message || '操作失败') - } - } catch (error) { - console.error('标记全部已读失败:', error) - toast.error('网络错误,请稍后重试') - } -} - -function handlePageChange(page: number) { - currentPage = page - loadNotifications() -} - -onMount(loadNotifications) +// 初始数据经 load 注入后交给页面状态模块接管,组件只做渲染与交互分发。 +let initialized = false +$effect(() => { + if (initialized) return + initialized = true + notificationsPageState.initialize(data ?? emptyNotificationsPageData()) +}) @@ -122,7 +36,7 @@ onMount(loadNotifications) {#snippet actions()} - @@ -135,8 +49,8 @@ onMount(loadNotifications) type="single" variant="outline" size="sm" - value={typeFilter} - onValueChange={handleTypeFilterChange} + value={notificationsPageState.typeFilter} + onValueChange={value => notificationsPageState.setTypeFilter(value)} > {#each NOTIFICATION_TYPE_OPTIONS as option (option.label)} {option.label} @@ -146,36 +60,40 @@ onMount(loadNotifications)
- {unreadCount} 条未读 + {notificationsPageState.unreadCount} 条未读 -
- {#if isLoading} + {#if notificationsPageState.isLoading}
- +
- {:else if notifications.length === 0} + {:else if notificationsPageState.notifications.length === 0}

- {hasActiveFilters ? '没有匹配的通知' : '暂无通知'} + {notificationsPageState.hasActiveFilters ? '没有匹配的通知' : '暂无通知'}

- {hasActiveFilters ? '调整或重置筛选条件后再试' : '新的评论回复与点赞会在这里提醒你'} + {notificationsPageState.hasActiveFilters + ? '调整或重置筛选条件后再试' + : '新的评论回复与点赞会在这里提醒你'}

- {#if hasActiveFilters} - @@ -183,10 +101,10 @@ onMount(loadNotifications)
{:else}
- {#each notifications as notification (notification.id)} + {#each notificationsPageState.notifications as notification (notification.id)}
-

共 {total} 条通知

+

共 {notificationsPageState.total} 条通知

notificationsPageState.changePage(page)} > - 第 {currentPage} 页,共 {Math.max(1, Math.ceil(total / NOTIFICATION_PAGE_SIZE))} 页 + 第 {notificationsPageState.currentPage} 页,共 {notificationsPageState.totalPages} 页 diff --git a/apps/admin/src/routes/(admin)/notifications/+page.ts b/apps/admin/src/routes/(admin)/notifications/+page.ts new file mode 100644 index 0000000..d43b1bd --- /dev/null +++ b/apps/admin/src/routes/(admin)/notifications/+page.ts @@ -0,0 +1,24 @@ +import type { PageLoad } from './$types' + +import { emptyNotificationsPageData } from './notifications-page-state.svelte' +import { NOTIFICATION_PAGE_SIZE } from '$lib/constants/notification' +import { NotificationAPI } from '$lib/api' + +// 通知中心页初始数据:首屏加载第一页且不带类型筛选。 +// 列表加载失败不抛错,回退空数据并由页面状态模块在后续交互中继续提示。 +export const load: PageLoad = async () => { + const pageData = emptyNotificationsPageData() + try { + const response = await NotificationAPI.list({ page: 1, pageSize: NOTIFICATION_PAGE_SIZE }) + if (response.code === 200 && response.data) { + pageData.notifications = response.data.notifications ?? [] + pageData.total = response.data.total ?? 0 + pageData.unreadCount = response.data.unreadCount ?? 0 + } else { + console.error('加载通知列表失败:', response.message) + } + } catch (error) { + console.error('加载通知列表失败:', error) + } + return pageData +} diff --git a/apps/admin/src/routes/(admin)/notifications/__tests__/notifications-page-state.test.ts b/apps/admin/src/routes/(admin)/notifications/__tests__/notifications-page-state.test.ts new file mode 100644 index 0000000..bfca1da --- /dev/null +++ b/apps/admin/src/routes/(admin)/notifications/__tests__/notifications-page-state.test.ts @@ -0,0 +1,288 @@ +import type { Notification } from '@myblog/api/modules/notification/types' +import { beforeEach, describe, expect, it, vi } from 'vitest' + +import { NOTIFICATION_PAGE_SIZE } from '$lib/constants/notification' + +// 接口与提示均以替身注入,测试只验证页面状态的编排逻辑,不触达网络与界面。 +const notificationApiMock = { + list: vi.fn(), + markRead: vi.fn(), + markAllRead: vi.fn() +} + +const toastMock = { + success: vi.fn(), + error: vi.fn() +} + +vi.mock('$lib/api', () => ({ NotificationAPI: notificationApiMock })) +vi.mock('svelte-sonner', () => ({ toast: toastMock })) + +const { emptyNotificationsPageData, notificationsPageState } = + await import('../notifications-page-state.svelte') + +// 后端统一响应的成功业务码。 +const SUCCESS_CODE = 200 + +// 构造一条通知替身,字段取值只覆盖被测逻辑关心的部分。 +function makeNotification(id: number, isRead = false): Notification { + return { + id, + type: 'comment_reply', + title: `通知${id}`, + content: null, + isRead, + createdAt: '2026-01-01T00:00:00Z' + } as unknown as Notification +} + +// 重置替身调用记录与页面状态,避免用例之间互相污染。 +function resetState() { + vi.clearAllMocks() + notificationsPageState.initialize(emptyNotificationsPageData()) + notificationsPageState.typeFilter = '' + notificationsPageState.currentPage = 1 +} + +describe('通知中心页状态:初始化', () => { + beforeEach(resetState) + + it('用 load 结果填充列表、总数与未读数', () => { + const notifications = [makeNotification(1), makeNotification(2, true)] + + notificationsPageState.initialize({ notifications, total: 2, unreadCount: 1 }) + + expect(notificationsPageState.notifications).toEqual(notifications) + expect(notificationsPageState.total).toBe(2) + expect(notificationsPageState.unreadCount).toBe(1) + }) + + it('空数据下无生效筛选条件且总页数至少为 1', () => { + expect(notificationsPageState.notifications).toEqual([]) + expect(notificationsPageState.isLoading).toBe(false) + expect(notificationsPageState.hasActiveFilters).toBe(false) + expect(notificationsPageState.totalPages).toBe(1) + }) +}) + +describe('通知中心页状态:列表加载', () => { + beforeEach(resetState) + + it('默认只携带分页参数', async () => { + notificationApiMock.list.mockResolvedValue({ + code: SUCCESS_CODE, + data: { notifications: [makeNotification(1)], total: 1, unreadCount: 0 } + }) + + await notificationsPageState.loadNotifications() + + expect(notificationApiMock.list).toHaveBeenCalledWith({ + page: 1, + pageSize: NOTIFICATION_PAGE_SIZE + }) + expect(notificationsPageState.notifications).toHaveLength(1) + expect(notificationsPageState.total).toBe(1) + }) + + it('类型筛选生效时按类型查询', async () => { + notificationApiMock.list.mockResolvedValue({ + code: SUCCESS_CODE, + data: { notifications: [], total: 0, unreadCount: 0 } + }) + notificationsPageState.typeFilter = 'system' + notificationsPageState.currentPage = 3 + + await notificationsPageState.loadNotifications() + + expect(notificationApiMock.list).toHaveBeenCalledWith({ + page: 3, + pageSize: NOTIFICATION_PAGE_SIZE, + type: 'system' + }) + }) + + it('响应缺失列表字段时按空列表处理', async () => { + notificationApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: {} }) + + await notificationsPageState.loadNotifications() + + expect(notificationsPageState.notifications).toEqual([]) + expect(notificationsPageState.total).toBe(0) + expect(notificationsPageState.unreadCount).toBe(0) + }) + + it('业务码非成功时提示后端文案且不清空现有列表', async () => { + notificationApiMock.list.mockResolvedValue({ code: 500, message: '查询失败' }) + notificationsPageState.initialize({ + notifications: [makeNotification(1)], + total: 1, + unreadCount: 1 + }) + + await notificationsPageState.loadNotifications() + + expect(toastMock.error).toHaveBeenCalledWith('查询失败') + expect(notificationsPageState.notifications).toHaveLength(1) + expect(notificationsPageState.isLoading).toBe(false) + }) + + it('请求抛错时提示网络错误并复位加载态', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + notificationApiMock.list.mockRejectedValue(new Error('断网')) + + await notificationsPageState.loadNotifications() + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(notificationsPageState.isLoading).toBe(false) + consoleError.mockRestore() + }) +}) + +describe('通知中心页状态:筛选与分页', () => { + beforeEach(resetState) + + it('类型筛选变更后回到第一页并重新加载', async () => { + notificationApiMock.list.mockResolvedValue({ + code: SUCCESS_CODE, + data: { notifications: [], total: 0, unreadCount: 0 } + }) + notificationsPageState.currentPage = 4 + + notificationsPageState.setTypeFilter('article_like') + + expect(notificationsPageState.typeFilter).toBe('article_like') + expect(notificationsPageState.currentPage).toBe(1) + expect(notificationsPageState.hasActiveFilters).toBe(true) + await vi.waitFor(() => expect(notificationApiMock.list).toHaveBeenCalledTimes(1)) + }) + + it('重置筛选清空类型条件并回到第一页', async () => { + notificationApiMock.list.mockResolvedValue({ + code: SUCCESS_CODE, + data: { notifications: [], total: 0, unreadCount: 0 } + }) + notificationsPageState.typeFilter = 'follow' + notificationsPageState.currentPage = 5 + + notificationsPageState.resetFilters() + + expect(notificationsPageState.typeFilter).toBe('') + expect(notificationsPageState.currentPage).toBe(1) + expect(notificationsPageState.hasActiveFilters).toBe(false) + await vi.waitFor(() => expect(notificationApiMock.list).toHaveBeenCalledTimes(1)) + }) + + it('切换页码后按目标页加载', async () => { + notificationApiMock.list.mockResolvedValue({ + code: SUCCESS_CODE, + data: { notifications: [], total: 50, unreadCount: 0 } + }) + + notificationsPageState.changePage(3) + + expect(notificationsPageState.currentPage).toBe(3) + await vi.waitFor(() => + expect(notificationApiMock.list).toHaveBeenCalledWith({ + page: 3, + pageSize: NOTIFICATION_PAGE_SIZE + }) + ) + }) + + it('总页数按分页大小向上取整', () => { + notificationsPageState.initialize({ + notifications: [], + total: NOTIFICATION_PAGE_SIZE * 2 + 1, + unreadCount: 0 + }) + + expect(notificationsPageState.totalPages).toBe(3) + }) +}) + +describe('通知中心页状态:标记已读', () => { + beforeEach(resetState) + + it('已读条目不再发起请求', async () => { + const target = makeNotification(1, true) + + await notificationsPageState.markRead(target) + + expect(notificationApiMock.markRead).not.toHaveBeenCalled() + }) + + it('标记成功后就地更新条目并递减未读数', async () => { + notificationApiMock.markRead.mockResolvedValue({ code: SUCCESS_CODE, data: null }) + const target = makeNotification(1) + notificationsPageState.initialize({ notifications: [target], total: 1, unreadCount: 2 }) + + await notificationsPageState.markRead(target) + + expect(notificationApiMock.markRead).toHaveBeenCalledWith(1) + expect(target.isRead).toBe(true) + expect(notificationsPageState.unreadCount).toBe(1) + }) + + it('未读数不会因标记操作变为负数', async () => { + notificationApiMock.markRead.mockResolvedValue({ code: SUCCESS_CODE, data: null }) + const target = makeNotification(1) + + await notificationsPageState.markRead(target) + + expect(notificationsPageState.unreadCount).toBe(0) + }) + + it('业务码非成功时提示后端文案且不改动未读数', async () => { + notificationApiMock.markRead.mockResolvedValue({ code: 403, message: '无权操作' }) + const target = makeNotification(1) + notificationsPageState.initialize({ notifications: [target], total: 1, unreadCount: 1 }) + + await notificationsPageState.markRead(target) + + expect(toastMock.error).toHaveBeenCalledWith('无权操作') + expect(target.isRead).toBe(false) + expect(notificationsPageState.unreadCount).toBe(1) + }) + + it('请求抛错时提示网络错误', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + notificationApiMock.markRead.mockRejectedValue(new Error('断网')) + const target = makeNotification(1) + + await notificationsPageState.markRead(target) + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(target.isRead).toBe(false) + consoleError.mockRestore() + }) + + it('全部已读成功后清零未读数并同步列表', async () => { + notificationApiMock.markAllRead.mockResolvedValue({ code: SUCCESS_CODE, data: null }) + notificationsPageState.initialize({ + notifications: [makeNotification(1), makeNotification(2)], + total: 2, + unreadCount: 2 + }) + + await notificationsPageState.markAllRead() + + expect(notificationsPageState.unreadCount).toBe(0) + expect(notificationsPageState.notifications.every(item => item.isRead)).toBe(true) + expect(toastMock.success).toHaveBeenCalledWith('全部通知已标记为已读') + }) + + it('全部已读失败时提示且保留未读数', async () => { + notificationApiMock.markAllRead.mockResolvedValue({ code: 500, message: '操作失败' }) + notificationsPageState.initialize({ + notifications: [makeNotification(1)], + total: 1, + unreadCount: 1 + }) + + await notificationsPageState.markAllRead() + + expect(toastMock.error).toHaveBeenCalledWith('操作失败') + expect(notificationsPageState.unreadCount).toBe(1) + expect(notificationsPageState.notifications.every(item => !item.isRead)).toBe(true) + }) +}) diff --git a/apps/admin/src/routes/(admin)/notifications/notifications-page-state.svelte.ts b/apps/admin/src/routes/(admin)/notifications/notifications-page-state.svelte.ts new file mode 100644 index 0000000..2c26c85 --- /dev/null +++ b/apps/admin/src/routes/(admin)/notifications/notifications-page-state.svelte.ts @@ -0,0 +1,128 @@ +import type { Notification, NotificationType } from '@myblog/api/modules/notification/types' +import { NOTIFICATION_PAGE_SIZE } from '$lib/constants/notification' +import { NotificationAPI } from '$lib/api' +import { toast } from 'svelte-sonner' + +// 网络异常的统一提示文案。 +const NETWORK_ERROR_MESSAGE = '网络错误,请稍后重试' + +// 初始页面数据形状,由 +page.ts 的 load 函数提供。 +export interface NotificationsPageData { + notifications: Notification[] + total: number + unreadCount: number +} + +// 空页面数据,load 失败时使用。 +export function emptyNotificationsPageData(): NotificationsPageData { + return { notifications: [], total: 0, unreadCount: 0 } +} + +// 通知中心页状态:集中持有列表、筛选条件与全部读写操作,页面组件只做渲染。 +class NotificationsPageState { + notifications = $state([]) + total = $state(0) + unreadCount = $state(0) + currentPage = $state(1) + // 类型筛选使用空串表示全部,与通知类型枚举的取值区间分开。 + typeFilter = $state('') + isLoading = $state(false) + + // 总页数,分页控件与页码文案共用同一口径。 + get totalPages(): number { + return Math.max(1, Math.ceil(this.total / NOTIFICATION_PAGE_SIZE)) + } + + // 是否存在生效中的筛选条件,用于空态区分无数据与无匹配。 + get hasActiveFilters(): boolean { + return this.typeFilter !== '' + } + + // 用 load 结果初始化页面状态,重复挂载时以最新数据覆盖。 + initialize(data: NotificationsPageData) { + this.notifications = data.notifications + this.total = data.total + this.unreadCount = data.unreadCount + } + + // 加载通知列表并同步未读数。 + async loadNotifications() { + this.isLoading = true + try { + const response = await NotificationAPI.list({ + page: this.currentPage, + pageSize: NOTIFICATION_PAGE_SIZE, + ...(this.typeFilter ? { type: this.typeFilter } : {}) + }) + if (response.code === 200 && response.data) { + this.notifications = response.data.notifications ?? [] + this.total = response.data.total ?? 0 + this.unreadCount = response.data.unreadCount ?? 0 + } else { + toast.error(response.message || '加载通知失败') + } + } catch (error) { + console.error('加载通知失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + this.isLoading = false + } + } + + // 类型筛选变更后回到第一页并重新加载。 + setTypeFilter(value: string) { + this.typeFilter = value as NotificationType | '' + this.currentPage = 1 + void this.loadNotifications() + } + + // 重置筛选条件并回到第一页。 + resetFilters() { + this.typeFilter = '' + this.currentPage = 1 + void this.loadNotifications() + } + + // 切换页码并重新加载。 + changePage(page: number) { + this.currentPage = page + void this.loadNotifications() + } + + // 标记单条通知为已读,已读条目不再发起请求。 + async markRead(notification: Notification) { + if (notification.isRead) return + try { + const response = await NotificationAPI.markRead(notification.id) + if (response.code === 200) { + notification.isRead = true + this.unreadCount = Math.max(0, this.unreadCount - 1) + } else { + toast.error(response.message || '操作失败') + } + } catch (error) { + console.error('标记已读失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + } + + // 标记全部通知为已读,成功后本地列表同步为已读态。 + async markAllRead() { + try { + const response = await NotificationAPI.markAllRead() + if (response.code === 200) { + this.unreadCount = 0 + this.notifications = this.notifications.map(item => ({ ...item, isRead: true })) + toast.success('全部通知已标记为已读') + } else { + toast.error(response.message || '操作失败') + } + } catch (error) { + console.error('标记全部已读失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + } +} + +// 页面级共享状态实例。 +export const notificationsPageState = new NotificationsPageState() diff --git a/apps/admin/src/routes/(admin)/posts/+page.svelte b/apps/admin/src/routes/(admin)/posts/+page.svelte index 23759cb..3a28213 100644 --- a/apps/admin/src/routes/(admin)/posts/+page.svelte +++ b/apps/admin/src/routes/(admin)/posts/+page.svelte @@ -1,159 +1,26 @@ @@ -172,37 +39,35 @@ onMount(() => { postsPageState.applyFilterChange()} + onReset={() => postsPageState.resetFilters()} /> - {#if isLoading} + {#if postsPageState.isLoading}
- +
- {:else if articles.length === 0} + {:else if postsPageState.articles.length === 0}

- {hasActiveFilters ? '没有匹配的文章' : '暂无文章'} + {postsPageState.hasActiveFilters ? '没有匹配的文章' : '暂无文章'}

- {hasActiveFilters ? '调整或重置筛选条件后再试' : '写下第一篇博客文章'} + {postsPageState.hasActiveFilters ? '调整或重置筛选条件后再试' : '写下第一篇博客文章'}

- {#if hasActiveFilters} - @@ -214,21 +79,25 @@ onMount(() => { {/if}
{:else} - + postsPageState.applyStatusAction(article, action)} + onDelete={article => postsPageState.removeArticle(article)} + />
-

共 {total} 篇文章

+

共 {postsPageState.total} 篇文章

postsPageState.changePage(page)} > - 第 {currentPage} 页,共 {Math.max(1, Math.ceil(total / ARTICLE_PAGE_SIZE))} 页 + 第 {postsPageState.currentPage} 页,共 {postsPageState.totalPages} 页 diff --git a/apps/admin/src/routes/(admin)/posts/+page.ts b/apps/admin/src/routes/(admin)/posts/+page.ts new file mode 100644 index 0000000..cae448d --- /dev/null +++ b/apps/admin/src/routes/(admin)/posts/+page.ts @@ -0,0 +1,39 @@ +import type { PageLoad } from './$types' + +import { emptyPostsPageData } from './posts-page-state.svelte' +import { ARTICLE_PAGE_SIZE } from '$lib/constants/article' +import { hasPermission } from '$lib/utils/permissions' +import { PERMISSIONS } from '$lib/constants/auth' +import { authStore } from '$lib/stores/auth' +import { ArticleAPI } from '$lib/api' + +// 文章管理页初始数据:首屏加载第一页且不带筛选的文章列表。 +// 状态筛选的可用性按后端登录下发的权限裁剪,权限读取走本地认证状态, +// 该状态在 store 创建时已同步水合,load 内不调用认证接口。 +// 列表加载失败不抛错,回退空数据并由页面状态模块在后续交互中继续提示。 +export const load: PageLoad = async () => { + const pageData = emptyPostsPageData() + pageData.canManageAllArticles = hasPermission( + authStore.getCurrentState().user, + PERMISSIONS.ARTICLE_MANAGE + ) + + try { + const response = await ArticleAPI.list({ + page: 1, + pageSize: ARTICLE_PAGE_SIZE, + status: '', + sortBy: 'created_at', + order: 'desc' + }) + if (response.code === 200 && response.data) { + pageData.articles = response.data.articles ?? [] + pageData.total = response.data.total ?? 0 + } else { + console.error('加载文章列表失败:', response.message) + } + } catch (error) { + console.error('加载文章列表失败:', error) + } + return pageData +} diff --git a/apps/admin/src/routes/(admin)/posts/[id]/+page.svelte b/apps/admin/src/routes/(admin)/posts/[id]/+page.svelte index 65c0441..83277a5 100644 --- a/apps/admin/src/routes/(admin)/posts/[id]/+page.svelte +++ b/apps/admin/src/routes/(admin)/posts/[id]/+page.svelte @@ -1,47 +1,15 @@ @@ -49,18 +17,13 @@ onMount(loadArticle) - {#if isLoading} -
- -
- {:else if loadError} + {#if data.loadError}

无法加载文章

-

{loadError}

+

{data.loadError}

- {:else if article} - + {:else if data.article} + {/if}
diff --git a/apps/admin/src/routes/(admin)/posts/[id]/+page.ts b/apps/admin/src/routes/(admin)/posts/[id]/+page.ts new file mode 100644 index 0000000..8b8f130 --- /dev/null +++ b/apps/admin/src/routes/(admin)/posts/[id]/+page.ts @@ -0,0 +1,23 @@ +import type { PageLoad } from './$types' + +import { ArticleAPI } from '$lib/api' + +// 文章编辑页初始数据:按路由参数加载文章详情供编辑表单回填。 +// 加载失败不抛错,改以错误文案返回,由页面渲染失败态并给出返回入口。 +export const load: PageLoad = async ({ params }) => { + const articleId = Number(params.id) + if (!Number.isFinite(articleId) || articleId <= 0) { + return { article: null, loadError: '无效的文章标识' } + } + + try { + const response = await ArticleAPI.getById(articleId) + if (response.code === 200 && response.data) { + return { article: response.data, loadError: '' } + } + return { article: null, loadError: response.message || '文章不存在或无权访问' } + } catch (error) { + console.error('加载文章失败:', error) + return { article: null, loadError: '网络错误,请稍后重试' } + } +} diff --git a/apps/admin/src/routes/(admin)/posts/__tests__/posts-page-state.test.ts b/apps/admin/src/routes/(admin)/posts/__tests__/posts-page-state.test.ts new file mode 100644 index 0000000..90c26b0 --- /dev/null +++ b/apps/admin/src/routes/(admin)/posts/__tests__/posts-page-state.test.ts @@ -0,0 +1,294 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import type { Article } from '@myblog/api/modules/article/types' + +import { ARTICLE_PAGE_SIZE } from '$lib/constants/article' + +// 接口与提示均以替身注入,测试只验证页面状态的编排逻辑,不触达网络与界面。 +const articleApiMock = { + list: vi.fn(), + delete: vi.fn(), + publish: vi.fn(), + unpublish: vi.fn(), + archive: vi.fn(), + private: vi.fn() +} + +const toastMock = { + success: vi.fn(), + error: vi.fn() +} + +vi.mock('$lib/api', () => ({ ArticleAPI: articleApiMock })) +vi.mock('svelte-sonner', () => ({ toast: toastMock })) + +const { emptyPostsPageData, postsPageState } = await import('../posts-page-state.svelte') + +// 后端统一响应的成功业务码。 +const SUCCESS_CODE = 200 + +// 搜索防抖时长,与页面状态模块内的取值一致。 +const SEARCH_DEBOUNCE_MS = 300 + +// 构造一篇文章替身,字段取值只覆盖被测逻辑关心的部分。 +function makeArticle(id: number, status = 'draft'): Article { + return { id, title: `文章${id}`, status } as unknown as Article +} + +// 重置替身调用记录与页面状态,避免用例之间互相污染。 +function resetState() { + vi.clearAllMocks() + postsPageState.initialize(emptyPostsPageData()) + postsPageState.search = '' + postsPageState.status = '' + postsPageState.sortBy = 'created_at' + postsPageState.order = 'desc' + postsPageState.currentPage = 1 + postsPageState.isLoading = false +} + +describe('文章管理页状态:初始化', () => { + beforeEach(resetState) + + it('用 load 结果填充列表、总数与权限标记', () => { + const articles = [makeArticle(1), makeArticle(2, 'published')] + + postsPageState.initialize({ articles, total: 2, canManageAllArticles: true }) + + expect(postsPageState.articles).toEqual(articles) + expect(postsPageState.total).toBe(2) + expect(postsPageState.canManageAllArticles).toBe(true) + }) + + it('空数据下无生效筛选条件且总页数至少为 1', () => { + expect(postsPageState.articles).toEqual([]) + expect(postsPageState.canManageAllArticles).toBe(false) + expect(postsPageState.hasActiveFilters).toBe(false) + expect(postsPageState.totalPages).toBe(1) + }) +}) + +describe('文章管理页状态:列表加载', () => { + beforeEach(resetState) + + it('默认携带分页、空状态与默认排序参数', async () => { + articleApiMock.list.mockResolvedValue({ + code: SUCCESS_CODE, + data: { articles: [makeArticle(1)], total: 1 } + }) + + await postsPageState.loadArticles() + + expect(articleApiMock.list).toHaveBeenCalledWith({ + page: 1, + pageSize: ARTICLE_PAGE_SIZE, + status: '', + sortBy: 'created_at', + order: 'desc' + }) + expect(postsPageState.articles).toHaveLength(1) + expect(postsPageState.total).toBe(1) + }) + + it('搜索词去除首尾空白后作为查询条件', async () => { + articleApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: { articles: [], total: 0 } }) + postsPageState.search = ' 博客 ' + postsPageState.status = 'published' + + await postsPageState.loadArticles() + + expect(articleApiMock.list).toHaveBeenCalledWith({ + page: 1, + pageSize: ARTICLE_PAGE_SIZE, + status: 'published', + sortBy: 'created_at', + order: 'desc', + search: '博客' + }) + }) + + it('搜索词为纯空白时不携带查询条件', async () => { + articleApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: { articles: [], total: 0 } }) + postsPageState.search = ' ' + + await postsPageState.loadArticles() + + expect(articleApiMock.list).toHaveBeenCalledWith({ + page: 1, + pageSize: ARTICLE_PAGE_SIZE, + status: '', + sortBy: 'created_at', + order: 'desc' + }) + }) + + it('业务码非成功时提示后端文案且不清空现有列表', async () => { + articleApiMock.list.mockResolvedValue({ code: 500, message: '查询失败' }) + postsPageState.initialize({ + articles: [makeArticle(1)], + total: 1, + canManageAllArticles: false + }) + + await postsPageState.loadArticles() + + expect(toastMock.error).toHaveBeenCalledWith('查询失败') + expect(postsPageState.articles).toHaveLength(1) + expect(postsPageState.isLoading).toBe(false) + }) + + it('请求抛错时提示网络错误并复位加载态', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + articleApiMock.list.mockRejectedValue(new Error('断网')) + + await postsPageState.loadArticles() + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(postsPageState.isLoading).toBe(false) + consoleError.mockRestore() + }) +}) + +describe('文章管理页状态:筛选与分页', () => { + beforeEach(resetState) + + it('筛选变更后回到第一页并重新加载', async () => { + articleApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: { articles: [], total: 0 } }) + postsPageState.currentPage = 4 + + postsPageState.applyFilterChange() + + expect(postsPageState.currentPage).toBe(1) + await vi.waitFor(() => expect(articleApiMock.list).toHaveBeenCalledTimes(1)) + }) + + it('重置筛选清空全部条件并回到第一页', async () => { + articleApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: { articles: [], total: 0 } }) + postsPageState.search = '博客' + postsPageState.status = 'archived' + postsPageState.sortBy = 'view_count' + postsPageState.order = 'asc' + postsPageState.currentPage = 5 + + postsPageState.resetFilters() + + expect(postsPageState.search).toBe('') + expect(postsPageState.status).toBe('') + expect(postsPageState.sortBy).toBe('created_at') + expect(postsPageState.order).toBe('desc') + expect(postsPageState.currentPage).toBe(1) + expect(postsPageState.hasActiveFilters).toBe(false) + await vi.waitFor(() => expect(articleApiMock.list).toHaveBeenCalledTimes(1)) + }) + + it('切换页码后按目标页加载', async () => { + articleApiMock.list.mockResolvedValue({ + code: SUCCESS_CODE, + data: { articles: [], total: ARTICLE_PAGE_SIZE * 5 } + }) + + postsPageState.changePage(2) + + await vi.waitFor(() => + expect(articleApiMock.list).toHaveBeenCalledWith({ + page: 2, + pageSize: ARTICLE_PAGE_SIZE, + status: '', + sortBy: 'created_at', + order: 'desc' + }) + ) + expect(postsPageState.totalPages).toBe(5) + }) +}) + +describe('文章管理页状态:搜索防抖', () => { + beforeEach(() => { + resetState() + vi.useFakeTimers() + }) + + afterEach(() => { + vi.useRealTimers() + }) + + // 连续输入必须在停顿后只请求一次,且回到第一页,避免翻页后搜索命中空页。 + it('连续输入只在停顿后触发一次请求并回到第一页', () => { + articleApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: { articles: [], total: 0 } }) + postsPageState.currentPage = 3 + + postsPageState.applySearchDebounced() + postsPageState.applySearchDebounced() + expect(articleApiMock.list).not.toHaveBeenCalled() + + vi.advanceTimersByTime(SEARCH_DEBOUNCE_MS) + + expect(articleApiMock.list).toHaveBeenCalledTimes(1) + expect(postsPageState.currentPage).toBe(1) + }) +}) + +describe('文章管理页状态:状态流转与删除', () => { + beforeEach(resetState) + + it('状态流转成功后提示后端消息并刷新列表', async () => { + articleApiMock.publish.mockResolvedValue({ + code: SUCCESS_CODE, + data: { message: '文章已发布' } + }) + articleApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: { articles: [], total: 0 } }) + + await postsPageState.applyStatusAction(makeArticle(1), 'publish') + + expect(articleApiMock.publish).toHaveBeenCalledWith(1) + expect(toastMock.success).toHaveBeenCalledWith('文章已发布') + expect(articleApiMock.list).toHaveBeenCalledTimes(1) + }) + + it('状态流转缺少业务消息时使用默认提示', async () => { + articleApiMock.archive.mockResolvedValue({ code: SUCCESS_CODE, data: null }) + articleApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: { articles: [], total: 0 } }) + + await postsPageState.applyStatusAction(makeArticle(1), 'archive') + + expect(toastMock.success).toHaveBeenCalledWith('操作成功') + }) + + it('状态流转失败时提示后端文案且不刷新列表', async () => { + articleApiMock.private.mockResolvedValue({ code: 403, message: '无权操作' }) + + await postsPageState.applyStatusAction(makeArticle(1), 'private') + + expect(toastMock.error).toHaveBeenCalledWith('无权操作') + expect(articleApiMock.list).not.toHaveBeenCalled() + }) + + it('状态流转请求抛错时提示网络错误', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + articleApiMock.unpublish.mockRejectedValue(new Error('断网')) + + await postsPageState.applyStatusAction(makeArticle(1, 'published'), 'unpublish') + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + consoleError.mockRestore() + }) + + it('删除成功后提示并刷新列表', async () => { + articleApiMock.delete.mockResolvedValue({ code: SUCCESS_CODE }) + articleApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: { articles: [], total: 0 } }) + + await postsPageState.removeArticle(makeArticle(1)) + + expect(articleApiMock.delete).toHaveBeenCalledWith(1) + expect(toastMock.success).toHaveBeenCalledWith('文章删除成功') + expect(articleApiMock.list).toHaveBeenCalledTimes(1) + }) + + it('删除失败时提示后端文案且不刷新列表', async () => { + articleApiMock.delete.mockResolvedValue({ code: 404, message: '文章不存在' }) + + await postsPageState.removeArticle(makeArticle(1)) + + expect(toastMock.error).toHaveBeenCalledWith('文章不存在') + expect(articleApiMock.list).not.toHaveBeenCalled() + }) +}) diff --git a/apps/admin/src/routes/(admin)/posts/posts-page-state.svelte.ts b/apps/admin/src/routes/(admin)/posts/posts-page-state.svelte.ts new file mode 100644 index 0000000..8946271 --- /dev/null +++ b/apps/admin/src/routes/(admin)/posts/posts-page-state.svelte.ts @@ -0,0 +1,163 @@ +import type { + Article, + ArticleActionResponse, + ArticleStatus +} from '@myblog/api/modules/article/types' +import { ARTICLE_PAGE_SIZE, type ArticleStatusAction } from '$lib/constants/article' +import { debounce } from '@myblog/shared' +import { toast } from 'svelte-sonner' +import { ArticleAPI } from '$lib/api' + +// 网络异常的统一提示文案。 +const NETWORK_ERROR_MESSAGE = '网络错误,请稍后重试' + +// 搜索输入停顿时长,避免每次按键都触发请求。 +const SEARCH_DEBOUNCE_MS = 300 + +// 排序字段以字符串承载空值表示默认排序,与后端 GetArticleListRequest 的 oneof 约束对齐。 +type ArticleSortField = + 'created_at' | 'updated_at' | 'published_at' | 'view_count' | 'like_count' | '' + +// 文章状态操作到接口方法的映射,统一走 /api/articles 端点,权限由后端判定。 +const STATUS_ACTION_METHODS: Record< + ArticleStatusAction, + (id: number) => Promise +> = { + publish: ArticleAPI.publish, + unpublish: ArticleAPI.unpublish, + archive: ArticleAPI.archive, + private: ArticleAPI.private +} + +// 初始页面数据形状,由 +page.ts 的 load 函数提供。 +export interface PostsPageData { + articles: Article[] + total: number + canManageAllArticles: boolean +} + +// 空页面数据,load 失败时使用。 +export function emptyPostsPageData(): PostsPageData { + return { articles: [], total: 0, canManageAllArticles: false } +} + +// 文章管理页状态:集中持有列表、筛选条件与全部读写操作,页面组件只做渲染。 +class PostsPageState { + articles = $state([]) + total = $state(0) + currentPage = $state(1) + search = $state('') + status = $state('') + sortBy = $state('created_at') + order = $state<'asc' | 'desc'>('desc') + // 当前用户是否具备 article:manage 权限,用于控制状态筛选是否可用。 + canManageAllArticles = $state(false) + isLoading = $state(false) + + // 总页数,分页控件与页码文案共用同一口径。 + get totalPages(): number { + return Math.max(1, Math.ceil(this.total / ARTICLE_PAGE_SIZE)) + } + + // 是否存在生效中的搜索与状态筛选,用于空态区分无数据与无匹配。 + get hasActiveFilters(): boolean { + return this.search.trim() !== '' || this.status !== '' + } + + // 用 load 结果初始化页面状态,重复挂载时以最新数据覆盖。 + initialize(data: PostsPageData) { + this.articles = data.articles + this.total = data.total + this.canManageAllArticles = data.canManageAllArticles + } + + // 加载文章列表,携带筛选、排序与分页参数。 + // 管理员可查看全部状态,其他角色由服务端强制只返回已发布文章。 + async loadArticles() { + this.isLoading = true + try { + const response = await ArticleAPI.list({ + page: this.currentPage, + pageSize: ARTICLE_PAGE_SIZE, + status: this.status, + sortBy: this.sortBy, + order: this.order, + ...(this.search.trim() ? { search: this.search.trim() } : {}) + }) + if (response.code === 200 && response.data) { + this.articles = response.data.articles ?? [] + this.total = response.data.total ?? 0 + } else { + toast.error(response.message || '加载文章列表失败') + } + } catch (error) { + console.error('加载文章列表失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + this.isLoading = false + } + } + + // 搜索词防抖应用,连续输入只在停顿后请求一次。 + applySearchDebounced = debounce(() => { + this.currentPage = 1 + void this.loadArticles() + }, SEARCH_DEBOUNCE_MS) + + // 状态、排序字段与排序方向变更后回到第一页并重新加载。 + applyFilterChange() { + this.currentPage = 1 + void this.loadArticles() + } + + // 重置全部筛选条件后重新加载。 + resetFilters() { + this.search = '' + this.status = '' + this.sortBy = 'created_at' + this.order = 'desc' + this.currentPage = 1 + void this.loadArticles() + } + + // 切换页码并重新加载。 + changePage(page: number) { + this.currentPage = page + void this.loadArticles() + } + + // 执行文章状态流转并提示结果,成功后刷新当前页。 + async applyStatusAction(article: Article, action: ArticleStatusAction) { + try { + const response = await STATUS_ACTION_METHODS[action](article.id) + if (response.code === 200) { + toast.success(response.data?.message || '操作成功') + await this.loadArticles() + } else { + toast.error(response.message || '操作失败') + } + } catch (error) { + console.error('文章状态操作失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + } + + // 删除文章,由表格组件确认后触发,成功后刷新当前页。 + async removeArticle(article: Article) { + try { + const response = await ArticleAPI.delete(article.id) + if (response.code === 200) { + toast.success('文章删除成功') + await this.loadArticles() + } else { + toast.error(response.message || '删除文章失败') + } + } catch (error) { + console.error('删除文章失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } + } +} + +// 页面级共享状态实例。 +export const postsPageState = new PostsPageState() diff --git a/apps/admin/src/routes/(admin)/settings/+page.svelte b/apps/admin/src/routes/(admin)/settings/+page.svelte index ec288d7..0f4909e 100644 --- a/apps/admin/src/routes/(admin)/settings/+page.svelte +++ b/apps/admin/src/routes/(admin)/settings/+page.svelte @@ -1,101 +1,25 @@ @@ -108,18 +32,20 @@ onMount(loadSettings) crumb="系统设置" > {#snippet actions()} - {/snippet} - {#if isLoading} + {#if settingsPageState.isLoading}
- +
- {:else if settings.length === 0} + {:else if settingsPageState.settings.length === 0}
@@ -131,7 +57,7 @@ onMount(loadSettings)
{:else}
- {#each groupSettings() as group, index (group.groupName)} + {#each settingsPageState.groups as group, index (group.groupName)} {SETTING_GROUP_LABELS[group.groupName] ?? group.groupName} @@ -146,15 +72,14 @@ onMount(loadSettings) {#each group.items as setting (setting.keyName)} { - values[setting.keyName] = nextValue - }} + value={settingsPageState.values[setting.keyName] ?? ''} + onValueChange={(nextValue: string) => + settingsPageState.setValue(setting.keyName, nextValue)} /> {/each}
- {#if index < groupSettings().length - 1} + {#if index < settingsPageState.groups.length - 1} {/if} diff --git a/apps/admin/src/routes/(admin)/settings/+page.ts b/apps/admin/src/routes/(admin)/settings/+page.ts new file mode 100644 index 0000000..e535b35 --- /dev/null +++ b/apps/admin/src/routes/(admin)/settings/+page.ts @@ -0,0 +1,21 @@ +import type { PageLoad } from './$types' + +import { emptySettingsPageData } from './settings-page-state.svelte' +import { SettingAPI } from '$lib/api' + +// 系统设置页初始数据:首屏加载全部设置项。 +// 加载失败不抛错,回退空数据并由页面状态模块在后续交互中继续提示。 +export const load: PageLoad = async () => { + const pageData = emptySettingsPageData() + try { + const response = await SettingAPI.list() + if (response.code === 200 && response.data) { + pageData.settings = response.data.settings ?? [] + } else { + console.error('加载设置失败:', response.message) + } + } catch (error) { + console.error('加载设置失败:', error) + } + return pageData +} diff --git a/apps/admin/src/routes/(admin)/settings/__tests__/settings-page-state.test.ts b/apps/admin/src/routes/(admin)/settings/__tests__/settings-page-state.test.ts new file mode 100644 index 0000000..69e0362 --- /dev/null +++ b/apps/admin/src/routes/(admin)/settings/__tests__/settings-page-state.test.ts @@ -0,0 +1,237 @@ +import type { Setting } from '@myblog/api/modules/setting/types' +import { beforeEach, describe, expect, it, vi } from 'vitest' + +// 接口与提示均以替身注入,测试只验证页面状态的编排逻辑,不触达网络与界面。 +const settingApiMock = { + list: vi.fn(), + update: vi.fn() +} + +const toastMock = { + success: vi.fn(), + error: vi.fn(), + info: vi.fn() +} + +vi.mock('$lib/api', () => ({ SettingAPI: settingApiMock })) +vi.mock('svelte-sonner', () => ({ toast: toastMock })) + +const { emptySettingsPageData, settingsPageState } = await import('../settings-page-state.svelte') + +// 后端统一响应的成功业务码。 +const SUCCESS_CODE = 200 + +// 构造一个设置项替身,字段取值只覆盖被测逻辑关心的部分。 +function makeSetting(keyName: string, value: string, groupName = 'site'): Setting { + return { + keyName, + value, + label: keyName, + defaultValue: '', + description: '', + type: 'string', + groupName, + isPublic: false, + isReadonly: false, + isSensitive: false, + validationRule: '', + sortOrder: 0 + } as unknown as Setting +} + +// 重置替身调用记录与页面状态,避免用例之间互相污染。 +function resetState() { + vi.clearAllMocks() + settingsPageState.initialize(emptySettingsPageData()) + settingsPageState.isLoading = false + settingsPageState.isSaving = false +} + +describe('系统设置页状态:初始化', () => { + beforeEach(resetState) + + it('用 load 结果展开表单当前值与初值', () => { + const settings = [makeSetting('site_title', '我的博客'), makeSetting('site_desc', '简介')] + + settingsPageState.initialize({ settings }) + + expect(settingsPageState.settings).toEqual(settings) + expect(settingsPageState.values).toEqual({ site_title: '我的博客', site_desc: '简介' }) + expect(settingsPageState.originalValues).toEqual({ + site_title: '我的博客', + site_desc: '简介' + }) + }) + + it('初值与当前值互不共享引用', () => { + settingsPageState.initialize({ settings: [makeSetting('site_title', '我的博客')] }) + + settingsPageState.setValue('site_title', '新标题') + + expect(settingsPageState.values.site_title).toBe('新标题') + expect(settingsPageState.originalValues.site_title).toBe('我的博客') + }) + + it('空数据下不产生分组与改动项', () => { + expect(settingsPageState.groups).toEqual([]) + expect(settingsPageState.collectChangedItems()).toEqual([]) + expect(settingsPageState.isLoading).toBe(false) + expect(settingsPageState.isSaving).toBe(false) + }) +}) + +describe('系统设置页状态:分组', () => { + beforeEach(resetState) + + it('按分组名聚合设置项并保持原始顺序', () => { + settingsPageState.initialize({ + settings: [ + makeSetting('site_title', '标题', 'site'), + makeSetting('sec_token', '令牌', 'security'), + makeSetting('site_desc', '简介', 'site') + ] + }) + + const groups = settingsPageState.groups + + expect(groups.map(group => group.groupName)).toEqual(['site', 'security']) + expect(groups[0]?.items.map(item => item.keyName)).toEqual(['site_title', 'site_desc']) + expect(groups[1]?.items.map(item => item.keyName)).toEqual(['sec_token']) + }) +}) + +describe('系统设置页状态:改动汇总', () => { + beforeEach(resetState) + + it('只汇总取值发生变化的设置项', () => { + settingsPageState.initialize({ + settings: [makeSetting('site_title', '标题'), makeSetting('site_desc', '简介')] + }) + + settingsPageState.setValue('site_desc', '新简介') + + expect(settingsPageState.collectChangedItems()).toEqual([ + { keyName: 'site_desc', value: '新简介' } + ]) + }) + + it('值被改回初值后不再计入改动', () => { + settingsPageState.initialize({ settings: [makeSetting('site_title', '标题')] }) + + settingsPageState.setValue('site_title', '临时值') + settingsPageState.setValue('site_title', '标题') + + expect(settingsPageState.collectChangedItems()).toEqual([]) + }) +}) + +describe('系统设置页状态:保存', () => { + beforeEach(resetState) + + it('没有改动时仅提示且不发起请求', async () => { + settingsPageState.initialize({ settings: [makeSetting('site_title', '标题')] }) + + await settingsPageState.saveSettings() + + expect(settingApiMock.update).not.toHaveBeenCalled() + expect(toastMock.info).toHaveBeenCalledWith('没有需要保存的修改') + }) + + it('保存成功后提示改动条数并重新加载', async () => { + settingApiMock.update.mockResolvedValue({ code: SUCCESS_CODE, data: { settings: [] } }) + settingApiMock.list.mockResolvedValue({ + code: SUCCESS_CODE, + data: { settings: [makeSetting('site_title', '新标题')] } + }) + settingsPageState.initialize({ settings: [makeSetting('site_title', '标题')] }) + settingsPageState.setValue('site_title', '新标题') + + await settingsPageState.saveSettings() + + expect(settingApiMock.update).toHaveBeenCalledWith({ + items: [{ keyName: 'site_title', value: '新标题' }] + }) + expect(toastMock.success).toHaveBeenCalledWith('已保存 1 项设置') + expect(settingApiMock.list).toHaveBeenCalledTimes(1) + expect(settingsPageState.values.site_title).toBe('新标题') + expect(settingsPageState.isSaving).toBe(false) + }) + + it('保存进行中重复提交不发起第二次请求', async () => { + settingApiMock.update.mockResolvedValue({ code: SUCCESS_CODE, data: { settings: [] } }) + settingApiMock.list.mockResolvedValue({ code: SUCCESS_CODE, data: { settings: [] } }) + settingsPageState.initialize({ settings: [makeSetting('site_title', '标题')] }) + settingsPageState.setValue('site_title', '新标题') + settingsPageState.isSaving = true + + await settingsPageState.saveSettings() + + expect(settingApiMock.update).not.toHaveBeenCalled() + }) + + it('业务码非成功时提示后端文案且保留改动', async () => { + settingApiMock.update.mockResolvedValue({ code: 400, message: '校验未通过' }) + settingsPageState.initialize({ settings: [makeSetting('site_title', '标题')] }) + settingsPageState.setValue('site_title', '新标题') + + await settingsPageState.saveSettings() + + expect(toastMock.error).toHaveBeenCalledWith('校验未通过') + expect(settingsPageState.values.site_title).toBe('新标题') + expect(settingsPageState.originalValues.site_title).toBe('标题') + expect(settingsPageState.isSaving).toBe(false) + }) + + it('请求抛错时提示网络错误并复位保存态', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + settingApiMock.update.mockRejectedValue(new Error('断网')) + settingsPageState.initialize({ settings: [makeSetting('site_title', '标题')] }) + settingsPageState.setValue('site_title', '新标题') + + await settingsPageState.saveSettings() + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(settingsPageState.isSaving).toBe(false) + consoleError.mockRestore() + }) +}) + +describe('系统设置页状态:加载', () => { + beforeEach(resetState) + + it('加载成功重置表单当前值与初值', async () => { + settingApiMock.list.mockResolvedValue({ + code: SUCCESS_CODE, + data: { settings: [makeSetting('site_title', '服务端标题')] } + }) + + await settingsPageState.loadSettings() + + expect(settingsPageState.settings).toHaveLength(1) + expect(settingsPageState.values).toEqual({ site_title: '服务端标题' }) + expect(settingsPageState.originalValues).toEqual({ site_title: '服务端标题' }) + expect(settingsPageState.isLoading).toBe(false) + }) + + it('加载失败时提示后端文案且不改动现有表单', async () => { + settingApiMock.list.mockResolvedValue({ code: 500, message: '查询失败' }) + settingsPageState.initialize({ settings: [makeSetting('site_title', '标题')] }) + + await settingsPageState.loadSettings() + + expect(toastMock.error).toHaveBeenCalledWith('查询失败') + expect(settingsPageState.values).toEqual({ site_title: '标题' }) + expect(settingsPageState.isLoading).toBe(false) + }) + + it('请求抛错时提示网络错误并复位加载态', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + settingApiMock.list.mockRejectedValue(new Error('断网')) + + await settingsPageState.loadSettings() + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(settingsPageState.isLoading).toBe(false) + consoleError.mockRestore() + }) +}) diff --git a/apps/admin/src/routes/(admin)/settings/settings-page-state.svelte.ts b/apps/admin/src/routes/(admin)/settings/settings-page-state.svelte.ts new file mode 100644 index 0000000..d3f7848 --- /dev/null +++ b/apps/admin/src/routes/(admin)/settings/settings-page-state.svelte.ts @@ -0,0 +1,119 @@ +import type { Setting, UpdateSettingItem } from '@myblog/api/modules/setting/types' +import { toast } from 'svelte-sonner' +import { SettingAPI } from '$lib/api' + +// 网络异常的统一提示文案。 +const NETWORK_ERROR_MESSAGE = '网络错误,请稍后重试' + +// 初始页面数据形状,由 +page.ts 的 load 函数提供。 +export interface SettingsPageData { + settings: Setting[] +} + +// 空页面数据,load 失败时使用。 +export function emptySettingsPageData(): SettingsPageData { + return { settings: [] } +} + +// 按 keyName 展开设置项键值,表单初值与当前值共用同一口径。 +function collectValues(settings: Setting[]): Record { + const values: Record = {} + for (const setting of settings) { + values[setting.keyName] = setting.value + } + return values +} + +// 设置项分组,分组名与成员按设置项的原始顺序聚合。 +interface SettingGroup { + groupName: string + items: Setting[] +} + +// 系统设置页状态:集中持有设置项、表单值与全部读写操作,页面组件只做渲染。 +class SettingsPageState { + settings = $state([]) + values = $state>({}) + originalValues = $state>({}) + isLoading = $state(false) + isSaving = $state(false) + + // 按分组名聚合设置项并保持原始顺序。 + get groups(): SettingGroup[] { + const groups: Record = {} + for (const setting of this.settings) { + const group = groups[setting.groupName] ?? [] + group.push(setting) + groups[setting.groupName] = group + } + return Object.entries(groups).map(([groupName, items]) => ({ groupName, items })) + } + + // 用设置项初始化页面状态,表单当前值与初值同时归位。 + initialize(data: SettingsPageData) { + this.settings = data.settings + const values = collectValues(data.settings) + this.values = { ...values } + this.originalValues = values + } + + // 记录单个设置项的编辑值。 + setValue(keyName: string, value: string) { + this.values[keyName] = value + } + + // 加载全部设置项并重置表单当前值与初值。 + async loadSettings() { + this.isLoading = true + try { + const response = await SettingAPI.list() + if (response.code === 200 && response.data) { + this.initialize({ settings: response.data.settings ?? [] }) + } else { + toast.error(response.message || '加载设置失败') + } + } catch (error) { + console.error('加载设置失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + this.isLoading = false + } + } + + // 汇总有改动的设置项,敏感掩码未改动时不会进入提交载荷。 + collectChangedItems(): UpdateSettingItem[] { + return Object.keys(this.values) + .filter(keyName => this.originalValues[keyName] !== this.values[keyName]) + .map(keyName => ({ keyName, value: this.values[keyName] ?? '' })) + } + + // 批量保存有改动的设置项,成功后重新加载以对齐服务端值。 + async saveSettings() { + if (this.isSaving) return + + const items = this.collectChangedItems() + if (items.length === 0) { + toast.info('没有需要保存的修改') + return + } + + this.isSaving = true + try { + const response = await SettingAPI.update({ items }) + if (response.code === 200 && response.data) { + toast.success(`已保存 ${items.length} 项设置`) + await this.loadSettings() + } else { + toast.error(response.message || '保存设置失败') + } + } catch (error) { + console.error('保存设置失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + this.isSaving = false + } + } +} + +// 页面级共享状态实例。 +export const settingsPageState = new SettingsPageState() diff --git a/apps/admin/src/routes/(admin)/stats/+page.svelte b/apps/admin/src/routes/(admin)/stats/+page.svelte index b5c29ed..5803e1c 100644 --- a/apps/admin/src/routes/(admin)/stats/+page.svelte +++ b/apps/admin/src/routes/(admin)/stats/+page.svelte @@ -1,13 +1,14 @@ @@ -68,10 +38,9 @@ onMount(loadStats) - {#if isLoading && !overview} + {#if statsPageState.isLoading && !statsPageState.overview}
- +
{:else}
@@ -84,7 +53,7 @@ onMount(loadStats)
- {overview ? overview[card.key] : '—'} + {statsPageState.overview ? statsPageState.overview[card.key] : '—'}
@@ -100,19 +69,19 @@ onMount(loadStats)
statsPageState.setTrendDays(value)} variant="outline" size="sm" > - 7 天 - 14 天 - 30 天 + {#each TREND_DAY_OPTIONS as days (days)} + {days} 天 + {/each}
- + {/if} diff --git a/apps/admin/src/routes/(admin)/stats/+page.ts b/apps/admin/src/routes/(admin)/stats/+page.ts new file mode 100644 index 0000000..fa07cff --- /dev/null +++ b/apps/admin/src/routes/(admin)/stats/+page.ts @@ -0,0 +1,31 @@ +import type { PageLoad } from './$types' + +import { emptyStatsPageData } from './stats-page-state.svelte' +import { DEFAULT_TREND_DAYS } from '$lib/constants/stats' +import { StatsAPI } from '$lib/api' + +// 站点统计页初始数据:首屏并行加载概览与默认天数的浏览量趋势。 +// 加载失败不抛错,回退空数据并由页面状态模块在后续交互中继续提示。 +export const load: PageLoad = async () => { + const pageData = emptyStatsPageData() + + const [overviewResult, trendResult] = await Promise.allSettled([ + StatsAPI.getOverview(), + StatsAPI.getArticleViewsTrend(Number(DEFAULT_TREND_DAYS)) + ]) + + if (overviewResult.status === 'fulfilled' && overviewResult.value.code === 200) { + pageData.overview = overviewResult.value.data ?? null + } else if (overviewResult.status === 'rejected') { + console.error('加载统计概览失败:', overviewResult.reason) + } + + if (trendResult.status === 'fulfilled' && trendResult.value.code === 200) { + pageData.trendDates = trendResult.value.data?.dates ?? [] + pageData.trendValues = trendResult.value.data?.values ?? [] + } else if (trendResult.status === 'rejected') { + console.error('加载浏览量趋势失败:', trendResult.reason) + } + + return pageData +} diff --git a/apps/admin/src/routes/(admin)/stats/__tests__/stats-page-state.test.ts b/apps/admin/src/routes/(admin)/stats/__tests__/stats-page-state.test.ts new file mode 100644 index 0000000..b15b73c --- /dev/null +++ b/apps/admin/src/routes/(admin)/stats/__tests__/stats-page-state.test.ts @@ -0,0 +1,138 @@ +import type { StatsOverview } from '@myblog/api/modules/stats/types' +import { beforeEach, describe, expect, it, vi } from 'vitest' + +import { DEFAULT_TREND_DAYS } from '$lib/constants/stats' + +// 接口与提示均以替身注入,测试只验证页面状态的编排逻辑,不触达网络与界面。 +const statsApiMock = { + getOverview: vi.fn(), + getArticleViewsTrend: vi.fn() +} + +const toastMock = { + error: vi.fn() +} + +vi.mock('$lib/api', () => ({ StatsAPI: statsApiMock })) +vi.mock('svelte-sonner', () => ({ toast: toastMock })) + +const { emptyStatsPageData, statsPageState } = await import('../stats-page-state.svelte') + +// 后端统一响应的成功业务码。 +const SUCCESS_CODE = 200 + +// 构造统计概览替身,字段取值只覆盖被测逻辑关心的部分。 +function makeOverview(articleCount = 3): StatsOverview { + return { articleCount } as unknown as StatsOverview +} + +// 重置替身调用记录与页面状态,避免用例之间互相污染。 +function resetState() { + vi.clearAllMocks() + statsPageState.initialize(emptyStatsPageData()) + statsPageState.trendDays = DEFAULT_TREND_DAYS + statsPageState.isLoading = false +} + +describe('站点统计页状态:初始化', () => { + beforeEach(resetState) + + it('用 load 结果填充概览与趋势数据', () => { + const overview = makeOverview(8) + + statsPageState.initialize({ overview, trendDates: ['2026-01-01'], trendValues: [12] }) + + expect(statsPageState.overview).toEqual(overview) + expect(statsPageState.trendDates).toEqual(['2026-01-01']) + expect(statsPageState.trendValues).toEqual([12]) + }) + + it('空数据下概览为空且趋势天数取默认值', () => { + expect(statsPageState.overview).toBeNull() + expect(statsPageState.trendDays).toBe(DEFAULT_TREND_DAYS) + expect(statsPageState.isLoading).toBe(false) + }) +}) + +describe('站点统计页状态:加载', () => { + beforeEach(resetState) + + it('概览与趋势按当前天数并行取数', async () => { + statsApiMock.getOverview.mockResolvedValue({ code: SUCCESS_CODE, data: makeOverview() }) + statsApiMock.getArticleViewsTrend.mockResolvedValue({ + code: SUCCESS_CODE, + data: { dates: [], values: [] } + }) + + await statsPageState.loadStats() + + expect(statsApiMock.getOverview).toHaveBeenCalledTimes(1) + expect(statsApiMock.getArticleViewsTrend).toHaveBeenCalledWith(Number(DEFAULT_TREND_DAYS)) + }) + + it('加载成功更新概览与趋势数据', async () => { + statsApiMock.getOverview.mockResolvedValue({ code: SUCCESS_CODE, data: makeOverview(9) }) + statsApiMock.getArticleViewsTrend.mockResolvedValue({ + code: SUCCESS_CODE, + data: { dates: ['2026-01-01'], values: [5] } + }) + + await statsPageState.loadStats() + + expect(statsPageState.overview?.articleCount).toBe(9) + expect(statsPageState.trendDates).toEqual(['2026-01-01']) + expect(statsPageState.trendValues).toEqual([5]) + expect(statsPageState.isLoading).toBe(false) + }) + + it('趋势响应缺失字段时按空数组处理', async () => { + statsApiMock.getOverview.mockResolvedValue({ code: SUCCESS_CODE, data: makeOverview() }) + statsApiMock.getArticleViewsTrend.mockResolvedValue({ code: SUCCESS_CODE, data: {} }) + + await statsPageState.loadStats() + + expect(statsPageState.trendDates).toEqual([]) + expect(statsPageState.trendValues).toEqual([]) + }) + + it('业务码非成功时保留现有数据且不提示', async () => { + statsApiMock.getOverview.mockResolvedValue({ code: 500, message: '查询失败' }) + statsApiMock.getArticleViewsTrend.mockResolvedValue({ code: 500, message: '查询失败' }) + statsPageState.initialize({ overview: makeOverview(2), trendDates: ['d'], trendValues: [1] }) + + await statsPageState.loadStats() + + expect(statsPageState.overview?.articleCount).toBe(2) + expect(statsPageState.trendDates).toEqual(['d']) + expect(toastMock.error).not.toHaveBeenCalled() + }) + + it('请求抛错时提示网络错误并复位加载态', async () => { + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}) + statsApiMock.getOverview.mockRejectedValue(new Error('断网')) + statsApiMock.getArticleViewsTrend.mockRejectedValue(new Error('断网')) + + await statsPageState.loadStats() + + expect(toastMock.error).toHaveBeenCalledWith('网络错误,请稍后重试') + expect(statsPageState.isLoading).toBe(false) + consoleError.mockRestore() + }) +}) + +describe('站点统计页状态:趋势天数切换', () => { + beforeEach(resetState) + + it('切换天数后按新天数重新加载', async () => { + statsApiMock.getOverview.mockResolvedValue({ code: SUCCESS_CODE, data: makeOverview() }) + statsApiMock.getArticleViewsTrend.mockResolvedValue({ + code: SUCCESS_CODE, + data: { dates: [], values: [] } + }) + + statsPageState.setTrendDays('30') + + expect(statsPageState.trendDays).toBe('30') + await vi.waitFor(() => expect(statsApiMock.getArticleViewsTrend).toHaveBeenCalledWith(30)) + }) +}) diff --git a/apps/admin/src/routes/(admin)/stats/stats-page-state.svelte.ts b/apps/admin/src/routes/(admin)/stats/stats-page-state.svelte.ts new file mode 100644 index 0000000..d6a226b --- /dev/null +++ b/apps/admin/src/routes/(admin)/stats/stats-page-state.svelte.ts @@ -0,0 +1,68 @@ +import type { StatsOverview } from '@myblog/api/modules/stats/types' +import { DEFAULT_TREND_DAYS } from '$lib/constants/stats' +import { toast } from 'svelte-sonner' +import { StatsAPI } from '$lib/api' + +// 网络异常的统一提示文案。 +const NETWORK_ERROR_MESSAGE = '网络错误,请稍后重试' + +// 初始页面数据形状,由 +page.ts 的 load 函数提供。 +export interface StatsPageData { + overview: StatsOverview | null + trendDates: string[] + trendValues: number[] +} + +// 空页面数据,load 失败时使用。 +export function emptyStatsPageData(): StatsPageData { + return { overview: null, trendDates: [], trendValues: [] } +} + +// 站点统计页状态:集中持有概览、趋势数据与全部读写操作,页面组件只做渲染。 +class StatsPageState { + overview = $state(null) + isLoading = $state(false) + // 趋势天数以字符串承载,适配 ToggleGroup 的字符串值约束。 + trendDays = $state(DEFAULT_TREND_DAYS) + trendDates = $state([]) + trendValues = $state([]) + + // 用 load 结果初始化页面状态,重复挂载时以最新数据覆盖。 + initialize(data: StatsPageData) { + this.overview = data.overview + this.trendDates = data.trendDates + this.trendValues = data.trendValues + } + + // 加载统计概览与浏览量趋势,趋势按当前选择的天数取数。 + async loadStats() { + this.isLoading = true + try { + const [overviewResult, trendResult] = await Promise.all([ + StatsAPI.getOverview(), + StatsAPI.getArticleViewsTrend(Number(this.trendDays)) + ]) + if (overviewResult.code === 200 && overviewResult.data) { + this.overview = overviewResult.data + } + if (trendResult.code === 200 && trendResult.data) { + this.trendDates = trendResult.data.dates ?? [] + this.trendValues = trendResult.data.values ?? [] + } + } catch (error) { + console.error('加载统计数据失败:', error) + toast.error(NETWORK_ERROR_MESSAGE) + } finally { + this.isLoading = false + } + } + + // 趋势天数变更后按新天数重新加载。 + setTrendDays(days: string) { + this.trendDays = days + void this.loadStats() + } +} + +// 页面级共享状态实例。 +export const statsPageState = new StatsPageState() diff --git a/docs/architecture-rules.md b/docs/architecture-rules.md index d9cc98a..8ecffa7 100644 --- a/docs/architecture-rules.md +++ b/docs/architecture-rules.md @@ -214,7 +214,9 @@ git grep -n "NewRBACService()" -- server | 应用 | 新页面强制模式 | 存量处理 | |---|---|---| | web(SSR 路线) | `+page.server.ts`(需 SEO/会话)或 `+page.ts` load | 死 load 已清理,按此模式接入业务 | -| admin(SPA 路线) | 优先 load + `.svelte.ts` 页面状态模块 | 7 个胖组件不强制迁移,触碰时拆分 | +| admin(SPA 路线) | 优先 load + `.svelte.ts` 页面状态模块 | 胖组件 7→0 已清零;13 个页面取数已归位 load | + +`admin` 侧再分两档:含客户端读写操作(列表筛选、分页、增删改)的页面必须配 `-page-state.svelte.ts` 及配套单测;只读页(无客户端读写)由 `+page.ts` 的 load 直出 page data,不建仅转发数据的空转模块。权限裁剪读 `@myblog/auth` 的本地认证状态,load 内禁止调用认证接口。 胖组件判定标准(任一命中即应拆分):单文件 > 300 行;`$state` 声明 > 8 个;组件内直接调用 API 且含增删改多个 handler;组件内含权限判定逻辑。 @@ -279,7 +281,7 @@ git grep -n "replicas" -- docker-compose.yml | 业务错误未归哨兵导致分档退化为 500 | [`debt/architecture.md`](./debt/architecture.md) 第 7 条 | 新增业务错误必须包装哨兵并同步登记契约 | | 两 app 基础设施逐字重复 | [`debt/frontend.md`](./debt/frontend.md) 第 1 条 | 修改任一必须同步另一份 | | admin 认证工具三轨并行 | [`debt/frontend.md`](./debt/frontend.md) 第 2 条 | 禁止新增认证工具文件与双轨回退 | -| admin 胖组件 + onMount 取数 | [`debt/frontend.md`](./debt/frontend.md) 第 3 条 | 新页面禁用 onMount 取数;行数口径已清零,constants 不得引入图标库 | +| admin 胖组件 + onMount 取数 | [`debt/frontend.md`](./debt/frontend.md) 第 3 条 | 新页面禁用 onMount 取数;行数与取数口径均已清零,constants 不得引入图标库 | | web 首页 load 死代码 | [`debt/frontend.md`](./debt/frontend.md) 第 4 条 | 新页面禁用 load 调认证接口 | | 401 文案匹配 | [`debt/frontend.md`](./debt/frontend.md) 第 5 条 | 禁止回退文案匹配 | | admin 重写 `$ui` 已有组件(含 web 分页例外) | [`debt/frontend.md`](./debt/frontend.md) 第 6 条 | 新分页一律 `$ui`,禁止新增第三处实现 | @@ -303,7 +305,7 @@ git grep -n "replicas" -- docker-compose.yml | 阶段一 结构归位与错误分档 | 删 router 重复接口与不可达代码;错误分档(哨兵错误→404/403/400);令牌表加锁;web 死 load 清理;建立 `contracts/` 目录 | router 重复接口、web 死 load、401 判定均已修复;令牌表已加锁;`RBACService` 生产实例化点仅 1 处;not-found 哨兵→404 已落地,403/400 随错误码契约落地;全部业务错误归哨兵完成,认证失败经 `ErrUnauthenticated`→401,handler 私有映射分支清零 | ✅ 项目自检命令(后端 build/vet/test、两应用类型检查、lint 与 format)全绿 | | 阶段二 类型归位 | 建立 `internal/domain`,合并双 User,service/middleware/router 签名切换为 domain 类型;前端 auth 下沉共享包、影子类型清除 | 双 User 模型与影子类型层已修复;两 app 重复代码大幅减少(auth store 下沉);service 层 repository 依赖由 12 降至 11 | ✅ 依赖方向基线下降;auth store diff 为零 | | 阶段三 契约切换 | handler DTO 分离;`contracts/` + 三把锁双向锚定(替代 codegen);401 改错误码判定 | 401 文案匹配与审计字段泄漏已修复;三把锁已落地(`pnpm run contract:check`) | ✅ 影子类型归零;漂移必当天变红 | -| 阶段四 横切归位与权限下发 | 中间件坍缩为 IdentityProvider 策略;组合根按域装配;RBAC 权限表迁数据源并下发;admin 胖组件拆分、users 搜索推回后端 | `RBACService` 生产实例化点仅 1 处;users 跨页补偿与 admin 分页均已修复;RBAC 迁 config.yaml 完成;permissions 下发完成;follow API 模块已补齐;IdentityProvider 中间件坍缩完成(router 依赖 repository 归零、middleware 1 处);认证工具已统一;admin 胖组件行数口径 7→0,7 个页面取数归位到 load + 页面状态模块 | 权限定义全栈唯一;认证工具单轨 ✅ | +| 阶段四 横切归位与权限下发 | 中间件坍缩为 IdentityProvider 策略;组合根按域装配;RBAC 权限表迁数据源并下发;admin 胖组件拆分、users 搜索推回后端 | `RBACService` 生产实例化点仅 1 处;users 跨页补偿与 admin 分页均已修复;RBAC 迁 config.yaml 完成;permissions 下发完成;follow API 模块已补齐;IdentityProvider 中间件坍缩完成(router 依赖 repository 归零、middleware 1 处);认证工具已统一;admin 胖组件行数口径 7→0,13 个页面取数归位到 load(含 11 个页面状态模块与配套单测),取数口径 6→0,`onMount` 仅余鉴权 2 处 | 权限定义全栈唯一;认证工具单轨 ✅;admin 行数与取数两条基线均归零 ✅ | | 阶段五 扩展点 | 后端 ContentRenderer 内容策略接口(当前 `pkg/markdown` 已直接承接 Markdown 渲染,策略接口化待做);web 业务页面已按"公开数据 SSR + 个性化数据客户端补拉"现状接入,token 迁 cookie 已完成 | — | 新文章类型 = 插入实现,非逐层打洞 | --- diff --git a/docs/debt/frontend.md b/docs/debt/frontend.md index b5666c5..7abf28e 100644 --- a/docs/debt/frontend.md +++ b/docs/debt/frontend.md @@ -19,13 +19,15 @@ ## 3. admin 胖组件 + onMount 取数 -- **状态**:存量,行数口径已清零,仅余非胖页面的 onMount 取数。 +- **状态**:已修复,行数口径与取数口径均已清零。 - **基线**: - 行数口径:`apps/admin/src/routes` 下单文件 > 300 行的页面为 **0** 个;修复前为 7 个,降序为 tags 454 / links 405 / users 404 / dicts 344 / comments 332 / media 323 / categories 322。路由 svelte 文件仍为 19 个,新增的 7 个展示组件下沉在 `lib/components/admin//`,不进入该口径。 - - 取数口径:`onMount` 命中 **8** 个路由文件,其中 2 个属鉴权重定向而非取数,不计入:`(admin)/+layout.svelte`、`(auth)/login/+page.svelte`;剩余取数 **6** 个页面为存量:`(admin)/+page.svelte`(仪表盘)、notifications、posts、`posts/[id]`、settings、stats。修复前取数命中 12 个页面。 - - 已按「`+page.ts` 的 load 取首屏 → `-page-state.svelte.ts` 持有列表与全部读写操作 → `+page.svelte` 只做渲染」重构 7 个原胖页面,页面状态模块 7 个(含 dicts 原有)与配套单测 7 个,合计 146 个用例经 `pnpm run test:apps` 门禁。 -- **验证命令**:`git grep -ln "onMount" -- "apps/admin/src/routes"`(应为 8 个文件,鉴权 2 + 取数 6);行数按「`apps/admin/src/routes` 下单文件 > 300 行」统计;在 `apps/admin` 下执行 `pnpm run check && pnpm run test`。 -- **红线**:新页面禁用 onMount 取数,一律 load + 页面状态模块;禁止复制 300 行以上胖组件;后端能力缺口推回后端修复;`lib/constants/*.ts` 不得引入 `@lucide/svelte`,图标映射随其唯一消费者组件声明,否则页面状态模块与单测的编译图会带入图标桶(comments 单测实测由 126 秒降至 5 秒)。 + - 取数口径:`onMount` 命中 **2** 个路由文件,均属鉴权重定向而非取数:`(admin)/+layout.svelte`、`(auth)/login/+page.svelte`。取数命中已归零;修复前为 12 个页面,本轮前余 6 个(仪表盘、notifications、posts、`posts/[id]`、settings、stats)。 + - 已按「`+page.ts` 的 load 取首屏 → `-page-state.svelte.ts` 持有列表与全部读写操作 → `+page.svelte` 只做渲染」重构 13 个页面:7 个原胖页面(tags / links / users / dicts / comments / media / categories),加本轮 6 个(仪表盘、notifications、posts、`posts/[id]`、settings、stats)。页面状态模块 **11** 个与配套单测 **11** 个,模块用例 **196** 个;`pnpm run test:apps` 下 admin 全量 13 个测试文件、203 个用例通过。 + - 本轮 6 页合计由 996 行降至 596 行。其中仪表盘与 `posts/[id]` 为只读页,无客户端读写操作,由 load 直出 page data,不建空转状态模块;`stats` 页趋势天数与选项新增 `lib/constants/stats.ts` 承载,不再散落字面量。 + - 权限裁剪依赖的登录态在 `@myblog/auth` 的 store 创建时同步水合,故 `+page.ts` 可读 `authStore.getCurrentState()` 裁决区块可见性,load 内不调用认证接口。 +- **验证命令**:`git grep -ln "onMount" -- "apps/admin/src/routes"`(应为 2 个文件,均属鉴权);行数按「`apps/admin/src/routes` 下单文件 > 300 行」统计;状态模块与单测按 `*-page-state.svelte.ts` / `*-page-state.test.ts` 计数(应各 11 个);在 `apps/admin` 下执行 `pnpm run check && pnpm run test`。 +- **红线**:新页面禁用 onMount 取数,一律 load 取首屏;含客户端读写操作的页面配 `-page-state.svelte.ts` 与配套单测,只读页可 load 直出 page data;load 内禁止调用认证接口,权限裁剪只读本地认证状态;禁止复制 300 行以上胖组件;后端能力缺口推回后端修复;`lib/constants/*.ts` 不得引入 `@lucide/svelte`,图标映射随其唯一消费者组件声明,否则页面状态模块与单测的编译图会带入图标桶(comments 单测实测由 126 秒降至 5 秒)。 ## 4. web 首页 load 死代码 diff --git a/docs/development.md b/docs/development.md index f17d457..7d01d15 100644 --- a/docs/development.md +++ b/docs/development.md @@ -629,7 +629,7 @@ pnpm run build:web # 构建前端静态文件 ### 6. 可维护性 - **文档更新**: 架构规则变更时按 [`architecture-rules.md`](./architecture-rules.md) 同步规则本体与第 8 节债务索引;债务条目的状态与基线数值按 [`debt/README.md`](./debt/README.md) 的维护纪律更新对应分册,历史分期状态更新第 9 节 -- **自动化测试**: 后端关键逻辑配套 `*_test.go`(service/repository 层已有存量);前端 packages 公共逻辑与页面状态模块应补 `*.test.ts`。应用侧单测经根 `test:apps` 汇聚(`@myblog/web` 覆盖 markdown 渲染守卫、日期格式化与服务端会话 Cookie 转发,`@myblog/admin` 覆盖字典页状态模块),并与 `test:packages` 一样纳入 `pnpm run test` 与 CI。 +- **自动化测试**: 后端关键逻辑配套 `*_test.go`(service/repository 层已有存量);前端 packages 公共逻辑与页面状态模块应补 `*.test.ts`。应用侧单测经根 `test:apps` 汇聚(`@myblog/web` 覆盖 markdown 渲染守卫、日期格式化与服务端会话 Cookie 转发,`@myblog/admin` 覆盖 11 个页面状态模块),并与 `test:packages` 一样纳入 `pnpm run test` 与 CI。 - **测试文件位置**: 前端测试文件不与业务文件同级,一律置于被测模块同级的 `__tests__/` 目录(例如 `apps/admin/src/lib/utils/__tests__/tag-display.test.ts`);跨用例共享的测试替身与夹具置于包内 `src/test/`(例如 `packages/auth/src/test/fixtures.ts`),不放入 `__tests__/`。移动测试文件后须同步修正其相对导入层级,并检查写死测试文件路径的外部锚点(如 `server/internal/handler/fixture_coverage_test.go` 的 TS 锚点常量)。 ## 更多资源