Extreme Programming Assignment: StarNote Contact Manager (Backend Data Layer & Repository Management)

Table of Contents

• 1. Project Links
• 2. Requirements & Overall Design
• 3. Core Implementation (Data Layer & Excel I/O)
• 4. Frontend UI & Integration
• 5. Program Screenshots
• 6. Demo Video
• 7. Git Collaboration Evidence
• 8. Team Division & Contribution Ratio
• 9. Problems Encountered & Solutions
• 10. PSP Table
• 11. Summary & Reflection

1. Project Links

How to Run

The project uses a zero-build lightweight architecture. Data persistence runs on browser localStorage, and Excel parsing runs locally via SheetJS.

Option 1: Open Directly

Double-click index.html in the repository root directory.

Option 2: Local Static Server (Recommended)

cd address-book
python -m http.server 5173

Open http://localhost:5173 in a browser.

Reading and writing .xlsx files relies on SheetJS 0.20.3 via CDN, so an internet connection is needed on first load.

2. Requirements & Overall Design

2.1 Requirement Breakdown

The assignment specifies three main functional requirements, which we split into verifiable subtasks:

The grading rubric also covers a usable UI (10 points), Git collaboration (at least 3 commits, PR, Release), and individual blog posts.

2.2 Tech Stack & Frontend/Backend Boundary

Yifan Ye and I agreed not to introduce heavy build tools or a standalone database server so the grader can open and verify the app right away. Even so, we split the codebase along a clean frontend/backend boundary:

2.3 Data Model Design

My main design problem on the data side was how to represent multiple contact methods for one person. Flat fields like phone, email, and wechat break down as soon as someone has two mobile numbers or a custom social handle. I moved all contact entries into a methods array:

{
  id: "uuid",
  name: "林晓",
  company: "星河科技",
  job: "产品经理",
  tags: "客户, 重点",
  notes: "负责年度项目对接",
  favorite: true,            // Boolean favorite flag
  methods: [                 // Unbounded array of contact methods
    { type: "手机", value: "138 0013 8000" },
    { type: "邮箱", value: "lin.xiao@example.com" },
    { type: "微信", value: "linxiao-tech" }
  ]
}

2.4 Module Architecture

Separating data logic from DOM rendering let Yifan Ye adjust CSS and form behavior without touching my Excel parsing code. Integration only needed a shared agreement on the contacts array and save().

3. Core Implementation (Data Layer & Excel I/O)

3.1 Favorite State Storage & Filtering

Instead of maintaining a separate table of favorite IDs, I stored favorite as a boolean property inside each contact object. Deleting a contact automatically cleans up its favorite state without leaving orphaned records.

When the user clicks the star icon, the logic flips c.favorite, calls save() to persist to localStorage, and triggers a re-render:

const c = contacts.find(x => x.id === star.dataset.star);
c.favorite = !c.favorite;
save();

View filtering and keyword search run in the same filter pipeline so switching between "All" and "Favorites" composes cleanly with the search box:

let list = contacts.filter(c =>
  (filter === 'all' || c.favorite) &&
  (!q || [c.name, c.company, c.job, c.tags, ...c.methods.map(m => m.value)]
          .join(' ').toLowerCase().includes(q))
);

3.2 Excel Import & Export (25 Points)

This was the heaviest part of the backend logic, focused on mapping between a flat spreadsheet table and our nested methods array.

Column Schema

The assignment requires one row per contact. To flatten methods into a single row, I used Chinese column headers and joined multiple entries of the same type with a Chinese semicolon (；). Non-preset types are grouped under "其他联系方式" in type:value format:

Export Implementation

Each contact object is mapped to a flat row object and passed to SheetJS to build and download the workbook:

const rows = contacts.map(c => ({
  姓名: c.name,
  公司: c.company,
  职位: c.job,
  标签: c.tags,
  收藏: c.favorite ? '是' : '否',
  手机: c.methods.filter(m => m.type === '手机').map(m => m.value).join('；'),
  邮箱: c.methods.filter(m => m.type === '邮箱').map(m => m.value).join('；'),
  微信: c.methods.filter(m => m.type === '微信').map(m => m.value).join('；'),
  其他联系方式: c.methods
      .filter(m => !['手机', '邮箱', '微信'].includes(m.type))
      .map(m => `${m.type}:${m.value}`).join('；'),
  备注: c.notes
}));

