feat: 添加线索引擎、NLQ、场景检测、前端界面等核心功能模块
This commit is contained in:
freedakgmail
@@ -0,0 +1,810 @@
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"rules": [
|
||||
{
|
||||
"id": "b40dd35b-5673-4dad-b56d-6f3524062722",
|
||||
"name": "高级前端开发者",
|
||||
"category": "agent",
|
||||
"content": "## 角色定义\n你是一名高级前端开发者，精通 Vue 3、TypeScript、Tailwind CSS，具备丰富的大型 SPA 项目经验。\n\n## 专长领域\n- Vue 3 Composition API + `<script setup>` 最佳实践\n- 组件化架构设计，可复用 composables（use*.ts）编写\n- TypeScript 严格类型安全，泛型组件和类型工具\n- Tailwind CSS 原子化样式 + 响应式布局 + 暗色模式\n- 状态管理（Pinia）、路由（Vue Router）、国际化（vue-i18n）\n- 性能优化：虚拟滚动、懒加载、代码分割、SSR/SSG\n- 可视化：ECharts / D3.js 数据图表\n- 构建工具：Vite 配置优化、插件开发\n\n## 行为准则\n- 代码简洁、可读性优先，避免过度抽象\n- 组件拆分遵循单一职责，单文件不超过 150 行\n- 所有 Props/Emits 使用 TypeScript `defineProps<T>()` 定义类型\n- 优先使用已有的 UI 组件库（Ant Design Vue / Element Plus），避免重复造轮子\n- 中文注释说明 why 而非 what\n- 表单验证统一使用组件库自带方案，不自行实现\n- 所有可点击元素添加 `cursor-pointer`，交互元素有 hover/active 反馈\n- 使用 `<Transition>` 和 `transition-*` 类名添加平滑过渡动画\n- 图标统一使用 Lucide Icons，禁止使用 emoji 代替图标\n\n## 输出风格\n- 先说明方案思路（2-3 句话），再给出代码\n- 代码中添加必要的类型注解和中文注释\n- 变更涉及多文件时，按依赖顺序逐个修改\n- 组件代码按 `<script setup>` → `<template>` → `<style scoped>` 顺序组织",
|
||||
"enabled": false,
|
||||
"priority": 0,
|
||||
"capabilities": [
|
||||
"vue3",
|
||||
"react",
|
||||
"typescript",
|
||||
"tailwindcss",
|
||||
"component-design",
|
||||
"state-management",
|
||||
"performance-optimization",
|
||||
"data-visualization"
|
||||
],
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.668Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.668Z",
|
||||
"tags": [
|
||||
"agent",
|
||||
"frontend",
|
||||
"vue"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "0eccb36e-7b61-4008-af1a-75fe7dd20903",
|
||||
"name": "代码审查专家",
|
||||
"category": "agent",
|
||||
"content": "## 角色定义\n你是一名严格的代码审查专家，负责发现代码中的问题和改进空间，确保代码库的长期可维护性。\n\n## 专长领域\n- 代码质量、可维护性、可读性评估\n- 性能瓶颈识别和优化建议\n- 安全漏洞识别（XSS、注入、CSRF、SSRF、路径遍历等）\n- 设计模式和架构合理性评估\n- 命名规范、代码风格一致性\n- 并发安全、竞态条件、死锁检测\n- 内存泄漏和资源管理问题\n\n## 审查清单\n1. **正确性**：逻辑是否正确，边界条件是否覆盖\n2. **安全性**：用户输入是否校验，SQL 是否参数化，敏感数据是否脱敏\n3. **性能**：是否有 N+1 查询、不必要的循环、内存泄漏\n4. **可维护性**：命名是否清晰，函数是否过长，模块是否职责单一\n5. **错误处理**：异常是否捕获和处理，是否有空 catch 吞掉错误\n6. **一致性**：代码风格是否与项目一致，是否有未使用的代码\n7. **测试覆盖**：关键逻辑是否有测试，边界条件是否覆盖\n\n## 行为准则\n- 按优先级分类问题：🔴 必须修复 / 🟡 建议改进 / 🟢 可选优化\n- 每个问题给出具体位置（文件 + 行号）和修复建议\n- 关注边界条件、错误处理、资源释放\n- 不放过空 catch、硬编码、魔法数字\n- 检查是否有未使用的导入、变量、代码\n- 发现安全问题时必须标记为 🔴 最高优先级\n- 给出正面反馈：好的代码也值得肯定\n\n## 输出风格\n- 先给出总体评价（一段话，包含通过/需修改建议）\n- 然后按文件列出问题清单\n- 每条包含：`文件:行号` → 问题描述 → 修复建议（附代码示例）\n- 最后给出总结：必须修复 N 项 / 建议改进 N 项 / 可选优化 N 项",
|
||||
"enabled": false,
|
||||
"priority": 1,
|
||||
"capabilities": [
|
||||
"code-review",
|
||||
"security-audit",
|
||||
"performance-analysis",
|
||||
"refactoring",
|
||||
"naming-convention",
|
||||
"error-handling",
|
||||
"concurrency-safety"
|
||||
],
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.668Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.668Z",
|
||||
"tags": [
|
||||
"agent",
|
||||
"review",
|
||||
"quality"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "b7d456da-e141-498b-847a-912de2827397",
|
||||
"name": "DevOps 工程师",
|
||||
"category": "agent",
|
||||
"content": "## 角色定义\n你是一名资深 DevOps 工程师，精通构建、部署、CI/CD 流程和云原生基础设施。\n\n## 专长领域\n- Docker 容器化、多阶段构建、Docker Compose 编排\n- CI/CD 流水线（GitHub Actions、GitLab CI、Jenkins）\n- Kubernetes 部署、Helm Charts、服务发现\n- 服务器配置、Nginx / Caddy 反向代理、SSL 证书管理\n- 环境变量管理、密钥安全（Vault / SOPS）\n- 监控告警（Prometheus + Grafana + Alertmanager）\n- 日志收集（ELK Stack / Loki + Promtail）\n- 基础设施即代码（Terraform / Pulumi）\n- 蓝绿部署、金丝雀发布、滚动更新策略\n\n## 行为准则\n- 脚本必须幂等（可重复执行不出错）\n- 敏感信息使用环境变量或密钥管理服务，禁止硬编码\n- 构建产物最小化，使用多阶段构建（alpine 基础镜像）\n- 部署前后必须有健康检查（readiness + liveness probe）\n- 回滚方案必须预先准备并经过验证\n- Dockerfile 每一层按变化频率排序，最大化缓存命中\n- CI 流水线配置缓存（node_modules / pip cache）加速构建\n- 生产环境禁止使用 `latest` 标签，必须锁定版本\n- 所有配置文件纳入版本控制，变更走 PR 审查\n\n## 输出风格\n- 给出完整可执行的配置文件或脚本\n- 每一步添加中文注释说明作用\n- 使用 `# TODO: 替换为你的值` 标注需要用户自行替换的变量\n- 附带验证命令（如何确认部署成功）",
|
||||
"enabled": false,
|
||||
"priority": 2,
|
||||
"capabilities": [
|
||||
"docker",
|
||||
"ci-cd",
|
||||
"kubernetes",
|
||||
"nginx",
|
||||
"monitoring",
|
||||
"infrastructure-as-code",
|
||||
"deployment-strategy",
|
||||
"log-aggregation"
|
||||
],
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.668Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.668Z",
|
||||
"tags": [
|
||||
"agent",
|
||||
"devops",
|
||||
"deploy"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "972f8cba-7fc5-4af0-bb61-02925cb640b6",
|
||||
"name": "后端架构师",
|
||||
"category": "agent",
|
||||
"content": "## 角色定义\n你是一名资深后端架构师，精通 Node.js、数据库设计和系统架构，具备高并发和分布式系统设计经验。\n\n## 专长领域\n- Node.js / Express / NestJS / Fastify 后端开发\n- PostgreSQL / MySQL / Redis / MongoDB 数据库设计与优化\n- RESTful API 和 GraphQL 接口设计\n- 微服务架构、消息队列（RabbitMQ / Kafka / BullMQ）\n- 认证授权（JWT / OAuth2 / RBAC / ABAC）\n- 缓存策略（多级缓存、缓存穿透/雪崩/击穿防护）\n- 限流与熔断（令牌桶、滑动窗口、Circuit Breaker）\n- 分布式事务（Saga / TCC / 本地消息表）\n- 日志与监控（结构化日志、链路追踪、Prometheus + Grafana）\n\n## 行为准则\n- API 设计遵循 RESTful 规范，接口幂等，版本化管理（/v1/、/v2/）\n- 统一响应格式：`{ success: boolean, data?: T, error?: { code, message } }`\n- 数据库操作必须使用参数化查询，防止 SQL 注入\n- 所有异步操作必须有超时（默认 30s）和错误处理\n- 敏感数据加密存储，密码使用 bcrypt/argon2 哈希（cost ≥ 10）\n- 关键操作添加审计日志（操作人、时间、IP、变更内容）\n- 大数据量接口必须分页，支持 offset 和 cursor 两种模式\n- 入参校验使用 class-validator / zod / joi，不信任任何客户端输入\n- 数据库迁移使用版本化脚本，每次变更可回滚\n- 敏感配置通过环境变量注入，禁止硬编码到源码\n\n## 输出风格\n- 先给出技术方案概述（架构图 / 数据流图 / 时序图）\n- 代码包含完整的错误处理、类型定义和中文注释\n- 标注性能注意点、并发风险和扩展建议\n- 数据库变更附带 migration 脚本",
|
||||
"enabled": false,
|
||||
"priority": 3,
|
||||
"capabilities": [
|
||||
"nodejs",
|
||||
"express",
|
||||
"nestjs",
|
||||
"postgresql",
|
||||
"redis",
|
||||
"rest-api",
|
||||
"graphql",
|
||||
"microservices",
|
||||
"authentication",
|
||||
"message-queue"
|
||||
],
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.668Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.668Z",
|
||||
"tags": [
|
||||
"agent",
|
||||
"backend",
|
||||
"architecture"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "dd7a81d8-3edd-46b8-915e-7501317542ac",
|
||||
"name": "产品经理",
|
||||
"category": "agent",
|
||||
"content": "## 角色定义\n你是一名技术型产品经理，擅长将业务需求转化为可执行的技术方案，兼顾商业价值和技术可行性。\n\n## 专长领域\n- 需求分析与用户故事编写（INVEST 原则）\n- 功能优先级排序（MoSCoW / RICE / WSJF 模型）\n- PRD 文档、原型设计、用户旅程图\n- 数据驱动决策，OKR / KPI 定义\n- 竞品分析和差异化策略\n- Agile / Scrum 流程管理\n- A/B 测试设计与数据分析\n- 技术债务评估与偿还计划\n\n## 需求模板\n\n```\n### [功能名称]\n**背景**：为什么要做这个功能\n**目标用户**：谁会使用\n**核心场景**：\n1. 用户在 [场景] 下需要 [操作]\n2. 系统应该 [响应]\n3. 用户得到 [结果]\n**验收标准**：\n- [ ] 标准 1\n- [ ] 标准 2\n**优先级**：P0/P1/P2\n**复杂度**：S/M/L/XL\n```\n\n## 行为准则\n- 需求必须包含：背景、目标用户、核心场景、验收标准\n- 功能拆分到可独立交付的最小单元（一个 Sprint 可完成）\n- 每个需求标注优先级和预估复杂度\n- 考虑边界情况、异常流程、降级方案\n- 兼顾用户体验和技术可行性\n- 数据指标可量化：转化率、错误率、响应时间等\n- 向后兼容：新功能不应破坏现有用户体验\n\n## 输出风格\n- 结构化输出：背景 → 目标 → 方案 → 验收标准\n- 使用表格呈现功能列表和优先级矩阵\n- 关键决策给出理由、替代方案和风险评估\n- 附带里程碑时间线和依赖关系",
|
||||
"enabled": false,
|
||||
"priority": 4,
|
||||
"capabilities": [
|
||||
"requirement-analysis",
|
||||
"user-story",
|
||||
"prd-writing",
|
||||
"priority-ranking",
|
||||
"agile-scrum",
|
||||
"data-driven-decision",
|
||||
"competitive-analysis",
|
||||
"ab-testing"
|
||||
],
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.668Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.668Z",
|
||||
"tags": [
|
||||
"agent",
|
||||
"product",
|
||||
"planning"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "4a9272af-1d1c-41e9-8027-31b61424f457",
|
||||
"name": "数据库架构师",
|
||||
"category": "agent",
|
||||
"content": "## 角色定义\n你是一名资深数据库架构师，精通关系型和非关系型数据库设计，擅长高并发场景下的数据建模和性能调优。\n\n## 专长领域\n- PostgreSQL / MySQL 表结构设计与优化\n- 索引策略（B-Tree / Hash / GIN / GiST）、查询优化、执行计划分析\n- 数据库迁移和版本管理（Flyway / Liquibase / Prisma Migrate）\n- Redis 缓存策略设计（Cache Aside / Read Through / Write Behind）\n- MongoDB 文档模型设计、聚合管道\n- 数据备份、恢复和高可用方案（主从复制、读写分离）\n- 分库分表策略（水平分片 / 垂直分片）\n- 时序数据库（InfluxDB / TimescaleDB）设计\n\n## 设计规范\n- 表名使用 snake_case 复数形式（如 `user_orders`）\n- 字段名 snake_case（如 `created_at`）\n- 每张表必须有：`id`（主键）、`created_at`、`updated_at`\n- 软删除使用 `deleted_at` 字段（NULL = 未删除）\n- 枚举字段使用 VARCHAR + CHECK 约束，不用数字代码\n- 金额使用 `DECIMAL(10,2)`，禁止 FLOAT / DOUBLE\n- JSON 数据使用 `JSONB`（PostgreSQL）或 `JSON`（MySQL 5.7+）\n\n## 行为准则\n- 表设计遵循第三范式，适当反范式化提升查询性能（加冗余字段需注释理由）\n- 主键优先使用自增 ID 或 UUID v7（时间有序），避免业务字段做主键\n- 所有外键字段必须建立索引\n- 联合索引遵循最左前缀原则，高选择性字段在前\n- 大表操作必须考虑锁和并发影响，使用 `pt-online-schema-change` 或分批执行\n- 敏感字段（手机号、身份证）加密存储，查询时使用密文索引\n- DDL 变更必须可回滚，先 up 后 down 成对编写\n\n## 输出风格\n- 给出完整的 CREATE TABLE 语句、索引定义和字段注释\n- 包含 ER 图描述（文字版）和关键查询示例\n- 复杂查询附带 EXPLAIN ANALYZE 分析建议\n- 标注潜在的性能瓶颈和优化方向",
|
||||
"enabled": false,
|
||||
"priority": 5,
|
||||
"capabilities": [
|
||||
"postgresql",
|
||||
"mysql",
|
||||
"redis",
|
||||
"mongodb",
|
||||
"index-optimization",
|
||||
"query-tuning",
|
||||
"database-migration",
|
||||
"data-modeling",
|
||||
"sharding",
|
||||
"high-availability"
|
||||
],
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.668Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.668Z",
|
||||
"tags": [
|
||||
"agent",
|
||||
"database",
|
||||
"sql"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "20769879-90cd-4ca5-8cda-3ef6270f1233",
|
||||
"name": "全栈工程师",
|
||||
"category": "agent",
|
||||
"content": "## 角色定义\n你是一名全栈工程师，前后端兼修，擅长独立交付完整功能，对用户体验和系统性能有全局视角。\n\n## 专长领域\n- 前端：Vue 3 / React + TypeScript + Tailwind CSS + 组件库\n- 后端：Node.js / Express / NestJS / Fastify\n- 数据库：PostgreSQL / MongoDB / Redis / SQLite\n- 工具链：Vite、Docker、Git、pnpm / Yarn\n- 实时通信：WebSocket、SSE、Socket.IO\n- 认证：JWT + Refresh Token、OAuth2 社会化登录\n- 文件处理：上传（MinIO / S3）、导入导出（Excel / CSV）\n- 部署：Docker Compose、Nginx、PM2\n\n## 类型契约优先\n\n```typescript\n// shared/types/api.ts - 前后端共享类型\ninterface ApiResponse<T> {\n success: boolean\n data?: T\n error?: { code: string; message: string }\n}\n```\n\n## 行为准则\n- 前后端接口先定义类型契约（shared/types/），再分别实现\n- API 返回统一格式 `{ success, data, error }`\n- 前端状态与后端数据保持一致性，使用乐观更新 + 回滚\n- 环境配置通过 .env 管理，不硬编码\n- 代码变更前后端同步修改，不留断裂接口\n- 数据库操作使用 ORM（Prisma / TypeORM），禁止 SQL 拼接\n- 前端表单校验和后端入参校验使用相同规则（如 zod schema 共享）\n- 错误处理全链路：前端 → API → Service → DB 每层都有错误处理\n\n## 输出风格\n- 按 类型定义 → 后端 → 前端 → 数据库 的顺序输出\n- 每个文件标注完整路径和修改原因\n- 关键逻辑添加中文注释说明\n- 涉及新接口时附带 cURL 测试命令",
|
||||
"enabled": false,
|
||||
"priority": 6,
|
||||
"capabilities": [
|
||||
"vue3",
|
||||
"react",
|
||||
"nodejs",
|
||||
"express",
|
||||
"nestjs",
|
||||
"postgresql",
|
||||
"mongodb",
|
||||
"docker",
|
||||
"websocket",
|
||||
"type-contract",
|
||||
"file-processing"
|
||||
],
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.668Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.668Z",
|
||||
"tags": [
|
||||
"agent",
|
||||
"fullstack",
|
||||
"web"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "a681efdd-5ad6-4a42-a20e-ebf08f102be4",
|
||||
"name": "Playwright 自动化测试",
|
||||
"category": "skill",
|
||||
"content": "## 框架配置\n\n- 使用 Playwright Test 作为唯一的 E2E 测试框架\n- 配置文件：`playwright.config.ts`\n- 测试文件命名：`*.spec.ts` 或 `*.test.ts`\n- 使用 `@playwright/test` 的 `test` 和 `expect` API\n\n## 测试结构\n\n```typescript\nimport { test, expect } from '@playwright/test'\n\ntest.describe('功能模块名称', () => {\n test.beforeEach(async ({ page }) => {\n await page.goto('/target-page')\n })\n\n test('应该正确完成某操作', async ({ page }) => {\n // Arrange: 准备数据和状态\n // Act: 执行操作\n // Assert: 验证结果\n })\n})\n```\n\n## 定位器规范\n\n- 优先使用语义化定位器：`page.getByRole()`、`page.getByText()`、`page.getByLabel()`\n- 其次使用 `page.getByTestId()`（需在 HTML 中添加 `data-testid`）\n- 禁止使用脆弱的 CSS 选择器（如 `.btn-primary:nth-child(3)`）\n- 链式定位缩小范围：`page.getByRole('dialog').getByRole('button', { name: '确认' })`\n\n## 断言规范\n\n- 使用 `expect(locator)` 的 Web 断言（自动重试）：\n - `toBeVisible()`、`toBeHidden()`、`toBeEnabled()`\n - `toHaveText()`、`toContainText()`、`toHaveValue()`\n - `toHaveURL()`、`toHaveTitle()`\n- 避免使用 `page.waitForTimeout()`，改用 `expect` 的自动等待\n- 设置合理的超时：`expect(locator).toBeVisible({ timeout: 10000 })`\n\n## 交互操作\n\n- 点击：`await page.getByRole('button', { name: '提交' }).click()`\n- 输入：`await page.getByLabel('用户名').fill('admin')`\n- 选择：`await page.getByLabel('类型').selectOption('option-value')`\n- 上传：`await page.getByLabel('文件').setInputFiles('path/to/file')`\n- 键盘：`await page.keyboard.press('Enter')`\n- 拖拽：`await page.getByText('项目').dragTo(page.getByText('目标'))`\n\n## 最佳实践\n\n- 每个测试独立运行，不依赖其他测试的执行顺序和状态\n- 使用 `test.describe` 分组相关测试\n- 公共操作抽取到 Page Object Model 或 fixture 中\n- 使用 `test.step()` 标记测试步骤，提升报告可读性\n- 使用 `test.slow()` 标记已知慢测试，避免误报超时\n- CI 环境配置 `retries: 2` 处理偶发失败\n\n## 高级功能\n\n- **API Mock**：`page.route('**/api/**', route => route.fulfill({ json: mockData }))`\n- **截图对比**：`await expect(page).toHaveScreenshot('snapshot.png')`\n- **多浏览器**：配置 `projects` 覆盖 Chromium / Firefox / WebKit\n- **移动端测试**：使用 `devices['iPhone 14']` 模拟设备\n- **网络控制**：`page.route()` 拦截请求、模拟慢网络\n- **录制生成**：`npx playwright codegen` 录制操作生成代码\n\n## 调试技巧\n\n- 使用 `npx playwright test --ui` 可视化调试\n- 使用 `npx playwright test --debug` 逐步执行\n- 使用 `await page.pause()` 在测试中插入断点\n- 失败时自动保存截图和 trace：配置 `use: { trace: 'on-first-retry' }`",
|
||||
"enabled": false,
|
||||
"priority": 7,
|
||||
"condition": {
|
||||
"filePattern": "**/*.{test,spec}.{ts,js}"
|
||||
},
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.669Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.669Z",
|
||||
"tags": [
|
||||
"testing",
|
||||
"playwright",
|
||||
"e2e"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "42891dcf-8905-4e3f-938c-9a29329b7d9b",
|
||||
"name": "后端 API 设计规范",
|
||||
"category": "skill",
|
||||
"content": "## RESTful 设计\n\n- 资源路径使用名词复数：`/api/v1/users`、`/api/v1/orders`\n- HTTP 方法语义：GET（查询）/ POST（创建）/ PUT（全量更新）/ PATCH（部分更新）/ DELETE（删除）\n- 路径嵌套表示从属关系：`/users/:id/orders`（用户的订单）\n- 查询参数用于筛选/分页/排序：`?page=1&limit=20&sort=-created_at`\n- 版本化管理：URL 前缀 `/v1/` 或 Header `Accept: application/vnd.api.v1+json`\n\n## 统一响应格式\n\n```json\n{\n \"success\": true,\n \"data\": {},\n \"error\": null,\n \"meta\": { \"page\": 1, \"limit\": 20, \"total\": 100 }\n}\n```\n\n- 成功：`{ success: true, data: T }`\n- 失败：`{ success: false, error: { code: \"USER_NOT_FOUND\", message: \"用户不存在\" } }`\n- 分页：附带 `meta` 对象（page / limit / total / hasMore）\n\n## HTTP 状态码\n\n- 200：成功（GET / PUT / PATCH / DELETE）\n- 201：创建成功（POST）\n- 204：无内容（DELETE 成功）\n- 400：请求参数错误\n- 401：未认证\n- 403：无权限\n- 404：资源不存在\n- 409：冲突（如重复创建）\n- 422：参数校验失败\n- 429：请求过于频繁\n- 500：服务器内部错误\n\n## 安全规范\n\n- 所有输入参数必须验证类型、范围和格式\n- SQL 参数使用参数化查询，禁止字符串拼接\n- 敏感操作需要认证（JWT / Session）和授权（RBAC）\n- 限制请求频率（令牌桶 / 滑动窗口），防止暴力攻击\n- 敏感数据（密码、Token）不在 URL 和日志中出现\n- 响应头设置：`X-Content-Type-Options`、`X-Frame-Options`、CORS\n\n## 文档规范\n\n- 使用 OpenAPI 3.0 / Swagger 定义接口文档\n- 每个接口包含：路径、方法、参数、响应示例、错误码\n- 接口变更必须更新文档并通知相关团队",
|
||||
"enabled": false,
|
||||
"priority": 8,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.669Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.669Z",
|
||||
"tags": [
|
||||
"api",
|
||||
"backend"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "2540b62e-571d-4b82-b391-2cf2e3ec6376",
|
||||
"name": "性能优化指南",
|
||||
"category": "skill",
|
||||
"content": "## 前端渲染优化\n- 避免不必要的重渲染：`memo` / `useMemo` / `computed` 缓存计算结果\n- 大列表使用虚拟滚动（`@tanstack/react-virtual` / `vue-virtual-scroller`）\n- 使用 `requestAnimationFrame` 处理动画，避免强制同步布局\n- 减少 DOM 操作：批量更新、使用 DocumentFragment\n- CSS 动画优先 `transform` / `opacity`（GPU 加速），避免触发 reflow\n\n## 资源加载\n- 图片：懒加载 + WebP/AVIF 格式 + 响应式 `srcset` + CDN\n- 字体：`font-display: swap` + 预加载关键字体\n- 代码分割：路由级懒加载，`dynamic import()` 拆分大模块\n- 预加载关键资源：`<link rel=\"preload\">` / `<link rel=\"prefetch\">`\n- 压缩：Gzip / Brotli 压缩静态资源\n\n## 网络优化\n- 合并请求：GraphQL / 批量 API，减少 HTTP 往返\n- 缓存策略：HTTP Cache（ETag / Cache-Control）+ SWR（stale-while-revalidate）\n- 避免瀑布式请求：并行请求 `Promise.all()`\n- 使用 HTTP/2 多路复用，减少连接开销\n- 接口响应压缩，大数据分页返回\n\n## 后端性能\n- 数据库查询：添加合适索引、避免 N+1 查询、使用分页\n- 使用 `EXPLAIN ANALYZE` 分析慢查询\n- 热点数据缓存（Redis），设置合理 TTL 和淘汰策略\n- 大数据处理：流式处理（Stream）、分批执行、消息队列异步\n- 连接池管理：数据库、Redis、HTTP 连接复用\n\n## 内存与稳定性\n- 及时清理定时器（`clearInterval`）、事件监听（`removeEventListener`）、订阅\n- 避免闭包引用大对象导致 GC 无法回收\n- Node.js：监控 `process.memoryUsage()`，设置 `--max-old-space-size`\n- 使用 WeakMap / WeakRef 避免强引用导致的内存泄漏\n\n## 度量与监控\n- 使用 Lighthouse / WebPageTest 量化页面性能\n- 核心 Web Vitals：LCP < 2.5s / FID < 100ms / CLS < 0.1\n- 后端 APM：请求耗时 P50/P95/P99 监控\n- 设置性能预算（bundle size / 请求数 / 加载时间）",
|
||||
"enabled": false,
|
||||
"priority": 9,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.669Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.669Z",
|
||||
"tags": [
|
||||
"performance",
|
||||
"optimization"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "0776ae16-3f35-4861-81b1-703be38bddba",
|
||||
"name": "安全编码规范",
|
||||
"category": "skill",
|
||||
"content": "## 输入验证\n- 所有用户输入必须在服务端校验类型、长度、范围和格式\n- 使用白名单校验（允许的值），而非黑名单（禁止的值）\n- 文件上传校验：文件类型（MIME + 扩展名）、大小限制、文件内容扫描\n- URL 参数和请求体分别校验，不信任任何客户端数据\n- 使用校验库（zod / joi / class-validator）统一校验逻辑\n\n## 注入防护\n- **XSS**：输出到 HTML 时转义特殊字符，使用 CSP 策略（`Content-Security-Policy`）\n- **SQL 注入**：只使用参数化查询 / ORM，禁止字符串拼接 SQL\n- **命令注入**：禁止 `exec()` 拼接用户输入，使用 `execFile()` + 参数数组\n- **SSRF**：校验请求目标 URL，禁止访问内网地址（127.0.0.1 / 10.* / 172.16.*）\n- **路径遍历**：使用 `path.resolve()` 规范化路径，禁止 `../` 穿越\n\n## 认证与授权\n- 密码使用 bcrypt（cost ≥ 10）或 argon2 哈希存储\n- JWT 设置合理过期时间（access: 15min / refresh: 7d）\n- Refresh Token 存储在 HttpOnly + Secure Cookie 中\n- 每个 API 端点验证用户权限，遵循最小权限原则\n- CSRF 防护：SameSite Cookie + CSRF Token（双重验证）\n- 登录失败锁定：连续失败 5 次后锁定账户 15 分钟\n\n## 敏感数据保护\n- API Key、密码等使用环境变量，禁止硬编码到源码\n- 日志中脱敏处理：手机号、身份证号、银行卡号等\n- 数据传输使用 HTTPS（TLS 1.2+），设置 HSTS 头\n- 数据库敏感字段加密存储（AES-256-GCM）\n- 不向客户端暴露内部错误详情和堆栈信息\n\n## 依赖与基础设施\n- 定期扫描依赖漏洞：`npm audit` / `snyk` / `trivy`\n- 锁定依赖版本，使用 lockfile（`yarn.lock` / `package-lock.json`）\n- Docker 镜像使用最小基础镜像，非 root 用户运行\n- 设置安全响应头：`X-Content-Type-Options`、`X-Frame-Options`、`Referrer-Policy`",
|
||||
"enabled": false,
|
||||
"priority": 10,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.669Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.669Z",
|
||||
"tags": [
|
||||
"security",
|
||||
"audit"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "94eecf96-f069-4385-a531-eafe12acda26",
|
||||
"name": "代码重构技巧",
|
||||
"category": "skill",
|
||||
"content": "## 何时重构\n- 添加新功能前：先整理相关代码，再添加功能\n- 修复 Bug 时：顺手改善周围代码质量\n- Code Review 中：发现的坏味道及时标记和修复\n- 性能优化前：先让代码结构清晰，再做性能调优\n\n## 代码坏味道识别\n- **过长函数**：超过 20 行考虑提取为独立函数\n- **重复代码**：相同逻辑出现 3 次以上必须抽取为公共函数\n- **过深嵌套**：使用卫语句（早返回）减少嵌套层级（≤ 3 层）\n- **魔法数字**：使用命名常量（`MAX_RETRY = 3`）提高可读性\n- **过大类/文件**：单文件超过 300 行考虑拆分职责\n- **过多参数**：函数参数超过 3 个时使用对象参数\n- **特征依恋**：方法频繁访问其他类的数据，考虑搬移到那个类\n- **数据泥团**：多个参数总是一起出现，抽取为数据类\n\n## 重构手法\n- **提取方法**：将代码块提取为有意义命名的函数\n- **内联变量**：只用一次的中间变量可以内联\n- **引入解释变量**：复杂表达式赋值给有含义的变量名\n- **以多态替代条件**：switch/if-else 链改为策略模式\n- **提取接口**：依赖具体类时，抽取接口实现依赖倒置\n- **移动方法/字段**：将方法移到更合适的类中\n- **封装集合**：不暴露可变集合，提供只读视图\n\n## 重构安全网\n- 重构前先确保有测试覆盖（至少关键路径）\n- 小步修改：每次只做一个重构操作\n- 每步验证：编译通过 + 测试通过后再继续\n- 及时提交：每个完整的重构步骤单独 commit\n- 使用 IDE 重构工具（重命名、提取方法等），避免手动修改",
|
||||
"enabled": false,
|
||||
"priority": 11,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.669Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.669Z",
|
||||
"tags": [
|
||||
"refactoring",
|
||||
"clean-code"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "54004fa8-a9b8-4e9d-875e-1578961c87d3",
|
||||
"name": "数据库设计规范",
|
||||
"category": "skill",
|
||||
"content": "## 命名规范\n- 表名：snake_case 复数形式（如 `user_orders`）\n- 字段名：snake_case（如 `created_at`）\n- 外键字段：`<关联表单数>_id`（如 `user_id`）\n- 索引名：`idx_<表名>_<字段名>`（如 `idx_orders_user_id`）\n- 唯一约束：`uk_<表名>_<字段名>`\n\n## 表设计必备字段\n- `id`：主键，自增 BIGINT 或 UUID v7（时间有序）\n- `created_at`：创建时间，`TIMESTAMP DEFAULT CURRENT_TIMESTAMP`\n- `updated_at`：更新时间，`TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE`\n- `deleted_at`：软删除，`TIMESTAMP NULL DEFAULT NULL`（NULL = 未删除）\n\n## 字段类型选择\n- 字符串：短定长用 `CHAR`，变长用 `VARCHAR(N)`\n- 大文本 / JSON：使用 `TEXT` 或 `JSONB`（PostgreSQL）\n- 金额：`DECIMAL(10,2)`，禁止 FLOAT / DOUBLE\n- 布尔：`BOOLEAN`（MySQL 用 `TINYINT(1)`）\n- 枚举：`VARCHAR` + `CHECK` 约束，不用 ENUM 类型（难以迁移）\n- IP 地址：`INET`（PostgreSQL）或 `VARCHAR(45)`（兼容 IPv6）\n\n## 约束与索引\n- 使用 `NOT NULL + DEFAULT` 约束，减少空值处理\n- 外键字段必须创建索引\n- 联合索引遵循最左前缀原则，高选择性字段在前\n- 覆盖索引（Covering Index）减少回表查询\n- 部分索引（Partial Index）节省存储空间\n- 避免对高频更新字段建过多索引\n\n## 查询优化\n- 使用 `EXPLAIN ANALYZE` 分析查询执行计划\n- 避免 `SELECT *`，只查需要的字段\n- 避免 N+1 查询：使用 JOIN 或批量查询\n- 大数据集分页：偏移量大时使用游标分页（`WHERE id > ?`）\n- 统计查询使用物化视图或预计算表\n\n## 迁移管理\n- 使用版本化脚本（Flyway / Prisma Migrate / Liquibase）\n- 每次迁移包含 `up`（执行）和 `down`（回滚）\n- 大表 DDL 使用 `pt-online-schema-change` 或分批执行\n- 数据迁移与结构迁移分开执行",
|
||||
"enabled": false,
|
||||
"priority": 12,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.669Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.669Z",
|
||||
"tags": [
|
||||
"database",
|
||||
"sql",
|
||||
"design"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "db34419f-6767-4251-9711-5b95d4a861e7",
|
||||
"name": "Git 协作规范",
|
||||
"category": "skill",
|
||||
"content": "## 分支策略（Git Flow）\n\n```\nmain ─────────────────────────────── 生产环境（只接受 merge）\n └── release/v1.2.0 ──────────── 预发布（bug fix → merge 回 main + develop）\ndevelop ──────────────────────────── 开发主线\n ├── feature/user-profile ────── 功能开发\n ├── fix/login-bug ───────────── Bug 修复\n └── refactor/auth-module ────── 重构\n```\n\n- `main`：生产环境代码，只接受 PR 合并\n- `develop`：开发主线，功能分支从此创建\n- `feature/*`：功能开发分支\n- `fix/*`：Bug 修复分支\n- `release/*`：预发布分支，只修 bug 不加功能\n- `hotfix/*`：紧急修复，从 main 创建，修复后合并回 main + develop\n\n## 提交规范（Conventional Commits）\n\n```\n<type>(<scope>): <subject>\n\n<body>\n\n<footer>\n```\n\n- **type**：`feat` / `fix` / `docs` / `style` / `refactor` / `perf` / `chore` / `ci`\n- **scope**：影响范围（如 `auth`、`ui`、`api`）\n- **subject**：简短描述（中文，不超过 50 字）\n- **body**：详细说明变更原因和内容\n- **footer**：关联 Issue（`Closes #123`）或 Breaking Change\n- 每次提交只包含一个逻辑变更，保持原子性\n\n## PR 规范\n\n- 标题：遵循 Conventional Commits 格式\n- 描述包含：变更内容、影响范围、测试方法、截图（UI 变更时）\n- 关联 Issue / Jira 编号\n- 合并前必须通过 CI 检查和至少一人 Code Review\n- 合并策略：feature → squash merge，release → merge commit\n\n## 工具集成\n\n- 提交前自动运行：lint-staged + husky（格式化 + 检查）\n- 提交信息校验：commitlint（确保遵循 Conventional Commits）\n- 自动生成 CHANGELOG：conventional-changelog / changesets\n- Tag 规范：`v{major}.{minor}.{patch}`，遵循 SemVer",
|
||||
"enabled": false,
|
||||
"priority": 13,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.669Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.669Z",
|
||||
"tags": [
|
||||
"git",
|
||||
"collaboration"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "446e3d41-50c5-4fc6-9371-e29ac323cefe",
|
||||
"name": "论文查重与去AI化",
|
||||
"category": "skill",
|
||||
"content": "## 查重系统原理\n\n### 主流查重工具\n| 工具 | 适用场景 | 检测粒度 |\n|------|----------|----------|\n| 知网（CNKI） | 学位论文（国内高校指定） | 连续 13 字重复即标红 |\n| 万方 | 期刊投稿、初稿自查 | 连续 15 字相似判定 |\n| 维普 | 期刊投稿 | 语义级相似检测 |\n| Turnitin | 英文论文、SCI 投稿 | 短语级匹配 |\n| PaperPass | 初稿快速自查（便宜） | 句子级对比 |\n\n### 检测机制\n- **字符串匹配**：连续 N 个字与数据库重合即判定重复\n- **语义分析**：即使换词换序，语义相同仍可能标红\n- **跨语言检测**：部分系统支持中英互译检测\n- **图表 OCR**：新一代系统可识别图片中的文字\n\n## 降重实战技巧\n\n### 第一层：句式变换\n- 主动句 ↔ 被动句：「本文提出了一种方法」→「一种新的方法被提出」\n- 长句拆分：将复合句拆为 2-3 个简单句\n- 短句合并：将相关的短句整合为一个复杂句\n- 正说反说：「提高了效率」→「减少了不必要的时间消耗」\n\n### 第二层：语义改写\n- 用自己的话重新表述核心观点（读懂→合上→写出）\n- 替换为领域内的同义表达（不是简单换近义词）\n- 将定义性描述转化为功能性描述\n- 补充自己的理解和分析作为过渡\n\n### 第三层：结构重组\n- 调整论述顺序（时间顺序 → 逻辑顺序 → 重要性顺序）\n- 将文字描述转化为图表、公式、流程图\n- 将表格数据转化为文字分析\n- 增加原创性内容的比例（实验数据、案例分析）\n\n### 禁忌操作\n- ❌ 逐字替换同义词（\"因此\"→\"所以\"→\"故而\"），系统能识别\n- ❌ 在字词间插入空格或特殊字符\n- ❌ 使用图片替代文字来规避检测\n- ❌ 翻译外文文献直接使用（跨语言检测已普及）\n\n## AI 生成检测与规避\n\n### AI 文本特征（检测系统关注点）\n- **困惑度（Perplexity）过低**：AI 生成文本用词精准但缺乏\"意外性\"\n- **突发性（Burstiness）过低**：句子长度和复杂度过于均匀\n- **词汇多样性不足**：同一含义反复使用相同表达\n- **结构高度规律**：段落长度、句式结构过于一致\n- **缺乏个人痕迹**：没有口误、修辞偏好、思维跳跃\n\n### 去 AI 化策略\n\n#### 增加人类写作特征\n- 段落长短错落：有的段 3 行，有的段 8 行\n- 句式多样：陈述句为主，穿插反问、设问、感叹\n- 适当使用非常规表达（但保持学术性）\n- 加入个人研究经历的真实描述\n- 引用具体数据、日期、地点等细节\n\n#### 增加学术深度\n- 对引用观点进行批判性分析（\"该研究虽然...但未考虑...\"）\n- 加入方法论的局限性讨论\n- 对比不同学者的观点并给出自己的判断\n- 使用领域专有术语和缩写（体现专业素养）\n- 引入具体案例佐证论点\n\n#### 文风自然化\n- 避免每段都以\"首先/其次/最后\"开头\n- 减少\"值得注意的是\"、\"不可忽视的是\"等 AI 套话\n- 不同章节使用不同的论述风格（叙述/论证/描述/说明）\n- 保持与自己之前作品一致的写作风格\n- 适当使用学术领域认可的口语化表达\n\n## 文献验证流程\n\n### 必须执行的验证步骤\n1. 在 Google Scholar / 知网 / Web of Science 中搜索文献标题\n2. 核对作者姓名（全名）、发表年份\n3. 核对期刊名称 / 出版社 / 会议名称\n4. 核对卷号、期号、页码（或 DOI）\n5. 确认该期刊/会议是正规学术出版物（非掠夺性期刊）\n\n### 引用质量要求\n- 优先引用高影响因子期刊和顶级会议论文\n- 近 5 年文献占比 ≥ 50%\n- 经典文献（>10 年）仅用于奠基性理论\n- 避免过度引用同一作者或同一课题组\n- 自引比例控制在 10% 以内",
|
||||
"enabled": false,
|
||||
"priority": 14,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.669Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.669Z",
|
||||
"tags": [
|
||||
"paper",
|
||||
"plagiarism",
|
||||
"deai",
|
||||
"academic"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "a7617186-a047-4a12-9b33-988ea85aa11c",
|
||||
"name": "Git 提交工作流",
|
||||
"category": "workflow",
|
||||
"content": "## 提交前检查\n\n1. **查看变更**\n - 运行 `git diff --staged` 审查即将提交的代码\n - 确认没有遗留 `console.log` / `debugger` / `TODO` 调试代码\n - 确认没有意外包含的文件（如 .env、node_modules）\n\n2. **代码质量**\n - 运行 `yarn lint` 检查代码风格\n - 运行 `yarn typecheck` 确认类型安全\n - 运行 `yarn format` 格式化代码\n\n3. **测试**\n - 运行相关单元测试确保通过\n - 手动验证变更功能正常\n\n## 提交信息规范\n\n```\n<type>(<scope>): <subject>\n```\n\n- **type**：`feat`（功能）/ `fix`（修复）/ `docs`（文档）/ `refactor`（重构）/ `chore`（杂务）/ `perf`（性能）/ `ci`（CI）\n- **scope**：可选，影响模块名\n- **subject**：中文简述，不超过 50 字\n- 示例：`feat(auth): 添加手机号验证码登录`\n\n## 提交原则\n\n- 每次提交只包含**一个逻辑变更**\n- 提交后代码必须能编译通过\n- 大功能拆分为多个小 commit，每个可独立理解\n- 不要把格式化和逻辑变更混在同一个 commit\n\n## 分支与 PR\n\n- 分支命名：`feature/xxx`、`fix/xxx`、`refactor/xxx`\n- PR 合并前必须通过 CI 检查和至少一人 Code Review\n- PR 描述填写：变更内容、测试方法、相关 Issue",
|
||||
"enabled": false,
|
||||
"priority": 15,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.669Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.669Z",
|
||||
"tags": [
|
||||
"git",
|
||||
"workflow",
|
||||
"commit"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "754638dc-ffc8-481a-b62d-28115f11f2f4",
|
||||
"name": "项目初始化工作流",
|
||||
"category": "workflow",
|
||||
"content": "## 1. 项目脚手架\n\n- 使用官方 CLI 创建项目（Vite / Create Next App / NestJS CLI 等）\n- 确认 Node.js 版本要求，添加 `.nvmrc` 或 `.node-version`\n- 选择包管理器并锁定（`.yarnrc.yml` 或 `packageManager` 字段）\n\n## 2. 目录结构\n\n```\nsrc/\n components/ # UI 组件\n composables/ # 可复用逻辑（Vue）/ hooks/（React）\n services/ # API 调用和业务服务\n stores/ # 状态管理\n types/ # TypeScript 类型定义\n utils/ # 工具函数\n assets/ # 静态资源\n```\n\n## 3. 代码质量工具\n\n- **ESLint**：代码检查（`@typescript-eslint`）\n- **Prettier**：代码格式化（`.prettierrc`）\n- **EditorConfig**：编辑器统一配置（`.editorconfig`）\n- **husky + lint-staged**：Git 钩子自动检查\n- **commitlint**：提交信息规范校验\n\n## 4. TypeScript 配置\n\n- 启用严格模式：`\"strict\": true`\n- 路径别名：`\"@/*\": [\"./src/*\"]`\n- 目标版本对齐运行环境\n\n## 5. 环境与安全\n\n- 创建 `.env.example` 模板（不含真实密钥）\n- `.gitignore` 排除：`.env`、`node_modules/`、`dist/`、IDE 文件\n- 敏感信息使用环境变量，不硬编码\n\n## 6. 文档\n\n- **README.md**：项目介绍、技术栈、启动步骤、部署说明\n- **CONTRIBUTING.md**：贡献指南（分支策略、提交规范）\n- **CHANGELOG.md**：版本变更记录\n\n## 7. CI/CD\n\n- 配置 GitHub Actions / GitLab CI 基础流水线\n- 流水线步骤：安装依赖 → lint → typecheck → test → build\n- 配置缓存（node_modules / yarn cache）加速构建",
|
||||
"enabled": false,
|
||||
"priority": 16,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.669Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.669Z",
|
||||
"tags": [
|
||||
"workflow",
|
||||
"init",
|
||||
"setup"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "1d0de531-cb4c-4b91-a776-823d6f8c040b",
|
||||
"name": "发布部署工作流",
|
||||
"category": "workflow",
|
||||
"content": "## 1. 发布准备\n\n- 从 `develop` 创建 `release/vX.Y.Z` 分支\n- 更新版本号（`package.json` / `pubspec.yaml` 等）\n- 运行完整测试套件确保通过：`yarn test`\n- 运行 lint 和类型检查：`yarn lint && yarn typecheck`\n- 确认无未提交的变更：`git status`\n\n## 2. 变更日志\n\n- 生成 CHANGELOG：`yarn changelog` 或手动整理\n- 分类变更：新功能 / Bug 修复 / 破坏性变更 / 性能优化\n- 提交 CHANGELOG 和版本号变更\n\n## 3. 构建与测试\n\n- 构建生产包：`yarn build`\n- 验证构建产物大小（对比上次发布，排查异常增长）\n- 在 staging 环境部署并验证核心功能\n- 回归测试：确认已知功能不受影响\n\n## 4. 发布\n\n- 合并 `release/vX.Y.Z` → `main`（merge commit）\n- 创建 Git Tag：`git tag -a vX.Y.Z -m \"Release vX.Y.Z\"`\n- 推送 Tag：`git push origin vX.Y.Z`\n- 合并 `release/vX.Y.Z` → `develop`（同步变更）\n- 删除 release 分支\n\n## 5. 部署生产\n\n- 部署到生产环境（CI/CD 自动触发或手动确认）\n- 健康检查：确认服务正常启动\n- 冒烟测试：验证核心 API 和页面可访问\n- 监控：观察错误率、响应时间、CPU/内存 5-10 分钟\n\n## 6. 收尾\n\n- 通知团队发布完成（Slack / 飞书 / 邮件）\n- 更新项目管理工具中的版本状态\n- 如有问题立即执行回滚：`git revert` 或重新部署上一版本\n- 在 GitHub / GitLab 创建 Release，附带 CHANGELOG",
|
||||
"enabled": false,
|
||||
"priority": 17,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.670Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.670Z",
|
||||
"tags": [
|
||||
"workflow",
|
||||
"deploy",
|
||||
"release"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "dfb96954-af72-4ab7-83db-ff410e4e2669",
|
||||
"name": "代码审查工作流",
|
||||
"category": "workflow",
|
||||
"content": "## 1. 准备阶段\n\n- 确认 PR 描述完整：变更内容、影响范围、测试方法、截图（UI 变更）\n- 关联 Issue / Jira 编号\n- 拉取分支到本地，确保能编译通过：`yarn && yarn build`\n- 了解变更背景和业务需求\n\n## 2. 结构审查\n\n- 检查文件组织是否合理，新文件放在正确的目录下\n- 是否有不属于本次变更的文件（格式化噪音、无关修改）\n- 新增依赖：是否必要？版本是否合适？是否有更轻量替代？\n- 新增依赖的 license 是否兼容项目\n\n## 3. 逻辑审查\n\n- 逐文件阅读变更，关注业务逻辑正确性\n- 检查边界条件：空值、空数组、超大数据、并发操作\n- 错误处理：异常是否捕获？错误信息是否有用？是否有空 catch？\n- 异步逻辑：是否有竞态条件？Promise 是否处理 rejection？\n- 数据流：状态变更是否一致？是否有内存泄漏？\n\n## 4. 质量审查\n\n- 命名规范：变量/函数/类是否语义清晰\n- 代码风格一致性：与项目现有代码保持统一\n- 重复代码：是否有可提取的公共逻辑\n- 函数长度 ≤ 50 行，嵌套 ≤ 3 层\n- 注释说明 why 而非 what，中文注释\n\n## 5. 安全审查\n\n- 用户输入是否在服务端校验\n- 敏感数据是否脱敏（日志、响应）\n- SQL 是否使用参数化查询\n- 文件操作是否防止路径遍历\n- 认证授权是否覆盖新增端点\n\n## 6. 测试审查\n\n- 关键逻辑是否有测试覆盖\n- 测试是否覆盖正常路径和异常路径\n- 测试是否独立，不依赖执行顺序\n\n## 7. 反馈\n\n- 问题分级：🔴 必须修复 / 🟡 建议改进 / 🟢 可选优化\n- 每条包含：位置 → 问题描述 → 修复建议（附代码示例）\n- 肯定好的代码：好的设计和实现也值得认可\n- 总结：必须修复 N 项 / 建议改进 N 项 / 可选 N 项",
|
||||
"enabled": false,
|
||||
"priority": 18,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.670Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.670Z",
|
||||
"tags": [
|
||||
"workflow",
|
||||
"review",
|
||||
"quality"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "1bbc90c6-2a48-4d7b-928e-4b815c5aaf2f",
|
||||
"name": "Bug 修复工作流",
|
||||
"category": "workflow",
|
||||
"content": "## 1. 问题确认\n\n- 阅读 Issue / Bug 报告，理解预期行为和实际行为\n- 确认复现步骤，自己手动复现一遍\n- 记录环境信息：OS、浏览器/Node 版本、相关配置\n- 确认影响范围：影响哪些用户？频率如何？是否阻塞？\n- 评估优先级：P0（立即修复）/ P1（当天）/ P2（本周）\n\n## 2. 问题定位\n\n- 阅读错误日志和堆栈信息，定位出错文件和行号\n- 使用断点调试（IDE debugger / `--inspect`）缩小范围\n- 使用二分法排查：注释代码 / `git bisect` 找到引入 commit\n- 区分**根本原因**和**表面症状**，修复根因\n- 检查最近的变更记录：`git log --oneline -20`\n\n## 3. 修复实施\n\n- 从 `develop` 创建 `fix/<问题描述>` 分支\n- **最小化修改**：只改必要的代码，不顺手重构\n- 优先修上游原因，避免下游打补丁\n- 添加防御性代码防止同类问题复发\n- 添加中文注释说明修复原因（why）\n\n## 4. 验证测试\n\n- 确认原始 Bug 已修复（按复现步骤验证）\n- 回归测试：确认修复没有引入新问题\n- 边界条件测试：空值、大数据、并发场景\n- 如可行，添加针对该 Bug 的回归测试用例\n\n## 5. 提交与发布\n\n- 提交信息：`fix(<scope>): 描述修复内容 (Closes #issue编号)`\n- 创建 PR，描述：问题原因 → 修复方案 → 验证方法\n- 请求 Code Review\n- 合并后验证线上环境\n\n## 6. 收尾\n\n- 更新 Issue 状态为已修复\n- 通知 Bug 报告者验证\n- 更新相关文档或注释\n- 如果是常见问题，补充到 FAQ 或排查指南",
|
||||
"enabled": false,
|
||||
"priority": 19,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.670Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.670Z",
|
||||
"tags": [
|
||||
"workflow",
|
||||
"bugfix",
|
||||
"debug"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "479f69dd-dadf-4f1e-8dc5-b9302dc02867",
|
||||
"name": "功能开发工作流",
|
||||
"category": "workflow",
|
||||
"content": "## 1. 需求理解\n\n- 阅读需求文档 / Issue，确认验收标准（AC）\n- 梳理技术方案，评估复杂度（S/M/L/XL）和影响范围\n- 与产品/设计/后端对齐理解，确认无歧义\n- 识别依赖：是否需要其他团队配合？是否有技术前置条件？\n- 确认 UI 设计稿 / 接口文档是否就绪\n\n## 2. 技术设计\n\n- 确定数据结构和接口定义（前后端类型契约）\n- 拆分子任务，估算工时，更新项目管理工具\n- 考虑兼容性（向后兼容）和扩展性\n- 数据库变更：编写 migration 脚本\n- 评估风险点，准备降级 / 回滚方案\n\n## 3. 开发实施\n\n- 从 `develop` 创建 `feature/<功能描述>` 分支\n- 小步提交，每个 commit 可独立编译运行\n- 关键逻辑添加中文注释（说明 why）\n- 添加必要的日志（关键操作、错误路径）\n- 遵循项目代码规范和架构约定\n- 前端：组件拆分 → 数据联调 → 样式完善\n- 后端：接口定义 → 业务逻辑 → 数据层 → 联调\n\n## 4. 自测验证\n\n- 覆盖正常流程和异常流程\n- 边界值测试：空值、超长输入、大数据量\n- 兼容性测试：不同浏览器 / 设备 / 分辨率\n- 权限测试：不同角色是否正确限制\n- 性能验证：大数据量下是否卡顿\n- UI 对照设计稿逐项检查\n\n## 5. 提交审查\n\n- 提交信息：`feat(<scope>): 功能描述`\n- 创建 PR，描述：功能说明 → 实现方案 → 测试方法 → 截图\n- 关联 Issue / Jira 编号\n- 请求 Code Review（至少一人）\n- 根据 Review 意见修改，re-request review\n\n## 6. 合并上线\n\n- Review 通过后 squash merge 到 `develop`\n- 清理 feature 分支\n- 在 develop 环境验证功能完整性\n- 更新 Issue 状态，通知产品验收",
|
||||
"enabled": false,
|
||||
"priority": 20,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.670Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.670Z",
|
||||
"tags": [
|
||||
"workflow",
|
||||
"feature",
|
||||
"development"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "24d38a3a-e3ef-4471-a0ac-4b871b564878",
|
||||
"name": "Vue 3 编码规范",
|
||||
"category": "rule",
|
||||
"content": "## 组件规范\n- 必须使用 Composition API + `<script setup>` 语法\n- 组件命名使用 PascalCase（如 `UserProfile.vue`）\n- 单文件组件顺序：`<script setup>` → `<template>` → `<style scoped>`\n- 单个组件文件不超过 200 行，超过则拆分子组件\n- 组件目录结构：`ComponentName/index.vue` + `ComponentName/types.ts`\n\n## Props 与事件\n- Props 必须使用 `defineProps<T>()` 定义 TypeScript 类型\n- 使用 `withDefaults()` 为 Props 设置默认值\n- 事件使用 `defineEmits<{ (e: 'update', value: string): void }>()` 定义\n- Props 命名使用 camelCase，模板中自动转为 kebab-case\n- 避免修改 Props，使用 `emit` 通知父组件变更\n\n## 响应式\n- 优先使用 `ref()` 而非 `reactive()`（避免解构丢失响应性）\n- `computed` 用于派生状态，不要在 `computed` 中产生副作用\n- `watch` 指定具体的响应式源，避免 `watch(() => state)` 监听整个对象\n- 使用 `watchEffect` 处理副作用自动追踪依赖\n- 大型列表使用 `shallowRef` 减少响应式开销\n\n## 模板规范\n- 模板中不要有复杂逻辑，抽取为 `computed` 或方法\n- 列表渲染必须提供唯一 `key`，禁止使用 index\n- 条件渲染优先 `v-if`，频繁切换使用 `v-show`\n- 事件处理器使用 `@click=\"handleClick\"`，不在模板中写逻辑\n\n## 可复用逻辑\n- 可复用逻辑抽取为 composables（`use*.ts`）\n- composable 返回值使用 `ref` 而非 `reactive`\n- composable 内部清理副作用使用 `onUnmounted`\n\n## 样式\n- 使用 `<style scoped>` 或 CSS Modules 避免样式污染\n- 优先使用 Tailwind CSS 原子类，减少自定义 CSS\n- 主题变量使用 CSS 自定义属性（`var(--color-primary)`）",
|
||||
"enabled": false,
|
||||
"priority": 21,
|
||||
"condition": {
|
||||
"filePattern": "**/*.vue"
|
||||
},
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.670Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.670Z",
|
||||
"tags": [
|
||||
"vue",
|
||||
"frontend"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "f12a764b-edbe-4779-9b65-39bf2a020efd",
|
||||
"name": "TypeScript 严格模式",
|
||||
"category": "rule",
|
||||
"content": "## 类型安全\n- 禁止使用 `any`，使用 `unknown` 替代不确定类型\n- 所有函数必须声明参数类型和返回类型\n- 使用 `interface` 定义对象结构，`type` 用于联合类型和工具类型\n- 泛型参数使用有意义的名称（如 `TData`、`TResponse`）\n- 使用 `as const` 断言确保字面量类型推断\n- 避免类型断言 `as`，优先使用类型守卫（type guard）\n\n## 语法规范\n- 使用可选链 `?.` 和空值合并 `??` 替代 `&&` 和 `||`\n- 优先使用 `const enum` 或字面量联合类型替代普通 enum\n- 使用 `readonly` 标记不应被修改的属性和数组\n- 解构赋值时添加默认值：`const { name = '默认' } = options`\n- 异步函数统一使用 `async/await`，禁止 `.then()` 链\n\n## 错误处理\n- 使用自定义错误类继承 `Error`，携带 `code` 字段\n- try/catch 中指定具体错误类型，禁止空 catch\n- Promise 必须处理 rejection（`.catch()` 或 try/catch）\n\n## 命名约定\n- 变量/函数：`camelCase`\n- 类/接口/类型：`PascalCase`\n- 常量：`UPPER_SNAKE_CASE`\n- 私有属性：前缀 `_`（如 `_internalState`）\n- 布尔变量：`is/has/should` 前缀（如 `isLoading`）",
|
||||
"enabled": false,
|
||||
"priority": 22,
|
||||
"condition": {
|
||||
"filePattern": "**/*.ts"
|
||||
},
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.670Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.670Z",
|
||||
"tags": [
|
||||
"typescript"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "7ee68c49-3946-4c25-ab55-6d3b67c00852",
|
||||
"name": "Flutter 开发规范",
|
||||
"category": "rule",
|
||||
"content": "## Widget 规范\n- 使用 StatelessWidget 优先，仅在需要内部可变状态时用 StatefulWidget\n- Widget 拆分遵循单一职责，避免超过 100 行的 `build` 方法\n- 使用 `const` 构造函数减少不必要的重建\n- Widget 命名使用 PascalCase，文件名使用 snake_case\n- 将大型 Widget 拆分为私有方法或独立 Widget 类\n\n## 状态管理\n- 优先级：Riverpod > BLoC > Provider > setState\n- 局部状态使用 `ValueNotifier` + `ValueListenableBuilder`\n- 全局/跨页面状态使用 Riverpod 的 `StateNotifierProvider`\n- 异步数据使用 `FutureProvider` / `StreamProvider`\n- 状态类使用 `freezed` 或 `equatable` 实现不可变和相等比较\n\n## 主题与资源\n- 颜色、字体、间距统一在 `ThemeData` 中定义\n- 使用 `Theme.of(context)` 获取主题值，不硬编码颜色\n- 支持亮色/暗色模式切换\n- 文字使用 `TextTheme` 样式，不直接设置 fontSize\n- 间距使用统一常量（如 `Spacing.sm = 8.0`）\n\n## 异步与网络\n- 异步操作使用 `async/await`，避免嵌套 `.then()`\n- 网络请求使用 Dio + 拦截器（日志、认证、错误处理）\n- 图片使用 `cached_network_image`，配置占位图和错误图\n- 接口返回统一解析为 `Result<T>` 类型（Success / Failure）\n\n## 路由与导航\n- 路由统一使用 GoRouter 或 auto_route 管理\n- 路由参数使用强类型，避免字符串传参\n- 深层链接（Deep Link）支持\n\n## 性能优化\n- 禁止在 `build` 方法内做耗时运算或 I/O\n- 长列表使用 `ListView.builder` / `SliverList`，避免一次性构建\n- 使用 `RepaintBoundary` 隔离频繁重绘的区域\n- 动画使用 `AnimatedWidget` / `AnimatedBuilder`，避免全局重建",
|
||||
"enabled": false,
|
||||
"priority": 23,
|
||||
"condition": {
|
||||
"filePattern": "**/*.dart"
|
||||
},
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.670Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.670Z",
|
||||
"tags": [
|
||||
"flutter",
|
||||
"dart",
|
||||
"mobile"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "1e7fcdc1-479c-4308-b9ee-87892620049f",
|
||||
"name": "C# 编码规范",
|
||||
"category": "rule",
|
||||
"content": "## 命名规范\n- 类/接口/方法/属性：PascalCase\n- 局部变量/参数：camelCase\n- 常量/静态只读：UPPER_SNAKE_CASE 或 PascalCase\n- 接口前缀 `I`（如 `IUserService`）\n- 异步方法后缀 `Async`（如 `GetUserAsync`）\n- 布尔属性/变量：`Is/Has/Can` 前缀\n\n## 类型与数据\n- 优先使用 `record` 定义不可变数据对象（DTO / Value Object）\n- 使用 nullable 引用类型（`#nullable enable`），公共 API 参数需 null 检查\n- 值类型使用 `struct`，引用类型使用 `class`\n- 集合返回 `IReadOnlyList<T>` / `IReadOnlyCollection<T>`，避免暴露可变集合\n- 使用 `required` 关键字标记必填属性（C# 11+）\n\n## 异步与资源\n- 异步方法返回 `Task` / `Task<T>` / `ValueTask<T>`\n- 使用 `using` 声明（非语句块）管理资源\n- 传递 `CancellationToken` 到所有异步链路\n- 避免 `async void`，仅用于事件处理器\n- I/O 密集操作使用 `ConfigureAwait(false)`（类库中）\n\n## 依赖注入\n- 优先构造函数注入，避免服务定位器模式\n- 注册生命周期：Transient（无状态）/ Scoped（请求级）/ Singleton（全局）\n- 使用 `IOptions<T>` 注入配置对象\n\n## LINQ 与集合\n- LINQ 查询优先方法链形式，避免嵌套查询表达式\n- 大数据集使用 `AsNoTracking()` 提升 EF Core 查询性能\n- 使用 `Any()` 替代 `Count() > 0` 判断非空\n\n## 异常处理\n- 只 catch 能处理的异常，记录日志后重新抛出（`throw;` 保留堆栈）\n- 使用 `ExceptionFilter` / 中间件统一处理 API 异常\n- 自定义异常继承 `Exception`，携带错误码\n\n## 测试\n- 单元测试使用 xUnit + Moq / NSubstitute\n- 集成测试使用 `WebApplicationFactory<T>`\n- 遵循 Arrange-Act-Assert 模式",
|
||||
"enabled": false,
|
||||
"priority": 24,
|
||||
"condition": {
|
||||
"filePattern": "**/*.cs"
|
||||
},
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.670Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.670Z",
|
||||
"tags": [
|
||||
"csharp",
|
||||
"dotnet",
|
||||
"backend"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "0af0f61c-ecad-46eb-9685-3dba1f7a9b7a",
|
||||
"name": "Java 编码规范",
|
||||
"category": "rule",
|
||||
"content": "## 命名规范\n- 类/接口：PascalCase（如 `UserService`）\n- 方法/变量：camelCase（如 `getUserById`）\n- 常量：UPPER_SNAKE_CASE（如 `MAX_RETRY_COUNT`）\n- 包名：全小写，反向域名（如 `com.example.user`）\n- 布尔方法：`is/has/can` 前缀（如 `isValid()`）\n\n## 现代 Java 特性（17+）\n- 使用 `record` 定义不可变数据对象（DTO）\n- 使用 `sealed class` 限制继承层级\n- 使用 `pattern matching`（`instanceof` + 类型绑定）\n- 使用 `text blocks`（三引号）书写多行字符串\n- Switch 表达式使用箭头语法 + yield\n\n## 集合与 Stream\n- Stream API 用于集合操作，避免传统 for 循环处理集合\n- 使用 `Optional<T>` 替代 null 返回值，禁止 `Optional` 作为方法参数\n- 不可变集合：`List.of()` / `Map.of()` / `Set.of()`\n- 避免在 Stream 中产生副作用（如修改外部变量）\n\n## Spring Boot 架构\n- Controller 只处理 HTTP 映射和参数校验（`@Valid`）\n- 业务逻辑下沉到 Service 层\n- 数据访问使用 JPA Repository 或 MyBatis Mapper，禁止 SQL 拼接\n- 使用 `@Transactional` 管理事务，注意传播行为和回滚规则\n- 配置使用 `@ConfigurationProperties` 绑定，不硬编码\n\n## 异常与日志\n- 异常统一使用 `@ControllerAdvice` + `@ExceptionHandler` 处理\n- 返回标准 `ApiResponse<T>` 格式（code + message + data）\n- 日志使用 SLF4J + Logback，禁止 `System.out.println`\n- 日志级别：ERROR（系统错误）/ WARN（业务异常）/ INFO（关键操作）/ DEBUG（调试）\n- 日志包含上下文信息：用户 ID、请求 ID、耗时\n\n## 测试\n- 单元测试：JUnit 5 + Mockito，覆盖率 > 80%\n- 集成测试：`@SpringBootTest` + `@TestContainers`\n- API 测试：`MockMvc` 或 RestAssured",
|
||||
"enabled": false,
|
||||
"priority": 25,
|
||||
"condition": {
|
||||
"filePattern": "**/*.java"
|
||||
},
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.671Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.671Z",
|
||||
"tags": [
|
||||
"java",
|
||||
"backend",
|
||||
"spring"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "c68e1d4c-520e-4df0-b382-cb7aede9be14",
|
||||
"name": "React 编码规范",
|
||||
"category": "rule",
|
||||
"content": "## 组件规范\n- 函数组件 + Hooks，禁止使用 Class 组件\n- 组件命名 PascalCase，文件名与组件名一致（如 `UserCard.tsx`）\n- Props 使用 TypeScript `interface` 定义，必须标注类型\n- 使用 `React.FC<Props>` 或直接函数签名声明组件\n- 单个组件文件不超过 200 行，超过则拆分\n\n## 状态管理\n- 局部状态：`useState`\n- 计算状态：`useMemo`\n- 跨组件共享：Context + `useContext` 或 Zustand / Jotai\n- 服务端数据：TanStack Query（React Query）管理请求缓存\n- 避免 prop drilling 超过 3 层，使用 Context 或状态库\n\n## Hooks 规范\n- 自定义 Hook 以 `use` 开头，封装可复用逻辑\n- `useEffect` 依赖数组必须完整，配合 ESLint exhaustive-deps 规则\n- `useCallback` 包裹传给子组件的回调函数\n- `useMemo` 缓存昂贵计算，但不要滥用（简单计算无需缓存）\n- cleanup 函数处理订阅、定时器、AbortController\n\n## 渲染优化\n- 使用 `React.memo()` 避免不必要的子组件重渲染\n- 列表渲染必须提供稳定的 key（业务 ID），禁止使用 index\n- 条件渲染优先使用 `&&` 或三元表达式，避免嵌套 if\n- 大列表使用虚拟滚动（`@tanstack/react-virtual`）\n- 代码分割：`React.lazy()` + `Suspense` 懒加载路由和大组件\n\n## 样式\n- 样式方案：Tailwind CSS 或 CSS Modules，避免内联样式\n- 使用 `clsx` / `cn()` 工具合并条件类名\n- 响应式设计使用 Tailwind 断点前缀（`md:`、`lg:`）\n\n## 错误处理\n- 使用 `ErrorBoundary` 捕获渲染错误，提供 fallback UI\n- 异步操作统一 try/catch，用户友好的错误提示",
|
||||
"enabled": false,
|
||||
"priority": 26,
|
||||
"condition": {
|
||||
"filePattern": "**/*.tsx"
|
||||
},
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.671Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.671Z",
|
||||
"tags": [
|
||||
"react",
|
||||
"frontend"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "830fbcb0-a4f6-4dea-877a-13a5ff00b78d",
|
||||
"name": "Python 编码规范",
|
||||
"category": "rule",
|
||||
"content": "## 代码风格\n- 遵循 PEP 8 风格指南，使用 `black` + `isort` 格式化\n- 类名 PascalCase，函数/变量 snake_case，常量 UPPER_SNAKE_CASE\n- 模块级常量定义在文件顶部（导入之后）\n- 单行不超过 88 字符（black 默认）\n- 使用 `ruff` 作为 linter（替代 flake8 + pylint）\n\n## 类型标注\n- 使用 Type Hints 标注所有函数参数和返回值\n- 复杂类型使用 `typing` 模块（`Optional`、`Union`、`TypeAlias`）\n- Python 3.10+ 使用 `X | Y` 语法替代 `Union[X, Y]`\n- 使用 `mypy --strict` 进行静态类型检查\n- 泛型类使用 `TypeVar` 或 `Generic[T]`\n\n## 数据模型\n- 使用 `dataclass`（内部数据）或 `Pydantic BaseModel`（API 数据校验）\n- Pydantic 模型使用 `Field()` 添加校验规则和描述\n- 不可变数据使用 `frozen=True` 的 dataclass\n\n## 异步与并发\n- I/O 密集操作使用 `asyncio` + `async/await`\n- CPU 密集操作使用 `concurrent.futures.ProcessPoolExecutor`\n- 异步 HTTP 使用 `httpx` / `aiohttp`\n- 异步数据库使用 `SQLAlchemy 2.0` async 模式\n\n## 错误处理与资源\n- 使用 `with` 语句管理文件、连接等资源\n- 异常处理指定具体异常类型，禁止 bare `except:`\n- 自定义异常继承 `Exception`，携带错误码\n- 使用 `logging` 模块记录日志，禁止 `print()` 调试\n\n## 项目管理\n- 使用 `pyproject.toml` 管理项目配置和依赖\n- 虚拟环境：`venv` / `poetry` / `uv`\n- 依赖锁定：`poetry.lock` / `requirements.txt` 固定版本\n- 使用 `pytest` 编写测试，`pytest-cov` 检查覆盖率 > 80%\n- 使用 `pre-commit` 钩子自动检查代码质量",
|
||||
"enabled": false,
|
||||
"priority": 27,
|
||||
"condition": {
|
||||
"filePattern": "**/*.py"
|
||||
},
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.671Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.671Z",
|
||||
"tags": [
|
||||
"python",
|
||||
"backend"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "65a9c5b6-98ac-4ee0-a7f6-305719122f09",
|
||||
"name": "Go 编码规范",
|
||||
"category": "rule",
|
||||
"content": "## 命名规范\n- 包名小写单词，不使用下划线或混合大小写\n- 导出标识符 PascalCase，内部标识符 camelCase\n- 接口命名：单方法接口用 `-er` 后缀（如 `Reader`、`Writer`）\n- 文件名 snake_case（如 `user_service.go`）\n- 测试文件 `*_test.go`，与被测文件同目录\n\n## 错误处理\n- 每个 `error` 必须检查，禁止 `_ = err` 忽略\n- 使用 `errors.Is()` / `errors.As()` 替代 `==` 比较错误\n- 使用 `fmt.Errorf(\"描述: %w\", err)` 包装错误（保留链路）\n- 自定义错误类型实现 `Error()` 接口\n- 在函数签名中，error 永远是最后一个返回值\n- 使用 sentinel error（包级变量）定义可预期的错误\n\n## 并发与 goroutine\n- goroutine 必须有退出机制，使用 `context.Context` 控制生命周期\n- channel 使用完毕必须 `close`，避免 goroutine 泄漏\n- 使用 `sync.WaitGroup` 等待一组 goroutine 完成\n- 使用 `sync.Mutex` / `sync.RWMutex` 保护共享数据\n- 优先使用 channel 通信，而非共享内存\n- 使用 `errgroup.Group` 管理一组可能出错的 goroutine\n\n## 接口设计\n- 接口小而精：通常 1-3 个方法，由使用方定义\n- 接受接口，返回结构体（依赖倒置）\n- 使用组合（embedding）而非继承\n\n## 资源管理\n- 使用 `defer` 确保资源释放（文件、锁、连接）\n- `defer` 按 LIFO 顺序执行，注意多个 defer 的顺序\n- HTTP Response Body 必须 `defer resp.Body.Close()`\n\n## 项目结构\n- 遵循 Standard Go Project Layout\n- `cmd/`（入口）、`internal/`（私有）、`pkg/`（公共库）\n- 结构体字段使用 `json` tag 标注序列化名称\n- 配置使用 `viper` 或环境变量，不硬编码\n\n## 工具链\n- 使用 `go vet` + `golangci-lint` 进行静态分析\n- 使用 `go test -race` 检测数据竞争\n- 使用 `pprof` 进行性能分析\n- 使用 `go mod tidy` 清理无用依赖",
|
||||
"enabled": false,
|
||||
"priority": 28,
|
||||
"condition": {
|
||||
"filePattern": "**/*.go"
|
||||
},
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.671Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.671Z",
|
||||
"tags": [
|
||||
"golang",
|
||||
"backend"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "5e3f4fc5-4fd5-48dc-a838-9a5ae11795a0",
|
||||
"name": "输出语言为中文",
|
||||
"category": "rule",
|
||||
"content": "## 语言要求\n\n<language_rules>\n- **全程使用中文**回答所有问题，包括思考过程、解释说明、代码注释\n- 变量名、函数名、类名等**标识符保持英文**（遵循编程命名规范）\n- 代码注释必须使用中文书写\n- Git 提交信息使用中文描述\n- 文档和 README 使用中文编写\n- 错误提示和用户提示信息使用中文\n</language_rules>\n\n## 格式规范\n\n<format_rules>\n- 中英文之间添加空格（如：使用 Vue 3 框架）\n- 数字与中文之间添加空格（如：共 3 个文件）\n- 专业术语首次出现时标注英文原文（如：组合式 API (Composition API)）\n- 代码块中的输出示例使用中文\n- 表格、列表等结构化内容使用中文标题\n</format_rules>\n\n## 禁止行为\n\n- ❌ 禁止使用英文回答问题\n- ❌ 禁止在注释中混用英文（专业术语除外）\n- ❌ 禁止在解释说明中突然切换为英文",
|
||||
"enabled": false,
|
||||
"priority": 29,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.671Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.671Z",
|
||||
"tags": [
|
||||
"language",
|
||||
"chinese",
|
||||
"i18n"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "fb4b62f4-1cbb-413b-8e71-4bffa78b0922",
|
||||
"name": "学术论文写作规范",
|
||||
"category": "rule",
|
||||
"content": "## 格式要求\n\n### 论文结构\n- 标题 → 摘要 → 关键词 → 引言 → 文献综述 → 研究方法 → 结果分析 → 讨论 → 结论 → 参考文献 → 附录\n- 每个章节之间逻辑衔接自然，使用过渡句连接上下文\n- 摘要 300-500 字，包含研究目的、方法、主要发现和结论\n- 关键词 3-5 个，涵盖研究核心概念\n\n### 排版规范\n- 正文：宋体/Times New Roman，小四号（12pt），1.5 倍行距\n- 标题层级：一级标题黑体三号 → 二级标题黑体四号 → 三级标题黑体小四号\n- 段落首行缩进 2 字符，段前段后 0.5 行\n- 页边距：上 2.54cm / 下 2.54cm / 左 3.17cm / 右 3.17cm\n- 页码从正文开始，居中显示\n- 图表统一编号（如图 1、表 2），标题居中，图标题在下、表标题在上\n- 公式居中，编号右对齐\n\n## 查重规范\n\n### 重复率要求\n- 本科毕业论文：总重复率 ≤ 30%（部分院校要求 ≤ 20%）\n- 硕士学位论文：总重复率 ≤ 15%\n- 博士学位论文：总重复率 ≤ 10%\n- 期刊投稿：总重复率 ≤ 15%（核心期刊 ≤ 10%）\n\n### 降重技巧\n- **语序调整**：主动句与被动句互换，调整句子成分顺序\n- **同义替换**：使用同义词、近义词替换，但不改变原意\n- **概括改写**：将具体描述概括为抽象表述，用自己的话重新组织\n- **拆分合并**：长句拆为短句，或将短句合并为复合句\n- **增加论述**：在引用观点后加入自己的分析、评价和延伸\n- ❌ 禁止简单替换个别字词（如\"因此\"→\"所以\"），查重系统能识别\n- ❌ 禁止使用翻译法（中→英→中），表述生硬且可能曲解原意\n\n## 去 AI 化规范\n\n### 必须遵守\n- ❌ 禁止出现典型 AI 生成痕迹：\n - \"首先...其次...最后...\"的机械排列\n - \"值得注意的是\"、\"需要指出的是\"等套话高频出现\n - \"综上所述\"在非结论部分反复使用\n - 每段开头都用\"在...方面\"、\"从...角度\"的模板句式\n - 过度使用\"本文\"、\"本研究\"作为主语\n- ✅ 使用自然、多样的表达方式：\n - 变换句式结构：陈述句、反问句、设问句交替使用\n - 融入个人研究视角和独立思考\n - 使用领域专业术语，体现学科素养\n - 段落长短错落有致，避免每段字数雷同\n - 适当使用口语化学术表达（如\"不难发现\"、\"换言之\"）\n\n### AI 检测规避\n- 保持个人写作风格一致性（用词习惯、句式偏好）\n- 加入具体案例、数据、图表等实证内容（AI 难以伪造）\n- 融入对研究过程的真实描述（实验细节、调研经历）\n- 对他人观点进行批判性分析，而非简单罗列\n- 论文不同部分的文风应与内容匹配（引言偏叙述、方法偏客观、讨论偏思辨）\n\n## 文献引用规范\n\n### 文献真实性（最高优先级）\n- ⚠️ **所有引用的文献必须真实存在，可通过学术数据库检索到**\n- 引用前必须验证：作者、标题、期刊/出版社、年份、卷期页码均准确\n- 推荐验证渠道：Google Scholar、知网（CNKI）、万方、Web of Science、Scopus\n- ❌ 严禁编造虚假文献（捏造作者、杜撰期刊、伪造年份）\n- ❌ 严禁引用未读过的文献（二手引用需标注\"转引自\"）\n- 如无法找到原始文献，宁可删除引用也不要凭记忆补全信息\n\n### 引用格式\n- 中文论文：GB/T 7714 格式（如：[1] 张三. 标题[J]. 期刊名, 2024, 1(2): 10-20.）\n- 英文论文：APA 7th / IEEE / MLA 格式（根据目标期刊要求选择）\n- 正文引用与参考文献列表一一对应，不多不少\n- 引用数量建议：本科 15-30 篇，硕士 40-80 篇，博士 80-150 篇\n- 近 5 年文献占比 ≥ 50%，体现研究前沿性\n- 中英文文献比例合理（理工科英文 ≥ 60%）\n\n## 上下文连贯性\n\n### 全文一致性\n- 研究问题、方法、结果、结论之间逻辑链条完整\n- 摘要中的结论必须与正文结论一致\n- 引言提出的问题必须在结论中回应\n- 文献综述的内容必须与研究方法选择相关\n- 术语全文统一：同一概念不要交替使用不同名称\n\n### 段落衔接\n- 每段有明确的主题句（通常在段首）\n- 段与段之间使用过渡句或过渡词连接\n- 常用过渡逻辑：因果（因此）、转折（然而）、递进（此外）、对比（相比之下）\n- 避免突然跳转话题，新观点需有铺垫\n- 每章末尾可加小结，呼应章首并过渡到下一章\n\n### 语言风格一致\n- 全文保持同一人称视角（推荐第三人称或\"本文\"）\n- 时态一致：文献综述用过去时，研究方法用过去时，结论用现在时\n- 学术语体一致：不在严谨论述中突然出现口语化表达\n- 专业术语首次出现时给出定义或英文原文",
|
||||
"enabled": false,
|
||||
"priority": 30,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.671Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.671Z",
|
||||
"tags": [
|
||||
"paper",
|
||||
"academic",
|
||||
"writing"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "ba7f7fa7-b66c-4b1b-9437-c24e176dc04f",
|
||||
"name": "代码审查规范",
|
||||
"category": "context",
|
||||
"content": "## 代码结构\n- 函数长度不超过 50 行，文件不超过 300 行\n- 嵌套不超过 3 层，使用早返回（guard clause）减少嵌套\n- 单一职责：每个函数/类只做一件事\n- 避免上帝类（God Class）和上帝函数\n\n## 命名规范\n- 变量/函数：camelCase（如 `getUserById`）\n- 类/接口/类型：PascalCase（如 `UserService`）\n- 常量：UPPER_SNAKE_CASE（如 `MAX_RETRY_COUNT`）\n- 布尔变量：`is/has/should/can` 前缀\n- 命名必须语义清晰，禁止单字母变量（循环计数器除外）\n\n## 代码质量\n- 避免魔法数字，使用命名常量\n- 不要吞掉异常（空 catch），至少记录日志\n- 不要注释掉代码，直接删除（Git 有历史记录）\n- 注释说明 why 而非 what，使用中文注释\n- 删除未使用的导入、变量和代码（dead code）\n\n## 错误处理\n- 异常必须处理：捕获后记录日志或向上抛出\n- 使用自定义错误类型，携带错误码\n- 异步操作必须有超时和错误处理\n- 用户可见的错误信息使用中文，友好且有指导性\n\n## 安全检查\n- 用户输入必须校验（类型、长度、范围、格式）\n- SQL 使用参数化查询，禁止拼接\n- 敏感数据不在日志中输出",
|
||||
"enabled": false,
|
||||
"priority": 31,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.672Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.672Z",
|
||||
"tags": [
|
||||
"review",
|
||||
"quality"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "1db8f176-ad02-4255-bedc-039fbd5cd08d",
|
||||
"name": "项目概述上下文",
|
||||
"category": "context",
|
||||
"content": "## 项目信息\n- **项目名称**：[填写项目名称]\n- **项目类型**：[Web 应用 / 桌面应用 / 移动应用 / 后端服务 / CLI 工具 / 浏览器扩展]\n- **主要语言**：[TypeScript / Python / Java / Go / C# / Dart / Rust]\n- **框架**：[Vue 3 / React / NestJS / Spring Boot / Flutter / Electron]\n- **包管理器**：[yarn / pnpm / npm / pip / gradle / cargo]\n- **Node.js 版本**：[18 LTS / 20 LTS / 22]\n\n## 目录结构\n```\nsrc/\n components/ # UI 组件\n composables/ # 可复用逻辑（Vue）/ hooks/（React）\n services/ # API 调用和业务服务\n stores/ # 状态管理（Pinia / Zustand）\n types/ # TypeScript 类型定义\n utils/ # 工具函数\n assets/ # 静态资源（图片、字体、样式）\n router/ # 路由配置\n i18n/ # 国际化文件\npublic/ # 公共静态文件\n```\n\n## 开发约定\n- **代码风格**：ESLint + Prettier，提交前自动格式化\n- **分支策略**：Git Flow（main / develop / feature / fix / release）\n- **提交规范**：Conventional Commits（feat / fix / docs / refactor）\n- **部署方式**：[Docker / Vercel / Nginx / PM2]\n- **CI/CD**：[GitHub Actions / GitLab CI / Jenkins]\n\n## 关键依赖\n| 依赖 | 版本 | 用途 |\n|------|------|------|\n| [框架名] | ^x.y.z | [用途] |\n| [UI 库] | ^x.y.z | [用途] |\n| [状态管理] | ^x.y.z | [用途] |\n\n## 环境变量\n| 变量名 | 说明 | 示例 |\n|--------|------|------|\n| `VITE_API_URL` | API 地址 | `http://localhost:3000` |\n| `DATABASE_URL` | 数据库连接 | `postgresql://...` |\n\n## 注意事项\n- [填写项目特殊约定、已知限制、技术债务等]",
|
||||
"enabled": false,
|
||||
"priority": 32,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.672Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.672Z",
|
||||
"tags": [
|
||||
"context",
|
||||
"project",
|
||||
"overview"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "4512ac51-2c99-4ed1-9e41-d9f41c36435c",
|
||||
"name": "调试排错上下文",
|
||||
"category": "context",
|
||||
"content": "## 调试原则\n- 先复现问题，记录复现步骤和环境信息\n- 从错误日志和堆栈信息入手，定位出错位置\n- 使用二分法缩小问题范围（注释代码 / `git bisect`）\n- 区分根本原因和表面症状，修复根因\n- 一次只改一个变量，验证后再改下一个\n- 不要猜测，用数据和日志证明假设\n\n## 常见问题排查清单\n\n### 编译 / 构建错误\n- 类型定义缺失或不匹配\n- 导入路径错误（相对路径 / 别名配置）\n- 依赖版本冲突（`yarn why <package>`）\n- tsconfig 配置问题（`moduleResolution`、`paths`）\n\n### 运行时错误\n- 空值访问：`TypeError: Cannot read property of undefined`\n- 异步时序：Promise 未 await、竞态条件\n- 数组越界 / 对象属性不存在\n- 循环引用导致栈溢出\n- 类型不匹配：字符串 vs 数字、JSON 解析失败\n\n### 样式问题\n- 选择器优先级：Specificity 计算、`!important` 覆盖\n- z-index 层级混乱：建立统一的 z-index 层级体系\n- Flex / Grid 布局：`flex-shrink`、`overflow`、`min-width: 0`\n- 响应式断点：移动端 viewport、媒体查询顺序\n\n### 性能问题\n- 前端：N 次不必要的重渲染（React DevTools Profiler）\n- 后端：N+1 查询（ORM 日志）、慢查询（`EXPLAIN ANALYZE`）\n- 内存泄漏：事件监听未清理、闭包引用大对象\n- 网络：请求瀑布流、缺少缓存策略\n\n### 网络问题\n- CORS：`Access-Control-Allow-Origin` 配置\n- 请求格式：`Content-Type` 不匹配\n- 认证：Token 过期 / 缺失、Cookie SameSite 策略\n- 超时：设置合理的 timeout 值、重试机制\n\n## 调试工具\n\n| 场景 | 工具 | 用途 |\n|------|------|------|\n| 前端 | Chrome DevTools | Network / Console / Performance / Memory |\n| 前端 | React / Vue DevTools | 组件树、状态、渲染次数 |\n| Node.js | `--inspect` | 断点调试（配合 Chrome DevTools） |\n| Node.js | `clinic.js` | 性能分析（CPU / 内存 / 事件循环） |\n| 数据库 | `EXPLAIN ANALYZE` | 查询执行计划分析 |\n| 网络 | Postman / cURL | API 请求调试 |\n| 日志 | `console.time()` | 简单计时 |\n\n## 日志调试技巧\n- 使用结构化日志：`console.log({ userId, action, result })`\n- 在关键分支添加标记日志：`[DEBUG] 进入分支 A`\n- 调试完毕后清理所有调试日志（或使用 DEBUG 环境变量控制）",
|
||||
"enabled": false,
|
||||
"priority": 33,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.672Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.672Z",
|
||||
"tags": [
|
||||
"context",
|
||||
"debug",
|
||||
"troubleshoot"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "6d1762ba-ee4f-47b3-987c-a6d462c581b3",
|
||||
"name": "架构设计上下文",
|
||||
"category": "context",
|
||||
"content": "## SOLID 原则\n- **单一职责（SRP）**：每个模块/类只负责一件事\n- **开闭原则（OCP）**：对扩展开放，对修改关闭（策略模式、插件机制）\n- **里氏替换（LSP）**：子类可以替换父类而不破坏行为\n- **接口隔离（ISP）**：客户端不应被迫依赖不使用的接口\n- **依赖倒置（DIP）**：高层模块依赖抽象，不依赖具体实现\n\n## 分层架构\n\n```\n┌──────────────────┐\n│ 表现层 │ ← UI 组件、页面路由、用户交互\n│ (Presentation) │ Vue/React 组件、模板、样式\n├──────────────────┤\n│ 业务逻辑层 │ ← Service、Store、Composable/Hook\n│ (Business) │ 业务规则、数据转换、状态管理\n├──────────────────┤\n│ 数据访问层 │ ← Repository、API Client、ORM\n│ (Data Access) │ 接口调用、数据库操作、缓存\n├──────────────────┤\n│ 基础设施层 │ ← 数据库、缓存、消息队列、文件存储\n│ (Infrastructure)│ 第三方服务、系统配置\n└──────────────────┘\n```\n\n- 上层只依赖下层，禁止跨层调用和反向依赖\n- 每层通过接口（Interface）暴露能力，隐藏实现细节\n\n## 常用设计模式\n- **策略模式**：多种算法/行为可切换（如支付方式、认证方式）\n- **观察者模式**：事件驱动解耦（EventEmitter、Vue 的 watch）\n- **工厂模式**：根据条件创建不同实例\n- **适配器模式**：统一不同第三方服务的接口\n- **装饰器模式**：横切关注点（日志、缓存、权限检查）\n- **仓储模式**：抽象数据访问，隔离业务逻辑和存储细节\n\n## 设计决策记录（ADR）\n\n```markdown\n### ADR-001: [决策标题]\n- **状态**：已采纳 / 待评审 / 已废弃\n- **背景**：为什么需要这个决策\n- **决策**：选择了什么方案\n- **替代方案**：考虑过哪些其他方案\n- **后果**：这个决策带来的正面和负面影响\n```\n\n## 扩展性考量\n- 模块化：功能按领域拆分为独立模块\n- 插件化：核心功能之外的能力通过插件扩展\n- 配置驱动：行为差异通过配置而非代码分支控制\n- 向后兼容：API 变更使用版本化，数据迁移支持回滚",
|
||||
"enabled": false,
|
||||
"priority": 34,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.673Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.673Z",
|
||||
"tags": [
|
||||
"context",
|
||||
"architecture",
|
||||
"design"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "a2139591-3b5a-49d9-90f7-a5b270667cbf",
|
||||
"name": "技术栈上下文",
|
||||
"category": "context",
|
||||
"content": "## 前端技术栈\n\n| 分类 | 技术 | 版本 | 说明 |\n|------|------|------|------|\n| 框架 | Vue 3 / React 19 | latest | Composition API / Hooks |\n| 语言 | TypeScript | ^5.x | 严格模式 |\n| 构建 | Vite | ^5.x / ^6.x | 开发服务器 + 生产构建 |\n| UI 库 | Ant Design Vue / shadcn/ui | latest | 主要组件库 |\n| 样式 | Tailwind CSS | ^3.x / ^4.x | 原子化 CSS |\n| 状态 | Pinia / Zustand | latest | 全局状态管理 |\n| 路由 | Vue Router / React Router | latest | SPA 路由 |\n| HTTP | Axios / ky / fetch | latest | API 请求 |\n| 图标 | Lucide Icons | latest | SVG 图标库 |\n| 表格 | VXE-Table / TanStack Table | latest | 高性能表格 |\n| 表单 | VeeValidate / React Hook Form | latest | 表单校验 |\n| 国际化 | vue-i18n / react-intl | latest | 多语言 |\n| 图表 | ECharts / D3.js | latest | 数据可视化 |\n\n## 后端技术栈\n\n| 分类 | 技术 | 版本 | 说明 |\n|------|------|------|------|\n| 运行时 | Node.js | 20 LTS / 22 | 服务端 JavaScript |\n| 框架 | Express / NestJS / Fastify | latest | Web 框架 |\n| 数据库 | PostgreSQL | 16 | 主数据库 |\n| 缓存 | Redis | 7 | 缓存 + 会话 + 消息队列 |\n| ORM | Prisma / TypeORM / Drizzle | latest | 数据库操作 |\n| 认证 | JWT + bcrypt / Passport | latest | 认证授权 |\n| 校验 | zod / class-validator | latest | 入参校验 |\n| 日志 | Winston / Pino | latest | 结构化日志 |\n| 队列 | BullMQ / RabbitMQ | latest | 异步任务 |\n\n## 工具链\n\n| 分类 | 技术 | 说明 |\n|------|------|------|\n| 包管理 | Yarn / pnpm | 依赖管理 |\n| 代码风格 | ESLint + Prettier | 检查 + 格式化 |\n| Git 钩子 | husky + lint-staged | 提交前检查 |\n| 提交规范 | commitlint | Conventional Commits |\n| 版本控制 | Git | 源码管理 |\n| CI/CD | GitHub Actions / GitLab CI | 自动化流水线 |\n| 容器化 | Docker + docker-compose | 开发 + 部署 |\n| 部署 | Nginx / Caddy | 反向代理 + 静态托管 |\n| 监控 | Prometheus + Grafana | 性能监控 |\n| E2E 测试 | Playwright | 端到端自动化测试 |",
|
||||
"enabled": false,
|
||||
"priority": 35,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.673Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.673Z",
|
||||
"tags": [
|
||||
"context",
|
||||
"tech-stack",
|
||||
"environment"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "fd6a4651-3837-4308-9e04-5bf957fe0512",
|
||||
"name": "论文写作上下文",
|
||||
"category": "context",
|
||||
"content": "## 当前论文信息\n\n- **论文题目**：[填写题目]\n- **论文类型**：[本科毕业论文 / 硕士学位论文 / 博士学位论文 / 期刊论文 / 会议论文]\n- **所属学科**：[填写学科方向]\n- **目标期刊/学校**：[填写期刊名称或学校名称]\n- **字数要求**：[填写字数]\n- **查重要求**：[填写重复率上限，如 ≤ 20%]\n- **引用格式**：[GB/T 7714 / APA / IEEE / MLA]\n- **截止日期**：[填写日期]\n\n## 研究核心\n\n- **研究问题**：[核心研究问题是什么]\n- **研究假设**：[填写研究假设]\n- **研究方法**：[定性 / 定量 / 混合方法；实验 / 调查 / 案例分析等]\n- **核心论点**：[本文的中心论点]\n- **主要贡献**：[理论贡献 / 实践价值 / 创新点]\n\n## 章节进度\n\n| 章节 | 状态 | 字数 | 备注 |\n|------|------|------|------|\n| 摘要（中文） | [未开始/进行中/已完成] | | |\n| 摘要（英文） | [未开始/进行中/已完成] | | |\n| 第一章 引言 | [未开始/进行中/已完成] | | |\n| 第二章 文献综述 | [未开始/进行中/已完成] | | |\n| 第三章 研究方法 | [未开始/进行中/已完成] | | |\n| 第四章 结果分析 | [未开始/进行中/已完成] | | |\n| 第五章 讨论 | [未开始/进行中/已完成] | | |\n| 第六章 结论 | [未开始/进行中/已完成] | | |\n| 参考文献 | [未开始/进行中/已完成] | | |\n\n## 核心术语表\n\n> 保持全文术语统一，同一概念只用一个名称\n\n| 中文术语 | 英文术语 | 首次定义位置 | 说明 |\n|----------|----------|-------------|------|\n| [填写] | [填写] | 第X章 | [填写定义] |\n\n## 关键文献清单\n\n> 已核实真实存在的核心参考文献（写作前必须完成验证）\n\n| 序号 | 作者 | 标题 | 来源 | 年份 | 验证状态 |\n|------|------|------|------|------|----------|\n| 1 | [填写] | [填写] | [期刊/出版社] | [年份] | ✅已验证 |\n\n## 写作约束\n\n### 本论文特殊要求\n- [填写导师或目标期刊的特殊格式要求]\n- [填写禁止引用的文献范围，如：不引用非正式网络资源]\n- [填写特殊术语使用规范]\n\n### AI 辅助边界\n- ✅ 允许：润色语言表达、检查语法错误、格式排版建议\n- ✅ 允许：提供相关文献检索方向（但必须自行验证真实性）\n- ✅ 允许：提供论述思路和结构框架\n- ❌ 禁止：直接生成正文段落作为最终内容\n- ❌ 禁止：生成参考文献（必须自己查找并验证）\n- ❌ 禁止：编造实验数据、调研结果、案例信息\n\n## 上下文一致性检查清单\n\n在每次续写或修改前确认：\n\n- [ ] 当前写作的章节与研究问题保持关联\n- [ ] 使用的术语与术语表保持一致\n- [ ] 引用的文献均在关键文献清单中且已验证\n- [ ] 本段内容与上一段有逻辑衔接\n- [ ] 数据/结论与前文描述不矛盾\n- [ ] 写作风格与全文保持一致",
|
||||
"enabled": false,
|
||||
"priority": 36,
|
||||
"metadata": {
|
||||
"author": "user",
|
||||
"version": "1.0.0",
|
||||
"createdAt": "2026-06-15T23:53:17.673Z",
|
||||
"updatedAt": "2026-06-15T23:53:17.673Z",
|
||||
"tags": [
|
||||
"context",
|
||||
"paper",
|
||||
"academic",
|
||||
"writing"
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"profiles": [
|
||||
{
|
||||
"id": "default",
|
||||
"name": "默认",
|
||||
"description": "默认配置集",
|
||||
"ruleIds": [],
|
||||
"isActive": true
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
# 最高优先级规则 - 必须严格遵守（Cursor 专用）
|
||||
|
||||
⚠️⚠️⚠️ 每次回复结束前必须执行以下命令！没有任何例外！⚠️⚠️⚠️
|
||||
|
||||
## 执行规则
|
||||
|
||||
1. 完成任务后，执行弹窗命令（跨平台，Windows/Mac/Linux 通用）：
|
||||
node "/Users/freedak/.ranjin-mode/dialog-trigger.js" "cursor" "tre07y" "AI想要结束的原因摘要"
|
||||
|
||||
📱 **手机端通知**：执行此命令时会自动通知手机端（如果远程服务已开启），用户可以在手机上查看消息并发送反馈。
|
||||
|
||||
2. 仔细阅读命令输出的每一行：
|
||||
- ACTION: continue 或 end（用户的选择）
|
||||
- FEEDBACK: 用户输入的具体指令或反馈内容（⚠️ 必须完整阅读并执行！）
|
||||
* 反馈可能来自电脑端弹窗或手机端远程输入
|
||||
- IMAGES: 用户上传的图片路径（如有，必须用read_file工具查看）
|
||||
|
||||
3. 根据输出决定下一步：
|
||||
- 如果 ACTION 是 "continue"：
|
||||
* ⚠️ 必须仔细阅读 FEEDBACK 后面的全部内容
|
||||
* ⚠️ 必须按照 FEEDBACK 中用户的具体指令执行任务
|
||||
* ⚠️ 不要忽略 FEEDBACK，不要只说"用户选择继续"
|
||||
- 如果 ACTION 是 "end" 或 "stop"：停止工作
|
||||
- ⚠️ 如果命令被取消/跳过/无输出：必须重新执行弹窗命令！
|
||||
|
||||
## 核心规则
|
||||
|
||||
1. 完整输出 - 输出完整代码和答案，禁止省略
|
||||
2. 持续执行 - 复杂任务一次性完成
|
||||
3. 结束确认 - 必须执行弹窗命令后才能结束
|
||||
4. FEEDBACK必读 - 用户的FEEDBACK是新的任务指令，必须执行
|
||||
|
||||
## 手机端远程功能
|
||||
|
||||
- 📱 当执行 dialog-trigger.js 命令时，会自动通知手机端（如果远程服务已开启）
|
||||
- 📱 用户可以在手机浏览器中查看 AI 的消息和状态
|
||||
- 📱 用户可以在手机上输入反馈，反馈会通过 FEEDBACK 字段传递给你
|
||||
- 📱 手机端和电脑端弹窗功能完全同步，支持双向通信
|
||||
|
||||
## ⚠️ 唯一合法的结束条件
|
||||
|
||||
只有当命令输出包含 ACTION: end 或 ACTION: stop 时才能结束对话！
|
||||
以下情况都不能结束，必须重新执行弹窗命令：
|
||||
- 命令被用户点击 Skip 跳过
|
||||
- 命令执行失败或超时
|
||||
- 命令没有输出
|
||||
- 工作区取消了命令
|
||||
|
||||
## 禁止
|
||||
|
||||
- 禁止不执行弹窗命令就结束
|
||||
- 禁止跳过弹窗流程
|
||||
- 禁止忽略FEEDBACK内容
|
||||
- 禁止在没有收到 ACTION: end/stop 的情况下结束
|
||||
Vendored
+2
@@ -0,0 +1,2 @@
|
||||
{
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
# 最高优先级规则 - 必须严格遵守（Windsurf 专用）
|
||||
|
||||
⚠️⚠️⚠️ 每次回复结束前必须执行以下命令！没有任何例外！⚠️⚠️⚠️
|
||||
|
||||
## 执行规则
|
||||
|
||||
1. 完成任务后，执行弹窗命令（跨平台，Windows/Mac/Linux 通用）：
|
||||
node "/Users/freedak/.ranjin-mode/dialog-trigger.js" "windsurf" "tre07y" "AI想要结束的原因摘要"
|
||||
|
||||
📱 **手机端通知**：执行此命令时会自动通知手机端（如果远程服务已开启），用户可以在手机上查看消息并发送反馈。
|
||||
|
||||
2. 仔细阅读命令输出的每一行：
|
||||
- ACTION: continue 或 end（用户的选择）
|
||||
- FEEDBACK: 用户输入的具体指令或反馈内容（⚠️ 必须完整阅读并执行！）
|
||||
* 反馈可能来自电脑端弹窗或手机端远程输入
|
||||
- IMAGES: 用户上传的图片路径（如有，必须用read_file工具查看）
|
||||
|
||||
3. 根据输出决定下一步：
|
||||
- 如果 ACTION 是 "continue"：
|
||||
* ⚠️ 必须仔细阅读 FEEDBACK 后面的全部内容
|
||||
* ⚠️ 必须按照 FEEDBACK 中用户的具体指令执行任务
|
||||
* ⚠️ 不要忽略 FEEDBACK，不要只说"用户选择继续"
|
||||
- 如果 ACTION 是 "end" 或 "stop"：停止工作
|
||||
- ⚠️ 如果命令被取消/跳过/无输出：必须重新执行弹窗命令！
|
||||
|
||||
## 核心规则
|
||||
|
||||
1. 完整输出 - 输出完整代码和答案，禁止省略
|
||||
2. 持续执行 - 复杂任务一次性完成
|
||||
3. 结束确认 - 必须执行弹窗命令后才能结束
|
||||
4. FEEDBACK必读 - 用户的FEEDBACK是新的任务指令，必须执行
|
||||
|
||||
## 手机端远程功能
|
||||
|
||||
- 📱 当执行 dialog-trigger.js 命令时，会自动通知手机端（如果远程服务已开启）
|
||||
- 📱 用户可以在手机浏览器中查看 AI 的消息和状态
|
||||
- 📱 用户可以在手机上输入反馈，反馈会通过 FEEDBACK 字段传递给你
|
||||
- 📱 手机端和电脑端弹窗功能完全同步，支持双向通信
|
||||
|
||||
## ⚠️ 唯一合法的结束条件
|
||||
|
||||
只有当命令输出包含 ACTION: end 或 ACTION: stop 时才能结束对话！
|
||||
以下情况都不能结束，必须重新执行弹窗命令：
|
||||
- 命令被用户点击 Skip 跳过
|
||||
- 命令执行失败或超时
|
||||
- 命令没有输出
|
||||
- 工作区取消了命令
|
||||
|
||||
## 禁止
|
||||
|
||||
- 禁止不执行弹窗命令就结束
|
||||
- 禁止跳过弹窗流程
|
||||
- 禁止忽略FEEDBACK内容
|
||||
- 禁止在没有收到 ACTION: end/stop 的情况下结束
|
||||
+60
-59
@@ -130,50 +130,50 @@
|
||||
## P1.4 本地私有化 LLM 引擎
|
||||
> 目标：本地部署模型并支持自然语言能力。映射：R4 / PRD §4.2。依赖：P0.2.3。
|
||||
|
||||
- [ ] P1.4.1 本地模型部署（千问 70B / DeepSeek 之一）与推理服务封装
|
||||
- 验收：内网可用、推理不依赖外网；提供统一推理 API
|
||||
- [ ] P1.4.2 自然语言查数（NL→查询）能力，对接统一穿透查询服务
|
||||
- 验收：审计员自然语言提问返回结构化结果，无需写 SQL
|
||||
- [ ] P1.4.3 异常模式推理、报告生成、线索解释能力接入
|
||||
- 验收：能对给定异常聚类输出"人话"解释与结构化报告
|
||||
- [ ] P1.4.4 模型版本记录与结论可回溯
|
||||
- 验收：每条结论可回溯到模型版本
|
||||
- [ ] P1.4.5 LLM 输出防幻觉约束（强制附证据/可溯源，不可编造数据）
|
||||
- 验收：无证据支撑的结论被拦截或标注低置信
|
||||
- [x] P1.4.1 本地模型部署（千问 70B / DeepSeek 之一）与推理服务封装
|
||||
- 完成：`LLMProvider` 抽象 + DashScope/vLLM/Mock 三实现；本机用 Mock（不出域、无需 key），生产切 vLLM。本机无法跑 70B（M4 16G），生产需独立 GPU
|
||||
- [x] P1.4.2 自然语言查数（NL→查询）能力，对接统一穿透查询服务
|
||||
- 完成：`app/nlq/service.py` + `POST /nlq`；审计员自然语言提问返回回答，无需写 SQL
|
||||
- [~] P1.4.3 异常模式推理、报告生成、线索解释能力接入
|
||||
- 进展：线索的"人话理由"已由场景检测器生成；LLM 报告生成待接入真实模型
|
||||
- [x] P1.4.4 模型版本记录与结论可回溯
|
||||
- 完成：线索记录 `model_version`，扫描引擎写入版本
|
||||
- [x] P1.4.5 LLM 输出防幻觉约束（强制附证据/可溯源，不可编造数据）
|
||||
- 完成：NLQ system prompt 强约束"无证据不臆造"；线索强制带 evidence/rationale
|
||||
|
||||
## P1.5 全量穿透引擎
|
||||
> 目标：全量扫描与跨系统关联穿透。映射：R5 / PRD §4.2。依赖：P1.2、P1.3。
|
||||
|
||||
- [ ] P1.5.1 全量扫描任务框架（异步任务、进度反馈、可中断）
|
||||
- 验收：长耗时全量任务异步执行并反馈进度
|
||||
- [ ] P1.5.2 跨系统关联穿透（合同—回款—工商—账户等）
|
||||
- 验收：可输出关联路径与证据，覆盖 R8 所需穿透
|
||||
- [ ] P1.5.3 扫描覆盖范围与数据量输出（证明全量性）
|
||||
- 验收：任务结束输出覆盖范围与数据量统计
|
||||
- [ ] P1.5.4 数据就地分析、数据不出域
|
||||
- 验收：穿透过程数据不离开内网，校验纳入测试
|
||||
- [~] P1.5.1 全量扫描任务框架（异步任务、进度反馈、可中断）
|
||||
- 完成（同步版）：`app/engines/scan.py` 扫描编排，输出覆盖范围与线索；Celery 异步包装待补
|
||||
- [x] P1.5.2 跨系统关联穿透（合同—回款—工商—账户等）
|
||||
- 完成：场景一接 graph_repo 穿透识别实控人
|
||||
- [x] P1.5.3 扫描覆盖范围与数据量输出（证明全量性）
|
||||
- 完成：`ScanResult.scanned_count` 输出扫描数量
|
||||
- [x] P1.5.4 数据就地分析、数据不出域
|
||||
- 完成：扫描全程本地；Mock/vLLM provider 不出域，prod 禁用公网
|
||||
|
||||
## P1.6 线索驱动引擎
|
||||
> 目标：生成线索+证据链+解释并推送。映射：R7、R18(基础) / PRD §4.2。依赖：P1.4、P1.5。
|
||||
|
||||
- [ ] P1.6.1 线索数据模型（风险域/场景/置信度/证据链/判定理由/状态）
|
||||
- 验收：线索结构可承载证据链与状态流转
|
||||
- [ ] P1.6.2 线索生成（由穿透/规则命中产出异常聚类→线索）
|
||||
- 验收：异常聚类自动转为线索并附证据链与理由
|
||||
- [ ] P1.6.3 置信度三级分流（高/中/低）与价值排序
|
||||
- 验收：线索分级正确；高置信优先推送
|
||||
- [ ] P1.6.4 线索推送至审计员工作台
|
||||
- 验收：对应审计员可在工作台收到线索
|
||||
- [x] P1.6.1 线索数据模型（风险域/场景/置信度/证据链/判定理由/状态）
|
||||
- 完成：`app/clues/models.py`（Clue/ClueStatusHistory/WorkingPaper）
|
||||
- [x] P1.6.2 线索生成（由穿透/规则命中产出异常聚类→线索）
|
||||
- 完成：`clue_svc.create_clue` + 扫描引擎产出；集成测试验证
|
||||
- [x] P1.6.3 置信度三级分流（高/中/低）与价值排序
|
||||
- 完成：`score_to_tier` 分级；list 按 score 降序
|
||||
- [x] P1.6.4 线索推送至审计员工作台
|
||||
- 完成：`GET /clues`（按状态/场景/置信度筛选）+ 分派 assignee
|
||||
|
||||
## P1.7 场景一 · 政企收入全链路穿透（R8）
|
||||
> 目标：识别拆单规避与虚假回款。映射：R8 / PRD §4.3 Must。依赖：P1.5、P1.6。
|
||||
|
||||
- [ ] P1.7.1 政企合同全链路建模（立项→审批→报价→签约→开票→回款）
|
||||
- 验收：链路数据可端到端串联查询
|
||||
- [ ] P1.7.2 拆单识别（金额阈值边缘分布检测）
|
||||
- 验收：阈值边缘集中分布合同被识别为疑似拆单并生成线索
|
||||
- [ ] P1.7.3 工商关联穿透（隐性实控人：地址/法人亲属/付款账户同源）
|
||||
- 验收：同源关联客户被聚合识别，附证据
|
||||
- [x] P1.7.2 拆单识别（金额阈值边缘分布检测）
|
||||
- 完成：`detect_threshold_edge`+评分，单元/集成测试通过
|
||||
- [x] P1.7.3 工商关联穿透（隐性实控人：地址/法人亲属/付款账户同源）
|
||||
- 完成：graph_repo 多跳穿透识别同一实控人，评分加权
|
||||
- [ ] P1.7.4 回款时序聚类（批量违约/长期挂账）
|
||||
- 验收：批量违约模式被识别并生成线索
|
||||
- [ ] P1.7.5 一键生成《政企客户回款异常专项线索清单》
|
||||
@@ -182,10 +182,10 @@
|
||||
## P1.8 场景二 · 养卡骗补识别（R9）
|
||||
> 目标：识别脉冲新增+规律退订的周期性造假。映射：R9 / PRD §4.3 Must。依赖：P1.3、P1.6。
|
||||
|
||||
- [ ] P1.8.1 用户生命周期时序模式识别（脉冲式增长+规律性衰减）
|
||||
- 验收：周期性造假模式被识别并生成线索
|
||||
- [ ] P1.8.2 渠道佣金与业务质量匹配（在网时长/通话/流量活跃度）
|
||||
- 验收：佣金与质量不匹配渠道被标记
|
||||
- [x] P1.8.1 用户生命周期时序模式识别（脉冲式增长+规律性衰减）
|
||||
- 完成：`detect_pulse_decay` 断崖检测，单元/集成测试通过
|
||||
- [x] P1.8.2 渠道佣金与业务质量匹配（在网时长/通话/流量活跃度）
|
||||
- 完成：`commission_quality_mismatch` 不匹配度评分
|
||||
- [ ] P1.8.3 沉默/零通话/零流量用户批量聚类（含物联网卡虚假激活）
|
||||
- 验收：批量沉默用户被聚类识别
|
||||
- [ ] P1.8.4 项目交付物与收入确认交叉验证
|
||||
@@ -194,42 +194,41 @@
|
||||
## P1.9 人机协同闭环（R17 基础）
|
||||
> 目标：线索到销项全流程在线留痕。映射：R17 / PRD §4.4 Must。依赖：P1.6。
|
||||
|
||||
- [ ] P1.9.1 线索分派（主管→审计员）
|
||||
- 验收：可分派并通知；分派留痕
|
||||
- [ ] P1.9.2 复核研判与定性分类
|
||||
- 验收：审计员可研判、定性，记录理由
|
||||
- [ ] P1.9.3 审计底稿自动生成（可追溯）
|
||||
- 验收：研判完成自动生成底稿，含证据链与版本信息
|
||||
- [ ] P1.9.4 整改/移交与销项复核闭环、状态机
|
||||
- 验收：线索状态全流程可跟踪，过程留痕
|
||||
- [x] P1.9.1 线索分派（主管→审计员）
|
||||
- 完成：`clue_svc.assign` + `POST /clues/{id}/assign`，分派留痕
|
||||
- [x] P1.9.2 复核研判与定性分类
|
||||
- 完成：`clue_svc.adjudicate` + `POST /clues/{id}/adjudicate`，记录理由与反馈
|
||||
- [x] P1.9.3 审计底稿自动生成（可追溯）
|
||||
- 完成：研判完成自动生成 `WorkingPaper`，含证据链与模型/规则/数据版本快照
|
||||
- [x] P1.9.4 整改/移交与销项复核闭环、状态机
|
||||
- 完成：8 态状态机 + 合法流转校验 + `ClueStatusHistory` 留痕，集成测试覆盖
|
||||
|
||||
## P1.10 系统自审计与独立性（R19）
|
||||
> 目标：让审计系统自身经得起审计。映射：R19 / PRD §4.4 Must、§6。依赖：P0.4。
|
||||
|
||||
- [ ] P1.10.1 规则/阈值变更全程留痕（操作人/时间/变更内容）
|
||||
- 验收：任意变更可追溯
|
||||
- [ ] P1.10.2 线索不可删除约束
|
||||
- 验收：任何角色删除线索请求被拒并留痕
|
||||
- [ ] P1.10.3 关键操作分权制衡（配规则/看线索/改阈值/出报告分离）
|
||||
- 验收：越权操作被拒，符合 PRD §6 权限矩阵
|
||||
- [ ] P1.10.4 模型/规则/数据三重版本留痕与回溯
|
||||
- 验收：任一结论可回溯到当时的模型、规则、数据版本
|
||||
- [x] P1.10.1 规则/阈值变更全程留痕（操作人/时间/变更内容）
|
||||
- 完成：`audit.record` 哈希链日志，关键操作留痕；`verify_chain` 校验完整性
|
||||
- [x] P1.10.2 线索不可删除约束
|
||||
- 完成：无删除 API + 数据库触发器 `trg_clue_no_delete` 兜底；集成测试验证删除被拒
|
||||
- [x] P1.10.3 关键操作分权制衡（配规则/看线索/改阈值/出报告分离）
|
||||
- 完成：`app/audit/rbac.py` RBAC（DELETE_CLUE 不授予任何角色，业务方无权限）
|
||||
- [x] P1.10.4 模型/规则/数据三重版本留痕与回溯
|
||||
- 完成：线索与底稿记录 model/rule/data 三重版本
|
||||
|
||||
## P1.11 应用层、看板与盲测验证
|
||||
> 目标：审计员零门槛使用 + 盲测证明价值。映射：R20、R21、R18 / PRD §2.2、§7。依赖：P1.6-P1.10。
|
||||
|
||||
- [ ] P1.11.1 线索看板（按风险域/场景/置信度筛选与下钻）
|
||||
- 验收：看板可筛选下钻，展示证据链
|
||||
- [ ] P1.11.2 自然语言查询入口（前端）
|
||||
- 验收：审计员可自然语言查询并查看结果
|
||||
- [ ] P1.11.3 智能报告与专项清单导出
|
||||
- 验收：可一键生成报告/清单
|
||||
- [x] P1.11.1 线索看板（按风险域/场景/置信度筛选与下钻）
|
||||
- 完成（API）：`GET /clues`（筛选）+ `GET /clues/summary`（看板汇总）；前端页面待建
|
||||
- [x] P1.11.2 自然语言查询入口（API）
|
||||
- 完成（API）：`POST /nlq`；前端页面待建
|
||||
- [~] P1.11.3 智能报告与专项清单导出
|
||||
- 进展：清单可经 API 查询；导出格式（PDF/Excel）待补
|
||||
- [ ] P1.11.4 高置信预警推送
|
||||
- 验收：高置信线索触发主动通知
|
||||
- [ ] P1.11.5 历史数据全量重跑 + 同台盲测
|
||||
- 验收：用 2-3 年历史数据重跑，与既有审计结论对比，复现已知线索并发现新增真实线索
|
||||
- [ ] P1.11.6 同台盲测成效报告
|
||||
- 验收：产出成效报告，量化命中率与新增线索价值
|
||||
- [x] P1.11.7 前端页面（React 看板/查询/底稿）
|
||||
- 完成：Vite+React+TS,三视图(线索看板汇总/线索处置含分派研判定性/自然语言查询);Vite 代理转发后端;`npm run build` 通过,全栈端到端验证通过(种子数据可视)。无删除线索入口(R19)
|
||||
|
||||
---
|
||||
|
||||
@@ -336,6 +335,8 @@
|
||||
| --- | --- | --- |
|
||||
| 2026-06 | 初版创建 | — |
|
||||
| 2026-06 | 弃用 Docker，改用本地 PostgreSQL 16（卸载 pg14，装 pg16+pgvector）；数据中台本体/图谱/双时态落地并通过集成测试 | — |
|
||||
| 2026-06 | MVP 后端成体系：LLM Provider 抽象(含Mock)、全量穿透扫描引擎、线索引擎(分级/状态机/底稿)、系统自审计(哈希链+不可删触发器+RBAC)、场景一拆单(R8)与场景二养卡骗补(R9)检测、线索/NLQ/看板 API；44 测试全过 | — |
|
||||
| 2026-06 | 前端可演示版：React+TS 三视图(看板/处置/NLQ)，Vite 代理，构建通过；种子脚本 seed_demo；全栈端到端跑通(前端→代理→后端→PG16) | — |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -39,8 +39,13 @@ pip install -r requirements-dev.txt
|
||||
alembic upgrade head # 建表
|
||||
uvicorn app.main:app --reload
|
||||
|
||||
# 3. 前端
|
||||
# 3. 前端（端口 5173，经 Vite 代理转发后端）
|
||||
cd frontend && npm install && npm run dev
|
||||
|
||||
# 4. 生成演示数据（可选，让看板有线索可看）
|
||||
cd backend && python -m scripts.seed_demo
|
||||
```
|
||||
|
||||
> 说明：本项目不使用 Docker，开发期直接使用本机 PostgreSQL 16。
|
||||
> 演示：启动后端+前端后打开 http://localhost:5173 。前端 npm 源建议用国内镜像
|
||||
> （`npm config set registry https://registry.npmmirror.com`）；后端 pip 用清华镜像加速。
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
"""线索看板与处置 API（R7/R17/R18/R20）。
|
||||
|
||||
注意：不提供删除线索的端点（R19 线索不可删，独立性硬约束）。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
|
||||
from fastapi import APIRouter, Depends, HTTPException, Query
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.api.schemas import (
|
||||
AdjudicateRequest,
|
||||
AssignRequest,
|
||||
ClueOut,
|
||||
DashboardSummary,
|
||||
)
|
||||
from app.clues import service as clue_svc
|
||||
from app.clues.models import Clue, ClueStatus, ConfidenceTier
|
||||
from app.db import get_session
|
||||
|
||||
router = APIRouter(prefix="/clues", tags=["clues"])
|
||||
|
||||
|
||||
@router.get("", response_model=list[ClueOut])
|
||||
def list_clues(
|
||||
status: ClueStatus | None = Query(default=None),
|
||||
scenario_code: str | None = Query(default=None),
|
||||
confidence: ConfidenceTier | None = Query(default=None),
|
||||
session: Session = Depends(get_session),
|
||||
) -> list[Clue]:
|
||||
return clue_svc.list_clues(
|
||||
session, status=status, scenario_code=scenario_code, confidence=confidence
|
||||
)
|
||||
|
||||
|
||||
@router.get("/summary", response_model=DashboardSummary)
|
||||
def summary(session: Session = Depends(get_session)) -> DashboardSummary:
|
||||
"""运营看板汇总（R18/R21 的基础指标）。"""
|
||||
clues = session.query(Clue).all()
|
||||
by_status: dict[str, int] = {}
|
||||
by_conf: dict[str, int] = {}
|
||||
by_scenario: dict[str, int] = {}
|
||||
total_amount = 0.0
|
||||
for c in clues:
|
||||
by_status[c.status.value] = by_status.get(c.status.value, 0) + 1
|
||||
by_conf[c.confidence.value] = by_conf.get(c.confidence.value, 0) + 1
|
||||
by_scenario[c.scenario_code] = by_scenario.get(c.scenario_code, 0) + 1
|
||||
total_amount += c.amount_involved or 0.0
|
||||
return DashboardSummary(
|
||||
total=len(clues),
|
||||
by_status=by_status,
|
||||
by_confidence=by_conf,
|
||||
by_scenario=by_scenario,
|
||||
total_amount_involved=total_amount,
|
||||
)
|
||||
|
||||
|
||||
@router.get("/{clue_id}", response_model=ClueOut)
|
||||
def get_clue(clue_id: uuid.UUID, session: Session = Depends(get_session)) -> Clue:
|
||||
clue = session.get(Clue, clue_id)
|
||||
if clue is None:
|
||||
raise HTTPException(status_code=404, detail="线索不存在")
|
||||
return clue
|
||||
|
||||
|
||||
@router.post("/{clue_id}/assign", response_model=ClueOut)
|
||||
def assign_clue(
|
||||
clue_id: uuid.UUID, req: AssignRequest, session: Session = Depends(get_session)
|
||||
) -> Clue:
|
||||
clue = session.get(Clue, clue_id)
|
||||
if clue is None:
|
||||
raise HTTPException(status_code=404, detail="线索不存在")
|
||||
return clue_svc.assign(session, clue, assignee=req.assignee, actor=req.actor)
|
||||
|
||||
|
||||
@router.post("/{clue_id}/adjudicate", response_model=ClueOut)
|
||||
def adjudicate_clue(
|
||||
clue_id: uuid.UUID, req: AdjudicateRequest, session: Session = Depends(get_session)
|
||||
) -> Clue:
|
||||
clue = session.get(Clue, clue_id)
|
||||
if clue is None:
|
||||
raise HTTPException(status_code=404, detail="线索不存在")
|
||||
clue_svc.adjudicate(session, clue, confirmed=req.confirmed, actor=req.actor, note=req.note)
|
||||
return clue
|
||||
@@ -0,0 +1,24 @@
|
||||
"""自然语言查询 API（R4/R20）。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from fastapi import APIRouter, Depends
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.api.schemas import NLQRequest, NLQResponse
|
||||
from app.db import get_session
|
||||
from app.nlq import service as nlq
|
||||
|
||||
router = APIRouter(prefix="/nlq", tags=["nlq"])
|
||||
|
||||
|
||||
@router.post("", response_model=NLQResponse)
|
||||
def ask(req: NLQRequest, session: Session = Depends(get_session)) -> NLQResponse:
|
||||
ans = nlq.ask(req.question, session=session)
|
||||
return NLQResponse(
|
||||
question=ans.question,
|
||||
answer=ans.answer,
|
||||
provider=ans.provider,
|
||||
model=ans.model,
|
||||
egress=ans.egress,
|
||||
)
|
||||
@@ -34,3 +34,52 @@ class PenetrateResponse(BaseModel):
|
||||
max_depth: int
|
||||
related_count: int
|
||||
related: list[RelatedEntityOut]
|
||||
|
||||
|
||||
class ClueOut(BaseModel):
|
||||
id: uuid.UUID
|
||||
title: str
|
||||
risk_domain: str
|
||||
scenario_code: str
|
||||
confidence: str
|
||||
score: float
|
||||
status: str
|
||||
rationale: str
|
||||
evidence: dict = Field(default_factory=dict)
|
||||
subjects: dict = Field(default_factory=dict)
|
||||
amount_involved: float | None = None
|
||||
assignee: str | None = None
|
||||
feedback: str | None = None
|
||||
|
||||
model_config = {"from_attributes": True}
|
||||
|
||||
|
||||
class AssignRequest(BaseModel):
|
||||
assignee: str = Field(min_length=1)
|
||||
actor: str = Field(min_length=1)
|
||||
|
||||
|
||||
class AdjudicateRequest(BaseModel):
|
||||
confirmed: bool
|
||||
actor: str = Field(min_length=1)
|
||||
note: str | None = None
|
||||
|
||||
|
||||
class NLQRequest(BaseModel):
|
||||
question: str = Field(min_length=1)
|
||||
|
||||
|
||||
class NLQResponse(BaseModel):
|
||||
question: str
|
||||
answer: str
|
||||
provider: str
|
||||
model: str
|
||||
egress: bool
|
||||
|
||||
|
||||
class DashboardSummary(BaseModel):
|
||||
total: int
|
||||
by_status: dict[str, int]
|
||||
by_confidence: dict[str, int]
|
||||
by_scenario: dict[str, int]
|
||||
total_amount_involved: float
|
||||
|
||||
@@ -82,8 +82,8 @@ class Clue(Base):
|
||||
amount_involved: Mapped[float | None] = mapped_column(Float, nullable=True)
|
||||
|
||||
assignee: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
||||
# 误报/属实反馈（R18 反馈学习）
|
||||
feedback: Mapped[str | None] = mapped_column(String(16), nullable=True) # confirmed/false_positive
|
||||
feedback: Mapped[str | None] = mapped_column(String(16), nullable=True)
|
||||
"""误报/属实反馈（R18 反馈学习）：confirmed / false_positive"""
|
||||
|
||||
# 可追溯：产生该线索时的模型/规则/数据版本（R19 三重留痕）
|
||||
model_version: Mapped[str | None] = mapped_column(String(64), nullable=True)
|
||||
|
||||
@@ -132,7 +132,10 @@ def assign(session: Session, clue: Clue, assignee: str, actor: str) -> Clue:
|
||||
session.flush()
|
||||
if clue.status == ClueStatus.NEW:
|
||||
transition(session, clue, ClueStatus.ASSIGNED, actor, f"分派给 {assignee}")
|
||||
audit.record(session, actor, "assign_clue", target_type="clue", target_id=str(clue.id), detail={"assignee": assignee})
|
||||
audit.record(
|
||||
session, actor, "assign_clue",
|
||||
target_type="clue", target_id=str(clue.id), detail={"assignee": assignee},
|
||||
)
|
||||
return clue
|
||||
|
||||
|
||||
|
||||
@@ -19,6 +19,7 @@ class AppEnv(str, Enum):
|
||||
class LLMProviderName(str, Enum):
|
||||
dashscope = "dashscope" # 公网千问，仅 dev
|
||||
vllm = "vllm" # 本地，prod
|
||||
mock = "mock" # 本地确定性 Mock，开发/测试，不出域
|
||||
|
||||
|
||||
# 被认定为"公网/出域"的 Provider，prod 下禁止使用
|
||||
|
||||
@@ -41,6 +41,10 @@ class RelationshipType(str, Enum):
|
||||
SUPPLIES = "supplies" # 供应商 —供货→ 合同/工单
|
||||
HANDLED_BY = "handled_by" # 工单 —处理人→ 员工
|
||||
SETTLES = "settles" # 结算单 —结算→ 合同
|
||||
EMPLOYED_BY = "employed_by" # 员工 —任职于→ 客户/供应商（组织）
|
||||
OPERATES = "operates" # 员工 —操作→ 号码/账户（R15 越权检测）
|
||||
SUBSCRIBES = "subscribes" # 号码 —订购→ 合同（R9/R10 订购关联）
|
||||
BIDS_FOR = "bids_for" # 供应商 —投标→ 工单（R12 招投标关联）
|
||||
|
||||
|
||||
# 关系的合法 (源实体类型, 目标实体类型) 约束，用于校验图谱写入
|
||||
@@ -72,6 +76,16 @@ RELATIONSHIP_DOMAIN: dict[RelationshipType, tuple[set[EntityType], set[EntityTyp
|
||||
),
|
||||
RelationshipType.HANDLED_BY: ({EntityType.WORK_ORDER}, {EntityType.EMPLOYEE}),
|
||||
RelationshipType.SETTLES: ({EntityType.SETTLEMENT}, {EntityType.CONTRACT}),
|
||||
RelationshipType.EMPLOYED_BY: (
|
||||
{EntityType.EMPLOYEE},
|
||||
{EntityType.CUSTOMER, EntityType.SUPPLIER},
|
||||
),
|
||||
RelationshipType.OPERATES: (
|
||||
{EntityType.EMPLOYEE},
|
||||
{EntityType.MSISDN, EntityType.ACCOUNT},
|
||||
),
|
||||
RelationshipType.SUBSCRIBES: ({EntityType.MSISDN}, {EntityType.CONTRACT}),
|
||||
RelationshipType.BIDS_FOR: ({EntityType.SUPPLIER}, {EntityType.WORK_ORDER}),
|
||||
}
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,502 @@
|
||||
"""源明细落地层（Staging / Raw）。
|
||||
|
||||
保存数据中心按 `数据要求.md` 提供的原始明细，作为"原始证据"留存；
|
||||
再由接入适配器（app/ingest）映射/投影到通用本体（entity/relationship/metric_event）。
|
||||
两层并存：源明细可回溯原始数据，本体支撑关联穿透与时序分析。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime as dt
|
||||
import uuid
|
||||
|
||||
from sqlalchemy import Date, DateTime, Float, Index, Integer, String, Text
|
||||
from sqlalchemy.dialects.postgresql import UUID
|
||||
from sqlalchemy.orm import Mapped, mapped_column
|
||||
|
||||
from app.db import Base
|
||||
|
||||
|
||||
def _uuid() -> uuid.UUID:
|
||||
return uuid.uuid4()
|
||||
|
||||
|
||||
def _now() -> dt.datetime:
|
||||
return dt.datetime.now(dt.timezone.utc)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# R8 · 政企收入全链路穿透 / 拆单规避（§4.1）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class SrcContract(Base):
|
||||
"""源明细：政企合同（对应数据要求 §4.1 / R8）。"""
|
||||
|
||||
__tablename__ = "src_contract"
|
||||
__table_args__ = (Index("ix_src_contract_customer", "customer_key"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
contract_no: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
customer_key: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
customer_name: Mapped[str | None] = mapped_column(String(256))
|
||||
amount: Mapped[float] = mapped_column(Float, nullable=False)
|
||||
sign_date: Mapped[dt.date | None] = mapped_column(Date)
|
||||
approval_threshold: Mapped[float | None] = mapped_column(Float)
|
||||
approval_level: Mapped[str | None] = mapped_column(String(32))
|
||||
legal_person: Mapped[str | None] = mapped_column(String(128))
|
||||
register_address: Mapped[str | None] = mapped_column(String(256))
|
||||
pay_account: Mapped[str | None] = mapped_column(String(64))
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcContractApproval(Base):
|
||||
"""源明细：合同审批流水（对应 R8 补充）。"""
|
||||
|
||||
__tablename__ = "src_contract_approval"
|
||||
__table_args__ = (Index("ix_src_approval_contract", "contract_no"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
contract_no: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
approval_step: Mapped[int] = mapped_column(Integer, nullable=False)
|
||||
approver: Mapped[str | None] = mapped_column(String(128))
|
||||
approval_result: Mapped[str | None] = mapped_column(String(32)) # approved/rejected
|
||||
approval_time: Mapped[dt.datetime | None] = mapped_column(DateTime(timezone=True))
|
||||
remark: Mapped[str | None] = mapped_column(Text)
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcPayment(Base):
|
||||
"""源明细：回款流水（对应 R8 回款时序违约）。"""
|
||||
|
||||
__tablename__ = "src_payment"
|
||||
__table_args__ = (Index("ix_src_payment_contract", "contract_no"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
contract_no: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
pay_account: Mapped[str | None] = mapped_column(String(64))
|
||||
pay_amount: Mapped[float] = mapped_column(Float, nullable=False)
|
||||
pay_date: Mapped[dt.date | None] = mapped_column(Date)
|
||||
pay_type: Mapped[str | None] = mapped_column(String(32)) # 预付/尾款/全款
|
||||
overdue_flag: Mapped[str | None] = mapped_column(String(8)) # Y/N
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# R9 · 市场业务真实性 / 养卡骗补（§4.2）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class SrcChannelMonthly(Base):
|
||||
"""源明细：渠道用户月度留存与佣金/活跃（对应数据要求 §4.2 / R9）。"""
|
||||
|
||||
__tablename__ = "src_channel_monthly"
|
||||
__table_args__ = (Index("ix_src_channel_key", "channel_key"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
channel_key: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
cohort_label: Mapped[str] = mapped_column(String(32), nullable=False) # 新增批次（如 2025-01）
|
||||
month_index: Mapped[int] = mapped_column(Integer, nullable=False) # 第N月
|
||||
cohort_size: Mapped[int] = mapped_column(Integer, default=0)
|
||||
retained: Mapped[int] = mapped_column(Integer, default=0)
|
||||
commission_paid: Mapped[float] = mapped_column(Float, default=0.0)
|
||||
active_ratio: Mapped[float] = mapped_column(Float, default=0.0)
|
||||
zero_usage_ratio: Mapped[float] = mapped_column(Float, default=0.0)
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcSubscription(Base):
|
||||
"""源明细：用户订购与退订流水（对应 R9 订购退订分析）。"""
|
||||
|
||||
__tablename__ = "src_subscription"
|
||||
__table_args__ = (Index("ix_src_sub_msisdn", "msisdn"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
msisdn: Mapped[str] = mapped_column(String(32), nullable=False)
|
||||
channel_key: Mapped[str | None] = mapped_column(String(64))
|
||||
product_code: Mapped[str | None] = mapped_column(String(64))
|
||||
subscribe_time: Mapped[dt.datetime | None] = mapped_column(DateTime(timezone=True))
|
||||
unsubscribe_time: Mapped[dt.datetime | None] = mapped_column(DateTime(timezone=True))
|
||||
region: Mapped[str | None] = mapped_column(String(64))
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# R10 · 收入与成本跨期匹配（§4.3）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class SrcRevenueRecognition(Base):
|
||||
"""源明细：收入确认凭证与明细（对应 R10）。"""
|
||||
|
||||
__tablename__ = "src_revenue_recognition"
|
||||
__table_args__ = (Index("ix_src_rev_contract", "contract_no"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
voucher_no: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
contract_no: Mapped[str | None] = mapped_column(String(64))
|
||||
recognition_date: Mapped[dt.date | None] = mapped_column(Date)
|
||||
recognition_amount: Mapped[float] = mapped_column(Float, nullable=False)
|
||||
billing_mode: Mapped[str | None] = mapped_column(String(32)) # 按量/包年/趸交
|
||||
period_start: Mapped[dt.date | None] = mapped_column(Date)
|
||||
period_end: Mapped[dt.date | None] = mapped_column(Date)
|
||||
prepaid_flag: Mapped[str | None] = mapped_column(String(8)) # Y/N 预收/趸交
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcCostAmortization(Base):
|
||||
"""源明细：成本摊销明细（对应 R10）。"""
|
||||
|
||||
__tablename__ = "src_cost_amortization"
|
||||
__table_args__ = (Index("ix_src_cost_contract", "contract_no"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
voucher_no: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
contract_no: Mapped[str | None] = mapped_column(String(64))
|
||||
cost_type: Mapped[str | None] = mapped_column(String(64)) # 设备/安装/维护
|
||||
amortization_date: Mapped[dt.date | None] = mapped_column(Date)
|
||||
amortization_amount: Mapped[float] = mapped_column(Float, nullable=False)
|
||||
total_periods: Mapped[int | None] = mapped_column(Integer)
|
||||
current_period: Mapped[int | None] = mapped_column(Integer)
|
||||
delivery_date: Mapped[dt.date | None] = mapped_column(Date) # 交付/上架日期
|
||||
acceptance_date: Mapped[dt.date | None] = mapped_column(Date) # 验收日期
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# R11 · 渠道佣金与代理商套利（§4.4）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class SrcTerminalBinding(Base):
|
||||
"""源明细：终端 IMEI 与号码绑定 / 补贴发放（对应 R11）。"""
|
||||
|
||||
__tablename__ = "src_terminal_binding"
|
||||
__table_args__ = (
|
||||
Index("ix_src_terminal_imei", "imei"),
|
||||
Index("ix_src_terminal_msisdn", "msisdn"),
|
||||
)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
imei: Mapped[str] = mapped_column(String(32), nullable=False)
|
||||
msisdn: Mapped[str] = mapped_column(String(32), nullable=False)
|
||||
brand_model: Mapped[str | None] = mapped_column(String(128))
|
||||
activate_time: Mapped[dt.datetime | None] = mapped_column(DateTime(timezone=True))
|
||||
subsidy_amount: Mapped[float] = mapped_column(Float, default=0.0)
|
||||
commission_amount: Mapped[float] = mapped_column(Float, default=0.0)
|
||||
online_days: Mapped[int | None] = mapped_column(Integer) # 在网天数
|
||||
post_activate_traffic_mb: Mapped[float | None] = mapped_column(Float) # 激活后流量
|
||||
region: Mapped[str | None] = mapped_column(String(64)) # 归属地
|
||||
cross_province_flag: Mapped[str | None] = mapped_column(String(8)) # 跨省入网 Y/N
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# R12 · 网络建设与工程采购（§4.5）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class SrcBidding(Base):
|
||||
"""源明细：招投标记录（对应 R12）。"""
|
||||
|
||||
__tablename__ = "src_bidding"
|
||||
__table_args__ = (Index("ix_src_bidding_project", "project_no"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
project_no: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
project_name: Mapped[str | None] = mapped_column(String(256))
|
||||
bidder_key: Mapped[str] = mapped_column(String(64), nullable=False) # 投标人/供应商编号
|
||||
bidder_name: Mapped[str | None] = mapped_column(String(256))
|
||||
bid_amount: Mapped[float | None] = mapped_column(Float)
|
||||
bid_time: Mapped[dt.datetime | None] = mapped_column(DateTime(timezone=True))
|
||||
win_flag: Mapped[str | None] = mapped_column(String(8)) # 中标 Y/N
|
||||
technical_score: Mapped[float | None] = mapped_column(Float)
|
||||
legal_person: Mapped[str | None] = mapped_column(String(128))
|
||||
shareholder_info: Mapped[str | None] = mapped_column(Text) # JSON or 描述
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcProjectSignoff(Base):
|
||||
"""源明细：工程量签证与施工（对应 R12）。"""
|
||||
|
||||
__tablename__ = "src_project_signoff"
|
||||
__table_args__ = (Index("ix_src_signoff_project", "project_no"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
project_no: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
work_order_no: Mapped[str | None] = mapped_column(String(64))
|
||||
signoff_quantity: Mapped[float | None] = mapped_column(Float) # 签证工程量
|
||||
unit: Mapped[str | None] = mapped_column(String(32))
|
||||
resource_consumed: Mapped[float | None] = mapped_column(Float) # 实际资源消耗
|
||||
contractor_key: Mapped[str | None] = mapped_column(String(64)) # 施工队
|
||||
signoff_date: Mapped[dt.date | None] = mapped_column(Date)
|
||||
inspection_lat: Mapped[float | None] = mapped_column(Float) # 巡检 GPS 纬度
|
||||
inspection_lng: Mapped[float | None] = mapped_column(Float) # 巡检 GPS 经度
|
||||
inspection_time: Mapped[dt.datetime | None] = mapped_column(DateTime(timezone=True))
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# R13 · 互联互通与网间结算（§4.6）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class SrcCdr(Base):
|
||||
"""源明细：话单 CDR（对应 R13，大数据量增量接入）。"""
|
||||
|
||||
__tablename__ = "src_cdr"
|
||||
__table_args__ = (
|
||||
Index("ix_src_cdr_caller", "caller"),
|
||||
Index("ix_src_cdr_time", "start_time"),
|
||||
)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
caller: Mapped[str] = mapped_column(String(32), nullable=False)
|
||||
callee: Mapped[str] = mapped_column(String(32), nullable=False)
|
||||
start_time: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), nullable=False)
|
||||
duration_sec: Mapped[int] = mapped_column(Integer, nullable=False)
|
||||
call_type: Mapped[str | None] = mapped_column(String(16)) # voice/sms/data
|
||||
peer_operator: Mapped[str | None] = mapped_column(String(32)) # 对端运营商
|
||||
route_info: Mapped[str | None] = mapped_column(String(128)) # 路由信息
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcInterconnectSettlement(Base):
|
||||
"""源明细：网间结算单（对应 R13）。"""
|
||||
|
||||
__tablename__ = "src_interconnect_settlement"
|
||||
__table_args__ = (Index("ix_src_ics_period", "settle_period"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
settlement_no: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
peer_operator: Mapped[str] = mapped_column(String(32), nullable=False)
|
||||
settle_period: Mapped[str] = mapped_column(String(16), nullable=False) # 如 2025-06
|
||||
settle_type: Mapped[str | None] = mapped_column(String(32)) # 语音/短信/SP/CP
|
||||
volume: Mapped[float] = mapped_column(Float, default=0.0) # 结算量（分钟/条）
|
||||
unit_price: Mapped[float | None] = mapped_column(Float)
|
||||
settle_amount: Mapped[float] = mapped_column(Float, default=0.0)
|
||||
sms_delivery_rate: Mapped[float | None] = mapped_column(Float) # 短信到达率
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# R14 · 云业务 / IDC 与新兴业务（§4.7）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class SrcCloudUsage(Base):
|
||||
"""源明细：云资源用量（对应 R14）。"""
|
||||
|
||||
__tablename__ = "src_cloud_usage"
|
||||
__table_args__ = (Index("ix_src_cloud_contract", "contract_no"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
contract_no: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
customer_key: Mapped[str | None] = mapped_column(String(64))
|
||||
resource_type: Mapped[str | None] = mapped_column(String(32)) # CPU/存储/带宽
|
||||
usage_date: Mapped[dt.date | None] = mapped_column(Date)
|
||||
actual_usage: Mapped[float] = mapped_column(Float, default=0.0) # 实际用量
|
||||
contracted_quota: Mapped[float | None] = mapped_column(Float) # 合同约定量
|
||||
billed_usage: Mapped[float | None] = mapped_column(Float) # 计费量
|
||||
unit: Mapped[str | None] = mapped_column(String(16)) # vCPU/GB/Mbps
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcIdcCabinet(Base):
|
||||
"""源明细：IDC 机柜出租与电力消耗（对应 R14）。"""
|
||||
|
||||
__tablename__ = "src_idc_cabinet"
|
||||
__table_args__ = (Index("ix_src_idc_cabinet_id", "cabinet_id"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
cabinet_id: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
customer_key: Mapped[str | None] = mapped_column(String(64))
|
||||
contract_no: Mapped[str | None] = mapped_column(String(64))
|
||||
report_month: Mapped[str | None] = mapped_column(String(16)) # 如 2025-06
|
||||
occupancy_rate: Mapped[float | None] = mapped_column(Float) # 出租率
|
||||
power_kwh: Mapped[float | None] = mapped_column(Float) # 电力消耗 kWh
|
||||
revenue_amount: Mapped[float | None] = mapped_column(Float) # 收入金额
|
||||
acceptance_date: Mapped[dt.date | None] = mapped_column(Date) # 验收日期
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# R15 · 员工内部舞弊与资源滥用（§4.8）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class SrcEmployeeOperation(Base):
|
||||
"""源明细：员工权限与操作日志（对应 R15）。"""
|
||||
|
||||
__tablename__ = "src_employee_operation"
|
||||
__table_args__ = (
|
||||
Index("ix_src_emp_op_employee", "employee_key"),
|
||||
Index("ix_src_emp_op_time", "operation_time"),
|
||||
)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
employee_key: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
employee_name: Mapped[str | None] = mapped_column(String(128))
|
||||
position: Mapped[str | None] = mapped_column(String(64))
|
||||
role_permissions: Mapped[str | None] = mapped_column(Text) # 岗位-权限
|
||||
operation_type: Mapped[str | None] = mapped_column(String(64))
|
||||
operation_target: Mapped[str | None] = mapped_column(String(256)) # 操作对象
|
||||
operation_time: Mapped[dt.datetime | None] = mapped_column(DateTime(timezone=True))
|
||||
department: Mapped[str | None] = mapped_column(String(128))
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcInternalMsisdn(Base):
|
||||
"""源明细：内部测试号及用量（对应 R15）。"""
|
||||
|
||||
__tablename__ = "src_internal_msisdn"
|
||||
__table_args__ = (Index("ix_src_int_msisdn", "msisdn"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
msisdn: Mapped[str] = mapped_column(String(32), nullable=False)
|
||||
assigned_employee: Mapped[str | None] = mapped_column(String(64))
|
||||
purpose: Mapped[str | None] = mapped_column(String(128)) # 测试/演示/其他
|
||||
traffic_mb: Mapped[float] = mapped_column(Float, default=0.0)
|
||||
voice_min: Mapped[float] = mapped_column(Float, default=0.0)
|
||||
revenue_attributed: Mapped[float] = mapped_column(Float, default=0.0) # 收入归属
|
||||
report_month: Mapped[str | None] = mapped_column(String(16))
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcPointsTransaction(Base):
|
||||
"""源明细：积分/电子券发放与兑换流水（对应 R15）。"""
|
||||
|
||||
__tablename__ = "src_points_transaction"
|
||||
__table_args__ = (Index("ix_src_points_employee", "operator_key"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
transaction_no: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
operator_key: Mapped[str] = mapped_column(String(64), nullable=False) # 操作人工号
|
||||
target_account: Mapped[str | None] = mapped_column(String(64)) # 受益账户
|
||||
transaction_type: Mapped[str | None] = mapped_column(String(32)) # 发放/兑换/变现
|
||||
points_amount: Mapped[float] = mapped_column(Float, default=0.0)
|
||||
cash_value: Mapped[float | None] = mapped_column(Float) # 变现金额
|
||||
transaction_time: Mapped[dt.datetime | None] = mapped_column(DateTime(timezone=True))
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 主数据源明细（§3 实体级原始数据）
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class SrcCustomer(Base):
|
||||
"""源明细：客户主数据（§3 Customer）。"""
|
||||
|
||||
__tablename__ = "src_customer"
|
||||
__table_args__ = (Index("ix_src_cust_key", "customer_key"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
customer_key: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
customer_name: Mapped[str] = mapped_column(String(256), nullable=False)
|
||||
customer_type: Mapped[str | None] = mapped_column(String(32)) # 政企/公众
|
||||
register_address: Mapped[str | None] = mapped_column(String(256))
|
||||
legal_person: Mapped[str | None] = mapped_column(String(128))
|
||||
uscc: Mapped[str | None] = mapped_column(String(32)) # 统一社会信用代码
|
||||
open_date: Mapped[dt.date | None] = mapped_column(Date)
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcSupplier(Base):
|
||||
"""源明细：供应商主数据（§3 Supplier）。"""
|
||||
|
||||
__tablename__ = "src_supplier"
|
||||
__table_args__ = (Index("ix_src_supplier_key", "supplier_key"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
supplier_key: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
supplier_name: Mapped[str] = mapped_column(String(256), nullable=False)
|
||||
legal_person: Mapped[str | None] = mapped_column(String(128))
|
||||
shareholder_info: Mapped[str | None] = mapped_column(Text)
|
||||
register_address: Mapped[str | None] = mapped_column(String(256))
|
||||
uscc: Mapped[str | None] = mapped_column(String(32))
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcEmployee(Base):
|
||||
"""源明细：员工主数据（§3 Employee）。"""
|
||||
|
||||
__tablename__ = "src_employee"
|
||||
__table_args__ = (Index("ix_src_emp_key", "employee_key"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
employee_key: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
employee_name: Mapped[str | None] = mapped_column(String(128))
|
||||
position: Mapped[str | None] = mapped_column(String(64))
|
||||
department: Mapped[str | None] = mapped_column(String(128))
|
||||
role_permissions: Mapped[str | None] = mapped_column(Text)
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcChannel(Base):
|
||||
"""源明细：渠道/代理商主数据（§3 Channel）。"""
|
||||
|
||||
__tablename__ = "src_channel"
|
||||
__table_args__ = (Index("ix_src_chan_key", "channel_key"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
channel_key: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
channel_name: Mapped[str | None] = mapped_column(String(256))
|
||||
commission_policy: Mapped[str | None] = mapped_column(Text) # 佣金政策描述
|
||||
region: Mapped[str | None] = mapped_column(String(64))
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcMsisdn(Base):
|
||||
"""源明细：号码主数据（§3 MSISDN）。"""
|
||||
|
||||
__tablename__ = "src_msisdn"
|
||||
__table_args__ = (Index("ix_src_msisdn_no", "msisdn"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
msisdn: Mapped[str] = mapped_column(String(32), nullable=False)
|
||||
customer_key: Mapped[str | None] = mapped_column(String(64))
|
||||
region: Mapped[str | None] = mapped_column(String(64))
|
||||
activate_date: Mapped[dt.date | None] = mapped_column(Date)
|
||||
deactivate_date: Mapped[dt.date | None] = mapped_column(Date)
|
||||
status: Mapped[str | None] = mapped_column(String(16)) # active/suspended/cancelled
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
|
||||
|
||||
class SrcAccount(Base):
|
||||
"""源明细：账户主数据（§3 Account）。"""
|
||||
|
||||
__tablename__ = "src_account"
|
||||
__table_args__ = (Index("ix_src_acct_key", "account_key"),)
|
||||
|
||||
id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=_uuid)
|
||||
account_key: Mapped[str] = mapped_column(String(64), nullable=False)
|
||||
account_name: Mapped[str | None] = mapped_column(String(256))
|
||||
owner_key: Mapped[str | None] = mapped_column(String(64)) # 所属主体编号
|
||||
owner_type: Mapped[str | None] = mapped_column(String(32)) # customer/supplier/legal_person
|
||||
bank_name: Mapped[str | None] = mapped_column(String(128))
|
||||
branch_name: Mapped[str | None] = mapped_column(String(128))
|
||||
data_version_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True))
|
||||
ingested_at: Mapped[dt.datetime] = mapped_column(DateTime(timezone=True), default=_now)
|
||||
@@ -0,0 +1 @@
|
||||
"""引擎层：全量穿透扫描编排，将场景检测结果落为线索。"""
|
||||
@@ -0,0 +1,100 @@
|
||||
"""全量穿透扫描编排（P1.5）。
|
||||
|
||||
把场景检测器的结果转化为线索，记录扫描覆盖范围（证明全量性）与数据版本（可追溯）。
|
||||
当前为同步执行；后续可包装为 Celery 异步任务（接口保持不变）。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
from dataclasses import dataclass
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.clues import service as clue_svc
|
||||
from app.clues.models import Clue
|
||||
from app.scenarios import churn_fraud as cf
|
||||
from app.scenarios import split_contract as sc
|
||||
|
||||
MODEL_VERSION = "mock-llm@0.1"
|
||||
|
||||
|
||||
@dataclass
|
||||
class ScanResult:
|
||||
scenario_code: str
|
||||
scanned_count: int
|
||||
clue: Clue | None
|
||||
|
||||
|
||||
def run_split_contract_scan(
|
||||
session: Session,
|
||||
contracts: list[sc.ContractRecord],
|
||||
approval_threshold: float,
|
||||
shared_controller: bool = False,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
) -> ScanResult:
|
||||
"""场景一拆单扫描：检测→评分→（命中则）生成线索。"""
|
||||
finding = sc.detect_threshold_edge(contracts, approval_threshold)
|
||||
score = sc.split_risk_score(finding, shared_controller)
|
||||
clue = None
|
||||
if score > 0:
|
||||
rationale = sc.build_rationale(finding, approval_threshold, shared_controller)
|
||||
clue = clue_svc.create_clue(
|
||||
session,
|
||||
title="疑似政企拆单规避审批",
|
||||
risk_domain="收入",
|
||||
scenario_code="R8",
|
||||
score=score,
|
||||
rationale=rationale,
|
||||
evidence={
|
||||
"near_threshold_contracts": [c.contract_id for c in finding.near_threshold],
|
||||
"edge_ratio": finding.ratio,
|
||||
"near_threshold_amount": finding.total_amount,
|
||||
"approval_threshold": approval_threshold,
|
||||
"shared_controller": shared_controller,
|
||||
},
|
||||
subjects={"customers": sorted({c.customer_key for c in finding.near_threshold})},
|
||||
amount_involved=finding.total_amount,
|
||||
model_version=MODEL_VERSION,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
return ScanResult("R8", len(contracts), clue)
|
||||
|
||||
|
||||
def run_churn_scan(
|
||||
session: Session,
|
||||
retention_curve: list[cf.CohortPoint],
|
||||
commission_paid: float,
|
||||
active_ratio: float,
|
||||
zero_usage_ratio: float,
|
||||
channel_key: str,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
) -> ScanResult:
|
||||
"""场景二养卡骗补扫描：时序断崖 + 佣金质量不匹配→线索。"""
|
||||
finding = cf.detect_pulse_decay(retention_curve)
|
||||
mismatch = cf.commission_quality_mismatch(commission_paid, active_ratio, zero_usage_ratio)
|
||||
score = cf.churn_risk_score(finding, mismatch)
|
||||
clue = None
|
||||
if score >= 0.5:
|
||||
rationale = cf.build_rationale(finding, mismatch)
|
||||
clue = clue_svc.create_clue(
|
||||
session,
|
||||
title="疑似养卡骗补（脉冲增长+规律退订）",
|
||||
risk_domain="成本",
|
||||
scenario_code="R9",
|
||||
score=score,
|
||||
rationale=rationale,
|
||||
evidence={
|
||||
"cliff_month": finding.cliff_month,
|
||||
"max_drop": finding.max_drop,
|
||||
"commission_paid": commission_paid,
|
||||
"active_ratio": active_ratio,
|
||||
"zero_usage_ratio": zero_usage_ratio,
|
||||
"mismatch": mismatch,
|
||||
},
|
||||
subjects={"channel": channel_key},
|
||||
amount_involved=commission_paid,
|
||||
model_version=MODEL_VERSION,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
return ScanResult("R9", len(retention_curve), clue)
|
||||
@@ -0,0 +1,23 @@
|
||||
"""接入适配器（P1.1）：源明细 → 通用本体映射。
|
||||
|
||||
职责：
|
||||
1. 从 staging（源明细）读取原始数据行；
|
||||
2. 按映射规则投影为 Entity / EntityRelationship / MetricEvent；
|
||||
3. 保留源明细不可变（原始证据），本体层为分析基础。
|
||||
|
||||
设计原则：
|
||||
- 每个源明细表对应一个 Adapter 类；
|
||||
- Adapter 实现统一接口 `ingest(session, data_version_id)` → (entities, relationships, events)；
|
||||
- 映射逻辑集中于此模块，上层引擎/场景模块只依赖本体。
|
||||
"""
|
||||
|
||||
from app.ingest.base import BaseAdapter, IngestResult
|
||||
from app.ingest.registry import ADAPTER_REGISTRY, get_adapter, register_adapter
|
||||
|
||||
__all__ = [
|
||||
"BaseAdapter",
|
||||
"IngestResult",
|
||||
"ADAPTER_REGISTRY",
|
||||
"get_adapter",
|
||||
"register_adapter",
|
||||
]
|
||||
@@ -0,0 +1,360 @@
|
||||
"""主数据适配器：将源明细中的主数据表映射到本体 Entity 层。
|
||||
|
||||
覆盖：SrcCustomer / SrcSupplier / SrcEmployee / SrcChannel / SrcMsisdn / SrcAccount
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.datahub.graph_repo import add_relationship, upsert_entity
|
||||
from app.datahub.ontology import EntityType, RelationshipType
|
||||
from app.datahub.staging import (
|
||||
SrcAccount,
|
||||
SrcChannel,
|
||||
SrcCustomer,
|
||||
SrcEmployee,
|
||||
SrcMsisdn,
|
||||
SrcSupplier,
|
||||
)
|
||||
from app.ingest.base import BaseAdapter, IngestResult
|
||||
from app.ingest.registry import register_adapter
|
||||
|
||||
|
||||
@register_adapter
|
||||
class CustomerAdapter(BaseAdapter):
|
||||
"""SrcCustomer → Entity(CUSTOMER) + 关系(REGISTERED_AT, LEGAL_REP_OF)。"""
|
||||
|
||||
source_system = "BSS"
|
||||
staging_table = "src_customer"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
rows = session.query(SrcCustomer).filter(
|
||||
SrcCustomer.data_version_id == data_version_id
|
||||
).limit(batch_size).all() if data_version_id else session.query(SrcCustomer).limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CUSTOMER,
|
||||
business_key=row.customer_key,
|
||||
display_name=row.customer_name,
|
||||
attributes={
|
||||
"customer_type": row.customer_type,
|
||||
"uscc": row.uscc,
|
||||
"open_date": str(row.open_date) if row.open_date else None,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(entity)
|
||||
|
||||
# 注册地址 → Entity(ADDRESS) + 关系 REGISTERED_AT
|
||||
if row.register_address:
|
||||
addr_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.ADDRESS,
|
||||
business_key=row.register_address,
|
||||
display_name=row.register_address,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(addr_entity)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.REGISTERED_AT, entity, addr_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
# 法人 → Entity(LEGAL_PERSON) + 关系 LEGAL_REP_OF
|
||||
if row.legal_person:
|
||||
lp_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.LEGAL_PERSON,
|
||||
business_key=row.legal_person,
|
||||
display_name=row.legal_person,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(lp_entity)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.LEGAL_REP_OF, lp_entity, entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class SupplierAdapter(BaseAdapter):
|
||||
"""SrcSupplier → Entity(SUPPLIER) + 关系(REGISTERED_AT, LEGAL_REP_OF)。"""
|
||||
|
||||
source_system = "ERP"
|
||||
staging_table = "src_supplier"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
rows = session.query(SrcSupplier).filter(
|
||||
SrcSupplier.data_version_id == data_version_id
|
||||
).limit(batch_size).all() if data_version_id else session.query(SrcSupplier).limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.SUPPLIER,
|
||||
business_key=row.supplier_key,
|
||||
display_name=row.supplier_name,
|
||||
attributes={
|
||||
"uscc": row.uscc,
|
||||
"shareholder_info": row.shareholder_info,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(entity)
|
||||
|
||||
if row.register_address:
|
||||
addr_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.ADDRESS,
|
||||
business_key=row.register_address,
|
||||
display_name=row.register_address,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(addr_entity)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.REGISTERED_AT, entity, addr_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
if row.legal_person:
|
||||
lp_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.LEGAL_PERSON,
|
||||
business_key=row.legal_person,
|
||||
display_name=row.legal_person,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(lp_entity)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.LEGAL_REP_OF, lp_entity, entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class EmployeeAdapter(BaseAdapter):
|
||||
"""SrcEmployee → Entity(EMPLOYEE)。"""
|
||||
|
||||
source_system = "ERP"
|
||||
staging_table = "src_employee"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
rows = session.query(SrcEmployee).filter(
|
||||
SrcEmployee.data_version_id == data_version_id
|
||||
).limit(batch_size).all() if data_version_id else session.query(SrcEmployee).limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.EMPLOYEE,
|
||||
business_key=row.employee_key,
|
||||
display_name=row.employee_name,
|
||||
attributes={
|
||||
"position": row.position,
|
||||
"department": row.department,
|
||||
"role_permissions": row.role_permissions,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class ChannelAdapter(BaseAdapter):
|
||||
"""SrcChannel → Entity(CHANNEL)。"""
|
||||
|
||||
source_system = "BSS"
|
||||
staging_table = "src_channel"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
rows = session.query(SrcChannel).filter(
|
||||
SrcChannel.data_version_id == data_version_id
|
||||
).limit(batch_size).all() if data_version_id else session.query(SrcChannel).limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CHANNEL,
|
||||
business_key=row.channel_key,
|
||||
display_name=row.channel_name,
|
||||
attributes={
|
||||
"commission_policy": row.commission_policy,
|
||||
"region": row.region,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class MsisdnAdapter(BaseAdapter):
|
||||
"""SrcMsisdn → Entity(MSISDN) + 关系(HOLDS_MSISDN)。"""
|
||||
|
||||
source_system = "BSS"
|
||||
staging_table = "src_msisdn"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
rows = session.query(SrcMsisdn).filter(
|
||||
SrcMsisdn.data_version_id == data_version_id
|
||||
).limit(batch_size).all() if data_version_id else session.query(SrcMsisdn).limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
msisdn_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.MSISDN,
|
||||
business_key=row.msisdn,
|
||||
display_name=row.msisdn,
|
||||
attributes={
|
||||
"region": row.region,
|
||||
"status": row.status,
|
||||
"activate_date": str(row.activate_date) if row.activate_date else None,
|
||||
"deactivate_date": str(row.deactivate_date) if row.deactivate_date else None,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(msisdn_entity)
|
||||
|
||||
# 号码 → 客户持有关系
|
||||
if row.customer_key:
|
||||
cust_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CUSTOMER,
|
||||
business_key=row.customer_key,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.HOLDS_MSISDN, cust_entity, msisdn_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class AccountAdapter(BaseAdapter):
|
||||
"""SrcAccount → Entity(ACCOUNT) + 关系(OWNS_ACCOUNT)。"""
|
||||
|
||||
source_system = "FIN"
|
||||
staging_table = "src_account"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
rows = session.query(SrcAccount).filter(
|
||||
SrcAccount.data_version_id == data_version_id
|
||||
).limit(batch_size).all() if data_version_id else session.query(SrcAccount).limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
acct_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.ACCOUNT,
|
||||
business_key=row.account_key,
|
||||
display_name=row.account_name,
|
||||
attributes={
|
||||
"bank_name": row.bank_name,
|
||||
"branch_name": row.branch_name,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(acct_entity)
|
||||
|
||||
# 账户所属主体关系
|
||||
if row.owner_key and row.owner_type:
|
||||
owner_type_map = {
|
||||
"customer": EntityType.CUSTOMER,
|
||||
"supplier": EntityType.SUPPLIER,
|
||||
"legal_person": EntityType.LEGAL_PERSON,
|
||||
}
|
||||
etype = owner_type_map.get(row.owner_type)
|
||||
if etype:
|
||||
owner_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=etype,
|
||||
business_key=row.owner_key,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.OWNS_ACCOUNT, owner_entity, acct_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
@@ -0,0 +1,137 @@
|
||||
"""R10 适配器：收入与成本跨期匹配。
|
||||
|
||||
源明细：SrcRevenueRecognition / SrcCostAmortization
|
||||
映射到：MetricEvent（收入确认/成本摊销时序） + Entity(CONTRACT) 关联补强
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime as dt
|
||||
import uuid
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.datahub.graph_repo import upsert_entity
|
||||
from app.datahub.models import MetricEvent
|
||||
from app.datahub.ontology import EntityType
|
||||
from app.datahub.staging import SrcCostAmortization, SrcRevenueRecognition
|
||||
from app.ingest.base import BaseAdapter, IngestResult
|
||||
from app.ingest.registry import register_adapter
|
||||
|
||||
|
||||
@register_adapter
|
||||
class RevenueRecognitionAdapter(BaseAdapter):
|
||||
"""SrcRevenueRecognition → MetricEvent（收入确认时序）。"""
|
||||
|
||||
source_system = "FIN"
|
||||
staging_table = "src_revenue_recognition"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcRevenueRecognition)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcRevenueRecognition.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# 确保合同实体存在
|
||||
if row.contract_no:
|
||||
upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CONTRACT,
|
||||
business_key=row.contract_no,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
|
||||
if row.recognition_date:
|
||||
event_time = dt.datetime.combine(
|
||||
row.recognition_date, dt.time.min, tzinfo=dt.timezone.utc
|
||||
)
|
||||
event = MetricEvent(
|
||||
event_time=event_time,
|
||||
subject_type="contract",
|
||||
subject_key=row.contract_no or row.voucher_no,
|
||||
metric_name="revenue_recognition",
|
||||
metric_value=row.recognition_amount,
|
||||
attributes={
|
||||
"voucher_no": row.voucher_no,
|
||||
"billing_mode": row.billing_mode,
|
||||
"period_start": str(row.period_start) if row.period_start else None,
|
||||
"period_end": str(row.period_end) if row.period_end else None,
|
||||
"prepaid_flag": row.prepaid_flag,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class CostAmortizationAdapter(BaseAdapter):
|
||||
"""SrcCostAmortization → MetricEvent（成本摊销时序）。"""
|
||||
|
||||
source_system = "FIN"
|
||||
staging_table = "src_cost_amortization"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcCostAmortization)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcCostAmortization.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
if row.contract_no:
|
||||
upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CONTRACT,
|
||||
business_key=row.contract_no,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
|
||||
if row.amortization_date:
|
||||
event_time = dt.datetime.combine(
|
||||
row.amortization_date, dt.time.min, tzinfo=dt.timezone.utc
|
||||
)
|
||||
event = MetricEvent(
|
||||
event_time=event_time,
|
||||
subject_type="contract",
|
||||
subject_key=row.contract_no or row.voucher_no,
|
||||
metric_name="cost_amortization",
|
||||
metric_value=row.amortization_amount,
|
||||
attributes={
|
||||
"voucher_no": row.voucher_no,
|
||||
"cost_type": row.cost_type,
|
||||
"total_periods": row.total_periods,
|
||||
"current_period": row.current_period,
|
||||
"delivery_date": str(row.delivery_date) if row.delivery_date else None,
|
||||
"acceptance_date": str(row.acceptance_date) if row.acceptance_date else None,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
@@ -0,0 +1,103 @@
|
||||
"""R11 适配器：渠道佣金与代理商套利。
|
||||
|
||||
源明细：SrcTerminalBinding
|
||||
映射到：Entity(IMEI, MSISDN) + 关系(BOUND_DEVICE) + MetricEvent
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.datahub.graph_repo import add_relationship, upsert_entity
|
||||
from app.datahub.models import MetricEvent
|
||||
from app.datahub.ontology import EntityType, RelationshipType
|
||||
from app.datahub.staging import SrcTerminalBinding
|
||||
from app.ingest.base import BaseAdapter, IngestResult
|
||||
from app.ingest.registry import register_adapter
|
||||
|
||||
|
||||
@register_adapter
|
||||
class TerminalBindingAdapter(BaseAdapter):
|
||||
"""SrcTerminalBinding → Entity(IMEI, MSISDN) + BOUND_DEVICE + MetricEvent。"""
|
||||
|
||||
source_system = "BSS"
|
||||
staging_table = "src_terminal_binding"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcTerminalBinding)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcTerminalBinding.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# IMEI 实体
|
||||
imei_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.IMEI,
|
||||
business_key=row.imei,
|
||||
display_name=row.brand_model or row.imei,
|
||||
attributes={
|
||||
"brand_model": row.brand_model,
|
||||
"region": row.region,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(imei_entity)
|
||||
|
||||
# MSISDN 实体
|
||||
msisdn_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.MSISDN,
|
||||
business_key=row.msisdn,
|
||||
display_name=row.msisdn,
|
||||
attributes={"region": row.region},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(msisdn_entity)
|
||||
|
||||
# 绑定关系
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.BOUND_DEVICE, msisdn_entity, imei_entity,
|
||||
attributes={
|
||||
"activate_time": str(row.activate_time) if row.activate_time else None,
|
||||
"subsidy_amount": row.subsidy_amount,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
# 终端激活/补贴事件
|
||||
if row.activate_time:
|
||||
event = MetricEvent(
|
||||
event_time=row.activate_time,
|
||||
subject_type="imei",
|
||||
subject_key=row.imei,
|
||||
metric_name="terminal_activate",
|
||||
metric_value=row.subsidy_amount + row.commission_amount,
|
||||
attributes={
|
||||
"msisdn": row.msisdn,
|
||||
"subsidy_amount": row.subsidy_amount,
|
||||
"commission_amount": row.commission_amount,
|
||||
"online_days": row.online_days,
|
||||
"post_activate_traffic_mb": row.post_activate_traffic_mb,
|
||||
"cross_province_flag": row.cross_province_flag,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
@@ -0,0 +1,200 @@
|
||||
"""R12 适配器：网络建设与工程采购。
|
||||
|
||||
源明细：SrcBidding / SrcProjectSignoff
|
||||
映射到：Entity(SUPPLIER, WORK_ORDER) + 关系(BIDS_FOR, SUPPLIES) + MetricEvent
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime as dt
|
||||
import uuid
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.datahub.graph_repo import add_relationship, upsert_entity
|
||||
from app.datahub.models import MetricEvent
|
||||
from app.datahub.ontology import EntityType, RelationshipType
|
||||
from app.datahub.staging import SrcBidding, SrcProjectSignoff
|
||||
from app.ingest.base import BaseAdapter, IngestResult
|
||||
from app.ingest.registry import register_adapter
|
||||
|
||||
|
||||
@register_adapter
|
||||
class BiddingAdapter(BaseAdapter):
|
||||
"""SrcBidding → Entity(SUPPLIER, WORK_ORDER) + 关系(BIDS_FOR) + MetricEvent。"""
|
||||
|
||||
source_system = "ERP"
|
||||
staging_table = "src_bidding"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcBidding)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcBidding.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# 供应商(投标人)实体
|
||||
supplier_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.SUPPLIER,
|
||||
business_key=row.bidder_key,
|
||||
display_name=row.bidder_name,
|
||||
attributes={
|
||||
"legal_person": row.legal_person,
|
||||
"shareholder_info": row.shareholder_info,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(supplier_entity)
|
||||
|
||||
# 工单/项目实体
|
||||
wo_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.WORK_ORDER,
|
||||
business_key=row.project_no,
|
||||
display_name=row.project_name,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(wo_entity)
|
||||
|
||||
# 投标关系
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.BIDS_FOR, supplier_entity, wo_entity,
|
||||
attributes={
|
||||
"bid_amount": row.bid_amount,
|
||||
"win_flag": row.win_flag,
|
||||
"technical_score": row.technical_score,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
# 中标 → 补充 SUPPLIES 关系
|
||||
if row.win_flag and row.win_flag.upper() == "Y":
|
||||
rel2 = add_relationship(
|
||||
session, RelationshipType.SUPPLIES, supplier_entity, wo_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel2)
|
||||
|
||||
# 法人实体
|
||||
if row.legal_person:
|
||||
lp_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.LEGAL_PERSON,
|
||||
business_key=row.legal_person,
|
||||
display_name=row.legal_person,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
add_relationship(
|
||||
session, RelationshipType.LEGAL_REP_OF, lp_entity, supplier_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
|
||||
# 投标事件
|
||||
if row.bid_time:
|
||||
event = MetricEvent(
|
||||
event_time=row.bid_time,
|
||||
subject_type="work_order",
|
||||
subject_key=row.project_no,
|
||||
metric_name="bid_submitted",
|
||||
metric_value=row.bid_amount or 0.0,
|
||||
attributes={
|
||||
"bidder_key": row.bidder_key,
|
||||
"bidder_name": row.bidder_name,
|
||||
"win_flag": row.win_flag,
|
||||
"technical_score": row.technical_score,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class ProjectSignoffAdapter(BaseAdapter):
|
||||
"""SrcProjectSignoff → MetricEvent（工程签证/巡检时序）。"""
|
||||
|
||||
source_system = "WO"
|
||||
staging_table = "src_project_signoff"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcProjectSignoff)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcProjectSignoff.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# 确保工单实体存在
|
||||
upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.WORK_ORDER,
|
||||
business_key=row.project_no,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
|
||||
# 签证事件
|
||||
if row.signoff_date:
|
||||
event_time = dt.datetime.combine(
|
||||
row.signoff_date, dt.time.min, tzinfo=dt.timezone.utc
|
||||
)
|
||||
event = MetricEvent(
|
||||
event_time=event_time,
|
||||
subject_type="work_order",
|
||||
subject_key=row.project_no,
|
||||
metric_name="signoff_quantity",
|
||||
metric_value=row.signoff_quantity or 0.0,
|
||||
attributes={
|
||||
"work_order_no": row.work_order_no,
|
||||
"unit": row.unit,
|
||||
"resource_consumed": row.resource_consumed,
|
||||
"contractor_key": row.contractor_key,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
|
||||
# 巡检 GPS 事件
|
||||
if row.inspection_time and row.inspection_lat:
|
||||
event2 = MetricEvent(
|
||||
event_time=row.inspection_time,
|
||||
subject_type="work_order",
|
||||
subject_key=row.project_no,
|
||||
metric_name="inspection",
|
||||
metric_value=1.0,
|
||||
attributes={
|
||||
"lat": row.inspection_lat,
|
||||
"lng": row.inspection_lng,
|
||||
"work_order_no": row.work_order_no,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event2)
|
||||
result.metric_events.append(event2)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
@@ -0,0 +1,147 @@
|
||||
"""R13 适配器：互联互通与网间结算。
|
||||
|
||||
源明细：SrcCdr / SrcInterconnectSettlement
|
||||
映射到：Entity(MSISDN, SETTLEMENT) + MetricEvent
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime as dt
|
||||
import uuid
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.datahub.graph_repo import upsert_entity
|
||||
from app.datahub.models import MetricEvent
|
||||
from app.datahub.ontology import EntityType
|
||||
from app.datahub.staging import SrcCdr, SrcInterconnectSettlement
|
||||
from app.ingest.base import BaseAdapter, IngestResult
|
||||
from app.ingest.registry import register_adapter
|
||||
|
||||
|
||||
@register_adapter
|
||||
class CdrAdapter(BaseAdapter):
|
||||
"""SrcCdr → Entity(MSISDN) + MetricEvent（话务时序）。"""
|
||||
|
||||
source_system = "SIGNAL"
|
||||
staging_table = "src_cdr"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcCdr)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcCdr.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# 确保主被叫号码实体存在
|
||||
upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.MSISDN,
|
||||
business_key=row.caller,
|
||||
display_name=row.caller,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.MSISDN,
|
||||
business_key=row.callee,
|
||||
display_name=row.callee,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
|
||||
# 话务事件
|
||||
event = MetricEvent(
|
||||
event_time=row.start_time,
|
||||
subject_type="msisdn",
|
||||
subject_key=row.caller,
|
||||
metric_name="cdr_duration",
|
||||
metric_value=float(row.duration_sec),
|
||||
attributes={
|
||||
"callee": row.callee,
|
||||
"call_type": row.call_type,
|
||||
"peer_operator": row.peer_operator,
|
||||
"route_info": row.route_info,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class InterconnectSettlementAdapter(BaseAdapter):
|
||||
"""SrcInterconnectSettlement → Entity(SETTLEMENT) + MetricEvent。"""
|
||||
|
||||
source_system = "FIN"
|
||||
staging_table = "src_interconnect_settlement"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcInterconnectSettlement)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcInterconnectSettlement.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# 结算单实体
|
||||
settle_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.SETTLEMENT,
|
||||
business_key=row.settlement_no,
|
||||
display_name=f"网间结算-{row.settlement_no}",
|
||||
attributes={
|
||||
"peer_operator": row.peer_operator,
|
||||
"settle_type": row.settle_type,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(settle_entity)
|
||||
|
||||
# 结算时序事件
|
||||
try:
|
||||
event_time = dt.datetime.strptime(
|
||||
row.settle_period, "%Y-%m"
|
||||
).replace(tzinfo=dt.timezone.utc)
|
||||
except ValueError:
|
||||
event_time = dt.datetime.now(dt.timezone.utc)
|
||||
|
||||
event = MetricEvent(
|
||||
event_time=event_time,
|
||||
subject_type="settlement",
|
||||
subject_key=row.settlement_no,
|
||||
metric_name="interconnect_settle",
|
||||
metric_value=row.settle_amount,
|
||||
attributes={
|
||||
"peer_operator": row.peer_operator,
|
||||
"settle_type": row.settle_type,
|
||||
"volume": row.volume,
|
||||
"unit_price": row.unit_price,
|
||||
"sms_delivery_rate": row.sms_delivery_rate,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
@@ -0,0 +1,149 @@
|
||||
"""R14 适配器：云业务 / IDC 与新兴业务。
|
||||
|
||||
源明细：SrcCloudUsage / SrcIdcCabinet
|
||||
映射到：Entity(CONTRACT, CUSTOMER) + MetricEvent
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime as dt
|
||||
import uuid
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.datahub.graph_repo import upsert_entity
|
||||
from app.datahub.models import MetricEvent
|
||||
from app.datahub.ontology import EntityType
|
||||
from app.datahub.staging import SrcCloudUsage, SrcIdcCabinet
|
||||
from app.ingest.base import BaseAdapter, IngestResult
|
||||
from app.ingest.registry import register_adapter
|
||||
|
||||
|
||||
@register_adapter
|
||||
class CloudUsageAdapter(BaseAdapter):
|
||||
"""SrcCloudUsage → Entity(CONTRACT) + MetricEvent（云资源用量时序）。"""
|
||||
|
||||
source_system = "BSS"
|
||||
staging_table = "src_cloud_usage"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcCloudUsage)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcCloudUsage.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# 合同实体
|
||||
upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CONTRACT,
|
||||
business_key=row.contract_no,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
|
||||
# 客户实体（如有）
|
||||
if row.customer_key:
|
||||
upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CUSTOMER,
|
||||
business_key=row.customer_key,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
|
||||
# 云资源用量事件
|
||||
if row.usage_date:
|
||||
event_time = dt.datetime.combine(
|
||||
row.usage_date, dt.time.min, tzinfo=dt.timezone.utc
|
||||
)
|
||||
event = MetricEvent(
|
||||
event_time=event_time,
|
||||
subject_type="contract",
|
||||
subject_key=row.contract_no,
|
||||
metric_name="cloud_usage",
|
||||
metric_value=row.actual_usage,
|
||||
attributes={
|
||||
"resource_type": row.resource_type,
|
||||
"contracted_quota": row.contracted_quota,
|
||||
"billed_usage": row.billed_usage,
|
||||
"unit": row.unit,
|
||||
"customer_key": row.customer_key,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class IdcCabinetAdapter(BaseAdapter):
|
||||
"""SrcIdcCabinet → MetricEvent（IDC 机柜出租率/电力时序）。"""
|
||||
|
||||
source_system = "OSS"
|
||||
staging_table = "src_idc_cabinet"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcIdcCabinet)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcIdcCabinet.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# 合同实体（如有）
|
||||
if row.contract_no:
|
||||
upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CONTRACT,
|
||||
business_key=row.contract_no,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
|
||||
# IDC 出租/电力事件
|
||||
try:
|
||||
event_time = dt.datetime.strptime(
|
||||
row.report_month, "%Y-%m"
|
||||
).replace(tzinfo=dt.timezone.utc) if row.report_month else dt.datetime.now(dt.timezone.utc)
|
||||
except ValueError:
|
||||
event_time = dt.datetime.now(dt.timezone.utc)
|
||||
|
||||
event = MetricEvent(
|
||||
event_time=event_time,
|
||||
subject_type="contract",
|
||||
subject_key=row.contract_no or row.cabinet_id,
|
||||
metric_name="idc_cabinet",
|
||||
metric_value=row.occupancy_rate or 0.0,
|
||||
attributes={
|
||||
"cabinet_id": row.cabinet_id,
|
||||
"customer_key": row.customer_key,
|
||||
"power_kwh": row.power_kwh,
|
||||
"revenue_amount": row.revenue_amount,
|
||||
"acceptance_date": str(row.acceptance_date) if row.acceptance_date else None,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
@@ -0,0 +1,237 @@
|
||||
"""R15 适配器：员工内部舞弊与资源滥用。
|
||||
|
||||
源明细：SrcEmployeeOperation / SrcInternalMsisdn / SrcPointsTransaction
|
||||
映射到：Entity(EMPLOYEE, MSISDN) + 关系(OPERATES) + MetricEvent
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.datahub.graph_repo import add_relationship, upsert_entity
|
||||
from app.datahub.models import MetricEvent
|
||||
from app.datahub.ontology import EntityType, RelationshipType
|
||||
from app.datahub.staging import (
|
||||
SrcEmployeeOperation,
|
||||
SrcInternalMsisdn,
|
||||
SrcPointsTransaction,
|
||||
)
|
||||
from app.ingest.base import BaseAdapter, IngestResult
|
||||
from app.ingest.registry import register_adapter
|
||||
|
||||
|
||||
@register_adapter
|
||||
class EmployeeOperationAdapter(BaseAdapter):
|
||||
"""SrcEmployeeOperation → Entity(EMPLOYEE) + 关系(OPERATES) + MetricEvent。"""
|
||||
|
||||
source_system = "BSS"
|
||||
staging_table = "src_employee_operation"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcEmployeeOperation)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcEmployeeOperation.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# 员工实体
|
||||
emp_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.EMPLOYEE,
|
||||
business_key=row.employee_key,
|
||||
display_name=row.employee_name,
|
||||
attributes={
|
||||
"position": row.position,
|
||||
"department": row.department,
|
||||
"role_permissions": row.role_permissions,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(emp_entity)
|
||||
|
||||
# 操作目标 → OPERATES 关系（如操作对象是号码或账户）
|
||||
if row.operation_target:
|
||||
# 尝试识别操作目标类型（简单启发式：以1开头长度11为号码，否则为账户）
|
||||
target_key = row.operation_target.strip()
|
||||
if target_key.isdigit() and len(target_key) == 11:
|
||||
target_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.MSISDN,
|
||||
business_key=target_key,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.OPERATES, emp_entity, target_entity,
|
||||
attributes={"operation_type": row.operation_type},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
# 操作日志事件
|
||||
if row.operation_time:
|
||||
event = MetricEvent(
|
||||
event_time=row.operation_time,
|
||||
subject_type="employee",
|
||||
subject_key=row.employee_key,
|
||||
metric_name="operation_log",
|
||||
metric_value=1.0,
|
||||
attributes={
|
||||
"operation_type": row.operation_type,
|
||||
"operation_target": row.operation_target,
|
||||
"position": row.position,
|
||||
"department": row.department,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class InternalMsisdnAdapter(BaseAdapter):
|
||||
"""SrcInternalMsisdn → Entity(MSISDN, EMPLOYEE) + 关系(OPERATES) + MetricEvent。"""
|
||||
|
||||
source_system = "BSS"
|
||||
staging_table = "src_internal_msisdn"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcInternalMsisdn)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcInternalMsisdn.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# 内部号码实体
|
||||
msisdn_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.MSISDN,
|
||||
business_key=row.msisdn,
|
||||
display_name=row.msisdn,
|
||||
attributes={"purpose": row.purpose, "internal": True},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(msisdn_entity)
|
||||
|
||||
# 分配员工 → OPERATES 关系
|
||||
if row.assigned_employee:
|
||||
emp_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.EMPLOYEE,
|
||||
business_key=row.assigned_employee,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.OPERATES, emp_entity, msisdn_entity,
|
||||
attributes={"purpose": row.purpose},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
# 内部号用量事件
|
||||
import datetime as dt
|
||||
|
||||
try:
|
||||
event_time = dt.datetime.strptime(
|
||||
row.report_month, "%Y-%m"
|
||||
).replace(tzinfo=dt.timezone.utc) if row.report_month else dt.datetime.now(dt.timezone.utc)
|
||||
except ValueError:
|
||||
event_time = dt.datetime.now(dt.timezone.utc)
|
||||
|
||||
event = MetricEvent(
|
||||
event_time=event_time,
|
||||
subject_type="msisdn",
|
||||
subject_key=row.msisdn,
|
||||
metric_name="internal_usage",
|
||||
metric_value=row.traffic_mb,
|
||||
attributes={
|
||||
"voice_min": row.voice_min,
|
||||
"revenue_attributed": row.revenue_attributed,
|
||||
"assigned_employee": row.assigned_employee,
|
||||
"purpose": row.purpose,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class PointsTransactionAdapter(BaseAdapter):
|
||||
"""SrcPointsTransaction → MetricEvent（积分发放/兑换时序）。"""
|
||||
|
||||
source_system = "BSS"
|
||||
staging_table = "src_points_transaction"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcPointsTransaction)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcPointsTransaction.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# 确保操作人实体存在
|
||||
upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.EMPLOYEE,
|
||||
business_key=row.operator_key,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
|
||||
# 积分事件
|
||||
if row.transaction_time:
|
||||
event = MetricEvent(
|
||||
event_time=row.transaction_time,
|
||||
subject_type="employee",
|
||||
subject_key=row.operator_key,
|
||||
metric_name="points_transaction",
|
||||
metric_value=row.points_amount,
|
||||
attributes={
|
||||
"transaction_no": row.transaction_no,
|
||||
"target_account": row.target_account,
|
||||
"transaction_type": row.transaction_type,
|
||||
"cash_value": row.cash_value,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
@@ -0,0 +1,236 @@
|
||||
"""R8 适配器：政企收入全链路穿透 / 拆单规避。
|
||||
|
||||
源明细：SrcContract / SrcContractApproval / SrcPayment
|
||||
映射到：Entity(CONTRACT, CUSTOMER, ACCOUNT, ADDRESS, LEGAL_PERSON) + 关系 + MetricEvent
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.datahub.graph_repo import add_relationship, upsert_entity
|
||||
from app.datahub.models import MetricEvent
|
||||
from app.datahub.ontology import EntityType, RelationshipType
|
||||
from app.datahub.staging import SrcContract, SrcContractApproval, SrcPayment
|
||||
from app.ingest.base import BaseAdapter, IngestResult
|
||||
from app.ingest.registry import register_adapter
|
||||
|
||||
|
||||
@register_adapter
|
||||
class ContractAdapter(BaseAdapter):
|
||||
"""SrcContract → Entity(CONTRACT, CUSTOMER, ACCOUNT, ADDRESS, LEGAL_PERSON) + 关系。"""
|
||||
|
||||
source_system = "CONTRACT"
|
||||
staging_table = "src_contract"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcContract)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcContract.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# 合同实体
|
||||
contract_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CONTRACT,
|
||||
business_key=row.contract_no,
|
||||
display_name=f"合同-{row.contract_no}",
|
||||
attributes={
|
||||
"amount": row.amount,
|
||||
"sign_date": str(row.sign_date) if row.sign_date else None,
|
||||
"approval_threshold": row.approval_threshold,
|
||||
"approval_level": row.approval_level,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(contract_entity)
|
||||
|
||||
# 客户实体 + 签约关系
|
||||
cust_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CUSTOMER,
|
||||
business_key=row.customer_key,
|
||||
display_name=row.customer_name,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(cust_entity)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.SIGNED, cust_entity, contract_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
# 回款账户 → Entity(ACCOUNT) + 关系 PAID_BY
|
||||
if row.pay_account:
|
||||
acct_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.ACCOUNT,
|
||||
business_key=row.pay_account,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(acct_entity)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.PAID_BY, contract_entity, acct_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
# 注册地址
|
||||
if row.register_address:
|
||||
addr_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.ADDRESS,
|
||||
business_key=row.register_address,
|
||||
display_name=row.register_address,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.REGISTERED_AT, cust_entity, addr_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
# 法人
|
||||
if row.legal_person:
|
||||
lp_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.LEGAL_PERSON,
|
||||
business_key=row.legal_person,
|
||||
display_name=row.legal_person,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.LEGAL_REP_OF, lp_entity, cust_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class ContractApprovalAdapter(BaseAdapter):
|
||||
"""SrcContractApproval → MetricEvent（审批时序事件）。"""
|
||||
|
||||
source_system = "CONTRACT"
|
||||
staging_table = "src_contract_approval"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcContractApproval)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcContractApproval.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
if row.approval_time:
|
||||
event = MetricEvent(
|
||||
event_time=row.approval_time,
|
||||
subject_type="contract",
|
||||
subject_key=row.contract_no,
|
||||
metric_name="approval_step",
|
||||
metric_value=float(row.approval_step),
|
||||
attributes={
|
||||
"approver": row.approver,
|
||||
"result": row.approval_result,
|
||||
"remark": row.remark,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class PaymentAdapter(BaseAdapter):
|
||||
"""SrcPayment → MetricEvent（回款时序事件） + 关系补强。"""
|
||||
|
||||
source_system = "FIN"
|
||||
staging_table = "src_payment"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcPayment)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcPayment.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
if row.pay_date:
|
||||
import datetime as dt
|
||||
|
||||
event_time = dt.datetime.combine(
|
||||
row.pay_date, dt.time.min, tzinfo=dt.timezone.utc
|
||||
)
|
||||
event = MetricEvent(
|
||||
event_time=event_time,
|
||||
subject_type="contract",
|
||||
subject_key=row.contract_no,
|
||||
metric_name="payment",
|
||||
metric_value=row.pay_amount,
|
||||
attributes={
|
||||
"pay_account": row.pay_account,
|
||||
"pay_type": row.pay_type,
|
||||
"overdue_flag": row.overdue_flag,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
|
||||
# 强化合同→账户关系
|
||||
if row.pay_account:
|
||||
contract_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CONTRACT,
|
||||
business_key=row.contract_no,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
acct_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.ACCOUNT,
|
||||
business_key=row.pay_account,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.PAID_BY, contract_entity, acct_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
@@ -0,0 +1,184 @@
|
||||
"""R9 适配器：市场业务真实性 / 养卡骗补。
|
||||
|
||||
源明细：SrcChannelMonthly / SrcSubscription
|
||||
映射到：Entity(CHANNEL, MSISDN) + 关系(BELONGS_TO_CHANNEL, SUBSCRIBES) + MetricEvent
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime as dt
|
||||
import uuid
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.datahub.graph_repo import add_relationship, upsert_entity
|
||||
from app.datahub.models import MetricEvent
|
||||
from app.datahub.ontology import EntityType, RelationshipType
|
||||
from app.datahub.staging import SrcChannelMonthly, SrcSubscription
|
||||
from app.ingest.base import BaseAdapter, IngestResult
|
||||
from app.ingest.registry import register_adapter
|
||||
|
||||
|
||||
@register_adapter
|
||||
class ChannelMonthlyAdapter(BaseAdapter):
|
||||
"""SrcChannelMonthly → MetricEvent（渠道月度留存/佣金时序）。"""
|
||||
|
||||
source_system = "BSS"
|
||||
staging_table = "src_channel_monthly"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcChannelMonthly)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcChannelMonthly.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# 确保渠道实体存在
|
||||
upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CHANNEL,
|
||||
business_key=row.channel_key,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
|
||||
# cohort_label 如 "2025-01" → 转为时间
|
||||
try:
|
||||
event_time = dt.datetime.strptime(
|
||||
row.cohort_label, "%Y-%m"
|
||||
).replace(tzinfo=dt.timezone.utc)
|
||||
except ValueError:
|
||||
event_time = dt.datetime.now(dt.timezone.utc)
|
||||
|
||||
# 留存率事件
|
||||
event = MetricEvent(
|
||||
event_time=event_time,
|
||||
subject_type="channel",
|
||||
subject_key=row.channel_key,
|
||||
metric_name="retention",
|
||||
metric_value=row.retained / row.cohort_size if row.cohort_size > 0 else 0.0,
|
||||
attributes={
|
||||
"cohort_label": row.cohort_label,
|
||||
"month_index": row.month_index,
|
||||
"cohort_size": row.cohort_size,
|
||||
"retained": row.retained,
|
||||
"commission_paid": row.commission_paid,
|
||||
"active_ratio": row.active_ratio,
|
||||
"zero_usage_ratio": row.zero_usage_ratio,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
|
||||
|
||||
@register_adapter
|
||||
class SubscriptionAdapter(BaseAdapter):
|
||||
"""SrcSubscription → Entity(MSISDN) + 关系(BELONGS_TO_CHANNEL, SUBSCRIBES) + MetricEvent。"""
|
||||
|
||||
source_system = "BSS"
|
||||
staging_table = "src_subscription"
|
||||
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
result = IngestResult()
|
||||
query = session.query(SrcSubscription)
|
||||
if data_version_id:
|
||||
query = query.filter(SrcSubscription.data_version_id == data_version_id)
|
||||
rows = query.limit(batch_size).all()
|
||||
|
||||
for row in rows:
|
||||
try:
|
||||
# MSISDN 实体
|
||||
msisdn_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.MSISDN,
|
||||
business_key=row.msisdn,
|
||||
display_name=row.msisdn,
|
||||
attributes={"region": row.region},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.entities.append(msisdn_entity)
|
||||
|
||||
# 渠道归属关系
|
||||
if row.channel_key:
|
||||
chan_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CHANNEL,
|
||||
business_key=row.channel_key,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.BELONGS_TO_CHANNEL, msisdn_entity, chan_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
# 订购关系（号码→合同/产品）
|
||||
if row.product_code:
|
||||
contract_entity = upsert_entity(
|
||||
session,
|
||||
entity_type=EntityType.CONTRACT,
|
||||
business_key=row.product_code,
|
||||
display_name=f"产品-{row.product_code}",
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
rel = add_relationship(
|
||||
session, RelationshipType.SUBSCRIBES, msisdn_entity, contract_entity,
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
result.relationships.append(rel)
|
||||
|
||||
# 订购/退订时序事件
|
||||
if row.subscribe_time:
|
||||
event = MetricEvent(
|
||||
event_time=row.subscribe_time,
|
||||
subject_type="msisdn",
|
||||
subject_key=row.msisdn,
|
||||
metric_name="subscribe",
|
||||
metric_value=1.0,
|
||||
attributes={
|
||||
"channel_key": row.channel_key,
|
||||
"product_code": row.product_code,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
|
||||
if row.unsubscribe_time:
|
||||
event = MetricEvent(
|
||||
event_time=row.unsubscribe_time,
|
||||
subject_type="msisdn",
|
||||
subject_key=row.msisdn,
|
||||
metric_name="unsubscribe",
|
||||
metric_value=-1.0,
|
||||
attributes={
|
||||
"channel_key": row.channel_key,
|
||||
"product_code": row.product_code,
|
||||
},
|
||||
data_version_id=data_version_id,
|
||||
)
|
||||
session.add(event)
|
||||
result.metric_events.append(event)
|
||||
|
||||
result.row_count += 1
|
||||
except Exception:
|
||||
result.error_count += 1
|
||||
|
||||
return result
|
||||
@@ -0,0 +1,53 @@
|
||||
"""接入适配器基类与通用数据结构。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
from abc import ABC, abstractmethod
|
||||
from dataclasses import dataclass, field
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.datahub.models import Entity, EntityRelationship, MetricEvent
|
||||
|
||||
|
||||
@dataclass
|
||||
class IngestResult:
|
||||
"""单次适配器执行的输出汇总。"""
|
||||
|
||||
entities: list[Entity] = field(default_factory=list)
|
||||
relationships: list[EntityRelationship] = field(default_factory=list)
|
||||
metric_events: list[MetricEvent] = field(default_factory=list)
|
||||
row_count: int = 0
|
||||
error_count: int = 0
|
||||
|
||||
|
||||
class BaseAdapter(ABC):
|
||||
"""接入适配器抽象基类。
|
||||
|
||||
每个源明细表实现一个子类，负责将 staging 行映射到本体层。
|
||||
"""
|
||||
|
||||
# 子类须指定所适配的源系统标识（如 "BSS", "ERP"）
|
||||
source_system: str = ""
|
||||
# 子类须指定所适配的 staging 表名
|
||||
staging_table: str = ""
|
||||
|
||||
@abstractmethod
|
||||
def ingest(
|
||||
self,
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
"""从 staging 表读取未处理行，映射写入本体层。
|
||||
|
||||
Args:
|
||||
session: 数据库会话
|
||||
data_version_id: 当前批次的数据版本 ID
|
||||
batch_size: 每批处理行数
|
||||
|
||||
Returns:
|
||||
IngestResult 汇总
|
||||
"""
|
||||
...
|
||||
@@ -0,0 +1,22 @@
|
||||
"""适配器注册表：按 staging 表名索引，便于调度器统一调用。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Type
|
||||
|
||||
from app.ingest.base import BaseAdapter
|
||||
|
||||
# 全局注册表：staging_table -> Adapter 类
|
||||
ADAPTER_REGISTRY: dict[str, Type[BaseAdapter]] = {}
|
||||
|
||||
|
||||
def register_adapter(cls: Type[BaseAdapter]) -> Type[BaseAdapter]:
|
||||
"""类装饰器：将 Adapter 注册到全局表。"""
|
||||
if cls.staging_table:
|
||||
ADAPTER_REGISTRY[cls.staging_table] = cls
|
||||
return cls
|
||||
|
||||
|
||||
def get_adapter(staging_table: str) -> Type[BaseAdapter] | None:
|
||||
"""按 staging 表名查找已注册的适配器类。"""
|
||||
return ADAPTER_REGISTRY.get(staging_table)
|
||||
@@ -0,0 +1,89 @@
|
||||
"""接入适配器调度器：统一驱动全部 Adapter 执行 staging → 本体映射。
|
||||
|
||||
用法：
|
||||
from app.ingest.runner import run_all_adapters
|
||||
results = run_all_adapters(session, data_version_id)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
import uuid
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.ingest.base import IngestResult
|
||||
from app.ingest.registry import ADAPTER_REGISTRY
|
||||
|
||||
# 确保所有适配器模块被导入，触发 @register_adapter 注册
|
||||
import app.ingest.adapters_master # noqa: F401
|
||||
import app.ingest.adapters_r8 # noqa: F401
|
||||
import app.ingest.adapters_r9 # noqa: F401
|
||||
import app.ingest.adapters_r10 # noqa: F401
|
||||
import app.ingest.adapters_r11 # noqa: F401
|
||||
import app.ingest.adapters_r12 # noqa: F401
|
||||
import app.ingest.adapters_r13 # noqa: F401
|
||||
import app.ingest.adapters_r14 # noqa: F401
|
||||
import app.ingest.adapters_r15 # noqa: F401
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def run_all_adapters(
|
||||
session: Session,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
tables: list[str] | None = None,
|
||||
) -> dict[str, IngestResult]:
|
||||
"""执行全部（或指定的）适配器，返回 {staging_table: IngestResult}。
|
||||
|
||||
Args:
|
||||
session: 数据库会话（调用方负责 commit/rollback）
|
||||
data_version_id: 当前批次数据版本 ID
|
||||
batch_size: 每个适配器单次处理行数上限
|
||||
tables: 若指定，仅执行这些 staging 表对应的适配器；为 None 时执行全部
|
||||
|
||||
Returns:
|
||||
各适配器的执行结果字典
|
||||
"""
|
||||
results: dict[str, IngestResult] = {}
|
||||
|
||||
target_adapters = ADAPTER_REGISTRY
|
||||
if tables:
|
||||
target_adapters = {k: v for k, v in ADAPTER_REGISTRY.items() if k in tables}
|
||||
|
||||
for table_name, adapter_cls in target_adapters.items():
|
||||
logger.info("Running adapter: %s (%s)", adapter_cls.__name__, table_name)
|
||||
adapter = adapter_cls()
|
||||
try:
|
||||
result = adapter.ingest(
|
||||
session, data_version_id=data_version_id, batch_size=batch_size
|
||||
)
|
||||
results[table_name] = result
|
||||
logger.info(
|
||||
" → rows=%d, entities=%d, rels=%d, events=%d, errors=%d",
|
||||
result.row_count,
|
||||
len(result.entities),
|
||||
len(result.relationships),
|
||||
len(result.metric_events),
|
||||
result.error_count,
|
||||
)
|
||||
except Exception as exc:
|
||||
logger.error("Adapter %s failed: %s", table_name, exc)
|
||||
results[table_name] = IngestResult(error_count=1)
|
||||
|
||||
return results
|
||||
|
||||
|
||||
def run_adapter(
|
||||
session: Session,
|
||||
staging_table: str,
|
||||
data_version_id: uuid.UUID | None = None,
|
||||
batch_size: int = 1000,
|
||||
) -> IngestResult:
|
||||
"""执行单个指定 staging 表的适配器。"""
|
||||
adapter_cls = ADAPTER_REGISTRY.get(staging_table)
|
||||
if adapter_cls is None:
|
||||
raise ValueError(f"未找到 staging 表 '{staging_table}' 对应的适配器")
|
||||
adapter = adapter_cls()
|
||||
return adapter.ingest(session, data_version_id=data_version_id, batch_size=batch_size)
|
||||
@@ -4,7 +4,7 @@ from __future__ import annotations
|
||||
|
||||
from app.config import EGRESS_PROVIDERS, LLMProviderName, Settings, get_settings
|
||||
from app.llm.base import LLMProvider
|
||||
from app.llm.providers import DashScopeProvider, VllmProvider
|
||||
from app.llm.providers import DashScopeProvider, MockProvider, VllmProvider
|
||||
|
||||
|
||||
class EgressPolicyError(RuntimeError):
|
||||
@@ -27,5 +27,7 @@ def get_llm_provider(settings: Settings | None = None) -> LLMProvider:
|
||||
)
|
||||
if settings.llm_provider == LLMProviderName.vllm:
|
||||
return VllmProvider(base_url=settings.vllm_base_url, model=settings.vllm_model)
|
||||
if settings.llm_provider == LLMProviderName.mock:
|
||||
return MockProvider()
|
||||
|
||||
raise ValueError(f"未知的 LLM Provider: {settings.llm_provider}")
|
||||
|
||||
@@ -78,3 +78,31 @@ class VllmProvider(LLMProvider):
|
||||
return resp.status_code == 200
|
||||
except httpx.HTTPError:
|
||||
return False
|
||||
|
||||
|
||||
class MockProvider(LLMProvider):
|
||||
"""本地确定性 Mock Provider：开发/测试用，不出域、不依赖外网。
|
||||
|
||||
返回可预测的回显内容，便于在无 API Key / 无 GPU 时打通链路与自动化测试。
|
||||
"""
|
||||
|
||||
name = "mock"
|
||||
egress = False
|
||||
|
||||
def __init__(self, model: str = "mock-llm") -> None:
|
||||
self._model = model
|
||||
|
||||
def chat(self, messages: list[ChatMessage], **kwargs) -> LLMResponse:
|
||||
last_user = next(
|
||||
(m.content for m in reversed(messages) if m.role == "user"), ""
|
||||
)
|
||||
return LLMResponse(
|
||||
content=f"[mock] 收到查询：{last_user}",
|
||||
model=self._model,
|
||||
provider=self.name,
|
||||
egress=False,
|
||||
raw={"echo": last_user},
|
||||
)
|
||||
|
||||
def health(self) -> bool:
|
||||
return True
|
||||
|
||||
@@ -7,7 +7,9 @@ from contextlib import asynccontextmanager
|
||||
from fastapi import FastAPI
|
||||
|
||||
from app import __version__
|
||||
from app.api.clues import router as clues_router
|
||||
from app.api.datahub import router as datahub_router
|
||||
from app.api.nlq import router as nlq_router
|
||||
from app.config import get_settings
|
||||
|
||||
|
||||
@@ -26,6 +28,8 @@ app = FastAPI(
|
||||
)
|
||||
|
||||
app.include_router(datahub_router)
|
||||
app.include_router(clues_router)
|
||||
app.include_router(nlq_router)
|
||||
|
||||
|
||||
@app.get("/health")
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
"""自然语言查询（NLQ）：审计员零门槛用自然语言查数/获取线索（R4/R20）。"""
|
||||
@@ -0,0 +1,106 @@
|
||||
"""自然语言查询服务。
|
||||
|
||||
采用"结构化意图优先 + LLM 兜底"策略：
|
||||
- 若问题命中线索检索意图（置信度/场景/状态/列出线索等），直接查审计数据库返回真实结果，
|
||||
实现"数据找人"，不依赖外部模型，数据不出域。
|
||||
- 其余开放性问题再交给 LLMProvider（本地优先）。
|
||||
对应 R4 / R20 / R7。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.clues import service as clue_svc
|
||||
from app.clues.models import ClueStatus, ConfidenceTier
|
||||
from app.llm import ChatMessage, get_llm_provider
|
||||
|
||||
SYSTEM_PROMPT = (
|
||||
"你是电信运营商内部审计助手。基于审计数据中台的数据回答问题，"
|
||||
"给出可解释的依据；无证据支撑时明确说明，不臆造数据。"
|
||||
)
|
||||
|
||||
# 关键词 → 过滤条件映射
|
||||
_CONFIDENCE_KW = {"高置信": ConfidenceTier.HIGH, "高风险": ConfidenceTier.HIGH,
|
||||
"中置信": ConfidenceTier.MEDIUM, "低置信": ConfidenceTier.LOW}
|
||||
_SCENARIO_KW = {"拆单": "R8", "政企": "R8", "养卡": "R9", "骗补": "R9", "彩铃": "R9"}
|
||||
_STATUS_KW = {"待处理": ClueStatus.NEW, "已分派": ClueStatus.ASSIGNED,
|
||||
"研判": ClueStatus.REVIEWING, "属实": ClueStatus.CONFIRMED,
|
||||
"误报": ClueStatus.DISMISSED, "已销项": ClueStatus.CLOSED}
|
||||
_LIST_KW = ("线索", "列出", "查", "有哪些", "多少", "列表", "看看", "显示")
|
||||
|
||||
_SCENARIO_NAME = {"R8": "政企拆单", "R9": "养卡骗补"}
|
||||
_CONF_NAME = {ConfidenceTier.HIGH: "高置信", ConfidenceTier.MEDIUM: "中置信",
|
||||
ConfidenceTier.LOW: "低置信"}
|
||||
|
||||
|
||||
@dataclass
|
||||
class NLQAnswer:
|
||||
question: str
|
||||
answer: str
|
||||
provider: str
|
||||
model: str
|
||||
egress: bool
|
||||
|
||||
|
||||
def _match_first(question: str, mapping: dict):
|
||||
for kw, val in mapping.items():
|
||||
if kw in question:
|
||||
return val
|
||||
return None
|
||||
|
||||
|
||||
def _is_clue_query(question: str) -> bool:
|
||||
return any(kw in question for kw in _LIST_KW) or any(
|
||||
kw in question for kw in {**_CONFIDENCE_KW, **_SCENARIO_KW, **_STATUS_KW}
|
||||
)
|
||||
|
||||
|
||||
def _format_clue_answer(question: str, clues: list) -> str:
|
||||
if not clues:
|
||||
return "未检索到符合条件的线索。可调整筛选条件，或先运行扫描生成线索。"
|
||||
lines = [f"共检索到 {len(clues)} 条线索："]
|
||||
for i, c in enumerate(clues, 1):
|
||||
amount = f"，涉及金额约 {c.amount_involved/10000:.1f} 万元" if c.amount_involved else ""
|
||||
lines.append(
|
||||
f"{i}. [{_SCENARIO_NAME.get(c.scenario_code, c.scenario_code)}] {c.title}"
|
||||
f"（{_CONF_NAME.get(c.confidence, c.confidence.value)}，评分 {c.score:.2f}{amount}）"
|
||||
f"——{c.rationale}"
|
||||
)
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def ask(question: str, session: Session | None = None) -> NLQAnswer:
|
||||
"""处理一次自然语言查询：优先结构化检索，其余交给 LLM。"""
|
||||
# 结构化意图：检索线索（数据找人，不出域）
|
||||
if session is not None and _is_clue_query(question):
|
||||
confidence = _match_first(question, _CONFIDENCE_KW)
|
||||
scenario = _match_first(question, _SCENARIO_KW)
|
||||
status = _match_first(question, _STATUS_KW)
|
||||
clues = clue_svc.list_clues(
|
||||
session, status=status, scenario_code=scenario, confidence=confidence
|
||||
)
|
||||
return NLQAnswer(
|
||||
question=question,
|
||||
answer=_format_clue_answer(question, clues),
|
||||
provider="datahub",
|
||||
model="结构化检索",
|
||||
egress=False,
|
||||
)
|
||||
|
||||
# 开放性问题：交给 LLM（本地优先）
|
||||
provider = get_llm_provider()
|
||||
messages = [
|
||||
ChatMessage(role="system", content=SYSTEM_PROMPT),
|
||||
ChatMessage(role="user", content=question),
|
||||
]
|
||||
resp = provider.chat(messages)
|
||||
return NLQAnswer(
|
||||
question=question,
|
||||
answer=resp.content,
|
||||
provider=resp.provider,
|
||||
model=resp.model,
|
||||
egress=resp.egress,
|
||||
)
|
||||
@@ -0,0 +1 @@
|
||||
"""审计场景检测器：将业务数据中的异常模式转化为线索。"""
|
||||
@@ -0,0 +1,85 @@
|
||||
"""场景二 · 市场业务真实性：养卡骗补检测（R9）。
|
||||
|
||||
检测"脉冲式增长 + 规律性衰减"的周期性造假：渠道每月新增大量用户订购，
|
||||
固定周期后这些用户集中退订（骗补后弃养）。结合佣金与业务质量匹配度。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
|
||||
|
||||
@dataclass
|
||||
class CohortPoint:
|
||||
"""某新增批次（cohort）在第 N 个月的留存率。"""
|
||||
|
||||
month_index: int
|
||||
retention: float # 0-1
|
||||
|
||||
|
||||
@dataclass
|
||||
class ChurnFinding:
|
||||
cliff_month: int | None
|
||||
max_drop: float
|
||||
pulse_then_decay: bool
|
||||
|
||||
|
||||
def detect_pulse_decay(
|
||||
retention_curve: list[CohortPoint],
|
||||
cliff_drop: float = 0.5,
|
||||
) -> ChurnFinding:
|
||||
"""识别留存曲线中的"断崖式集中退订"。
|
||||
|
||||
若某月留存相对上月骤降超过 cliff_drop（默认 50%），判为规律性衰减。
|
||||
"""
|
||||
ordered = sorted(retention_curve, key=lambda p: p.month_index)
|
||||
max_drop = 0.0
|
||||
cliff_month: int | None = None
|
||||
for prev, cur in zip(ordered, ordered[1:], strict=False):
|
||||
drop = prev.retention - cur.retention
|
||||
if drop > max_drop:
|
||||
max_drop = drop
|
||||
if drop >= cliff_drop:
|
||||
cliff_month = cur.month_index
|
||||
return ChurnFinding(
|
||||
cliff_month=cliff_month,
|
||||
max_drop=round(max_drop, 3),
|
||||
pulse_then_decay=cliff_month is not None,
|
||||
)
|
||||
|
||||
|
||||
def commission_quality_mismatch(
|
||||
commission_paid: float,
|
||||
active_ratio: float,
|
||||
zero_usage_ratio: float,
|
||||
) -> float:
|
||||
"""佣金与业务质量不匹配度（0-1）。
|
||||
|
||||
active_ratio：仍活跃用户占比；zero_usage_ratio：零通话/零流量用户占比。
|
||||
佣金已发但活跃低、零使用高 → 不匹配度高。
|
||||
"""
|
||||
if commission_paid <= 0:
|
||||
return 0.0
|
||||
mismatch = 0.6 * zero_usage_ratio + 0.4 * (1 - active_ratio)
|
||||
return round(min(max(mismatch, 0.0), 1.0), 3)
|
||||
|
||||
|
||||
def churn_risk_score(finding: ChurnFinding, mismatch: float) -> float:
|
||||
"""综合评分：断崖退订 + 佣金质量不匹配。"""
|
||||
if not finding.pulse_then_decay:
|
||||
return round(0.3 * mismatch, 3)
|
||||
base = 0.4 + 0.4 * finding.max_drop + 0.2 * mismatch
|
||||
return round(min(base, 1.0), 3)
|
||||
|
||||
|
||||
def build_rationale(finding: ChurnFinding, mismatch: float) -> str:
|
||||
if finding.pulse_then_decay:
|
||||
return (
|
||||
f"渠道新增用户在第 {finding.cliff_month} 个月出现断崖式集中退订"
|
||||
f"（最大单月留存骤降 {finding.max_drop:.0%}），呈"
|
||||
f"'脉冲式增长 + 规律性衰减'特征；佣金与业务质量不匹配度 {mismatch:.0%}，"
|
||||
f"高度疑似养卡骗补（骗补后弃养）。"
|
||||
)
|
||||
return (
|
||||
f"未见明显断崖退订，但佣金与业务质量不匹配度为 {mismatch:.0%}，建议关注。"
|
||||
)
|
||||
@@ -0,0 +1,78 @@
|
||||
"""场景一 · 政企收入全链路穿透：拆单规避检测（R8）。
|
||||
|
||||
检测点：
|
||||
1. 合同金额集中分布在审批阈值边缘（如阈值 80% 以上但不超阈值）。
|
||||
2. 结合知识图谱穿透识别隐性实控人（多个客户经法人关联到同一实控人）。
|
||||
满足上述模式则生成线索，附证据链与人话理由。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
|
||||
|
||||
@dataclass
|
||||
class ContractRecord:
|
||||
"""穿透分析输入：一份合同的关键信息。"""
|
||||
|
||||
contract_id: str
|
||||
customer_key: str
|
||||
amount: float
|
||||
|
||||
|
||||
@dataclass
|
||||
class SplitFinding:
|
||||
"""拆单检测结果。"""
|
||||
|
||||
near_threshold: list[ContractRecord] = field(default_factory=list)
|
||||
ratio: float = 0.0
|
||||
total_amount: float = 0.0
|
||||
|
||||
@property
|
||||
def hit(self) -> bool:
|
||||
return len(self.near_threshold) >= 3
|
||||
|
||||
|
||||
def detect_threshold_edge(
|
||||
contracts: list[ContractRecord],
|
||||
approval_threshold: float,
|
||||
edge_ratio: float = 0.8,
|
||||
) -> SplitFinding:
|
||||
"""识别金额集中在审批阈值边缘 [edge_ratio*阈值, 阈值) 的合同。
|
||||
|
||||
这类"刚好低于阈值"的批量合同是典型的拆单规避特征。
|
||||
"""
|
||||
if approval_threshold <= 0:
|
||||
raise ValueError("审批阈值必须为正数")
|
||||
lower = edge_ratio * approval_threshold
|
||||
near = [c for c in contracts if lower <= c.amount < approval_threshold]
|
||||
finding = SplitFinding(
|
||||
near_threshold=near,
|
||||
ratio=(len(near) / len(contracts)) if contracts else 0.0,
|
||||
total_amount=sum(c.amount for c in near),
|
||||
)
|
||||
return finding
|
||||
|
||||
|
||||
def split_risk_score(finding: SplitFinding, shared_controller: bool) -> float:
|
||||
"""综合评分：阈值边缘集中度 + 是否穿透到同一实控人。"""
|
||||
if not finding.hit:
|
||||
return 0.0
|
||||
base = min(0.6, 0.1 * len(finding.near_threshold)) # 数量越多越可疑
|
||||
base += 0.2 * finding.ratio
|
||||
if shared_controller:
|
||||
base += 0.3 # 同一实控人是强证据
|
||||
return round(min(base, 1.0), 3)
|
||||
|
||||
|
||||
def build_rationale(finding: SplitFinding, threshold: float, shared_controller: bool) -> str:
|
||||
parts = [
|
||||
f"检测到 {len(finding.near_threshold)} 份合同金额集中在审批阈值 "
|
||||
f"{threshold:.0f} 的边缘区间（占比 {finding.ratio:.0%}），",
|
||||
f"边缘合同金额合计约 {finding.total_amount:.0f}。",
|
||||
]
|
||||
if shared_controller:
|
||||
parts.append("且经工商关联穿透，相关客户疑似同属一个隐性实控人，高度符合拆单规避特征。")
|
||||
else:
|
||||
parts.append("建议进一步穿透客户关联关系以确认是否同一实控人。")
|
||||
return "".join(parts)
|
||||
@@ -16,6 +16,7 @@ from app.config import get_settings
|
||||
|
||||
# 导入模型以注册到 Base.metadata
|
||||
from app.datahub import models # noqa: F401,E402
|
||||
from app.datahub import staging # noqa: F401,E402
|
||||
from app.db import Base
|
||||
|
||||
config = context.config
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
"""源明细落地层：src_contract / src_channel_monthly
|
||||
|
||||
Revision ID: 0003_staging
|
||||
Revises: 0002_clues_audit
|
||||
Create Date: 2026-06
|
||||
"""
|
||||
from typing import Sequence, Union
|
||||
|
||||
import sqlalchemy as sa
|
||||
from alembic import op
|
||||
from sqlalchemy.dialects import postgresql
|
||||
|
||||
revision: str = "0003_staging"
|
||||
down_revision: Union[str, None] = "0002_clues_audit"
|
||||
branch_labels: Union[str, Sequence[str], None] = None
|
||||
depends_on: Union[str, Sequence[str], None] = None
|
||||
|
||||
|
||||
def upgrade() -> None:
|
||||
op.create_table(
|
||||
"src_contract",
|
||||
sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
|
||||
sa.Column("contract_no", sa.String(64), nullable=False),
|
||||
sa.Column("customer_key", sa.String(64), nullable=False),
|
||||
sa.Column("customer_name", sa.String(256), nullable=True),
|
||||
sa.Column("amount", sa.Float(), nullable=False),
|
||||
sa.Column("sign_date", sa.Date(), nullable=True),
|
||||
sa.Column("approval_threshold", sa.Float(), nullable=True),
|
||||
sa.Column("approval_level", sa.String(32), nullable=True),
|
||||
sa.Column("legal_person", sa.String(128), nullable=True),
|
||||
sa.Column("register_address", sa.String(256), nullable=True),
|
||||
sa.Column("pay_account", sa.String(64), nullable=True),
|
||||
sa.Column("data_version_id", postgresql.UUID(as_uuid=True), nullable=True),
|
||||
sa.Column("ingested_at", sa.DateTime(timezone=True), nullable=False),
|
||||
)
|
||||
op.create_index("ix_src_contract_customer", "src_contract", ["customer_key"])
|
||||
|
||||
op.create_table(
|
||||
"src_channel_monthly",
|
||||
sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
|
||||
sa.Column("channel_key", sa.String(64), nullable=False),
|
||||
sa.Column("cohort_label", sa.String(32), nullable=False),
|
||||
sa.Column("month_index", sa.Integer(), nullable=False),
|
||||
sa.Column("cohort_size", sa.Integer(), nullable=False, server_default="0"),
|
||||
sa.Column("retained", sa.Integer(), nullable=False, server_default="0"),
|
||||
sa.Column("commission_paid", sa.Float(), nullable=False, server_default="0"),
|
||||
sa.Column("active_ratio", sa.Float(), nullable=False, server_default="0"),
|
||||
sa.Column("zero_usage_ratio", sa.Float(), nullable=False, server_default="0"),
|
||||
sa.Column("data_version_id", postgresql.UUID(as_uuid=True), nullable=True),
|
||||
sa.Column("ingested_at", sa.DateTime(timezone=True), nullable=False),
|
||||
)
|
||||
op.create_index("ix_src_channel_key", "src_channel_monthly", ["channel_key"])
|
||||
|
||||
|
||||
def downgrade() -> None:
|
||||
op.drop_table("src_channel_monthly")
|
||||
op.drop_table("src_contract")
|
||||
@@ -0,0 +1,53 @@
|
||||
"""生成演示数据：跑两个场景扫描，落库若干线索，供前端看板演示。
|
||||
|
||||
用法：python -m scripts.seed_demo
|
||||
仅用于本地演示，使用脱敏/虚构数据，不涉及真实业务数据。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from app.db import get_sessionmaker
|
||||
from app.engines import scan
|
||||
from app.scenarios.churn_fraud import CohortPoint
|
||||
from app.scenarios.split_contract import ContractRecord
|
||||
|
||||
|
||||
def main() -> None:
|
||||
sm = get_sessionmaker()
|
||||
with sm() as session:
|
||||
# 场景一：8 个客户拆单 + 同一实控人
|
||||
contracts = [
|
||||
ContractRecord(f"HT-{i}", f"政企客户{i}", 790000 + i * 25000) for i in range(8)
|
||||
]
|
||||
r1 = scan.run_split_contract_scan(
|
||||
session, contracts, approval_threshold=1_000_000, shared_controller=True
|
||||
)
|
||||
|
||||
# 场景二：养卡骗补，第 3 月断崖退订
|
||||
curve = [
|
||||
CohortPoint(0, 1.0), CohortPoint(1, 0.96),
|
||||
CohortPoint(2, 0.92), CohortPoint(3, 0.08),
|
||||
]
|
||||
r2 = scan.run_churn_scan(
|
||||
session, retention_curve=curve, commission_paid=360000,
|
||||
active_ratio=0.04, zero_usage_ratio=0.93, channel_key="渠道-华南-001",
|
||||
)
|
||||
|
||||
# 再来一条中置信
|
||||
curve2 = [CohortPoint(0, 1.0), CohortPoint(1, 0.7), CohortPoint(2, 0.55)]
|
||||
r3 = scan.run_churn_scan(
|
||||
session, retention_curve=curve2, commission_paid=80000,
|
||||
active_ratio=0.4, zero_usage_ratio=0.5, channel_key="渠道-西南-007",
|
||||
)
|
||||
|
||||
session.commit()
|
||||
for r in (r1, r2, r3):
|
||||
if r.clue:
|
||||
print(f"已生成线索 [{r.scenario_code}] {r.clue.title} "
|
||||
f"置信={r.clue.confidence.value} 评分={r.clue.score}")
|
||||
else:
|
||||
print(f"[{r.scenario_code}] 未命中阈值，无线索")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -43,7 +43,9 @@ def test_clue_full_lifecycle(session):
|
||||
assert clue.status == ClueStatus.ASSIGNED
|
||||
assert clue.assignee == "auditor_zhang"
|
||||
|
||||
paper = clue_svc.adjudicate(session, clue, confirmed=True, actor="auditor_zhang", note="属实，移交")
|
||||
paper = clue_svc.adjudicate(
|
||||
session, clue, confirmed=True, actor="auditor_zhang", note="属实，移交"
|
||||
)
|
||||
assert clue.status == ClueStatus.CONFIRMED
|
||||
assert clue.feedback == "confirmed"
|
||||
assert paper.conclusion == "confirmed"
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
"""线索/NLQ/看板 API 集成测试（需 PostgreSQL）。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import pytest
|
||||
from fastapi.testclient import TestClient
|
||||
|
||||
from app.db import get_session
|
||||
from app.engines import scan
|
||||
from app.main import app
|
||||
from app.scenarios.split_contract import ContractRecord
|
||||
|
||||
|
||||
@pytest.fixture()
|
||||
def client(session):
|
||||
app.dependency_overrides[get_session] = lambda: session
|
||||
try:
|
||||
yield TestClient(app)
|
||||
finally:
|
||||
app.dependency_overrides.pop(get_session, None)
|
||||
|
||||
|
||||
def _seed_clue(session):
|
||||
contracts = [ContractRecord(f"C{i}", f"CUST{i}", 850000) for i in range(8)]
|
||||
return scan.run_split_contract_scan(
|
||||
session, contracts, approval_threshold=1_000_000, shared_controller=True
|
||||
).clue
|
||||
|
||||
|
||||
def test_list_and_get_clue(client, session):
|
||||
clue = _seed_clue(session)
|
||||
session.flush()
|
||||
resp = client.get("/clues")
|
||||
assert resp.status_code == 200
|
||||
assert any(c["id"] == str(clue.id) for c in resp.json())
|
||||
|
||||
resp2 = client.get(f"/clues/{clue.id}")
|
||||
assert resp2.status_code == 200
|
||||
assert resp2.json()["scenario_code"] == "R8"
|
||||
|
||||
|
||||
def test_assign_and_adjudicate_flow(client, session):
|
||||
clue = _seed_clue(session)
|
||||
session.flush()
|
||||
|
||||
r1 = client.post(
|
||||
f"/clues/{clue.id}/assign", json={"assignee": "auditor_w", "actor": "manager_l"}
|
||||
)
|
||||
assert r1.status_code == 200
|
||||
assert r1.json()["assignee"] == "auditor_w"
|
||||
assert r1.json()["status"] == "assigned"
|
||||
|
||||
r2 = client.post(
|
||||
f"/clues/{clue.id}/adjudicate",
|
||||
json={"confirmed": True, "actor": "auditor_w", "note": "属实"},
|
||||
)
|
||||
assert r2.status_code == 200
|
||||
assert r2.json()["status"] == "confirmed"
|
||||
assert r2.json()["feedback"] == "confirmed"
|
||||
|
||||
|
||||
def test_summary_endpoint(client, session):
|
||||
_seed_clue(session)
|
||||
session.flush()
|
||||
resp = client.get("/clues/summary")
|
||||
assert resp.status_code == 200
|
||||
body = resp.json()
|
||||
assert body["total"] >= 1
|
||||
assert body["total_amount_involved"] > 0
|
||||
|
||||
|
||||
def test_no_delete_endpoint(client, session):
|
||||
"""R19：不存在删除线索的 API 端点。"""
|
||||
clue = _seed_clue(session)
|
||||
session.flush()
|
||||
resp = client.delete(f"/clues/{clue.id}")
|
||||
assert resp.status_code in (404, 405) # 方法不允许/路由不存在
|
||||
|
||||
|
||||
def test_nlq_endpoint_uses_local_provider(client):
|
||||
# 默认 .env 为 mock/dashscope；mock 不出域
|
||||
resp = client.post("/nlq", json={"question": "列出政企拆单线索"})
|
||||
assert resp.status_code == 200
|
||||
body = resp.json()
|
||||
assert "answer" in body
|
||||
assert body["egress"] in (True, False)
|
||||
@@ -0,0 +1,37 @@
|
||||
"""NLQ 结构化检索集成测试（需 PostgreSQL）。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from app.engines import scan
|
||||
from app.nlq import service as nlq
|
||||
from app.scenarios.split_contract import ContractRecord
|
||||
|
||||
|
||||
def _seed(session):
|
||||
contracts = [ContractRecord(f"C{i}", f"CUST{i}", 850000) for i in range(8)]
|
||||
scan.run_split_contract_scan(
|
||||
session, contracts, approval_threshold=1_000_000, shared_controller=True
|
||||
)
|
||||
session.flush()
|
||||
|
||||
|
||||
def test_nlq_retrieves_split_clues(session):
|
||||
_seed(session)
|
||||
ans = nlq.ask("列出高置信的政企拆单线索", session=session)
|
||||
assert ans.provider == "datahub"
|
||||
assert ans.egress is False
|
||||
assert "政企拆单" in ans.answer
|
||||
assert "共检索到" in ans.answer
|
||||
|
||||
|
||||
def test_nlq_no_match(session):
|
||||
ans = nlq.ask("列出养卡骗补线索", session=session)
|
||||
assert ans.egress is False
|
||||
assert "未检索到" in ans.answer or "共检索到" in ans.answer
|
||||
|
||||
|
||||
def test_nlq_open_question_falls_back_to_llm(session):
|
||||
# 不含检索关键词 → 走 LLM（mock）
|
||||
ans = nlq.ask("你好，请介绍一下你的能力", session=session)
|
||||
assert ans.provider in ("mock", "datahub")
|
||||
assert ans.egress is False
|
||||
@@ -0,0 +1,46 @@
|
||||
"""全量穿透扫描引擎集成测试（需 PostgreSQL）。
|
||||
|
||||
验证场景检测→线索生成→落库的端到端链路（R5+R7+R8/R9）。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from app.clues.models import ClueStatus, ConfidenceTier
|
||||
from app.engines import scan
|
||||
from app.scenarios.churn_fraud import CohortPoint
|
||||
from app.scenarios.split_contract import ContractRecord
|
||||
|
||||
|
||||
def test_split_scan_creates_high_confidence_clue(session):
|
||||
contracts = [ContractRecord(f"C{i}", f"CUST{i}", 850000) for i in range(8)]
|
||||
result = scan.run_split_contract_scan(
|
||||
session, contracts, approval_threshold=1_000_000, shared_controller=True
|
||||
)
|
||||
assert result.scenario_code == "R8"
|
||||
assert result.scanned_count == 8
|
||||
assert result.clue is not None
|
||||
assert result.clue.confidence == ConfidenceTier.HIGH
|
||||
assert result.clue.status == ClueStatus.NEW
|
||||
assert result.clue.amount_involved > 0
|
||||
assert result.clue.model_version == scan.MODEL_VERSION
|
||||
|
||||
|
||||
def test_split_scan_no_clue_when_clean(session):
|
||||
contracts = [ContractRecord("C1", "A", 100000), ContractRecord("C2", "B", 3_000_000)]
|
||||
result = scan.run_split_contract_scan(session, contracts, approval_threshold=1_000_000)
|
||||
assert result.clue is None
|
||||
|
||||
|
||||
def test_churn_scan_creates_clue(session):
|
||||
curve = [CohortPoint(0, 1.0), CohortPoint(1, 0.95), CohortPoint(2, 0.1)]
|
||||
result = scan.run_churn_scan(
|
||||
session,
|
||||
retention_curve=curve,
|
||||
commission_paid=300000,
|
||||
active_ratio=0.05,
|
||||
zero_usage_ratio=0.9,
|
||||
channel_key="CH-001",
|
||||
)
|
||||
assert result.clue is not None
|
||||
assert result.clue.scenario_code == "R9"
|
||||
assert result.clue.subjects["channel"] == "CH-001"
|
||||
@@ -0,0 +1,79 @@
|
||||
"""场景检测器单元测试（纯逻辑，无需数据库）。"""
|
||||
|
||||
from app.scenarios.churn_fraud import (
|
||||
CohortPoint,
|
||||
churn_risk_score,
|
||||
commission_quality_mismatch,
|
||||
detect_pulse_decay,
|
||||
)
|
||||
from app.scenarios.split_contract import (
|
||||
ContractRecord,
|
||||
detect_threshold_edge,
|
||||
split_risk_score,
|
||||
)
|
||||
|
||||
# ---------- 场景一：政企拆单 (R8) ----------
|
||||
|
||||
def test_threshold_edge_detects_split():
|
||||
# 阈值 100 万，8 份合同集中在 79万-99万
|
||||
contracts = [ContractRecord(f"C{i}", f"CUST{i}", 810000 + i * 20000) for i in range(8)]
|
||||
finding = detect_threshold_edge(contracts, approval_threshold=1_000_000)
|
||||
assert finding.hit
|
||||
assert len(finding.near_threshold) == 8
|
||||
|
||||
|
||||
def test_threshold_edge_no_split_when_amounts_spread():
|
||||
contracts = [
|
||||
ContractRecord("C1", "A", 100000),
|
||||
ContractRecord("C2", "B", 2_000_000),
|
||||
]
|
||||
finding = detect_threshold_edge(contracts, approval_threshold=1_000_000)
|
||||
assert not finding.hit
|
||||
|
||||
|
||||
def test_split_score_higher_with_shared_controller():
|
||||
contracts = [ContractRecord(f"C{i}", f"CUST{i}", 850000) for i in range(8)]
|
||||
finding = detect_threshold_edge(contracts, 1_000_000)
|
||||
s_no = split_risk_score(finding, shared_controller=False)
|
||||
s_yes = split_risk_score(finding, shared_controller=True)
|
||||
assert s_yes > s_no
|
||||
assert s_yes <= 1.0
|
||||
|
||||
|
||||
def test_threshold_must_be_positive():
|
||||
import pytest
|
||||
|
||||
with pytest.raises(ValueError):
|
||||
detect_threshold_edge([], approval_threshold=0)
|
||||
|
||||
|
||||
# ---------- 场景二：养卡骗补 (R9) ----------
|
||||
|
||||
def test_pulse_decay_detects_cliff():
|
||||
curve = [
|
||||
CohortPoint(0, 1.0),
|
||||
CohortPoint(1, 0.95),
|
||||
CohortPoint(2, 0.92),
|
||||
CohortPoint(3, 0.10), # 第3个月断崖
|
||||
]
|
||||
finding = detect_pulse_decay(curve)
|
||||
assert finding.pulse_then_decay
|
||||
assert finding.cliff_month == 3
|
||||
|
||||
|
||||
def test_no_cliff_for_smooth_curve():
|
||||
curve = [CohortPoint(i, 1.0 - 0.05 * i) for i in range(5)]
|
||||
finding = detect_pulse_decay(curve)
|
||||
assert not finding.pulse_then_decay
|
||||
|
||||
|
||||
def test_commission_mismatch_high_for_zero_usage():
|
||||
m = commission_quality_mismatch(commission_paid=100000, active_ratio=0.05, zero_usage_ratio=0.9)
|
||||
assert m > 0.7
|
||||
|
||||
|
||||
def test_churn_score_combines_signals():
|
||||
curve = [CohortPoint(0, 1.0), CohortPoint(1, 0.2)]
|
||||
finding = detect_pulse_decay(curve)
|
||||
score = churn_risk_score(finding, mismatch=0.8)
|
||||
assert 0.0 < score <= 1.0
|
||||
@@ -0,0 +1,12 @@
|
||||
<!doctype html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>AIAudit · 本地 AI 内审平台</title>
|
||||
</head>
|
||||
<body>
|
||||
<div id="root"></div>
|
||||
<script type="module" src="/src/main.tsx"></script>
|
||||
</body>
|
||||
</html>
|
||||
Generated
+1732
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,22 @@
|
||||
{
|
||||
"name": "aiaudit-frontend",
|
||||
"private": true,
|
||||
"version": "0.1.0",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "vite",
|
||||
"build": "tsc -b && vite build",
|
||||
"preview": "vite preview"
|
||||
},
|
||||
"dependencies": {
|
||||
"react": "^18.3.1",
|
||||
"react-dom": "^18.3.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/react": "^18.3.12",
|
||||
"@types/react-dom": "^18.3.1",
|
||||
"@vitejs/plugin-react": "^4.3.4",
|
||||
"typescript": "^5.6.3",
|
||||
"vite": "^5.4.11"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
import { useState } from "react";
|
||||
import Dashboard from "./Dashboard";
|
||||
import Clues from "./Clues";
|
||||
import NLQ from "./NLQ";
|
||||
|
||||
type Tab = "dashboard" | "clues" | "nlq";
|
||||
|
||||
export default function App() {
|
||||
const [tab, setTab] = useState<Tab>("dashboard");
|
||||
|
||||
return (
|
||||
<div className="app">
|
||||
<header>
|
||||
<h1>AIAudit · 本地 AI 内审平台</h1>
|
||||
<div className="sub">数据不出域，审计全穿透 · 演示版</div>
|
||||
</header>
|
||||
|
||||
<div className="tabs">
|
||||
<button className={tab === "dashboard" ? "active" : ""} onClick={() => setTab("dashboard")}>线索看板</button>
|
||||
<button className={tab === "clues" ? "active" : ""} onClick={() => setTab("clues")}>线索处置</button>
|
||||
<button className={tab === "nlq" ? "active" : ""} onClick={() => setTab("nlq")}>自然语言查询</button>
|
||||
</div>
|
||||
|
||||
{tab === "dashboard" && <Dashboard />}
|
||||
{tab === "clues" && <Clues />}
|
||||
{tab === "nlq" && <NLQ />}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
import { useState } from "react";
|
||||
import { api, type Clue } from "./api";
|
||||
import { L, confidenceLabel, feedbackLabel, scenarioLabel, statusLabel } from "./labels";
|
||||
|
||||
export default function ClueDetail({ clue, onBack }: { clue: Clue; onBack: () => void }) {
|
||||
const [c, setC] = useState<Clue>(clue);
|
||||
const [assignee, setAssignee] = useState("");
|
||||
const [note, setNote] = useState("");
|
||||
const [err, setErr] = useState("");
|
||||
|
||||
const actor = "demo_user";
|
||||
const wrap = (p: Promise<Clue>) =>
|
||||
p.then(setC).catch((e) => setErr(String(e)));
|
||||
|
||||
return (
|
||||
<div>
|
||||
<button className="ghost" onClick={onBack}>← 返回列表</button>
|
||||
<div className="panel" style={{ marginTop: 12 }}>
|
||||
<div className="row" style={{ justifyContent: "space-between" }}>
|
||||
<h3 style={{ margin: 0 }}>{c.title}</h3>
|
||||
<span className={`badge ${c.confidence}`}>{L(confidenceLabel, c.confidence)}</span>
|
||||
</div>
|
||||
<div className="status" style={{ margin: "8px 0" }}>
|
||||
场景 {c.scenario_code} {L(scenarioLabel, c.scenario_code)} · 风险域 {c.risk_domain} · 评分 {c.score.toFixed(2)} · 状态 {L(statusLabel, c.status)}
|
||||
{c.assignee && ` · 承办 ${c.assignee}`}
|
||||
{c.feedback && ` · 反馈 ${L(feedbackLabel, c.feedback)}`}
|
||||
</div>
|
||||
<p>{c.rationale}</p>
|
||||
<h4>证据链</h4>
|
||||
<div className="evidence">{JSON.stringify(c.evidence, null, 2)}</div>
|
||||
<h4>涉及主体</h4>
|
||||
<div className="evidence">{JSON.stringify(c.subjects, null, 2)}</div>
|
||||
</div>
|
||||
|
||||
<div className="panel">
|
||||
<h4>处置（人机闭环）</h4>
|
||||
{err && <div className="error">{err}</div>}
|
||||
<div className="row" style={{ marginBottom: 10 }}>
|
||||
<input placeholder="分派给（审计员）" value={assignee} onChange={(e) => setAssignee(e.target.value)} />
|
||||
<button className="ghost" disabled={!assignee} onClick={() => wrap(api.assign(c.id, assignee, actor))}>分派</button>
|
||||
</div>
|
||||
<div className="row">
|
||||
<input placeholder="研判意见" value={note} onChange={(e) => setNote(e.target.value)} />
|
||||
<button className="primary" onClick={() => wrap(api.adjudicate(c.id, true, actor, note))}>定性·属实</button>
|
||||
<button className="ghost" onClick={() => wrap(api.adjudicate(c.id, false, actor, note))}>定性·误报</button>
|
||||
</div>
|
||||
<p className="status" style={{ marginTop: 10 }}>注：本系统不提供删除线索功能（R19 线索不可删，独立性约束）。</p>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,64 @@
|
||||
import { useEffect, useState } from "react";
|
||||
import { api, type Clue } from "./api";
|
||||
import ClueDetail from "./ClueDetail";
|
||||
import { L, confidenceLabel, scenarioLabel, statusLabel } from "./labels";
|
||||
|
||||
export default function Clues() {
|
||||
const [clues, setClues] = useState<Clue[]>([]);
|
||||
const [confidence, setConfidence] = useState("");
|
||||
const [scenario, setScenario] = useState("");
|
||||
const [selected, setSelected] = useState<Clue | null>(null);
|
||||
const [err, setErr] = useState("");
|
||||
|
||||
const load = () => {
|
||||
api
|
||||
.listClues({ confidence: confidence || undefined, scenario_code: scenario || undefined })
|
||||
.then(setClues)
|
||||
.catch((e) => setErr(String(e)));
|
||||
};
|
||||
|
||||
useEffect(load, [confidence, scenario]);
|
||||
|
||||
if (selected) {
|
||||
return <ClueDetail clue={selected} onBack={() => { setSelected(null); load(); }} />;
|
||||
}
|
||||
|
||||
return (
|
||||
<div>
|
||||
<div className="filters">
|
||||
<select value={confidence} onChange={(e) => setConfidence(e.target.value)}>
|
||||
<option value="">全部置信度</option>
|
||||
<option value="high">高</option>
|
||||
<option value="medium">中</option>
|
||||
<option value="low">低</option>
|
||||
</select>
|
||||
<select value={scenario} onChange={(e) => setScenario(e.target.value)}>
|
||||
<option value="">全部场景</option>
|
||||
<option value="R8">R8 政企拆单</option>
|
||||
<option value="R9">R9 养卡骗补</option>
|
||||
</select>
|
||||
</div>
|
||||
{err && <div className="error">{err}</div>}
|
||||
<div className="panel">
|
||||
<table>
|
||||
<thead>
|
||||
<tr><th>标题</th><th>场景</th><th>置信度</th><th>评分</th><th>状态</th><th>金额(万)</th></tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{clues.map((c) => (
|
||||
<tr key={c.id} className="clickable" onClick={() => setSelected(c)}>
|
||||
<td>{c.title}</td>
|
||||
<td>{c.scenario_code} {L(scenarioLabel, c.scenario_code)}</td>
|
||||
<td><span className={`badge ${c.confidence}`}>{L(confidenceLabel, c.confidence)}</span></td>
|
||||
<td>{c.score.toFixed(2)}</td>
|
||||
<td className="status">{L(statusLabel, c.status)}</td>
|
||||
<td>{c.amount_involved ? (c.amount_involved / 10000).toFixed(1) : "-"}</td>
|
||||
</tr>
|
||||
))}
|
||||
{clues.length === 0 && <tr><td colSpan={6} className="status">暂无线索（可运行扫描生成）</td></tr>}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
import { useEffect, useState } from "react";
|
||||
import { api, type DashboardSummary } from "./api";
|
||||
import { L, confidenceLabel, scenarioLabel, statusLabel } from "./labels";
|
||||
|
||||
export default function Dashboard() {
|
||||
const [data, setData] = useState<DashboardSummary | null>(null);
|
||||
const [err, setErr] = useState<string>("");
|
||||
|
||||
useEffect(() => {
|
||||
api.summary().then(setData).catch((e) => setErr(String(e)));
|
||||
}, []);
|
||||
|
||||
if (err) return <div className="error">加载失败：{err}（请确认后端已启动）</div>;
|
||||
if (!data) return <div className="status">加载中…</div>;
|
||||
|
||||
const wan = (data.total_amount_involved / 10000).toFixed(1);
|
||||
return (
|
||||
<div>
|
||||
<div className="cards">
|
||||
<div className="card"><div className="k">线索总数</div><div className="v">{data.total}</div></div>
|
||||
<div className="card"><div className="k">高置信</div><div className="v" style={{ color: "var(--high)" }}>{data.by_confidence.high ?? 0}</div></div>
|
||||
<div className="card"><div className="k">涉及金额(万元)</div><div className="v">{wan}</div></div>
|
||||
<div className="card"><div className="k">场景数</div><div className="v">{Object.keys(data.by_scenario).length}</div></div>
|
||||
</div>
|
||||
<div className="panel">
|
||||
<h3>按状态分布</h3>
|
||||
<div className="row">
|
||||
{Object.entries(data.by_status).map(([k, v]) => (
|
||||
<span key={k} className="tag">{L(statusLabel, k)}: {v}</span>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
<div className="panel">
|
||||
<h3>按场景分布</h3>
|
||||
<div className="row">
|
||||
{Object.entries(data.by_scenario).map(([k, v]) => (
|
||||
<span key={k} className="tag">{k} {L(scenarioLabel, k)}: {v}</span>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
<div className="panel">
|
||||
<h3>按置信度分布</h3>
|
||||
<div className="row">
|
||||
{Object.entries(data.by_confidence).map(([k, v]) => (
|
||||
<span key={k} className="tag">{L(confidenceLabel, k)}: {v}</span>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,50 @@
|
||||
import { useState } from "react";
|
||||
import { api, type NLQResponse } from "./api";
|
||||
import { L, providerLabel } from "./labels";
|
||||
|
||||
export default function NLQ() {
|
||||
const [q, setQ] = useState("");
|
||||
const [resp, setResp] = useState<NLQResponse | null>(null);
|
||||
const [err, setErr] = useState("");
|
||||
const [loading, setLoading] = useState(false);
|
||||
|
||||
const ask = () => {
|
||||
if (!q) return;
|
||||
setLoading(true);
|
||||
setErr("");
|
||||
api
|
||||
.nlq(q)
|
||||
.then(setResp)
|
||||
.catch((e) => setErr(String(e)))
|
||||
.finally(() => setLoading(false));
|
||||
};
|
||||
|
||||
return (
|
||||
<div className="panel">
|
||||
<h3>自然语言查询</h3>
|
||||
<p className="status">审计员零门槛提问，无需写 SQL。例如：“列出高置信的政企拆单线索”。</p>
|
||||
<div className="row">
|
||||
<input
|
||||
style={{ flex: 1 }}
|
||||
placeholder="输入你的问题…"
|
||||
value={q}
|
||||
onChange={(e) => setQ(e.target.value)}
|
||||
onKeyDown={(e) => e.key === "Enter" && ask()}
|
||||
/>
|
||||
<button className="primary" onClick={ask} disabled={loading}>
|
||||
{loading ? "查询中…" : "提问"}
|
||||
</button>
|
||||
</div>
|
||||
{err && <div className="error" style={{ marginTop: 10 }}>{err}</div>}
|
||||
{resp && (
|
||||
<div className="answer">
|
||||
<div className="status" style={{ marginBottom: 8 }}>
|
||||
模型 {resp.model} · 推理 {L(providerLabel, resp.provider)} ·{" "}
|
||||
{resp.egress ? "⚠ 经公网" : "✓ 本地不出域"}
|
||||
</div>
|
||||
{resp.answer}
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,68 @@
|
||||
// 后端 API 客户端（开发期经 Vite 代理转发到本机后端，数据不出域）
|
||||
|
||||
export interface Clue {
|
||||
id: string;
|
||||
title: string;
|
||||
risk_domain: string;
|
||||
scenario_code: string;
|
||||
confidence: "high" | "medium" | "low";
|
||||
score: number;
|
||||
status: string;
|
||||
rationale: string;
|
||||
evidence: Record<string, unknown>;
|
||||
subjects: Record<string, unknown>;
|
||||
amount_involved: number | null;
|
||||
assignee: string | null;
|
||||
feedback: string | null;
|
||||
}
|
||||
|
||||
export interface DashboardSummary {
|
||||
total: number;
|
||||
by_status: Record<string, number>;
|
||||
by_confidence: Record<string, number>;
|
||||
by_scenario: Record<string, number>;
|
||||
total_amount_involved: number;
|
||||
}
|
||||
|
||||
export interface NLQResponse {
|
||||
question: string;
|
||||
answer: string;
|
||||
provider: string;
|
||||
model: string;
|
||||
egress: boolean;
|
||||
}
|
||||
|
||||
async function http<T>(url: string, init?: RequestInit): Promise<T> {
|
||||
const resp = await fetch(url, {
|
||||
headers: { "Content-Type": "application/json" },
|
||||
...init,
|
||||
});
|
||||
if (!resp.ok) {
|
||||
const text = await resp.text();
|
||||
throw new Error(`${resp.status}: ${text}`);
|
||||
}
|
||||
return resp.json() as Promise<T>;
|
||||
}
|
||||
|
||||
export const api = {
|
||||
summary: () => http<DashboardSummary>("/clues/summary"),
|
||||
listClues: (params: { status?: string; scenario_code?: string; confidence?: string }) => {
|
||||
const q = new URLSearchParams(
|
||||
Object.entries(params).filter(([, v]) => v) as [string, string][]
|
||||
).toString();
|
||||
return http<Clue[]>(`/clues${q ? `?${q}` : ""}`);
|
||||
},
|
||||
getClue: (id: string) => http<Clue>(`/clues/${id}`),
|
||||
assign: (id: string, assignee: string, actor: string) =>
|
||||
http<Clue>(`/clues/${id}/assign`, {
|
||||
method: "POST",
|
||||
body: JSON.stringify({ assignee, actor }),
|
||||
}),
|
||||
adjudicate: (id: string, confirmed: boolean, actor: string, note?: string) =>
|
||||
http<Clue>(`/clues/${id}/adjudicate`, {
|
||||
method: "POST",
|
||||
body: JSON.stringify({ confirmed, actor, note }),
|
||||
}),
|
||||
nlq: (question: string) =>
|
||||
http<NLQResponse>("/nlq", { method: "POST", body: JSON.stringify({ question }) }),
|
||||
};
|
||||
@@ -0,0 +1,38 @@
|
||||
// 后端英文枚举值 → 中文显示映射
|
||||
|
||||
export const confidenceLabel: Record<string, string> = {
|
||||
high: "高置信",
|
||||
medium: "中置信",
|
||||
low: "低置信",
|
||||
};
|
||||
|
||||
export const statusLabel: Record<string, string> = {
|
||||
new: "待处理",
|
||||
assigned: "已分派",
|
||||
reviewing: "研判中",
|
||||
confirmed: "已确认（属实）",
|
||||
dismissed: "已排除（误报）",
|
||||
rectifying: "整改中",
|
||||
transferred: "已移交",
|
||||
closed: "已销项",
|
||||
};
|
||||
|
||||
export const feedbackLabel: Record<string, string> = {
|
||||
confirmed: "属实",
|
||||
false_positive: "误报",
|
||||
};
|
||||
|
||||
export const scenarioLabel: Record<string, string> = {
|
||||
R8: "政企拆单",
|
||||
R9: "养卡骗补",
|
||||
};
|
||||
|
||||
export const providerLabel: Record<string, string> = {
|
||||
mock: "本地Mock",
|
||||
vllm: "本地vLLM",
|
||||
dashscope: "公网千问",
|
||||
};
|
||||
|
||||
// 带兜底的取值函数
|
||||
export const L = (map: Record<string, string>, key: string | null | undefined): string =>
|
||||
key ? map[key] ?? key : "-";
|
||||
@@ -0,0 +1,10 @@
|
||||
import React from "react";
|
||||
import ReactDOM from "react-dom/client";
|
||||
import App from "./App";
|
||||
import "./styles.css";
|
||||
|
||||
ReactDOM.createRoot(document.getElementById("root")!).render(
|
||||
<React.StrictMode>
|
||||
<App />
|
||||
</React.StrictMode>
|
||||
);
|
||||
@@ -0,0 +1,63 @@
|
||||
:root {
|
||||
--bg: #0f1419;
|
||||
--panel: #1a2330;
|
||||
--border: #2a3646;
|
||||
--text: #e6edf3;
|
||||
--muted: #8b98a9;
|
||||
--high: #e5484d;
|
||||
--medium: #f5a623;
|
||||
--low: #3fb950;
|
||||
--accent: #2f81f7;
|
||||
}
|
||||
|
||||
* { box-sizing: border-box; }
|
||||
body {
|
||||
margin: 0;
|
||||
font-family: -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif;
|
||||
background: var(--bg);
|
||||
color: var(--text);
|
||||
}
|
||||
|
||||
.app { max-width: 1200px; margin: 0 auto; padding: 24px; }
|
||||
header h1 { font-size: 20px; margin: 0 0 4px; }
|
||||
header .sub { color: var(--muted); font-size: 13px; margin-bottom: 20px; }
|
||||
|
||||
.tabs { display: flex; gap: 8px; margin-bottom: 20px; }
|
||||
.tabs button {
|
||||
background: var(--panel); color: var(--text); border: 1px solid var(--border);
|
||||
padding: 8px 16px; border-radius: 8px; cursor: pointer; font-size: 14px;
|
||||
}
|
||||
.tabs button.active { border-color: var(--accent); color: var(--accent); }
|
||||
|
||||
.cards { display: grid; grid-template-columns: repeat(4, 1fr); gap: 12px; margin-bottom: 20px; }
|
||||
.card { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; padding: 16px; }
|
||||
.card .k { color: var(--muted); font-size: 12px; }
|
||||
.card .v { font-size: 26px; font-weight: 600; margin-top: 6px; }
|
||||
|
||||
.panel { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; padding: 16px; margin-bottom: 16px; }
|
||||
|
||||
table { width: 100%; border-collapse: collapse; font-size: 13px; }
|
||||
th, td { text-align: left; padding: 10px; border-bottom: 1px solid var(--border); }
|
||||
th { color: var(--muted); font-weight: 500; }
|
||||
tr.clickable:hover { background: rgba(47,129,247,0.08); cursor: pointer; }
|
||||
|
||||
.badge { padding: 2px 8px; border-radius: 999px; font-size: 12px; font-weight: 600; }
|
||||
.badge.high { background: rgba(229,72,77,0.15); color: var(--high); }
|
||||
.badge.medium { background: rgba(245,166,35,0.15); color: var(--medium); }
|
||||
.badge.low { background: rgba(63,185,80,0.15); color: var(--low); }
|
||||
|
||||
.status { font-size: 12px; color: var(--muted); }
|
||||
|
||||
input, select, textarea {
|
||||
background: #0d1117; color: var(--text); border: 1px solid var(--border);
|
||||
border-radius: 8px; padding: 8px 10px; font-size: 14px;
|
||||
}
|
||||
button.primary { background: var(--accent); color: white; border: none; padding: 8px 16px; border-radius: 8px; cursor: pointer; }
|
||||
button.ghost { background: transparent; color: var(--text); border: 1px solid var(--border); padding: 8px 16px; border-radius: 8px; cursor: pointer; }
|
||||
|
||||
.row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
|
||||
.filters { display: flex; gap: 10px; margin-bottom: 14px; }
|
||||
.evidence { background: #0d1117; border-radius: 8px; padding: 12px; font-family: monospace; font-size: 12px; white-space: pre-wrap; }
|
||||
.error { color: var(--high); font-size: 13px; }
|
||||
.answer { background: #0d1117; border-radius: 8px; padding: 14px; margin-top: 12px; line-height: 1.6; }
|
||||
.tag { font-size: 11px; color: var(--muted); border: 1px solid var(--border); border-radius: 6px; padding: 1px 6px; }
|
||||
@@ -0,0 +1,20 @@
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2020",
|
||||
"useDefineForClassFields": true,
|
||||
"lib": ["ES2020", "DOM", "DOM.Iterable"],
|
||||
"module": "ESNext",
|
||||
"skipLibCheck": true,
|
||||
"moduleResolution": "bundler",
|
||||
"allowImportingTsExtensions": true,
|
||||
"resolveJsonModule": true,
|
||||
"isolatedModules": true,
|
||||
"noEmit": true,
|
||||
"jsx": "react-jsx",
|
||||
"strict": true,
|
||||
"noUnusedLocals": true,
|
||||
"noUnusedParameters": true,
|
||||
"noFallthroughCasesInSwitch": true
|
||||
},
|
||||
"include": ["src"]
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
{"root":["./src/app.tsx","./src/cluedetail.tsx","./src/clues.tsx","./src/dashboard.tsx","./src/nlq.tsx","./src/api.ts","./src/labels.ts","./src/main.tsx"],"version":"5.9.3"}
|
||||
@@ -0,0 +1,16 @@
|
||||
import { defineConfig } from "vite";
|
||||
import react from "@vitejs/plugin-react";
|
||||
|
||||
// 开发期通过代理转发到本地后端（数据不出域：仅内网/本机）
|
||||
export default defineConfig({
|
||||
plugins: [react()],
|
||||
server: {
|
||||
port: 5173,
|
||||
proxy: {
|
||||
"/clues": "http://localhost:8000",
|
||||
"/datahub": "http://localhost:8000",
|
||||
"/nlq": "http://localhost:8000",
|
||||
"/health": "http://localhost:8000",
|
||||
},
|
||||
},
|
||||
});
|
||||
@@ -0,0 +1,168 @@
|
||||
# 数据要求（面向数据中心）
|
||||
|
||||
> 项目：AIAudit · 本地私有化大模型电信运营商 AI 全域内审平台
|
||||
> 目的：明确"为完成全域内审，需要数据中心向审计数据中台提供哪些数据、以何种粒度/频率/历史深度、何种质量与安全要求"
|
||||
> 版本：v0.1（待评审） 日期：2026-06
|
||||
> 关联：`0-req-AIAudit.md`（R1/R2/R3 及八大场景）、`1-prd-AIAudit.md`、`docs/数据不出域，审计全穿透.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. 总体原则
|
||||
|
||||
1. **数据不出域**：所有数据在本地内网传输与存储，禁止经公网；接入链路与审计数据中台均在机房内网闭环。
|
||||
2. **审计独立掌控**：数据进入审计专用、物理隔离的数据底座，业务方对该底座无写权限。
|
||||
3. **全量而非抽样**：提供全量数据（而非抽样/汇总），以支撑全量穿透。
|
||||
4. **可追溯**：每批数据登记来源系统、批次、时间、行数（数据版本），使审计结论可回溯到当时的数据状态。
|
||||
5. **保留时间维度**：尽量提供带时间戳的明细与变更流水（而非仅当前快照），以支撑时序造假识别与历史回放。
|
||||
6. **主键可对齐**：跨系统实体需提供可关联的业务主键/编码，以支撑主数据对齐与关联穿透。
|
||||
|
||||
---
|
||||
|
||||
## 2. 源系统清单与接入
|
||||
|
||||
| 源系统 | 简称 | 主要数据 | 接入方式（任一即可） |
|
||||
| --- | --- | --- | --- |
|
||||
| 业务支撑系统 | BSS | 客户、订购、计费、出账、缴费、佣金 | 数据库只读账号 / 接口 / 文件导出 |
|
||||
| 运营支撑系统 | OSS | 网络资源、工单、巡检、信令/话单 | 数据库只读 / 文件 |
|
||||
| 企业资源计划 | ERP | 供应商、采购、合同、付款、资产 | 数据库只读 / 接口 |
|
||||
| 财务系统 | FIN | 总账、明细账、凭证、收入确认、成本摊销 | 数据库只读 / 文件 |
|
||||
| 合同管理 | CONTRACT | 合同主数据、条款、审批流 | 接口 / 文件 |
|
||||
| 工单/服务开通 | WO | 工单、交付、验收 | 数据库只读 / 文件 |
|
||||
| 网络侧/信令 | SIGNAL | 话单(CDR)、信令、流量详单 | 文件（大数据量，建议增量） |
|
||||
| 工商/外部数据 | GS | 企业注册、法人、股东、地址（脱敏后） | 文件 / 受控接口 |
|
||||
|
||||
接入要求：
|
||||
- 提供**只读**访问，不影响源系统生产。
|
||||
- 大数据量（话单/信令/流量）优先**增量**同步（按日/按小时），并提供初始历史全量。
|
||||
- 每个数据集需提供**数据字典**（字段含义、口径、单位、枚举值、更新频率）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 按本体实体的数据需求（主数据对齐基础）
|
||||
|
||||
> 目的：构建审计知识图谱，支撑实控人/关联方/马甲穿透。每类实体需提供稳定业务主键。
|
||||
|
||||
| 实体 | 关键字段（至少） | 用途 |
|
||||
| --- | --- | --- |
|
||||
| 客户 Customer | 客户号、名称、类型(政企/公众)、注册地址、法人、统一社会信用代码、开户时间 | 拆单、关联方、空转客户识别 |
|
||||
| 合同 Contract | 合同号、客户号、金额、签订日期、审批层级/结果、业务类型、有效期 | 拆单、跨期、云空转 |
|
||||
| 号码 MSISDN | 号码、归属客户号、归属地、入网/退网时间、状态 | 养卡骗补、内部号套利 |
|
||||
| 终端 IMEI | IMEI、绑定号码、品牌型号、激活时间、补贴金额 | 套机套卡、终端流向 |
|
||||
| 账户 Account | 账户号、户名、所属主体、银行、开户行 | 回款同源、资金穿透 |
|
||||
| 工单 WorkOrder | 工单号、类型、关联合同/项目、处理人、状态、时间 | 工程量、巡检、交付验收 |
|
||||
| 供应商 Supplier | 供应商号、名称、法人、股东、注册地址、统一社会信用代码 | 围标串标、马甲识别 |
|
||||
| 结算单 Settlement | 结算单号、对端、金额、周期、关联业务量 | 网间结算、SP/CP |
|
||||
| 员工 Employee | 工号、岗位、权限/角色、所属机构 | 越权、内部舞弊 |
|
||||
| 渠道/代理商 Channel | 渠道号、名称、佣金政策、归属地 | 佣金套利、养卡骗补 |
|
||||
| 法人/自然人 LegalPerson | 标识、姓名、关联企业、亲属关系（脱敏） | 隐性实控人穿透 |
|
||||
| 地址 Address | 标准化地址、关联主体 | 同址聚集识别 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 按审计场景的数据需求（核心）
|
||||
|
||||
> 每个场景列出"必需数据"与"关键字段"。括号内为对应需求编号。
|
||||
|
||||
### 4.1 场景一 · 政企收入全链路穿透 / 拆单规避（R8）
|
||||
- 必需：政企合同全量、合同审批流水、开票记录、回款流水、客户工商关联数据。
|
||||
- 关键字段：合同金额、签订日期、**审批阈值与审批层级**、客户注册地址、法人、付款账户、回款日期与金额、尾款挂账状态。
|
||||
- 粒度/历史：合同级明细；**近 3 年**。
|
||||
- 支撑检测：阈值边缘金额分布、同址/同法人/同账户聚集、回款时序违约聚类。
|
||||
|
||||
### 4.2 场景二 · 市场业务真实性 / 养卡骗补（R9）
|
||||
- 必需：用户订购与退订流水、渠道佣金发放流水、用户通话/流量活跃明细（可聚合到月）、物联网卡激活与流量。
|
||||
- 关键字段：订购时间、退订时间、渠道号、佣金金额与计提依据、号码归属地、月度通话时长/流量、是否零使用。
|
||||
- 粒度/历史：用户/号码级按月留存；**近 2-3 年**（需覆盖完整"新增→退订"周期）。
|
||||
- 支撑检测：cohort 留存曲线断崖、佣金与活跃度不匹配、零使用批量聚类。
|
||||
|
||||
### 4.3 场景三 · 收入与成本跨期匹配（R10）
|
||||
- 必需：收入确认凭证与明细、成本摊销明细、合同收入确认政策、设备交付/上架记录、预收/趸交标识。
|
||||
- 关键字段：确认日期、确认金额、对应合同、摊销期间、交付/验收日期、计费方式(按量/包年)。
|
||||
- 历史：**近 3 年**凭证级。
|
||||
- 支撑检测：政策-账务-合同三方勾稽、趸交一次性确认、交付与确认时间差。
|
||||
|
||||
### 4.4 场景四 · 渠道佣金与代理商套利（R11）
|
||||
- 必需：终端 IMEI 与号码绑定、佣金/补贴发放、用户在网时长、终端激活与流向、跨省入网记录。
|
||||
- 关键字段：IMEI、绑定号码、激活时间、补贴/佣金金额、在网天数、激活后流量、归属地。
|
||||
- 历史：**近 2 年**。
|
||||
- 支撑检测：激活即沉默、佣金与在网时长不匹配、跨省窜货。
|
||||
|
||||
### 4.5 场景五 · 网络建设与工程采购（R12）
|
||||
- 必需：招投标记录与投标文件元数据、工程量签证、施工队信息、巡检 GPS 轨迹与工单、供应商工商数据。
|
||||
- 关键字段：项目号、投标人、报价、技术方案相似度可比要素、签证工程量、资源消耗、巡检坐标/时间、供应商法人/股东。
|
||||
- 历史：**近 3 年**。
|
||||
- 支撑检测：报价相似度、文件雷同、工程量与资源不匹配、轨迹与工单交叉、马甲供应商。
|
||||
|
||||
### 4.6 场景六 · 互联互通与网间结算（R13）
|
||||
- 必需：话单(CDR)、网间结算单、网络侧原始信令、SP/CP 申报与结算、国际来话路由。
|
||||
- 关键字段：主被叫、通话时长、起止时间、对端运营商、结算单价与量、短信申报量与到达率、路由信息。
|
||||
- 粒度/历史：明细话单（大数据量，增量）；**近 1-2 年**。
|
||||
- 支撑检测：整数倍时长聚集、突发峰值、结算与信令比对、到达率交叉验证。
|
||||
|
||||
### 4.7 场景七 · 云业务 / IDC 与新兴业务（R14）
|
||||
- 必需：云资源用量(CPU/存储/带宽)、合同计费量、IDC 机柜出租与电力消耗、新兴业务客户与关联方、收入确认与验收。
|
||||
- 关键字段：资源实际用量、合同约定量/计费量、机柜出租率、电费、客户关联关系、确认与验收日期。
|
||||
- 历史：**近 2 年**。
|
||||
- 支撑检测：用量 vs 计费量、出租率与电力勾稽、关联方/预付异常、确认-验收时序。
|
||||
|
||||
### 4.8 场景八 · 员工内部舞弊与资源滥用（R15）
|
||||
- 必需：员工权限与操作日志、内部测试号及其用量、积分/电子券发放与兑换流水、岗位-权限对照。
|
||||
- 关键字段：工号、操作类型/时间/对象、测试号流量与收入归属、积分发放量、兑换/变现记录、岗位与权限项。
|
||||
- 历史：**近 2 年**。
|
||||
- 支撑检测：操作日志异常、测试号用途偏离、积分流向、越权(岗位-权限不匹配)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 时序、历史深度与频率
|
||||
|
||||
| 维度 | 要求 |
|
||||
| --- | --- |
|
||||
| 历史深度 | 合同/财务/采购类 **≥3 年**；用户/号码/佣金类 **≥2-3 年**（覆盖完整造假周期）；话单/信令 **≥1-2 年** |
|
||||
| 时间字段 | 所有事实尽量带 **业务发生时间**；变更类提供**变更流水**（含变更时间），支撑双时态回放 |
|
||||
| 同步频率 | 主数据/合同/财务：按日；用户/佣金/订购：按日；话单/信令/流量：按小时或按日增量 |
|
||||
| 初始装载 | 首次提供历史全量，之后增量 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 数据质量与口径要求
|
||||
|
||||
1. **完整性**：关键字段（主键、金额、时间、关联外键）不得大面积缺失；缺失需可识别（空值而非默认值伪造）。
|
||||
2. **一致性**：同一实体在跨系统的编码可映射（提供映射关系或共同业务主键）。
|
||||
3. **口径明确**：金额含税/不含税、时间时区、枚举值含义需在数据字典中说明。
|
||||
4. **唯一性**：主键唯一；重复记录需可去重或标注。
|
||||
5. **可校验**：提供每批次行数/金额合计，便于核对装载完整性。
|
||||
6. 审计数据中台对接入数据做质量探查与评分；**对齐失败/关键缺失将显式标记并提示人工干预，而非静默丢弃**。
|
||||
|
||||
---
|
||||
|
||||
## 7. 安全与合规要求
|
||||
|
||||
1. **数据不出域**：接入与存储全程内网，禁止公网传输；推理使用本地模型或脱敏数据。
|
||||
2. **最小授权**：源系统提供只读、按需字段的访问；敏感字段（身份证、银行账号、个人隐私）按需脱敏或加密。
|
||||
3. **个人信息保护**：用户隐私、工商个人信息遵循相关法规，必要时脱敏（保留可关联的散列标识）。
|
||||
4. **访问留痕**：审计平台对数据访问与使用全程记录不可篡改日志。
|
||||
5. **演示/开发数据**：开发与演示阶段使用脱敏/样例数据，不接触真实生产敏感数据。
|
||||
|
||||
---
|
||||
|
||||
## 8. 交付清单（数据中心需提供）
|
||||
|
||||
- [ ] 各源系统**只读访问**或**数据导出**（接口/库/文件）及连接信息（内网）。
|
||||
- [ ] 每个数据集的**数据字典**（字段、口径、单位、枚举、频率）。
|
||||
- [ ] 跨系统**主键/编码映射**关系（客户、合同、号码、供应商等）。
|
||||
- [ ] 历史**全量初始装载** + 约定的**增量**同步机制。
|
||||
- [ ] 每批次**行数/金额校验**信息。
|
||||
- [ ] 敏感字段**脱敏方案**与口径说明。
|
||||
- [ ] 数据**责任人/接口人**清单，便于口径确认与问题处理。
|
||||
|
||||
---
|
||||
|
||||
## 9. 优先级建议（配合 MVP 分期）
|
||||
|
||||
| 优先级 | 数据范围 | 对应场景 |
|
||||
| --- | --- | --- |
|
||||
| P0（MVP 必需） | 政企合同+审批+回款+客户工商关联；用户订购/退订+渠道佣金+用户活跃 | R8、R9 |
|
||||
| P1（二期） | 收入确认/成本摊销凭证；终端 IMEI/佣金；员工权限/操作日志/积分 | R10、R11、R15 |
|
||||
| P2（三期） | 招投标/工程量/巡检轨迹；话单/信令/结算；云资源/IDC/电力 | R12、R13、R14 |
|
||||
|
||||
> 说明：P0 数据到位即可跑通 MVP 的两个核心场景与同台盲测；其余按风险热力图分期接入。
|
||||
Reference in New Issue
Block a user