Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 163 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
name: CI

on:
push:
branches: [main]
pull_request:
workflow_dispatch:

permissions:
contents: read

concurrency:
group: ci-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true

env:
CI: 'true'
APP_ENV: test
MATCHING_AI_ENABLED: 'false'

jobs:
frontend:
name: Frontend checks
runs-on: ubuntu-24.04
timeout-minutes: 10
defaults:
run:
working-directory: frontend
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
- uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
with:
node-version: '22'
cache: npm
cache-dependency-path: frontend/package-lock.json
- run: npm ci
- run: npm test -- --reporter=default --reporter=junit --outputFile=test-results/vitest.xml
- run: npm run type-check:e2e
- run: npm run build
- name: Upload frontend test results
if: ${{ !cancelled() }}
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: frontend-test-results
path: frontend/test-results/
if-no-files-found: ignore
retention-days: 7

backend:
name: Backend checks
runs-on: ubuntu-24.04
timeout-minutes: 10
defaults:
run:
working-directory: backend
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
version: '0.11.7'
python-version: '3.12'
enable-cache: true
cache-dependency-glob: backend/uv.lock
- run: uv sync --locked
- run: uv run --frozen ruff check .
- run: uv run --frozen pytest -m 'not mysql' --junitxml=test-results/pytest.xml
- name: Upload backend test results
if: ${{ !cancelled() }}
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: backend-test-results
path: backend/test-results/
if-no-files-found: ignore
retention-days: 7

integration:
name: MySQL and browser tests
needs: [frontend, backend]
runs-on: ubuntu-24.04
timeout-minutes: 20
env:
DATABASE_URL: mysql+pymysql://lostlink_test:lostlink_test@127.0.0.1:3306/lostlink_test?charset=utf8mb4
TEST_DATABASE_URL: mysql+pymysql://lostlink_test:lostlink_test@127.0.0.1:3306/lostlink_test?charset=utf8mb4
E2E_DATABASE_URL: mysql+pymysql://lostlink_test:lostlink_test@127.0.0.1:3306/lostlink_test?charset=utf8mb4
services:
mysql:
image: mysql:8.4
env:
MYSQL_DATABASE: lostlink_test
MYSQL_USER: lostlink_test
MYSQL_PASSWORD: lostlink_test
MYSQL_ROOT_PASSWORD: lostlink_test_root
TZ: UTC
ports:
- 3306:3306
options: >-
--health-cmd="mysqladmin ping -h 127.0.0.1 -ulostlink_test -plostlink_test --silent"
--health-interval=5s
--health-timeout=5s
--health-retries=30
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
- uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
with:
node-version: '22'
cache: npm
cache-dependency-path: frontend/package-lock.json
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
with:
version: '0.11.7'
python-version: '3.12'
enable-cache: true
cache-dependency-glob: backend/uv.lock
- run: uv sync --locked
working-directory: backend
- name: Check migration upgrade and rollback on the disposable database
working-directory: backend
run: |
uv run --frozen alembic upgrade head
uv run --frozen alembic downgrade 20261006_0004
uv run --frozen alembic upgrade head
uv run --frozen alembic downgrade 20260930_0001
uv run --frozen alembic upgrade head
uv run --frozen alembic downgrade base
uv run --frozen alembic upgrade head
uv run --frozen python -m scripts.seed_items
- name: Run real MySQL integration tests
working-directory: backend
run: uv run --frozen pytest -m mysql --junitxml=test-results/mysql.xml
- run: npm ci
working-directory: frontend
- run: npx playwright install --with-deps chromium
working-directory: frontend
- run: npm run test:e2e
working-directory: frontend
- name: Upload integration and browser results
if: ${{ !cancelled() }}
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: integration-test-results
path: |
backend/test-results/
frontend/playwright-report/
frontend/test-results/
if-no-files-found: ignore
retention-days: 7

required:
name: CI passed
if: ${{ always() }}
needs: [frontend, backend, integration]
runs-on: ubuntu-24.04
timeout-minutes: 1
steps:
- name: Require every test job to pass
env:
FRONTEND_RESULT: ${{ needs.frontend.result }}
BACKEND_RESULT: ${{ needs.backend.result }}
INTEGRATION_RESULT: ${{ needs.integration.result }}
run: |
test "$FRONTEND_RESULT" = success
test "$BACKEND_RESULT" = success
test "$INTEGRATION_RESULT" = success
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,16 @@ node_modules/
dist/
coverage/
*.tsbuildinfo
playwright-report/
test-results/

