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/development-guide.md
+++ b/docs/development/development-guide.md
@@ -0,0 +1,154 @@
+# 开发指南
+
+本文定义 AI 工单平台的代码边界、领域约束、异步任务、迁移、测试和提交规则。环境安装见
+[本地开发环境](local-setup.md)，产品行为以[项目蓝图](../product/blueprint.md)为准。
+
+## 1. 仓库与技术栈
+
+```text
+backend/
+  apps/       Django 业务应用
+  config/     设置、URL、Celery 和 WSGI/ASGI
+  tests/      跨应用测试配置
+frontend/
+  src/app/        路由与应用壳
+  src/components/ 通用 UI 和项目级 App 组件
+  src/features/   按业务领域组织的页面、API 和类型
+infra/        Compose、Nginx、监控和恢复工具
+docs/         产品、开发、前端、运维和验收文档
+```
+
+- 后端：Python 3.12、Django、Django Ninja、PostgreSQL、pgvector、Celery。
+- 前端：React、TypeScript、Vite、Tailwind CSS、shadcn/ui。
+- 存储与安全：MinIO、ClamAV、Fernet 凭据加密。
+- 工具链：pytest、Ruff、Vitest、ESLint、pnpm。
+
+## 2. 后端应用边界
+
+| 应用 | 职责 |
+|---|---|
+| `accounts` | 用户、权限、菜单、企业身份与组织映射 |
+| `tickets` | 工单聚合、受理、材料、支持分析、回复与评估 |
+| `solutions` | 解决方案和工单权威解决结果 |
+| `knowledge` | 知识、排查方案、文档、索引、检索、治理与蒸馏 |
+| `agents` | Agent 版本、步骤、运行、事件和产物 |
+| `modelhub` | 模型渠道、部署、加密凭据和调用记录 |
+| `tools` | Tool/MCP 目录、授权、调用和风险确认 |
+| `channels` | 企业渠道端点、会话、消息和回执 |
+| `workitems` | 任务中心、活动任务去重和 SLA |
+| `audit` | 业务操作审计 |
+| `system` | 健康、指标和蓝图退出报告 |
+
+API 层负责鉴权、参数解析和响应序列化，不承载跨实体业务事务。复杂业务必须进入对应
+`services.py` 或明确命名的领域模块。
+
+## 3. 领域不变量
+
+### 3.1 工单
+
+- 工单创建、字段更新、状态流转、解决和归档必须通过 `apps.tickets.services`。
+- Agent、Celery、渠道和 Tool 不得直接修改 `Ticket` 状态或受保护字段。
+- 每次状态变化必须记录 `TicketEvent`，Agent 事件关联 `agent_run_id`。
+- 人工修改的业务字段默认受保护；Agent 建议字段保留来源和证据，但不自动获得保护。
+- `TicketResolution` 是权威解决结果，旧展示字段不得成为新的写入来源。
+
+### 3.2 智能受理
+
+- 问题描述是自动建单的唯一门槛；其他缺失字段使工单进入 `pending_info`。
+- 同一受理记录和 Agent 重试只能关联一张正式工单。
+- 对象复制、附件记录、字段证据和建单事件必须处于受控事务；临时对象只在提交后删除。
+- 模型、扫描、解析或存储失败必须保留原始材料并提供人工接管路径。
+- `revision` 是受理记录的乐观锁，客户端不得忽略冲突后直接覆盖。
+
+### 3.3 支持、知识和自动化
+
+- Agent 只能引用启动运行时冻结的知识、方案和历史工单候选。
+- 未发布、范围不匹配或未进入引用快照的内容不能成为可信结论。
+- 知识资产发布需要独立审核；提交人不能审核自己的版本。
+- 索引刷新通过 `transaction.on_commit` 触发，避免读取未提交业务版本。
+- 自动解决同时要求 Agent 授权、全局开关、置信度、风险和操作人权限。
+
+### 3.4 Tool、渠道和身份
+
+- Tool 有效权限是用户权限、用户/用户组授权、Agent 动作和 Agent 授权的交集。
+- 高风险 Tool 必须由非申请人独立确认。
+- MCP 和渠道 URL 只允许无内嵌凭据的 HTTP(S) 地址；真实网络还需由部署层限制出口。
+- 渠道入站、出站和回执必须使用外部 ID 或幂等键去重。
+- OIDC 账号以提供方和稳定 `subject` 关联；显示名不得作为身份主键。
+- 外部组织映射只管理显式配置的业务组，不删除不属于该提供方管理范围的组。
+
+## 4. 异步任务与失败处理
+
+- 在数据库事务内创建业务记录，使用 `transaction.on_commit` 投递 Celery。
+- Celery 任务必须允许重复执行，进入任务时先检查业务终态或幂等键。
+- Agent 运行使用有序 `AgentRunEvent.sequence`；SSE 客户端以 `Last-Event-ID` 或 `after`
+  续传并忽略重复序号。
+- 模型调用使用总时间预算和有限重试，不把渠道原始错误或凭据写入普通审计。
+- 单个材料或目录记录失败不得把整个批次伪装成成功，也不应删除可供排查的原始数据。
+
+## 5. API 与前端约定
+
+- API 路径统一以 `/api` 开头，内部 MCP 单独使用 `/internal-mcp`。
+- Django Ninja Schema 只描述传输结构，业务合法性仍由领域服务验证。
+- 前端 API 请求集中在功能目录的 `api.ts` 或明确命名的 API 模块。
+- 页面使用项目级 `AppPage`、`AppSection`、`AppDataTable`、`AppField` 和语义状态组件。
+- 表单只提交发生变化的字段；时间在浏览器转换为带时区 ISO 8601。
+- 用户可见文案以中文为主，后端字段名和 TypeScript 标识符保持英文。
+
+前端视觉和组件规则见[前端设计系统](../frontend/design-system.md)。
+
+## 6. 数据库迁移
+
+1. 先修改模型，再执行 `python manage.py makemigrations <app>`。
+2. 检查迁移依赖、约束名称、反向操作和数据迁移的幂等性。
+3. 数据迁移使用历史模型，不导入当前业务模型。
+4. 向量维度、唯一约束、非空字段等高风险变化需要单独说明升级与回滚方案。
+5. 运行：
+
+   ```powershell
+   python manage.py migrate
+   python manage.py makemigrations --check --dry-run
+   ```
+
+禁止修改已经进入共享历史且可能在其他环境执行过的迁移。
+
+## 7. 注释与文档
+
+- 核心模块使用中文模块 docstring 说明职责和边界。
+- 公共编排函数说明事务、幂等、信任或失败语义。
+- 行内注释只解释代码无法直接表达的“为什么”，例如提交回调、行锁、降级或安全判断。
+- 不为普通 CRUD、简单序列化、测试、迁移、脚本或直观 JSX 添加逐行注释。
+- 行为、接口、部署变量或质量基线变化时同步 README 和对应产品/运维文档。
+
+## 8. 测试分层
+
+- 领域单元测试：状态机、字段保护、授权、验证和指标计算。
+- API 测试：权限、输入错误、脱敏和响应兼容。
+- 集成测试：数据库事务、对象存储、Celery、SSE、MCP 和渠道。
+- 前端测试：关键页面恢复、自动跳转、失败降级、重复提交和权限状态。
+- 真实验收：只使用脱敏真实案例和目标环境服务，不以 Mock 或哈希回退代替。
+
+提交前执行：
+
+```powershell
+cd backend
+pytest
+ruff check .
+python manage.py check
+python manage.py makemigrations --check --dry-run
+
+cd ..\frontend
+pnpm test:run
+pnpm typecheck
+pnpm lint
+pnpm build
+```
+
+## 9. Git 提交
+
+- 使用英文 Conventional Commit：`feat:`、`fix:`、`test:`、`docs:`、`ops:`、`refactor:`。
+- 一个提交表达一个可说明的功能边界，测试和迁移随功能提交。
+- 暂存前检查 `git diff`，暂存后检查 `git diff --cached` 和
+  `git diff --cached --check`。
+- 不提交 `.env`、凭据、运行数据、对象卷、数据库卷、备份、构建产物或本地缓存。
+- 不使用破坏性重置清理他人改动；不在未经授权时推送或改写历史。
--- 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 主密钥来“修复”单条凭据。