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