From e67763fa82c1510477d2c7ea2fd78b4700ff7bd5 Mon Sep 17 00:00:00 2001
From: admin <572701190@qq.com>
Date: Sat, 2 May 2026 02:30:08 +0800
Subject: [PATCH] Add installation and initial setup documentation

- Add docs/installation.md covering prerequisites, port usage, Docker startup, local development setup, default accounts, first-run validation, and common setup issues.

- Link the installation guide from the project README and docs index.

- Point deployment documentation to the installation guide for first-time setup.

- Update AGENTS.md and progress documentation to include the new installation guide.
---
 AGENTS.md            |   1 +
 README.md            |   3 +
 docs/README.md       |   1 +
 docs/deployment.md   |   2 +
 docs/installation.md | 230 +++++++++++++++++++++++++++++++++++++++++++
 docs/progress.md     |   1 +
 6 files changed, 238 insertions(+)
 create mode 100644 docs/installation.md

diff --git a/AGENTS.md b/AGENTS.md
index 2e7cd7e..5ceb6ba 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -207,6 +207,7 @@ npm run test:e2e
 │   └── tsconfig.json
 ├── docs/
 │   ├── README.md
+│   ├── installation.md
 │   ├── requirements.md
 │   ├── design.md
 │   ├── permissions.md
diff --git a/README.md b/README.md
index e24ef3b..3f60e9f 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,8 @@
 
 更细的功能真实性判断见 [docs/features.md](./docs/features.md)。
 
+首次安装、端口规划、数据库初始化和常见问题见 [docs/installation.md](./docs/installation.md)。
+
 ## 技术栈
 
 - React 19
@@ -177,6 +179,7 @@ cp .env.example .env.local
 ## 文档
 
 - [docs/README.md](./docs/README.md)：文档入口。
+- [docs/installation.md](./docs/installation.md)：安装、初始设置和首次验收。
 - [docs/requirements.md](./docs/requirements.md)：需求文档。
 - [docs/design.md](./docs/design.md)：设计文档。
 - [docs/features.md](./docs/features.md)：功能真实性盘点。
diff --git a/docs/README.md b/docs/README.md
index 501b165..66458d2 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,6 +4,7 @@
 
 ## 文档结构
 
+- [安装与初始设置](./installation.md)：从源码到可登录系统的首次安装、端口、数据库初始化和常见问题。
 - [需求文档](./requirements.md)：业务目标、用户角色、功能需求和非功能约束。
 - [设计文档](./design.md)：前端架构、路由、状态、数据模型和关键设计取舍。
 - [权限设计](./permissions.md)：已确定的角色、部门、报告、模板和 AI 上下文权限规则。
diff --git a/docs/deployment.md b/docs/deployment.md
index a69ca7e..d7abba3 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -1,5 +1,7 @@
 # 部署运行
 
