状态：认证、物品、图片、举报、匹配通知与管理控制台已完成前后端联调
前端、后端与 MySQL 联调记录：2026-10-06
LostLink 是面向校园失物招领场景的软件工程课程项目。前端已经接入 FastAPI 和 MySQL，支持认证、物品与图片发布、个人管理、举报审核、候选匹配通知和管理员工作流。
项目希望把失物、拾物信息的发布、检索、匹配和状态跟踪集中到一个协作流程中，减少信息分散和重复沟通。当前产品范围仍处于团队确认阶段，需求草案见 docs/product/requirements.md。
已实现：
- 基于 Vue 3、TypeScript 和 Vite 的可运行前端工程。
- 首页关键词搜索，以及类别、校区、时间和记录类型筛选。
- 东丽校区北区/南区二级筛选，以及宁河校区整体筛选。
- 记录卡片、空结果、独立详情页、真实举报提交和响应式布局。
- 发布失物、登记拾物共用前端表单，支持校验、本地草稿、最多三张图片上传并写入真实后端。
- 账号注册、登录、会话恢复、受保护路由和退出登录，并在当前标签页保存 Bearer 会话。
- “我的”页面包含真实用户摘要、个人记录筛选与分页、编辑、找回/归还和关闭操作。
- 管理员控制台包含真实数据概览、举报审核、用户限制/恢复、只读审计日志和匹配校准版本管理。
- 基于 Vue Router 的统一页面导航、独立管理布局及窄屏适配。
- FastAPI 应用入口、健康检查、统一错误响应和 OpenAPI 文档。
- 使用 SQLAlchemy 查询 MySQL 的
GET /api/v1/items筛选与分页接口。 - 后端账号注册、登录、注销和当前用户接口，以及 Bearer 会话、登录失败锁定和角色/归属权限守卫。
- 后端物品详情、发布、个人记录、编辑和状态更新接口，并记录不可变状态审计。
- MySQL 8.4 本地容器配置和五份 Alembic migration，支持一次性数据库中的升级与回滚验证。
- 前端接口、本地表单及状态存储单元测试，以及后端代码检查、接口测试和可选 MySQL 集成测试。
- GitHub Actions 自动检查前后端、真实 MySQL 迁移与集成，以及 Playwright 核心用户流程。
后续范围：
- 校园统一身份、密码找回和完整认领/归还身份核验流程。
- 对象存储、异步任务、站外通知以及基于真实标注样本的高级匹配训练。
- 扩展图片、匹配和管理端的浏览器自动化覆盖，以及跨浏览器兼容性验证。
个人页和管理端均使用真实账号与服务端数据；所有管理写操作要求管理员角色并记录理由和审计日志。
以下路径附在前端服务地址之后，例如 http://127.0.0.1:5173/register。
| 路径 | 当前行为 |
|---|---|
/ |
首页，查询真实物品接口 |
/publish/lost、/publish/found |
登录后向后端发布真实失物或拾物记录 |
/notifications |
登录后查看真实候选匹配通知并提交反馈 |
/login、/register |
真实账号登录与注册 |
/my |
登录后查看和管理自己的记录 |
/admin/{section} |
管理员工作台，提供概览、举报、用户、审计和校准模块 |
/admin-preview/{section} |
兼容旧链接并重定向到真实管理地址 |
前端路由守卫只改善导航体验，管理员与普通用户的权限区分最终由后端逐个接口验证。
全部真实业务流程都需要已启动的 FastAPI 和 MySQL。完整开发与测试环境建议使用 Node.js 22，与 CI 保持一致。启动前先按 backend/README.md 启动数据库、执行迁移和演示数据脚本。
在仓库根目录使用 Windows PowerShell 执行：
cd frontend
npm.cmd ci
Copy-Item .env.example .env
npm.cmd run dev启动成功后，以终端显示的地址为准，通常是 http://127.0.0.1:5173/。后端不可用时，真实查询、认证、发布和个人管理会显示连接错误。停止服务时在终端按 Ctrl+C。
以下命令在 frontend/ 目录执行，按改动范围选择；生产构建在交付或相关配置变更时执行：
npm.cmd test
npm.cmd run type-check
npm.cmd run buildtest 运行现有 Vitest 接口层测试，type-check 检查 Vue/TypeScript 类型，build 执行类型检查并生成 frontend/dist/。dist/ 只是本地产物，不提交到 Git。
2026-10-06 验证结果：6 个测试文件中的 17 个测试通过，类型检查、生产构建和真实浏览器联调通过；npm 生产依赖审计为 0 个已知漏洞。
已增加 .github/workflows/ci.yml：在 PR 和推送到 main 时自动运行，统一结果为 CI passed。本地复现、隔离测试数据库与报告说明见测试策略。上述历史验证和依赖审计不代表最新运行结果，以本次 Actions 记录为准。
如果 PowerShell 提示禁止运行 npm.ps1，请使用上述 npm.cmd 命令，无需修改系统执行策略。
LostLink/
├─ .github/ # CI 工作流、Issue 与 Pull Request 模板
├─ backend/ # 后端工程骨架
│ ├─ alembic/ # 数据库迁移目录
│ ├─ app/ # 后端应用分层目录
│ └─ tests/ # 后端测试目录
├─ frontend/ # 前端工程骨架
│ ├─ public/ # 公共静态资源
│ └─ src/ # 前端源码、页面和同目录单元测试
├─ docs/ # 项目级文档中心
│ ├─ product/ # 需求范围与用户流程
│ ├─ architecture/ # 系统、前端、后端、数据库与 ADR
│ ├─ api/ # 跨端接口契约
│ ├─ development/ # 环境、流程、测试与约定
│ ├─ design/ # 页面、交互与视觉说明
│ └─ operations/ # 部署、运行与安全
├─ scripts/ # 项目辅助脚本说明目录
├─ CONTRIBUTING.md # 协作与提交规范
└─ README.md # 项目入口说明
更完整的目录职责见 系统架构总览。
- 团队确认校园统一身份和认领核验的正式规则。
- 扩展图片、匹配与管理流程的浏览器自动化测试。
- 评估对象存储、异步匹配和站外通知集成。
- 完成部署、监控、备份和回滚演练。
- 文档中心：按产品、架构、开发、设计和运维主题浏览全部文档。
- 前端开发说明：前端安装、运行、检查命令和目录职责。
- 后端开发说明：后端安装、运行、迁移与验证说明。
- 贡献指南：分支、提交、评审和协作要求。
- 变更记录：对使用者和开发者有影响的变化。
- 从需求文档中选择一个已确认的需求，创建对应 Issue。
- 在 Issue 中写明范围、验收条件、负责人和依赖。
- 按 CONTRIBUTING.md 创建分支并提交 Pull Request。
- 功能、测试和相关文档在同一个 Pull Request 中交付。
认证、物品、图片、举报、匹配和管理模块已经完成前后端与 MySQL 联调。下一阶段应优先补齐认领核验、扩展浏览器测试覆盖与部署准备。