• 报告期次：第1次 ｜ 报告日期：2026-10-08 ｜ 项目组号：第5组 ｜ 项目名称：在线购物系统（挑战升级）

• 已完成工作：搭建项目 GitHub 仓库与组 Wiki，挂接全部文档页

• 成果物：https://github.com/xiaochu-dev/online-shopping-group5

• 已完成工作：架构设计：技术选型论证、分层架构、商品三态与意向五态状态机、队列递补算法、三表数据库设计

• 成果物：在线购物系统 架构设计与数据库表结构（MVP）

• 已完成工作：公共数据层与状态机骨架开发（sqlite3 三表 DDL、商品/意向状态流转、队列排序键设计）

• 成果物：https://github.com/xiaochu-dev/online-shopping-group5/blob/main/db.py、https://github.com/xiaochu-dev/online-shopping-group5/blob/main/services_state.py

• 已完成工作：卖家后台模块开发（FR-01/05/07/08）：登录与会话、验原密码改密、意向购买人列表、进入交易自动冻结、冻结/解冻开关、交易结果标记、历史记录

• 成果物：https://github.com/xiaochu-dev/online-shopping-group5/blob/main/main.py、https://github.com/xiaochu-dev/online-shopping-group5/blob/main/auth.py

• 已完成工作：部署交付与质量基线：全流程冒烟测试 30 项自动化用例、部署脚本（run.bat）与部署手册

• 成果物：在线购物系统 部署手册（MVP）

文档说明：本文件是组长「架构设计、数据库表结构」职责的署名成果物，描述 MVP 版本的技术选型、分层架构、两个状态机、队列递补算法、数据库表结构与 REST 接口，作为三人并行开发的实现依据。

选型总原则：3 人小组、单次迭代 2 周、目标是可运行可验收的基线 MVP。全部组件均为轻量级、零外部服务依赖，pip install 一次即可在任意 Windows 机器上跑通，最大化开发与演示效率，避免运维开销挤占编码时间。

结论：MVP 的数据规模（单商品、数百意向）与并发量（课程演示级别）远低于 SQLite 能力上限，引入 MySQL/PostgreSQL 属于过度设计。SQLite 是本场景的最优解。

flowchart TD
    BROWSER["浏览器（买家 / 卖家）"]
    BROWSER -->|"HTTP（127.0.0.1:8000）"| ROUTE

    subgraph ROUTE["路由层 · FastAPI + uvicorn"]
        direction LR
        R1["买家页路由<br/>/product"]
        R2["意向路由<br/>/intents"]
        R3["登录路由<br/>/login"]
        R4["后台路由<br/>/admin/*"]
    end

    ROUTE -->|"会话校验（签名 cookie）· 表单/文件解析 · 重定向"| SVC

    subgraph SVC["服务层（业务逻辑，纯 Python 函数）"]
        direction LR
        S1["auth 认证服务<br/>登录校验 · 改密验旧密码<br/>签名 cookie"]
        S2["商品状态机服务<br/>发布唯一性校验 · 冻结/解冻/下架<br/>进入交易自动冻结 · 标记成功/失败"]
        S3["意向队列服务<br/>排序（时间+id）· 撤销（口令码）<br/>递补（失败→队首）· 成交批量转 failed"]
    end

    SVC -->|"事务边界：每个状态流转 = 一个事务 · PRAGMA foreign_keys = ON"| DATA

    subgraph DATA["数据层 · 标准库 sqlite3（单文件 shop.db）"]
        direction LR
        T1["seller 卖家"]
        T2["product 商品"]
        T3["intent 意向"]
    end

    DATA -.->|"渲染上下文"| TPL

    subgraph TPL["模板层 · Jinja2（服务端渲染）"]
        direction LR
        P1["卖家后台模板<br/>发布/意向人/冻结"]
        P2["买家页模板<br/>商品详情/口令码页"]
        P3["历史记录模板<br/>历史列表/历史详情"]
    end

stateDiagram-v2
    direction LR
    state "在售 on_sale" as S
    state "已冻结 frozen" as F
    state "已下架 delisted（终态）" as D
    [*] --> S: 卖家发布（on_sale 唯一性校验通过）
    S --> F: ① 进入交易（系统自动冻结）；② 卖家手动冻结
    F --> S: ③ 手动解冻；④ 标记「失败」恢复在售（已恢复在售语义态 + 递补）
    F --> D: ⑤ 标记「成功」（进入历史）
    S --> D: ⑥ 手动下架（仅在售状态可执行）
    D --> [*]

规则：自动冻结（#2）与手动冻结（#3）到达同一个 frozen 状态，库中不做来源标记（澄清结论第六节）。 下架唯一性：delisted 仅有 #5、#6 两条进入路径；frozen 状态下卖家只能选择标记成功 / 标记失败 / 手动解冻，不能直接手动下架。

