Veyra/AGENTS.md

Veyra 工程约定

项目背景、已完成功能和验证状态见 docs/development-state.md。继续开发前阅读该文件，完成工作后更新事实与待办，不记录密码。

• 后端使用 Go，遵循 gofmt、go vet、惯用错误处理、context 传递、明确依赖注入及入口/internal 分层。

• 后端采用仓库根目录的单 Go module：仅保留根目录 main.go 一个入口和一个 main 函数，internal 按 model、service、repository、handler、config、database 等职责组织；管理端位于 web/admin。避免为单体项目重复嵌套 services/api、业务域目录和 platform 层，不引入单模块 go.work。

• 不使用 Makefile；后端直接 go run / go build，前端直接使用 npm scripts。数据库和开发身份维护通过同一个可执行文件的 -command 参数切换。

• HTTP handler 只做协议适配，业务规则归 service/domain，SQL 归 repository。不得将 Gin Context 传入业务层。

• PostgreSQL 所有表（包括迁移、任务和关联表）必须以 veyra_ 开头，表与字段使用 snake_case。

• 主键 id 使用字符串 UUID：Go 类型 string，数据库 varchar(36) 并校验 UUID 格式。外键保持相同类型。

• 映射去掉表名前缀并转 PascalCase：veyra_user → User，veyra_trade_plan → TradePlan。使用显式 SQL 与 db tag，不依赖 ORM 隐式命名。

• 金额、价格、数量规则不得使用 float64；采用明确精度的整数或 Decimal。

• 已入账成交不可覆盖，采用冲正；触发提醒不可产生持仓或扣款。

• 管理端必须采用 Vite + React + TypeScript + Tailwind CSS + shadcn/ui，保留暖白、炭黑、焦糖橙视觉。

• 管理端生产构建必须通过 Go embed 嵌入后端，页面和 API 同源服务，Vite 仅用于本地开发。

• App 采用 React Native + Expo，白底、石墨黑与柔紫。

• 凭据通过环境配置，禁止提交 .env、打印连接串或口令。所有数据库变更使用版本化迁移。

• 功能与真实数据能力必须如实呈现；不得用演示结果冒充在线统计。

• 更改后完成对应测试、go vet、类型检查与构建。原始两个设计文件保留。

• PostgreSQL 开发地址为 192.168.100.127:5432，数据库名 veyra；Redis 为 192.168.100.127:6379，无用户名、有密码。实际凭据只从本地 configs/.env 读取。

• 本机与数据库处于同一内网。若工具返回 Operation not permitted，应区分执行沙箱权限限制与主机网络故障，不因此修改服务地址。

• 后端环境文件与模板位于 configs/；管理端和 App 分别维护自己的 npm 配置、锁文件与依赖，不在根目录建立 npm workspace。

• 后端日志使用 zap：控制台易读，当前运行目录 logs/ 下自动写文件与轮转；日志不提交，不记录密钥、口令、Cookie 或请求正文。

• 开发在 dev 分支进行，禁止直接提交或推送 master（管理员也须遵守）；通过合并请求进入 master。CI/CD 仅监听 master 的 push，包含合并提交；dev 提交不触发部署。