docs: complete Chinese project documentation

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