状态 3 的撤销仅允许 pending 意向：已进入 trading 的意向买家不可自行撤销，须等待卖家标记结果；success / failed / cancelled 均为终态。

队列不落物理位次字段，位次始终由查询时排序计算，撤销后天然前移，无更新风暴：

• 主排序键：created_at（毫秒级时间戳，INTEGER）
• 兜底键：id（自增主键；同一毫秒内多次提交时保证入库顺序即队列顺序）
• 即 ORDER BY created_at ASC, id ASC，与复合索引 intent(product_id, status, created_at) 配合（见 6.3 节）

##### ── 查询当前商品队列（服务层函数）──────────────────────
function get_queue(product_id):
    return SELECT id, buyer_name, phone, created_at
           FROM intent
           WHERE product_id = product_id AND status = 'pending'
           ORDER BY created_at ASC, id ASC        # 位次 = 结果集行号

##### ── 买家撤销意向（一个事务）───────────────────────────
function cancel_intent(token_code):
    BEGIN
        row = SELECT * FROM intent WHERE token_code = token_code
                                   AND status = 'pending'   # 精确匹配 + 仅排队中可撤销
        assert row 存在
        UPDATE intent SET status = 'cancelled' WHERE id = row.id
        # 队列按 ORDER BY 实时计算，删除即前移，无需更新其余行
        # 商品状态不变（on_sale 或 frozen，取决于撤销时机）
    COMMIT

##### ── 卖家选定队首进入交易（一个事务）─────────────────────
function start_trade(product_id):
    BEGIN
        assert product.status == 'on_sale'
        head = get_queue(product_id) 的第一行
        assert head 存在
        UPDATE intent SET status = 'trading' WHERE id = head.id
        UPDATE product SET status = 'frozen'      # 自动冻结
    COMMIT

##### ── 标记交易失败（一个事务，触发递补）────────────────────
function mark_failed(product_id):
    BEGIN
        cur = SELECT * FROM intent
              WHERE product_id = product_id AND status = 'trading'
        UPDATE intent SET status = 'failed' WHERE id = cur.id
        UPDATE product SET status = 'on_sale'     # ① 商品恢复在售
        head = get_queue(product_id) 的第一行
        IF head 存在 THEN                          # ② 队列非空
            UPDATE intent SET status = 'trading' WHERE id = head.id
            UPDATE product SET status = 'frozen'   # ③ 新队首进入交易，商品再冻结
        ELSE                                       # ④ 队列为空
            商品停留在 on_sale，重新接收新意向
        END IF
    COMMIT

##### ── 标记交易成功（一个事务，殃及整个队列）─────────────────
function mark_success(product_id):
    BEGIN
        cur = 当前 trading 意向
        UPDATE intent SET status = 'success' WHERE id = cur.id
        UPDATE intent SET status = 'failed'
              WHERE product_id = product_id AND status = 'pending'
              # 商品已下架，队列中其余排队意向失去意义，全部转 failed
        UPDATE product SET status = 'delisted',
                           trade_result = 'success',
                           traded_at = 当前毫秒时间戳
    COMMIT

算法要点：

1. 位次不落库，ORDER BY created_at, id 即队列，撤销后位次自动前移（FR-04-6）。
2. 失败递补严格按「商品回在售 → 取新队首 → 意向转 trading → 商品再冻结」四步，在同一事务内完成，中间状态不可见（NFR-02）。
3. 队列为空时商品停在 on_sale，等待新买家提交（FR-04-7 的自然结果）。
4. 成交时批量将剩余 pending 意向转 failed，保证历史详情页每人交易结果字段有值（FR-08-5）。

PRAGMA foreign_keys = ON;

-- 卖家账号表（全系统仅一条记录）
CREATE TABLE seller (
    id            INTEGER PRIMARY KEY AUTOINCREMENT,
    username      TEXT    NOT NULL UNIQUE,
    password_hash TEXT    NOT NULL,
    created_at    INTEGER NOT NULL
);

-- 商品表（同一时间最多一条 status = 'on_sale'）
CREATE TABLE product (
    id           INTEGER PRIMARY KEY AUTOINCREMENT,
    name         TEXT    NOT NULL,
    description  TEXT    NOT NULL DEFAULT '',
    image_path   TEXT    NOT NULL DEFAULT 'static/placeholder.png',
    price_cents  INTEGER NOT NULL CHECK (price_cents > 0),
    status       TEXT    NOT NULL DEFAULT 'on_sale'
                 CHECK (status IN ('on_sale', 'frozen', 'delisted')),
    published_at INTEGER NOT NULL,
    trade_result TEXT    CHECK (trade_result IN ('success', 'failed', 'manual_delist')),
    traded_at    INTEGER
);

