SCUTmarket.md

SCUT 旧物交易市场网站设计文档

介绍

这是一个华南理工大学的旧物交易市场网站，学生们可以在上面发布二手商品和联系方式。只有使用学校邮箱登录之后才能发布。不登陆也能查看商品。

技术选型

后端

• 后端语言确定使用 Go。
• 后端主要负责用户登录、商品发布与管理、公告管理、图片上传、权限校验和数据接口输出。
• 前后端通过 HTTP API 交互，接口数据格式统一为 JSON。

数据库

• 数据库确定使用 SQLite。
• SQLite 适合作为本项目第一阶段的实现方案，部署简单，开发成本低。
• 当前项目场景以校内使用、小规模访问、功能快速落地为主，SQLite 可以满足需求。
• 如果未来访问量明显增长，或者需要更复杂的检索和运维能力，再考虑迁移到 PostgreSQL。

技术选型说明

• 当前方案定为：前端使用 TypeScript + React + Vite + TanStack Router + TanStack Query，后端使用 Go，数据库使用 SQLite。
• 前端需要按照前后端分离方式设计，避免页面逻辑与后端实现强耦合。
• 后端接口和数据表结构在设计时应尽量保持清晰，便于后续扩展或迁移数据库。

前端技术补充说明

• 前端路由方案确定使用 TanStack Router。
• 前端数据请求、缓存和异步状态管理确定使用 TanStack Query。
• TanStack Router 主要负责页面路由、路由参数、页面跳转和路由层级组织。
• TanStack Query 主要负责公告列表、商品列表、商品详情、我的商品、登录态等数据的请求与缓存。
• 商品发布、修改、删除、登录、退出登录等操作完成后，需要通过 TanStack Query 做缓存失效和数据刷新。

认证方案

登录方式

• 登录方式确定为“校内邮箱注册 / 登录”。
• 注册时使用华工邮箱 + 验证码完成校验，并允许用户设置密码。
• 登录时同时支持两种方式：

1. 华工邮箱 + 验证码登录
2. 华工邮箱 + 密码登录

• 用户未登录时可以浏览公告和市场。
• 用户只有在完成注册并成功登录后，才能发布、修改和删除自己的商品。
• 系统不单独提供昵称字段，用户身份以邮箱账号为准。

校内邮箱限制

• 后端需要校验邮箱后缀，只允许学校邮箱进行登录。
• 当前邮箱域名固定写死为 @mail.scut.edu.cn，不作为配置项暴露。
• 如果邮箱不属于允许范围，需要直接拒绝发送验证码。

登录流程

1. 用户在前端输入华工邮箱地址。
2. 如果是注册流程，前端调用后端接口发送验证码。
3. 后端生成验证码并发送到该校内邮箱。
4. 用户输入收到的验证码，并设置登录密码。
5. 前端调用后端接口完成注册。
6. 注册成功后，后端创建登录态，并返回当前用户信息。
7. 后续登录时，用户可以选择“邮箱 + 验证码”或“邮箱 + 密码”。

后端实现要求

• 后端需要提供发送验证码接口、验证码登录接口、密码登录接口和注册接口。
• 验证码需要有过期时间，例如 5 分钟。
• 验证码只能使用一次。
• 同一邮箱需要做发送频率限制，避免被恶意刷接口。
• 用户密码需要安全存储，不能明文保存，建议使用哈希方案。
• 登录成功后，建议后端使用 Cookie Session 维持登录状态。
• 后端在执行发布、修改、删除等操作时，必须校验当前登录用户身份。

配置化要求

• 校内邮箱域名固定为 @mail.scut.edu.cn，这一项不需要放入配置文件。
• 除上述两项外，其他可变的业务参数建议统一收敛到配置文件中，避免分散硬编码在页面或接口逻辑里。
• 后端验证码发送需要通过配置文件提供 SMTP 参数，第一阶段仅要求支持 STARTTLS，不要求 SMTPS / SSL 直连。

