# 开发指南

本文定义 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`、凭据、运行数据、对象卷、数据库卷、备份、构建产物或本地缓存。
- 不使用破坏性重置清理他人改动；不在未经授权时推送或改写历史。