-- 购买意向表
CREATE TABLE intent (
    id         INTEGER PRIMARY KEY AUTOINCREMENT,
    product_id INTEGER NOT NULL REFERENCES product(id),
    buyer_name TEXT    NOT NULL,
    phone      TEXT    NOT NULL,
    token_code TEXT    NOT NULL,  -- 口令码；唯一性由应用层生成时查重保证（services_state.py）
    status     TEXT    NOT NULL DEFAULT 'pending'
               CHECK (status IN ('pending', 'trading', 'success', 'failed', 'cancelled')),
    created_at INTEGER NOT NULL
);

-- 队列查询复合索引（见 6.3 节）
CREATE INDEX idx_intent_queue ON intent (product_id, status, created_at);

表 1：seller（卖家账号）

表 2：product（商品）

表 3：intent（购买意向）

其余高频查询均为小表全表扫描（seller 单行、product 按状态过滤、历史列表按 traded_at 排序的记录量受翻页限制），MVP 数据量下不额外建索引。

权限说明：/admin/* 全部经签名 cookie 会话校验，未登录访问重定向至 /login（FR-01-3）；本版本不提供退出登录（FR-01-6）。接口均为服务端渲染页面表单，不提供 JSON API。

依据《团队分工方案-第5组》第四节「第 1 次迭代（MVP）模块认领」，与本架构文档的模块划分对照如下：

对照说明：本表与需求追溯矩阵（需求规格说明书第 7 节）一致；FR-02 的发布表单与校验归卖家后台（胡成溯），FR-03 的买家浏览与提交归黄程宇，两模块共用 product 表但入口分离，接口边界即第 7 节接口清单。

本文件为第 5 组 MVP 架构基线，三人开发均以本文件为实现依据；后续迭代在此文件基础上增补设计章节。

文档说明：本手册描述 MVP 版本从零到可访问的完整部署过程。按第 1~4 节顺序执行即可完成部署；第 5 节为常见问题排查；第 6 节为评审现场的一键演示脚本。

从 Git 平台下载 项目简写-版本号.zip 并解压，或直接克隆仓库，得到项目目录：

shop-mvp/
├── main.py              # 应用入口（uvicorn 启动）
├── db.py                # 建表与种子数据初始化脚本
├── run.bat              # Windows 一键启动脚本
├── requirements.txt     # 第三方依赖清单
├── app/                 # 路由层、服务层代码
├── templates/           # Jinja2 模板（后台 / 买家页 / 历史）
└── static/              # 占位图、上传图片目录

cd shop-mvp
python -m venv .venv
.venv\Scripts\activate

pip install -r requirements.txt

国内网络环境建议使用清华镜像源加速：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后可用 pip list 确认 fastapi、uvicorn、jinja2、python-multipart 均已就位。

首次部署必须先执行初始化脚本（自动建表 + 写入种子卖家账号）：

python db.py

初始化脚本自动完成：

1. 在项目根目录创建 SQLite 数据库文件 shop.db；
2. 创建 seller / product / intent 三张表及队列复合索引（DDL 见《03-架构设计与数据库表结构》第 6 节）；
3. 写入种子卖家账号：

⚠️ 安全提示：种子密码仅用于首次登录，评审与日常使用前请登录后台立即修改密码（后台「修改密码」入口，需验证原密码，新密码 ≥ 8 位）。

两种方式任选其一：

方式一：命令行启动

python main.py

方式二：双击一键启动脚本

双击项目根目录下的 run.bat

run.bat 内部执行「激活虚拟环境 + python main.py」，用于评审现场免命令行演示。

启动成功后控制台输出：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

首次部署顺序：第 3 节初始化 → 第 4 节启动。未初始化直接启动会提示数据库文件缺失，按第 3 节执行 python db.py 后重新启动即可。

以下为第 1 次评审的完整演示动线，覆盖 MVP 验收清单第 1~12 项。演示前建议按 FAQ-3 重置数据库，保证队列干净。演示用买家在多个浏览器窗口（或普通 + 无痕窗口）中打开买家页。

演示要点提示：步骤 6~7 是「队列与递补」的核心演示点（FR-06-1、FR-07-6/7）；步骤 9 可对照验收清单第 12 项逐字段核对。若评审现场 8000 端口冲突，全程将 URL 中的 8000 替换为 FAQ-1 中的备用端口即可。

本文件对齐课程《系统验收标准》第 4 项「部署」三要素：运行环境说明（第 1 节）、安装部署过程（第 2~4 节）、部署脚本（run.bat 一键启动 + db.py 初始化脚本）。

（评审后填写）