AI Coding 在后端开发中的上下文管理与质量把关实践

AI Coding = 编程能力强的执行者 + 通用方案生成器 + 文档整理助手
开发者 = 需求解释者 + 上下文组织者 + 架构决策者 + 质量把关人

# 搜索业务关键词
rg "OrderExport|订单导出|exportOrder" src/

# 搜索接口路径
rg "/api/orders|/orders/export" src/

# 搜索数据库表或字段
rg "order_status|payment_status|order_export" src/

# 查看模块结构
tree -L 3 src/main/java

docs/ai/
  ├── requirement-context.md     # 需求上下文
  ├── repo-map.md                # 代码仓库相关结构
  └── implementation-plan.md     # 实现方案与迭代记录

# 需求上下文：订单导出功能

## 业务目标
为运营人员提供订单导出能力，支持按时间范围、订单状态、支付状态筛选订单，并导出为 CSV 文件。

## 使用角色
- 运营管理员：可以导出全部订单
- 商家管理员：只能导出自己店铺的订单

## 输入条件
- startTime：必填，导出开始时间
- endTime：必填，导出结束时间
- orderStatus：可选
- paymentStatus：可选
- shopId：商家管理员场景由登录上下文决定，不允许前端任意传入

## 输出结果
- CSV 文件
- 字段包括：订单号、店铺名称、支付金额、订单状态、支付状态、创建时间

## 关键约束
- 最大导出时间范围：31 天
- 单次最多导出 100000 条
- 必须做权限校验
- 导出任务异步执行
- 需要记录操作审计日志

## 不做什么
- 不支持跨租户导出
- 不支持自定义导出字段
- 不做实时大文件同步返回

# 代码仓库上下文：订单模块

## 入口层
- OrderController：订单查询相关接口
- ExportTaskController：导出任务创建与查询接口

## 业务层
- OrderQueryService：订单查询逻辑
- ExportTaskService：导出任务创建、状态流转
- PermissionService：权限判断

## 数据层
- OrderRepository：订单数据读取
- ExportTaskRepository：导出任务持久化

## 公共约定
- ApiResponse<T>：统一响应结构
- BizException：业务异常
- ErrorCode：错误码枚举
- PageRequest：分页请求结构

## 可参考实现
- UserExportService：用户导出的异步任务实现
- ProductExportService：商品导出的 CSV 写入逻辑

# 实现方案：订单导出

## 当前方案
1. 新增创建导出任务接口
2. 校验权限与查询条件
3. 写入 export_task 表，状态为 PENDING
4. 后台任务消费导出请求
5. 分页查询订单数据并写入 CSV
6. 上传文件到对象存储
7. 更新任务状态为 SUCCESS 或 FAILED

## 待确认问题
- CSV 文件保存时长是多少？
- 是否需要导出收货人手机号？
- 失败任务是否允许重试？

## 变更记录
- 2026-06-07：确定采用异步任务，避免大文件同步返回

请先阅读以下三个文件，恢复当前任务上下文：

1. docs/ai/requirement-context.md
2. docs/ai/repo-map.md
3. docs/ai/implementation-plan.md

阅读后请只输出：
- 你理解的业务目标
- 涉及的核心模块
- 当前实现计划
- 仍需确认的问题

暂时不要修改代码。

问题：
当前实现直接使用请求参数中的 shopId 查询订单。

为什么不对：
商家管理员只能导出自己店铺的订单，shopId 必须从登录上下文获取，不能由前端传入，否则存在越权风险。

请修改：
1. 从 LoginUserContext 中获取当前用户身份；
2. 如果是商家管理员，使用上下文中的 shopId；
3. 如果是运营管理员，允许按请求参数筛选 shopId；
4. 补充越权访问的单元测试。

你是后端研发助手。请基于 PRD 和代码仓库上下文，生成系统分析文档。

输入材料：
1. PRD 内容：见 docs/prd/order-export.md
2. 代码结构说明：见 docs/ai/repo-map.md
3. 参考实现：UserExportService、ProductExportService

输出要求：
1. 业务目标
2. 涉及模块
3. 可复用代码
4. 需要新增的类和接口
5. 数据库变更
6. 权限与安全要求
7. 异常与错误码设计
8. 测试计划
9. 待确认问题

限制：
- 不要直接修改代码
- 不要编造不存在的类
- 对不确定的点标记为“待确认”

# 查看 AI 修改了哪些文件
git status

# 查看具体差异
git diff

# 运行测试
mvn test

# 提交一个可回退的小版本
git add src/main/java docs/ai
git commit -m "feat: add order export task creation flow"

