harness_coding_docs/docs/04-architecture.md

架构设计

本文讲“怎么把技术栈搭起来”：系统结构、职责划分、数据模型、技术难点、开发顺序。 具体用了哪些框架 / 库 / 数据库 / 部署方式，见 技术栈。

一、系统结构

用户
  |
  v
前端 / 客户端
  |
  v
后端 API
  |
  v
数据库 / 文件 / 第三方服务

把真实组件替换到上图中，例如：

• 前端：【框架、入口目录】
• 后端：【框架、入口文件】
• 数据库：【类型、迁移方式】
• 外部服务：【支付、邮件、对象存储、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】	【为什么难】	【降级方案】

高风险功能应先做最小原型，不要等整个系统搭完才验证。

五、推荐开发顺序

1. 最小可运行地基。
2. 最高风险功能原型。
3. 核心用户流程。
4. 数据持久化和账号体系。
5. 完整验收、部署和边界处理。

六、项目结构建议

project/
├── docs/
├── src/ 或 app/
├── server/ 或 api/
├── tests/
├── scripts/
└── README.md

按实际技术栈替换：

• src/：【前端 / 客户端代码】
• server/：【后端代码】
• scripts/：【数据校验、迁移、构建辅助脚本】
• tests/：【测试目录】

七、架构纪律

• 业务事实和 schema 变化必须同步更新本文。
• 不在代码里发明文档没有的接口、字段和状态。
• 不把静态内容、用户数据、缓存数据混在一个模型里。
• 高风险模块先单独验证，再接入完整页面或流程。