# Runtime data
uploads/
logs/
*.log
*.db
*.sqlite3
backend/var/e2e-uploads/

# IDE and OS
.idea/
Expand Down
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@

### Added

- 2026-10-21 增加 GitHub Actions CI:Vitest、Ruff/pytest、MySQL 迁移与集成、Playwright 认证及失物/拾物核心流程;增加隔离测试数据库配置、报告上传和本地复现说明。
- 2026-10-21 新增 `20261021_0005` 迁移,为历史 MySQL 回滚保留独立外键支撑索引,修复删除外键依赖索引时报错 1553;保留已发布迁移不变。
- 2026-10-07 增加可配置 DeepSeek 等 OpenAI 兼容图文匹配接口、规则与模型评分融合、批量候选及图片预算、异常降级和模拟供应商测试;真实模型调用待配置密钥后验证。

- 建立项目目录、协作模板和初始文档体系。
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ docs(readme): add project structure guide
- 业务功能与无关格式化修改应拆分提交。
- 接口或数据结构变化必须同步更新文档。

仓库目前提供 Issue 和 Pull Request 模板,但尚未配置 `.github/workflows/` 自动检查。作者应在 Pull Request 中写明实际执行的命令、结果、未执行项及原因;不能把本地未运行的检查写成 CI 已通过。
仓库通过 `.github/workflows/ci.yml` 自动检查前后端代码、MySQL 迁移与集成、Playwright 核心浏览器流程。PR 应等待 `CI passed` 成功;管理员可将它设为 `main` 的必需检查。作者仍应在 Pull Request 中写明实际执行的命令、结果、未执行项及原因;不能把本地验证写成 GitHub CI 已通过。配置与复现方法见[测试策略](docs/development/testing.md)。

## 完成标准

Expand Down
15 changes: 9 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,14 +25,15 @@ LostLink 是面向校园失物招领场景的软件工程课程项目。前端
- 使用 SQLAlchemy 查询 MySQL 的 `GET /api/v1/items` 筛选与分页接口。
- 后端账号注册、登录、注销和当前用户接口,以及 Bearer 会话、登录失败锁定和角色/归属权限守卫。
- 后端物品详情、发布、个人记录、编辑和状态更新接口,并记录不可变状态审计。
- MySQL 8.4 本地容器配置和四份 Alembic migration。
- MySQL 8.4 本地容器配置和五份 Alembic migration,支持一次性数据库中的升级与回滚验证。
- 前端接口、本地表单及状态存储单元测试,以及后端代码检查、接口测试和可选 MySQL 集成测试。
- GitHub Actions 自动检查前后端、真实 MySQL 迁移与集成,以及 Playwright 核心用户流程。

后续范围:

- 校园统一身份、密码找回和完整认领/归还身份核验流程。
- 对象存储、异步任务、站外通知以及基于真实标注样本的高级匹配训练。
- 可重复执行的浏览器端自动化测试;当前完整认证、发布、编辑和退出流程已做人工浏览器联调。
- 扩展图片、匹配和管理端的浏览器自动化覆盖,以及跨浏览器兼容性验证。

个人页和管理端均使用真实账号与服务端数据;所有管理写操作要求管理员角色并记录理由和审计日志。

Expand All @@ -54,7 +55,7 @@ LostLink 是面向校园失物招领场景的软件工程课程项目。前端

## 快速开始

全部真实业务流程都需要已启动的 FastAPI 和 MySQL。当前锁定的 Vite 6.4.3 要求 Node.js 18、20 或 22 及以上版本。启动前先按 [backend/README.md](backend/README.md) 启动数据库、执行迁移和演示数据脚本。
全部真实业务流程都需要已启动的 FastAPI 和 MySQL。完整开发与测试环境建议使用 Node.js 22,与 CI 保持一致。启动前先按 [backend/README.md](backend/README.md) 启动数据库、执行迁移和演示数据脚本。

在仓库根目录使用 Windows PowerShell 执行:

