# AI开发规范

## 核心原则
1. 优先最小改动
2. 优先兼容现有架构
3. 优先复用已有能力
4. 禁止主动重构
5. 禁止引入新基础设施
6. 所有改动必须支持回滚
7. 所有接口必须向后兼容
8. 所有设计必须可灰度发布
9. 所有方案必须考虑监控与告警
10. 输出必须包含风险分析

## 技术栈限制

- 不允许新增核心框架
- 不允许替换现有 ORM
- 不允许修改微服务通信协议
- 不允许引入实验性技术
- 优先复用现有组件和基础设施
- 新增依赖必须说明必要性
- 能使用现有 SDK 时禁止重新封装

## 架构约束

- 本次需求默认属于增量迭代
- 禁止进行系统级重构
- 禁止拆分新微服务
- 禁止引入事件驱动重构
- 禁止新增中间件
- 优先兼容现有DDD边界
- 优先遵循现有模块分层
- 除非需求明确要求，否则不允许进行架构升级

## 数据库限制

- 禁止删除字段
- 禁止修改历史字段语义
- 禁止破坏向后兼容
- 数据迁移必须可回滚
- 大表禁止全表扫描方案
- 新增索引必须说明影响
- 默认兼容灰度发布
- 不允许跨库事务设计

## API设计规范

- API优先向后兼容
- 不允许删除已有字段
- 新增字段必须可选
- 错误码遵循统一规范
- 分页参数统一
- 时间统一使用UTC
- ID统一使用string
- 禁止返回数据库内部字段。

## 前端约束

- 优先复用现有组件
- 不允许替换UI框架
- 不允许新增全局状态管理
- 禁止重构路由体系
- 样式遵循现有Design System
- 默认兼容移动端
- 不允许引入大型图表库

## 安全要求

- 所有接口必须鉴权
- 禁止绕过RBAC
- 禁止明文存储敏感信息
- 禁止日志打印token
- 禁止拼接SQL
- 输入必须校验
- 输出必须脱敏
- 新增外部依赖必须经过安全评审

## 性能要求

- 禁止N+1查询
- 默认分页查询
- 默认异步处理耗时任务
- 禁止循环调用远程接口
- 缓存优先复用现有方案
- 大批量任务必须支持限流
- 接口P99响应时间目标 < 500ms

## 禁止事项

禁止：
- 大规模重构
- 修改基础框架
- 修改CI/CD
- 修改认证体系
- 修改网关
- 修改数据库主键策略
- 引入新消息队列
- 引入新缓存系统
- 修改公共协议

## AI行为约束

- 不要主动重构
- 不要主动升级依赖
- 不要主动优化无关代码
- 不要修改未涉及模块
- 不要假设不存在的问题
- 不要引入未来需求设计

## 设计方案输出要求

方案必须包含：

1. 需求理解
2. 影响范围
3. 模块改动点
4. 数据结构变更
5. API变更
6. 风险分析
7. 回滚方案
8. 测试方案
9. 灰度方案
10. 工时评估

禁止输出纯理论架构设计。

## 代码生成规则

- 优先修改已有代码
- 禁止重复造轮子
- 优先复用现有service
- 单函数不超过100行
- 禁止过度抽象
- 禁止生成未使用代码
- 必须补充单元测试

## 设计优先级

优先级从高到低：

1. 不破坏线上稳定性
2. 向后兼容
3. 最小改动
4. 复用现有能力
5. 快速上线
6. 易于回滚
7. 可维护性
8. 理论最佳实践

# Git 提交管理规范

## 核心原则

AI Agent 可以协助管理 Git 提交，但必须遵守以下原则：

1. 不允许自动提交未确认的改动
2. 不允许自动 push
3. 不允许修改远程分支
4. 不允许执行 force push
5. 每次提交必须是最小语义单元
6. 提交前必须展示 diff 摘要
7. 提交信息必须清晰、可追踪
8. 禁止把无关改动混入同一次提交

## 提交流程

1. 执行 `git status --short`，说明改动范围。
2. 只处理本次相关 tracked diff，不提交 logs、截图、bundle、临时文件或无关改动。
3. 执行本次改动相关的最小必要测试。
4. 建议提交拆分方案
5. 创建干净 commit进行提交，要求commit message必须清晰、可追踪

但执行 `git commit` 前，必须确认：

- 改动范围正确
- 没有敏感信息
- 没有调试代码
- 测试已通过或已说明未执行原因


# 测试服发布规则

测试服发布必须严格遵循：少假设、小发布、强验证、可回滚。
## 测试服SSH
ssh root@101.42.99.35

## 部署架构
/opt/popiart-canvas
├── current -> 当前线上版本
├── releases/
│   ├── 20260521104810-6b5c645/
│   ├── 20260520102122-1f2e3d4/
├── shared/
│   ├── .env
│   ├── uploads/
│   ├── logs/

设计原则：

