3.4 KiB
3.4 KiB
架构设计
本文讲“怎么把技术栈搭起来”：系统结构、职责划分、数据模型、技术难点、开发顺序。 具体用了哪些框架 / 库 / 数据库 / 部署方式，见 技术栈。
一、系统结构
按真实产品形态替换下图。项目可以是 Web、桌面、CLI、本地自动化、移动端、插件或多端组合，不要强行保留不存在的后端层。
用户
|
v
前端 / 客户端 / CLI / 本地工具
|
v
后端 API / 本地核心模块
|
v
数据库 / 文件 / 第三方服务
把真实组件替换到上图中，例如：
- 前端：【框架、入口目录】
- 后端：【框架、入口文件】
- 本地工具：【CLI 入口、桌面入口、自动化脚本入口】
- 数据库：【类型、迁移方式】
- 外部服务：【邮件、对象存储、AI 服务、第三方平台等】
二、职责划分
前端 / 客户端
- 【页面与交互职责】
- 【客户端状态】
- 【本地缓存 / 离线 / 上传等职责】
后端
- 【鉴权】
- 【业务 API】
- 【数据校验】
- 【异步任务 / 文件处理】
如果项目没有后端，删除本节或改为 本地核心模块：
- 【模块入口和公开函数】
- 【输入输出合约】
- 【文件读写 / 系统调用 / 第三方平台调用边界】
- 【错误处理和重试策略】
数据库 / 存储
- 【持久化哪些数据】
- 【不持久化哪些数据】
- 【哪些数据只读，哪些数据可变】
三、数据模型
3.1 静态 / 只读数据
| 数据 | 来源 | 说明 |
|---|---|---|
| 【数据名】 | 【路径 / 服务】 | 【字段和约束】 |
关键事实：
- 【字段事实 1】
- 【字段事实 2】
- 【路径映射 / schema 约束】
3.2 用户 / 业务动态数据
示例表结构：
CREATE TABLE users (
id INTEGER PRIMARY KEY,
email TEXT UNIQUE NOT NULL,
created_at TEXT NOT NULL
);
需要说明：
- 主键和唯一约束。
- 重要索引。
- 是否软删除。
- 哪些字段由服务端生成。
- 哪些字段是前向兼容预留，MVP 是否启用逻辑。
四、关键技术难点
| 难点 | 说明 | 应对 |
|---|---|---|
| 【难点 1】 | 【为什么难】 | 【先做 spike / 原型 / 测试】 |
| 【难点 2】 | 【为什么难】 | 【降级方案】 |
高风险功能应先做最小原型，不要等整个系统搭完才验证。
五、推荐开发顺序
- 最小可运行地基。
- 最高风险功能原型。
- 核心用户流程。
- 数据持久化和账号体系。
- 完整验收、部署和边界处理。
六、项目结构建议
project/
├── docs/
├── src/ 或 app/
├── server/ 或 api/
├── tests/
├── scripts/
└── README.md
按实际技术栈替换：
src/：【前端 / 客户端代码】server/：【后端代码；无后端项目可删除或替换为核心模块目录】scripts/：【数据校验、迁移、构建辅助脚本】tests/：【测试目录】
路径只是模板占位，初始化后必须按真实技术栈和项目形态替换，不要保留误导性的空目录说明。
七、架构纪律
- 业务事实和 schema 变化必须同步更新本文。
- 不在代码里发明文档没有的接口、字段和状态。
- 不把静态内容、用户数据、缓存数据混在一个模型里。
- 高风险模块先单独验证，再接入完整页面或流程。