docs: complete Chinese project documentation

2026-07-27 19:08:08 +08:00
parent b02d18d3b9
commit 78a70ee7c2
20 changed files with 3441 additions and 654 deletions
--- a/docs/development/local-setup.md
+++ b/docs/development/local-setup.md
@@ -1,115 +1,334 @@
-# Local Setup
+# 本地开发环境

-## Prerequisites
+本文说明 Windows 和 Linux/macOS 上的本地配置、三种启动方式、数据库初始化、质量检查及
+常见问题。生产环境请使用[生产部署与恢复手册](../operations/production-runbook.md)。
+
+## 1. 前置环境

 - Python 3.12
- Node.js 22
- Docker Desktop
+- Node.js 22 或更高版本
+- pnpm 11.9.0
+- Docker Desktop，或 Docker Engine + Compose
+- Git

-## First Run
+建议通过 Corepack 启用仓库声明的 pnpm：
+
+```bash
+corepack enable
+corepack prepare pnpm@11.9.0 --activate
+```
+
+检查版本：
+
+```bash
+python --version
+node --version
+pnpm --version
+docker compose version
+```
+
+## 2. 初始化配置
+
+在项目根目录复制环境变量模板：

 ```powershell
 Copy-Item .env.example .env
-python -c "import base64,secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"
 ```

-将输出写入 `.env` 的 `AI_CREDENTIAL_ENCRYPTION_KEY`。该值缺失时，系统会拒绝保存模型渠道凭证；已经保存凭证后不要随意更换主密钥。
+Linux/macOS：

-完整应用（PostgreSQL、Redis、MinIO、Django、Celery worker、Celery Beat、React）：
+```bash
+cp .env.example .env
+```
+
+生成稳定的 Fernet 主密钥：
+
+```bash
+python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+```
+
+把结果写入 `.env` 的 `AI_CREDENTIAL_ENCRYPTION_KEY`。已经保存模型、MCP、渠道或 OIDC
+凭据后不要直接更换主密钥，否则历史密文将无法解密。
+
+本地至少检查：
+
+- `DJANGO_SECRET_KEY`
+- `DJANGO_SUPERUSER_PASSWORD`
+- `POSTGRES_PASSWORD`
+- `MINIO_ROOT_USER`、`MINIO_ROOT_PASSWORD`
+- `MINIO_ACCESS_KEY`、`MINIO_SECRET_KEY`
+- `AI_CREDENTIAL_ENCRYPTION_KEY`
+- `INTERNAL_MCP_TOKEN`
+- `METRICS_TOKEN`
+
+`.env` 已被 Git 忽略，不得把真实值写回 `.env.example`。
+
+## 3. 启动方式
+
+### 3.1 完整 Docker 环境
+
+适合第一次启动和端到端联调：

 ```powershell
-cd infra
-docker compose --env-file ../.env up --build
+docker compose -f infra/docker-compose.yml --env-file .env up --build
 ```

-只启动本地基础设施、在宿主机运行前后端时：
+包含 PostgreSQL、Redis、MinIO、ClamAV、Django、Celery Worker、Celery Beat 和 React。
+后端入口会等待依赖服务、执行数据库迁移并初始化治理数据。
+
+访问地址：
+
+- 前端：<http://localhost:5173>
+- API 文档：<http://localhost:8000/api/docs>
+- 存活探针：<http://localhost:8000/api/system/health/live>
+- 就绪探针：<http://localhost:8000/api/system/health/ready>
+- MinIO 控制台：<http://localhost:9001>
+
+停止环境：

 ```powershell
-cd infra
-docker compose -f docker-compose.local.yml --env-file ../.env up -d
+docker compose -f infra/docker-compose.yml --env-file .env down
 ```

-首次启动时，backend 容器会自动等待 PostgreSQL、执行数据库迁移，并初始化企业后台治理数据。
+不要随意添加 `-v`，该参数会删除本地数据库和对象存储卷。

-Backend:
+### 3.2 Docker 基础设施 + 宿主机应用

- API: http://localhost:8000/api/docs
- Health: http://localhost:8000/api/system/health
+适合频繁调试后端和前端：

-Frontend:
+```powershell
+docker compose -f infra/docker-compose.local.yml --env-file .env up -d
+```

- App: http://localhost:5173
- 局域网访问: `http://<宿主机局域网 IP>:5173`
+宿主机进程需要把容器服务名覆盖为本机地址：