current 永远是软链接
release 永远不可修改
部署必须原子切换
环境变量必须外置
build 必须隔离执行

## 部署流程
Codex 执行发布时主要流程如下，通过脚本执行：

#### 第一阶段：Build Release
1. 测试服只部署指定 commit SHA。
2. 部署前记录测试服旧 SHA: "$OLD"。
3. 本地针对指定部署 commit SHA代码进行打包，并上传测试服务器
4. 测试服创建release：格式为YYYYMMDDHHMMSS-<short_commit>
5. 解压源码包到新SHA的release目录
6. 复用node_modules，从旧 SHA复制依赖
7. 注入环境变量
8. 写入版本信息
9. Docker隔离build
10. Build 成功标记

#### 第二阶段：Smoke Test
1. 创建Smoke容器
2. 注册Cleanup
3. 启动 Smoke 容器
4. Smoke Health Check
5. 检查日志
6. Smoke 成功标记

#### 第三阶段：正式发布
1. 从current获取当前版本
2. 原子软链接切换
3. 重启正式容器
4. 正式健康检查

#### 发布后验证
- 当前版本
- 容器版本

#### 特别注意
失败立即回滚旧 SHA。

#### 输出测试服发布报告：

- 发布 SHA：
- 旧 SHA / 回滚点：
- 变更范围：
- 本地测试结果：
- 构建结果：
- 测试服部署结果：
- Smoke test 结果：
- 日志检查结果：
- 未验证项：
- 剩余风险：
- 回滚方式：

#### 部署脚本
完整部署流程通过脚本执行，可根据具体情况调整：
```
#!/usr/bin/env bash
set -euo pipefail

APP="/opt/popiart-canvas"
IMAGE="docker.m.daocloud.io/library/node:23-alpine"
REV="${1:?Usage: ./deploy-popiart-canvas.sh <git-revision>}"

SHORT="${REV:0:7}"
SRC="/tmp/popiart-canvas-${SHORT}-src.tgz"
OLD="$(readlink -f "$APP/current")"
RELEASE="$APP/releases/$(date +%Y%m%d%H%M%S)-$SHORT"
RELEASE_FILE="/tmp/popiart-canvas-new-release.txt"
SMOKE="popiart-canvas-smoke-$(date +%H%M%S)"

cleanup() {
  docker stop "$SMOKE" >/dev/null 2>&1 || true
}
trap cleanup EXIT

echo "Deploy Info:"
echo "- Revision: $REV"
echo "- Old Release: $OLD"
echo "- New Release: $RELEASE"
echo "- Docker Image: $IMAGE"

echo "==> Build release"

test -s "$SRC"
mkdir -p "$RELEASE"

tar -xzf "$SRC" -C "$RELEASE"
cp -al "$OLD/node_modules" "$RELEASE/node_modules"
cp "$APP/shared/.env" "$RELEASE/.env.local"
printf '%s\n' "$REV" > "$RELEASE/REVISION"

docker run --rm \
  -v "$RELEASE:/app" \
  -w /app \
  --env-file "$APP/shared/.env" \
  "$IMAGE" \
  sh -lc 'npm run build'

echo "$RELEASE" > "$RELEASE_FILE"
echo "BUILD_OK"

echo "==> Smoke test"

docker rm -f "$SMOKE" >/dev/null 2>&1 || true

docker run -d --rm \
  --name "$SMOKE" \
  -p 127.0.0.1:3101:3000 \
  -v "$RELEASE:/app:ro" \
  -w /app \
  --env-file "$APP/shared/.env" \
  "$IMAGE" \
  node server.js

sleep 8

curl -fsSI --max-time 10 http://127.0.0.1:3101/ | sed -n '1,8p'
docker logs --tail 20 "$SMOKE"

echo "SMOKE_OK"

echo "==> Switch release"

ln -s "$RELEASE" "$APP/current.new"
mv -Tf "$APP/current.new" "$APP/current"

docker restart popiart-canvas

sleep 8

if curl -fsS --max-time 10 http://127.0.0.1:3100/ > /tmp/popiart-canvas-health.html; then
  echo "DEPLOY_HEALTH_OK"
else
  echo "DEPLOY_HEALTH_FAILED_ROLLING_BACK"

  ln -s "$OLD" "$APP/current.rollback"
  mv -Tf "$APP/current.rollback" "$APP/current"

  docker restart popiart-canvas
  exit 1
fi

echo "==> Verify"

readlink -f "$APP/current"

docker exec popiart-canvas sh -lc '
  cat /app/REVISION
  test ! -f /app/.env.local && echo NO_ENV_LOCAL_IN_RELEASE || true
'

docker ps \
  --filter name=popiart-canvas \
  --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

curl -fsSI --max-time 15 https://wwwtestcanvas.popi.art/ | sed -n '1,8p'

echo "DEPLOY_DONE"
```

使用方式：

```
chmod +x deploy-popiart-canvas.sh

./deploy-popiart-canvas.sh "指定发布的 commit SHA"
```