Todo List 多用户应用：从单用户到跨平台架构的升级实践

技术栈

• 前端: HTML5 + CSS3 + jQuery 3.6.0 + 认证界面
• 后端: Flask 2.3.3 + Flask-JWT-Extended + bcrypt
• 数据库: SQLite 多用户设计（外键关联）
• 认证: Session 认证（Web UI）+ JWT Token（API 客户端）
• 架构: 面向跨平台客户端的多用户服务端架构

核心升级内容

1. 项目结构重组

将原有平铺结构重新组织，为多平台客户端开发做准备：

todo-list/
├── BLUE.md              # 跨平台开发蓝图
├── CLAUDE.md            # 开发指南和代码分析
├── README.md            # 项目说明文档
└── web-client/          # B/S Web 客户端
    ├── backend/
    │   ├── app.py           # Flask 应用主文件
    │   ├── models.py        # 数据模型
    │   ├── requirements.txt # Python 依赖
    │   ├── migrate_db.py    # 数据库迁移脚本
    │   └── todo.db         # SQLite 数据库
    ├── static/
    │   ├── auth.css        # 认证页面样式
    │   ├── auth.js         # 认证页面脚本
    │   ├── script.js       # 主应用脚本
    │   └── style.css       # 主应用样式
    └── templates/
        ├── index.html      # 主应用页面
        ├── login.html      # 登录页面
        └── register.html   # 注册页面

2. 数据库架构升级

原始设计

CREATE TABLE todos (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    completed BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

多用户设计

-- 用户表
CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    username TEXT UNIQUE NOT NULL,
    password_hash TEXT NOT NULL,
    email TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 待办事项表（支持多用户）
CREATE TABLE todos (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    title TEXT NOT NULL,
    completed BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE
);

技术说明：SQLite 仅在 INSERT 时自动写入 updated_at，UPDATE 操作不会触发自动更新。若需在更新时正确记录时间戳，需在应用层显式赋值，或添加数据库触发器。ON DELETE CASCADE 约束确保删除用户时，其关联的待办事项会自动级联删除，维护引用完整性。

3. 用户认证系统

后端 API

# 用户认证端点
@app.route('/api/register', methods=['POST'])
def register():
    # 用户注册逻辑，包含密码加密
    
@app.route('/api/login', methods=['POST'])
def login():
    # 用户登录验证，返回JWT Token
    
@app.route('/api/logout', methods=['POST'])
def logout():
    # 用户登出，清除会话

# 受保护的API端点
@app.route('/api/todos', methods=['GET'])
@login_required
def get_todos():
    # 仅返回当前用户的待办事项

认证装饰器

def login_required(f):
    @wraps(f)
    def decorated_function(*args, **kwargs):
        if 'user_id' not in session:
            return jsonify({'error': 'Authentication required'}), 401
        return f(*args, **kwargs)
    return decorated_function

4. 前端认证界面

登录页面

• 支持桌面与移动端的响应式布局
• 实时验证：用户名长度与密码强度
• 友好的错误提示与加载状态
• 防止表单重复提交，密码输入遮盖

注册页面

• 验证用户名唯一性与密码确认匹配
• 实时输入状态指示
• 注册成功后自动跳转至登录页

5. 数据库迁移

专用迁移脚本 migrate_db.py 负责 Schema 升级：

def migrate_database(db_path):
    # 1. 自动备份现有数据库
    backup_path = backup_database(db_path)
    
    # 2. 检查表结构，判断是否需要迁移
    todos_columns, users_exists = check_table_structure(db_path)
    
    # 3. 安全地添加user_id列和users表
    # 4. 保留现有数据，分配给默认用户
    # 5. 添加外键约束确保数据一致性
    # 6. 失败时自动回滚

迁移特性:

• ✅ 自动数据备份
• ✅ 数据完整性保护
• ✅ 失败自动回滚
• ✅ 详细迁移日志

技术难点与解决方案

1. 升级后 Schema 不匹配

问题：sqlite3.OperationalError: no such column: user_id

解决方案：编写安全的迁移脚本，以渐进方式升级表结构，确保数据零丢失。

2. API 路径 404 错误

问题：前端调用 /api/5 而非 /api/todos/5

修复：

// 修复前
url: `${API_BASE}/${id}`  // /api/5

// 修复后  
url: `${API_BASE}/todos/${id}`  // /api/todos/5

3. 用户数据隔离

问题：确保不同用户只能访问自己的数据

解决方案：所有 API 端点均验证当前认证用户，数据库查询全部加入 user_id 过滤条件，严格执行会话管理。

性能与安全

数据库连接

• 复用连接，避免每次查询新建
• 实施连接池管理
• 优化 SQL 查询效率

前端体验

• 异步操作加载状态指示
• 危险操作确认对话框
• 清晰的错误提示展示

安全措施

• bcrypt 密码哈希存储
• JWT Token 认证机制
• HTML 转义防范 XSS 攻击
• CSRF 防护措施

项目成果

功能特性

• ✅ 用户管理：注册、登录、登出完整流程
• ✅ 数据隔离：每个用户的待办事项相互独立
• ✅ 会话管理：Session + JWT 双重认证
• ✅ 响应式设计：支持桌面与移动设备
• ✅ 安全认证：bcrypt 加密，XSS 防护

指标（本地环境）

• 响应时间：< 200ms
• 数据隔离：在查询层按用户强制执行
• 浏览器支持：现代浏览器
• 可扩展性：服务端 API 已为多平台客户端预留接口

跨平台发展规划

基于已建立的服务端架构，后续将按照 BLUE.md 路线图开发各平台客户端：

Phase 2：Apple 生态

• iOS 客户端（Swift + SwiftUI）
• macOS 客户端（Catalyst）
• Core Data 离线缓存

Phase 3：Android + Windows

• Android 客户端（Kotlin + Compose）
• Windows 客户端（C# + WPF）
• 本地数据库缓存

Phase 4：Linux + 集成测试

• Linux 客户端（Python + PyQt）
• 跨平台集成测试
• 完整文档编写

技术栈：Python Flask, SQLite, HTML5, CSS3, JavaScript, JWT, bcrypt
项目特点：多用户认证、数据隔离、响应式设计、跨平台服务端架构
开发时间：2025 年 7 月 24 日
项目状态：Web 端完成，多平台客户端开发中