-前端默认通过同源 `/api` 代理后端：宿主机直接运行 Vite 时代理到
-`http://localhost:8000`，Docker Compose 中通过 `API_PROXY_TARGET` 代理到
-`http://backend:8000`。因此局域网访问时无需把浏览器 API 地址配置为
+```env
+POSTGRES_HOST=localhost
+CELERY_BROKER_URL=redis://localhost:6379/0
+CELERY_RESULT_BACKEND=redis://localhost:6379/1
+MINIO_ENDPOINT=localhost:9000
+CLAMAV_HOST=localhost
+API_PROXY_TARGET=http://localhost:8000
+```
+
+安装并启动后端：
+
+```powershell
+cd backend
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install -e ".[dev]"
+python manage.py migrate
+python manage.py bootstrap_governance
+python manage.py runserver 0.0.0.0:8000
+```
+
+Linux/macOS 激活虚拟环境：
+
+```bash
+source .venv/bin/activate
+```
+
+另开终端启动异步进程：
+
+```powershell
+cd backend
+.\.venv\Scripts\Activate.ps1
+python -m celery -A config.celery worker -l info -P solo
+```
+
+```powershell
+cd backend
+.\.venv\Scripts\Activate.ps1
+python -m celery -A config.celery beat -l info
+```
+
+安装并启动前端：
+
+```powershell
+cd frontend
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+前端通过同源 `/api` 代理后端，局域网访问时无需把浏览器 API 地址写成
 `localhost:8000`。

-默认管理员:
+### 3.3 Windows 后端辅助脚本

- 账号: `admin`
- 密码: `admin12345`
- 可通过 `.env` 中的 `DJANGO_SUPERUSER_USERNAME`、`DJANGO_SUPERUSER_PASSWORD`、`DJANGO_SUPERUSER_EMAIL` 修改。
+基础设施已启动时，可在项目根目录执行：

-## Backend Tests
-
-```bash
-cd backend
-python -m pip install -e ".[dev]"
-pytest -v
+```powershell
+.\start-backend.ps1
 ```

-## Frontend Checks
+脚本校验 `.env` 和 Fernet 主密钥，分别启动 Django、Celery Worker 和 Celery Beat。
+它不会启动 Docker、前端或执行迁移。修改 `.env` 后使用：

-```bash
+```powershell
+.\start-backend.ps1 -Restart
+```
+
+## 4. 数据库与初始数据
+
+创建或更新迁移：
+
+```powershell
+cd backend
+python manage.py makemigrations
+python manage.py migrate
+python manage.py bootstrap_governance
+```
+
+提交前必须确认没有遗漏迁移：
+
+```powershell
+python manage.py makemigrations --check --dry-run
+```
+
+开发环境默认管理员为 `admin / admin12345`，可通过 `.env` 中的
+`DJANGO_SUPERUSER_*` 修改。生产环境禁止使用默认密码。
+
+## 5. AI 能力初始化
+
+### 5.1 模型、Skill 和 Agent
+
+1. 使用管理员进入 `#/modelhub/providers`，创建 OpenAI-compatible 渠道和模型部署。
+2. 文本步骤使用 `text_chat`；包含图片时使用 `vision_chat`，并单独批准图片出境。
+3. 在 `#/skills` 管理 Skill 草稿和发布版本。
+4. 在 `#/agents` 配置步骤、模型、输入映射和授权动作。
+5. 在 `#/agent-runs` 查看冻结配置、步骤轨迹、调用尝试、Token 和耗时。
+
+发布可信建单 Agent：
+
+```powershell
+cd backend
+python manage.py publish_trusted_ticket_intake --deployment-id 1
+```
+
+发布支持分析 Agent：
+
+```powershell
+python manage.py publish_support_analysis --deployment-id 1
+```
+
+发布知识蒸馏 Agent：
+
+```powershell
+python manage.py publish_knowledge_distillation --deployment-id 1
+```
+
+### 5.2 混合检索
+
+在模型中心创建 `embedding` 部署，可选创建 `rerank` 部署，并配置：
+
+```env
+KNOWLEDGE_EMBEDDING_DEPLOYMENT_ID=<Embedding 部署 ID>
+KNOWLEDGE_EMBEDDING_DIMENSIONS=1536
+KNOWLEDGE_EMBEDDING_ALLOW_HASH_FALLBACK=false
+KNOWLEDGE_RERANK_DEPLOYMENT_ID=<可选重排部署 ID>
+```
+
+维度变更必须同时提供数据库迁移。重建现有索引：
+
+```powershell
+python manage.py rebuild_knowledge_embeddings
+```
+
+生产环境使用 PostgreSQL 全文和 pgvector HNSW。哈希向量回退只允许测试或明确的本地开发。
+
+### 5.3 自动解决
+
+自动解决默认关闭。启用前需要同时满足：
+
+- Agent 发布版本包含自动解决授权。
+- 发起人具有 `ticket.resolve` 权限。
+- 结果通过引用、风险和置信度校验。
+- `TICKET_AUTO_RESOLVE_ENABLED=true`。
+- 匹配分数达到 `TICKET_AUTO_RESOLVE_MIN_SCORE`。
+
+## 6. 质量检查
+
+后端：
+
+```powershell
+cd backend
+pytest
+ruff check .
+python manage.py check
+python manage.py makemigrations --check --dry-run
+```
+
+前端：
+
+```powershell
 cd frontend
-npm install
-npm run test:run
-npm run lint
-npm run typecheck
-npm run build
+pnpm install --frozen-lockfile
+pnpm test:run
+pnpm typecheck
+pnpm lint
+pnpm build
 ```

