harness_coding_docs/docs/04-architecture.md

# 架构设计

> 本文讲“怎么把技术栈搭起来”：系统结构、职责划分、数据模型、技术难点、开发顺序。
> 具体用了哪些框架 / 库 / 数据库 / 部署方式，见 [技术栈](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 变化必须同步更新本文。
- 不在代码里发明文档没有的接口、字段和状态。
- 不把静态内容、用户数据、缓存数据混在一个模型里。
- 高风险模块先单独验证，再接入完整页面或流程。