统一配置结构建议

• 当前项目的正式配置建议落在后端配置文件中，例如 backend/config/server.json。
• 如需类型约束，可以在后端保留与配置文件对应的结构体定义。
• 建议至少拆分为四组配置：server、auth、smtp、audit。
• auth 建议包含：

1. 密码最小长度
2. 验证码有效期
3. 验证码发送冷却时间
4. 登录态有效期

• smtp 建议包含：

1. SMTP 服务器地址
2. SMTP 端口
3. 发信账号
4. 发信邮箱
5. 授权码或 SMTP 密码
6. 发信人名称
7. 超时时间

• 发送邮件时默认走 STARTTLS 升级连接，不使用 SSL 直连 465 端口。
• audit 建议包含：

1. audit.mode
2. audit.enable_rule
3. audit.enable_ai
4. 审核队列 SLA 文案
5. 审核策略说明文案
6. 风险规则中的关键词和风险分

管理员账号

• 系统中需要有一个管理员账号。
• 管理员账号同样通过登录流程进入系统，但拥有额外的审核权限。
• 后端需要区分普通用户和管理员用户身份。
• 管理员登录成功后，前端需要展示管理员专用的审核页面入口。
• 普通用户登录后不能看到审核页面，也不能访问审核相关接口。

部署方案

部署位置

• 网站计划部署在 DragonOS 实验室内部一台连接校内网的机器上。
• 该机器作为前后端服务的部署节点，对外提供网站访问能力。

访问范围

• 当前设想是通过部署位置和网络环境控制访问范围，使网站仅能在校园网环境下访问。
• 也就是说，只有连接华工校园网的用户才能打开该网站。
• 这可以作为平台的第一层访问限制，与“校内邮箱注册 / 登录”共同组成访问与发布权限控制。

域名方案

• 网站计划在 osc 的域名体系下新增一个子域名。
• 该子域名将解析或映射到 DragonOS 实验室内该机器的 IP 和对应服务端口。
• 用户最终通过该子域名访问网站，而不是直接访问 IP 和端口。

部署结构建议

• 前端构建产物可以由 Go 后端统一托管，也可以由反向代理提供静态文件。
• Go 后端负责 API、登录、权限校验、图片上传和 SQLite 数据访问。
• SQLite 数据文件保存在部署机器本地，并做好备份。
• 如果后续需要，可以在前面加一层 Nginx，用于域名接入、反向代理和静态资源分发。

部署注意事项

• 需要保证部署机器可以正常发送验证码邮件。
• 需要确认实验室机器的网络策略允许目标端口被校园网访问。
• 需要确认 osc 子域名映射时，能够正确转发到部署机器上的服务端口。
• 如果站点后续启用 HTTPS，还需要同时考虑证书部署与反向代理配置。

内容审核与风控方案

设计目标

• 平台需要尽量拦截违法违规内容，例如黄赌毒、政治敏感信息、诈骗引流、开盒和隐私泄露信息。
• 审核方案需要控制成本，不能依赖全量人工审核，也不依赖高成本的大模型审核。
• 第一阶段采用“规则拦截 + 举报机制 + 少量人工复核”的低成本方案。

审核总体策略

• 不采用所有内容都先人工审核的方式。
• 不采用所有内容都走 AI 模型审核的方式。
• 默认先由后端进行规则检测。
• 明显违规内容直接拒绝发布。
• 可疑内容进入待审核状态，不直接公开展示。
• 正常内容直接发布上线。
• 上线后的内容继续接受举报和风控检测。

审核模式配置

• 平台支持两种审核方式：规则审核和 AI 审核。
• 后端需要通过配置文件控制审核方式，而不是把审核策略写死在代码里。
• 配置文件应支持以下模式：

1. 仅启用规则审核
2. 仅启用 AI 审核
3. 同时启用规则审核和 AI 审核

