ai-ticket-platform/docs/development/development-guide.md

开发指南

本文定义 AI 工单平台的代码边界、领域约束、异步任务、迁移、测试和提交规则。环境安装见 本地开发环境，产品行为以项目蓝图为准。

1. 仓库与技术栈

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 标识符保持英文。

前端视觉和组件规则见前端设计系统。

6. 数据库迁移

1. 先修改模型，再执行 python manage.py makemigrations <app>。

2. 检查迁移依赖、约束名称、反向操作和数据迁移的幂等性。

3. 数据迁移使用历史模型，不导入当前业务模型。

4. 向量维度、唯一约束、非空字段等高风险变化需要单独说明升级与回滚方案。

5. 运行：

   python manage.py migrate
   python manage.py makemigrations --check --dry-run
   

禁止修改已经进入共享历史且可能在其他环境执行过的迁移。

7. 注释与文档

• 核心模块使用中文模块 docstring 说明职责和边界。
• 公共编排函数说明事务、幂等、信任或失败语义。
• 行内注释只解释代码无法直接表达的“为什么”，例如提交回调、行锁、降级或安全判断。
• 不为普通 CRUD、简单序列化、测试、迁移、脚本或直观 JSX 添加逐行注释。
• 行为、接口、部署变量或质量基线变化时同步 README 和对应产品/运维文档。

8. 测试分层

• 领域单元测试：状态机、字段保护、授权、验证和指标计算。
• API 测试：权限、输入错误、脱敏和响应兼容。
• 集成测试：数据库事务、对象存储、Celery、SSE、MCP 和渠道。
• 前端测试：关键页面恢复、自动跳转、失败降级、重复提交和权限状态。
• 真实验收：只使用脱敏真实案例和目标环境服务，不以 Mock 或哈希回退代替。

提交前执行：

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