**

前后端分离计算器系统 | Front-End/Back-End Separation Calculator (832401126)

Front-End / Back-End Separation Calculator System — Assignment Blog

目录

---

1. Git Repository Link and Code Standards Link

Item	Link
Frontend Repository	https://github.com/**Tribulati0n**/832401126_calculator_frontend
Backend Repository	https://github.com/**Tribulati0n**/832401126_calculator_backend
Frontend Code Standard	https://github.com/**Tribulati0n**/832401126_calculator_frontend/blob/main/codestyle.md
Backend Code Standard	https://github.com/**Tribulati0n**/832401126_calculator_backend/blob/main/codestyle.md

---

2. PSP Table

Time recorded before implementation (estimated) and after implementation (actual).

Module	Planned (min)	Actual (min)
Requirement analysis	30	35
System design (architecture, API, database)	40	45
Expression calculation module (lexer / parser / evaluator)	90	100
Back-end development (API + services)	60	70
Database design & history module	50	45
Front-end development (UI + interaction)	120	130
Front-end / back-end integration	40	35
Testing (unit tests + API tests + manual)	50	45
Deployment & configuration	30	25
Screenshots / demo recording	30	40
Blog writing	90	85
Total	630	655

---

3. Assignment Description

The task is to build a calculator system based on a front-end / back-end separation architecture. The client only takes care of user interaction and information display, while the server is responsible for calculation, expression processing, data validation, exception handling and database operations. The two parts communicate through HTTP/JSON APIs.

Core requirements:

1. Basic calculation — at least + − × ÷; the front end sends {"expression": "12+8"} and displays the result the back end returns. The front end must not compute the result itself.
2. Compound expression calculation — operator precedence, parentheses, unary +/-, decimals, invalid-expression handling, division-by-zero handling. The calculation must happen on the back end.
3. Calculation history — every successful calculation is stored in a back-end database (expression, result, created_at); history is fetched from the database and survives refresh/restart.
4. Delete history — delete one record by id (and optionally clear all) through a back-end API; the database row must actually be removed.
5. Security — eval / exec / equivalent arbitrary-code execution is prohibited. I implemented a hand-written lexer → recursive-descent parser → AST evaluator pipeline.

Technology choices: Flask + SQLite (back end), vanilla HTML/CSS/JS (front end), deployed as two independent services. The full stack is documented in each repository's README.

---

4. Presentation of the Finished Product

4.1 Main calculator interface

The main page is split into two panels: the calculator (display + keypad + collapsible scientific panel) on the left, and the calculation history panel on the right. The status chip in the header shows whether the back end is reachable.

4.2 Addition

12 + 8 — the front end sends the expression, the back end computes 20 and stores it, the front end displays 12+8 = 20.

4.3 Subtraction

12 − 8 = 4.

4.4 Multiplication

5 × 8 = 40. The UI shows ×, the API payload uses * (5*8), and the back end normalizes both.

4.5 Division

10 ÷ 2 = 5.

4.6 Decimal calculation

0.1 + 0.2 = 0.3 — floating-point noise is rounded away by the result formatter on the back end.

4.7 Compound expression & operator precedence

1 + 2 × 3 = 7 — multiplication binds tighter than addition.

4.8 Parentheses

(1 + 2) × 3 = 9 — parentheses override precedence.

4.9 Unary positive / negative numbers

−5 + 8 = 3. The parser treats a leading − as a unary negation node.

4.10 Invalid expression handling

An incomplete expression such as 1+ is rejected by the back end with a clear message and HTTP 400; the front end shows the error banner.

4.11 Division by zero handling

1 ÷ 0 returns Division by zero instead of crashing the server.

4.12 Calculation history

Every successful calculation is appended to the history panel with expression, result and time — read from the back-end database.

4.13 History persistence after refresh

The page was fully reloaded; all records are still there because they live in the back-end SQLite database, not in browser storage.

4.14 Delete a specified history record