• 后端启动时读取配置，并按配置决定发布流程中的审核链路。

规则审核

• 规则审核基于敏感词词库、正则规则和基础风控规则实现。
• 规则审核结果分为三类：

1. 明显违规：直接禁止发布，并返回错误提示。
2. 疑似违规：商品进入“待审核”状态，不直接公开展示。
3. 通过：商品可以继续进入后续审核流程或直接发布。

• “明显违规”主要指命中高风险违法词、隐私泄露规则、开盒信息等强规则内容。
• “疑似违规”主要指命中部分风险词，但不能完全确定违规的内容。

AI 审核

• AI 审核作为可选审核能力，不强制要求第一阶段默认启用。
• AI 审核可用于补充判断规则审核难以覆盖的模糊内容。
• AI 审核结果同样分为三类：

1. 明显违规：直接禁止发布。
2. 疑似违规：进入“待审核”状态。
3. 通过：允许继续发布流程。

• AI 审核是否启用，由配置文件决定。

联合审核策略

• 当同时启用规则审核和 AI 审核时，两者共同参与判定。
• 联合审核建议采用从严策略：

1. 任一审核结果为“明显违规”，则直接禁止发布。
2. 如果没有“明显违规”，但任一审核结果为“疑似违规”，则进入“待审核”状态。
3. 只有规则审核和 AI 审核都通过时，商品才允许直接发布。

• 这样可以降低漏审风险。

配置文件要求

• 后端配置文件中需要包含审核模式开关。
• 建议至少提供以下配置项：

1. audit.mode
2. audit.enable_rule
3. audit.enable_ai

• 也可以只保留一种配置表达方式，但最终必须能够表达“规则审核”“AI 审核”“同时启用”三种模式。
• 后续如果接入不同 AI 服务商，也可以在配置文件中继续增加 AI 审核提供方、接口地址、模型名称、超时等配置项。

重点审核内容

• 黄赌毒相关信息。
• 政治敏感和违法违规信息。
• 诈骗、引流、黑灰产相关信息。
• 泄露他人隐私、开盒、人肉搜索相关信息。
• 辱骂、骚扰、恶意攻击性内容。
• 与二手交易平台定位明显无关的垃圾内容。

文本审核方案

• 后端对商品标题、商品描述、联系方式等文本字段进行审核。
• 第一阶段以敏感词词库和规则匹配为主。
• 对明显违规关键词直接拦截，不允许提交。
• 对命中部分风险词但不完全确定的内容，进入待审核队列。
• 需要对联系方式字段单独加强校验，避免用户在联系方式中夹带违规内容。

隐私与开盒信息检测

• 平台明确禁止发布他人的身份证号、学号、手机号、宿舍号、详细住址、银行卡号等敏感信息。
• 后端可以通过正则规则识别明显的隐私信息模式。
• 一旦命中高风险隐私信息，默认不直接发布。
• 对于疑似开盒、人肉搜索、曝光他人信息的内容，应直接进入高风险处理流程。

图片审核策略

• 第一阶段不引入高成本图片 AI 审核。
• 图片层面先做基础限制，例如文件类型、文件大小、图片数量。
• 对图片内容的违规风险，主要依赖用户举报和人工复核。
• 如果后续平台规模扩大，再考虑补充第三方图片审核服务。

用户举报机制

• 每个商品页面都应提供举报入口。
• 举报原因建议固定为几个选项，例如：

1. 违法违规
2. 色情低俗
3. 政治敏感
4. 泄露隐私 / 开盒
5. 诈骗 / 引流
6. 其他

• 被举报内容需要进入审核队列。
• 同一商品在短时间内被多人举报时，可以先自动下架，再等待人工复核。

风控与限流策略

• 对单个账号的发布频率、修改频率、验证码发送频率进行限制。
• 对短时间内反复发布、删除、修改内容的账号进行风控标记。
• 对多次发布违规内容或多次被举报属实的账号，可以限制发帖或直接封禁。

