# 无碍智检

**Repository Path**: elfbobo_admin_admin/wazj

## Basic Information

- **Project Name**: 无碍智检
- **Description**: 无碍智检是一款面向政务、医院、学校、国企及服务商的信息无障碍/适老化预检测与整改交付系统。项目聚焦页面采集、规则预检测、问题复核、整改清单、报告导出和复测归档，帮助交付团队快速发现网站或小程序中的无障碍与适老化问题，形成截图证据、整改建议和可留档的交付材料。系统定位为评测前准备和内部整改辅助工具，不替代官方认证或法律合规结论。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CrossAccess AI / 无碍智检

> [!IMPORTANT]
> **🏆 OPC 2026 跨境半决赛成果展示与演示指南**
>
> 项目成果与演示指南详见：👉 **[COMPETITION_RESULTS.md](./COMPETITION_RESULTS.md) (半决赛成果展示与演示指南)**

基于检测流水线，对网页或小程序的**可访问性**、**适老化**、**跨境体验**以及**个人敏感信息保护**进行自动检测，并输出整改清单与修复建议。

本项目定位为**上线前的辅助检测与预诊断工具**，不具有官方认证、法律审查或最终合规认定的效力。

---

## 快速启动（Docker）

```bash
# 首次部署：按 secrets/README.md 准备 Docker Secrets（*.txt 文件）
bash scripts/init-secrets.sh   # 或手动写入真实密钥
# 须在项目根目录执行（含 docker-compose.yml 的目录）：
docker compose up -d --build
# 或
make up
```

| 服务 | 地址 |
|------|------|
| 前端（Agent Demo） | http://localhost:3000 |
| 后端 API | http://localhost:8080/api/v1/health |
| MCP | `POST http://localhost:8080/mcp` |
| 任务进度（SSE） | `GET /api/v1/tasks/{task_id}/stream` |
| MinIO 控制台 | http://localhost:9001（默认账号 `minioadmin`，密码见 `secrets/minio_secret_key.txt`） |

```bash
make health      # 健康检查
make ps          # 容器状态
make demo-check  # 演示链路自检
make logs        # 日志
make restart     # 重启
make down        # 停止
make clean       # 停止并删数据卷
make test        # 本地 CI：后端单测 + 前端构建（与 GitHub Actions 一致）
```

推送至 `main` / `master` 或发起 PR 时，`.github/workflows/ci.yml` 会自动运行 Go 单测、前端构建与 Docker 镜像构建。

**说明**

- **配置方式**：本部署不再使用 `backend/.env`；敏感信息（密码、API Key、加密密钥）统一通过 `secrets/*.txt` 以 Docker Secrets 挂载；非敏感配置在本文件或 `docker-compose.yml` 中设有默认值，也可通过 shell 环境变量覆盖。
- **对象存储**：Docker Compose 默认 `STORAGE_DRIVER=minio`；本地直跑后端时可设 `STORAGE_DRIVER=local` + `STORAGE_ROOT`。
- **大模型**：未配置 `secrets/deepseek_api_key.txt`、`secrets/llm_api_key.txt` 等时走内置规则模板，Demo 可不依赖外部 Key。
- **Redis**（可选）：`docker compose --profile redis up` 启用任务队列与查询缓存；未启用时在进程内 goroutine 执行。
- **截图与渲染（已内置）**：Docker Compose 运行阶段已集成安装了无头 Chromium 浏览器及中文字体，底层采用 `chromedp` 驱动，实现单次浏览器会话极速抓取真实页面渲染 DOM 及高保真截图存入 MinIO。
- **数据库**：Docker Compose 使用库名 `crossaccess_ai`；本地直跑请保持 `DB_NAME` 一致。生产种子：`make db-seed`；首个管理员：`make db-bootstrap-admin BOOTSTRAP_ADMIN_PASSWORD='…'`。
- **API 认证（生产）**：`API_AUTH_MODE=required` 后，除 `/health`、`/auth/login` 外需 `Authorization: Bearer <token>`；用户登录 `POST /api/v1/auth/login`；机器令牌写入 `secrets/api_service_token.txt`；Token HMAC 密钥写入 `secrets/auth_token_secret.txt`。
- **MCP 认证**：`POST /mcp` 始终强制认证，不受 `API_AUTH_MODE=off` 影响；使用 `secrets/mcp_service_token.txt` 对应的 Bearer / `X-API-Key`，或 admin 用户 Access Token。

---

## 演示流程（OPC 2026 跨境半决赛）

1. `docker compose up -d --build`
2. 打开 http://localhost:3000
3. 选「跨境电商结账页」快捷任务，可填真实 URL，也可留空走内置回退数据
4. 点「开始智能诊断」，等待 Timeline 8 步跑完（7 个 Skill；`page_capture` 在 Timeline 中展示为场景识别 + 采集两步）
5. 看跨境相关 finding（多语言、支付、币种/关税、配送、退货等）和数据保护 finding（隐私同意、Cookie 等）
6. 在 Agent Chat 里追问，例如：「如何降低跨境支付页面的合规风险？」
7. 勾选问题，导出整改清单 CSV
8. 如需展示 MCP：`POST /mcp`，`method: tools/list`

---

## 主要能力