+如果是第一次安装项目，建议先阅读 [安装与初始设置](./installation.md)。本文档主要记录开发运行、质量检查、环境变量和 Docker/Nginx 部署边界。
+
 ## 本地开发
 
 前端：
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..a95fbd5
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,230 @@
+# 安装与初始设置
+
+本文档面向第一次接手项目的开发者，目标是把系统从源码启动到可登录、可保存报告。部署细节见 [部署运行](./deployment.md)，业务和架构背景见 [文档入口](./README.md)。
+
+## 前置要求
+
+- Node.js 20 或更高版本。
+- npm。
+- Docker 与 Docker Compose，用于一键启动 PostgreSQL、API 和前端。
+- Linux/macOS shell 环境；Windows 建议使用 WSL。
+
+确认工具可用：
+
+```bash
+node --version
+npm --version
+docker --version
+docker compose version
+```
+
+## 端口规划
+
+本项目已避开常见默认端口：
+
+| 用途 | 本地/宿主机端口 | 说明 |
+| --- | --- | --- |
+| Vite 前端开发服务 | `3001` | 仅 `npm run dev` 使用 |
+| NestJS API 本地服务 | `3100` | `npm run server:dev` 默认监听 |
+| Docker API 暴露端口 | `3002` | 宿主机访问 Compose API |
+| Docker 前端入口 | `4002` | 推荐的整套系统访问入口 |
+| Docker PostgreSQL | `5433` | 宿主机访问 Compose 数据库 |
+
+如果这些端口被占用，优先修改 `.env`、`docker-compose.yaml` 和对应文档，避免回退到 `3000` 等默认端口。
+
+## 推荐方式：Docker 一键启动
+
+第一次启动：
+
+```bash
+npm install
+docker compose up -d --build
+```
+
+启动后访问：
+
+```text
+http://localhost:4002
+```
+
+健康检查：
+
+```bash
+curl http://localhost:4002/api/health
+curl http://localhost:3002/api/health
+```
+
+当前 Compose 会启动：
+
+- `tuwen_web`：Nginx 托管前端，宿主机端口 `4002`。
+- `tuwen_api`：NestJS API，容器内监听 `3100`，宿主机端口 `3002`。
+- `tuwen_db`：PostgreSQL 16，宿主机端口 `5433`。
+
+查看状态：
+
+```bash
+docker compose ps
+```
+
+停止：
+
+```bash
+docker compose down
+```
+
+连数据卷一起清理会删除数据库和上传文件，只在确认不需要当前数据时使用：
+
+```bash
+docker compose down -v
+```
+
+## 本地开发方式
+
+如果希望前端热更新、后端直接跑在本机，可以按下面启动。
+
+安装依赖并创建环境变量：
+
+```bash
+npm install
+cp .env.example .env
+```
+
+先准备 PostgreSQL。可以复用 Compose 的数据库：
+
+```bash
+docker compose up -d db
+```
+
+生成 Prisma Client、执行迁移和 seed：
+
+```bash
+npm run prisma:generate
+npm run prisma:migrate
+npm run prisma:seed
+```
+
+启动后端 API：
+
+```bash
+npm run server:dev
+```
+
+API 默认地址：
+
+```text
+http://localhost:3100/api/health
+```
+
+另开一个终端启动前端开发服务：
+
+```bash
+npm run dev
+```
+
+前端开发地址：
+
+```text
+http://localhost:3001
+```
+
+开发模式下，Vite 会把 `/api` 代理到 `VITE_API_PROXY_TARGET`，默认是 `http://localhost:3100`。如果你想用本机 Vite 前端连接 Docker Compose API，把 `.env` 中的目标改成：
+
+```bash
+VITE_API_PROXY_TARGET="http://localhost:3002"
+```
+
+## 默认账号
+
+默认数据由后端 seed 写入：
+
+| 用户ID | 密码 | 角色 |
+| --- | --- | --- |
+| `admin` | `123456` | 超级管理员 |
+| `manager` | `123456` | 管理员 |
+| `0001` | `123456` | 医生 |
+
+登录后建议先进入“系统设置”确认 AI Provider、讯飞语音配置、默认模板和抽帧策略。AI 与语音密钥保存在后端 Settings API 中，不应写入源码、文档或提交记录。
+
+## 初次验收
+
+完成启动后建议按顺序验证：
+
+1. 打开 `http://localhost:4002` 或本地开发地址 `http://localhost:3001`。
+2. 使用 `admin / 123456` 登录。
+3. 进入工作台，确认统计卡片能正常加载。
+4. 进入“系统设置”，确认全局配置可保存。
+5. 使用医生账号 `0001 / 123456` 新建报告并保存草稿。
+6. 进入“报告管理”，确认能看到刚保存的报告。
+
+命令行验证：
+
+```bash
+npm run lint
+npm run test
+npm run build
+```
+
+后端、权限或关键流程变更后再运行：
+
+```bash
+npm run server:build
+npm run test:e2e
+```
+
+## 常见问题
+
+### 保存草稿提示后端不可用
+
+先检查当前访问入口和 API 健康检查：
+
+```bash
+curl http://localhost:4002/api/health
+curl http://localhost:3002/api/health
+docker compose ps
+```
+
+Docker 方式应访问 `http://localhost:4002`。本地开发方式应确保 `npm run server:dev` 正在运行，并且 `VITE_API_PROXY_TARGET` 指向 `http://localhost:3100`。
+
+### 端口被占用
+
+检查占用：
+
+```bash
+ss -ltnp | grep -E ':3001|:3002|:3100|:4002|:5433'
+```
+
+本项目不应使用 `3000` 作为默认 API 端口。如果必须改端口，同步修改 `.env`、`docker-compose.yaml`、`vite.config.ts` 或 Nginx upstream，并更新文档。
+
+### 数据库连接失败
+
+如果使用 Compose 数据库，确认 `tuwen_db` 正常运行：
+
+```bash
+docker compose ps db
+```
+
+本地默认连接串在 `.env.example` 中：
+
+```text
+postgresql://surclaw:surclaw_dev_password@localhost:5433/surclaw?schema=public
+```
+
+修改数据库配置后重新运行：
+
+```bash
+npm run prisma:generate
+npm run prisma:migrate
+npm run prisma:seed
+```
+
+### AI 或讯飞提示未配置
+
+AI 对话和讯飞语音均通过后端代理读取系统设置。使用超级管理员进入“系统设置”，填写并保存 AI Provider、模型名称和讯飞 APPID/APIKey/APISecret。普通用户读取设置时不会拿到真实密钥。
+
+### 前端页面像旧版本
+
+Docker 重建后浏览器可能仍缓存旧 bundle。先强制刷新页面；仍异常时重新构建：
+
+```bash
+docker compose up -d --build
+```
diff --git a/docs/progress.md b/docs/progress.md
index 649de15..b69df45 100644
--- a/docs/progress.md
+++ b/docs/progress.md
@@ -72,3 +72,4 @@
 | 2026-05-02 | 新增 `ReportMedia` 表和迁移，报告视频/关键帧引用从 `Report.metadata` 拆出。 |
 | 2026-05-02 | 新增 Dashboard API、数据库 Session Store、审计服务、HTML 白名单清洗、本地回退开关和 Docker 上传目录 volume，清理 Gemini 旧依赖。 |
 | 2026-05-02 | 新增审计日志查询 API/页面、Auth Context 路由角色守卫，并把 Playwright E2E 改为真实后端 API seed。 |
+| 2026-05-02 | 新增安装与初始设置文档，补充首次启动、端口规划、数据库初始化、验收步骤和常见问题。 |