人工复核策略

• 人工审核只处理高风险和被系统筛出的内容，不处理全部商品。
• 人工优先处理以下队列：

1. 命中高风险关键词的内容
2. 命中隐私泄露规则的内容
3. 被用户举报的内容
4. 多次违规账号发布的新内容

• 这样可以把人工审核量控制在较低水平。

平台规则与处罚

• 平台需要明确发布规则，并在前端和文档中说明。
• 平台应明确禁止黄赌毒、政治敏感、隐私泄露、开盒、诈骗、恶意骚扰等内容。
• 平台应保留删除内容、下架商品、限制账号、封禁账号的处理权。
• 后端需要保留必要的日志信息，便于后续排查违规行为。

第一阶段落地建议

• 第一阶段优先实现以下能力：

1. 敏感词词库检测
2. 隐私信息正则检测
3. 举报入口和举报原因分类
4. 待审核 / 已下架 / 正常展示状态
5. 基础限流与账号风控
6. 简单的后台审核队列

• 第一阶段暂不依赖大模型审核，以降低部署和运行成本。

前端

前端以桌面端优先，同时兼容手机浏览器。整体风格尽量简洁、校园化、信息清晰，重点突出商品图片、标题、价格和校区信息。页面结构以顶部导航 + 主内容区为主，未登录用户可以浏览，登录后才允许发布和管理商品。

前端目标

1. 让未登录用户可以快速浏览市场和公告。
2. 让已登录用户可以低成本发布、修改、删除自己的商品。
3. 页面信息层级清楚，尽量减少学习成本。
4. 首页负责传达通知，市场负责浏览和搜索，我的商品负责管理。

全局结构

普通用户至少包含三个一级界面：

1. 首页 / 公告
2. 市场
3. 我的商品

管理员登录后包含四个一级界面：

1. 首页 / 公告
2. 市场
3. 我的商品
4. 审核

全局导航与通用模块

• 顶部导航栏固定展示网站名称、首页、市场、我的商品。
• 右上角展示登录状态。
• 未登录时显示“登录 / 注册”入口。
• 登录入口需要支持注册、验证码登录、密码登录三种操作路径。
• 已登录时显示当前邮箱账号，并提供退出登录。
• 如果当前登录用户是管理员，则顶部导航栏额外显示“审核”入口。
• 页面底部需要提供信息型页脚，可集中展示联系方式、二维码、项目仓库链接和友情链接。
• 页脚内容应保持低干扰，不与顶部导航和市场筛选抢占主要注意力。
• 页脚内容建议通过前端本地配置维护，便于替换反馈邮箱、社群二维码和外链地址。
• 页脚区块数量、顺序和标题应可配置，避免把“联系方式”“友情链接”等模块写死在代码里。
• 所有页面需要保留统一的留白、标题样式、按钮样式和卡片样式。
• 移动端导航可折叠，但核心入口不能隐藏过深。
• 前端页面路由由 TanStack Router 管理。
• 页面中的公告、商品、用户信息等异步数据由 TanStack Query 管理。

首页/公告

首页用于展示平台公告、使用须知和校内交易提醒。

页面内容

• 公告列表默认按照“置顶优先、再按时间倒序”排序。
• 已置顶公告排在最前面；多个置顶公告之间仍按发布时间倒序排列。
• 未置顶公告排在置顶公告之后，未置顶部分同样按发布时间倒序排列。
• 每条公告至少展示标题、发布时间、正文。
• 重要公告可以置顶或高亮展示。
• 首页顶部可以增加一小段平台介绍，例如“华南理工大学校内旧物交易平台”。
• 首页需要展示当前公开可见的出售商品数量、收购商品数量和已注册用户数量。
• 首页统计数量不包含“待审核”状态的商品。

交互要求