Expand All @@ -81,13 +82,15 @@ npm.cmd run build

2026-10-06 验证结果:6 个测试文件中的 17 个测试通过,类型检查、生产构建和真实浏览器联调通过;npm 生产依赖审计为 0 个已知漏洞。

已增加 `.github/workflows/ci.yml`:在 PR 和推送到 `main` 时自动运行,统一结果为 `CI passed`。本地复现、隔离测试数据库与报告说明见[测试策略](docs/development/testing.md)。上述历史验证和依赖审计不代表最新运行结果,以本次 Actions 记录为准。

如果 PowerShell 提示禁止运行 `npm.ps1`,请使用上述 `npm.cmd` 命令,无需修改系统执行策略。

## 目录说明

```text
LostLink/
├─ .github/ # GitHub Issue 与 Pull Request 模板
├─ .github/ # CI 工作流、Issue 与 Pull Request 模板
├─ backend/ # 后端工程骨架
│ ├─ alembic/ # 数据库迁移目录
│ ├─ app/ # 后端应用分层目录
Expand All @@ -112,7 +115,7 @@ LostLink/
## 后续开发顺序

1. 团队确认校园统一身份和认领核验的正式规则。
2. 为完整用户流程补充可重复执行的浏览器自动化测试。
2. 扩展图片、匹配与管理流程的浏览器自动化测试。
3. 评估对象存储、异步匹配和站外通知集成。
4. 完成部署、监控、备份和回滚演练。

Expand All @@ -131,4 +134,4 @@ LostLink/
3. 按 [CONTRIBUTING.md](CONTRIBUTING.md) 创建分支并提交 Pull Request。
4. 功能、测试和相关文档在同一个 Pull Request 中交付。

认证、物品、图片、举报、匹配和管理模块已经完成前后端与 MySQL 联调。下一阶段应优先补齐认领核验、浏览器自动化测试与部署准备。
认证、物品、图片、举报、匹配和管理模块已经完成前后端与 MySQL 联调。下一阶段应优先补齐认领核验、扩展浏览器测试覆盖与部署准备。
8 changes: 5 additions & 3 deletions backend/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

> 状态:账号认证、物品与图片、举报、匹配通知、管理审计和校准接口均已实现;全部 migration 已在本地 MySQL 完成升级验证。
>
> 最后验证:2026-10-06;33 个默认测试和 3 个 MySQL 集成测试通过。
> 本地验证:2026-10-21;95 个默认测试、3 个 MySQL 集成测试,以及迁移的部分/完整回滚再升级通过。

后端采用 Python 3.12、FastAPI、SQLAlchemy 和 MySQL,并按照“接口层 → 服务层 → 数据访问层 → 数据模型层”组织。`GET /api/v1/items` 通过 Repository 查询 MySQL;内存 Repository 只用于不依赖数据库的快速测试。

Expand Down Expand Up @@ -71,6 +71,8 @@ uv run alembic downgrade -1

已经合并或在共享环境执行过的 migration 不得修改;结构变化必须创建新的 migration。

最新迁移为 `20261021_0005`,新增独立外键支撑索引,修复历史迁移回滚时 MySQL 报错 1553 的问题。降到 `0004` 时刻意保留兼容索引,继续回滚删除对应表/列时一并清除。完整回滚验证只允许在一次性测试库执行,步骤见[测试策略](../docs/development/testing.md)。

## 检查命令

```bash
Expand All @@ -85,8 +87,8 @@ $env:TEST_DATABASE_URL = $env:DATABASE_URL
uv run pytest -m mysql
```

代码检查和测试均应以退出码 `0` 结束。2026-10-06 的最近一次验证中,Ruff
检查通过,33 个默认测试及 3 个显式启用的 MySQL 集成测试通过。
代码检查和测试均应以退出码 `0` 结束。2026-10-21 本地验证中,Ruff
检查通过,95 个默认测试及 3 个显式启用的 MySQL 集成测试通过。CI 统一检查名为 `CI passed`,本地复现步骤见[测试策略](../docs/development/testing.md)。

## 当前接口

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
"""为历史迁移的 MySQL 回滚保留独立外键索引。

Revision ID: 20261021_0005
Revises: 20261006_0004
Create Date: 2026-10-21

历史迁移先删除业务索引再删除表;MySQL 可能已经用这些业务索引替换了
自动生成的外键索引,导致 DROP INDEX 报错 1553。新增独立支撑索引,
无需改写已发布的迁移或关闭外键检查。
"""

from collections.abc import Sequence

import sqlalchemy as sa

from alembic import context, op

revision: str = "20261021_0005"
down_revision: str | Sequence[str] | None = "20261006_0004"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None

SUPPORT_INDEXES = (
("stored_images", "ix_stored_images_owner_fk", ["owner_id"]),
("stored_images", "ix_stored_images_item_fk", ["item_id", "id"]),
("item_status_history", "ix_item_status_history_item_fk", ["item_id"]),
("auth_sessions", "ix_auth_sessions_user_fk", ["user_id"]),
("items", "ix_items_owner_fk", ["owner_id"]),
)


def upgrade() -> None:
"""补足索引;从旧版本重新升级时复用已保留的同名索引。"""

inspector = None if context.is_offline_mode() else sa.inspect(op.get_bind())
for table, name, columns in SUPPORT_INDEXES:
existing = set() if inspector is None else {
index["name"] for index in inspector.get_indexes(table)
}
if name not in existing:
op.create_index(name, table, columns)


def downgrade() -> None:
"""刻意保留兼容索引,供 0004、0003、0002 的回滚使用。

降到 0004 时只额外保留索引,不改变数据或约束。继续回滚时,历史迁移
删除对应表会一并移除索引;再次升级由 upgrade 的存在性检查保证幂等。
"""
2 changes: 2 additions & 0 deletions backend/app/models/feature.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ class StoredImage(Base):
__tablename__ = "stored_images"
__table_args__ = (
Index("ix_stored_images_owner_created", "owner_id", "created_at"),
Index("ix_stored_images_owner_fk", "owner_id"),
Index("ix_stored_images_item_fk", "item_id", "id"),
{"mysql_charset": "utf8mb4", "mysql_collate": "utf8mb4_0900_ai_ci"},
)

Expand Down
1 change: 1 addition & 0 deletions backend/app/models/item.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ class Item(Base):
Index("ix_items_type", "type"),
Index("ix_items_category", "category"),
Index("ix_items_campus_area", "campus", "area"),
Index("ix_items_owner_fk", "owner_id"),
{"mysql_charset": "utf8mb4", "mysql_collate": "utf8mb4_0900_ai_ci"},
)

Expand Down
1 change: 1 addition & 0 deletions backend/app/models/item_status_history.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ class ItemStatusHistory(Base):
__tablename__ = "item_status_history"
__table_args__ = (
Index("ix_item_status_history_item_created", "item_id", "created_at"),
Index("ix_item_status_history_item_fk", "item_id"),
{"mysql_charset": "utf8mb4", "mysql_collate": "utf8mb4_0900_ai_ci"},
)

Expand Down
1 change: 1 addition & 0 deletions backend/app/models/user.py
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@ class AuthSession(Base):
__tablename__ = "auth_sessions"
__table_args__ = (
Index("ix_auth_sessions_user_expires", "user_id", "expires_at"),
Index("ix_auth_sessions_user_fk", "user_id"),
{"mysql_charset": "utf8mb4", "mysql_collate": "utf8mb4_0900_ai_ci"},
)

Expand Down
21 changes: 21 additions & 0 deletions backend/compose.test.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# 一次性测试数据库;与 compose.yaml 的开发数据库使用不同端口和项目名。
name: lostlink-test

services:
mysql:
image: mysql:8.4
environment:
MYSQL_DATABASE: lostlink_test
MYSQL_USER: lostlink_test
MYSQL_PASSWORD: lostlink_test
MYSQL_ROOT_PASSWORD: lostlink_test_root
TZ: UTC
ports:
- "127.0.0.1:${MYSQL_TEST_PORT:-13306}:3306"
healthcheck:
test: [CMD-SHELL, "mysqladmin ping -h 127.0.0.1 -u$$MYSQL_USER -p$$MYSQL_PASSWORD --silent"]
interval: 5s
timeout: 5s
retries: 30
start_period: 20s
# 不挂载开发数据库卷;结束后用 down -v 删除测试容器及其匿名卷。
Loading