Clicking ✕ sends DELETE /api/history/{id}; the record count drops from 8 to 7 and the list is re-fetched from the database.

4.15 History search (extension)

Typing 2 in the search box queries the back end (GET /api/history?q=2) and shows only the 6 records whose expression contains 2.

4.16 Scientific functions (extension)

Scientific panel with sin(30) = 0.5 (degrees).

sqrt(16) = 4 and 5! = 120 (postfix factorial) also run through the same back-end engine.

4.17 Theme switching (extension)

One click switches between light and dark themes (CSS custom properties, preference persisted in localStorage).

4.18 Keyboard input (extension)

The whole keypad is usable from the keyboard: digits, operators, Enter/= to evaluate, Backspace, Esc to clear. The demo GIF below shows 12+8= typed entirely with the keyboard.

4.19 Back-end offline behavior (separation verification)

With the back-end service stopped, the UI stays fully interactive, the status chip turns red, and any attempt to calculate shows “Cannot reach the back end…” — the front end cannot obtain a new valid result on its own, which proves the calculation really lives on the back end.

---

5. Design and Implementation Process

5.1 Requirement analysis

• Functional requirements: basic arithmetic, compound expressions with correct mathematical rules, history persistence, history deletion (single + clear-all), plus usable extras (scientific functions, keyboard, theme, search, connectivity indicator).
• Architectural requirement (the core of this assignment): front-end and back-end separation over HTTP/JSON; the back end must perform validation, parsing, calculation, exception handling and database operations; the front end must not compute results.
• Non-functional requirements: no eval/exec; data survives refresh and restart; the project must be deployable so teaching assistants can check it.

5.2 Overall system architecture

┌─────────────────────┐        HTTP/JSON        ┌──────────────────────┐        ┌──────────┐
│   Front End         │  POST /api/calculate    │   Back End (Flask)   │  SQL   │ Database │
│   HTML/CSS/JS       │ ──────────────────────► │                      │ ─────► │ SQLite   │
│                     │  GET  /api/history      │  controller → service│        │          │
│  • buttons/keyboard │ ◄────────────────────── │  → engine → model    │ ◄───── │ history  │
│  • display          │  DELETE /api/history/id │                      │  rows  │  table   │
│  • history UI       │                         │                      │        │          │
│  • error banner     │  JSON responses         │                      │        │          │
└─────────────────────┘ ◄──────────────────────┘                      └────────┘          └

The back end is layered (controller → service → calculator engine / model), which keeps HTTP concerns, business flow and pure calculation logic separate and independently testable.

5.3 Functional structure diagram

                        Calculator System
        ┌──────────────────────┼──────────────────────┐
     Calculator            History                 Front/Back End
        │                     │                          │
  ┌─────┼────────┐     ┌──────┼──────┐        ┌─────────┼─────────┐
Basic   Compound  Error  Save  Query  Delete   Front End  Back End  Database
Calc    Expr     Handle  List  Search Delete   (HTML/CSS/JS)  (Flask)  (SQLite)
│  │    │  │  │     │
+ − × ÷  precedence  invalid  insert  list+search  one/clear
         parens     ÷0        on OK   + paginate   by id
         unary      domain
         decimals   overflow

5.4 Front-end design

• No framework — plain HTML/CSS/ES Modules so the code is easy to read and needs no build step.
• js/api.js is the only module that talks to the network: a fetch wrapper with an 8-second timeout and a typed ApiError that carries the back end's error message.
• js/calculator.js owns the input buffer and renders the display. It converts display symbols (× ÷ −) to API symbols (* / -) only when building the request body.
• js/history.js renders the list from GET /api/history, with per-item delete, clear-all, debounced search and a “Load more” button for pagination.
• Light input conveniences exist (no two consecutive operators, one decimal point per number, balanced parentheses), but all real validation happens on the back end.

5.5 Back-end design

