smartClean/docs/ai-development-guide.md

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

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

---

目录

• 问题 1：AI 辅助开发文档保存
• 问题 2：选择 Java 的深层分析
• 问题 3：避免 AI 修改业务逻辑
• 问题 4：人工/AI 开发边界划分
• 问题 5：产品手册与用户培训
• 问题 6：打卡身份校验与代操作拦截
• 问题 7：开放问题与逻辑安全
• 问题 8：手机端数据展示方案
• 问题 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 注释模板：

/**
 * [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 出勤统计以自然月为周期，跨月打卡归属到打卡开始时间所在月
 */

/**
 * [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 代码追溯的命令：

# 查看所有 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/ 或飞书文档中：

# 开发日志：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 —— 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 —— 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 生成代码时框架约定自然引导分层：

@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：悄悄改变比较运算符

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

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

场景 2：简化权限校验

// 原始代码：完整的权限校验
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：改变数据精度

// 原始代码
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/**（文档）

防线二：业务规则断言

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

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;
        // ... 其他校验
    }
}

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

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

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

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

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

防线四：Git Hook 自动检查

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

#!/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	多人操作	"我和李四一起打卡"	拦截，只为当前用户打卡
查询例外	他人名字 + 疑问	"李四打卡了吗？"	允许（需权限），当做查询

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

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 审计日志设计

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

{
    "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"
}

代操作拦截记录：

{
    "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

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