请基于 docs/ai/implementation-plan.md 实现订单导出任务创建接口。

开发范围：
- 只修改订单导出相关文件
- 本轮只实现 Controller、Request、Response、Service 主流程
- 暂时不要实现后台任务消费逻辑

参考代码：
- UserExportController
- UserExportService
- ApiResponse
- BizException
- PermissionService

实现要求：
1. 校验 startTime、endTime，最大范围 31 天；
2. 根据登录用户判断权限；
3. 创建导出任务，初始状态为 PENDING；
4. 返回 taskId；
5. 使用项目已有错误码风格；
6. 补充必要的单元测试。

输出前请说明：
- 新增或修改了哪些文件；
- 每个文件的职责；
- 仍未实现的内容。

请生成一个 Python 脚本，把 i18n.csv 转成 messages.json。

输入 CSV 字段：
- module：模块名，必填
- key：文案 key，必填
- zh_CN：中文文案，可为空
- en_US：英文文案，必填

输出 JSON 格式：
{
  "moduleName": {
    "key": {
      "zh_CN": "...",
      "en_US": "..."
    }
  }
}

规则：
1. module、key、en_US 为空时报错；
2. 同一个 module 下 key 重复时报错；
3. 输出文件使用 UTF-8；
4. 命令行参数支持 --input 和 --output；
5. 控制台打印处理成功数量和错误行号。

import argparse
import csv
import json
from pathlib import Path


REQUIRED_FIELDS = ["module", "key", "en_US"]


def validate_row(row: dict, line_no: int) -> list[str]:
    errors = []
    for field in REQUIRED_FIELDS:
        if not row.get(field, "").strip():
            errors.append(f"line {line_no}: field '{field}' is required")
    return errors


def convert(input_path: Path) -> dict:
    result: dict[str, dict[str, dict[str, str]]] = {}
    errors: list[str] = []

    with input_path.open("r", encoding="utf-8-sig", newline="") as file:
        reader = csv.DictReader(file)

        for line_no, row in enumerate(reader, start=2):
            row_errors = validate_row(row, line_no)
            if row_errors:
                errors.extend(row_errors)
                continue

            module = row["module"].strip()
            key = row["key"].strip()

            result.setdefault(module, {})

            if key in result[module]:
                errors.append(f"line {line_no}: duplicated key '{key}' in module '{module}'")
                continue

            result[module][key] = {
                "zh_CN": row.get("zh_CN", "").strip(),
                "en_US": row["en_US"].strip(),
            }

    if errors:
        raise ValueError("\n".join(errors))

    return result


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("--input", required=True, help="input csv file path")
    parser.add_argument("--output", required=True, help="output json file path")
    args = parser.parse_args()

    data = convert(Path(args.input))

    output_path = Path(args.output)
    output_path.write_text(
        json.dumps(data, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )

    total = sum(len(items) for items in data.values())
    print(f"converted {total} records into {output_path}")


if __name__ == "__main__":
    main()

python convert_i18n.py --input i18n.csv --output messages.json

角色：
你是一个代码审查助手，负责检查后端代码中的风险。

任务：
根据输入的 Git diff，识别功能正确性、性能、安全、可维护性问题。

输入：
- Git diff
- 相关需求说明
- 项目编码规范

检查范围：
1. 是否符合需求；
2. 是否存在空指针、越权、事务错误；
3. 是否存在 N+1 查询；
4. 是否缺少必要测试；
5. 是否破坏已有接口兼容性。

输出格式：
请以 JSON 输出：
{
  "riskLevel": "LOW | MEDIUM | HIGH",
  "issues": [
    {
      "type": "SECURITY | PERFORMANCE | BUG | STYLE",
      "file": "文件路径",
      "line": "行号或代码片段",
      "description": "问题说明",
      "suggestion": "修改建议"
    }
  ]
}

限制：
- 不要输出无依据的问题；
- 不要编造不存在的代码；
- 如果信息不足，请在 issues 中说明需要补充的上下文。

请根据以下要求生成系统设计文档，输出 Markdown。

文档目标：
说明订单导出功能的后端设计，供研发评审使用。

章节结构：
1. 背景与目标
2. 需求范围
3. 总体架构
4. 核心流程
5. 接口设计
6. 数据库设计
7. 异常处理
8. 权限与安全
9. 测试计划
10. 风险与待确认问题

重点要求：
- 权限与安全部分必须详细写；
- 核心流程使用 Mermaid flowchart；
- 接口设计使用表格；
- 不确定的点不要编造，统一放到“待确认问题”。