const ws = XLSX.utils.json_to_sheet(rows);
const wb = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(wb, ws, '联系人');
XLSX.writeFile(wb, `星笺联系人-${exportStamp()}.xlsx`);

Timestamped Export Filenames

During testing, exporting twice with a fixed filename caused the browser to append (1) and (2), making it hard to tell which file was newer. I added exportStamp() to append YYYYMMDD-HHmm to the filename:

function exportStamp(d = new Date()) {
  const p = n => String(n).padStart(2, '0');
  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}` +
         `-${p(d.getHours())}${p(d.getMinutes())}`;
}

Import Parsing & Error Handling

On import, FileReader loads the file as an ArrayBuffer, and XLSX.utils.sheet_to_json converts the first sheet back into our internal structure:

const wb = XLSX.read(ev.target.result, { type: 'array' });
const rows = XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]], { defval: '' });

const imported = rows.filter(x => x.姓名).map(x => ({
  id: crypto.randomUUID(),
  name: String(x.姓名),
  company: String(x.公司 || ''),
  // ...
  favorite: String(x.收藏) === '是',
  methods: [
    ['手机', x.手机], ['邮箱', x.邮箱], ['微信', x.微信], ['其他', x.其他联系方式]
  ].filter(([, v]) => v).map(([type, value]) => ({ type, value: String(value) }))
}));

Three safeguards protect against bad input:

1. Rows without a 姓名 value are skipped so nameless records are never created.
2. Wrapping the parser in try...catch catches corrupted or non-.xlsx files, shows an error prompt, and leaves existing contacts intact.
3. Missing optional columns fall back to || '' so undefined never appears in the UI.

3.3 Data Safety & Persistence

Every write operation (add, edit, delete, favorite toggle, Excel import) goes through save() to serialize contacts into localStorage. Because the frontend builds card HTML via innerHTML, I added esc() in the utility layer to escape &, <, >, ", and ' before rendering user input.

4. Frontend UI & Integration

Yifan Ye built the frontend interface using a classic two-column layout (left navigation sidebar + right main workspace):

• Color Palette: Deep green (#163b2c) primary accent paired with soft mint (#d5efe1) and an off-white background to keep text readable without visual clutter.
• Dynamic Forms & Card Truncation: The modal uses <template> cloning to add/remove contact method rows and strips empty rows on submit. Cards display up to 4 contact methods and collapse extras into a summary line so card heights stay uniform.
• Responsive Layout: Below 750px width, the sidebar collapses to an icon strip and the two-column form stacks into a single column.

5. Program Screenshots

5.1 Initial Empty State

5.2 Contact List & Statistics

Shows 3 contacts, 2 favorites, and 8 contact methods in the summary bar, along with multi-type methods on each card.

5.3 Editing Multiple Contact Methods

Contact "林晓" holds phone, email, and WeChat entries at the same time, with an option to append more rows.

5.4 Favorites Filter

Clicking "我的收藏" in the left sidebar filters the grid down to starred contacts only.

5.5 Search

6. Demo Video

The full demo video is committed in the repository:

• Repository file: evidence/星笺联系人演示视频.mp4
• Direct download: https://raw.githubusercontent.com/alemanhong-cmyk/address-book/main/evidence/%E6%98%9F%E7%AC%BA%E8%81%94%E7%B3%BB%E4%BA%BA%E6%BC%94%E7%A4%BA%E8%A7%86%E9%A2%91.mp4

The walkthrough covers:

1. Opening the app to show the empty state and counters
2. Viewing the contact list and multiple contact methods
3. Opening the edit modal to inspect three methods on one contact
4. Toggling the favorite star and switching to the Favorites view
5. Filtering contacts with the search bar
6. Exporting to Excel and checking the column layout
7. Deleting data and restoring it via Excel import
8. Refreshing the browser to verify localStorage persistence

7. Git Collaboration Evidence

7.1 Commit History

7.2 Repository Overview

7.3 Commit Statistics

The repository has 10 commits, 2 branches, 1 tag, and 2 contributors, meeting the minimum 3-commit requirement.

Note on Commit Distribution: During pair development, Yifan Ye implemented the frontend UI and interactions while I (Boyu Xu) implemented the backend data layer and Excel I/O. To avoid merge conflicts on a single-file static bundle, we integrated and tested both parts locally first, and I (alemanhong-cmyk) handled the unified upload, documentation, and Release on GitHub while Yifan Ye (Remisuki) committed the MIT LICENSE and reviewed the docs. Thus, the commit count is concentrated on my account even though the actual coding workload was shared.

7.4 Collaboration Workflow

Our workflow is documented in CONTRIBUTING.md:

1. Keep main runnable at all times and develop features on feature/* branches
2. Prefix commit messages with feat:, fix:, or docs:
3. Open a Pull Request for peer review before merging
4. Verify all items T01 to T11 in TEST_PLAN.md before merge
5. Tag milestones and publish a GitHub Release

7.5 Pull Request & Release

• PR #1: feat: 导出文件名增加时间戳并补充 v1.0.0 发布说明
  https://github.com/alemanhong-cmyk/address-book/pull/1
• Release v1.0.0:
  https://github.com/alemanhong-cmyk/address-book/releases/tag/v1.0.0

8. Team Division & Contribution Ratio

The 50/50 split reflects the actual coding workload rather than the commit count. Because the two halves were merged into a single static bundle before being pushed, the Git graph is concentrated on one account — see the note under 7.3 for the full explanation.

9. Problems Encountered & Solutions

Issue 1: Modeling Multiple Contact Methods per Person

Symptom: Using fixed fields (phone, email, wechat) made it impossible to store two mobile numbers or a custom social account.

Solution: Switched to a methods array of { type, value } objects. The dropdown lists common types with an "Other" fallback, so new types require no schema changes.

Issue 2: Data Lost on Page Refresh

Symptom: Early versions kept contacts only in memory, so pressing F5 wiped everything.

Solution: Routed all mutations (create, edit, delete, star toggle, import) through save() to serialize the array into localStorage, and added JSON.parse(... || '[]') on startup.

Issue 3: Losing Extra Numbers During Excel Round-Trip

Symptom: Exporting joined multiple phone numbers into one cell, but the initial import parser only read the first entry.

Solution: Standardized on the Chinese semicolon (；) as the delimiter for both export and import, and documented the type:value format for the "其他联系方式" column in the README.

Issue 4: Identical Filenames on Repeated Exports

Symptom: Exporting twice produced (1) and (2) browser suffixes, making it hard to identify the latest file.

Solution: Added exportStamp() to generate YYYYMMDD-HHmm timestamps, checked syntax with node --check, and verified output formatting as 星笺联系人-20261115-1405.xlsx.

Issue 5: Git Push Failures & Windows SSL Error

Symptom: git push failed with error: failed to push some refs, followed by Windows schannel reporting SEC_E_NO_CREDENTIALS.

Solution: Replaced a placeholder remote URL via git remote set-url, renamed local master to main via git branch -M main, and switched SSL backend with git config http.sslBackend openssl.

10. PSP Tables

10.1 Boyu Xu (Data Layer & Repo Management)

10.2 Yifan Ye (Frontend UI & Verification)

11. Summary & Reflection

Working on the backend data layer and repository management gave me three concrete takeaways:

First, data modeling sets the ceiling for flexibility. Starting with fixed fields forced a rewrite halfway through once multiple numbers per person came up. That rework accounts for the extra time in my design phase.

Second, import and export must be strictly symmetric. Column names, delimiters (；), and missing-column fallbacks have to match on both sides, otherwise an exported file cannot be re-imported cleanly.

Third, centralizing Git uploads hides individual commit history. Having me upload the integrated code avoided merge conflicts, but it made the commit graph look one-sided even though Yifan Ye wrote the frontend locally. On future pair projects, splitting the codebase into separate files (storage.js, excel.js, ui.js) from day one will let both partners push to their own feature/* branches and open PRs independently.

References

• Assignment Post: https://bbs.csdn.net/topics/620593436
• Course Forum: https://bbs.csdn.net/forums/2601_MU_SE_FZU
• SheetJS Documentation: https://docs.sheetjs.com/
• MDN localStorage: https://developer.mozilla.org/zh-CN/docs/Web/API/Window/localStorage