# 软件工程 **Repository Path**: mo-gaoqiang/software-engineering ## Basic Information - **Project Name**: 软件工程 - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-14 - **Last Updated**: 2026-09-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 校园活动报名与场地设备调度系统 > 软件工程课程设计 · 第 10 组 ## 课题 学生社团办活动需要报名、借场地、借设备、记志愿者工时。平台让社团发起活动收报名，向场地管理方申请借用并调度设备，活动结束后结算志愿者工时并发积分券，形成完整闭环。 ## 子系统划分（v2.0 架构改判：每子系统 = 一个微服务 + 一个库 + 一个前端子应用） | 子系统 | 名称 | 责任人 | 主导日 | 服务目录（进程/宿主端口/库） | 前端子应用 | |---|---|---|---|---|---| | S1 | 场地与设备 | 朱志鹏（产品经理） | D1 | `backend/services/s1_venue/`（8081 / `se_s1`） | `frontend/apps/s1_venue/` | | S2 | 活动与报名 | 莫高强（配置管理员） | D3 | `backend/services/s2_activity/`（8082 / `se_s2`） | `frontend/apps/s2_activity/` | | S3 | 借用审批与设备调度 | 吴腥（测试经理） | D4 | `backend/services/s3_borrow/`（8083 / `se_s3`） | `frontend/apps/s3_borrow/` | | S4 | 志愿者工时与积分券 | 潘宏捷（架构师） | D2 | `backend/services/s4_volunteer/`（8084 / `se_s4`） | `frontend/apps/s4_volunteer/` | | S5 | 用户与看板（最薄） | 李林峰（项目经理） | D5 | `backend/services/s5_user/`（8085 / `se_s5`） | `frontend/apps/s5_user/` | > 架构形态与决策依据见《技术路线说明》**v2.0** 与《统一约定》**v1.1**：五服务微服务（一服务一库一实例，MySQL 容器 `mysql-s1`~`mysql-s5` 宿主 3307~3311）+ Nginx 网关 8080（对外=契约 `servers`，不变）+ qiankun 微前端（`frontend/shell` 基座 + 5 子应用）。D3 起每人只写自己的 `services/sX/` + `apps/sX/` + `db/sX_schema.sql`，互不打扰。 一次创建活动由 S2 **同步编排（Saga）**扇出到 **S3、S4** 落库（任一失败补偿归零、活动不落库，对外语义见台账 §八 L11/L12）；场地预占（S1）在发布 T2 触发。 ## 目录结构 ``` software-engineering/ ├── README.md # 本文件 ├── .gitignore # Git 忽略规则 ├── docker-compose.yml # 本地一键启动（D3 起维护） │ ├── api/ # 接口契约（全组共享，架构师维护） │ ├── openapi.yaml # 冻结的 API 契约（唯一事实源） │ └── api-changelog.md # 接口变更记录（B5 变更单留痕） │ ├── db/ # 数据库脚本（一服务一库：D3 起按服务拆分） │ ├── s1_schema.sql ~ s5_schema.sql # 各服务建表语句（各负责人所有；留痕表 DDL 用架构师模板） │ ├── s1_seed.sql ~ s5_seed.sql # 各服务种子数据（跨库引用 ID 冻结成约定） │ └── schema.sql / seed.sql # D2 旧共库版（D3 拆分后退役） │ ├── docs/ # 文档 │ ├── A1-需求/ # 五人需求文档（D1 产物） │ ├── A2-设计/ # 五人设计文档（D2 产物） │ ├── A2-2-统一约定/ # 架构师统一约定（鉴权/响应/错误码/分页/架构形态） │ └── evidence/ # 证据截图（AI 留痕、安全审查、前后对比） │ ├── backend/ # 五服务微服务后端（FastAPI；D3 重组完成：modules/ 已退役） │ ├── common/ # 服务公共件（架构师维护）：resp / auth / http_client / config / pagination / db │ ├── services/ # s1_venue / s2_activity / s3_borrow / s4_volunteer / s5_user │ │ # 每服务五件：main.py（独立进程）+ router / service / models / schemas │ ├── tests/ # pytest：common 单测 + 按服务一目录信封冒烟（78 用例） │ ├── Dockerfile # 五服务共用镜像（ARG SERVICE） │ └── requirements.txt # 后端依赖（Python 3.12 + FastAPI，全服务共用） │ ├── frontend/ # 微前端（qiankun，D3 骨架落地） │ ├── shell/ # qiankun 基座（架构师维护）：登录态 / 布局菜单 / 子应用注册 —— dev 5173 │ ├── common/ # request.ts 拦截器样板与信封类型（架构师维护，子应用复制式引用） │ ├── apps/ # s1_venue / … / s5_user：各负责人独占 —— dev 5174~5178 │ └── Dockerfile # web 容器多阶段构建（7 包独立构建 → Nginx 托管） │ ├── deploy/ # 编排配套配置（与 compose 同笔提交，配置管理员维护） │ ├── gateway/nginx.conf # 网关静态前缀路由表（/api/internal/* 不出网） │ └── web/nginx.conf # shell 托管 + 子应用 /sX/ 静态前缀 + /api 反代网关 │ ├── scripts/ # 运维脚本 │ └── reset-demo.sh # 重置演示数据（按服务连各自 mysql-sX，S1→S5 序） │ ├── tests/ # 集成测试 │ └── smoke.sh # 冒烟测试（配置管理员维护；SERVICES_BASE 直连 / BASE 网关双模式） ├── demo-script.md # D5 答辩演示脚本（可复现，每步带预期结果与勾选项） └── verify.sh # 一键自查关卡（①后端 ②前端 ③契约一致 ④五服务冒烟） ``` > 📌 **D3 骨架重组已完成（2026-09-15，架构师执行；台账 §八 L12 落地）**：`backend/app/modules/` 单体骨架已平移退役为 `backend/services/`（一服务一进程一库）+ `backend/common/` 公共件（错误码跟版统一约定 v1.1-r3 五位数字）；`db/schema.sql` / `seed.sql` 已拆为 `db/sX_schema.sql` / `db/sX_seed.sql`（旧文件加退役横幅留档）；`docker-compose.yml` 12 容器编排（`mysql-s1`~`mysql-s5` + `gateway` + `s1`~`s5` + `web`，含单人 profiles 与 Prism mock）已落地；前端 qiankun 基座 + 五子应用骨架（dev 5173~5178）已就绪。**各负责人从各自的 501 桩开始填业务实现**，上手步骤见《docs/项目管理/开发上手指南_v1.0.md》。 ## 分支规范 - `main`：主干分支，只收评审通过的改动（PR 合并，或经当日主导人确认后直推）。**禁止 force push**、禁止直接改他人子系统目录。 > ⚠️ 截至 2026-09-14，Gitee 后台**尚未开启分支保护规则**（技术上仍可直推），目前靠本条约定约束；如需强制保护，请仓库管理员在仓库设置里开启。 - `feat/<子系统>-<简述>`：功能分支，例：`feat/s2-activity-create` - `fix/<子系统>-<简述>`：缺陷修复分支，例：`fix/s2-registration-capacity` ## 提交信息规范 格式：`(): ` | type | 用途 | |---|---| | feat | 新功能 | | fix | 缺陷修复 | | docs | 文档 | | refactor | 重构（不改行为） | | test | 测试 | | contract | 接口契约变更（`api/openapi.yaml`，须同步登 `api/api-changelog.md`） | | chore | 构建/杂项 | - subject 用祈使句、≤50 字、结尾不加句号 - 一次提交只做一件事；涉及缺陷单的在正文写 `Ref: D-0007`；涉及接口契约变更的在正文写 `Ref: api-changelog vX.Y` ## 各子系统内部约定 每个子系统目录内自行组织代码结构（前后端分离、分层等），但需遵循架构师在 `docs/A2-2-统一约定/` 中冻结的统一规范（鉴权方式、响应格式、错误码、分页参数等）。 ## 快速开始（D3 骨架已落地） > 五服务微服务 + 一服务一库（《技术路线说明》v2.0）：12 容器编排已随 D3 骨架落地。 > 鉴权两姿态：默认 `local`（本地验签，单人栈友好）；全栈联调/演示用 `AUTH_VERIFY_MODE=http` > （S1~S4 经 S5 `verify` 校验账号态，S5 不可用即 503、严禁降级 401，统一约定 §4.1）。 ```bash # 克隆仓库 git clone https://gitee.com/mo-gaoqiang/software-engineering.git cd software-engineering # ===== 全栈 12 容器（mysql-s1~s5 + gateway + s1~s5 + web）===== docker compose --profile full up -d # 全链路鉴权姿态（可选）：AUTH_VERIFY_MODE=http docker compose --profile full up -d # 网关 8080 = 契约对外入口；web 8090 = 前端；直连各服务 8081~8085；五库 3307~3311 # ===== 单人只起本服务栈（示例 S4 负责人 = mysql-s4 + s4，无需起全栈）===== docker compose --profile s4 up -d # ===== 契约 mock（消费方未就绪时，按 api/openapi.yaml 起 Prism，4010）===== docker compose --profile mock up -d # ===== 不用 Docker：后端本地起单个服务（骨架期不触库即可起；示例 S4）===== cd backend && uvicorn services.s4_volunteer.main:app --host 0.0.0.0 --port 8084 --reload # ===== 前端：基座 + 子应用各自 vite dev（建议开 6 个终端）===== cd frontend/shell && npm ci && npm run dev # 基座 5173 cd frontend/apps/s4_volunteer && npm ci && npm run dev # 子应用 5174~5178（各负责人自己的） # ===== 一键自查关卡（提交 / 合并前必跑：后端单测 + 前端 7 包构建 + 契约一致 + 五服务冒烟）===== bash verify.sh # ===== 答辩演示：按脚本逐步操作，每步带预期结果（见 demo-script.md）===== # 起栈自检：docker compose --profile full up -d && bash scripts/reset-demo.sh && bash verify.sh # 重置演示数据（按服务连各自 mysql-sX；跨库引用 ID 冻结成约定） bash scripts/reset-demo.sh ```