# 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 提交不触发部署。