smartClean/docs/ai-development-guide.md

# AI 辅助开发九大核心问题：深度解析与解决方案

> SmartClean 智慧清洁 SaaS 平台 — AI 辅助开发实践指南
> 创建日期：2026-04-15
> 适用范围：开发团队、产品团队、项目管理

---

## 目录

- [问题 1：AI 辅助开发文档保存](#问题-1ai-辅助开发文档保存)
- [问题 2：选择 Java 的深层分析](#问题-2选择-java-的深层分析)
- [问题 3：避免 AI 修改业务逻辑](#问题-3避免-ai-修改业务逻辑)
- [问题 4：人工/AI 开发边界划分](#问题-4人工ai-开发边界划分)
- [问题 5：产品手册与用户培训](#问题-5产品手册与用户培训)
- [问题 6：打卡身份校验与代操作拦截](#问题-6打卡身份校验与代操作拦截)
- [问题 7：开放问题与逻辑安全](#问题-7开放问题与逻辑安全)
- [问题 8：手机端数据展示方案](#问题-8手机端数据展示方案)
- [问题 9：国内 AI 编程现状与成本管理](#问题-9国内-ai-编程现状与成本管理)
- [综合实施路线图](#综合实施路线图)

---

## 问题 1：AI 辅助开发文档保存

### 1.1 为什么传统文档体系在 AI 时代失效

传统软件开发的知识链条是：

```
需求文档 → 设计文档 → 代码 → 代码注释 → 测试用例
```

每一环都有人类参与，知识自然沉淀在参与者脑中。即使文档不全，"问写这段代码的人"就能解决。

AI 辅助开发打破了这个链条：

```
需求文档 → Prompt → AI 黑盒处理 → 代码 → 人工微调
                    ↑
              这里的决策过程消失了
```

消失的信息包括：
- AI 为什么选择这个实现方案而不是另一个？
- AI 理解的需求和实际需求有没有偏差？人工微调修正了什么偏差？
- AI 生成的初始版本是什么样？人工改了哪些地方？为什么改？
- Prompt 是什么？下次类似需求能否复用这个 Prompt？
- AI 遗漏了什么？哪些边界条件是后来人工补上的？

如果不记录这些，三个月后你看到一段代码，无法判断：
- 这是经过深思熟虑的设计，还是 AI 随机生成的？
- 改了安全吗？会不会破坏 AI 当初设计的某个巧妙之处？
- 出了 Bug，是 AI 的问题还是人工微调引入的？

### 1.2 文档体系设计（四层架构）

#### 第一层：代码级标注体系

**标注分类标准：**

| 标注 | 含义 | 审核要求 | 示例场景 |
|------|------|----------|----------|
| `[AI-Generated]` | AI 生成，人工审核未改 | 必须审核 | CRUD 接口、UI 页面 |
| `[AI-Assisted]` | AI 辅助，人工大量修改 | 必须审核 | 业务逻辑、复杂查询 |
| `[AI-Suggested]` | AI 建议方案，人工重写 | 自审 | 算法、架构方案 |
| `[Human-Only]` | 纯人工编写 | 同行审核 | 核心业务、安全相关 |
| `[AI-Test]` | AI 生成的测试代码 | 抽查 | 单元测试、集成测试 |

**Java 注释模板：**

```java
/**
 * [AI-Generated] 2026-04-15
 *
 * @ai-model Claude Opus 4.6
 * @ai-prompt "实现保洁员月度出勤汇总查询接口，支持按项目、班组筛选，
 *             返回出勤天数、迟到次数、早退次数、缺勤天数"
 * @ai-confidence 高（标准 CRUD 查询，逻辑简单）
 * @human-review 通过 — Tony 2026-04-15
 * @human-changes 无
 * @business-rule 出勤统计以自然月为周期，跨月打卡归属到打卡开始时间所在月
 */
```

```java
/**
 * [AI-Assisted] 2026-04-15
 *
 * @ai-model Claude Opus 4.6
 * @ai-prompt "实现保洁员排班冲突检测算法"
 * @ai-confidence 中（AI 初始版本有缺陷）
 * @human-review Tony 2026-04-15
 * @human-changes
 *   1. AI 原始版本未考虑夜班跨天场景（22:00-06:00），
 *      人工添加了跨天时间段重叠检测
 *   2. AI 使用了简单的 start/end 比较，
 *      人工改为支持"开区间"（排班结束时间=下一排班开始时间不算冲突）
 *   3. AI 遗漏了"法定假日不检测冲突"的业务规则
 * @business-rule
 *   - 同一保洁员同一时段只能分配到一个区域
 *   - 夜班跨天算一个排班，不拆分
 *   - 排班结束时间 = 下一排班开始时间，不算冲突（交接班）
 *   - 法定假日排班不参与冲突检测
 */
```

**`@ai-confidence` 说明：**
- 高置信度（标准 CRUD）：未来修改时可以放心让 AI 继续处理
- 中置信度（AI 有部分错误）：未来修改时需要特别注意 AI 可能犯同样的错
- 低置信度（AI 严重偏差）：这类代码应标记为人工维护，不再让 AI 碰

**`@human-changes` 的核心价值：**
- 记录了 AI 的能力边界
- 反复出现相同类型的 human-changes，说明需要优化 Prompt 或调整 AI 使用策略
- 新人入职时读这些注释，能快速了解"AI 在哪些地方容易犯错"

#### 第二层：Git Commit 规范体系

**Commit Message 格式：**

```
<类型>(<模块>): <描述> [<AI参与度>]

<详细说明>

AI-Context:
  Model: <模型名>
  Prompt-Summary: <核心 prompt 摘要>
  AI-Contribution: <AI 具体完成了什么>
  Human-Contribution: <人工具体做了什么>
  AI-Errors-Fixed: <修正了 AI 的哪些错误>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
```

**实际示例：**

```
feat(attendance): 实现打卡地理围栏校验 [AI-Assisted]

基于 Haversine 公式实现经纬度距离计算，支持可配置围栏半径。
当 GPS 信号弱时降级到 WiFi 定位辅助校验。

AI-Context:
  Model: Claude Opus 4.6
  Prompt-Summary: 实现基于经纬度的打卡地理围栏校验，支持配置围栏半径
  AI-Contribution: 生成了基础的地理围栏校验框架、Haversine 公式实现、
                   Controller/Service/Mapper 三层代码
  Human-Contribution:
    - 添加 WiFi 辅助定位降级方案（AI 未考虑 GPS 不可用场景）
    - 修正距离计算精度（AI 用 float，改为 double）
    - 添加"围栏半径按项目可配置"功能（AI 硬编码了 200 米）
  AI-Errors-Fixed:
    - AI 初始版本用欧氏距离代替 Haversine，在高纬度地区误差大
    - AI 未处理经纬度为 null 的情况（GPS 获取失败）

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
```

**利用 Git 进行 AI 代码追溯的命令：**

```bash
# 查看所有 AI 参与的提交
git log --grep="AI-Generated\|AI-Assisted" --oneline

# 查看某个文件中 AI 贡献的部分
git log --grep="AI-" -p -- src/service/AttendanceService.java

# 统计 AI 参与度
git log --grep="AI-Generated" --oneline | wc -l   # AI 完全生成
git log --grep="AI-Assisted" --oneline | wc -l     # AI 辅助

# 查看 AI 犯过的错误
git log --grep="AI-Errors-Fixed" --format="%H %s"
```

#### 第三层：需求级开发日志

每个需求完成后，创建一份开发日志，存在 `docs/dev-logs/` 或飞书文档中：

```markdown
# 开发日志：REQ-042 保洁员排班管理

## 基本信息
- 需求编号：REQ-042
- 开发周期：2026-04-10 ~ 2026-04-18
- 开发者：Tony
- AI 工具：Claude Code (Opus 4.6)

## 开发过程时间线

### Day 1：数据库设计 + 基础 CRUD
- Prompt: "设计保洁员排班管理的数据库表..."
- AI 输出质量：良好
- 人工调整：
  - AI 用 VARCHAR(20) 存排班类型，改为 TINYINT + 枚举类
  - AI 未创建复合索引 (user_id + schedule_date)，手动添加

### Day 2：排班冲突检测算法
- Prompt: "实现排班冲突检测..."
- AI 输出质量：中等
- AI 遗漏的关键点：夜班跨天、交接班衔接、法定假日、临时调班
- 决策：核心冲突算法改为人工编写，让 AI 只生成测试用例

### Day 3-4：前端排班页面
- AI 输出质量：良好
- 人工调整：拖拽组件替换、CSS 与设计体系对齐、全局组件使用

## 效率分析
| 阶段 | 传统开发预估 | AI 辅助实际 | 效率提升 |
|------|-------------|------------|---------|
| 数据库设计 | 4h | 1.5h | 63% |
| 后端 CRUD | 8h | 2h | 75% |
| 冲突算法 | 4h | 3.5h | 12%（AI 反而拖慢了） |
| 前端页面 | 16h | 6h | 63% |
| 联调测试 | 8h | 6h | 25% |
| **总计** | **40h** | **19h** | **52%** |

## AI 经验总结
1. 数据库设计：必须在 Prompt 中明确字段类型规范、索引要求
2. 复杂算法：AI 生成初版参考，但核心逻辑人工编写更可靠
3. 前端开发：要在 Prompt 中告知项目的全局组件、CSS 规范
4. 前后端联调：前后端代码最好在同一个对话中生成，避免接口不一致
5. 测试：AI 生成测试框架很快，但边界条件测试必须人工补充
```

#### 第四层：AI 开发经验知识库

将所有开发日志中的共性问题汇总，持续积累：

**数据库设计类常见错误：**

| ID | 错误模式 | 出现频率 | 防范措施 |
|----|---------|---------|---------|
| DB-001 | 时间字段用 VARCHAR | 高 | Prompt 中明确"时间用 DATETIME 类型" |
| DB-002 | 缺少索引 | 高 | Prompt 中明确要求设计索引 |
| DB-003 | 物理删除 | 高 | CLAUDE.md 中写明软删除规范 |
| DB-004 | 缺少审计字段 | 中 | 要求所有表包含 create_time/update_time |
| DB-005 | 类型字段用字符串 | 中 | 要求用 TINYINT + 代码枚举 |
| DB-006 | 缺少字段注释 | 高 | 明确要求每个字段加 COMMENT |

**Java 后端常见错误：**

| ID | 错误模式 | 出现频率 | 防范措施 |
|----|---------|---------|---------|
| BE-001 | 忽略并发 | 高 | 涉及写操作的接口必须考虑并发 |
| BE-002 | 空指针不防御 | 中 | 要求对外部数据做空值检查 |
| BE-003 | 事务边界错误 | 中 | 涉及多表写入时提醒加 @Transactional |
| BE-004 | 硬编码配置 | 高 | 要求可配置项读取配置中心 |
| BE-005 | 异常吞没 | 中 | 要求异常必须记录日志或抛出 |
| BE-006 | 权限校验遗漏 | 高 | Prompt 中明确权限要求 |
| BE-007 | 分页不设上限 | 高 | 要求分页大小有最大值限制 |

**Vue 前端常见错误：**

| ID | 错误模式 | 出现频率 | 防范措施 |
|----|---------|---------|---------|
| FE-001 | 不用全局组件 | 高 | Prompt 中列出全局组件清单 |
| FE-002 | 样式不统一 | 高 | 要求使用项目 CSS 变量 |
| FE-003 | API 路径硬编码 | 中 | 要求使用 api.js 中定义的端点 |
| FE-004 | 权限控制遗漏 | 高 | 要求使用 fetchButtons/fetchFields |
| FE-005 | 内存泄漏 | 低 | 提醒在 onUnmounted 中清理 |
| FE-006 | 请求不防重 | 中 | 要求提交按钮加 loading 状态 |

**业务逻辑常见错误（最危险）：**

| ID | 错误模式 | 出现频率 | 防范措施 |
|----|---------|---------|---------|
| BL-001 | 跨天场景遗漏 | 高 | 涉及时间的业务必须说明跨天 |
| BL-002 | 边界条件 >= 和 > 混淆 | 中 | 工资相关逻辑必须有精确测试 |
| BL-003 | 角色权限假设错误 | 中 | Prompt 中明确涉及的角色 |
| BL-004 | 状态机不完整 | 高 | 画状态图后再让 AI 编码 |
| BL-005 | 数据归属判断错 | 中 | 明确多租户隔离要求 |
| BL-006 | 计算精度丢失 | 中 | 金额计算强制使用 BigDecimal |

### 1.3 文档维护的成本控制

| 文档层级 | 维护频率 | 维护方式 | 耗时 |
|---------|---------|---------|------|
| 代码注释 | 每次 AI 开发时 | 开发时随手写 | 2-3 分钟/文件 |
| Git Commit | 每次提交 | 遵循模板 | 3-5 分钟/提交 |
| 需求开发日志 | 每个需求完成后 | 让 AI 根据对话生成初稿，人工补充 | 15-20 分钟/需求 |
| 经验知识库 | 每月汇总 | 从开发日志中提取共性问题 | 1-2 小时/月 |

**关键技巧：让 AI 帮你写文档。** 每个需求完成后，让 AI 回顾对话生成开发日志初稿：

```
请回顾我们这次对话，生成一份开发日志，包括：
1. 你完成了哪些部分
2. 我人工修改了哪些地方
3. 你犯了哪些错误，我是怎么修正的
4. 下次类似需求的 Prompt 优化建议
```

这样文档工作量下降 60-70%，人工只需审核和补充。

---

## 问题 2：选择 Java 的深层分析

### 2.1 编程语言在 AI 协作中的五个评估维度

#### 维度一：类型安全——AI 错误的拦截率

```
                AI 犯错后的发现时机
     ─────────────────────────────────────
     编译期         运行期          生产环境
       │              │               │
Java   ████████████   ██              █
Go     ████████████   ██              █
TS     █████████      ███             ██
Python █              █████████       ████████
JS     █              █████████       ████████
```

Java/Go（强类型）：AI 传错参数类型、返回值类型不匹配、方法调用参数数量错误——全部在编译期报错。不需要运行代码就能发现 AI 的低级错误。

Python/JS（弱类型）：AI 的类型错误会悄悄通过，直到运行时才暴露，甚至可能在特定条件下才触发。

**具体例子：**

```java
// Java —— AI 写错类型，编译器立刻报错
public BigDecimal calculateOvertime(Long userId, int hours) {
    return baseSalary.multiply(new BigDecimal(hours)); // 类型正确才能编译
}

// 如果 AI 写成：
public BigDecimal calculateOvertime(Long userId, int hours) {
    return baseSalary * hours; // 编译错误！BigDecimal 不能用 * 运算符
}
```

```python
# Python —— AI 写错类型，运行时才发现
def calculate_overtime(user_id, hours):
    return base_salary * hours  # 如果 base_salary 是字符串 "5000"
    # Python 不报错，返回 "500050005000..."（字符串重复）
    # 这个 Bug 可能到月底算工资时才被发现
```

#### 维度二：框架约束力——AI 行为的规范性

框架越有"约定"，AI 生成的代码越规范：

```
框架约束力排名：
Spring Boot (Java)  ★★★★★  注解驱动，结构高度规范
NestJS (TypeScript)  ★★★★☆  借鉴 Spring，较规范
Django (Python)      ★★★★☆  MTV 模式明确
Gin (Go)             ★★★☆☆  轻量灵活，约束少
Express (Node.js)    ★★☆☆☆  过于灵活，AI 容易写出混乱代码
Flask (Python)       ★★☆☆☆  同上
```

Spring Boot 的约束力体现——AI 生成代码时框架约定自然引导分层：

```java
@RestController                    // 框架约定：这是接口层
@RequestMapping("/api/attendance")
public class AttendanceController {

    @Autowired                     // 框架约定：依赖注入
    private AttendanceService attendanceService;

    @PostMapping("/punch")         // 框架约定：HTTP 方法映射
    @RequiresPermission("attendance:punch")  // 框架约定：权限控制
    public Result<PunchRecord> punch(
            @Valid @RequestBody PunchDTO dto) {  // 框架约定：参数校验
        return Result.ok(attendanceService.punch(dto));
    }
}
```

AI 在 Spring Boot 项目中生成代码，即使不给额外提示，也会自然遵循 Controller → Service → Mapper 分层。而在 Express/Flask 中，AI 可能把所有逻辑塞进路由里。

#### 维度三：AI 训练数据量——生成质量

```
AI 训练数据量（GitHub 企业级项目）：
Java       ★★★★★  海量 Spring Boot 企业项目
Python     ★★★★★  数量最多但质量参差不齐
TypeScript ★★★★☆  近年增长快
Go         ★★★★☆  质量高但数量相对少
Rust       ★★★☆☆  数量较少
```

Java + Spring Boot 是 AI 生成质量最稳定的企业级组合之一。

#### 维度四：调试与排查能力

Java 的堆栈跟踪信息详细，异常类型明确，IDE 支持强大（IDEA 的断点调试、代码导航），当 AI 生成的代码出问题时，排查效率最高。

#### 维度五：团队交接与维护

AI 生成的 Java 代码，不同开发者读起来差异不大（框架约束）。AI 生成的 Python/JS 代码，可能每次风格都不同，维护成本高。

### 2.2 SmartClean 项目的具体选择建议

```
核心业务后端：Java + Spring Boot ← 不变
理由：类型安全、框架约束、团队熟悉、AI 生成质量高

前端：Vue 3 + TypeScript（建议渐进迁移）
理由：TypeScript 给前端加了类型安全，AI 生成 TS 代码的质量 > JS
     渐进迁移：新页面用 TS，老页面不动

NLP/AI 服务（龙虾助手）：Python 微服务 ← 独立部署
理由：ML/NLP 生态在 Python，通过 HTTP API 隔离，与主业务系统语言无关

脚本/工具：Python 或 Shell
理由：一次性脚本不需要类型安全

不建议：
- 核心业务改用 Go/Rust（团队学习成本、现有代码迁移）
- 全部用 Python（失去类型安全，长期维护风险）
- 微服务过度拆分（当前规模不需要）
```

### 2.3 Java 8 是否需要升级

当前项目用 Java 8，在 AI 辅助开发中有微妙影响：AI 模型训练数据中包含大量 Java 11/17 代码，AI 生成代码时倾向于使用 var、Records、switch 表达式等新特性，导致编译失败。

**当前做法：** 在 CLAUDE.md 中明确标注 Java 版本约束。

**长远建议：** 可以考虑升级到 Java 17（LTS），既能获得新特性带来的开发效率提升，又能减少 AI 生成代码的适配成本。

---

## 问题 3：避免 AI 修改业务逻辑

### 3.1 AI 篡改业务逻辑的真实风险场景

AI 修改业务逻辑的危险性在于：**不报错、不告警、看起来完全正常，但业务含义已经改变。**

#### 场景 1：悄悄改变比较运算符

```java
// 原始代码：加班费按工作超过 8 小时（含）计算
if (workHours >= 8) {
    overtimePay = calculateOvertime(workHours - 8);
}

// AI 在"优化"代码时，悄悄改成了：
if (workHours > 8) {  // >= 变成了 > ！
    overtimePay = calculateOvertime(workHours - 8);
}
// 后果：恰好工作 8 小时的员工，少算加班费
// 金额差异不大，可能存在数月才被发现
```

#### 场景 2：简化权限校验

```java
// 原始代码：完整的权限校验
public Result deleteSchedule(Long scheduleId) {
    Schedule schedule = scheduleMapper.selectById(scheduleId);
    if (schedule == null) return Result.fail("排班记录不存在");
    if (!schedule.getProjectId().equals(getCurrentUserProjectId()))
        return Result.fail("无权操作其他项目的排班");
    if (schedule.getStatus() == ScheduleStatus.ACTIVE)
        return Result.fail("已生效的排班不能直接删除，请先取消");
    schedule.setDeleted(1);
    scheduleMapper.updateById(schedule);
    return Result.ok();
}

// AI "重构优化"后：
public Result deleteSchedule(Long scheduleId) {
    scheduleMapper.deleteById(scheduleId);  // 物理删除！权限校验全部丢失！
    return Result.ok();
}
```

#### 场景 3：改变数据精度

```java
// 原始代码
BigDecimal hourlyRate = baseSalary.divide(
    new BigDecimal("21.75"), 6, RoundingMode.HALF_UP);

// AI 修改后（"简化"）
double hourlyRate = baseSalary.doubleValue() / 21.75;
// 浮点精度丢失，涉及工资这种敏感数据，1 分钱的差异都可能引起投诉
```

### 3.2 五层防护体系

#### 防线一：代码分区制度（最重要）

将代码库分为三个区域，写入 CLAUDE.md：

**红区（AI 禁入）——AI 只可阅读和建议，不可直接修改：**

```
工资与财务：
- **/service/salary/**
- **/service/finance/**
- 所有包含 "calculate" + "salary/wage/pay" 的方法

权限与安全：
- **/config/security/**
- **/service/auth/**
- **/interceptor/**、**/filter/**

打卡与考勤核心：
- AttendanceService.punch()
- AttendanceService.calculateOvertime()
- PunchRecordService 中的防重复逻辑

数据删除：
- 所有 DELETE 语句（物理删除）
- 所有 mapper.xml 中的 delete 标签
```

修改红区文件的流程：
1. AI 提供修改建议和代码片段
2. 开发者理解建议后手动修改
3. 必须有对应的单元测试覆盖
4. 需要至少一人 Code Review

**黄区（AI 可写，必须审核）：**

```
- **/service/**（除红区外的所有 Service）
- **/mapper/xml/**（复杂查询语句）
- **/job/**、**/task/**（定时任务）
- **/integration/**、**/client/**（第三方集成）
```

**绿区（AI 自主操作）：**

```
- frontend/**（UI 组件和页面）
- **/controller/**（接口层）
- **/dto/**、**/vo/**、**/entity/**（数据传输对象）
- **/test/**（测试代码）
- docs/**（文档）
```

#### 防线二：业务规则断言

将核心业务规则集中定义为常量，系统启动时自动校验：

```java
public final class BusinessRules {
    // 工资规则
    public static final BigDecimal MONTHLY_WORK_DAYS = new BigDecimal("21.75");
    public static final BigDecimal WEEKDAY_OVERTIME_RATE = new BigDecimal("1.5");
    public static final BigDecimal WEEKEND_OVERTIME_RATE = new BigDecimal("2.0");
    public static final BigDecimal HOLIDAY_OVERTIME_RATE = new BigDecimal("3.0");

    // 打卡规则
    public static final int DEFAULT_FENCE_RADIUS_METERS = 200;
    public static final int DUPLICATE_PUNCH_WINDOW_MINUTES = 30;
    public static final int LATE_THRESHOLD_MINUTES = 15;

    // 启动时校验
    public static void validateAll() {
        assert WEEKDAY_OVERTIME_RATE.compareTo(new BigDecimal("1.5")) == 0
            : "BR-SALARY-002 被篡改: 加班费率=" + WEEKDAY_OVERTIME_RATE;
        // ... 其他校验
    }
}
```

业务代码引用此处常量，禁止硬编码。任何值被篡改，系统启动时立刻报警。

#### 防线三：核心逻辑单元测试

核心业务测试必须做到：**修改任何一个运算符、任何一个常量、任何一个判断条件，至少一个测试会失败。**

```java
@Test
public void 加班费_恰好8小时_包含边界() {
    // 这个测试专门防止 >= 被改成 >
    // 恰好 8 小时不算加班（正常工时）
    assertEquals(BigDecimal.ZERO, result.getOvertimePay());
}

@Test
public void 精度_不使用浮点类型() {
    // 通过反射检查 Service 中没有使用 double/float
}
```

#### 防线四：Git Hook 自动检查

提交前自动检测红区文件变更并告警：

```bash
#!/bin/bash
# .git/hooks/pre-commit

RED_ZONE_PATTERNS=("service/salary" "service/auth" "BusinessRules.java")
STAGED_FILES=$(git diff --cached --name-only)

for pattern in "${RED_ZONE_PATTERNS[@]}"; do
    MATCHES=$(echo "$STAGED_FILES" | grep "$pattern")
    if [ -n "$MATCHES" ]; then
        echo "⚠️  红区文件变更警告：$MATCHES"
        echo "需要：1.人工逐行审查 2.单元测试通过 3.至少一人 Code Review"
        read -p "确认已完成以上检查？(yes/no): " confirm
        [ "$confirm" != "yes" ] && exit 1
    fi
done
```

#### 防线五：定期业务逻辑巡检

每两周执行一次自动巡检脚本，检查：
- 红区文件近期变更
- 新增的物理删除语句
- 工资模块中的浮点类型使用
- 缺少权限注解的写接口

---

## 问题 4：人工/AI 开发边界划分

### 4.1 按代码层级划分

```
┌─────────────────────────────────────────────┐
│                前端 UI 层                      │  AI 为主（80%）
│    列表页、表单页、详情页、组件搭建              │
├─────────────────────────────────────────────┤
│              API 接口层（Controller）           │  AI 为主（70%）
│    参数接收、参数校验、调用 Service、返回结果     │
├─────────────────────────────────────────────┤
│            业务逻辑层（Service）                │  人机协作（50/50）
│    业务规则实现、流程编排、事务管理              │
├─────────────────────────────────────────────┤
│            数据访问层（Mapper/DAO）             │  AI 辅助（60%简单/40%复杂）
│    SQL 编写、数据查询、数据持久化               │
├─────────────────────────────────────────────┤
│            基础设施层                          │  人工为主（80%）
│    安全、缓存、消息队列、第三方集成              │
└─────────────────────────────────────────────┘
```

### 4.2 按业务风险划分（最关键）

```
                        业务风险
                          高
                          │
          ┌───────────────┼───────────────┐
          │  人工编写       │  人工编写      │
          │  AI 写测试     │  AI 禁入       │
          │               │               │
          │  工资计算       │  资金流转      │
          │  排班算法       │  权限认证      │
          │  考勤规则       │  数据安全      │
     低 ──┼───────────────┼───────────────┼── 高  技术复杂度
          │               │               │
          │  AI 自主完成    │  AI 生成      │
          │  人工抽查      │  人工审核      │
          │               │               │
          │  CRUD 页面     │  复杂报表      │
          │  简单列表      │  数据迁移      │
          │  表单提交      │  第三方对接    │
          └───────────────┼───────────────┘
                          低
```

**原则：越接近钱和权限的代码，人工参与度越高。**

### 4.3 按 SmartClean 业务模块的详细边界

#### 用户管理模块

- **绿区（AI 自主）：** 用户列表/详情/表单页面、团队/标签/技能 CRUD、用户导入导出、Controller 接口
- **黄区（AI 辅助）：** 用户状态管理、用户与角色关联、数据权限、批量操作
- **红区（人工）：** 用户认证（登录/Token/Session）、密码加密、权限计算与缓存、敏感信息脱敏

#### 打卡考勤模块

- **绿区：** 打卡记录列表/详情页面、考勤报表页面、查询接口、导出 Excel
- **黄区：** 考勤月度汇总统计 SQL、打卡异常检测定时任务、考勤与排班关联查询
- **红区：** 打卡核心逻辑（身份校验、地理围栏、防重、迟到/早退判定）、补卡审批、数据防篡改

#### 任务调度模块

- **绿区：** 任务列表/详情/表单页面、任务记录查询接口、数据导出
- **黄区：** 任务分配算法、计划任务生成、状态流转、巡检路线规划
- **红区：** 任务与工资联动计算、任务完成验证（照片/GPS）、紧急任务推送

#### 人效分析模块

- **绿区：** 统计页面、图表组件、数据导出
- **黄区：** 统计 SQL、效率评分算法、数据缓存策略
- **红区：** 工资积分计算公式、绩效评定规则、数据权限隔离

### 4.4 开发流程中的分工

```
1. 需求分析          → 100% 人工（产品+开发+测试）
2. 技术方案设计       → 人工主导，AI 辅助出初稿
3. 数据库设计        → AI 出初稿 → 人工审核字段类型、索引、关联关系
4. API 接口设计      → AI 出初稿 → 人工审核接口粒度、参数设计
5. 后端 CRUD 开发    → AI 为主（Controller + 简单 Service + Mapper）
6. 核心业务逻辑      → 人工为主，AI 辅助写辅助函数
7. 前端页面开发      → AI 为主
8. 前后端联调        → AI 辅助排查参数不匹配问题
9. 单元测试          → AI 生成测试用例 → 人工补充边界条件
10. Code Review      → 人工审核 AI 代码 + AI 辅助审核人工代码
11. 部署上线         → 人工操作
12. 线上验证         → 人工验证
```

---

## 问题 5：产品手册与用户培训

### 5.1 用户画像分析

#### 保洁员画像

```
年龄分布：35-55 岁为主
教育背景：初中到高中为主
手机使用：
  - 会发微信、看短视频
  - 偏好语音 > 打字
  - 对新 APP 有抵触心理（"又要学新东西"）
工作特点：
  - 早班 5:00-6:00 到岗，没时间"研究"系统
  - 手可能湿/脏，不方便精细操作
  - 手机可能是低端安卓机
  - 流动性高，平均在职 6-12 个月
核心诉求：
  - 打卡不要麻烦，任务看得懂就行，工资算对就行
```

#### 班组长画像

```
年龄分布：30-45 岁
手机使用：熟练使用微信、钉钉，能接受学习新工具
核心诉求：
  - 快速知道谁没来、谁没干完
  - 简单地安排和调整任务
  - 处理异常（补卡、调班）
```

#### 项目经理画像

```
年龄分布：28-40 岁
核心诉求：
  - 数据驾驶舱（全局概览）
  - 人力成本分析、月度报告数据支撑
```

### 5.2 分角色产品手册设计

#### 保洁员手册（极简版——一页纸、大字体、有图示、零术语）

```
设计规格：
- A4 双面彩打，覆膜（防水防脏）
- 字体最小 16px，关键词 20px 加粗
- 左边图/截图，右边文字说明
- 纯口语化

内容：
  上班时说：  "我要上班打卡"
  下班时说：  "我要下班打卡"
  看任务说：  "今天有什么任务"
  干完了说：  "XX区域打扫完了"
  请假时说：  "我要请假"
  看工资说：  "查看本月工资"
  有问题说：  "我有问题要反馈"

  注意：
  - 打卡必须本人操作，不能帮别人打卡
  - 打卡时要在工作区域范围内
  - 不确定怎么说，直接说你想做什么就行
  遇到问题找：班组长 XXX（电话）
```

#### 班组长手册（功能更全）

**日常管理操作：**

| 你想做什么 | 怎么说 | 备注 |
|-----------|--------|------|
| 查看团队出勤 | "今天谁没打卡" | 可加时间，如"本周出勤情况" |
| 安排临时任务 | "给张三安排清扫3号楼大厅" | 需指定人员和区域 |
| 查看任务进度 | "今天的任务完成情况" | 可按区域查 |
| 审批请假 | "查看待审批的请假" | |
| 查看巡检结果 | "今天的巡检报告" | 可指定区域 |

**常见问题处理：**

- 新员工第一天：班组长花 2 分钟教"上班打卡""看任务""下班打卡"三句话
- 龙虾听不懂：换个说法试试，不行就打开 APP 手动操作
- GPS 不准：连工作区域 WiFi，或到室外信号好的地方
- 临时借调：说"临时借调XX到我的班组"

### 5.3 系统内引导设计

#### 新手引导流程

```
第1屏（欢迎）："你好！我是龙虾助手，从今天起帮你处理工作上的事"
第2屏（打卡演示）："来，试试跟我说'上班打卡'" → 用户说后 → "太棒了！就是这么简单！"
第3屏（任务演示）："再试试说'今天有什么任务'" → 展示任务列表 → "干完了跟我说一声"
```

#### 智能引导与纠错

```
高置信度（>90%）→ 直接执行
  "我要上班打卡" → 执行打卡

中置信度（60-90%）→ 确认后执行
  "打卡" → "你是要上班打卡还是下班打卡？"

低置信度（30-60%）→ 猜测 + 引导
  "考勤" → "关于考勤，你想：上班打卡/下班打卡/查看出勤记录？"

极低置信度（<30%）→ 通用引导
  "吃饭了吗" → "我暂时只能帮你处理工作相关的事情。你可以问我：..."

无法识别 → 兜底 + 学习
  同时将消息记录到"未识别日志"中，用于后续优化
```

### 5.4 培训方案（零集中培训）

```
培训金字塔：

运营团队（2人）  ← 深度培训 1 天
  ↓ 培训
班组长           ← 中度培训 2 小时
  ↓ 带教
保洁员           ← 现场带教 10 分钟（只学打卡、看任务、完成任务）
```

**为什么不做集中培训：**
1. 保洁员分散在各项目点，集中成本高
2. 人员流动大，每月都有新人
3. 学习能力参差不齐，集中培训效果差
4. 学了不马上用就忘

**辅助手段：**
- 微信群钉 3 个 30 秒短视频（打卡、看任务、完成任务）
- 每周微信群发一个"你知道吗？你还可以说'查看本月工资'"小贴士
- 月度工资提醒："本月工资已发放，跟龙虾说'看工资'查看工资条"

**应对抵触心理：**
- "我不会用手机" → 班组长当面教，只教打卡
- "以前不用打卡也没事" → 强调打卡是算工资的依据
- "手机里装太多东西了" → 基于微信，不需要装新 APP

### 5.5 持续优化闭环

```
数据收集 → 分析 → 优化 → 验证

1. 记录所有用户输入和系统响应，特别关注：
   - 系统无法识别的消息
   - 用户放弃的对话
   - 用户重复说相同内容（说明第一次没成功）

2. 每周分析：
   - Top 20 未识别消息 → 添加意图/话术映射
   - 高放弃率的对话流程 → 优化引导

3. 持续更新：
   - 每周更新话术库
   - 每月更新引导流程
   - 每季度更新手册
```

---

## 问题 6：打卡身份校验与代操作拦截

### 6.1 威胁模型分析

| 威胁类型 | 典型场景 | 风险级别 |
|---------|---------|---------|
| 直接代打 | "帮李四打卡" | 高 |
| 间接代打 | "李四让我帮他说一下，他今天到了" | 高 |
| 身份伪装 | "我是李四"（用张三账号说） | 高 |
| 模糊描述 | "李四也到了" | 中 |
| 多人同时 | "我和李四都打卡" | 中 |
| 位置作弊 | 使用虚拟定位 APP | 高 |
| 时间作弊 | "我7点就到了，手机没电" | 中 |
| 社会工程 | "班组长帮我打个卡吧" | 中 |

### 6.2 身份认证方案

| 级别 | 方案 | 适用场景 |
|------|------|----------|
| Level 1 | 微信 OpenID 绑定 | 低安全要求（基础方案） |
| Level 2 | 微信 + 设备指纹（推荐） | 标准安全要求 |
| Level 3 | 微信 + 人脸识别 | 高安全要求（如金融物业） |

**建议 SmartClean 采用 Level 2：微信 OpenID + 设备指纹 + 地理围栏三重验证。**

### 6.3 代操作检测逻辑

**检测规则：**

| 规则 | 模式 | 示例 | 处理 |
|------|------|------|------|
| 规则1 | 代操作介词 + 他人名字 + 动词 | "帮李四打卡" | 拦截 |
| 规则2 | 第三人称 + 操作动词 | "李四要打卡" | 拦截 |
| 规则3 | 身份伪装 | "我是李四" | 拦截，提示以登录账号为准 |
| 规则4 | 多人操作 | "我和李四一起打卡" | 拦截，只为当前用户打卡 |
| 查询例外 | 他人名字 + 疑问 | "李四打卡了吗？" | 允许（需权限），当做查询 |

**代操作检测核心逻辑（伪代码）：**

```java
public ProxyDetectResult detect(String message, Long currentUserId) {
    String currentUserName = getNameById(currentUserId);

    // 规则1：代操作介词检测
    // "帮/替/给 + 他人名字 + 操作动词"
    if (包含代操作介词 && 包含他人名字 && 包含操作动词) {
        return 拦截("打卡只能本人操作，请让对方用自己的手机");
    }

    // 规则2：第三人称操作请求
    // "李四要打卡"（不是"李四打卡了吗？"）
    if (提到他人名字 && 包含操作动词 && 不是查询语气) {
        return 拦截("不能帮他人操作，每个人需要用自己的手机");
    }

    // 规则3：身份伪装
    // "我是李四"
    if (包含身份声明 && 声明的名字不是当前用户) {
        return 拦截("系统已通过手机识别你的身份，不需要报名字");
    }

    // 规则4：多人操作
    // "我和李四一起打卡"
    if (包含"和/一起/我们" && 提到他人名字 && 包含操作动词) {
        return 拦截("我先帮你打卡，其他人请用自己的手机");
    }

    return 通过();
}
```

### 6.4 打卡全流程

```
用户发送消息
  │
  ▼
1. 意图识别 → "我要上班打卡" → PUNCH_IN
  │
  ▼
2. 代操作检测 → 检查是否涉及他人 → 拦截或通过
  │
  ▼
3. 身份确认 → Session 获取 userId + 设备指纹校验
  │
  ▼
4. 地理围栏校验 → GPS 定位（降级到 WiFi）→ 计算距离
  │
  ▼
5. 防重复打卡 → 30 分钟内同类型已打过 → 提示
  │
  ▼
6. 考勤判定 → 与排班时间比对 → 正常/迟到/早退
  │
  ▼
7. 写入记录 + 审计日志
  │
  ▼
8. 返回结果
   正常："上班打卡成功！08:01，全勤继续保持！"
   迟到："上班打卡成功！08:18，迟到 3 分钟。"
```

### 6.5 审计日志设计

每次打卡请求（无论成功失败）都记录：

```json
{
    "timestamp": "2026-04-15T08:32:15",
    "userId": 10086,
    "userName": "张三",
    "rawMessage": "我要上班打卡",
    "intent": "PUNCH_IN",
    "proxyDetected": false,
    "geoLocation": {"lat": 31.2304, "lng": 121.4737},
    "withinFence": true,
    "result": "SUCCESS",
    "attendanceStatus": "NORMAL"
}
```

代操作拦截记录：

```json
{
    "timestamp": "2026-04-15T08:35:22",
    "userId": 10086,
    "userName": "张三",
    "rawMessage": "帮李四打个卡吧",
    "intent": "PUNCH_IN",
    "proxyDetected": true,
    "proxyTarget": "李四",
    "result": "BLOCKED",
    "blockReason": "代操作拦截"
}
```

审计日志的价值：
- 员工投诉"我打了卡但系统没记录" → 查审计日志
- 发现疑似作弊行为 → 分析异常模式
- 优化 NLP → 分析被拦截的消息
- 法律纠纷 → 作为电子证据

---

## 问题 7：开放问题与逻辑安全

### 7.1 两个层面分析

#### 层面 A：AI 辅助开发中的开放问题

开发者和 Claude Code 对话时，问分析性问题，AI 可能"好心地"顺便改代码。

**防护措施（写入 CLAUDE.md）：**

```
1. 分析性问题（"你觉得""你看看""合不合理"）→ 只输出文字分析，不修改文件
2. 明确指令（"修改""添加""删除""重构"）→ 执行修改
3. 模糊指令（"处理一下""搞一下"）→ 先确认意图，等待确认
4. 修改红区文件 → 必须先列出完整修改方案，等待确认
5. 不可在回答问题时顺便修改不相关的文件
6. 不可"优化"未被要求修改的代码
7. 不可修改测试用例中的预期值来让测试通过
```

**额外安全网：Git 习惯**
- 每次让 AI 开始新任务前，先 commit 当前状态
- AI 做完后，`git diff` 审核所有变更
- 不满意 → `git checkout` 回退

#### 层面 B：终端用户对话的逻辑安全（龙虾助手）

面向保洁员的对话系统，必须做到**绝对的读写隔离**。

**核心设计：意图白名单制**

```
所有允许的操作穷举列出：

写操作（需二次确认）：
- PUNCH_IN / PUNCH_OUT（打卡）
- LEAVE_REQUEST（请假）
- TASK_COMPLETE（完成任务）
- SUPPLEMENT_PUNCH（补卡申请）

读操作（直接返回）：
- QUERY_MY_TASKS（查看我的任务）
- QUERY_MY_ATTENDANCE（查看我的考勤）
- QUERY_MY_SALARY（查看我的工资）

管理操作（仅班组长+）：
- QUERY_TEAM_ATTENDANCE（查看团队考勤）
- ASSIGN_TEMP_TASK（安排临时任务）

不在白名单 → 当做闲聊，只返回文字，绝不触发数据库操作
```

**写操作二次确认：**

```
用户："我要请假三天"
龙虾："确认请假信息：
  请假人：张三
  时间：2026-04-16 至 2026-04-18（3天）
  类型：事假
  确认提交吗？[确认] [取消]"
```

**危险操作完全拦截：**

```
用户："把我上个月的打卡记录删了"
龙虾："抱歉，删除数据需要管理员在后台操作。
  如果你的考勤记录有问题，可以跟班组长说明情况。"

以下操作不能通过对话执行：
- 删除数据
- 修改工资配置
- 修改权限设置
- 批量操作
```

**注入防护：**
- 用户消息永远作为纯文本处理，不参与任何代码执行
- 意图识别输出的是枚举值，不是用户原文
- 数据库操作使用参数化查询
- 如果用 LLM 做意图识别，用户消息放在独立标签中，与系统 prompt 严格隔离

---

## 问题 8：手机端数据展示方案

### 8.1 核心设计原则

```
保洁员 ≠ 办公室白领

设计原则：
1. 首屏 = 最重要的一个数字/状态
2. 操作 ≤ 3 次点击完成
3. 文字大、按钮大、间距大
4. 支持弱网/离线基础功能
5. 绝不要求用电脑
```

### 8.2 各类数据的适配方案

#### 工资条：卡片化 + 渐进展开

**第一级：摘要卡片（龙虾助手直接返回）**

```
2026年4月 工资条

    实发工资
  ¥ 5,680.00

基本工资    ¥4,500.00
加班费      ¥  750.00
全勤奖      ¥  200.00
───────────────────
社保        -¥  520.00
个税        -¥  250.00

[查看完整明细]  [有疑问]
```

**第二级：完整明细（H5 页面，不是 Web 后台）**
- 所有收入项 + 计算过程（如"平日加班费：10小时 × ¥28.74 × 1.5 = ¥431.03"）
- 所有扣除项
- 出勤信息汇总
- 底部有"工资有疑问？点击反馈"入口

关键设计：加班费后标注计算过程，让员工看懂怎么算的。不用横向表格，全部纵向列表。

#### 考勤记录

```
龙虾返回：
"你4月的考勤情况：
  出勤 21 天（全勤）
  迟到 0 次 / 早退 0 次
  加班 15.22 小时
  全勤奖 ¥200 到手！继续保持！
  [查看每日打卡详情]"
```

#### 任务清单

```
"今天你有 3 个任务：
1. A栋大厅清扫 [08:00-10:00]
2. B栋卫生间清洁 [10:00-11:30]
3. 外围道路保洁 [13:00-16:00]
干完了跟我说'XX干完了'就行！"
```

#### 排班表

```
"这周你的排班：
周一 07:00-16:00  A区
周二 07:00-16:00  A区
周三 07:00-16:00  B区  ← 注意换区了
周四 07:00-16:00  B区
周五 07:00-16:00  A区
周六 休息 / 周日 休息"
```

### 8.3 各数据类型的双端分工

| 数据 | 手机端展示 | Web 端附加能力 |
|------|-----------|---------------|
| 工资条 | 卡片摘要 + H5 详情 | 导出 Excel、历史对比 |
| 考勤 | 出勤天数 + 异常标记 | 完整日历视图 |
| 排班 | 我的本周排班 | 全员排班甘特图 |
| 任务统计 | 今日/本周完成数 | 多维度图表分析 |
| 巡检报告 | 最近一次结果 | 历史趋势、照片汇总 |

### 8.4 Web 端定位

Web 端不是给保洁员用的，而是给管理层用的：

```
Web 端用户：项目经理、区域经理、公司管理层
Web 端功能：
- 数据驾驶舱（全局概览）
- 多维度报表（可筛选、可导出）
- 排班管理（甘特图、批量操作）
- 人员管理（入职、离职、调动）
- 薪资管理（批量算薪、审核、发放）
- 系统配置（权限、围栏、规则配置）

设计原则：
- Web 端面向"管理+分析"场景
- 手机端面向"执行+查询"场景
- 两端数据实时同步
- 不强制任何人必须用 Web 端
```

---

## 问题 9：国内 AI 编程现状与成本管理

### 9.1 工具能力对比（以 SmartClean 典型任务为基准）

**任务 1：生成完整的排班 CRUD**

| 工具 | 评分 | 说明 |
|------|------|------|
| Claude Code (Opus) | ★★★★★ | 一次生成完整代码，分层规范 |
| Cursor (Claude) | ★★★★☆ | IDE 内生成，需分步操作 |
| GitHub Copilot | ★★★☆☆ | 补全好，无法一次生成完整模块 |
| 通义灵码 | ★★★☆☆ | 能生成框架，细节需调整 |
| DeepSeek Coder | ★★★☆☆ | Java 代码质量不错，上下文理解弱 |
| 豆包 MarsCode | ★★☆☆☆ | 简单补全可以，复杂力不足 |

**任务 2：排查跨天排班冲突 Bug**

| 工具 | 评分 | 说明 |
|------|------|------|
| Claude Code (Opus) | ★★★★★ | 能理解业务上下文，精确定位 |
| Cursor (Claude) | ★★★★☆ | 需手动指定相关文件 |
| DeepSeek Coder | ★★★☆☆ | 推理不错但上下文窗口小 |
| 通义灵码 | ★★☆☆☆ | 简单 Bug 可以，复杂推理弱 |

**任务 3：设计打卡防作弊方案**

| 工具 | 评分 | 说明 |
|------|------|------|
| Claude Code (Opus) | ★★★★★ | 方案完整、考虑全面 |
| DeepSeek (Chat) | ★★★★☆ | 推理能力强，方案有深度 |
| 通义灵码 | ★★★☆☆ | 中文好，方案深度一般 |

### 9.2 推荐的任务分流策略

| 任务类型 | 推荐工具 | 原因 |
|---------|---------|------|
| 日常代码补全 | 通义灵码/Copilot | 实时补全，免费/低价 |
| 简单 CRUD | DeepSeek/通义 | 够用且便宜 |
| Vue 页面开发 | DeepSeek/通义 | 前端代码质量可以 |
| 复杂业务逻辑 | Claude Code | 推理能力最强 |
| 架构设计 | Claude Code | 长上下文 + 深度推理 |
| Bug 排查 | Claude Code | 跨文件理解能力最强 |
| 代码重构 | Claude Code/Cursor | 需要理解全局上下文 |
| 文档生成 | DeepSeek/通义 | 中文好，成本低 |
| 单元测试 | 通义/DeepSeek | 模板化工作 |
| SQL 编写优化 | Claude/DeepSeek | 需要理解表关系 |

### 9.3 Token 消耗深度分析

**为什么对话越长越贵：**

```
轮次   单轮 token    累计 token    累计成本（Opus 估算）
1      15,000        15,000       $0.30
5      25,000        115,000      $2.10
10     40,000        315,000      $5.70
20     70,000        1,015,000    $17.50
30     100,000       2,015,000    $34.00
50     150,000       5,015,000    $82.00

因为每轮对话都携带之前的完整历史！
```

**Token 优化策略：**

**策略 1：优化 CLAUDE.md（节省 30-40%）**
在 CLAUDE.md 中写清楚代码生成规范（Java 版本、字段类型、全局组件等），每条规范能减少一轮返工对话。

**策略 2：任务拆分（节省 40-60%）**

```
错误：一个大对话完成整个需求 → ~3,000,000-5,000,000 token
正确：拆成 6 个小对话 → ~1,000,000 token（节省 60-70%）
```

10 个各 5 轮的小对话，比 1 个 50 轮的大对话便宜得多。

**策略 3：精准 Prompt（节省 20-30%）**

```
错误（引发 3-5 轮追问）：
"帮我写个打卡接口"

正确（一次到位）：
"在 AttendanceController 中新增 POST /api/attendance/punch 接口：
 接收 PunchDTO（type: IN/OUT, latitude, longitude），
 校验地理围栏 200 米，防重复 30 分钟，
 判定迟到/早退 15 分钟，需要权限注解"
```

**策略 4：善用 /compact**
对话进行到 15-20 轮时执行 `/compact`，后续每轮消耗降低 30-50%。

**策略 5：分流到国内模型（节省 50-70% 成本）**
60-70% 的日常任务用国内模型（免费或极低价），30-40% 的复杂任务用 Claude。

### 9.4 成本测算

```
假设：2 个开发者，月均开发 12 个需求

方案 A：全部使用 Claude Code
  月成本：约 ¥9,000

方案 B：混合策略（推荐）
  60% 用 DeepSeek（约 ¥200/月）
  10% 用通义灵码（免费）
  30% 用 Claude Code（约 ¥1,350/月）
  月总成本：约 ¥3,100

方案 C：Claude Max 订阅
  $100-200/月/人
  两个开发者：约 ¥1,400-2,800/月

对比参考：
  中级 Java 开发者月薪 ¥15,000-25,000
  AI 工具成本 ¥1,500-4,500/月 = 开发者工资的 3-8%
  如果 AI 能提升 30%+ 效率，ROI 非常高
```

### 9.5 数据安全合规

**数据分级制度：**

| 级别 | 说明 | 处理方式 |
|------|------|----------|
| Level 1 公开数据 | 开源代码、公开技术文档 | 可发送给任何 AI |
| Level 2 内部数据 | 业务代码、表结构、接口定义 | 可发送给付费 AI 服务 |
| Level 3 敏感数据 | 含用户信息的代码、业务数据 SQL | 脱敏后可发送 |
| Level 4 机密数据 | 密码、密钥、真实工资、身份证号 | 禁止发送 |

**发送代码给 AI 前的检查清单：**

- [ ] 代码中没有硬编码的密码/密钥/Token
- [ ] 代码中没有真实的 IP 地址/域名
- [ ] 代码中没有真实用户的姓名/手机号
- [ ] 配置文件中的敏感信息已替换为占位符
- [ ] SQL 中的 WHERE 条件不包含真实数据
- [ ] 错误截图中没有敏感信息

---

## 综合实施路线图

### 第一阶段：立即执行（本周）

| 行动 | 对应问题 | 负责人 |
|------|----------|--------|
| 更新 CLAUDE.md 添加代码生成规范 | 问题 3/9 | 技术负责人 |
| 更新 CLAUDE.md 添加代码分区规则 | 问题 3 | 技术负责人 |
| 制定 Git Commit 规范 | 问题 1 | 技术负责人 |
| 制作保洁员一页纸快速指南 | 问题 5 | 产品经理 |

### 第二阶段：两周内完成

| 行动 | 对应问题 |
|------|----------|
| 创建 BusinessRules.java 业务规则断言文件 | 问题 3 |
| 建立核心业务逻辑的单元测试覆盖 | 问题 3 |
| 实现打卡代操作检测逻辑 | 问题 6 |
| 实现意图白名单 + 写操作确认机制 | 问题 7 |
| 制定人工/AI 开发边界文档并团队对齐 | 问题 4 |

### 第三阶段：一个月内完善

| 行动 | 对应问题 |
|------|----------|
| 建立需求级开发日志模板并执行 | 问题 1 |
| 沉淀 AI 开发经验知识库初版 | 问题 1 |
| 完成工资条/考勤移动端卡片化设计 | 问题 8 |
| 完成班组长操作手册 + 培训视频 | 问题 5 |
| 确定混合工具策略并跟踪成本 | 问题 9 |

### 持续迭代

| 行动 | 频率 |
|------|------|
| 分析用户未识别消息，优化话术 | 每周 |
| 更新 AI 经验知识库 | 每月 |
| 审计红区文件变更 | 每月 |
| 评估 AI 工具效果与成本 | 每季度 |

---

## 附录：高效 Prompt 模板库

### 新增 CRUD 功能模板

```
在 {模块名} 中新增 {功能名} 的完整 CRUD：

数据库：
- 表名：{table_name}
- 核心字段：{字段列表及类型}
- 必须包含：id(BIGINT), create_time, update_time, deleted(TINYINT)
- 类型/状态字段用 TINYINT，时间字段用 DATETIME
- 设计查询所需索引

后端：
- Controller: {接口路径前缀}
- 包含：分页列表、新增、修改、删除（逻辑删除）、详情
- 分页大小上限 100，参数校验，权限注解

前端：
- 使用 qu-table 全局组件
- 列和按钮通过 fetchFields/fetchButtons 动态加载
- API 定义在 Apis/api.js，调用封装在 ApiService/ 下
- 提交按钮加 loading 防重
```

### 复杂业务逻辑模板

```
实现 {功能描述}

业务规则（必须全部遵守，不可简化）：
1. {规则1}
2. {规则2}

边界条件：
- {如跨天、并发、空值}

角色权限：
- {角色1}可以{操作}
- {角色2}只能{有限操作}

技术约束：
- 金额用 BigDecimal，多表写入加 @Transactional

请先输出实现方案概述，确认后再编写代码。
```