Files

duanshuwen 6245159e7c feat: 添加后台登录验证码、记住密码功能，优化媒体资源与前端规范

- 新增后台登录图形验证码功能，完善登录安全防护
- 新增登录rememberMe参数，控制Refresh Token的会话持久化策略
- 实现OSS私有桶媒体URL自动签名，统一处理图片资源的临时访问签名
- 新增素材库数据库表与上传API，规范媒体资源管理流程
- 统一前端UI图标使用@element-plus/icons-vue，重构布局图标组件
- 登录页新增验证码输入、刷新功能，添加账号记忆与记住密码逻辑
- 更新全套文档，补充API契约、技术决策记录与集成流程说明
- 修复多个业务页面的图标展示问题，新增认证流程相关测试用例

2026-08-27 07:50:59 +08:00

5.3 KiB

Raw Blame History

WonderQ 三端联调流程

本文档定义 WonderQ-Admin 后端、WonderQ-Admin-UI-Vue 管理前端和 WonderQ-MiniAPP 前台的本地启动、联调顺序与接口变更流程。

三端职责

端	目录	职责	主要契约
后端 API	`WonderQ-Admin`	提供 Public API、Admin API、鉴权、数据库、迁移和 seed	`admin-api-requirements.md`、`public-api.md`
管理前端	`WonderQ-Admin-UI-Vue`	管理登录、权限、站点模块、玩法、详情、管家和线索	`admin-api-requirements.md`、`module-config-api.md`、各领域契约
前台 MiniAPP	`WonderQ-MiniAPP`	H5 与微信小程序展示、咨询和线索提交	`public-api.md`

三端所有 JSON 接口还必须遵守 api-response-contract.md：成功业务数据位于 data，失败时 data: null，code 等于 HTTP 状态码。

本地启动顺序

1. 启动后端

首次安装：

Set-Location .\WonderQ-Admin
Copy-Item .env.example .env
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

日常启动：

Set-Location .\WonderQ-Admin
.\.venv\Scripts\Activate.ps1
docker-compose up -d postgres redis
python -m alembic upgrade head
python -m uvicorn app.main:app --host 0.0.0.0 --port 4000 --reload

健康检查：http://localhost:4000/health。

首次空库初始化内容才执行 python -m app.seed；该命令会覆盖初始化站点与媒体内容，已有开发数据时不要重复执行。

2. 启动管理前端

Set-Location .\WonderQ-Admin-UI-Vue
yarn install
yarn dev

访问 http://localhost:5604/admin/。Vite /api 代理默认指向 http://localhost:4000；修改后端地址时，在 .env.local 设置 VITE_API_PROXY_TARGET。

3. 启动 MiniAPP H5

Set-Location .\WonderQ-MiniAPP
yarn install
yarn dev

访问 http://localhost:5173。微信小程序开发构建使用：

yarn dev:mp-weixin

联调检查清单

后端启动后：

GET /health 返回健康状态。
GET /api/public/site-config 返回前台站点配置。
GET /api/admin/auth/captcha 返回图形验证码和短时 captchaId。
POST /api/admin/auth/login 携带 captchaId、captchaCode 和可选 rememberMe 后返回统一包裹的登录结果；验证码错误或过期后重新获取。
管理端登录后依次读取 /api/admin/system/profile 和 /api/admin/system/routers；后者按当前管理员权限提供动态导航树。
所有成功响应包含数字 code、msg: "success" 和 data；失败响应的 data 必须为 null。

管理端重点检查：

登录后请求带 Authorization: Bearer <access-token>，Refresh Token 只通过 HttpOnly Cookie 传递。
登录页应展示验证码图片，点击图片可刷新；验证码失败后自动刷新，不能在前端缓存或记录验证码答案。
“记住密码”只控制 Refresh Token Cookie 是否持久化；前端最多记住账号和勾选偏好，不得保存明文密码。
动态路由只注册 /api/admin/system/routers 返回的页面菜单；目录用于组织层级，按钮只用于按钮权限，不注册为页面。
管理端界面图标统一由 @element-plus/icons-vue 提供；菜单返回的图标名经 LayoutIcon 白名单映射，未知值显示默认图标。顾问服务详情中的 icon 字段仍按业务内容数据处理。
变更角色、菜单或用户关联后，权限缓存失效时要重新登录或重新加载菜单，确认侧栏、路由和按钮权限同步变化。
站点模块、玩法、详情、管家、线索和媒体接口按当前契约返回。
新增、更新、删除和排序成功后，页面使用接口返回的数据更新状态，不自行生成 ID 或排序结果。

MiniAPP 重点检查：

Public API 失败时显示错误、重试或空态，并按现有本地 fallback 规则处理。
首页、玩法、路线详情、管家、团队共创和客片案例都由公共 API 层解包 data，页面不重复解包。
POST /api/public/leads 的用车需求携带客户 JWT；后端从 JWT 写入 customerId，客户端不提交该字段。

接口变更流程

响应包裹、错误结构或 ID 规则变化：先更新 api-response-contract.md。
Admin API 路径、字段、权限或状态码变化：更新 admin-api-requirements.md 或对应领域契约。
站点模块字段、排序、单例或删除规则变化：更新 module-config-api.md。
Public API 变化：更新 public-api.md，再同步后端序列化和 MiniAPP 类型。
完成后端实现、前端调用和影响范围内的测试；不得在流程文档中复制接口字段。

验证命令

后端：

Set-Location .\WonderQ-Admin
python -m pytest

管理前端：

Set-Location .\WonderQ-Admin-UI-Vue
yarn test
yarn build

MiniAPP：

Set-Location .\WonderQ-MiniAPP
yarn test
yarn build:h5
yarn build:mp-weixin

安全边界

不读取、展示或提交 .env、.env.local 和生产环境变量值。
文档示例只写占位值，不写真实 Token、JWT secret、客服链接、企业 ID 或手机号。
python -m app.seed 和数据库迁移属于高风险动作，生产环境执行前必须明确确认。

5.3 KiB Raw Blame History Unescape Escape