Extreme Programming Assignment(832402210 靳立一)

832402210Liyi Jin 832402210Liyi Jin 墨衍会员 · AI 创作全网分发 墨衍智能分发 通过墨衍一键同步至各平台 可同步平台 CSDN微信公众号微博知乎掘金百家号博客园抖音小红书 你的文章也可以这样分发 墨衍会员 ¥399起/年,写一次发全网 我也要 + 加入社区

Extreme Programming Assignment: Atlas Contacts — Favorites, Multiple Contact Methods, Excel Import/Export, and Alibaba Cloud Deployment

项目内容
本次作业课程2601_FZU-MU_SE
团队名称Atlas (xp-contacts-team)
作业要求极限编程(通讯录应用)
本次作业目标Implement the contacts app — favorites, multiple contact methods, Excel import/export — and practise XP collaboration, Git workflow and software engineering
MemberNameStudent IDGitHub
ALiyi Jin832402210https://github.com/Lucas-JIN-cloud@Lucas-JIN-cloud
BSiyang Cheng832401220https://github.com/fu-yi-hang@fu-yi-hang

Other references: GitHub xp-contacts-team/xp-contacts-app-v2; code style docs/code-style.md; live app http://120.55.102.189/.

This was a two-person XP project. We built a React + TypeScript frontend, a Python + SQLite backend, and a Docker/Nginx deployment on Alibaba Cloud ECS. I'm Liyi Jin (Member A, Student ID 832402210). This post records the work I did and how the two of us split the project.

Contents

ItemLink
GitHub repositoryhttps://github.com/xp-contacts-team/xp-contacts-app-v2
PR #1 — A platformhttps://github.com/xp-contacts-team/xp-contacts-app-v2/pull/1 (merged)
PR #2 — B producthttps://github.com/xp-contacts-team/xp-contacts-app-v2/pull/2 (merged)
PR #3 — CIhttps://github.com/xp-contacts-team/xp-contacts-app-v2/pull/3 (merged)
Live app (Alibaba Cloud ECS)http://120.55.102.189/
API status pagehttp://120.55.102.189/status.html
API health checkhttp://120.55.102.189/api/health
Code stylehttps://github.com/xp-contacts-team/xp-contacts-app-v2/blob/main/docs/code-style.md
Team divisionhttps://github.com/xp-contacts-team/xp-contacts-app-v2/blob/main/docs/team-division.md
Releasesv1.0.0 initial · v1.0.1 persistence-label fix

Tech stack:

  • Frontend: React 19 + TypeScript + Vite 8 + SheetJS
  • Backend: Python 3.12 standard library HTTP server + SQLite (no third-party dependencies)
  • Deployment: Docker Compose + Nginx on Alibaba Cloud ECS (Hangzhou)
  • Tests: Vitest + Testing Library (34 frontend tests), unittest (3 backend tests)

The app is deliberately small, but it covers a complete path: browser UI → REST API → SQLite → Docker volume → Nginx → public URL.

2. Commit History and Contributions

2.1 One shared repository, two authorship streams

We used one public repository instead of two forks, and split commits by file ownership:

  • A — platform and domain (7 commits): project configuration, domain model, Python API, SQLite, Docker/Nginx, Alibaba Cloud deployment, CI.
  • B — UI and data exchange (5 commits): React pages and styles, favorites view, multiple contact methods, Excel import/export, frontend tests, documentation.

Each member configured their own Git identity on their own machine. B's UI and Excel commits are authored by B's GitHub account; I did not push B's work under my name. This keeps git shortlog and the GitHub contributors graph meaningful.

Branches:

  • main: B's Initial commit + A0–A6 + B1–B5 after PR #1/#2/#3 merged
  • feat/a-platform: A0–A5, merged via PR #1
  • feat/b-product: A0–A2 + B1–B5, merged via PR #2
  • ci/verify: A0–A2 + A6, merged via PR #3 after CI passed

2.2 Commits uploaded by the team

