cursor-init/prd/星撰-概要设计.md

星撰个人综合平台 - 软件开发概要设计

---

1. 引言

1.1. 文档目的

本概要设计文档旨在为"星撰"个人综合平台项目定义一个完整的软件开发生命周期（SDLC）框架。它将作为项目从规划、设计、实现到部署和维护的最高指导性文件，确保所有开发活动遵循标准化的软件工程最佳实践。

1.2. 项目概述

"星撰"是一个高度集成的个人数字化中枢，其核心功能、用户故事及非功能性需求已在《个人网站综合平台产品需求文档 (PRD)》中详细定义。本项目旨在将该PRD转化为一个稳定、可扩展、高质量的软件产品。

1.3. 范围

本文档覆盖范围包括：

• 项目开发模型的选定。
• 系统的高层体系结构设计。
• 各阶段（设计、开发、测试、部署）的规划和规范。
• 项目管理、风险控制和质量保证策略。

---

2. 项目规划与管理

2.1. 开发模型

本项目采用 迭代式增量开发模型 (Iterative and Incremental Development)。

• 迭代式: 将开发过程划分为多个短周期的迭代，每个迭代都包含需求分析、设计、编码、测试的完整流程。
• 增量式: 每个迭代都会产出一个可测试、可交付的软件增量。产品功能将分阶段（见PRD中的优先级规划）逐步构建和完善。

优势: 此模型能够快速交付核心功能（MVP），及时获取反馈，灵活应对需求变化，并有效控制项目风险。

2.2. 项目里程碑

项目将按照PRD中的优先级划分为四个主要里程碑（阶段）：

里程碑	名称	核心交付物	目标
M1	核心基础 (MVP)	基础用户系统、笔记核心功能、基础博客发布、CI/CD流程建立	验证核心架构，跑通开发部署全流程
M2	内容增强	完整博客系统、个人空间、基础工具、搜索引擎集成	完善内容生态，提升用户体验
M3	高级功能	阅读管理、文件管理、AI功能集成、第三方平台同步	扩展平台能力，引入智能化
M4	生态完善	移动端应用、浏览器插件、高级分析功能、性能深度优化	构建跨平台生态，实现长期稳定运营

2.3. 风险管理

风险类别	风险描述	可能性	影响	应对策略
技术风险	第三方API变更（如B站、QQ音乐）	中	中	封装Adapter层，隔离变化；设计优雅降级机制。
	新技术引入（Bun/Elysia）的未知问题	低	中	保持对社区的关注，构建完善的测试体系以快速发现问题。
进度风险	个人项目时间投入不稳定	高	高	严格遵循任务清单，将大任务分解为小任务，利用碎片时间完成。
安全风险	个人敏感数据（密码、文件）泄露	中	高	强制加密存储；定期进行安全扫描；代码审查时关注安全漏洞。

---

3. 系统设计

3.1. 系统架构

系统采用分层、模块化的架构，实现前后端分离。

graph TD
    subgraph "客户端 (Clients)"
        WebApp[Web 应用 (Vue/React)]
        BrowserExt[浏览器插件]
        MobileApp[移动应用 (PWA/Native)]
    end

    subgraph "服务端 (Backend - Elysia.js on Bun)"
        API_Gateway[API 网关 / 路由层]

        subgraph "核心服务层 (Core Services)"
            AuthService[认证与授权服务]
            UserService[用户管理服务]
            ContentService[内容管理服务 (笔记/博客)]
            FileService[文件管理服务]
        end

        subgraph "工具服务层 (Utility Services)"
            ToolService[密码/书签/同步等工具服务]
        end

        subgraph "插件与中间件 (Plugins & Middlewares)"
            Logger[日志插件]
            ErrorHandler[错误处理]
            JWTMiddleware[JWT认证]
            Swagger[Swagger文档]
        end
    end

    subgraph "数据与存储层 (Data & Storage)"
        MySQL[(MySQL - 关系型数据)]
        Redis[(Redis - 缓存/会话)]
        Elasticsearch[(Elasticsearch - 全文搜索)]
        ObjectStorage[对象存储 (OSS/NAS)]
    end

    subgraph "第三方服务 (3rd Party Services)"
        EmailService[邮件服务]
        OAuth[OAuth 2.0 提供商]
        AI_API[AI/LLM API]
    end

    %% 连接关系
    WebApp --> API_Gateway
    BrowserExt --> API_Gateway
    MobileApp --> API_Gateway

    API_Gateway --> AuthService
    API_Gateway --> UserService
    API_Gateway --> ContentService
    API_Gateway --> FileService
    API_Gateway --> ToolService

    AuthService <--> MySQL
    UserService <--> MySQL
    ContentService <--> MySQL
    ContentService <--> Elasticsearch
    FileService <--> ObjectStorage
    ToolService <--> MySQL

    AuthService --> JWTMiddleware
    API_Gateway -- use --> Logger
    API_Gateway -- use --> ErrorHandler
    API_Gateway -- use --> JWTMiddleware
    API_Gateway -- use --> Swagger

    subgraph "通用依赖"
        AuthService <--> Redis
        UserService <--> Redis
        ContentService <--> Redis
    end

    AuthService --> EmailService
    AuthService --> OAuth
    ContentService --> AI_API