• controller/ — Flask blueprint that maps HTTP requests to services and translates engine exceptions into 400 responses.
• service/ — CalculatorService.calculate() implements exactly the required flow: validate → parse → calculate → store → return.
• calculator/ — the pure expression engine (no Flask dependency): lexer → parser → evaluator.
• model/ — SQLite connection handling and the history record model.

5.6 API design

Method	Endpoint	Request / params	Response
POST	/api/calculate	{"expression": "(1+2)*3"}	200 {success,id,expression,result,created_at}
GET	/api/history	?q=&limit=&offset=	200 {success,data,total,limit,offset}
DELETE	/api/history/{id}	—	200 {success,deleted,id} / 404
DELETE	/api/history	—	200 {success,deleted}
GET	/api/health	—	200 {status:"ok",...}

Failures always use HTTP 4xx with {"success": false, "message": "..."}, so the front end has a single error path.

5.7 Database design

CREATE TABLE calculation_history (
    id         INTEGER PRIMARY KEY AUTOINCREMENT,
    expression TEXT    NOT NULL,   -- normalized expression, e.g. "(1+2)*3"
    result     TEXT    NOT NULL,   -- display-ready result, e.g. "9"
    created_at TEXT    NOT NULL    -- "YYYY-MM-DD HH:MM:SS"
);

Design notes: the result is stored as text so the display value is never mangled by float serialization; the created_at index keeps list queries fast; SQLite needs no external server, which makes local and hosted deployment trivial; the file path is configurable via DATABASE_PATH.

5.8 Calculation module design (the core)

The pipeline is: whitelist check → tokenize → parse (AST) → evaluate. Full grammar (recursive descent):

expression := term (('+' | '-') term)*
term       := factor (('*' | '/' | '%') factor)*
factor     := ('+' | '-') factor | power
power      := primary ('^' factor)?          # right associative
primary    := NUMBER | CONSTANT | FUNC '(' args ')' | '(' expression ')' ['!' ...]

• Precedence is encoded in the grammar levels: + − < * / % < unary ± < ^ < primary.
• Unary minus creates a ("neg", node) AST node; -2^2 = -(2^2) = -4 follows mathematical convention.
• Division/modulo by zero raises DivisionByZeroError; sqrt(-1), ln(0) etc. raise MathDomainError; values beyond 1e308 raise NumberOverflowError.
• Security: the lexer only accepts a strict character whitelist (0-9 + - * / ^ % ( ) . , whitespace letters _ !), quotes and semicolons are rejected before parsing, and no eval/exec exists anywhere.

5.9 Calculation history module design

• Save: inside CalculatorService.calculate() — after a successful evaluation, an INSERT stores (expression, result, created_at) in the same request cycle.
• Query: GET /api/history with optional q (SQL LIKE search) and limit/offset pagination.
• Delete: DELETE /api/history/{id} deletes the actual row (rowcount > 0 decides 200 vs 404); DELETE /api/history clears everything.
• Front end: after every delete/clear, the list is re-fetched so the UI always mirrors the database.

5.10 Exception handling

CalculatorError (base)
 ├── InvalidExpressionError   -> 400 "Expression ended unexpectedly…"
 ├── DivisionByZeroError      -> 400 "Division by zero"
 ├── MathDomainError          -> 400 "sqrt of a negative number is undefined"
 └── NumberOverflowError      -> 400 "Result is too large to represent"

The controller catches only CalculatorError; unknown errors fall through to a JSON 500 handler, so the client always gets a structured response.

5.11 Front-end / back-end interaction process

User presses "="  →  front end builds expression string
  →  fetch POST /api/calculate {"expression": "12+8"}
  →  back end: validate → tokenize → parse → evaluate → INSERT history
  →  back end returns 200 {"success":true, "result":"20", ...}
  →  front end renders "12+8 = 20" and refreshes the history list
On error: back end returns 400 {"success":false, "message": "..."}
  →  front end shows the message in the error banner

5.12 Deployment process