#BranchAuthorCommitMessage
A0mainA0047a7cdchore: initialize repository and license
A1mainAfdf9c4b5chore: scaffold React + TypeScript + Vite project
A2mainA08f1a286feat(domain): add contact model, favorites, search, and local cache
A3feat/a-platformA852275d5feat(api): implement SQLite contacts REST API
A4feat/a-platformA779899a7test(api): cover repository validation and seed data
A5feat/a-platformA74da9441chore(deploy): add Docker/Nginx and Alibaba Cloud deployment
B1feat/b-productB38d8f964feat(ui): 搭建响应式通讯录界面与收藏视图
B2feat/b-productBdbb3ab34feat(contacts): implement multiple contact methods and detail view
B3feat/b-productB5865fa92feat(excel): implement Excel import and export
B4feat/b-productBd21bbf32test(ui): cover domain logic, Excel round-trip and UI flows
B5feat/b-productB1caca187docs: add project documentation
A6ci/verifyAc1eca55dci: add lint, test, and build workflow
PatchmainA6fb58daffix(ui): clarify that contacts persist in cloud SQLite

2.3 Branch graph

main:             B Initial ── A0 ── A1 ── A2 ── merge(PR #1) ── merge(PR #2) ── merge(PR #3)
feat/a-platform:                        └── A3 ── A4 ── A5            (merged)
feat/b-product:                         └── B1 ── B2 ── B3 ── B4 ── B5 (merged)
ci/verify:                              └── A6                        (merged)

All three PRs have been merged into main with merge commits, so the individual contributions remain visible. PR #3 (CI) was merged after its workflow passed against the merged application code; v1.0.0 was published, followed by the v1.0.1 patch that fixes the stale browser-only persistence label.

2.4 GitHub commit screenshots

img

feat/a-platform: A0–A5 authored by Liyi Jin (Member A; GitHub handle Lucas-JIN-cloud).

img

ci/verify: A6, the CI workflow commit.

img

main: PR #1, PR #2 and PR #3 merged with merge commits, followed by the v1.0.1 label fix; all feature commits and both authors remain visible.

img

feat/b-product: B1–B5 authored by Siyang Cheng (Member B; GitHub handle fu-yi-hang).

2.5 Commit counts

MemberGitHubFeature commitsMain scope
Liyi Jin (A, 832402210)https://github.com/Lucas-JIN-cloud@Lucas-JIN-cloud7Project configuration, domain model, Python API, SQLite, Docker/Nginx, Alibaba Cloud deployment, CI
Siyang Cheng (B, 832401220)https://github.com/fu-yi-hang@fu-yi-hang5React UI and styles, favorites view, multiple contact methods, Excel import/export, frontend tests, documentation

Both members exceed the individual minimum of three commits. A has 7 feature commits plus 1 post-release patch commit; B has 5. The repository has 12 feature commits, 3 merge commits, B's initial README commit and the v1.0.1 patch commit.

3. How the Features Work

This section explains where the data comes from, how it moves, and which rules matter. It is not a code listing.

3.1 Favorites (25 points)

A favorite is more than a yellow star. It touches the list, the detail panel, the sidebar, sorting and persistence.

  • Data: Contact.favorite: boolean; toggling also updates updatedAt.
  • Interaction: the star on a list card and the “Favorite / Favorited” button in the detail panel call the same toggleFavorite() logic.
  • View: the sidebar's “Favorites” view filters favorite === true; the all-contacts view supports sorting by name, last update and company.
  • Persistence: after a change, the full contact list is sent to PUT /api/contacts with a 400 ms debounce; localStorage is kept as a cache.
  • Reload: the app requests /api/contacts first; if the request fails it falls back to the local cache and shows a “changes are stored locally” warning.

My part was the data path: field, toggle function, API synchronization and SQLite write. B built the star, the favorites view and the visual feedback. Splitting the feature this way let both of us work in parallel.

3.2 Multiple contact methods (10 points)

Instead of four fixed fields, a contact owns an array:

interface ContactMethod {
  id: string
  kind: 'phone' | 'email' | 'social' | 'address'
  label: string
  value: string
}

One person can have two phone numbers, two email addresses, several social accounts and several addresses. Each entry has its own label: mobile, work, WeChat, home, etc.

  • Form: ContactForm.tsx groups methods by kind and supports add/remove; it validates the required name and email format.
  • Detail: ContactDetail.tsx groups methods by kind; phone numbers can be dialled, emails can be opened in a mail client, and every value can be copied.
  • Storage: the whole methods array is stored with the contact in SQLite.
  • Excel: each kind is expanded into “label + value” column pairs; the number of pairs is calculated from the contact with the most entries.

3.3 Excel export (25 points)

The export menu offers three actions: export all, export favorites, and download an import template.

Rules:

  • One contact per row.
  • Name, company, job title, favorite and notes each get a column.
  • Each contact method becomes a pair of columns: Phone 1 Label / Phone 1 Number / Phone 2 Label / Phone 2 Number ….
  • The number of pairs is not hard-coded. The exporter scans every contact, finds the maximum count per kind, and generates headers (at least two pairs).
  • The favorite column contains “Yes” or “No”.
  • The workbook contains a Contacts sheet and an Instructions sheet, with column widths and an auto-filter.

buildHeaders() calculates the columns, buildWorkbook() builds the workbook with SheetJS, and exportContactsToExcel() triggers the download. An empty address book still exports a valid header row.

A sample export is available here: Atlas-export-sample.xlsx.

3.4 Excel import (25 points)

Import is harder than export because users' spreadsheets rarely match our headers exactly.

  1. Drag or choose an .xlsx / .xls file, up to 10 MB.
  2. Read the file as an ArrayBuffer and locate the header row within the first ten rows.
  3. Normalize headers: trim spaces, remove full-width punctuation and parentheses, and accept Chinese/English synonyms.
  4. Parse each row into a ContactInput; rows without a name are reported as row-level errors.
  5. Preview the first five rows, the number of recognized contacts, and any ignored columns.
  6. Choose a duplicate strategy:
    • Smart merge: same name and at least one shared contact value; add new methods and update company/title/notes.
    • Skip duplicates: import only contacts that do not exist yet.
    • Add all: no duplicate detection.
  7. Write the result back to state and synchronize it to SQLite.

Supported headers include 姓名 / Name, 公司 / Company, 职位 / Job Title, 收藏 / Favorite, 电话1标签, 邮箱1地址, 社交1账号, 地址1详细地址, and simpler files with a single Phone or Email column. Unknown columns are ignored and reported instead of silently losing data.

img

3.5 Backend and database (my work)

server/app.py uses only the Python standard library — no Flask or FastAPI:

  • ThreadingHTTPServer exposes a small REST API.
  • SQLite stores contacts in a contacts table (id, name, data, updated_at); the full contact JSON lives in data.
  • GET /api/contacts returns all contacts.
  • PUT /api/contacts replaces the full list (used by the 400 ms frontend sync).
  • POST /api/contacts, PUT /api/contacts/{id} and DELETE /api/contacts/{id} support single-contact operations.
  • GET /api/health returns { status: 'ok', contacts: N }.
  • On first start, server/seed.json seeds ten demo contacts and writes a meta.seeded flag, so deleting all contacts and restarting does not bring the seed data back.

Persistence is handled by a Docker named volume:

atlas-contacts_atlas-data:/data/atlas.db

Restarting or rebuilding the containers does not lose data; only docker compose down -v removes the volume. I added a test contact, restarted the API container, confirmed the count stayed at 11, then deleted the test data.

3.6 UI and responsive layout (B's work)

  • Desktop: sidebar + contact list + detail panel.
  • Tablet: two columns.
  • Mobile: list plus a full-screen detail panel with a back button.
  • Shared CSS variables, cards, stars, empty states, toasts and dialogs.
  • Ctrl/⌘ + K focuses the search box; Esc closes dialogs.
  • No horizontal scrolling at 375 px.

3.7 Deployment

The request path is:

Browser
  → Nginx :80
      → /        static files from dist/
      → /api/*   Python API :8000
                     → SQLite /data/atlas.db

The app runs on an Alibaba Cloud ECS instance in Hangzhou (2 vCPU, 2 GiB, Ubuntu 22.04). Docker Compose starts two containers, api and web; Nginx proxies /api to the API. The live URL is:

http://120.55.102.189/

The health endpoint currently returns:

{"status":"ok","contacts":12}

The initial seed contains ten contacts; during integration we added two more test contacts, so the current database count is 12.

There is a deployment story worth recording. We first tried Alibaba Cloud OSS static website hosting. The files uploaded successfully, but OSS adds Content-Disposition: attachment to web content on its default domain, so opening the URL downloaded the HTML instead of rendering it. We switched to ECS + Nginx, which produced a genuinely browsable page. The details are in the deployment document.

4. Screenshots and Demo Video

4.1 Home and favorites

img

Real contacts from the deployed database: 12 contacts, 6 favorites. The selected profile is ly, with a social account and an address; all data comes from the SQLite-backed API.

img

The Favorites view filters the same live database to 6 starred contacts; lgx is selected and its saved address is visible.

4.2 New contact and multiple methods

img

The create form filled with ly from the live database. One contact can hold several phone numbers, emails, social accounts and addresses.

4.3 Excel import preview

img

Preview of the five real contacts in Atlas-import-real.xlsx; the recognized methods and duplicate strategy are shown before import.

4.4 Mobile

img

img

At 390 px the layout switches to a list plus a full-screen detail panel; ly keeps the same social account and address on mobile.

4.5 Public deployment

img

The ECS-hosted status page: 12 contacts, SQLite at /data/atlas.db, the Docker volume and Nginx :80.

4.6 Backend and deployment evidence (A)

img

The ECS instance is running Ubuntu 22.04 with 2 vCPU / 2 GiB and the public IP 120.55.102.189.

4.7 Full demo video

A 3:06 captioned screen recording is ready:

It covers the live home page, favorites, the new-contact form, Excel export, Excel import preview, and the deployment status page.

TimeScene
0:00–1:07Title and project/architecture overview
1:07–1:40Live home page with real contacts, then favorites
1:40–2:10New contact form with multiple methods
2:10–2:50Excel import preview and export
2:50–3:06ECS deployment status and closing card

5. Team Division

MemberRoleScopeFeature commits
Liyi Jin (A, 832402210)Platform and domainProject configuration, domain model (favorites/search/merge), Python API, SQLite, Docker/Nginx, Alibaba Cloud deployment, code style and division docs7
Siyang Cheng (B, 832401220)UI and data exchangeReact pages and styles, favorites view, multiple-method form/detail, Excel import/export, frontend tests, screenshots/video/blog layout5

What I did

  • Set up the project: Vite + React + TypeScript + ESLint + Prettier + pnpm workspace.
  • Wrote the domain layer: src/lib/contacts.ts (CRUD, search, sort, merge), src/lib/storage.ts (cache and malformed-data recovery), src/lib/api.ts (frontend/backend sync).
  • Wrote the backend: REST routes in server/app.py, SQLite schema/seed/full replacement, and three tests in server/test_app.py.
  • Built the deployment: Dockerfile.runtime, docker-compose.yml, nginx.conf, ECS security group/key/containers, and SQLite volume persistence.
  • Wrote documentation: code style, team division, Alibaba Cloud deployment guide, the technical sections of this post, and PSP-A.

What B did

  • Page skeleton, three-column layout, mobile breakpoints, CSS variables and component styling.
  • Contact list, search, detail grouping, star/favorites view, empty states, toasts and dialogs.
  • Create/edit form, dynamic multiple contact methods, labels and validation.
  • Excel export with dynamic columns, import parsing/preview/duplicate strategies.
  • 34 frontend tests, screenshot set, demo video and blog layout.

How we collaborated

  1. A pushed the base commits to main.
  2. A continued on feat/a-platform; B worked on feat/b-product from the same base.
  3. Each person only changes their own files; shared files (README, package.json) are discussed first.
  4. PR #1 was merged by B, PR #2 by A and PR #3 by B, all with Create a merge commit.
  5. CI passed on main; v1.0.0 was tagged and published, followed by the v1.0.1 label fix.

6. Contribution Evaluation

MemberMain contributionFeature commitsReviewShare
Liyi Jin (A, 832402210)Project configuration, domain model, API/SQLite, Docker/Nginx, cloud deployment7merged PR #250%
Siyang Cheng (B, 832401220)UI/styles, favorites, multiple methods, Excel, frontend tests, docs/video5merged PR #150%
Total12100%

Both members committed their own work: A has 7 commits, B has 5. The 50/50 split reflects the commit counts, module weight and the shared delivery work: A owns the backend/deployment/CI tracks; B owns the UI, Excel engine and delivery material. A merged B's PR #2 and B merged A's PR #1, so the cross-review requirement is represented in the merge history.

7. Problems We Hit and How We Solved Them

7.1 OSS uploaded files but the browser downloaded them

Symptom: The OSS upload succeeded, but opening the default OSS URL downloaded the HTML instead of rendering it.

Cause: Alibaba Cloud OSS adds Content-Disposition: attachment to web content on its default domain. Setting object metadata to inline did not override it.

Fix: We stopped spending time on OSS and moved to ECS + Docker Compose + Nginx, serving static files and proxying /api on the same host.

Result: http://120.55.102.189/ renders normally and /api/health returns 200.

7.2 Contacts could not live only in the browser

Symptom: The first version stored contacts only in localStorage; clearing the browser or switching devices lost them.

Fix: Added a Python API + SQLite backend. The frontend loads /api/contacts first and falls back to the local cache only when the API is unavailable; changes are synchronized after a 400 ms debounce. SQLite lives in a Docker named volume.

Result: Data survives container restarts, and clearing browser storage no longer deletes the address book.

7.3 Excel had a variable number of method columns

Symptom: One contact had three phone numbers, another had one; a fixed header would truncate data.

Fix: Before export, scan all contacts and calculate the maximum count per type, then generate label/value pairs dynamically. On import, parse numbered headers plus label/value suffixes and accept Chinese/English synonyms.

Result: Export → edit → import round-trips correctly; one contact per row, multiple columns per type, no mojibake.

7.4 Frontend state and API synchronization timing

Symptom: Repeated star clicks triggered multiple writes; a network failure could leave the UI and database out of sync.

Fix: 400 ms debounce, one PUT /api/contacts with the full list, a visible “sync failed, changes are local” banner, and a retry button. The app still prefers the API on startup and falls back to localStorage only when needed.

Result: Normal operation stays consistent after refresh/restart; offline edits remain usable and can be retried.

7.5 SSH could not reach the ECS instance

Symptom: The instance was running and port 22 was reachable, but SSH returned Permission denied (publickey); after binding the key and rebooting, the connection briefly timed out.

Cause: The instance had not been bound to the atlas-deploy key; the security group allowed 22 only from the VPC CIDR 192.168.0.0/16; the instance was restarting.

Fix: Bound the key in the ECS console and restarted the instance; added a temporary 22/22 inbound rule from 0.0.0.0/0; waited for the reboot to finish.

Result: SSH worked and Docker Compose deployed the app. For production, SSH should be restricted to a personal IP.

8. PSP Tables

The actual minutes are based on this development cycle. B's table should be confirmed by B before publishing.

8.1 PSP — Liyi Jin (Member A, 832402210)

PhaseTaskEstimated (min)Actual (min)VarianceNotes
PlanningRead the assignment, choose the stack and split2025+5React + Python/SQLite
PlanningRepository, API/data model, code style4045+5Freeze the model and API first
DesignDirectory layout, SQLite schema, REST routes, Excel column mapping3035+5Design import rules with the columns
DevelopmentProject configuration (Vite/TS/ESLint/Prettier/pnpm)4050+10Windows/pnpm dependency issues
DevelopmentPython standard-library REST API + SQLite persistence90125+35Connection closing, seed flag, full replacement
DevelopmentSeed data, health check, full-replacement endpoint3040+10Health check useful for deployment
TestingBackend unit tests + API checks4560+15Seed/replace/delete/invalid data
DeploymentDockerfile / Compose / Nginx7085+15Runtime image vs. full build image
DeploymentECS, security group, volume persistence80100+20Key binding, port 22, Compose
DeploymentPublic smoke test + restart persistence check3040+10Restarted API, count stayed at 11, then cleaned up
IntegrationFrontend/API integration, cache/timing fixes5065+15Sync failure banner and retry
ReviewReview B's PR (scope, build, tests)3040+10Focus on file boundaries and build
DocumentationDeployment doc, division plan, blog technical sections, PSP6090+30Recorded deployment pitfalls
Total615800+185About 13.3 hours

8.2 PSP — Siyang Cheng (Member B, 832401220)

PhaseTaskEstimated (min)Actual (min)VarianceNotes
PlanningRead the assignment, choose interaction approach and split20200Page structure first
PlanningReview API/data model, page information architecture30300Align fields with A
DesignWireframes, colours, component list, breakpoints3035+5Three columns → two → one
DevelopmentPage skeleton, layout, style system80800CSS variables, cards, empty states
DevelopmentList/search/detail/multiple methods70700Grouping, dialling, copying
DevelopmentFavorites interaction, view, count and sort6065+5Star, filter, count
DevelopmentCreate/edit form, multiple-method validation8085+5Add/remove, email validation
DevelopmentExcel export (dynamic columns, styles, template)9095+5Dynamic column count
DevelopmentExcel import (headers, preview, duplicate strategy)110115+5Chinese/English headers, row errors
TestingFrontend unit/component tests + manual regression6070+1034 tests
IntegrationAPI integration, cache/timing fixes5055+5Debounce and retry
DeploymentPublic smoke test and screenshots3035+5Seven screenshots
ReviewReview A's PR2530+5API/deployment files
DocumentationVideo recording, screenshots, blog layout, PSP1001000Recording and formatting
Total835885+50About 14.8 hours

9. Self-check

ItemStatus
Markdown blogYes
Opening assignment information tableYes — course/team/assignment/goal
Both members code; at least 3 commits eachA 7 / B 5
Cloud deploymentYes — http://120.55.102.189/
Table of contentsYes
GitHub repository linkYes (public)
Code style linkYes
Commit history screenshot + per-member countsA 7 / B 5 captured (A-05, A-06, A-07, B-01)
Feature implementation explanationYes
Program screenshotsYes — 7 live-data screenshots (home, favorites, form, import, mobile x2, deploy)
Complete demo videoYes — 3:06 captioned MP4
Team divisionYes
Contribution total 10050% / 50%, total 100%
PR / merge / releasePR #1/#2/#3 merged; CI passed; v1.0.0 + v1.0.1 released
3–5 real problems and solutionsYes
One PSP table per memberYes
Public cloud URLYes

10. Closing Thoughts

The most valuable part of this assignment was not adding features one by one, but connecting the whole path: data model → pure domain functions → API/SQLite → frontend state → Excel exchange → Docker/Nginx → public access. Favorites, multiple methods and Excel are not difficult in isolation; the hard part is keeping data consistent when they all exist at once, surviving refresh, avoiding duplicates on import, and producing a page that actually opens from the public internet.

XP's “small commits, continuous testing, collective code ownership” became concrete rules for us: split commits by file boundary, review each other's PRs, preserve history with merge commits, and run tests after every change. Being able to explain each other's code matters more than the commit count.

...全文
评论
收藏 已收藏
分享
返回顶部