• 公告列表默认直接展开展示，不需要复杂操作就能阅读。
• 公告较多时支持分页或“加载更多”。
• 若当前没有公告，显示空状态提示，而不是空白页面。
• 管理员登录后，首页公告区域需要提供“发布公告”入口。
• 管理员可以直接在前端填写公告标题和正文并发布。
• 所有公告都需要提供“置顶”和“删除”操作按钮，且这些按钮仅管理员可见。
• 公告执行置顶、取消置顶、删除、发布后，列表需要立即刷新。

市场

市场页面是网站核心页面，用于浏览所有在售商品。

页面结构

• 顶部为搜索和筛选区域。
• 中间为商品列表区域。
• 商品列表使用图墙 / 卡片流布局。
• 商品列表默认按修改时间倒序排列，最近发布或最近修改的商品排在最前面。
• 商品列表需要支持按修改时间升序、修改时间降序、价格升序、价格降序切换排序。
• 每个商品卡片只展示第一张图片作为封面。
• 图片下方展示核心文字信息，建议至少包含商品标题、价格、交易类型、商品类型、校区、发布时间。
• 商品卡片不展示发布者姓名、昵称、邮箱账号等身份信息。

商品卡片要求

• 商品图片区域尽量保持统一比例，避免页面高低错乱。
• 商品标题最多展示两行，超出部分省略。
• 价格需要比普通文字更醒目。
• 校区标签以小标签或轻量徽标形式展示。
• 商品卡片需要展示“交易类型”和“商品类型”两个字段。
• 商品状态包含“在售”“待审核”“审核不通过”。
• 其中“待审核”和“审核不通过”状态都不在公开市场显示。
• 商品类型至少包含两个选项：

1. 活动票 / 讲座票
2. 其他

• 其中“活动票 / 讲座票”类型的商品仅登录用户可见，未登录用户在市场列表和详情页中都不能看到。
• 若商品已下架，不应继续出现在公开市场列表中。
• 管理员登录后，市场中的商品卡片需要额外出现“下架”按钮。
• 管理员点击“下架”后，商品状态应改为“审核不通过”，并立即从公开市场列表中消失。

搜索

• 支持按商品标题和商品内容关键词搜索。
• 搜索框应放在页面显眼位置。
• 输入关键词后可点击搜索按钮，也可按回车触发搜索。
• 搜索结果为空时，显示明确提示，例如“暂无相关商品”。

筛选

• 至少支持按校区筛选。
• 至少支持按交易类型筛选，交易类型包含“出售”“收购”。
• 需要支持按商品类型筛选，商品类型至少包含“活动票 / 讲座票”和“其他”。
• 未登录用户的商品类型筛选中不显示“活动票 / 讲座票”选项。
• 校区建议包含常用枚举值，例如五山校区、大学城校区、国际校区。
• 筛选条件切换后，商品列表应立即刷新。
• 排序条件切换后，商品列表应立即刷新，并在分页场景下保持全量顺序一致。
• 后续可预留更多筛选位，例如价格区间、更多商品分类。

商品详情展示

• 点击商品卡片后进入商品详情页或详情弹层。
• 详情中展示完整图片集、完整标题、正文描述、交易类型、商品类型、校区、发布时间、联系方式。
• 未登录用户也可以查看详情和联系方式。
• 但商品类型为“活动票 / 讲座票”的详情仅登录用户可见。
• 若联系方式较敏感，可在界面上提醒用户注意隐私与交易安全。

页面状态

• 首次加载需要有加载中状态。
• 搜索无结果、筛选无结果、系统错误都要有对应提示。
• 移动端下商品卡片应变为双列或单列，保证可读性。
• 商品列表、详情页和筛选结果页的 loading、error、empty 状态需要结合 TanStack Query 统一处理。
• 市场页需要支持分页，避免商品数量过多时页面过长。

我的商品

该页面仅对已登录用户开放，用于管理自己发布的商品。

我的商品列表

