调试与验证
先确认后端接口正确，再排查页面。使用专用开发数据库、Redis 和测试账号；测试命令不会自动保证所有外部资源都已隔离，需要按目标仓库的测试说明准备环境。
日常命令速查
命令在对应组件目录执行。新增模块先运行相关测试，交付前执行仓库要求的完整检查。
| 目录 | 命令 | 用途 |
|---|---|---|
| 后端 | uv run ruff check . | Python 规范检查 |
| 后端 | uv run ruff format --check . | 检查格式，不改写文件 |
| 后端 | uv run pytest | 后端测试；先核对测试资源与 fixture |
| 后端 | uv run alembic current、uv run alembic heads | 比较当前数据库与源码迁移版本 |
| Web | pnpm lint | 代码检查，会自动修复部分问题，运行后审查 diff |
| Web | pnpm typecheck | Vue 与 TypeScript 类型检查 |
| Web | pnpm test | Vitest 测试 |
| Web | pnpm build | 使用 prod 模式构建 |
| 桌面端 | pnpm typecheck、pnpm test、pnpm build | 类型、主进程服务测试与构建 |
临时日志、截图和测试输出放在本地 .local/，不随产品提交。pytest 可用 --basetemp 指定专用临时目录；该目录会被 pytest 清理，只使用为本次测试准备的空目录。
请求排错顺序
- 在浏览器 Network 中检查请求路径、方法、HTTP 状态与响应体。
- 核对当前用户、权限和目标租户，使用
/docs复现同一个请求；不把 token 放进问题反馈或日志。 - 查看后端日志，确认 API 是否到达、Service 是否报错，以及迁移是否完整。
- 接口正确后检查前端类型、响应解包、状态更新和翻译资源。
| 现象 | 优先检查 |
|---|---|
| Web 能打开，请求连接失败或 502 | 后端启动状态、端口、.env.test.local / .env.test 与 Vite 代理 |
| 请求 404 | router 是否在 app/main.py 注册；前缀与请求路径是否一致 |
| 请求 401 | 登录状态、令牌刷新与目标服务；不要靠页面跳过认证 |
| 请求 403 | 接口权限码、启用角色、租户归属及数据范围 |
| 请求 422 | 请求字段、类型、长度与额外字段；读取响应校验详情 |
| 菜单不出现 | 菜单种子已同步、角色已授权、登录权限已刷新 |
| 菜单存在，页面打不开 | 自动路由生成日志、文件路径与菜单 component 映射 |
| 后端成功，页面数据为空 | request 已解包 data，不要重复读取 data.data |
| 提示表或字段不存在 | Alembic 版本、模型导入与目标数据库连接 |
| 页面显示翻译键 | 语言资源合并层级与 App.I18n.Schema |
一个模块的最小验证集
| 范围 | 需要验证 |
|---|---|
| 正常操作 | 创建、刷新、分页及空状态符合约定 |
| 输入 | 空值、长度上限、非法 ID、额外 tenantId 被正确拒绝 |
| 权限 | 普通角色无权限时直接调用接口也被拒绝 |
| 租户与记录范围 | 列表、总数、详情和写入使用同一边界 |
| 事务 | Service 调用后回滚，数据不落库；失败不触发成功反馈 |
| 数据迁移 | 专用数据库上检查升级与回退；保留已有迁移回归 |
| 页面 | 重复提交、快速翻页、失败重试、移动端和深浅主题 |
| 国际化 | 中英文按钮、菜单、校验、错误与空状态 |
需要 AI 工具时，额外验证撤权、过期确认、重复执行和历史结果访问，见业务工具接入。
教程示例的验证范围
文档仓库 tests/test_notes*.py 使用内存 SQLite 验证示例的服务行为，运行方式见便签教程。这些测试不替代目标项目的 PostgreSQL 迁移、HTTP 认证、浏览器和生产构建验证。
交付时将模块源码、迁移、菜单、翻译与相应测试一起提交。发布流程见升级、备份与恢复。