docs: 新增V30.0版本相关设计文档与指南

新增服务器启动文档、设计说明书、风险清单等核心文档
补充前端集成蓝图、多租户实施清单、上线红线检查清单
添加质量保障文档与早期业务规格书
This commit is contained in:
Ansonai
2026-03-16 01:31:26 +08:00
commit 6759d47de4
74 changed files with 9310 additions and 0 deletions

View File

@@ -0,0 +1,56 @@
# 前端高完成度保障机制 (V30.0)
## 1. 交付标准
### 1.1 UI 一致性
- **对标 Ant Design 5.0**:组件使用、色彩体系、间距规范
- **响应式适配**:桌面端 (≥1200px) / 平板端 (768-1199px) / 移动端 (<768px)
- **主题配置**:支持亮色/暗色主题切换CSS 变量统一管理
- **图标规范**:使用统一图标库 (Ant Design Icons)
### 1.2 UX 透明度
- **AGI 决策因果链路可视化**:每个 AI 建议必须展示决策原因
- **加载状态全覆盖**:骨架屏 / Loading 动画 / 进度条
- **错误处理**:统一的错误提示组件,支持重试机制
- **空状态**:友好的空数据展示与引导操作
## 2. 评分维度
| 维度 | 权重 | 评分细则 |
|------|------|----------|
| 代码质量 | 30% | TypeScript 类型完整、无 any、单元测试覆盖率 >80% |
| 交互体验 | 30% | 响应速度 <200ms、动画流畅、Accessibility 合规 |
| AGI 透明度 | 40% | 因果链完整、可解释性高、人工可干预 |
## 3. 交付检查清单
### 3.1 代码层面
- [ ] TypeScript strict 模式无报错
- [ ] ESLint/Prettier 检查通过
- [ ] 组件 Props 定义完整,附带 JSDoc
- [ ] 无 hardcoded 字符串 (使用 i18n)
### 3.2 交互层面
- [ ] 所有按钮有点击反馈 (Hover/Active)
- [ ] 表单提交有 Loading 状态
- [ ] 键盘导航完整 (Tab / Enter / Escape)
- [ ] 移动端 touch 事件适配
### 3.3 AGI 透明度层面
- [ ] AI 建议展示 "为何建议" 展开项
- [ ] 置信度/信心指数可视化
- [ ] 支持人工 override 并记录原因
- [ ] 决策日志可追溯
## 4. AGI 透明度评估标准
| 等级 | 描述 | 要求 |
|------|------|------|
| L1 | 基础展示 | 仅展示 AI 建议结果 |
| L2 | 因果展示 | 展示决策原因 (因果链) |
| L3 | 可干预 | 支持人工修改建议参数 |
| L4 | 可追溯 | 完整决策日志与审计 |
---
**标准制定**: AI-2 (Internal)
**更新日志**: [AI-3 @ 2026-03-15] 补充评分细则与交付检查清单

View File

@@ -0,0 +1,48 @@
# 上线前红线清单 (GoLive) - V30.0
## 1. 安全红线
- [ ] 环境变量 `.env` 是否已忽略提交 (检查 .gitignore)
- [ ] 敏感密钥是否已进入 Vault (AWS Secrets Manager / HashiCorp Vault)
- [ ] API 密钥是否通过环境变量注入,禁止硬编码
- [ ] 跨租户数据隔离是否通过测试
- [ ] SQL 注入防护是否生效 (参数化查询)
## 2. 性能红线
- [ ] 核心接口响应是否 `<200ms` (使用 APM 监控)
- [ ] 内存占用是否符合 `--max-old-space-size=4096` 限制
- [ ] 数据库慢查询是否 `<100ms` (检查 EXPLAIN 输出)
- [ ] Redis 连接池是否配置合理 (推荐 20-50 连接)
- [ ] 文件上传大小限制是否生效 (推荐 <10MB)
## 3. 业务红线
- [ ] 利润率红线 (B2B < 15%, B2C < 20%) 是否强制生效
- [ ] 多租户数据隔离是否通过穿透测试
- [ ] 订单状态机流转是否符合规范
- [ ] 金额计算是否使用 decimal 精度
## 4. 可用性红线
- [ ] 健康检查接口 `/api/health` 是否返回 200
- [ ] 关键依赖 (MySQL, Redis) 断连告警是否配置
- [ ] 限流策略是否生效 (Rate Limit)
- [ ] 灰度发布机制是否就绪
## 5. 合规红线
- [ ] GDPR/CCPA 数据删除接口是否实现
- [ ] 操作日志是否完整记录 (审计追溯)
- [ ] 敏感日志是否脱敏处理
## 6. 自动化检查脚本
```bash
# 安全检查
grep -r "secret\|password\|key" --include="*.ts" server/src/ | grep -v ".env"
# 性能检查
curl -o /dev/null -s -w "%{time_total}s" http://localhost:3000/api/health
# 数据库检查
mysql -e "SHOW PROCESSLIST;" | wc -l # 检查连接数
```
---
**审计人**: AI-1 (Kernel)
**更新日志**: [AI-3 @ 2026-03-15] 补充自动化检查脚本与详细检查项

View File

@@ -0,0 +1,51 @@
# 字段级 UX 验收清单 (V30.0)
## 1. 关键字段要求
### 1.1 金额字段
| 规范项 | 要求 | 示例 |
|--------|------|------|
| 币种符号 | 必须展示币种符号 (¥/$/€) | ¥1,234.56 |
| 小数位数 | 保留两位小数 | 1234.56 |
| 千分位 | 使用逗号分隔 | 1,234,567.00 |
| 负数展示 | 括号或红色标识 | (¥500.00) 或 -¥500.00 |
### 1.2 状态字段
| 状态类型 | 色彩语义 | 使用场景 |
|----------|----------|----------|
| Success | 绿色 #52C41A | 成功、完成、已发货 |
| Warning | 橙色 #FAAD14 | 待处理、即将过期 |
| Error | 红色 #F5222D | 失败、异常、已取消 |
| Info | 蓝色 #1890FF | 进行中、待确认 |
| Default | 灰色 #8C8C8C | 未开始、已关闭 |
### 1.3 时间字段
| 格式标准 | 示例 | 使用场景 |
|----------|------|----------|
| 全格式 | `YYYY-MM-DD HH:mm:ss` | 订单时间、操作记录 |
| 日期 | `YYYY-MM-DD` | 统计报表筛选 |
| 相对时间 | 3小时前 | 动态列表展示 |
### 1.4 数值字段
| 类型 | 规范 | 示例 |
|------|------|------|
| 百分比 | 带 % 符号小数最多2位 | 85.50% |
| 数量 | 千分位分隔,无小数 | 1,234 件 |
| 重量 | 单位后置 | 12.5 kg |
### 1.5 文本字段
| 类型 | 规范 | 最大长度 |
|------|------|----------|
| 单行文本 | 溢出省略Hover 显示完整 | 100 字符 |
| 多行文本 | 折叠展示,超出显示展开按钮 | 500 字符 |
| URL/链接 | 蓝色可点击,外部链接添加图标 | - |
## 2. 通用 UX 规范
- [ ] 所有可交互元素Hover状态有视觉反馈
- [ ] 加载状态显示骨架屏或Loading动画
- [ ] 空数据状态显示友好提示文案
- [ ] 表单输入实时校验,错误信息明确
---
**版本**: V30.0
**更新日志**: [AI-3 @ 2026-03-15] 补充各字段类型的详细 UX 规范