• 列表展示当前用户发布的所有商品。
• 列表按发布时间倒序排列，最近发布或最近修改的商品排在最前面。
• 每个商品使用独立卡片展示，内容包括封面、标题、价格、交易类型、商品类型、校区、发布时间、当前状态。
• 我的商品列表需要支持分页。
• 每个商品卡片至少包含两个操作：

1. 修改：进入编辑界面，允许修改商品内容。
2. 删除：从市场中删除商品，删除前需要二次确认。

发布按钮

• 页面上需要有明显的“发布商品”按钮。
• 点击后进入商品编辑 / 发布界面。

发布 / 编辑界面

• 支持上传多张图片。
• 支持填写商品标题。
• 支持填写商品描述内容。
• 支持填写价格。
• 支持选择交易类型，至少包含“出售”和“收购”。
• 支持选择商品类型，第一阶段至少包含“活动票 / 讲座票”和“其他”。
• 支持选择校区。
• 支持填写联系方式。
• 页面底部提供“立即发布”按钮。
• 如果是编辑已有商品，则按钮文案可变为“保存修改”。

表单要求

• 标题、内容、交易类型、商品类型、校区、联系方式为必填项。
• 图片至少上传一张。
• 提交前需要做基本表单校验，并给出明确报错提示。
• 提交中按钮应进入禁用或 loading 状态，避免重复提交。
• 新发布商品默认进入“待审核”状态。
• 用户修改了已有商品后，商品时间要同步更新，并重新进入“待审核”状态，直到审核通过后再公开显示。
• 用户修改了已有商品后，除了状态变为“待审核”，还需要重新进入审核队列，管理员应能在审核页中看到该商品。
• 发布成功后，需要明确提示成功，并返回“我的商品”或对应商品详情。

权限要求

• 未登录用户访问“我的商品”时，应提示先使用学校邮箱登录。
• 只有通过学校邮箱登录的用户才能发布商品。
• 用户只能修改和删除自己发布的商品，不能操作他人的商品。
• 前端需要结合 TanStack Router 做基础路由权限控制，并结合 TanStack Query 维护当前登录用户状态。

审核

该页面仅对管理员账号开放，用于处理所有“待审核”状态的商品。

审核列表

• 页面展示所有待审核商品。
• 列表按提交时间倒序排列，最近进入待审核的商品排在最前面。
• 每个待审核商品应展示封面、标题、价格、交易类型、商品类型、校区、发布时间、发布账号、联系方式和当前状态。
• 管理员需要能够快速看到商品标题、正文描述和联系方式，便于判断是否违规。

审核操作

• 每个待审核商品至少有两个审核操作：

1. 通过：商品状态改为“在售”，随后进入公开市场。
2. 拒绝：商品状态改为“审核不通过”，不进入公开市场，并记录审核结果。

• 如果后续需要，也可以增加“删除”或“封禁用户”等更高权限操作，但第一阶段不是必须。

权限要求

• 普通用户不能访问审核页面。
• 普通用户即使手动输入审核页面地址，也应被前端拦截并由后端拒绝。
• 只有管理员账号才能调用审核通过、审核拒绝等接口。

页面交互要求

• 审核页需要支持分页，避免待审核商品过多时页面过长。
• 如果没有待审核商品，显示明确的空状态提示。
• 审核操作成功后，列表应立即刷新。
• 审核操作失败时，需要给出明确错误提示。

建议补充的前端细节

• 增加统一的空状态设计，例如“还没有发布商品”“暂无公告”“没有找到相关商品”。
• 增加删除确认弹窗，避免误删。
• 增加图片上传预览，便于用户确认封面和顺序。
• 增加基础响应式设计，保证手机上也能顺畅使用。
• 增加基础反馈组件，例如成功提示、失败提示、加载骨架屏。
• 如果后续时间允许，可以补充商品分类、收藏、举报、公告编辑等扩展能力。