- **页面分析**：HTTP 拉 HTML，goquery 解析 DOM，按规则提取 Selector；支持 CSS 对比度计算（4.5:1）。
- **四类检测 Skill**：可访问性、适老化、跨境体验、个人信息/残疾人数据保护（含跨境电商场景 finding 目录）。
- **整改建议**：配置了 DeepSeek 时走 LLM；否则用内置模板。
- **Agent Chat**：基于项目上下文追问，同样支持 LLM / 规则回退。
- **导出**：整改清单 CSV，含数据类型、敏感个人信息、残疾人相关字段等列。
- **MCP**：HTTP JSON-RPC（`tools/list`、`tools/call`、`resources/read`、`prompts/get`），与 REST 共用 usecase。
- **异步任务**：页面采集、Agent 诊断异步执行；可选 Redis 队列。任务进度 API 支持 SSE 与轮询；前端优先 SSE，失败时回退轮询。

---

## 实现情况

| 模块 | 状态 |
|------|------|
| Agent + 7 个 Skill 流水线 | 可用 |
| REST API | 可用 |
| 真实 HTML / DOM 分析 (Chromedp 无头浏览器) | 可用 |
| 对比度检测 (Axe-Core & CSS 规则分析) | 可用 |
| 跨境 / 数据保护 finding 目录 | 可用 |
| LLM 整改建议 + HTML 修复代码对比生成 | 可用 |
| CSV 导出 | 可用 |
| HTML 可打印报告（预检/摘要/复测归档） | 可用 |
| 报告维度分布与优先整改可视化 | 可用 |
| SSE 任务进度 | 可用 |
| MCP JSON-RPC | 可用 |
| MCP stdio（`crossaccess-mcp`） | 可用 |
| Redis 队列与缓存 | 可选 |
| Chromium 真实截图与页面捕获 | 可用 (已在 Docker 内集成中文字体与 chromedp) |
| OCR 截图分析（Tesseract） | 可用 |
| 服务端高保真 PDF 报告导出 | 可用 (基于无头 Chromium 服务端打印生成) |

---

## 架构

```
Frontend (React + Vite + Tailwind)
        │  REST / SSE
API (chi)  —  /api/v1/*  +  POST /mcp
        │
UseCase (App + 按领域拆分的接口)
        │
Agent Orchestrator → Pipeline → Skills
        │
Adapters: MySQL · MinIO/本地存储 · DeepSeek/规则 LLM · Redis · Playwright 截图
```

Skill 顺序：`page_capture` → `accessibility_rule_check` → `age_friendly_ux_check` → `cross_border_experience_check` → `personal_data_protection_check` → `ai_remediation_suggestion` → `remediation_export`

---

## API 一览

### REST（前缀 `/api/v1`）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/agent/diagnose` | 发起 Agent 诊断，返回 `task_id` |
| POST | `/agent/chat` | 诊断后追问 |
| GET | `/tasks/{task_id}` | 查询任务状态 |
| GET | `/tasks/{task_id}/stream` | SSE 推送进度（轮询 `GET` 亦可） |
| GET | `/health` | 健康检查 |
| GET | `/mcp/tools` | MCP Tool 元数据（JSON，非 JSON-RPC） |
| * | `/projects` | 项目 CRUD |
| * | `/projects/{id}/pages` | 页面 |
| * | `/projects/{id}/findings` | 问题 |
| POST | `/projects/{id}/scan` | 规则包扫描 |
| POST | `/ai/impact-summary` | 影响说明生成 |
| POST | `/ai/fix-suggestion` | 修复建议生成 |
| POST | `/projects/{id}/reports` | 生成报告（整改清单 CSV 等） |
| GET | `/reports/{id}/download` | 下载报告文件 |

### MCP（根路径，无 `/api/v1` 前缀）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/mcp` | JSON-RPC（`tools/list`、`tools/call` 等；强制认证） |

完整字段见 [docs/API.md](./docs/API.md)。

---

## 技术栈

| 层 | 选型 |
|----|------|
| 前端 | React、TypeScript、Vite、Tailwind、shadcn/ui |
| 后端 | Go 1.24、chi |
| 结构 | Domain → UseCase → Adapter → API |
| 数据库 | MySQL 8 |
| 对象存储 | MinIO（S3 兼容）或本地目录 |
| LLM | DeepSeek（可配），无 Key 时规则引擎 |
| 队列 | Redis 7（可选） |
| 部署 | Docker Compose |

---

## 合规边界

本项目输出为**预诊断结果与修复建议**，上线前需经专业人员复核。

请勿将此工具的检测结果作为已通过官方合规认证、完全消除合规风险、或替代法律及专业审计意见的凭证。

---

## 文档

- [CHECKLIST.md](./CHECKLIST.md) — 演示验收
- [RUNBOOK.md](./RUNBOOK.md) — 排障
- [DEMO_SCRIPT.md](./DEMO_SCRIPT.md) — 演示话术
- [docs/API.md](./docs/API.md) — 接口说明
- [docs/DB_SCHEMA.md](./docs/DB_SCHEMA.md) — 库表设计
- [backend/internal/mcp/README.md](./backend/internal/mcp/README.md) — MCP 开发说明
- [docs/MCP_SETUP.md](./docs/MCP_SETUP.md) — **MCP 配置手册（Cursor / Claude / HTTP）**