gaokao-volunteer-system/reports/code-analysis-review-input-2026-06-12.md

# 🔍 Deep Code Analysis Report

**Generated:** 2026-06-12T19:18:10.577328

**Path:** /home/long/project/gaokao-volunteer-system


## 📋 Executive Summary

- **Total Files:** 107
- **Total Lines:** 25,582
- **Architecture Style:** MVC
- **Entry Points:** 1
- **Data Models:** 123
- **Business Rules:** 218
- **External Dependencies:** 66


## 🏗️ Architecture

**Style:** MVC

**Layers/Modules:**

- `admin/`
- `data/`
- `scripts/`
- `tests/`
- `skills/`

## 🚀 Entry Points & Execution Flow


### main

- **Location:** `admin/app.py`
- **Parameters:** argv
- **Business Logic:** ❌ No
- **Calls:** ArgumentParser, add_argument, add_argument, add_argument, add_argument

## 📊 Data Models


### Core Entities


**UserOrderRecord** (`admin/users.py`)


**CaseRecord** (`data/cases/models.py`)


### DTOs/Value Objects

- **OrderSummaryResponse** - admin/routes/orders.py
- **OrderMutationResponse** - admin/routes/orders.py
- **CreateOrderRequest** - admin/routes/orders.py
- **UpdateOrderRequest** - admin/routes/orders.py
- **UserSummaryResponse** - admin/routes/users.py

## 📜 Business Rules


### Validation Rules (200)

**rule_1:** Validation in login

- Location: `locustfile.py:login`
- Priority: medium
- Condition: `if not token:
                resp.failure("login response missing access_token")
                se...`

**rule_2:** Validation in hash_password

- Location: `admin/password.py:hash_password`
- Priority: high
- Condition: `if not plain:
        raise ValueError("password cannot be empty")
    salt = secrets.token_bytes(_S...`

**rule_3:** Validation in verify_password

- Location: `admin/password.py:verify_password`
- Priority: high
- Condition: `if not plain or not stored or _STORED_SEPARATOR not in stored:
        return False
    salt_hex, ha...`

**rule_4:** Validation in authenticate

- Location: `admin/db.py:authenticate`
- Priority: medium
- Condition: `if result is None:
        return None
    user, password_hash = result
    if not user.is_active:
 ...`

**rule_5:** Validation in authenticate

- Location: `admin/db.py:authenticate`
- Priority: medium
- Condition: `if not user.is_active:
        return None
    if not verify_password(password, password_hash):
    ...`


### Constraint Rules (18)

**rule_9:** Business constraint in log_event

- Location: `admin/logging_utils.py:log_event`
- Priority: critical
- Condition: `if not event:
        raise ValueError("log_event: 'event' is required")

    safe_fields: Dict[str,...`

**rule_12:** Business constraint in log_event_exc

- Location: `admin/logging_utils.py:log_event_exc`
- Priority: critical
- Condition: `if not event:
        raise ValueError("log_event_exc: 'event' is required")
    safe_fields: Dict[s...`

**rule_54:** Business constraint in main

- Location: `skills/gaokao-audit/scripts/validate_template.py:main`
- Priority: critical
- Condition: `if needle not in text:
            print(f"FAIL: placeholder missing: {needle!r}")
            retur...`

**rule_55:** Business constraint in main

- Location: `skills/gaokao-audit/scripts/validate_template.py:main`
- Priority: critical
- Condition: `if needle not in rendered:
            print(f"FAIL: rendered output missing: {needle!r}")
         ...`

**rule_68:** Business constraint in base62_encode

- Location: `data/share/short_link.py:base62_encode`
- Priority: critical
- Condition: `if num < 0:
        raise ValueError("num must be >= 0")
    if num == 0:
        return BASE62_ALPH...`


## 🔗 External Dependencies


### Other Dependencies

- locust
- datetime
- secrets
- dataclasses
- argparse
- urllib
- xianyu_adapter
- admin
- fastapi
- tempfile
- uuid
- collections
- schema
- json
- jinja2

## 💧 Data Flows

- **external** → **admin/password.py:verify_password**
  - Data: plain, stored
  - Trigger: function_call
- **external** → **admin/db.py:create**
  - Data: username, password, role
  - Trigger: function_call
- **external** → **admin/db.py:update_last_login**
  - Data: user_id
  - Trigger: function_call
- **external** → **admin/app.py:_validate_and_log_settings**
  - Data: settings
  - Trigger: function_call
- **external** → **admin/app.py:create_app**
  - Data: settings
  - Trigger: function_call
- **external** → **admin/stats.py:generate_day_series**
  - Data: db_path
  - Trigger: function_call
- **external** → **scripts/gaokao-quick-3min.py:generate_quick_summary**
  - Data: info
  - Trigger: function_call
- **external** → **scripts/gaokao-quick-3min.py:generate_quick_recommendation**
  - Data: info
  - Trigger: function_call
- **external** → **scripts/gaokao-visual-report-v2.py:generate_student_radar**
  - Data: student_profile
  - Trigger: function_call
- **external** → **scripts/gaokao-visual-report-v2.py:generate_school_comparison**
  - Data: volunteer_list
  - Trigger: function_call

## 🛤️ Key Execution Paths


### main

Entry point: admin/app.py

**Steps:**

1. `main`

### main

Entry point: scripts/gaokao-quick-3min.py

**Steps:**

1. `main`

### run

Entry point: scripts/gaokao-collect-info.py

**Steps:**

1. `run`
2. `main`
3. `_git`
4. `_run_cli`
5. `_remote_head`
6. `test_supports_async_function`
7. `test_audit_report_template_renders`
8. `_init_repo`
... and 2 more

## 💡 Recommendations


### For Understanding This Codebase

1. Start with entry points listed above
2. Review core entities and their relationships
3. Trace execution paths for key features
4. Review business rules for domain logic
5. Check external dependencies for integration points


### For Code Quality

1. Add documentation to entry points
2. Document business rules explicitly
3. Create architecture decision records (ADRs)
4. Add data flow diagrams