• 客户端层: 负责用户交互和数据展示。
• 服务端层: 核心业务逻辑处理中心。通过API网关统一入口，内部按业务垂直划分为多个服务模块。
• 数据与存储层: 持久化存储数据，提供缓存和搜索能力。
• 第三方服务: 集成外部服务以完成特定功能。

3.2. 模块划分

系统功能将按以下模块进行开发，每个模块对应src/controllers, src/services下的独立子目录。

1. core: 核心模块，包括用户、角色、权限、组织、字典等。
2. content: 内容模块，包括笔记、博客、评论、分类、标签等。
3. space: 个人空间模块，包括生活日志、社交互动。
4. reader: 阅读模块，包括电子书管理、批注。
5. tools: 工具模块，包括密码、书签、文件、同步等。
6. system: 系统模块，包括健康检查、监控、配置管理。

3.3. 详细设计规划

本概要设计完成后，将对每个模块进行详细设计，产出物包括：

• 数据库设计文档: E-R图、表结构定义（字段、类型、约束、索引）、数据字典。
• API接口设计文档: 使用Swagger/OpenAPI规范，定义每个端点的URL、HTTP方法、请求参数、响应体结构及错误码。
• UI/UX设计稿: 针对核心页面和流程，制作线框图或高保真原型。

---

4. 实现与编码

4.1. 开发环境与工具

• IDE: Visual Studio Code
• 语言: TypeScript
• 运行时: Bun.js
• 包管理器: Bun
• 版本控制: Git / GitHub
• 代码检查与格式化: ESLint / Prettier

4.2. 编码规范

• 严格遵守项目已定义的注释、命名、代码风格规范。
• 所有业务逻辑必须在 services 层实现，controllers 层只负责路由和数据校验。
• 禁止在代码中硬编码配置项（如密钥、端口），所有配置通过环境变量或配置文件注入。

4.3. 版本控制策略

采用 Gitflow工作流 的简化版：

• main: 主分支，存放稳定、可发布的代码。每个里程碑完成后合并。
• develop: 开发分支，集成了所有已完成的功能。
• feat/feature-name: 功能分支，每个新功能或任务都在此分支开发，完成后合并到 develop。
• fix/bug-name: Bug修复分支。

---

5. 测试策略

5.1. 测试层次

• 单元测试: 使用 Vitest 对 services 和 utils 中的核心函数进行测试，目标覆盖率 > 90%。
• 接口测试 (集成测试): 使用 supertest 或Elysia的内置测试工具，对每个API端点进行测试，验证其与数据库、缓存的交互是否正确。
• 端到端测试 (系统测试): 使用 Playwright 或 Cypress 对关键用户流程（如注册登录、发布博客）进行自动化测试。
• 性能测试: 使用 autocannon 对核心API进行压力测试，确保其满足技术指标。

5.2. 测试执行

• 所有代码提交前，必须在本地通过相关单元测试和接口测试。
• CI/CD流水线将在每次向 develop 或 main 分支合并代码时，自动运行全量测试用例。测试不通过则禁止合并。

---

6. 部署与运维

6.1. 部署流程 (CI/CD)

使用 GitHub Actions 自动化构建、测试和部署流程。

1. Push to feat/*: 触发ESLint检查和单元测试。
2. Merge to develop: 触发全量测试，构建Docker镜像并推送到镜像仓库，然后部署到 Staging (预发布) 环境。
3. Merge to main: 触发全量测试，构建生产Docker镜像，并部署到 Production (生产) 环境。

6.2. 基础设施

• 运行环境: Docker容器。
• 容器编排: Docker Compose (初期) / Kubernetes (未来扩展)。
• 数据库/缓存: 使用云服务商提供的托管服务或在Docker中自建。

6.3. 运维监控

• 日志: 使用 pino 记录结构化日志，并聚合到统一的日志管理平台（如ELK Stack或Loki）。
• 监控与告警: 使用 Prometheus 收集应用指标，Grafana 进行可视化展示，并针对关键指标（如API错误率、延迟）设置告警。

---

7. 维护与演进

• 问题跟踪: 使用GitHub Issues跟踪Bug和功能请求。
• 文档同步: 所有代码变更，若涉及架构、API或数据库设计，必须同步更新相关设计文档。
• 定期审查: 每个里程碑结束后，进行项目复盘，评估开发流程、代码质量和系统架构，并进行优化。
• 依赖更新: 定期（如每季度）审查并更新项目依赖，以修复潜在的安全漏洞和利用新特性。