Initialize harness coding docs

2026-06-22 21:44:11 +08:00
commit 066f3c75e9
14 changed files with 900 additions and 0 deletions
@@ -0,0 +1,124 @@
+# 架构设计
+
+> 本文讲“怎么把技术栈搭起来”：系统结构、职责划分、数据模型、技术难点、开发顺序。
+> 具体用了哪些框架 / 库 / 数据库 / 部署方式，见 [技术栈](03-tech-stack.md)。
+
+## 一、系统结构
+
+```text
+用户
+  |
+  v
+前端 / 客户端
+  |
+  v
+后端 API
+  |
+  v
+数据库 / 文件 / 第三方服务
+```
+
+把真实组件替换到上图中，例如：
+
+- 前端：【框架、入口目录】
+- 后端：【框架、入口文件】
+- 数据库：【类型、迁移方式】
+- 外部服务：【支付、邮件、对象存储、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 变化必须同步更新本文。
+- 不在代码里发明文档没有的接口、字段和状态。
+- 不把静态内容、用户数据、缓存数据混在一个模型里。
+- 高风险模块先单独验证，再接入完整页面或流程。