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