1. Local: start the back end (python app.py), serve the front end (python -m http.server 5500), set js/config.js → apiBaseUrl.
2. Hosted (Render): push the backend repo to GitHub, create a Render web service (blueprint render.yaml included), DB stored on a persistent disk at /data.
3. Hosted (Vercel/Netlify): import the frontend repo as a static site (no build command), then point apiBaseUrl at the Render URL.
4. Docker (optional): Dockerfile included for the back end.

---

6. Code Explanation

Key implementation logic with brief explanations (full source in the repositories).

6.1 Front-end API request (js/api.js)

async function request(path, options = {}) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
  let response;
  try {
    response = await fetch(`${CONFIG.apiBaseUrl}${path}`, { ...options, signal: controller.signal });
  } catch {
    throw new ApiError("Cannot reach the back end. Please check that the server is running.", null);
  } finally {
    clearTimeout(timer);
  }
  const body = await response.json().catch(() => null);
  if (!response.ok || (body && body.success === false)) {
    throw new ApiError((body && body.message) || `Request failed with status ${response.status}`, response.status);
  }
  return body;
}

Why: one place owns timeouts, network failures and the error envelope, so the UI never guesses at backend messages. This is what produces the friendly “Cannot reach the back end…” banner.

6.2 Back-end calculation endpoint (controller)

@calculator_bp.post("/calculate")
def calculate():
    payload = request.get_json(silent=True)
    if payload is None:
        return _error("Request body must be valid JSON"), 400
    if "expression" not in payload or not isinstance(payload["expression"], str):
        return _error("Missing or invalid field 'expression'"), 400
    try:
        record = calculator_service.calculate(payload["expression"])
    except CalculatorError as exc:
        return _error(str(exc)), 400
    return jsonify({"success": True, **record}), 200

Why: the controller is a thin translation layer — request parsing and error translation only; all business logic lives in the service.

6.3 Expression parsing (parser.py — precedence)

def _term(self):
    node = self._factor()
    while self._peek().type == TokenType.OPERATOR and self._peek().value in ("*", "/", "%"):
        self._advance()
        node = ("binop", token.value, node, self._factor())
    return node

Why: precedence comes from the grammar structure, not from a list of rules. 1+2*3 parses as 1 + (2*3) because _expression only loops over + - while _term consumes * / % first.

6.4 Input validation & security (lexer.py)

_ALLOWED_CHARS = re.compile(r"^[0-9+\-*/^%().,\sA-Za-z_!]+$")

def tokenize(text):
    if not _ALLOWED_CHARS.match(text):
        raise InvalidExpressionError("Expression contains illegal characters")
    ...