-## AI Platform Demo
+当前完整基线为后端 217 项、前端 73 项。更详细的测试分层和提交规范见
+[开发指南](development-guide.md)。

-1. 使用管理员账号打开 `#/modelhub/providers`，创建 OpenAI-compatible 渠道和文本模型，并执行异步连通测试。
-2. 取得模型配置 ID 后创建预置草稿：
+## 7. 固定验收入口
+
+- 智能建单真实文本闭环：
+
+  ```powershell
+  python manage.py verify_ticket_intake --username admin
+  ```
+
+- 阶段 2 报告：
+
+  ```powershell
+  python manage.py report_stage2_acceptance
+  ```
+
+- 阶段 3 报告：
+
+  ```powershell
+  python manage.py report_stage3_acceptance
+  ```
+
+- 统一蓝图报告：
+
+  ```powershell
+  python manage.py report_blueprint_readiness `
+    --evidence ../docs/product/acceptance/blueprint-external-evidence.template.json
+  ```
+
+合成案例只能用于开发回归，不得替代真实业务验收。
+
+## 8. 常见问题
+
+### 前端提示 esbuild 构建被忽略
+
+确认使用 pnpm 11.9.0，并检查 `pnpm-workspace.yaml` 中 `allowBuilds.esbuild` 为 `true`，
+然后重新执行 `pnpm install --frozen-lockfile`。
+
+### 材料上传后扫描失败
+
+确认 ClamAV 已健康：

 ```powershell
-cd backend
-python manage.py seed_ai_demo --deployment-id 1
+docker compose -f infra/docker-compose.local.yml ps clamav
 ```

-3. 在 `#/skills` 检查、编辑并发布三个 Skill。
-4. 在 `#/agents` 编辑技术支持分析 Agent 的模型、步骤和输入映射，先运行草稿沙箱，再发布并运行正式版本。
-5. 在 `#/agent-runs` 查看执行脊柱、每步输入输出、调用尝试、Token、耗时和配置快照。
+ClamAV 首次启动需要下载病毒库。扫描失败只影响对应材料，原件会保留。

-完整验收步骤见 [AI 平台配置演示版验收](ai-platform-demo-acceptance.md)。
+### MinIO 附件不可用

-## Trusted Ticket Intake
+宿主机运行后端时确认 `MINIO_ENDPOINT=localhost:9000`；容器内后端应使用
+`MINIO_ENDPOINT=minio:9000`。

-1. 在模型中心配置并启用一个文本模型。
-2. 发布预置建单 Skill 与单步 Agent：
+### Agent 一直处于 queued

-```powershell
-cd backend
-python manage.py seed_ticket_intake --deployment-id 1
-```
+检查 Redis、Celery Worker 和 Beat 是否运行，并确认 Django 与 Celery 使用同一份 `.env`
+和 `AI_CREDENTIAL_ENCRYPTION_KEY`。

-3. 打开 `#/tickets/create`，输入自然语言描述，审核结构化字段并明确确认。
-4. 可运行固定真实文本验收脚本；脚本会保留草稿、AgentRun、产物、审计和一张验收工单：
+### 修改模型凭据后 Celery 仍报解密失败

-```powershell
-python manage.py verify_ticket_intake --username admin
-```
-
-宿主机直接运行时要确保已加载根目录 `.env` 中的凭证主密钥，并把容器服务主机名覆盖为本机地址。缺少主密钥时脚本会安全失败，不会读取或替换渠道凭证。
-
-图片代码要求 MinIO 可用；只有 `vision_chat` 模型且渠道已由管理员授权图片出境时才允许分析图片。当前真实视觉渠道验收仍待完成。
-
-## Stage 1 API Smoke Tests
-
- Tickets: `GET http://localhost:8000/api/tickets`
- Ticket export: `GET http://localhost:8000/api/tickets/export`
- Solutions: `GET http://localhost:8000/api/solutions`
+重启 Django 和所有 Celery 进程。禁止通过替换 Fernet 主密钥来“修复”单条凭据。