Why: rejecting programming characters (quotes, ;, =, #…) at the door makes __import__("os")-style attacks fail before parsing even starts. Combined with hand-written evaluation, arbitrary code execution is impossible by construction.

6.5 Division by zero & overflow (evaluator.py)

def _binary(op, left, right):
    if op == "/":
        if right == 0:
            raise DivisionByZeroError("Division by zero")
        return _check_overflow(left / right)
    if op == "^":
        try:
            return _check_overflow(math.pow(left, right))
        except OverflowError:
            raise NumberOverflowError("Result is too large to represent")

def _check_overflow(value):
    if not math.isfinite(value) or abs(value) > 1e308:
        raise NumberOverflowError("Result is too large to represent")
    return value

Why: every operator and function funnels through _check_overflow, so overflow can never silently become inf.

6.6 Database insert (database.py + service)

cursor = self._database.execute_write(
    "INSERT INTO calculation_history (expression, result, created_at) VALUES (?, ?, ?)",
    (normalized, result_text, created_at),
)
record = HistoryRecord(id=cursor.lastrowid, expression=normalized, ...)
return record.to_dict()

Why: parameterized SQL prevents injection; the insert happens inside the calculate request, so a successful calculation and its history record are always consistent.

6.7 Database query & delete (history_service.py)

rows = self._database.query(
    f"SELECT id, expression, result, created_at FROM calculation_history "
    f"{where} ORDER BY id DESC LIMIT ? OFFSET ?",
    tuple(params + [limit, offset]),
)
...
cursor = self._database.execute_write(
    "DELETE FROM calculation_history WHERE id = ?", (history_id,))
return cursor.rowcount > 0   # False -> controller returns 404

Why: newest-first ordering matches what users expect; rowcount makes the delete idempotent and tells the API whether the id existed.

---

7. Personal Journey and Learnings

7.1 Problems encountered and solutions

• “Which side computes what?” — I first sketched a version where the front end computed and only stored results. Re-reading the assignment made the rule clear: the front end sends the expression, the back end returns the result. I then designed the API and the UI around that flow and verified it by stopping the back end (see 4.19).
• Expression parsing — the first prototype used Python's eval, which the assignment forbids. I replaced it with a hand-written tokenizer + recursive-descent parser. The hardest part was unary minus vs. exponent precedence (-2^2 should be -4); the fix was putting unary operators one grammar level above power.
• Floating-point display — 0.1+0.2 returned 0.30000000000000004. I added a result formatter that rounds to 12 significant digits before storing.
• Front-end / back-end communication — CORS blocked browser calls during early testing; I added flask-cors with a configurable origin list. The timeout + typed ApiError wrapper then gave consistent UX for network failures.
• SQLite in a threaded server — concurrent requests occasionally hit “database is locked”. Writes are now serialized with a lock and each request opens a short-lived connection; WAL mode allows concurrent readers.
• History disappearing on reload — early debugging showed history only in the front end; after moving persistence into the back-end calculate flow, records survived refresh (verified in 4.13).
• Deployment planning — SQLite is not a remote database, so for Render I mount a persistent disk at /data; the DB path is env-configurable.

7.2 New knowledge learned

• Front-end/back-end separation is a responsibility boundary, not just two folders: what the client can and cannot do changes the API design.
• A safe expression engine is a miniature compiler: lexer → parser → AST → evaluator, with each stage doing one job.
• HTTP status codes + a consistent JSON envelope make client error handling dramatically simpler.
• CORS, timeouts, pagination and search are “small” things that decide whether a demo feels like a real product.

7.3 Possible future improvements

• User accounts and per-user history (the current table is global).
• RAD/DEG mode toggle, more scientific functions (hyperbolic, random, constants).
• Expression auto-completion and syntax highlighting in the display.
• Export history to CSV, calculation statistics dashboard.
• Replace SQLite with PostgreSQL/MySQL for multi-instance hosting.

---

8. Deployment & Access Guide (for teaching assistants)

How to access the running project

• Public URLs (during evaluation):
    - Front end: https://elegant-elf-173fd2.netlify.app/ 
    - Back end: https://tribulation.pythonanywhere.com/ 
    - (fill in the actual deployed URLs here once deployed)
• Local run: follow each repository's README (install → python app.py → python -m http.server 5500 → open http://localhost:5500).

How to test

1. Click buttons or use the keyboard to enter expressions (12+8, (1+2)*3, -5+8, 0.1+0.2, 1/0, 1+ …) and press =.
2. Verify every calculation shows in the History panel; refresh the page and verify the history persists.
3. Click ✕ on a record to delete it; use Clear all; use the search box.
4. Toggle the scientific panel (ƒx) and try sin(30), sqrt(16), 5!.
5. Stop the back-end service and press = — the front end must not produce a result (separation check).
6. API smoke test:

curl -X POST https://<your-backend-domain>/api/calculate -H "Content-Type: application/json" -d '{"expression":"(1+2)*3"}'
# => {"success":true,"expression":"(1+2)*3","result":"9",...}

Notes

• Screenshots are also stored in the backend repo under docs/screenshots/ (20 PNGs + 1 GIF).
• Both repositories contain README.md (run instructions) and codestyle.md (code standards with sources).
• If any link above is still a placeholder, it means the corresponding repository or deployment was not yet pushed/published — please replace with the final URLs.

---

— Assignment blog by student 832401126 · First Assignment · Front-End / Back-End Separation Calculator System